tap-python-sdk 0.7.0

Tap strap python sdk

TapStrap Python SDK (beta)

What Is This ?

TAP python SDK allows you to build python app that can establish BLE connection with Tap Strap and TapXR, send commands and receive events and data - Thus allowing TAP to act as a controller for your app!
The library is developed with Python >= 3.9 and is currently in beta.

Supported Platforms

This package supports the following platforms:

• MacOS (tested on 10.15.2) - using Apple's CoreBluetooth library. The library depends on PyObjC which Apple includes with their Python version on OSX. Note that if you're using a different Python, be sure to install PyObjC for that version of Python.
• Windows 10 - using Bleak with WinRT for BLE connectivity (no external DLL required).
• Linux (tested on Ubuntu 18.04) - need to install libbluetooth-dev and bluez-tools

  sudo apt-get install bluez-tools libbluetooth-dev
  

  also the user needs to be in the bluetooth group:

  sudo usermod -G bluetooth -a <username>
  #and can reload groups in this shell by running the following command or by logging out and back in:
  su - $USER
  

Installation

Install the package from PyPI:

pip install tap-python-sdk

Or clone this repo and install the package locally:

git clone https://github.com/TapWithUs/tap-python-sdk
cd tap-python-sdk
pip install .

The SDK is asyncio-based. Pair your Tap device with the OS first, then connect and register callbacks inside an async entry point:

import asyncio
from tapsdk import TapSDK

async def main():
    tap_device = TapSDK()
    tap_device.register_tap_events(lambda identifier, tapcode: print(identifier, tapcode))
    await tap_device.run()  # connects to a paired Tap, or scans until one is found

asyncio.run(main())

If no Tap is already connected at the OS level, run() will scan and wait for a device. On Windows and MacOS it also polls for already-paired devices that reconnect without advertising.

Also make sure that you have updated your Tap device to the latest version.

Features

This SDK implements two basic interfaces with a Tap device.

First is setting the operation mode:

1. Text mode - the Tap device will operate normally, with no events being sent to the SDK
2. Controller mode - the Tap device will send events to the SDK
3. Controller and Text mode - the Tap device will operate normally, in parallel with sending events to the SDK
4. Raw data mode - the Tap device will stream raw sensors data to the SDK.

Second, subscribing to the following events:

1. Tap event - whenever a tap event has occurred
2. Mouse event - whenever a mouse movement has occurred
3. AirGesture event - whenever one of the gestures is detected
4. Raw data - whenever new raw data sample is being made.

Additional to these functional events, there are also some state events, such as connection and disconnection of Tap devices to the SDK backend.

Spatial Control - NEW

Authorized developers can gain access to the experimental Spatial Control features:

1. Extended AirGesture state - enabling aggregation for pinch, drag and swipe gestures.
2. Select input type - enabling the selection of input type to be activated - i.e. AirMouse/Tapping.

These features are only available on TapXR and only for qualified developers. Request access here

Migration from 0.6.x

If you are upgrading from an earlier release, note these breaking changes:

• TapInputMode("controller") → InputModeController() (and similarly for other modes). Import from tapsdk.
• TapInputMode("raw", sensitivity=[2, 1, 4]) → InputModeRaw(finger_accl_sens=..., imu_gyro_sens=..., imu_accl_sens=...). Use the typed enums in tapsdk.enumerations.
• from tapsdk.models import AirGestures → from tapsdk import AirGestures
• The loop= constructor argument has been removed.
• Event registration (register_*) is synchronous; call it before await tap_device.run().
• Commands (set_input_mode, set_input_type, send_vibration_sequence) are async and must be awaited.
• OS-specific examples (example_unix.py, example_win.py) have been replaced by a single cross-platform examples/basic.py.

High level API

The SDK uses callbacks to implement user functions on the various events. To register a callback, you just have to instance a TapSDK object and:

def on_tap_event(identifier, tapcode):
    print(identifier + " tapped " + str(tapcode))

tap_device.register_tap_events(on_tap_event)

Commands list

1. set_input_mode(self, input_mode:InputMode, identifier=None): This function sends a mode selection command. It accepts an object of type InputMode such as InputModeText, InputModeController, InputModeControllerText, or InputModeRaw.
   For example:

   from tapsdk import InputModeController
   await tap_device.set_input_mode(InputModeController())
   

   For raw sensors mode, you can specify sensitivity and scaling:

   from tapsdk import InputModeRaw
   from tapsdk.enumerations import FingerAcclSensitivity, ImuGyroSensitivity, ImuAcclSensitivity
   await tap_device.set_input_mode(InputModeRaw(
       scaled=True,
       finger_accl_sens=FingerAcclSensitivity.G4,
       imu_gyro_sens=ImuGyroSensitivity.DPS250,
       imu_accl_sens=ImuAcclSensitivity.G4
   ))
   

2. set_input_type(self, input_type:InputType, identifier=None):

   Only for TapXR and with Spatial Control experimental firmware

   This function sends a command to force input type. It accepts an enum of type InputType initialized with any of the types InputType.MOUSE, InputType.KEYBOARD, or InputType.AUTO.
   For example:

   from tapsdk import InputType
   await tap_device.set_input_type(InputType.AUTO)
   

   This will set the input to be automatically selected by the Tap device, based on hand posture.

3. send_vibration_sequence(self, sequence:list, identifier=None): This function sends a series of haptic activations. sequence is a list of integers indicating the activation and delay periods one after another. The periods are in millisecond units, in the range of [10,2550] and in resolution of 10ms. Each haptic command supports up to 18 period definitions (i.e. 9 haptics + delay pairs).
   For example:

   await tap_device.send_vibration_sequence(sequence=[1000,300,200])
   

   will trigger a 1s haptic, followed by 300ms delay, followed by 200ms haptic.

Events list

1. register_connection_events(self, listener:Callable):
   Register callback to a Tap strap connection event.

   def on_connect(tap_sdk_instance):
       print("Connected to Tap device")
   
   tap_device.register_connection_events(on_connect)
   

2. register_disconnection_events(self, listener:Callable):
   Register callback to a Tap strap disconnection event.

   def on_disconnect(client):
       print("Tap device disconnected")
   
   tap_device.register_disconnection_events(on_disconnect)
   

3. register_tap_events(self, listener:Callable):
   Register callback to a tap event.

   def on_tap_event(identifier, tapcode):
       print(identifier + " - tapped " + str(tapcode))
   
   tap_device.register_tap_events(on_tap_event)
   

   tapcode is an 8-bit unsigned number, between 1 and 31 which is formed by a binary representation of the fingers that are tapped. The LSb is thumb finger, the MSb is the pinky finger. For example: if combination equals 5 - its binary form is 10100 - means that the thumb and the middle fingers were tapped.

4. register_mouse_events(self, listener:Callable):
   Register callback to a mouse or air mouse movement event.

   def on_mouse_event(identifier, vx, vy, proximity):
       print(identifier + " - moused: %d, %d" %(vx, vy))
   
   tap_device.register_mouse_events(on_mouse_event)
   

   vx and vy are the horizontal and vertical velocities of the mouse movement respectively. proximity is a boolean that indicates proximity with a surface.

5. register_raw_data_events(self, listener:Callable):
   Register callback to raw sensors data packet received event.

   def on_raw_sensor_data(identifier, packets):
       for packet in packets:
           print(identifier, packet["type"], packet["ts"], packet["payload"])
   
   tap_device.register_raw_data_events(on_raw_sensor_data)
   

   The callback receives a list of dicts, each with keys type ("imu" or "accl"), ts (millisecond timestamp), and payload (list of sample values). When InputModeRaw(scaled=True) is active, values are in mg and mdps. You'll find more information on that mode in the dedicated section below or here.

6. register_air_gesture_events(self, listener:Callable):
   Register callback to air gesture events.

   from tapsdk import AirGestures
   
   def on_airgesture(identifier, gesture):
       print(identifier + " - gesture: " + str(AirGestures(gesture)))
   
   tap_device.register_air_gesture_events(on_airgesture)
   

   gesture is an integer code of the air gesture detected. The air gesture values are enumerated in the AirGestures class, including directional gestures (UP_ONE_FINGER, PINCH, etc.), thumb gestures (THUMB_FINGER, THUMB_MIDDLE), and spatial state gestures (STATE_OPEN, STATE_FIST, etc.).

7. register_air_gesture_state_events(self, listener:Callable):
   Register callback to mouse-mode state changes (e.g. air mouse, optical mouse).

   from tapsdk.enumerations import MouseModes
   
   def on_mouse_mode_change(identifier, mouse_mode):
       print(identifier + " - mode: " + str(mouse_mode))
   
   tap_device.register_air_gesture_state_events(on_mouse_mode_change)
   

   mouse_mode is a MouseModes enum value: STDBY, AIR_MOUSE, OPTICAL1, or OPTICAL2.

Raw sensors mode

Make sure that "Developer mode" is enabled on TapManager app for this mode to work properly

In raw sensors mode, the Tap device continuously sends raw data from the following sensors:

1. Five 3-axis accelerometers - one per each finger (available only on TAP Strap and Tap Strap 2).
   • sampled at 200Hz
   • allows dynamic range configuration (±2G, ±4G, ±8G, ±16G)
2. IMU (3-axis accelerometer + gyro) located on the thumb (available on TAP Strap 2 and TapXR).
   • sampled at 208Hz.
   • allows dynamic range configuration for the accelerometer (±2G, ±4G, ±8G, ±16G) and for the gyro (±125dps, ±250dps, ±500dps, ±1000dps, ±2000dps).

The sensors measurements are given with respect to the reference system below.

Each sample (of accelerometer or imu) is preambled with a millisecond timestamp, referenced to an internal Tap clock.

The dynamic range of the sensors is determined with the set_input_mode method by passing an InputModeRaw instance with the desired sensitivity enums, and a boolean flag indicating if the data should be scaled to mg and mdps for the accelerometer and gyro respectively:

from tapsdk import InputModeRaw
from tapsdk.enumerations import FingerAcclSensitivity, ImuGyroSensitivity, ImuAcclSensitivity

await tap_device.set_input_mode(InputModeRaw(
    scaled=True,
    finger_accl_sens=FingerAcclSensitivity.G4,
    imu_gyro_sens=ImuGyroSensitivity.DPS250,
    imu_accl_sens=ImuAcclSensitivity.G4
))

Refer to FingerAcclSensitivity, ImuGyroSensitivity, and ImuAcclSensitivity in tapsdk.enumerations for the available sensitivity values.

Examples

You can find some examples in the examples folder.

Testing

To run the tests, first install the development dependencies:

pip install .[dev]

Then run the tests using pytest:

pytest

Known Issues

See History.md for release notes. No known issues at 0.7.0.

Support

Please refer to the issues tab! :)

History

Releasing

PyPI releases are published automatically when a version tag is pushed to GitHub.

1. Bump __version__ in tapsdk/__version__.py and update this file.

2. Merge the release changes into develop, then into master as needed.

3. Create and push an annotated tag whose name matches the package version (for example v0.7.0):

   git tag -a v0.7.0 -m "Release 0.7.0"
   git push origin v0.7.0
   

The Publish to PyPI workflow runs the same lint and test matrix as CI, verifies that the tag (without the v prefix) matches tapsdk.__version__, builds the package with python -m build, and uploads it to PyPI using Trusted Publishing.

Maintainers must configure PyPI Trusted Publishing for the tap-python-sdk project name, the TapWithUs/tap-python-sdk repository, and a GitHub pypi environment before the first automated release.

0.7.0 (2026-06-09)

---

Main features

• Unified cross-platform implementation in tapsdk/tap.py (removed separate posix/dotnet backends).
• Windows rewritten to use Bleak/WinRT instead of TAPWin.dll.
• InputMode API: TapInputMode("…") replaced by InputModeText, InputModeController, InputModeControllerText, InputModeRaw.
• Raw mode: typed sensitivity enums and optional scaling to mg/mdps (scaled=True).
• Connection and disconnection events implemented on all platforms.
• Windows: BLE scan and reconnect polling for paired devices.
• Python requirement raised to 3.9+.
• CI: cross-platform pytest and flake8.
• New AirGestures values (thumb and state gestures).

Breaking changes

• Removed TapInputMode, loop constructor argument, tapsdk.models, and OS-specific examples.
• Windows no longer uses bundled TAPWin.dll.

0.6.0 (2024-07-04)

---

Main features

• Added Spatial features for TapXR.
• Mac and Linux backends unified to posix backend.

Known Issues

• Windows backend -
  • Raw sensor data rate might be lower than expected.
  • Sometimes a Tap strap wouldn't be detected upon connection. In this case try restarting your Tap and/or the Python application. In worst case scenario re-pair your Tap.
  • Spatial features are still not available for Windows backend.
• MacOS & Linux backends -
  • Doesn't support multiple Tap strap connections.
  • OnConnect and OnDisconnect events are not implemented
  • Raw sensor data is given unscaled (i.e. unitless), therefore in order to scale to physical units need to multiply by the relevant scale factor

0.5.1 (2024-01-01)

---

Main features

• Support TapXR Air Gesture pinch

0.5.0 (2021-08-03)

---

Main features

• Support Bleak 0.12.1 for mac

0.3.0 (2020-09-07)

---

Main features

• Linux support
• Some bug fixes

0.2.0 (2020-02-22)

---

Main features

• Added dll to enable windows backend.
• fix parsers output types on gesture and tap messages

0.1.0 (2020-02-20)

---

Main features

• SDK created.