BluePiano: User Manual

Introduction

BluePiano is typically used for scanning barcodes with external Bluetooth barcode scanners or for RFID data collection. BluePiano installs as a soft-keyboard which injects captured device data into arbitrary target apps by simulating user-input. For the target app there is no difference between user input and device input.

If activated, BluePiano works as a keyboard wedge which replaces the standard Android keyboard. BluePiano offers English, German, French, Russian and Swedish keyboard layouts.

BluePiano is easy to use and provides you with connectivity feedback in the notification bar or via a special key on the soft-keyboard. For backup purposes BluePiano is also able to scan barcodes using the built-in camera scanners (you may also adjust an external camera scanner app).

BluePiano is able to connect to all Bluetooth SPP devices (Bluetooth client or Bluetooth server devices supporting the Serial Port Profile, RFCOMM). Special Android-enabled bar code scanners are NOT required. HID devices are not supported.

How does BluePiano Work?

Whenever the BluePiano keyboard is shown it establishes a device connection (via a system service running in the background) and waits for data. If there are any problems connecting to the device, BluePiano first tries to re-establish the connection automatically. If this is not possible, BluePiano suspends the device connection in order to preserve battery power. The user will be notified with an error sound, a vibration, a message in the notification bar or with a special symbol for the Bluetooth action key (see BluePiano keyboard). The parameters for (re-)establishing a Bluetooth connection as well as the preferred notification method can be adjusted in the BluePiano Settings.

BluePiano provides two methods for receiving data (refer to Bluetooth Device Manager):

In Raw Mode the data is forwarded as it is received from the device. Except for the carriage return (CR) and line feed (LF) separator characters which trigger an immediate forwarding no special grouping is performed. In this operation mode the user can't be sure that - for example - 8 bytes of an EAN barcode are transferred as a single unit to the target app.

In the Enhanced Mode BluePiano takes care to group incoming device data into packets. Each packet is forwarded as a single unit into an edit field. 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, BluePiano assumes the data packet as complete and injects it into the edit-field of the active application.

Initial Configuration

After you have downloaded and installed BluePiano a setup wizards simplifies the initial configuration. The wizard guides you through the minimal required configuration steps:

• Pairing with the Bluetooth device
  Pairing is done via Android Settings, Wireless & networks, Bluetooth settings. Before you pair your devices make sure Bluetooth is switched on and your device is discoverable. Refer to the user manual of the device for details regarding this topic.
• Configure BluePiano to capture data from this device
  After the device was paired successfully, configure BluePiano to use this device for data acquisition. Do this by opening the Bluetooth Device Manager.
• Enable the input method BluePiano
  In order to use the BluePiano keyboard you need to enable it. Do this by opening Android Settings, Language & keyboard and enable the BluePiano keyboard by checking the box. Confirm the security warning (see privacy).
• Activate the input method
  After the input method was enabled it must be activated. Long tap on any edit field and select the input method BluePiano Keyboard.

Your Android is now using the BluePiano keyboard as input method. Whenever the Bluetooth device sends data it is injected into the current edit-field of the target app.

The Keyboard

If the BluePiano keyboard is visible you can long-tap on the ?123 key. A menu with the following options appears:

• Scan with Camera
  Invokes the adjusted camera scanner (see BluePiano Settings).
• Simulation Rules
  Goes directly to the Keyboard Simulation Rules.
• Input Device
  Use this menu entry for adjusting the Bluetooth input device with the Bluetooth Device Manager.
• Settings
  Opens the BluePiano Settings screen.
• Input Methods
  Allows you to activate another soft-keyboard.

If enabled, the new action key may show the symbols below. To enter a comma, long-tap the action key.

This symbol is shown if no Bluetooth input device was configured. Tap this key to open the Bluetooth Device Manager.

This symbol is shown if BluePiano is currently connecting to the Bluetooth input device.

The connection to the Bluetooth input device was lost, BluePiano tries to re-establish the connection in the background. You may also tap the key to re-establish a connection immediately.

The Bluetooth input device was suspended, BluePiano will not try to re-establish the connection anymore. You have to tap this key to re-establish a connection.

If the Bluetooth connection is working fine, the action key may show the barcode scanner key (this can be configured in BluePiano Settings). Use the barcode scanner key to scan barcodes with the built-in camera scanner.

Tap this key to invoke the camera scanner (see BluePiano Settings).

BluePiano Settings

To modify the BluePiano options, go to Android Settings -> Language & keyboard -> BluePiano. The following options are available:

• Bluetooth
  

  This section is used to specify the Bluetooth input device, advanced device options and the behavior in case of Bluetooth errors.

  Bluetooth Input Device

  Use the Bluetooth Device Manager to select the Bluetooth input device and to adjust the advanced device settings. The Bluetooth Device manager can also be used for establishing or suspending a Bluetooth connection manually.

  Advanced Device Settings

  Use Advanced Device Settings to adjust the connection properties and to switch between raw and enhanced mode.

  Vibrate on Error

  If selected a lost Bluetooth connection is signaled by vibrating the handset.

  Notifications

  If selected the current Bluetooth connection state is displayed in the notification bar. Tapping on a notification opens the Bluetooth Device Manager.

  Show Action Key

  If checked BluePiano shows a special key to reconnect a Bluetooth connection.





• Camera Scanner Settings
  

  For backup purposes BluePiano offers support for camera barcode scanner apps. Use this section to configure the details of the scanner app.

  Camera Scanner

  Select the preferred camera scanner and choose between: Automatic Orientation, Landscape and Portrait.

  Advanced Camera Scanner Settings

  Enable Flashlight or/and set the Barcode Character Set.

  Batch Scanning

  If checked, batch scanning is enabled. Also you can set the pause in milliseconds between scans.

  Search Key Function

  Specify if the hardware search key (magnifier symbol) is used as hotkey for invoking the selected camera scanner app.

  Show Scan Key

  If selected, the comma key on the keyboard is replaced with a barcode scanning symbol. Pressing this key invokes the selected camera scanner app.





• Hardware Scanner Module
  Device Type

  Choose your device type.

  Scanner off

  Choose, if the scanner should be switched of after 5 seconds.

  Hardware Scan-Button

  Scan barcode each 2 seconds.





• Keyboard Options
  Input Language

  Change your system language.

  Sound on Keypress

  Adjust whether a keypress should produce a sound.

  Vibrate on Keypress

  Adjust whether a keypress should trigger a short vibration.

  Simulation Rules

  By the means of Keyboard Simulation Rules the user is able to configure keystroke simulation mode and cursor movements per target application. Also you can define if a prefix or/and suffix should be added.





• Preferences
  Import

  Import a configuration file.

  Export

  Export configuration to a file.

  Device ID

  Your device ID will be shown here.





• About
  

  This section 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. You may purchase a full license directly via the Android Market. For users without access to Android Market or in case of bulk-licensing BluePiano can be licensed by entering an activation key. Activation keys are available from TEC-IT upon purchase, licensing with activation keys requires one-time internet access.

  About

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

Keyboard Simulation Rules

By the means of keyboard simulation rules the user is able to configure keystroke simulation mode and cursor movements per target application. When simulating keystrokes BluePiano searches for a rule which matches the current target app. If no such rule is found, it applies the current default rule.

To maintain simulation rules, go to Android Settings -> Language & keyboard -> BluePiano -> Keyboard Simulation Rules. By tapping on a rule name you have the following options:

• Set as default
  This option promotes the current rule to the default rule.
• Edit
  Modify the rule settings (see below)
• Remove
  The initial default rule can't be deleted

A new rule can be added with the button Add Simulation Rule.

Two methods for simulating user input are available:

• All keys at once
  Received device data is injected as a single string.
• One key at a time
  Received device data is forwarded keystroke by keystroke. This method is recommended if the target app is a browser or a RDP (remote desktop) application.

If you have problems forwarding keystrokes to a specific target application you may add an application specific rule for exactly the app in question. Most likely browser or remote desktop (RDP) applications require One key at a time forwarding to handle simulated user input correctly.

Each simulation rule allows the user to add cursor control commands before and after the data received from the device. The following placeholders are supported:

• ${INPUT} or ${I}
  This is the placeholder for the received device data
• ${ENTER} or ${E}
  Placeholder for the enter key
• ${TAB} or ${T}
  Placeholder for the tab key
• ${DOWN} or ${D}
  Placeholder for the cursor down key
• ${UP} or ${U}
  Placeholder for the cursor up key
• ${LEFT} or ${L}
  Placeholder for the cursor left key
• ${RIGHT} or ${R}
  Placeholder for the cursor right key

A placeholder can also be used with a multiplier: ${R3} is equivalent to ${R}${R}${R}.

Example: To instruct BluePiano to inject the input data followed by the enter key use this rule: ${I}${E}.

Bluetooth Device Manager

You can reach these settings with the contextual menu () by tapping on Debug.

BluePiano can be used with each Bluetooth SPP (serial port profile, RFCOMM) device. Bluetooth clients and Bluetooth server connections are supported. Use this activity to select the input device and to adjust the advanced device settings for establishing a connection and for reading data. In addition, the Bluetooth Device manager can be used for establishing or suspending a device connection manually.

Select Device

Taping this button opens an activity in which you are able to choose the Bluetooth input device. BluePiano supports devices working in 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). Just select the device by tapping on it or enter the Bluetooth MAC address manually. Please note: It is required to pair your handset or tablet with the Bluetooth device before you perform this operation.
• Bluetooth Server
  Use the server mode if another Bluetooth client device is connecting to your handset (e.g. if a Microsoft Windows PC connects to your handset). In server mode no specific device can be selected. Please note: It is recommended to pair the PC with your handset after the Bluetooth server mode was activated.

Contextual Menu ( )

This button opens a menu in which you reach:

• Clear log
  

  Clears the connection and error log.

• Restart BT (Bluetooth)
  

  Restart the Bluetooth service. This operation may be helpful in case of Bluetooth firmware problems.

• Settings
  

  This button opens the screen for Advanced Device Settings.

Start/Stop

Starts the connection with the selected Bluetooth device. If the connection is already established, this button may be used to stop the connection.

Suspend

Suspends an existing Bluetooth connection. To continue, the connection must be started again.

Advanced Bluetooth Device Settings

Use these settings to adjust the advanced settings for opening a device connection and for reading data from the Bluetooth device.

• Connection Settings
  Suspend Timeout

  This timeout in seconds specifies how long BluePiano should try to re-establish a lost connection. If the connection can't be re-established within this time, the connection is suspended. The user must initiate a reconnect manually via the notification bar or via the Bluetooth action key.

  Retry Interval

  When opening a Bluetooth connection, BluePiano waits the specified number of milliseconds between the single open operations.

  Open Retries

  The total number of retries when opening a connection.

  Disaster Recovery

  Some handsets utilize buggy Bluetooth firmware. In the case of unrecoverable Bluetooth SPP errors BluePiano may restart the Bluetooth stack automatically. The use of this option is not recommended under normal circumstances.






• Read Policies
  

  These parameters instruct BluePiano how to handle received device data.

  Raw Mode

  If checked, BluePiano works in raw mode. Data is forwarded to the target app immediately after it was received or if a carriage return (CR) or line feed (LF) character was detected in the input data. No other special data grouping is performed. In this mode BluePiano is able to handle byte values above 0x7f correctly.

  If unchecked, BluePiano works in enhanced mode: it groups incoming device data automatically into so-called data packets. A data packet is defined by the time required for receiving it, by the byte-size of the packet or by a delimiter sequence. 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 (available in enhanced mode only).

  Size

  The maximum number of bytes for a data packet (available in enhanced mode only).

  Separator

  A regular expression which matches the character sequence used for marking the end of a data packet (available in enhanced mode only).
  Please note: If using a regular expression, BluePiano expects valid UTF-8 (or ANSI 0x00-0x7f) characters to be received from the device.

  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.

BluePiano Privacy

TEC-IT respects your privacy. Your data is safe.

BluePiano does not log, store or forward typed text, passwords or other personal data. Please contact us if you have any concerns regarding phishing, key logging or spying.

Background information: In order to use an alternative input method on Android devices, the user must manually activate this method. Android displays a security hint which reads like this: Attention: This input method may be able to collect all the text you type, including personal data like passwords and credit card numbers. It comes from the application BluePiano (or a similar name). Use this input method?