# FreeMicro: decoding Codex Micro's USB and Bluetooth control protocol

> FreeMicro implements Codex Micro key input and LED output through the device's vendor HID protocol, linking six keys to Claude Code project states. Its protocol notes describe different USB and Bluetooth LE report framing, device commands, and observed input events, with Python code for device control.

- Type: Case study
- Targets: Protocol
- Category: Independent reconstruction cases
- Relationship: Independent reconstruction project
- Sources reviewed: 2026-11-06
- Added to the catalog: 2026-11-09
- Original resource: <https://github.com/eliBenven/freemicro>
- Primary source: <https://github.com/eliBenven/freemicro/blob/64258eb6cc3312a43f9f9f86d87e55e0b609ccc5/docs/PROTOCOL.md>
- Catalog page: <https://awesomerea.org/resources/freemicro-codex-micro-case/>
- Record JSON: <https://awesomerea.org/resources/freemicro-codex-micro-case/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/freemicro-codex-micro-case/index.md)

## Requirements & limits

- **Prerequisites:** A Codex Micro device, macOS, and Python 3.9+.
- **Scope:** The protocol observations are documented for a shipping unit with firmware v0.4.1.
- **License:** MIT license.

## Primary sources

1. <https://github.com/eliBenven/freemicro/blob/64258eb6cc3312a43f9f9f86d87e55e0b609ccc5/docs/PROTOCOL.md>
2. <https://github.com/eliBenven/freemicro/blob/64258eb6cc3312a43f9f9f86d87e55e0b609ccc5/README.md>

## More in Protocols

- [Mittzon Standing Desk: decoding the LIN bus for Home Assistant control](https://awesomerea.org/resources/mittzon-homeassistant-case/index.md) · Case study
- [zenvision-linux: reconstructing ASUS ZenVision OLED control over USB](https://awesomerea.org/resources/zenvision-linux-case/index.md) · Case study
- [orba-protocol: reconstructing Artiphon Orba 2 control messages](https://awesomerea.org/resources/orba-protocol-artiphon-orba-2-case/index.md) · Case study
- [TrikiEmu: reconstructing the Żabka Triki BLE controller](https://awesomerea.org/resources/trikiemu-zabka-triki-case/index.md) · Case study
- [TrikiScope: decoding the Żabka Triki BLE motion stream](https://awesomerea.org/resources/trikiscope-zabka-triki-case/index.md) · Case study
- [G2CC: a replacement Even G2 client built from Bluetooth traffic analysis](https://awesomerea.org/resources/g2cc-even-g2-client-case/index.md) · Case study

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.