Skip to content

TapSDK

Input-mode firmware entry point. Import with from tapsdk import TapSDK, or prefer connect() which returns TapSDK or TapSDK2 (use TapSDK2 docs when it returns TapSDK2).

Construction imports a platform BLE backend (macOS, Windows, or Linux). Creating TapSDK on an unsupported platform, or with the wrong Bleak pin, raises ImportError.

connect

from tapsdk import connect

sdk = await connect(address=None, *, skip_scan=False, **kwargs)

Attach to a Tap, detect firmware (c3ff000e present → TapSDK2), and return TapSDK or TapSDK2 with an already-connected client.

Parameter Description
address Optional BLE address / platform device id (same rules as the constructor)
skip_scan Windows only. If True, never falls back to a live BLE scan — only attaches to a Tap Windows already reports as connected/paired (via AEP) or an explicitly given address. Raises ConnectionError immediately instead of scanning and waiting. Ignored (no effect) on macOS/Linux.
**kwargs Forwarded to the SDK constructor (for example keepalive_timeout on TapSDK2)

Does not start notifications. Register callbacks, then await sdk.start().

Constructor

TapSDK(client=None, address=None)
Parameter Description
client Optional already-connected TapClient (from connect())
address Optional BLE address / platform device id. On Linux, if omitted, the SDK picks a connected device whose name starts with Tap.

Connection

async start()

Start GATT notifications on an already-connected client (for example after connect()). Raises ConnectionError if the client is not connected. Invokes the connection callback with self when notifications are armed.

async run()

Connect to a Tap (via shared connect_tap()) if needed, then call start().

  • Prefer an already OS-connected / paired device.
  • Otherwise scan until a Tap advertising the Tap service UUID is found.
  • On Windows, also polls for paired devices that reconnect without advertising.

Returns when setup finishes; it does not block forever. Keep the asyncio loop alive yourself.

Async context manager

TapSDK supports async with. The client is already connected when you enter the block. Exit calls client.disconnect().

async with await connect() as sdk:
    sdk.register_tap_events(on_tap)
    await sdk.start()

Use this on Windows so the GATT session closes when the block ends. See examples/connect.py and Windows BLE connect notes.

Commands

async set_input_mode(input_mode, identifier=None)

Write an input mode command to the device (NUS RX).

Parameter Description
input_mode Instance of InputModeText, InputModeController, InputModeControllerText, or InputModeRaw
identifier Reserved for multi-device use; currently unused

Starts periodic mode refresh on first call. Changing raw sensitivities while already in a different raw configuration is rejected with a warning.

async set_input_type(input_type, identifier=None)

TapXR Spatial Control only. Force mouse, keyboard, or automatic input selection.

Parameter Description
input_type InputType.MOUSE, InputType.KEYBOARD, or InputType.AUTO
identifier Reserved; currently unused

async send_vibration_sequence(sequence, identifier=None)

Send haptic on/off periods via the TapSDK UI characteristic.

Parameter Description
sequence List of integers (ms). Each value is clamped to 0–2550 and stored as value // 10. Max length 18.
identifier Reserved; currently unused

async get_device_info() -> DeviceInfo

Read public device information. Requires a bonded connection (DIS/BAS characteristics are encrypted on Tap firmware). Missing characteristics yield None for that field.

Returns a DeviceInfo dataclass:

Field Description
name Device name
fw_version Firmware revision
fw_version2 Secondary firmware version (None if absent)
model_version Model version as hex (e.g. 0x2A; None if absent)
hardware_revision Hardware revision
serial_number Serial number
manufacturer Manufacturer name
software_revision Bootloader revision on Tap
battery_level 0–100
from tapsdk import DeviceInfo

info = await tap_device.get_device_info()
print(info.name, info.fw_version, info.model_version, info.battery_level)

Event registration

All register_* methods are synchronous. Pass a callable; pass None is not required to clear (re-assign by registering again). See Events.

Method Callback signature
register_connection_events (tap_sdk)
register_disconnection_events (client) — Bleak disconnected callback
register_tap_events (identifier, tapcode)
register_mouse_events (identifier, vx, vy, proximity)
register_air_gesture_events (identifier, gesture)
register_air_gesture_state_events (identifier, mouse_mode)
register_raw_data_events (identifier, packets)

Attributes (runtime)

Attribute Meaning
client Underlying TapClient / BleakClient
input_mode Last requested InputMode instance
input_type Last requested InputType
mouse_mode Current MouseModes from air-gesture state notifications