BluePiano: User Manual

The keyboard wedge BluePiano extends Android® with Bluetooth® data acquisition. This new input method provides a Bluetooth-enabled soft-keyboard. This keyboard captures Bluetooth data and forwards the received data to input fields of arbitrary apps by simulating manual user input. For the target app the captured data appears as entered by the user.


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.

Bluetooth Software Wedge

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?

Connecting to Bluetooth Device

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

Long-Press on ?123

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

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

Bluetooth action key - device not configuredThis symbol is shown if no Bluetooth input device was configured. Tap this key to open the Bluetooth Device Manager.

Bluetooth action key - connectingThis symbol is shown if BluePiano is currently connecting to the Bluetooth input device.

Bluetooth action key - connection lostThe 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.

Bluetooth action key - suspendedThe 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.

Action key - camera scannerTap 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:

BluePiano Android Keyboard Settings: Bluetooth
  • 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.


    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.

  • BluePiano Android Keyboard Settings: Bluetooth
  • 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
    BluePiano Android Keyboard Settings: Bluetooth 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
    BluePiano Android Keyboard Settings: Bluetooth Import

    Import a configuration file.


    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.


    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.


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

Keyboard Simulation Rules

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

Keyboard Simulation Rule

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

Bluetooth Device Manager

You can reach these settings with the contextual menu (Menu Icon) 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.

Bluetooth Device Manager 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 ( 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.


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


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.

Bluetooth Connection Settings
  • 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.

    Bluetooth Connection Settings 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.


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


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


    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?