Tap Python SDK (beta)

BLE SDK for building Python apps that connect to Tap Strap and TapXR, send commands, and receive tap, mouse, air-gesture, and raw sensor events.

Python ≥ 3.9 · macOS / Windows / Linux · currently in beta

Documentation

Published docs (MkDocs Material, versioned with mike): https://tapwithus.github.io/tap-python-sdk/

Pick the path that matches your goal:

Full index: docs/index.md. Local preview: pip install -r requirements-docs.txt && mkdocs serve.

Install

pip install tap-python-sdk

Platform notes (BlueZ on Linux, Bleak pins, pairing): Install the SDK.

Quick example

import asyncio
from tapsdk import TapSDK2, connect

async def main():
    sdk = await connect()  # auto-detects v1 / v2
    sdk.register_tap_events(lambda identifier, tapcode: print(identifier, tapcode))
    await sdk.start()
    print("Protocol:", "v2" if isinstance(sdk, TapSDK2) else "v1")
    await asyncio.Event().wait()

asyncio.run(main())

Pair the Tap with the OS first. Update firmware with Tap Manager. connect() picks TapSDK (v1) or TapSDK2 (v2) from GATT. More: examples/connect.py.

Features (summary)

• Protocols: v1 (TapSDK) and v2 framed (TapSDK2); connect() auto-detects
• Modes (v1): Text, Controller, Controller+Text, Raw sensors
• Features (v2): DeviceFeatures, vision model/op-mode, IMU motion/raw, standby
• Events: tap, mouse, air gesture, raw / IMU packets, connect/disconnect
• Commands: set mode / features, Spatial Control input type (TapXR), haptic sequences
• Spatial Control (authorized TapXR builds): see Use Spatial Control

Migrating from 0.6.x

Breaking API changes are listed in Migrate from 0.6 and Release notes.

Contributing

Every pull request should add a user-facing entry under the Unreleased heading in Release notes. PRs with no user-facing change (CI, refactors, typo fixes) can skip this by adding the skip-changelog label.

Releasing

Releases use a prep-commit-then-tag flow so the tag, PyPI artifact, and docs all match:

python scripts/prepare_release.py X.Y.Z   # bumps version, cuts Unreleased -> X.Y.Z
git add tapsdk/__version__.py docs/release-notes.md
git commit -m "Release X.Y.Z"
git tag -a vX.Y.Z -m "Release X.Y.Z"
git push origin HEAD vX.Y.Z

Pushing the tag runs .github/workflows/publish.yml, which re-runs tests, verifies the version and release notes, and publishes to PyPI. Versioned docs deploy separately after a successful publish. See the header comments in that workflow for details.

Testing

pip install .[dev]
pytest

Support

Use the GitHub issues tab.

Release notes

Changelog for published tap-python-sdk releases on PyPI.

Add user-facing changes for the next release under Unreleased in your pull request. At release time scripts/prepare_release.py renames this section to the new version and opens a fresh empty one.

Unreleased

Main features

Bug fixes

0.8.0 (2026-08-04)

Main features

• Unified v1/v2 entry: await connect() auto-detects protocol from GATT (c3ff000e), returns TapSDK or TapSDK2; register callbacks then await start() (#36)
• Shared BLE transport (tapsdk._transport) so TapSDK2 uses the same Windows retrieve/scan/reconnect path as TapSDK
• Shared get_device_info() / DeviceInfo on both TapSDK and TapSDK2 via tapsdk.device_info (#36)
• Versioned docs site (mike) deployed after successful PyPI publish, with a release notes page derived from docs/release-notes.md (#47) (#48)
• Prep-commit-then-tag release flow: author-written Unreleased entries, scripts/prepare_release.py, and a verify-only publish pipeline (#47) (#48)
• Shared reusable test workflow used by CI and Publish (#39) (#48)

Bug fixes

• connect() now discovers GATT services before protocol detect so empty service caches cannot mis-classify v2 devices as v1

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.