BluePiano: User Manual

The keyboard wedge BluePiano extends Android® with data acquisition from external Bluetooth® devices. This new 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.

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.

Bluetooth Software Wedge

If activated, BluePiano replaces the currently active keyboard on your device with its own keyboard. This keyboard supports all major input languages and keyboard layouts, provides word suggestions and listens to voice input. Swipe input is not supported.

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.

In addition to the Bluetooth capabilities, BluePiano is able to read NFC tags (if supported by the hardware) and provides a built-in camera scanner (useful for backup purposes, an external camera scanner app can also be adjusted).

How does BluePiano Work?

Connecting to Bluetooth Device

The BluePiano keyboard establishes a connection to the configured Bluetooth SPP device (via a system service running in the background) and waits for data. Received device data is grouped into packets. Each packet is forwarded as a single unit to the target app (this ensures that - for example - all 8 digits of an EAN barcode are transferred as a single unit to the app). Such 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. The data is then forwarded to the target app by injecting the data into the active input-field.

If there are any problems with the device connection, BluePiano tries to reconnect automatically. If this is not possible, BluePiano suspends the device connection and notifies the user with a message in the notification bar. The parameters for (re-)establishing a Bluetooth connection as well as the preferred notification method can be adjusted in the BluePiano Settings.

Basic Configuration

After installation, BluePiano is the active keyboard on your system. Manual typing is possible immediately, for Bluetooth data acquisition you need to configure a Bluetooth device first.

For initial configuration tap on the notification message (Bluetooth device not configured! Tap here!) or open BluePiano Settings (BluePiano cog wheel -> Keyboard preferences -> Configuration -> Paired device). Choose the device from the list or use Bluetooth Settings to establish a pairing with a new device. Check out the user manual of the device for the detailed pairing procedure and the required passkey (if any key is required you may try the standard keys 0000 or 1234).

That's all. Whenever the Bluetooth device sends data, this data is grouped according to the rules defined below and then injected into the current input-field of the target app. In case of interrupted or lost Bluetooth connections, the app informs the user with suitable messages in the notification area.

Please note that you may need to adjust advanced parameters for Bluetooth connectivity, data grouping and data packaging and for input rules which control the behavior in combination with certain target apps. This document focuses on Bluetooth-specific settings, for keyboard or camera scanner / NFC reader settings please refer to the Barcode/NFC Scanner Keyboard user manual.

BluePiano Settings

Open Settings

To modify the BluePiano options, tap the BluePiano cog wheel in the suggestion bar (also reachable by a long tap of the comma key). A menu with the following options appears:

  • Buy now
    The buy now option is only visible in the free trial. Tap it to purchase the unlimited version.
  • Keyboard preferences
    Opens a page which offers a section named Keyboard preferences (again :-) ) which subsequently offers all settings related to BluePiano and another section named Common keyboard preferences which offers options for the general keyboard functionality (not covered in this document).
  • Scan
    Tapping this option invokes the camera based barcode scanner or NFC reader (whatever is adjusted in the Keyboard preferences).

Keyboard preferences for BluePiano

BluePiano Android Keyboard Settings: Bluetooth
  • Bluetooth options

    This section is used to specify the operation mode and name of the Bluetooth device, advanced device options and the feedback behavior.

  • Full version

    This section offers you the possibility to purchase (in-app purchase) a full license or to check the license status

  • Common

    This section specifies the additional features of the keyboard (like support for camera scanner and NFC reader), whether scanned data should be copied to the clipboard and the appearance of the scanner and quicktext keys. For more information please refer to the Barcode/NFC Scanner Keyboard user manual.

  • Camera Scanner

    This section is used for configuration of the camera scanner feature. For more information refer to the Barcode/NFC Scanner Keyboard user manual.

  • NFC Reader

    This section is used for configuration of the NFC reader feature. For more information refer to the Barcode/NFC Scanner Keyboard user manual.

  • Keyboard behaviour

    This section is used for configuration of the simulation rules, prefix and postfix settings and autoscan-features. For more information refer to the Barcode/NFC Scanner Keyboard user manual.

  • Import/Export

    This section is used for exporting or importing configuration settings. For more information refer to the Barcode/NFC Scanner Keyboard user manual.

  • About

    This section is used for granting app permissions, presenting the user manual or YouTube videos, providing information regarding privacy, licensing and app versions.

Bluetooth options

Device type

BluePiano can be used with each Bluetooth SPP (serial port profile, RFCOMM) device. Select one of the following options to choose the operating mode of BluePiano:

  • Bluetooth Client
    Use the client mode if you need to connect to a device which is sending data on its own (like an external Bluetooth barcode scanner which is usually working as a server). Select the device by tapping on Configuration below (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.

Configuration

When BluePiano is working in client mode specify the following common options:

  • Paired device
    The device BluePiano connects to. Please note, you need to pair your Android with the Bluetooth device in question.
  • Insecure RFCOMM
    Select if you allow insecure RFCOMM pairing/communication. Required for some Bluetooth devices.
  • Display name
    The friendly name of this Bluetooth connection which is displayed by BluePiano in informational, warning and error messages.

When BluePiano is working in server mode specify the following common options:

  • SPP name
    The name used for the Bluetooth SPP service offered by BluePiano.
  • Display name
    The friendly name of this Bluetooth connection which is displayed by BluePiano in informational, warning and error messages.

To specify the automatic grouping of data into packets the following options are available:

  • Enabled
    If checked, BluePiano 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.
    If unchecked, BluePiano processes and forwards data as it is received by the device. No packaging is performed.
  • Size limit
    If checked, the maximum length of a packet can be specified.
  • Max. length of a data packet
    The maximum number of bytes for a data packet.
  • Time limit
    If checked, the maximum time for receiving a packet can be specified.
  • Reading period for a data packet
    The maximum time (in milliseconds) to receive the data packet. All bytes received within this time are delivered in a single data packet.
  • Use delimiter
    If checked, a delimiter sequence can be specified.
  • Delimiter
    A regular expression which matches the character sequence used for marking the end of a data packet.
  • Include delimiter
    If checked, the delimiter sequence is treated as part of the data packet. If unchecked, the delimiter sequence is stripped from the acquired data.

To specify the behaviour when opening a connection the following options are available:

  • Open attempts
    The total number of attempts to open a connection to a device.
  • Waiting time
    Waiting time (in milliseconds) before another open attempt is performed.

When operating BluePiano in client mode, it offers the following parameters to specify the reconnection behaviour :

  • Enabled
    If checked, BluePiano tries to reestablish interrupted or lost device connections.
  • Reconnection attempts
    The total number of attempts to recover a lost device connection.
  • Waiting time
    Waiting time (in milliseconds) before another reconnection attempt is performed.

Feedback on success

Specify the feedback behavior in case of successful Bluetooth connections.

Feedback on error

Specify the feedback behavior in case of failed Bluetooth connections.

BluePiano Privacy

TEC-IT respects your privacy. BluePiano does not log, store or forward sensitive information.

When using alternative input methods, Android displays a security warning as a general precautional measure which must be confirmed during installation. This message is normal and reads something like this: 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. Use this input method?

Please contact us if you have any privacy or security concerns.