Skip to content

tapsdk.md

Latest commit

 

History

History
128 lines (88 loc) · 4.8 KB

tapsdk.md

File metadata and controls

128 lines (88 loc) · 4.8 KB
Raw

TapSDK

v1 protocol entry point. Import with from tapsdk import TapSDK, or prefer connect() which returns TapSDK or 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, **kwargs)

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

Parameter Description
address Optional BLE address / platform device id (same rules as the constructor)
**kwargs Forwarded to the SDK constructor (for example keepalive_timeout on v2)

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.

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 v1 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