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:

I want to…	Go to
Get a first working connection	Tutorial: Getting started
Solve a specific task	How-to guides
Look up APIs and types	Reference
Understand modes and sensors	Explanation
Read the changelog	Release notes

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 TapSDK, InputModeController

async def main():
    tap = TapSDK()
    tap.register_tap_events(lambda identifier, tapcode: print(identifier, tapcode))
    await tap.run()
    await tap.set_input_mode(InputModeController())
    await asyncio.Event().wait()

asyncio.run(main())

Pair the Tap with the OS first. Update firmware with Tap Manager. More complete flow: examples/basic.py.

Features (summary)

• Modes: Text, Controller, Controller+Text, Raw sensors
• Events: tap, mouse, air gesture, air-gesture state, raw packets, connect/disconnect
• Commands: set mode, set 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.