Getting started (TapSDK2)¶
This tutorial walks you through installing the SDK, connecting with TapSDK2, and printing tap events. By the end you will have a small asyncio program that talks to the TapXR developer firmware (and TapBand, same BLE API).
The docs home has one script that works for Tap Strap and TapXR. Use this page when you already know you have set_feature.
TapBand is coming soon and is not for sale yet. Join the TapBand waitlist.
What you need¶
- Python 3.10 or newer
- A TapXR on the TapXR developer firmware, or TapBand (GATT characteristic
c3ff000epresent)
If connect() returns TapSDK, use the TapSDK tutorial instead.
1. Install the SDK¶
Then import with from tapsdk import .... The PyPI name is tap-python-sdk; the import name is tapsdk.
On Linux, also install BlueZ tooling and add your user to the bluetooth group:
2. Create a project file¶
Create hello_tap.py:
import asyncio
from tapsdk import DeviceFeatures, ModelTypes, VisionSensorOpModes, connect
def on_tap(identifier, tapcode):
code = tapcode[0] if isinstance(tapcode, (list, tuple)) else tapcode
print(f"{identifier} tapped {code}")
def on_connect(serial_number):
print("Connected:", serial_number.decode("utf-8"))
async def main():
sdk = await connect()
if not hasattr(sdk, "set_feature"):
raise SystemExit("This device uses set_input_mode. See the TapSDK tutorial.")
sdk.register_connection_events(on_connect)
sdk.register_tap_events(on_tap)
await sdk.start()
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)
await asyncio.Event().wait()
asyncio.run(main())
Or construct TapSDK2() and call await sdk.run() when you already know the firmware uses features.
3. Run it¶
- Turn the Tap on.
- Run:
- When you see
Connected: …, tap with one or more fingers. You should see lines like:
On TapSDK2, tapcode is a one-element list [tapcode]; the value is the same finger bitmask as TapSDK (bit 0 = thumb … bit 4 = pinky). See Events.
Without DeviceFeatures.MODEL_DETECTION and a vision model, model events stay off.
4. What just happened¶
await connect()attaches to a Tap (already connected, or by scan) and returnsTapSDK2for developer firmware. Notifications are not started yet.register_*attaches callbacks (sync; register connection callbacks beforestart()).await sdk.start()arms framed notifications, starts keepalive, and fires the connection callback with the serial number (bytes).set_feature(MODEL_DETECTION, True)plus the tapping model enables tap delivery. There is noset_input_modeonTapSDK2.
Next steps¶
- Enable IMU, vision, standby, or haptics: How-to guides
- Full callback and command signatures: API reference
- Why features replace modes: Explanation
- Auto-detect sample:
examples/connect.py - Feature cycle demo:
examples/features.py