Request for Help Capturing Codex Micro BLE Protocol Data

[jjggzhou]

What's the problem or use case?

Hi Eli! I’m building an open-source nRF52840/ZMK firmware compatible with the Codex Micro, and I was wondering if you could help me capture some BLE data from your real device. The most useful information would be the complete BLE HID Report Map (reportedly 216 bytes), the GATT/HIDS service and characteristic layout—including UUIDs, report IDs, handles, properties, CCC descriptors, and Report Reference values—and, if possible, a BLE packet capture showing pairing, connection, device.status communication, key/encoder/joystick events, and RGB commands. Raw exports from nRF Connect, Wireshark, btmon, or a BLE sniffer would be ideal, along with the Codex Micro firmware version and OS used for the capture. Please remove any device addresses, bonding keys, or other personal identifiers before sharing. Even just the complete Report Map would be extremely helpful. Thank you!

Proposed solution

No response

Area

None

[eliBenven]

Happy to help - this is exactly the kind of interop work FreeMicro documents. Captured from a real Codex Micro over Bluetooth Low Energy on macOS, firmware/HID version 0xB1 (177). No device address, serial, or bonding keys are included.

Complete HID Report Map (216 bytes)

The report descriptor macOS reports for the device, exactly 216 bytes as you'd heard:

05010906a1018501050719e029e71500250175019508810295017508810195057501
050819012905910295017503910195067508150025a40507190029a48100c0050c09
01a101850275109501150026ff0719002aff078100c00902a10185030901a1000509
19012905150025019505750181029501750381010501093009311581257f95027508
810609381581257f950175088106050c0a38021581257f950175088106c0c00600ff
0901a10185060902150026ff007508953f81020903150026ff007508953f91020904
150026ff007508953fb102c0

Decoded

Report ID 1  - Boot Keyboard (Generic Desktop / Keyboard)
  8 modifier bits, 1 reserved byte, 5 LED output bits + 3 pad,
  6-byte key array (usages 0x00-0xA4)

Report ID 2  - Consumer Control
  one 16-bit consumer usage (0x000-0x7FF)

Report ID 3  - Mouse (Generic Desktop / Pointer, Physical collection)
  5 button bits + 3 pad
  X, Y        (usages 0x30/0x31), signed 8-bit relative (-127..127)
  Wheel       (usage 0x38),       signed 8-bit relative
  AC Pan      (Consumer 0x238),   signed 8-bit relative

Report ID 6  - Vendor-Defined, Usage Page 0xFF00   <-- the real channel
  Input   (usage 0x02): 63 bytes, 0-255 each
  Output  (usage 0x03): 63 bytes
  Feature (usage 0x04): 63 bytes

HID-level facts (safe to share)

VendorID / ProductID	0x303A / 0x8360 (Espressif / Codex Micro)
Manufacturer / Product	Work Louder / Codex Micro
Transport	Bluetooth Low Energy
HID version	0xB1
Max Input/Output/Feature report	64 bytes each (report ID byte + 63 payload)
Primary usage	Generic Desktop / Keyboard (0x0001/0x0006)

The one thing that will save you the most time

The standard collections (keyboard RID 1, consumer RID 2, mouse RID 3) are present, but on this firmware the Agent keys, action keys, dial and joystick do not emit standard HID reports through them - the device delivers all of that, and accepts LED/RGB and device.status, over the vendor channel on Report ID 6 as a line-framed JSON-RPC protocol. That is fully documented here: https://github.com/eliBenven/freemicro/blob/main/docs/PROTOCOL.md (methods, key ids, the v.oai.* events, the effect enum, and the per-transport framing). Notably, over BLE the vendor reports use the 64-byte buffer with the 0x06 report id prefixed; USB is 63 bytes with no prefix. A write framed the USB way over BLE is accepted and silently dropped, which cost real debugging time.

So for a ZMK-compatible firmware you'll want to implement Report ID 6 and that JSON-RPC layer, not just the boot-keyboard collection - otherwise the host software (FreeMicro, and the vendor app) won't see keys.

What I could NOT capture on macOS, and how to get it

You also asked for the raw GATT layer - service/characteristic UUIDs, handles, CCC descriptors, Report Reference values - and an over-the-air packet capture. macOS claims HID-over-GATT devices at the system level and does not expose the underlying GATT to userland, so those are not reachable with the tools that produced the above. To get them you'll want either:

• an nRF52840 / TI BLE sniffer capturing over the air during pairing (this gives you the true ATT handles, CCC, and Report Reference descriptors), or
• macOS PacketLogger (Additional Tools for Xcode) during pairing, which logs HCI/ATT and will show the report-map read and the handle layout.

If a live example of a device.status round trip or an RGB command over the vendor channel would help, I can capture and paste those payloads - just say the word.

Good luck with the firmware, and please link it here when it's up.

[jjggzhou]

Thank you—this is extremely helpful and provides the key information needed to complete the BLE implementation, especially the exact 216-byte Report Map and the BLE-specific 64-byte Report ID framing.

The device.status and RGB examples documented in PROTOCOL.md are sufficient for the implementation, so there is no need to capture additional payloads right now. I’ll first update the ZMK firmware and validate the Report ID 6 JSON-RPC path. If the live BLE round-trip reveals any ambiguity, I may follow up for a raw example.

I’ll link the firmware here once the BLE compatibility work is ready. Thanks again for taking the time to capture and document this.

[jjggzhou]

Sorry for the confusion. Your previous response already provided enough information for us to begin implementing the BLE transport, especially the critical distinction that BLE uses a 64-byte buffer with Report ID 0x06 prefixed, while USB uses 63 bytes without that prefix. That is why I did not request an additional capture at the time.
We have now reached the hardware-verification stage. Our firmware pairs successfully with macOS, exposes the expected Report ID 6 vendor collection, and macOS completes the HID-over-GATT initialization. However, macOS is preventing our user-space HID tool from opening the BLE vendor collection, so we cannot independently verify an actual JSON-RPC round trip from this machine.
Could you please provide the live BLE vendor-channel payloads you offered for:
One complete device.status request and response.
If possible, one key-remapping command and its response. If a remapping capture is inconvenient, an RGB command and response would also work.
For each example, the most useful format would be:
The decoded JSON request and response
The exact raw HID report bytes in each direction
Individual 64-byte report boundaries if the JSON spans multiple reports
Confirmation of where the 0x06 Report ID appears
Whether trailing bytes are zero-padded
There is no need to provide the GATT handles, CCC descriptors, or Report Reference values, since you already explained that macOS does not expose those. We mainly need the official device’s BLE JSON-RPC framing as a reference for our final compatibility verification.
Thanks again, and sorry that I did not make the distinction between “enough to implement” and “useful for final verification” clear earlier.