The Keyboard Hung Up on the Mac: Chasing a Zephyr BLE Bug with Claude Code
My daily-driver keyboard sometimes drops off Bluetooth for a couple of seconds. It’s rare, it’s random, and I can’t make it happen on demand. By the end of this, two log lines had named a bug in Zephyr’s Bluetooth controller, and a fix was already sitting upstream.
(I used AI assistance writing this post — why)
The drop
My daily driver these days is the mesa3w, which runs Zephyr on an nRF52840 and talks to my Mac over Bluetooth Low Energy. Every so often it drops off the connection for about two seconds. If I happen to be holding a key down when that happens, the key can auto-repeat.
It doesn’t happen often, there’s no pattern to when it happens, and I have no way of making it happen. That is the worst kind of bug to chase. You can’t sit there and poke at it; you can only wait for it to show up again and hope you were collecting the right information when it did.
Groundwork
This part happened in earlier sessions, so I’ll keep it brief.
The Mac’s side. macOS’s bluetoothd keeps a log that can be read after the fact with log show. It recorded each drop as reason 708, which is a supervision timeout: the Mac stopped hearing from the keyboard for long enough that it gave up on the link. That points at radio loss, or at the keyboard rebooting.
The keyboard’s side. At my direction, Claude had added a console ring buffer to the firmware, which I can read over BLE with keyminder console. That means I can see what the keyboard logged without hooking up a J-Link, which matters when the event I care about happened hours ago while I was just typing.
Ruling things out. Some of the drops turned out to be my own doing: keyminder upgrade reboots the keyboard, and those reboots look like drops from the Mac’s side.
None of the rest of this would have been possible without the console. With no visibility into the device, there’s nothing to debug.
The first real clue: 0x24
The next time it dropped, I pulled the keyboard’s log and pasted it in:
Disconnected ... 0x24 BT_HCI_ERR_LMP_PDU_NOT_ALLOWED
No reboot. The keyboard had stayed up and simply lost the connection, with a reason code I’d never seen.
Matching the logs. Claude went to the Mac’s bluetoothd log for the same moment. The Mac logged its 708 two seconds after the keyboard logged its 0x24, and its last 30 connection events before that show only “No-Sync”: the Mac was listening, and nothing was coming back.
Reading the source. Claude then worked through Zephyr’s Bluetooth controller source, the ull_llcp*.c files that implement the Link Layer Control Protocol. LLCP is how the link layers at the two ends of a connection talk to each other about the connection itself: changing parameters, updating the channel map, pinging, encryption, and so on. 0x24 means the keyboard’s own link layer received one of these control packets and decided it was out of place. When that happens, the controller cuts the link right there. It doesn’t send a terminate first, so all the Mac sees is silence.
The new reading. That flips the story around. The “radio loss” drops weren’t radio loss at all. The keyboard was hanging up on the Mac, without saying goodbye. The two-second gap is just the Mac’s supervision timeout running out before it notices.
Being honest about the limits. Claude was clear that neither log could tell us which packet the keyboard had objected to. It named LE Ping as a suspect, but pointed out that one drop isn’t a pattern.
Adding instrumentation
So Claude proposed patching the Zephyr controller to record what triggered the 0x24. I said go ahead.
One wrapper. There are 11 different places in the controller that can raise 0x24. Rather than touch each of them, Claude turned ull_cp_rx(), the function that handles incoming control packets, into a wrapper around the original code. Before handing a packet on, the wrapper saves the opcode, the first few payload bytes, the connection event counter, and the state of both the local and the remote procedure. It only keeps that record if the packet ends up terminating the link with 0x24. That covers all 11 sites without modifying any of them.
The app side. A small accessor exposes the saved record, and the disconnected() callback in my firmware, jolt, logs it as two LLCP ... lines. Those land in the console ring buffer along with everything else.
A Kconfig gotcha. The first build silently set the new option to n. Claude had put it inside the controller’s “Advanced features” menu, which is hidden, so setting it in my config did nothing. Claude caught this from the build warning and moved the option somewhere it could actually be turned on.
Commits. Claude committed in both repos: with jj in Zephyr, as I’d asked, and with git in jolt. It also told me plainly what hadn’t been tested yet.
All of that took about ten minutes. This is code I’d otherwise have spent an evening just learning my way around before I could write a line of it.
The next morning: two drops, identical records
By the next morning, the keyboard had dropped twice. Both drops logged the same record:
- opcode 0x13, which is
LL_PING_RSP - local procedure: LE Ping
- remote procedure: Channel Map Update
- both procedures “want 0xff”
Two drops, identical records. That’s the pattern the single 0x24 couldn’t give us.
Decoding the numbers. Claude decoded these against the controller’s enums, and then traced back through the code to work out why the ping had stopped expecting its own reply. It came down to a chain of five things:
- Five seconds after connecting, the keyboard asks the Mac for a connection interval of 9–12 ms with a peripheral latency of 30.
- macOS always rejects that. Every time,
bluetoothdlogs “Rejecting following parameters: min=9…”. - When the central rejects a peripheral’s parameter request, the peripheral side of Zephyr’s controller never clears its
incompatflag. It stays set for the rest of the connection. - Later, the Mac sends a channel map update while a ping from the keyboard is still waiting for its reply. Because of that stale flag, the controller wrongly treats this as two procedures colliding, and clears the state the ping was waiting on.
- The ping reply arrives, matches nothing the controller is expecting, and the link is dropped with 0x24.
This also explains why the drops are rare. Steps 1 through 3 happen on every connection, but step 4 needs a channel map change to land in the short window while a ping exchange is in flight.
The twist: it was already fixed upstream
By this point Claude had worked out both the cause and the fix: reset incompat when the central rejects the peripheral’s parameter request, the same way the central-side path already does.
Before writing that patch, though, it fetched upstream Zephyr and diffed just the files it had narrowed things down to. There it found commit 3e297898e50, “Reset incompat on rejected peripheral CPR”, from about three weeks earlier. It makes the same change Claude was about to make. And its commit message describes my exact case:
Observed with a macOS central … the link dropped whenever a channel map update overtook an LL_PING_RSP.
Claude brought that commit into my local Zephyr stack with jj duplicate and built a new firmware image. That whole second round, from reading the two log lines to having a fixed image, took about three minutes.
I find it reassuring that this went the way it did. An independent diagnosis that lands on the same fix as upstream is a good check on both of them: two separate lines of reasoning are unlikely to arrive at the same change if the reasoning behind them were wrong. Using the upstream commit instead of our own patch also brought its unit tests along, including a collision test for this exact sequence.
What made Claude useful here
Two logs at once. It read the Mac’s logs and the keyboard’s logs together and lined up the timestamps. That’s what turned a 708 on one side and a 0x24 on the other into a single event.
Unfamiliar code. It read through a large state machine I didn’t know, quickly, and turned a vague error code into a specific hypothesis.
Measuring instead of guessing. When the logs ran out, it proposed instrumentation rather than a guess, and kept the patch small: one wrapper rather than 11 edits.
Honest reporting. All the way through, it was clear about what was known, what was a guess, and what had been built but not yet tested.
Small cleanups it caught on its own. The Kconfig visibility trap, a wrapped symbol name in a comment, a commit identity, and a missing Signed-off-by. None of these are interesting, and all of them are the sort of thing that costs time when they’re missed.
Memory across sessions. This played out over several sessions and several days. The notes from earlier sessions carried the context forward, so each new session started from what we’d already learned, instead of from “my keyboard sometimes disconnects.”
Lessons and loose ends
An error code reported only on the far side can hide the real cause on the near side. The Mac’s 708 said “I lost the keyboard,” which was true and told me nothing. The cause was the keyboard’s 0x24. Get logs from both ends.
When an embedded stack hides its state, a small diagnostic hook is worth flashing. One night of waiting with the hook in place got further than more staring at the source would have.
Check upstream before writing your own fix, even once you’re sure of it. Especially once you’re sure of it.
Still open:
- It’s been a few days on the new image, 0.1.0+18, without any drops so far. Given how rare they were, it will take longer before I can say with confidence that they’ve stopped.
- I may set
CONFIG_BT_PERIPHERAL_PREF_MIN_INT=12, so the keyboard stops making a request that macOS always rejects. With the fix in place it shouldn’t matter, but there’s no point in asking for something I know I won’t get. - I’m not planning to send the diagnostic hook upstream as it is. It did its job, but it’s a bit of a hack, and I doubt it would be accepted. If I come back to it, it would need reworking into something cleaner first.