Introduction

GetBlue automates data acquisition tasks and provides manual device communication features for Android®-devices. GetBlue captures device data and displays or processes it. Two high-lights of GetBlue are the possibility to populate device data directly into an online Google spreadsheet and the capability to simulate user input based on device data (e.g. scanning a barcode with a Bluetooth scanner directly into some app). GetBlue can also be used as generic "proxy" between devices and protocols.

The app provides versatile data acquisition features for devices running Android version 1.6 or higher. GetBlue automatically captures data from adjustable datasources like Bluetooth SPP devices (Bluetooth clients and Bluetooth servers are supported), HTTP or TCP/IP endpoints and from camera scanner apps. The collected data is displayed, logged, stored, forwarded, or injected as virtual user input into other apps. The destination of the collected data is called datasink in this context.

Bi-directional device communication is supported. If configured, responses of the datasink (like HTTP status codes) are sent back to the datasource.

In general GetBlue works as cross-switch or proxy. It transfers data between the different endpoints regardless of the devices or protocols in use (e.g. receiving data from a Bluetooth SPP barcode scanner and forwarding this data via TCP/IP sockets to a server application). If required GetBlue can be operated as so-called keyboard wedge: in this case GetBlue is used to simulate user input based on captured device data. The received data is injected via simulated keystrokes into 3rd party apps.

GetBlue is available as a single APK file. This APK file contains a system service which is responsible for device communication in the background and a front-end for configuration and manual data acquisition tasks. The system service is available as SDK for 3rd parties. Check out the section licensing for details.

Basics

In order to use GetBlue for automated data collection you need to configure some basic options. The most important settings are the datasource (e.g. a Bluetooth barcode scanner) and the datasink (e.g. a Google Docs spreadsheet).

Once the data acquisition was started, device data is collected by the GetBlue background service. This system service is invisible to the user and ensures uninterrupted device connectivity, the service automatically tries to reconnect in case of lost connectivity. The service is also responsible to forward data received from the datasource to the configured datasink in a reliable way.

Opening a connection to a datasource or a datasink is done according to the open policies. The number of retries as well is the delay between retries is adjustable. After the connection was opened successfully, GetBlue divides incoming data from a datasource into packets (see read policies).

A data packet is defined by

  • the maximal number of bytes (packet size),
  • the time required for receiving it (measured from the first byte of the packet)
  • or by a delimiter character sequence (which is a regular expression).

If at least one of the three parameters is fulfilled GetBlue assumes the packet as complete and forwards it to the datasink. GetBlue is ready to receive the next data packet.

Supported Datasources

GetBlue is able to capture data from the following devices or endpoints:

  • Bluetooth SPP and Bluetooth RFCOMM
    All serial Bluetooth devices supporting the Serial Port Profile (like SPP or RFCOMM barcode scanners) can be used. GetBlue supports Bluetooth client and Bluetooth server mode, thus device as well as PC connections are possible.
  • TCP (plain data)
    Any device providing a raw TCP/IP socket. TCP/IP connections in client and in server mode are supported.
  • USB serial
  • HTTP
    Any HTTP-based application supporting HTTP GET or HTTP POST requests. The request parameters are adjustable.
  • Camera scanners
    GetBlue offers you the possibility to use 3rd party barcode scanner apps.
  • Manual data input
    Device commands can be entered manually.

Supported Datasinks

The captured data can be transferred or forwarded to the following datasinks:

  • Display
    Switch between HEX or ASCII display.
  • Bluetooth SPP device
    Bluetooth clients as well as Bluetooth servers are possible.
  • TCP (plain data)
    TCP clients as well as TCP servers are possible.
  • HTTP
    GET and POST methods with adjustable parameters.
  • Keyboard
  • File
    Any file on the SD card.
  • Google Spreadsheet
    Captured data is immediately uploaded to an online Google Docs spreadsheet.
  • Arbitrary 3rd party apps
    Use the GetBlue keyboard to inject the captured data as virtual keystrokes into any apps accepting user input (keyboard wedge mode).
GetBlue Main Screen

Main Screen

In the upper part of the main screen (data view), GetBlue displays received device data as ASCII characters or in hexadecimal form (see main screen options). In the lower part of the screen (log view), GetBlue shows a log with informational, warning and error messages.

  • Available options for the data view

    Tapping onto the data view opens a menu which offers you context sensitive commands:

    Copy line

    Copies the selected line into the clipboard.

    Copy all

    Copies all data lines into the clipboard.

    Save to file

    Save the received data into a file.

    Send to

    Send the selected line to another application (e.g. Gmail, Google Buzz, a NFC tag, etc.).

    Clear

    Clear the view.

  • Available options for the log view

    Tapping onto the log view opens a menu which offers you context sensitive commands:

    Clear

    Clear the log.

  • Available buttons
    Start/Stop

    Starts or stops data acquisition. If started, GetBlue receives data from a datasource and forwards it to a datasink. Captured data is always displayed in the data view of the main screen.

    Send Data

    Send manually entered data to a connected device.

  • Available menu commands
    Settings

    Adjust datasource, datasink, open policy, read policy, main screen settings and bi-directional communication options. In the about section you have access to this user manual and to copyright as well as version information.

    Toggle Log

    This command allows you to hide or display the log view.

    Exit

    This command quits GetBlue and removes the background service which is part of GetBlue from memory.

Datasources

Input Device (Datasource)

After data acquisition was started with the Start button on the main screen, GetBlue opens the connections according to the open policy, monitors the datasource for incoming data, reads it, processes the received data according to the specified read policy and forwards it to the adjusted datasink.

The following datasources are supported:

  • None

    Select None if you need to test connectivity with a datasink.

  • Bluetooth

    GetBlue supports Bluetooth client as well as Bluetooth server mode.

    Bluetooth Client

    Use the client mode if you need to connect to a device which is sending data on its own (like a Bluetooth barcode scanner).

    If Bluetooth client mode is selected enumerate the Bluetooth devices in range (as an alternative you can enter the Bluetooth address of the client directly). Please note: You need to pair the Bluetooth device with your smart-phone! It is recommend to pair the device before starting GetBlue.

    Bluetooth Server

    Use the server mode if another Bluetooth client device is connecting to your handset (e.g. if you want to connect from a PC with Microsoft Windows to your handset, the PC is usually acting as a client). In server mode no specific device can be selected. Please note: It is recommended to pair your Bluetooth devices after the Bluetooth server mode was activated.

  • USB serial

  • TCP (plain data)

    GetBlue supports TCP/IP client as well as TCP/IP server mode.

    TCP/IP Client

    Use the client mode if you need to connect to an existing TCP server. Specify the host-name or IP address of the TCP/IP device and adjust the port number to which GetBlue should connect to.

    TCP/IP Server

    Use the server mode if another TCP/IP client (e.g. a telnet client) is connecting to your handset. In TCP/IP server mode the current IP address of your handset is displayed read-only. You just need to provide a suitable port number to which your client should connect to.

  • HTTP

    Specify the host-name (or IP address) / port combination of the HTTP server to which GetBlue should connect to. In addition choose whether the HTTP GET (the default) or HTTP POST method should be used for requests.

  • Camera Scanner

    When selecting this entry, GetBlue shows a dialog with the installed 3rd party barcode scanners apps. You may select a specific scanner application or choose Always ask. In the latter case GetBlue asks you for the camera scanner to be used.

Datasink

Output Device (Datasink)

The term datasink refers to an endpoint to which the data captured from a datasource is sent or forwarded to. The following datasinks are available:

  • None

    Select this option if you need to test connectivity with a datasource. Captured data is just displayed in the data section of the main screen. No further processing is done.

  • Bluetooth

    Select Bluetooth if you need to forward the data received from the datasource to another Bluetooth device. Bluetooth client as well as Bluetooth server mode is supported. For more information see Bluetooth datasources.

  • TCP (plain data)

    Select TCP if you need to forward the data received from the datasource via a TCP/IP socket. The data packets are unmodified, as received by the datasource. TCP client and TCP server mode are available. For more information see TCP/IP datasources.

  • HTTP

    Specify the URI (host-name or IP address, optional port number) of the HTTP server to which GetBlue should send the captured data. Provide any static parameters (like the user-ID) in this URI. Separate an optional port number with a colon (e.g. http://172.16.100.1:8080?myparam=something).

    Use POST method

    Choose whether the HTTP GET (the default) or the HTTP POST method should be used for forwarding data.

    Parameter Data

    The data is forwarded using this freely adjustable parameter name. The default is Data.

    Parameter Timestamp

    The time-stamp belonging to the received data is forwarded to the data-sink using this freely adjustable parameter name. The default is Timestamp. The time-stamp contains the system time in milliseconds since January 1, 1970 00:00:00 UTC.).

  • Keyboard

    Chose keyboard if you want to GetBlue to operate as software wedge. In this operation mode GetBlue injects received data into arbitrary 3rd party apps. This is done by simulating keystrokes via the GetBlue keyboard.

    Please note: You also need to activate the GetBlue keyboard and the GetBlue input method for this purpose:

    1. first enable the GetBlue Keyboard in Android Settings (confirm the security warning),
    2. then activate the input method GetBlue Keyboard. Do this by long tapping on any edit field and select the input method GetBlue Keyboard.
    Sound on Keypress

    Adjust whether a keypress should produce a sound for better feedback.

    Vibrate on Keypress

    Adjust whether a keypress should trigger a short vibration for better feedback.

    Default Data Prefix

    If required, the data packet received from the datasource is prefixed with the adjusted character sequence. Use the following placeholders to control the cursor or input focus before the received data is injected: ${ENTER} or ${E}, ${TAB}/${T}, ${DOWN}/${D}, ${UP}/${U}, ${LEFT}/${L} , ${RIGHT}/${R}. The default data prefix is only applied if no application specific prefix is defined (see below).

    Default Data Suffix

    If required, the data packet received from the datasource is suffixed with the adjusted character sequence. Use the following placeholders to control the cursor or input focus after the received data was injected: ${ENTER} or ${E}, ${TAB}/${T}, ${DOWN}/${D}, ${UP}/${U}, ${LEFT}/${L} , ${RIGHT}/${R}. The default data prefix is only applied if no application specific suffix is defined (see below).

    Application Prefix/Suffix

    Application specific pre- and suffixes control the behavior of the GetBlue keyboard based on the currently active target application. This option is useful if you use the GetBlue keyboard with different target applications which require different adjustments for cursor movements or focus selection.

    To create a new application specific policy press the button Add Application Policy. Then select the target application of interest and enter the application specific pre- and suffix. In addition you can select if the data should be forwarded as a single data string or simulated with single keystrokes. Single keystroke simulation is recommended for browsers or RDP target applications.

    To modify or delete an existing policy (e.g. the pre-defined policy for the Android browser) just long-tap on the entry.

    Enable Keyboard

    This is a shortcut for opening Android Settings -> Language & keyboard.

  • File

    Choose the option file if you want to save captured device data to a file on your SD card.

    Save plain data

    The data received from the datasource is written to the file “as is”; no time-stamps are added if checked.

  • Google Spreadsheet

    If you want to save device data directly into a Google Spreadsheet select this entry. Specify your Google Docs user account including password, the name of the spreadsheet and an optional worksheet name. Data received from the datasource is forwarded instantly to this spreadsheet (Internet connectivity is required).

    Google Account

    The email address used for accessing your Google Docs account. The email address is exclusively used for accessing the spreadsheet specified below. It is not used for any other purpose and it is not sent to TEC-IT!

    Password

    The password for your Google Docs account. The password is exclusively used for accessing the spreadsheet specified below. It is not used for any other purpose, it is not sent to TEC-IT!

    Name of Document / Spreadsheet

    The name of an existing spreadsheet in Google Docs.
    GetBlue is not able to create spreadsheets; you need to create an empty spreadsheet manually. To do so, log in to Google Docs, click Create New and select Spreadsheet. Then save the empty spreadsheet by selecting File and Save from the menu. The name used for saving the spreadsheet must be entered in GetBlue. If these names do not match you will receive an error when starting data acquisition.

    Name of Worksheet in Spreadsheet

    The name of the worksheet the data should be saved to. If nothing is specified the worksheet is named GetBlue Demo.

Bi-Directional Communication

This option enables you to establish a bi-directional communication between datasource and datasink . Select it to instruct GetBlue to send responses of the datasink (if any) to the datasource.

Example: GetBlue captures device data (e.g. from a Bluetooth barcode scanner) and forwards this data to a TCP server acting as datasink. The TCP server acknowledges the data with a response which is then proxied back to the device acting as datasource.

Launch by Default

Using this option you have the possibility to start GetBlue automatically when booting your device. You have 3 options:

No

GetBlue must be started manually.

Background data acquisition

The GetBlue service is started with the last configuration, connects to the adjusted datasource and datasink and begins operation.

Service only

The GetBlue service is started without configuration. Users of the GetBlue SDK (details are available on request) are able to configure the communication parameters and to start or stop the data collection programmatically.

Settings: Open/Read Policies

Device Open Policy

Use these settings to adjust the behavior when opening a connection to a datasource or a datasink.

Retry Timeout

If an open connection fails, GetBlue waits the specified number of milliseconds before retrying.

Open Retries

The total number of retries when opening a connection. If no connection was established after the specified number of retries, an error is raised.

Data Read Policy

These parameters instruct GetBlue how to handle received device data.

GetBlue groups incoming device data automatically into so-called data packets. A data packet is defined by the time required for receiving it, by the total number of bytes or - finally - by a delimiter sequence specified with a regular expression. You can combine these settings as required.

Raw Mode

Option 1: Read data immediately (like TELNET).
Option 2: Read data packet by packet as defined below.

Timeout

The maximum time (in milliseconds) to receive the data packet. All bytes received within this time are delivered in a single data packet.

Size

The maximum number of bytes for a data packet.

Separator

A regular expression which matches the character sequence used for marking the end of a data packet.

Include Separator

If checked, the separator sequence is treated as part of the data packet. If unchecked, separator sequences are stripped from the acquired data.

Settings: Main Screen Options

Main Screen Options

These settings control the behavior of the main screen.

Hexadecimal / ASCII

Usually incoming device data is displayed as ASCII characters. To enable hexadecimal display activate this option.

Data Rows

Specifies the maximum number of data rows displayed in the data view. The value 0 means that there is no limitation.

Data Font Size

Specifies the font size for the data view. An empty values defaults to 14.

Log Font Size

Specifies the font size for the log view. An empty values defaults to 14.

Show Detailed Logs

Switch between basic and detailed log information in the log view.

Show Response

Use this option to select if the responses from the datasink (if configures) should be displayed in the data view. Responses are displayed in a different color.

Settings: About

About

This option provides commands for displaying the user manual, the software version and the copyright information. In addition you can display your license information or enter a manual license.

User Manual

This command shows this web-page in your browser. Please contact us in case of questions, suggestions or if you want to report a bug.

YouTube Videos

This command opens TEC-IT’s YouTube channels with relevant Android Data Acquisition videos.

License

This command opens a dialog which displays the current state of your license. In this dialog you have also the possibility to license GetBlue manually by entering a license certificate. This feature is helpful for licensing without access to Google Play or for bulk-licensing.

About

Displays the current software version, a copyright notice and 3rd party credits.

Send data manually

Send Data Manually

This function allows you to send manually entered data to the connected devices (a datasource or a datasink). This function is especially helpful for testing and sending control commands. The buttons Send to Datasource and Send to Datasink are only enabled if an appropriate endpoint was adjusted in Settings.

You can select between normal input (the default is ASCII) or HEX input. In the latter case GetBlue only accepts valid hex-characters as input (0..9, A-F).

The History button provides access to the last entered values.

Please note: when sending a HTTP GET command to a web-server you may receive a lot of data as reply.

Licensing

GetBlue can be licensed via Google Play (pay as you go) or by applying a license certificate manually. A manual license certificate is ideal for users without access to the Google Play or for bulk licensing requirements. In order to be able to license GetBlue without Google Play you need to download the GetBlue APK from http://www.tec-it.com (the version available on Google Play can't be licensed manually).

The GetBlue APK on tec-it.com requires additional permissions like IMEI access but offers the following licensing features:

  • IMEI bound license
  • Android Device ID bound license
  • License bound to other installed apps (package names)
    For bulk licensing when bundling GetBlue or GetBlue SDK with your app
  • A license may be valid perpetual or just for a limited time (expiry date)
A manual license certificate is installed by opening GetBlue Settings. Scroll down to the About section and tap on License. Use the Manual... button to paste the certificate into the edit box for the license key.

Licenses are available for GetBlue (GUI front-end + data acquisition system service) or for the GetBlue SDK (no GUI front-end, just the service). Please contact us for bulk pricing, general license requests or for purchasing one or more license certificates.