Python SDK

Cross-platform BLE host SDK for macOS, Windows, and Linux. Pair in the OS first, then connect from Python.

1. Package
2. Install
3. Hello Tap
4. Modes
5. Events
6. Spatial Control
7. Notes

Package

PyPI
Source	TapWithUs/tap-python-sdk
Docs	tapwithus.github.io/tap-python-sdk

Install

Requires Python 3.10+.

pip install tap-python-sdk

Platforms: macOS (CoreBluetooth), Windows 10+ (Bleak/WinRT), Linux (BlueZ). Pair Tap with the OS before running your script.

Hello Tap

One path for Tap Strap and TapXR. Pair in OS Bluetooth first, then connect and start. The script switches the Tap out of keyboard mode — Text/HID sends no tap callbacks.

import asyncio
from tapsdk import (
    DeviceFeatures,
    InputModeController,
    ModelTypes,
    VisionSensorOpModes,
    connect,
)


def on_tap(identifier, tapcode):
    # tapcode is int 1..31 — bit0=thumb … bit4=pinky
    code = tapcode[0] if isinstance(tapcode, (list, tuple)) else tapcode
    print(f"{identifier} tapped {code} (0b{int(code):05b})")


async def main():
    # Pair in OS Bluetooth settings first — do not expect a cold unpaired scan.
    sdk = await connect()
    sdk.register_tap_events(on_tap)
    await sdk.start()
    if hasattr(sdk, "set_input_mode"):
        await sdk.set_input_mode(InputModeController())
    else:
        await sdk.set_feature(DeviceFeatures.MODEL_DETECTION, True)
        await sdk.set_vision_sensor_model(ModelTypes.TAPPING)
        await sdk.set_vision_sensor_op_mode(VisionSensorOpModes.TRIGGER)

    print("Waiting for taps… (Ctrl+C to quit)")
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())

The script switches the Tap out of keyboard mode for you. If you write your own, do this after start(), or you'll get no tap events. Same script as Getting started.

Modes

Recent releases use typed modes such as InputModeText, InputModeController, InputModeControllerText, and InputModeRaw (replacing older stringly TapInputMode("…")). Pin a version and check the published reference for setters on that release.

Events

Register handlers for tap events, and register_air_gesture_events for raw air gestures (swipes, pinches, fist). Exact method names live in the package reference; the Hello Tap example above is the minimal tap path. TapXR on the new developer firmware supports the full gesture set (taps, thumb-to-finger pinches, pinch-and-drag, thumb swipes, fist). Raw air gestures (swipes, pinches, fist) are available in Python, Web and Android (Android via onAirMouseInputReceived). iOS delivers TapXR air gestures through tapXRAirGestured.

Spatial Control

TapXR Spatial Control needs authorized builds. Request access.

Notes

• APIs can change between PyPI releases — pin versions.
• Prefer the published docs when this page and a release diverge.
• BLE stacks differ (BlueZ / CoreBluetooth / Bleak). Re-pair if connect flaps.