# Protocol provenance

Protocol snapshot reviewed September 29, 2026; bridge packaging updated September 30, 2026. PointCast's optional bridge adapts the vendor HID framing and macOS IOKit calling pattern from **FreeMicro**, by Eli Benveniste, licensed under MIT. The upstream implementation is independent reverse engineering, not an official public hardware SDK. Its maintainer documents testing on one shipping Codex Micro with firmware 0.4.1. Normal room mode accepts that documented version. Firmware 0.6.2 requires explicit interactive visual qualification each time the bridge runs; the later primary implementation below supports that bounded test.

- [FreeMicro repository and verification caveats](https://github.com/eliBenven/freemicro)
- [Transport implementation: codex_micro.py](https://github.com/eliBenven/freemicro/blob/main/src/freemicro/device/codex_micro.py)
- [Lighting message builder: lighting.py](https://github.com/eliBenven/freemicro/blob/main/src/freemicro/device/lighting.py)
- [Renderer and competing-writer behavior](https://github.com/eliBenven/freemicro/blob/main/src/freemicro/renderers/micro_leds.py)
- [Protocol notes](https://github.com/eliBenven/freemicro/blob/main/docs/PROTOCOL.md)
- [Upstream license](https://github.com/eliBenven/freemicro/blob/main/LICENSE)
- [Official Work Louder Codex Micro setup](https://worklouder.cc/openai-micro-setup)

This bridge uses USB VID `0x303A`, PID `0x8360`, vendor report ID `6` and Output reports. Native USB buffers contain `[0x02][length][up to 61 bytes]` padded to 63 bytes. Native Bluetooth buffers additionally prefix `0x06`, producing 64 bytes. Compact JSON is CRLF terminated. `device.status` is the sole read-only request; `v.oai.thstatus` is the sole light notification and omits the outer RPC `id`.

Only one `thstatus` entry is emitted: key index 0–5, RGB color, brightness at or below 0.2, solid effect `e=1`, and `s=sk=sa=0`. No `rgbcfg`, device filesystem, persistence, preview, mapping, or firmware command is exposed. The upstream notes include older, contradictory observations about other lighting methods; this bridge does not use those methods.

Native IOKit transport is intentionally separate from browser WebHID. A working native USB status probe does not prove browser output framing or WebHID access. No WebHID compatibility claim is made.

The local read-only probe on September 29, 2026 returned firmware `0.6.2` over USB with a valid status response. This is recorded as **transport verified**. A later one-shot amber/idle test was accepted by the native HID write API, but no person has confirmed the visible physical result. Our bridge's lighting remains **visually unverified** in this record.


## Firmware 0.6.2 evidence

[libremicro 0.1.0](https://docs.rs/crate/libremicro/0.1.0), published September 1, 2026, is a separate community Rust implementation for Linux USB. It reports visually confirmed Agent Key lighting through `v.oai.thstatus` on firmware 0.6.2. Its [typed lighting source](https://github.com/uint4/libremicro/blob/master/src/lighting.rs) uses the same `id`, `c`, `b`, `e`, `s`, `sk`, `sa` fields and solid effect value 1. Its [lighting example](https://github.com/uint4/libremicro/blob/master/examples/lighting.rs) explicitly treats these writes as volatile and notes that prior light state cannot be restored. We use this source as protocol corroboration; its Linux transport is not included in this macOS bridge.

This evidence supports a bounded local qualification test. It is not a claim that our macOS bridge's physical light output has been visually verified. The qualification test can emit only spark and idle on exact firmware 0.6.2. The separate one-shot command never enables room playback. Guided room setup requires a live terminal and an explicit `yes` confirming amber followed by dim-white idle; only then does that running process enable the four bounded room modes. No qualification is persisted, and arbitrary firmware versions remain blocked.