tapwithus/tap-python-sdk/tap-build-an-app

Build an app with a Tap

The user may not be a developer. Keep the project small, explain how to run it in plain words, and test with the real device.

Workflow

1. Ask (only what is missing): device (Tap Strap / Tap Strap 2 / TapXR; TapBand uses the same API as TapXR and is coming soon), OS, and what the app should do.
2. Connect first. Run the tap-getting-started quickstart and confirm taps arrive before building anything else.
3. Pick the input (load the matching skill):

• finger taps and combos: tap-tapping
• swipes, pinches, fist: tap-vision-models
• pointer, tilt, rotation: tap-imu-motion
• twist-to-adjust value: tap-knob (TapXR developer firmware / TapBand)
• directions + select + drag/rotate: tap-dpad (TapXR developer firmware / TapBand)
• data recording: tap-raw-sensors

1. Pick the output (pattern below).
2. Build one interaction, test it with the user, then add the next.
3. Give feedback: haptics (send_vibration_sequence) and on-screen state, so the user knows the gesture was seen.
4. Deliver: one folder, a requirements.txt, and one run command (python app.py).

Core pattern: callbacks to a queue

SDK callbacks run on the Bluetooth path. Do not draw UI or do slow work in them. Put events on an asyncio.Queue and handle them in your own loop:

import asyncio
from tapsdk import (
    DeviceFeatures,
    InputModeController,
    ModelTypes,
    VisionSensorOpModes,
    connect,
)
def first(v):
    return v[0] if isinstance(v, (list, tuple)) else v
async def main():
    events = asyncio.Queue()
    sdk = await connect()
    sdk.register_tap_events(lambda i, t: events.put_nowait(("tap", first(t))))
    sdk.register_air_gesture_events(lambda i, g: events.put_nowait(("air", first(g))))
    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)
    while True:
        kind, code = await events.get()
        handle(kind, code)
asyncio.run(main())

Output patterns

Browser bridge (WebSocket)

# pip install websockets
import json, websockets
clients = set()
async def ws_handler(ws):
    clients.add(ws)
    try:
        await ws.wait_closed()
    finally:
        clients.discard(ws)
async def broadcast(event):
    msg = json.dumps(event)
    for ws in list(clients):
        await ws.send(msg)
# in main(): await websockets.serve(ws_handler, "localhost", 8765)
# in the loop: await broadcast({"kind": kind, "code": code})

<script>
  const ws = new WebSocket("ws://localhost:8765");
  ws.onmessage = (e) => { const ev = JSON.parse(e.data); /* update the page */ };
</script>

Serve the HTML with python -m http.server or open the file directly.

pygame (blocking loop)

pygame needs the main thread. Run the Tap SDK in a background thread with its own event loop and pass events through queue.Queue:

import queue, threading
q = queue.Queue()
threading.Thread(target=lambda: asyncio.run(tap_main(q)), daemon=True).start()
# in the pygame loop: while not q.empty(): handle(*q.get_nowait())

Rules

• Do not add dependencies to the SDK. Add them to the app's requirements.txt.
• Use a virtual environment (python3 -m venv .venv). Requires Python 3.10 or newer.
• Add a keyboard fallback (arrow keys, space) so the user can test the app without the Tap.
• Show connection status on screen ("Connecting...", "Connected", "Disconnected").
• macOS: Bluetooth permission for the terminal; Accessibility permission when sending keys.
• If the device does not connect, use the troubleshooting table in tap-getting-started.