GetBlue: User Manual

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.

Introduction

GetBlue 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.

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:

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).

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.

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

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.

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.

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:

first enable the GetBlue Keyboard in Android Settings (confirm the security warning),

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.

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.

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

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 frontend + data acquisition system service) or for the GetBlue SDK (no GUI frontend, just the service). Please contact us for bulk pricing, general license requests or for purchasing one or more license certificates.