Docs: incorrect pairing order and missing adapter recovery procedure #1

New issue

Closed

opened 2026-06-07 02:44:25 +00:00 by ldraney · 0 comments

ldraney commented 2026-06-07 02:44:25 +00:00

Owner

Copy link

Type

Bug

Lineage

Standalone — no plan or project page.

Repo

ldraney/keyboard

What Broke

Pairing docs had the wrong command order (pair before trust) and used separate bluetoothctl invocations, which drops the agent registration. No documentation existed for recovering from adapter dropout (USB controller reset) or handling BLE MAC rotation on re-pair.

Repro Steps

1. BT adapter drops off USB bus (autosuspend or firmware glitch)
2. Reset USB controller to bring adapter back
3. Attempt to re-pair keyboard using documented procedure
4. Pairing fails with AuthenticationFailed or ConnectionAttemptFailed

Expected Behavior

Docs should provide correct pairing order (trust before pair) in a single bluetoothctl session, adapter recovery steps, and note that BLE random addresses rotate.

Environment

• Arch Linux, kernel 7.0.7-arch1-1
• bluez 5.86-6
• Intel 9460/9560 CNVi

Acceptance Criteria

• Pairing procedure corrected: trust before pair, single session
• Troubleshooting guide for adapter dropout and re-pairing
• MAC rotation documented — match by name, not hardcoded MAC

Related

None

### Type Bug ### Lineage Standalone — no plan or project page. ### Repo ldraney/keyboard ### What Broke Pairing docs had the wrong command order (pair before trust) and used separate `bluetoothctl` invocations, which drops the agent registration. No documentation existed for recovering from adapter dropout (USB controller reset) or handling BLE MAC rotation on re-pair. ### Repro Steps 1. BT adapter drops off USB bus (autosuspend or firmware glitch) 2. Reset USB controller to bring adapter back 3. Attempt to re-pair keyboard using documented procedure 4. Pairing fails with `AuthenticationFailed` or `ConnectionAttemptFailed` ### Expected Behavior Docs should provide correct pairing order (trust before pair) in a single `bluetoothctl` session, adapter recovery steps, and note that BLE random addresses rotate. ### Environment - Arch Linux, kernel 7.0.7-arch1-1 - bluez 5.86-6 - Intel 9460/9560 CNVi ### Acceptance Criteria - [ ] Pairing procedure corrected: trust before pair, single session - [ ] Troubleshooting guide for adapter dropout and re-pairing - [ ] MAC rotation documented — match by name, not hardcoded MAC ### Related None

ldraney referenced this issue from a pull request that will close it, 2026-06-07 02:44:39 +00:00

Document BLE reconnect procedure and adapter recovery #2

ldraney referenced this issue 2026-06-07 02:46:07 +00:00

Document BLE reconnect procedure and adapter recovery #2

ldraney closed this issue 2026-06-07 20:08:15 +00:00

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

init-docs

No results found.

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

ldraney/keyboard#1

No description provided.