GetBlue: User Manual

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.

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.

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.

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/IP
  Any device providing a raw TCP/IP socket. TCP/IP connections in client and in server mode are supported.
• 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.

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

• Display
  Switch between HEX or ASCII display.
• File
  Any file on the SD card.
• Google Docs Spreadsheet
  Captured data is immediately uploaded to an online Google Docs spreadsheet.
• HTTP
  GET and POST methods with adjustable parameters.
• TCP/IP
  TCP clients as well as TCP servers are possible.
• Another Bluetooth SPP device
  Bluetooth clients as well as Bluetooth servers are possible.
• 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).

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.

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.

• TCP/IP
  

  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.

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.

• 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 timestamps are added if checked.

• 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/IP
  

  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 timestamp belonging to the received data is forwarded to the data-sink using this freely adjustable parameter name. The default is Timestamp. The timestamp contains the system time in milliseconds since January 1, 1970 00:00:00 UTC.).

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

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.

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.

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.

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.

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.

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.

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.

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 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 Android Market or for bulk-licensing.

About

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

GetBlue can be licensed via the Android Market (pay as you go) or by applying a license certificate manually. A manual license certificate is ideal for users without access to the Android Market or for bulk licensing requirements. In order to be able to license GetBlue without Android Market you need to download the GetBlue APK from http://www.tec-it.com (the version available in Android Market 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.