Unify v1/v2 SDK over shared connect()

[ilouzl]

Summary

• Add TapSDK2 (framed v2 protocol) alongside existing TapSDK, plus encoder/parsers/features needed for v2 devices.
• Share BLE transport (tapsdk._transport), protocol detect (c3ff000e → v2), and DeviceInfo across both SDKs.
• New await connect() factory returns TapSDK or TapSDK2; register callbacks then await start(). Docs + examples/connect.py updated.

Closes #36

Test plan

• pytest + flake8 green on CI
• Run examples/connect.py on a v1 TapXR — expect Protocol: v1, device info, taps in controller mode
• Run examples/v2.py / connect() on a v2 device — expect Protocol: v2
• Confirm set_input_mode / set_input_type HID semantics still match docs (Text/ControllerText = HID; Controller + KEYBOARD = SDK taps, no HID)
• Merge with a merge commit (no squash)

Made with Cursor

[github-actions]

Docs check

• Status: OK
• Affected quadrants: tutorial, how-to, reference, explanation
• Gaps: none
• Suggested edits: none

[github-actions]

Workflow run: https://github.com/TapWithUs/tap-python-sdk/actions/runs/30809935445

Docs check

• Status: NEEDS UPDATES
• Affected quadrants: tutorial, how-to, reference, explanation
• Gaps: docs/tutorial/getting-started.md expected tap output/tapcode shape is v1-only (tapped 5 as an int) while await connect() can return TapSDK2, which passes a one-element list ([5]) — already stated in docs/reference/events.md but not in the tutorial happy path; docs/reference/package.md / docs/reference/enumerations.md omit that ImuAcclSensitivity is re-exported from tapsdk (it is in tapsdk/__init__.py); docs/explanation/input-modes.md never mentions that v2 has no input modes / uses DeviceFeatures
• Suggested edits: In docs/tutorial/getting-started.md (and briefly in docs/how-to/connect-and-listen.md preferred/v2 tap examples), note v1 tapcode is an int and v2 is [tapcode], and adjust the sample line accordingly; add ImuAcclSensitivity to the public-import table / re-export sentence in docs/reference/package.md and docs/reference/enumerations.md; add a short v2 cross-link in docs/explanation/input-modes.md to DeviceFeatures / docs/how-to/use-v2-features.md. Assets docs/assets/TAP-axis-alpha.png and docs/assets/TAPXR-axis.png are present and tracked — not missing.

[github-actions]

Workflow run: https://github.com/TapWithUs/tap-python-sdk/actions/runs/30822789192

Docs check

• Status: NEEDS UPDATES
• Affected quadrants: tutorial, how-to, reference, explanation
• Gaps: docs/how-to/use-spatial-control.md is still written as if every SDK instance supports set_input_type and register_air_gesture_state_events; those APIs exist only on v1 TapSDK (NUS), not on TapSDK2 returned by connect()
• Suggested edits: In docs/how-to/use-spatial-control.md, add a v1/TapSDK scope note (same pattern as switch-input-modes.md / stream-raw-sensors.md): Spatial Control uses TapSDK.set_input_type and v1 air-gesture state callbacks; for v2 use DeviceFeatures / UnifiedAirGestures paths instead (or state that Spatial Control is v1-only)

[ilouzl]

This also closes #49 on the sdk side.
A fw fix will be published separately.

[github-actions]

Workflow run: https://github.com/TapWithUs/tap-python-sdk/actions/runs/30904844266

Docs check

• Status: NEEDS UPDATES
• Affected quadrants: tutorial, how-to, reference, explanation
• Gaps: docs/how-to/send-haptics.md still says periods are clamped to 10–2550, but TapSDK.send_vibration_sequence / TapSDK2.set_haptic_pattern encode with max(0, min(255, d // 10)) (0–2550 ms). Same-PR reference pages already say 0–2550.
• Suggested edits: In docs/how-to/send-haptics.md, change the clamp wording to 0–2550 (keep 10 ms steps / period // 10) so it matches docs/reference/tapsdk.md, docs/reference/tapsdk2.md, and the code.

[github-actions]

Workflow run: https://github.com/TapWithUs/tap-python-sdk/actions/runs/30906566009

Docs check

• Status: NEEDS UPDATES
• Affected quadrants: tutorial, how-to, reference, explanation
• Gaps: docs/tutorial/getting-started.md first-run sample no longer enables tap delivery on v1 (removed set_input_mode(InputModeController())) while still telling the reader they should see tap lines; text admits Text-mode silence but the sample is not a reliable Diátaxis happy path. Same sample also omits v2 DeviceFeatures.MODEL_DETECTION, which how-tos / examples/v2.py enable before expecting model/tap events. docs/how-to/install.md documents Darwin/Windows Bleak pins but not Linux after setup.py raised Linux to bleak==0.12.1. docs/how-to/send-haptics.md still says periods are clamped to 10–2550; code and docs/reference/tapsdk.md use 0–2550. Assets docs/assets/TAP-axis-alpha.png and docs/assets/TAPXR-axis.png are present (tracked + on disk).
• Suggested edits: In docs/tutorial/getting-started.md, after await sdk.start(), branch: v1 → await sdk.set_input_mode(InputModeController()); v2 → await sdk.set_feature(DeviceFeatures.MODEL_DETECTION, True) (and import those symbols). In docs/how-to/install.md Linux section, note bleak==0.12.1 (same as Darwin). In docs/how-to/send-haptics.md, change the clamp range to 0–2550 to match code/tapsdk.md.