Skip to content

Fix Windows connection issues - #56

Merged
ilouzl merged 9 commits into
masterfrom
windows_connection_issues
Oct 15, 2026
Merged

ilouzl merged 9 commits into
masterfrom
windows_connection_issues

Conversation

@ilouzl

@ilouzl ilouzl commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Improve Tap discovery and connection handling on Windows.
  • Recover connections to paired devices and handle advertising devices more robustly.

Test plan

  • Connect an already-connected, paired Tap that is not advertising.
  • Connect and pair an unpaired Tap that is advertising.
  • Disconnect and reconnect a paired Tap.

@ilouzl

ilouzl commented Sep 15, 2026

Copy link
Copy Markdown
Contributor Author

@odedtap Thanks for digging into this — I agree there is a real Windows regression after the Bleak 3 upgrade, but I think we can preserve the old behavior more elegantly and avoid relying on Bleak's private backend.

Before Bleak 3, the Windows path bypassed BleakClient.connect() and attached directly to the existing WinRT session because Bleak 0.22 could miss the already-fired GattSessionStatus.ACTIVE event. Bleak 3 now handles an already-active session, so the remaining problem appears to be the value passed into Bleak: master passes the full WinRT AEP id as a string, which makes Bleak perform an implicit scan. An already-connected Tap may not advertise, so that scan times out.

Suggested shape:

  1. Read the MAC from AEP DeviceAddress (already requested), with device-id parsing only as fallback.
  2. Construct a BLEDevice and pass it to TapClient, matching the macOS/Linux approach. This skips implicit discovery while staying on Bleak's public API.
  3. Call public connect() with one timeout and keep use_cached_services=False.
  4. Keep the improved Tap* name / UUID scan matching and pair=True for the unpaired advertising path.
  5. Remove the private _backend requester/session/service setup, the second watchdog, and the unbounded reconnect loop.

Could you confirm the hardware repro for both cases before we slim this down?

  • already-connected paired Tap that is not advertising
  • advertising unpaired Tap

If the first case still fails quickly with BLEDevice + public connect(), then a narrow WinRT attach fallback may be justified. I would avoid making that the default without that repro, since it duplicates Bleak internals and will be fragile across upgrades.

Mostly related to the order of scanning/retrieving devices.
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Docs check

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

This will properly release GATT objects on script exit.
@github-actions

Copy link
Copy Markdown
Contributor

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

Docs check

  • Status: NEEDS UPDATES
  • Affected quadrants: tutorial, how-to, reference, explanation
  • Gaps: docs/release-notes.md has no Unreleased entry for Fix Windows connection issues #56 (context manager, Windows connect fixes, skip_scan); docs/v1/reference/tapsdk.md and docs/v2/reference/tapsdk2.md omit connect(..., skip_scan=...) and async context-manager/__aenter__/__aexit__ cleanup; tutorials and connect how-tos still show sdk = await connect() with no disconnect while examples/connect.py now uses async with await connect() as sdk; user-facing Windows pairing / session-cleanup guidance lives only in docs/windows-ble-connect-notes.md, which is tracked and present but not in mkdocs.yml nav and is not linked from install or connection-model pages; docs/windows-ble-connect-notes.md ends mid-sentence and misstates examples/connect.py as try/finally: await sdk.client.disconnect() instead of the async context manager
  • Suggested edits: add a Bug fixes (and note the context-manager API) bullet under docs/release-notes.md ## Unreleased citing Fix Windows connection issues #56; document skip_scan and async with disconnect behavior in docs/v1/reference/tapsdk.md and docs/v2/reference/tapsdk2.md (and briefly in docs/reference/package.md for connect); update docs/v1/tutorial/getting-started.md, docs/v2/tutorial/getting-started.md, docs/v1/how-to/connect-and-listen.md, and docs/v2/how-to/connect-and-listen.md to match the async with cleanup pattern; add Windows pairing and clean-disconnect notes to docs/how-to/install.md and/or docs/v1/explanation/connection-model.md + docs/v2/explanation/connection-model.md (or link those pages to docs/windows-ble-connect-notes.md and add that page to mkdocs.yml if it should be published); finish the truncated last sentence in docs/windows-ble-connect-notes.md and align its examples/connect.py description with the current async-with code

@github-actions

Copy link
Copy Markdown
Contributor

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

Docs check

  • Status: NEEDS UPDATES
  • Affected quadrants: how-to, reference, explanation
  • Gaps: docs/windows-ble-connect-notes.md ends mid-sentence (“enabling bleak's own debug logging”); docs/v1/reference/tapsdk.md and docs/v2/reference/tapsdk2.md omit the new public async context manager (__aenter__ / __aexit__) that docs/release-notes.md and examples/connect.py already describe; docs/windows-ble-connect-notes.md links ../tapsdk/_transport.py (outside docs_dir) instead of a GitHub blob URL; docs/v1/explanation/index.md and docs/v2/explanation/index.md omit the Windows notes page that mkdocs.yml already lists
  • Suggested edits: Finish the last paragraph in docs/windows-ble-connect-notes.md; document async with await connect() as sdk: under Connection in docs/v1/reference/tapsdk.md and docs/v2/reference/tapsdk2.md; point the _transport.py link at a GitHub blob URL; add a Windows BLE connect notes row to both explanation index tables

@github-actions

Copy link
Copy Markdown
Contributor

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

Docs check

  • Status: NEEDS UPDATES
  • Affected quadrants: how-to, reference, explanation
  • Gaps: docs/windows-ble-connect-notes.md ends mid-sentence (If this recurs, the next diagnostic step is enabling bleak's own debug logging); docs/v1/reference/tapsdk.md and docs/v2/reference/tapsdk2.md omit the new async context manager API (__aenter__ / __aexit__, async with await connect() as sdk:) that the code, examples/connect.py, and docs/release-notes.md already describe; docs/v1/explanation/index.md and docs/v2/explanation/index.md do not list the new Windows notes page that mkdocs.yml already puts under Explanation
  • Suggested edits: Finish the last sentence in docs/windows-ble-connect-notes.md (and remove the informal “repo memory / session history” aside); add a short Connection subsection on async context manager use (disconnect on exit; useful on Windows) in docs/v1/reference/tapsdk.md and docs/v2/reference/tapsdk2.md; optionally show async with await connect() as sdk: in docs/v1/how-to/connect-and-listen.md and docs/v2/how-to/connect-and-listen.md; add a row for Windows BLE connect notes in both explanation overview tables

@github-actions

Copy link
Copy Markdown
Contributor

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

Docs check

  • Status: NEEDS UPDATES
  • Affected quadrants: how-to, reference, explanation
  • Gaps:
    • TapSDK2 adds public NUS API (write_nus_command, register_nus_raw_data_events, NUS notify in start()) but docs/v2/reference/tapsdk2.md and docs/v2/reference/events.md do not document it; the tapsdk2 intro still only says there is no NUS set_input_mode path
    • docs/release-notes.md Unreleased omits the v2 generic NUS feature (commit “Generic NUS support for the v2 API”)
    • TapSDK / TapSDK2 async context managers (__aenter__ / __aexit__) are in release notes and examples/connect.py, but not in docs/v1/reference/tapsdk.md, docs/v2/reference/tapsdk2.md, or the connect how-tos
    • docs/windows-ble-connect-notes.md ends mid-sentence after “enabling bleak's own debug logging”
  • Suggested edits:
    • docs/v2/reference/tapsdk2.md: document write_nus_command and register_nus_raw_data_events; note that NUS is generic raw RX/TX (not v1 input modes); list async context-manager support
    • docs/v2/reference/events.md: add register_nus_raw_data_events with callback shape (sender, packets) (packets from parsers.raw_data_msg)
    • docs/release-notes.md: add an Unreleased main-feature bullet for v2 generic NUS write/notify
    • docs/v1/reference/tapsdk.md and docs/v2/reference/tapsdk2.md (and optionally docs/v1/how-to/connect-and-listen.md / docs/v2/how-to/connect-and-listen.md): document async with await connect() as sdk: disconnect-on-exit, matching examples/connect.py
    • docs/windows-ble-connect-notes.md: finish the last sentence (or remove the incomplete line)
    • Optional: add Windows BLE connect notes to docs/v1/explanation/index.md and docs/v2/explanation/index.md (already in mkdocs.yml nav)
    • Verified present (tracked + on disk): docs/windows-ble-connect-notes.md, docs/assets/TAP-axis-alpha.png, docs/assets/TAPXR-axis.png. No missing assets. Readme.md unchanged is fine for this PR.

Keep both Unreleased notes. Fix flake8 E203 in the Windows address parser. Document the v2 NUS API and the async context manager.

Co-authored-by: Liron Ilouz <ilouzl@users.noreply.github.com>
Comment thread tapsdk/tap2.py Resolved
NUS communication implementation to be done using inheritence with a private SDK class.
@github-actions

Copy link
Copy Markdown
Contributor

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

Docs check

  • Status: NEEDS UPDATES
  • Affected quadrants: how-to, reference, explanation
  • Gaps: docs/v2/reference/tapsdk2.md, docs/v2/reference/events.md, and docs/release-notes.md document TapSDK2 APIs write_nus_command / register_nus_raw_data_events and NUS notify on start(), but tapsdk/tap2.py has no such methods after the NUS commit was reverted. Windows connect docs (skip_scan, async context manager, docs/windows-ble-connect-notes.md, install / connect-and-listen / connection-model) match the code; that page is tracked and present; mkdocs.yml nav is correct; Readme.md needs no change for Diátaxis.
  • Suggested edits: Remove the NUS intro, “Nordic UART Service (NUS)” section, and register_nus_raw_data_events row from docs/v2/reference/tapsdk2.md. Remove the NUS section from docs/v2/reference/events.md. Delete the Unreleased NUS bullet from docs/release-notes.md. Keep the Windows / skip_scan / context-manager material as written.

Commit db1cd9e deleted write_nus_command and register_nus_raw_data_events. The reference pages, release notes, AGENTS.md, and the raw-sensors skill still described them.

Co-authored-by: Liron Ilouz <ilouzl@users.noreply.github.com>
@ilouzl
ilouzl marked this pull request as ready for review October 15, 2026 09:57
@ilouzl
ilouzl merged commit 8122a99 into master Oct 15, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants