Document BLE reconnect procedure and adapter recovery

ldraney commented

2026-06-07 02:44:39 +00:00

Owner

Summary

Fixed trust-before-pair order in pairing docs (was causing auth failures on re-pair)
Added troubleshooting guide: adapter dropout recovery, stale bond cleanup, re-pairing
Updated MAC to current value with note that BLE random addresses rotate on re-pair
Added .gitignore for .claude-no-enforce

Changes

README.md: updated MAC, added MAC rotation note, linked troubleshooting doc
docs/wireless-keyboard-2.md: corrected pairing order (trust before pair), single-session requirement, generic MAC in examples
docs/architecture.md: updated connection flow diagram to show trust before pair, updated MAC
docs/troubleshooting.md: new file — adapter dropout recovery (USB controller reset), re-pairing after reset, auth failure fixes, autosuspend diagnosis
.gitignore: added .claude-no-enforce

Test Plan

Verified pairing procedure works with corrected order (trust → pair → connect)
Verified USB controller reset brings back dropped adapter
Confirmed autosuspend fix applied after reset
No regressions — keyboard currently connected and stable

Review Checklist

Passed automated review-fix loop
No secrets committed
No unnecessary file changes
Commit messages are descriptive
Feature flag needed? No — documentation only

ldraney/keyboard #1 — Docs: incorrect pairing order and missing adapter recovery procedure

Closes #1

## Summary - Fixed trust-before-pair order in pairing docs (was causing auth failures on re-pair) - Added troubleshooting guide: adapter dropout recovery, stale bond cleanup, re-pairing - Updated MAC to current value with note that BLE random addresses rotate on re-pair - Added .gitignore for .claude-no-enforce ## Changes - `README.md`: updated MAC, added MAC rotation note, linked troubleshooting doc - `docs/wireless-keyboard-2.md`: corrected pairing order (trust before pair), single-session requirement, generic MAC in examples - `docs/architecture.md`: updated connection flow diagram to show trust before pair, updated MAC - `docs/troubleshooting.md`: new file — adapter dropout recovery (USB controller reset), re-pairing after reset, auth failure fixes, autosuspend diagnosis - `.gitignore`: added .claude-no-enforce ## Test Plan - [x] Verified pairing procedure works with corrected order (trust → pair → connect) - [x] Verified USB controller reset brings back dropped adapter - [x] Confirmed autosuspend fix applied after reset - [x] No regressions — keyboard currently connected and stable ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive - [ ] Feature flag needed? No — documentation only ## Related Notes - `ldraney/keyboard #1` — Docs: incorrect pairing order and missing adapter recovery procedure Closes #1

ldraney commented

2026-06-07 02:46:07 +00:00

Author

Owner

PR #2 Review

DOMAIN REVIEW

Tech stack: Documentation (Markdown, Mermaid diagrams, Bash code blocks). No application code -- this is a Bluetooth device registry/knowledge base.

Documentation quality:

The troubleshooting guide (docs/troubleshooting.md) is well-structured with clear symptom/cause/fix sections. Each issue has actionable commands.
The pairing order correction (trust before pair) is consistently applied across all three docs: wireless-keyboard-2.md, architecture.md (sequence diagram), and the new troubleshooting guide. No contradictions between documents.
The MAC address update (09:00 to 0A:00) is applied consistently in all four files that reference it.
The BLE random address rotation warning is placed where it matters: in the device table (README), device info table, pairing procedure, re-pairing section, and troubleshooting. Good coverage without being redundant.
The pairing procedure now correctly shows an interactive bluetoothctl session with agent NoInputNoOutput and default-agent set within the session, matching the requirement that agent registration does not persist across invocations.
The architecture sequence diagram correctly shows trust before pair, with the connect step simplified (no longer bundled with trust).

Mermaid diagrams: The sequence diagram in architecture.md correctly reflects the updated flow. Trust produces a Trusted: yes response before pair begins.

Bash code blocks: Commands in troubleshooting are correct Linux sysfs/PCI paths. The unbind/bind approach for xHCI reset is a standard Linux technique. The sudo bash -c wrapper is appropriate for the compound write operations.

Cross-references: All internal doc links use relative paths correctly (wireless-keyboard-2.md#working-method from within docs/). The README links use docs/ prefix. All consistent.

BLOCKERS

None. This is a documentation-only PR with no application code, no secrets, no credentials, and no security-sensitive changes.

NITS

Branch naming: Branch is fix/bluetooth-reconnect-docs but SOP convention is {issue-number}-{kebab-case-purpose} (e.g., 1-bluetooth-reconnect-docs). Not blocking for a docs repo, but worth aligning for consistency.
PR body "Related" section: The PR body uses ## Related Notes instead of the standard ## Related header from the PR template. Minor formatting difference. It does correctly reference ldraney/keyboard #1 and includes Closes #1.
PR body missing plan slug: The Related section does not reference a plan slug, which is expected per SOP. Acceptable for a small docs fix where no formal plan exists.
Hardcoded PCI address: The troubleshooting guide hardcodes 0000:00:14.0 for the xHCI controller. This is correct for archbox but a brief note that this address is host-specific would help if this knowledge base is ever referenced for other machines. Very minor -- the repo is explicitly scoped to archbox.
Hardcoded USB port: Similarly, 1-14 is hardcoded throughout. Same reasoning applies -- correct for this specific host.

SOP COMPLIANCE

Branch named after issue (fix/bluetooth-reconnect-docs vs expected 1-bluetooth-reconnect-docs)
PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related)
Related references plan slug (no plan slug -- acceptable for small docs fix)
No secrets committed
No unnecessary file changes (all 4 changed files are directly relevant to issue #1)
Commit messages -- PR title is descriptive and matches the work done
.gitignore addition is appropriate (.claude-no-enforce is a tooling artifact)

PROCESS OBSERVATIONS

Low change-failure risk: documentation-only changes with no deployable code.
The PR body is thorough -- Summary, Changes, Test Plan with verification checkboxes, Related with issue reference and Closes #1. This is above-average for a docs PR.
The test plan includes manual verification steps (confirmed pairing works, adapter reset works, keyboard connected and stable), which is appropriate for hardware documentation.

VERDICT: APPROVED

Clean documentation PR. The pairing order fix is correct and consistently applied across all affected documents. The new troubleshooting guide adds genuine operational value. Branch naming deviates from SOP convention but is non-blocking for a documentation repository.

## PR #2 Review ### DOMAIN REVIEW **Tech stack**: Documentation (Markdown, Mermaid diagrams, Bash code blocks). No application code -- this is a Bluetooth device registry/knowledge base. **Documentation quality**: - The troubleshooting guide (`docs/troubleshooting.md`) is well-structured with clear symptom/cause/fix sections. Each issue has actionable commands. - The pairing order correction (trust before pair) is consistently applied across all three docs: `wireless-keyboard-2.md`, `architecture.md` (sequence diagram), and the new troubleshooting guide. No contradictions between documents. - The MAC address update (`09:00` to `0A:00`) is applied consistently in all four files that reference it. - The BLE random address rotation warning is placed where it matters: in the device table (README), device info table, pairing procedure, re-pairing section, and troubleshooting. Good coverage without being redundant. - The pairing procedure now correctly shows an interactive `bluetoothctl` session with `agent NoInputNoOutput` and `default-agent` set within the session, matching the requirement that agent registration does not persist across invocations. - The architecture sequence diagram correctly shows trust before pair, with the connect step simplified (no longer bundled with trust). **Mermaid diagrams**: The sequence diagram in `architecture.md` correctly reflects the updated flow. Trust produces a `Trusted: yes` response before pair begins. **Bash code blocks**: Commands in troubleshooting are correct Linux sysfs/PCI paths. The `unbind`/`bind` approach for xHCI reset is a standard Linux technique. The `sudo bash -c` wrapper is appropriate for the compound write operations. **Cross-references**: All internal doc links use relative paths correctly (`wireless-keyboard-2.md#working-method` from within `docs/`). The README links use `docs/` prefix. All consistent. ### BLOCKERS None. This is a documentation-only PR with no application code, no secrets, no credentials, and no security-sensitive changes. ### NITS 1. **Branch naming**: Branch is `fix/bluetooth-reconnect-docs` but SOP convention is `{issue-number}-{kebab-case-purpose}` (e.g., `1-bluetooth-reconnect-docs`). Not blocking for a docs repo, but worth aligning for consistency. 2. **PR body "Related" section**: The PR body uses `## Related Notes` instead of the standard `## Related` header from the PR template. Minor formatting difference. It does correctly reference `ldraney/keyboard #1` and includes `Closes #1`. 3. **PR body missing plan slug**: The Related section does not reference a plan slug, which is expected per SOP. Acceptable for a small docs fix where no formal plan exists. 4. **Hardcoded PCI address**: The troubleshooting guide hardcodes `0000:00:14.0` for the xHCI controller. This is correct for archbox but a brief note that this address is host-specific would help if this knowledge base is ever referenced for other machines. Very minor -- the repo is explicitly scoped to archbox. 5. **Hardcoded USB port**: Similarly, `1-14` is hardcoded throughout. Same reasoning applies -- correct for this specific host. ### SOP COMPLIANCE - [ ] Branch named after issue (`fix/bluetooth-reconnect-docs` vs expected `1-bluetooth-reconnect-docs`) - [x] PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related) - [ ] Related references plan slug (no plan slug -- acceptable for small docs fix) - [x] No secrets committed - [x] No unnecessary file changes (all 4 changed files are directly relevant to issue #1) - [x] Commit messages -- PR title is descriptive and matches the work done - [x] `.gitignore` addition is appropriate (`.claude-no-enforce` is a tooling artifact) ### PROCESS OBSERVATIONS - Low change-failure risk: documentation-only changes with no deployable code. - The PR body is thorough -- Summary, Changes, Test Plan with verification checkboxes, Related with issue reference and `Closes #1`. This is above-average for a docs PR. - The test plan includes manual verification steps (confirmed pairing works, adapter reset works, keyboard connected and stable), which is appropriate for hardware documentation. ### VERDICT: APPROVED Clean documentation PR. The pairing order fix is correct and consistently applied across all affected documents. The new troubleshooting guide adds genuine operational value. Branch naming deviates from SOP convention but is non-blocking for a documentation repository.

ldraney force-pushed fix/bluetooth-reconnect-docs from f6ef23d6b3 to 29ef411818

2026-06-07 02:48:36 +00:00

Compare

ldraney added 1 commit

2026-06-07 14:10:37 +00:00

Fix udev rule priority: rename 50- to 99- to beat 60-autosuspend 9c60ae22aa

60-autosuspend.rules was overriding our rule back to power/control=auto,
causing the adapter to drop off the USB bus repeatedly. Rule must run
after priority 60 to win.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldraney added 1 commit

2026-06-07 14:16:55 +00:00

Add hwdb override as the real autosuspend fix 17a821db6a

The udev rule alone wasn't enough — hwdb flags the Intel 9560 with
ID_AUTOSUSPEND=1, and any udev re-evaluation (upower, state changes)
resets power/control back to auto. The hwdb override at
99-bluetooth-no-autosuspend.hwdb kills this at the source.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>