Version 1.1.1

Table of contents

General description

Bluetooth Low Energy (or BLE) is a new standard that emphasizes connectivity with low power devices.

The Tap is a BLE v4.2 device, backwards compatible with BLE v4.0, in peripheral mode. Every BLE v4.0 central device can connect to the Tap device.

Usage of the keyboard and mouse is done over the standard HID over GATT interface, which most of mainstream devices, such as Windows 8.1/10 laptops or iPhones since 4S, support.
Custom protocol can be used to interact with the Tap without using the HID interface for any kind of application.

Device discovery

Scanning

The Tap is advertising when it's not connected.

The advertised data contains a 128-bit custom UUID to distinguish it from other BLE devices.
The device name itself is not unique to the device as it can be modified by the user.

The 128-bit UUID is: C3FF0001-1D8B-40FD-A56F-C7BD5D0F3370

Connecting & pairing

The device is connectable as long as it's not already connected to a peer device.

For proper usage with the Tap, the Tap must be also paired (bonded) and not just connected.
To detect a Tap in a paired devices list, use the Tap UUID for filtering.

If it's currently connected, it must be disconnected from the active peer.
Disconnected on the peer can be done by turning off the Bluetooth connectivity or by hitting a disconnect button, if applicable.

Usage of API

Tap is communicating over GATT for information exchange between the Tap and the central device.

The Tap is a GATT server and is exposing several standard services and 2 custom ones.
Any central device may communicate with the API after connection.

For certain operations, higher ATT MTU (Maximum transmission unit) of 185 is required and expected from the central to support.
Which operation require that are TBA.

Certain APIs are available from specific firmware (FW) versions. Please be sure to check the FW version before using those APIs.
If no version is described in a feature, it's available for all versions.

Types of API

Battery level

A standard Battery Service is available, according to BLE specifications.

Any bonded central device may read the battery level from the Battery Level characteristic.

Device information

A standard Device Information Service is available, according to BLE specifications.

Any bonded central device may read these fields: 

• Manufacturer Name String
• Serial Number String
• Hardware Revision String
• Firmware Revision String

The firmware version string is in a MAJOR.MINOR.FORMAT format (see https://semver.org/).
Each element would not be larger than 99.

Tap proprietary 

Custom 128-bit service contains the main API for the Tap. The UUID of the service is: C3FF0001-1D8B-40FD-A56F-C7BD5D0F3370

The following characteristics are available:

• From FW version 1.3.0: Tap data. UUID: C3FF0005-1D8B-40FD-A56F-C7BD5D0F3370. Properties: Notify
• From FW version 1.4.0: Mouse motion data. UUID: C3FF0006-1D8B-40FD-A56F-C7BD5D0F3370. Properties: Notify

Support service is being used for the API. It's UUID: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E.
There's a single support characteristic in the support service. UUID: 6E400002-B5A3-F393-E0A9-E50E24DCCA9E. Properties: Write

Tap proprietary protocol (supported from version 1.3.0)

General description

The is extracting a handful of gestures from its sensor using complicated algorithms.
Our SDK exposes those via the Tap protocol and allows anyone to receive events on any gesture detection.

The Tap has 2 usage modes: Text mode and Controller mode. By default, the device is in Text mode and all normal functions, such as mouse and multi-taps are maintained.
When the proprietary protocol is desired, the Tap must enter Controller mode by application request.
During Controller mode, the Tap has reduced functionally but will send events according to the protocol.
When done with Controller mode, the app must tell the Tap to exit the controller mode.

Events are sent as an array of bytes from specific characteristic under the Tap Service. Multi-byte fields are in Little Endian format.

Controller mode

The Tap must be entered into controller mode by performing a write action on the support characteristic with the Enter controller mode 4 byte magic packet.
To remain in controller mode, the enter controller mode magic packet must be sent every 10 seconds.
To exit out of controller mode, the exit controller mode magic packet must be written.

During the controller mode, the Tap has reduced functionality to not potentially interfere with applications.
For example, multi taps are not supported and Switch & Shift behavior.
Make sure to exit out of controller mode when the application closes.

Tap data

Once in controller mode and Tap data characteristic's notifications are enabled, Tap data characteristic will send tap events via notifications.

Packet format:

The tap code is a binary combination of the tapping fingers with the following mapping:

• (LSB) Bit 0: thumb finger
• Bit 1: index finger
• Bit 2: middle finger
• Bit 3: ring finger
• Bit 4: pinky finger
• Bit 5: unused
• Bit 6: unused
• (MSB) Bit 7: unused

For example, when the user tapped all fingers, the tap code is 31 (or 0x1F). When the user tapped both thumb and index (character N), the tap code is 3 (0x03).

When the tap is in left hand mode, the finger-to-bit mapping remains relevant.
Thumb tap on the right hand with the right-hand setting will set the same bit as the thumb tap on the left-hand with the left hand setting.

The tap interval is the period from the previous tap in milliseconds. It's saturated at 65535 milliseconds and will not grow further.

Mouse motion data (from version 1.4.0)

Once in controller mode and Mouse motion data characteristic's notifications are enabled, Tap data characteristic will send tap events via notifications.

Packet format:

To get mouse information, the user must place the Tap in the mouse mode position. This is then indicated in the mouse mode indicator field as 1.
When the user lifts the hand, the mouse mode indicator turns to 0 and then the transmission stops.

These packets are sent at a constant 16ms interval when there's motion, allowing to capture a smooth mouse motion as it's generated on the Tap's side.
When the Tap is not detecting that the mouse is on the surface, motion transmission is stopped.
Due to BLE limitations, actual data arrival is not constant and maybe arrive at 0ms - 30ms interval. Motion interval field may be used to identify correct data intervals.

The mouse motion is encoded in the dx and dy fields in dots units, range between -32767 and 32768 and describe the amount of relative motion done in the current interval on the surface.
Note that this data doesn't mean absolute position or relative position on the screen.

Mouse motion directions:

This means that positive dx means forward motion and positive dy means leftward motion.
Note that when mouse mode indicator is 0, dx and dy values shouldn't be used.

When left hand settings is on, the motion is updated accordingly so that dx and dy still have same meaning, i.e. positive dx means forward motion.
Mouse sensitivity setting that can be modified using the TapManager also affects the motion data. High mouse sensitivity means more dots per inch.