A non-invasive teardown of the Work Louder Creator Micro 2 sold as the Codex Micro—and the story of turning its keys, joystick, dial, Bluetooth link, and lighting into an interface for our own software.

The first experience was not futuristic. The device paired, charged, and lit up, but its most interesting controls did not behave like ordinary keys. A host watching for keyboard shortcuts could see a connected product and still miss the Agent buttons, dial, and joystick entirely. For a $250 control surface, that creates a blunt question: did we buy a beautiful remote for one approved application, or a piece of hardware we could make genuinely ours?

The answer arrived in a 63-byte HID report.

Editorial illustration—not evidence. This image imagines the six translucent keys as addresses into parallel software work. Exact-unit photographs, captures, and measured protocol claims are identified separately below.

Behind the keyboard-shaped surface is a vendor-defined channel carrying framed, CRLF-terminated JSON. A shipping unit running firmware v0.4.1 publishes structured control events on that channel, and it accepts status and lighting messages in return. On macOS, a small clean-room IOKit client can speak to it directly over Bluetooth or USB without treating either ChatGPT or Work Louder Input as a required intermediary.

The first successful device.status reply changed the investigation. The device was no longer a collection of mystery buttons; it was one end of a two-way control loop. Thirteen switch positions, encoder turns, and full-range joystick motion could enter our software. Battery, profile, worker state, and authorization state could come back out as light.

The final live test made that loop tangible. A two-key chord turned the whole device yellow. A second chord turned it red. The wide key captured the spoken instruction “Run LS.” A deliberately narrow one-job authorization launched a native DSCO worker, consumed itself, and returned the device to calm green. Every important transition was visible before the consequential action ran.

That is the larger story of this teardown: not how to add more macros, but how to turn a small illuminated object into an operator console. The same building blocks support six resumable agent slots, creative and spatial controls, a game/simulator adapter, or the physical front end for any local service that can consume a JSON Lines event stream.

The investigation follows three questions in order: what the exact device really exposes, how to control it without crossing unsafe firmware boundaries, and what becomes possible once physical intent and software state share the same loop.

Scope and safety. This was a non-invasive investigation. No enclosure was opened. No bootloader was entered. No firmware was flashed. No factory reset, self-test, charger diagnostic, or device-filesystem mutation was performed. Device identifiers and machine-specific details are excluded from this public account.

Before the teardown: what counts as proof

Reverse engineering gets unreliable when a fact observed in one version is quietly promoted into a claim about another. This investigation uses explicit provenance throughout:

The nearest downloadable firmware was v0.4.0; the live unit reported v0.4.1. Static discoveries from v0.4.0 are therefore described as v0.4.0 facts. They are not silently attributed to the live firmware.

What we proved without opening the case

The strongest findings are already enough to establish an open integration path:

The important conclusion is not that the device happens to have colorful lights. It is that the input, state, and feedback paths form a real two-way control loop.

The path to that conclusion began with a less glamorous problem: deciding what the object actually was. Its chassis, host identity, sales listing, and firmware do not use one consistent name.

Discovery 1: one device, five identities

The naming is confusing because each layer describes a different part of the product stack:

The physical label, operating-system identity, commercial SKU, and firmware project name are related, but they are not interchangeable. In particular, kbd-1.0-codex-micro is not what the hardware broadcasts to macOS.

This matches the public product story. OpenAI describes the device as a collaboration with Work Louder, while Work Louder's Creator Micro setup guide documents three Bluetooth host slots and a fourth wired mode.

That mode distinction matters in practice. Plugging in a USB cable while a Bluetooth slot remains selected can charge the battery without moving control traffic to USB. A lit, charging device is not necessarily a USB-connected device. The touch/profile control must select wired mode when USB data is the goal.

Once those identities were separated, the next task was to ignore the movable legends and map the physical surface itself.

Discovery 2: the keycaps hide thirteen switches

Provenance: exact-unit live for the event IDs and behavior; official product documentation and public-image analysis for subsystem context.

The Codex layout contains 13 mechanical switch positions:

top:       [dial]      [AG00] [AG01] [joystick]
middle:                [AG02] [AG03] [AG04] [AG05]
actions:   [ACT06]     [ACT07] [ACT08] [ACT09]
bottom:    [touch]     [===== ACT10 + ACT11 =====] [ACT12]

The six AG00–AG05 positions are the translucent Agent keys. The seven ACT06–ACT12 positions are action switches. The printed caps can be moved, so software should bind physical IDs first and treat the cap legend as editable metadata.

The large bottom key deserves special treatment. Its one visible cap spans two mechanical switches, ACT10 and ACT11. On the measured unit, one press closed the switches 3 milliseconds apart and released them 2 milliseconds apart. A naive application will perform the same action twice. A correct bridge maps both sources to one logical control and keeps that control pressed until both sources have released.

The rotary encoder has three identifiers: ENC_CW, ENC_CC, and ENC_CLK. The press is an ordinary down/up control. Turns are momentary edge events. On the measured firmware they arrived with act:2 and no corresponding release, so filtering every action for act == 1 discards the dial entirely.

The planar joystick uses a separate notification and publishes normalized polar coordinates. Live capture reached distance 1.0 in four directions and returned to exactly angle:0.0, distance:0.0 at center. The experiment did not label physical direction order, so angle-zero orientation, rotation direction, dead zone, quantization, and sample rate remain calibration questions for the host.

The lower-left touch control is different again. It selects the transport/profile slot and available evidence places its activity on a standard HID path rather than the vendor notification stream. Its exact report has not yet been decoded.

There is also no evidence yet for host-controllable haptics. The official specification identifies a touch sensor, and the public v0.4.0 image contains touch-input and self-test machinery, but neither a vibration actuator nor a haptic-output RPC was found. “Haptic pad” is therefore not a confirmed hardware claim.

The control map raised the next question: which of those signals actually reaches the host, and does it arrive the same way over a cable and over radio?

Discovery 3: USB and Bluetooth are not the same device

Provenance: exact-unit live descriptors.

Over USB, macOS enumerated a USB 2.0 full-speed HID device with a 500 mA power allocation. Its 275-byte report descriptor contains several top-level collections:

Report 4 is a substantial standard gamepad declaration: six signed axes, a hat switch, and 32 buttons. Its presence proves that the USB descriptor can describe a conventional game controller. It does not prove that the factory Codex profile actively populates those fields.

The BLE descriptor is smaller—216 bytes—and contains Reports 1, 2, 3, and 6. It omits the USB gamepad Report 4 and adds a 63-byte Feature item to Report 6. That difference has an immediate consequence: software using the Codex profile should not expect a native BLE gamepad identity merely because USB advertises one.

The Agent keys, action switches, encoder, and joystick observed in this study arrived through Report 6 rather than as ordinary keyboard scancodes. That explains the familiar “it is connected but does nothing” failure mode: a host waiting only for keys will never see the structured event stream.

The descriptor answered where to look. Report 6 answered how the product actually talks.

Discovery 4: Report 6 is a tiny message bus

Provenance: exact-unit descriptor and live BLE round trip; exact-unit host captures plus independent v0.4.1 corroboration for the protocol.

The vendor collection uses HID Report ID 6 on usage page 0xFF00. Inside its 63-byte payload, messages are split into chunks with a simple header:

[0x02 message-chunk opcode] [chunk length] [up to 61 JSON bytes] [zero padding]

Complete messages end with CRLF. A long JSON object continues across multiple reports and is parsed only after reassembly.

The easy-to-miss detail is that USB and BLE require different output buffers.

USB sends 63 bytes:

[0x02] [length] [up to 61 bytes] [padding]

BLE sends 64 bytes with the report ID included in the buffer:

[0x06 report ID] [0x02] [length] [up to 61 bytes] [padding]

The report-ID argument passed to IOHIDDeviceSetReport remains 6 in both cases. In other words, BLE needs the identifier twice: once as the API argument and once at byte zero of the output buffer.

This is more than a formatting nicety. An incorrectly framed BLE call can still return kIOReturnSuccess; that proves only that macOS accepted the write. The firmware may silently discard it. The only meaningful health check is an actual round trip: send device.status, wait for a response carrying the same request ID, and reject the connection if it times out or returns the wrong shape.

A compact request expands to the following structure for readability; it can be minified before framing on the wire:

{
  "m": "device.status",
  "p": {},
  "id": 1
}

On the live device, a direct BLE exchange returned firmware v0.4.1 plus active profile, active layer, battery percentage, and charging state. Those power values are point-in-time telemetry; the significant fact is that bidirectional communication succeeded.

The independent FreeMicro protocol documentation describes the same v0.4.1 transport distinction and the same need for a genuine status response. That is useful corroboration, not a substitute for the exact unit measurements above.

The status round trip proved the channel was bidirectional. Listening to it while operating every control revealed the vocabulary flowing in the other direction.

Discovery 5: the controls publish structured events

The main switch notification is compact JSON:

{
  "m": "v.oai.hid",
  "p": {
    "k": "AG02",
    "act": 1,
    "ag": 2
  }
}

For normal switches, act:1 means down and act:0 means up. The k field is the stable physical identifier; ag carries the Agent index when relevant. All six Agent positions and all seven action-switch positions produced clean down/up pairs during exact-unit BLE capture.

Joystick messages use a second method:

{
  "m": "v.oai.rad",
  "p": {
    "a": 0.42,
    "d": 0.78
  }
}

Applications should preserve the raw angle and distance and apply their own coordinate convention, dead zone, and response curve. Converting immediately to four arrow keys throws away most of the useful signal.

The cleanest host architecture separates four stages:

HID report
  -> transport-specific frame decoder
  -> CRLF JSON message reassembly
  -> event normalization
  -> application policy and actions

That separation prevents Bluetooth framing quirks, switch debouncing, or a future firmware event from leaking into every downstream integration.

At this point the live device had already established the integration path. The public firmware image was useful for a different reason: it supplied an architectural map of the platform underneath, without pretending to be the exact software running on the desk.

Discovery 6: the public firmware reveals the platform underneath

Provenance: official public v0.4.0 image only.

Work Louder publishes firmware binaries in its cm-v2-fw-releases repository. The v0.4.0 merged image used for this study matched its published SHA-256 digest before analysis.

Its ESP image header identifies an ESP32-S3 target: magic 0xE9, chip ID 0x0009, four application segments, project cm-v2-fw, and an embedded ESP-IDF 5.3.2 lineage. Strings and structures identify NimBLE, native USB HID, LittleFS, the keymapper, rotary encoder, joystick, touch input, SPI-driven LED strips, and a substantial battery and power-management subsystem.

The partition table is especially informative:

0x00F000  phy_init    4 KiB
0x010000  factory     8 MiB application
0x810000  nvs       128 KiB
0x830000  fs          2 MiB LittleFS
0xA30000  coredump   64 KiB

There are no A/B OTA application slots in that actual table. Generic ESP-IDF text elsewhere in the image can mention OTA, but a parsed partition entry is stronger evidence than an SDK string. For v0.4.0, the layout points to one factory application updated through a bootloader or merged-image workflow, without an on-device A/B rollback slot.

That finding is one reason not to experiment casually with undocumented update or storage calls. It says nothing definitive about a host-side recovery tool, and it does not prove that v0.4.1 has an identical table, but it raises the cost of being wrong.

Other v0.4.0 subsystem evidence includes:

• a MAX77972 charger/fuel-gauge and battery guard;
• TURBO, NORMAL, ECO, STANDBY, and SLEEP power recipes;
• rear-button standby, wake, battery animation, and factory-reset handling;
• self-test paths for keys, encoder, touch, rear button, and battery; and
• lighting effect names for off, solid, snake, rainbow, breath, gradient, and shallow breath.

These are firmware-image facts, not a board-level bill of materials for the v0.4.1 unit. Confirming the exact PCB, component population, GPIO routing, antenna, and LED topology still requires a physical teardown.

A useful protocol needs a hard safety boundary

Static discovery in v0.4.0 reveals both useful and dangerous method families. Some were then tested read-only or reversibly on the live v0.4.1 device.

A generic “send any RPC” command would erase the value of that classification. The clean-room probe therefore has no arbitrary-RPC escape hatch. Bootloader entry and filesystem mutation are rejected before a HID write can be built.

The bounded live storage check found one small keymap.json in the root, with a single vendor layer and no macros or multi-actions. The contents were inspected through read-only calls; nothing was written back. That is enough to establish that a device-side keymap exists without turning a protocol study into an unnecessary persistence experiment.

The allowlist made it possible to test the most expressive output surface without touching persistent configuration. That produced the first result a person could understand from across the room.

The first visible payoff: software painted the hardware

Provenance: exact-unit live v0.4.1 over BLE unless stated otherwise.

Three lighting APIs appear in the evidence:

• lights.preview addresses whole-device key backlight and underglow with full field names;
• v.oai.thstatus sends six indexed status/color entries for the translucent Agent keys; and
• v.oai.rgbcfg uses compact configuration fields and may persist state.

The first two are no longer theoretical. On the exact device, lights.preview visibly changed the chassis lighting. v.oai.thstatus independently set all six Agent keys green. A red “blinking eyes” sequence sent 49 frames and received a reply to every one. A later composite test layered a whole-device effect with a spatial six-key cyan/indigo/violet field and delivered 81 frames in 24.421 seconds.

That sustained test achieved about 3.3 effective frames per second despite a higher request rate. BLE lighting should therefore begin around three frames per second and be measured under real coexistence conditions before increasing load. The translucent caps and enclosure diffuse neighboring colors enough for the six points to read as one continuous field—closer to chromatophore-like camouflage than six unrelated indicator lamps.

The latest showcase defaults to an emerald field: lime, leaf, jade, and teal tones across the six keys, with green whole-device lighting underneath. It uses runtime preview/status messages and does not alter the saved keymap or invoke the potentially persistent v.oai.rgbcfg path.

The precise number, placement, and electrical grouping of physical LEDs remain unknown. What is proven is the addressable behavior visible from the host: one whole-device layer plus six independently controlled translucent positions.

Seeing the colors change proved the protocol. Making that proof reliable on macOS required one more layer of engineering.

The macOS bridge: why the obvious HID route was not enough

The device appears as one IOHIDDevice whose primary usage is keyboard and whose vendor collection is secondary. Cross-platform HID libraries often model each top-level collection as an independently openable path; on macOS that abstraction can fail to reach the secondary vendor report.

Direct IOKit access follows a predictable path:

match IOHIDDevice by VID/PID
  -> create IOHIDDevice
  -> open shared
  -> register input-report callback
  -> schedule on a CoreFoundation run loop
  -> send Report 6 output
  -> require a matched device.status response

The process needs macOS Input Monitoring permission. Without it, discovery and descriptor inspection can still work while IOHIDDeviceOpen returns kIOReturnNotPermitted. That is an operating-system authorization failure, not a framing or firmware failure.

The callback itself is a native-code boundary. A Python ctypes callback must remain strongly referenced, no Python exception may unwind through the C frame, and disconnects must be safe between any two operations. The probe stores the callback for the device lifetime, captures callback errors, bounds frame and raw report memory, matches replies by request ID, and unschedules before closing.

It opens the hardware shared and never seizes it. Shared access prevents the probe from deliberately displacing another host, but it cannot prevent semantic conflicts. Two applications can react to the same key; two lighting writers can overwrite each other. A production bridge needs one output owner even when multiple input subscribers are allowed.

Turning the probe into a physical API

The integration boundary is deliberately boring: normalized JSON Lines.

codex-micro-probe doctor
codex-micro-probe status --json
codex-micro-probe listen --duration 30 | your-service

Records carry a timestamp, device/transport context, firmware when known, event type, normalized fields, and optional raw report data. A Node, Rust, Swift, Go, Python, or shell-based service can consume the stream without implementing IOKit.

Python applications can use the library directly:

from codex_micro_probe import CodexMicro

with CodexMicro.connect() as micro:
    status = micro.status()
    for event in micro.events():
        dispatch(event)

For a durable integration, a small local daemon should own the HID connection and expose a Unix socket or local WebSocket. It should provide reconnect with backoff, status-based feature negotiation after every attachment, subscriber fan-out, single-writer lighting arbitration, mapping configuration, action audit, and a circuit breaker around consequential downstream operations.

The device then becomes a physical API:

Codex Micro
  -> IOKit transport
  -> normalized events
  -> local policy broker
       |- editor or creative-tool adapter
       |- game/simulator adapter
       |- agent-runtime adapter
       |- observability and audit log
       `- lighting renderer back to the device

Once the transport disappears behind a stable local event stream, the question changes from “Can we talk to it?” to “What should this object mean?” The useful answers form a ladder: first stable targets, then visible authority, then voice, continuous control, and finally carefully bounded machines beyond the desktop.

Editorial illustration—not evidence. The three panels visualize the proposed interaction arc: speak a brief, guide or select visible work, then read the resulting six-lane state from the device. The exact-unit capabilities and the host-side prototypes supporting that concept are distinguished in each use case below.

Three walkthroughs you can actually run

These are deliberately written as control loops, not feature lists. Every walkthrough says what the operator does, what the host is allowed to do, what feedback should appear, and which gesture exits safely. The physical input and lighting primitives were observed on the exact unit. Agent dispatch, pointer injection, overlays, and state arbitration are implemented on the Mac; they are not hidden firmware modes.

1. Give one agent a voice brief

Official Codex mode and DSCO Swarm mode intentionally assign different meaning to the same physical surface. In Official mode, the desktop application owns its configured Agent-key and Voice Chat behavior. In DSCO mode, the local broker owns the HID stream and routes a Mac-microphone transcript to a selected slot.

The Codex Micro is the baton here; the Mac supplies the ears and voice output. No USB or BLE audio interface was observed on the device.

Open the full voice-routing diagram →

2. Use the joystick as a guided desktop cursor

This path is opt-in because pointer injection is more consequential than reading HID events. It requires DSCO mode, Input Monitoring, Accessibility, and the explicit Joystick Controls This Mac toggle. Returning to Official mode must release the HID device and stop event injection.

Disconnect, stale input, a permission failure, or a mode change takes the same fail-safe path as Stop. Joystick angle-zero orientation remains configurable because its physical direction convention has not yet been measured.

Open the full joystick-control diagram →

3. Dispatch work and page through six live results

The six transparent keys work best as stable addresses, while the action row, voice bar, encoder, and joystick remain verbs. That avoids tying a physical position to a conversation that may disappear.

The diagram atlas later in this edition shows these three loops in detail: the voice route, the opt-in pointer gate, and the single swarm-state owner that drives tiles, chassis light, overlay, and spoken cues.

Open the full swarm-feedback diagram →

Use case 1: six lights become six agent slots

Provenance: host-side implementation, with exact-unit input and lighting primitives proven live. External task execution remains a policy-layer prototype, not a firmware feature.

Six target keys plus seven action positions create 42 direct agent/action pairs before chords, layers, the encoder, or the joystick enter the picture. The most useful model is to make the Agent keys transparent selectors and keep the action row as a stable verb vocabulary.

• Tap AG03 to make Agent 3 the persistent focus.
• Hold AG01 and AG03 to create the temporary target set {1,3}.
• Press an action while holding them to emit one action for both targets.
• Release the selectors and preserve the previous persistent focus.
• Turn the encoder to adjust a visible parameter for the selected targets.
• Move the joystick to steer a visible two-dimensional policy or routing space.

The implemented AgentRouter emits intents; it does not directly execute shell commands, approve external actions, or mutate task state. For example:

{
  "event_type": "agent-intent",
  "intent": "action",
  "action": "approve",
  "targets": [
    1,
    3
  ],
  "transparent": true
}

That boundary matters. A downstream broker can enforce authorization, idempotency, target generations, and audit policy without complicating the HID decoder.

The repository also contains a bounded swarm runner that launches six ephemeral Codex workers in a shared workspace. Its initial roles are researcher, protocol analyst, systems integrator, tester, product designer, and synthesizer. Read-only sandboxing is the default. Device events change focus and emit routed intents; worker state can be rendered on the six Agent lights. A bounded run terminates and reaps unfinished worker processes instead of leaving a hidden swarm behind.

codex-micro-probe swarm \
  --goal "Audit this repository and propose the next release" \
  --cwd /path/to/project \
  --duration 120

The production version should keep six stable physical slots while allowing their backing runtimes to change. A slot might point to a builder, reviewer, researcher, operator, strategist, or coordinator today and to a different local or remote service tomorrow. Physical identity stays fixed; adapters remain replaceable.

Approval semantics need stronger rules than ordinary navigation. An Approve press should be accepted only when the visible target is waiting for approval, and it should include the target's current generation so a duplicate HID event cannot approve a later proposal. Consequential actions should require a visible confirmation surface. The double-switch wide cap cannot serve as two-factor confirmation: ACT10 and ACT11 are two switches under the same finger.

The result is not six “AI buttons.” It is a compact operator console with selection, verbs, continuous adjustment, spatial steering, and a six-channel status display.

Use case 2: chords become visible, expiring authority

Provenance: host-side DSCO implementation built on exact-unit Report-6 key events and reversible lighting. The model assignments and privilege semantics are host policy, not firmware features or official Codex behavior.

The six transparent positions become more useful when treated as three model pairs. The top pair, AG00 + AG01, addresses two Sol lanes. The left pair, AG02 + AG03, addresses two Terra lanes. The right pair, AG04 + AG05, addresses two Luna lanes. The inner or middle pair, AG03 + AG04, crosses the boundary between Terra and Luna and is useful for comparison, handoff, or a two-model review.

For normal work, the operator holds a pair and presses an action. That action is routed to the two selected, resumable Codex lanes, which remain under a workspace-write sandbox. A pair chord is therefore a targeting gesture, not an implicit privilege escalation.

The same controls can form a much more deliberate state machine for the rare case where the operator requests a native, ungoverned DSCO job:

The speech comes from the Mac speakers. Voice input likewise comes from the selected Mac microphone: the Codex Micro exposes HID controls, but no audio input interface or microphone has been observed on the exact unit.

The privileged native argument vector is deliberately narrow and explicit:

dsco --profile worker --model MODEL \
  --systems-agent --gov-model none --prompt PROMPT

There is no shell interpolation, no -e codex, and no Codex danger-full-access flag. Omitting -e codex is essential because an external Codex executor would replace the native DSCO process and make the DSCO flags a misleading description of the actual executor boundary.

This sequence should not be described as “safer YOLO.” DSCO's source labels --systems-agent UNGOVERNED and says that it has no safety envelope; --gov-model none removes the governance-model gate. Yellow, red, spoken confirmations, expiry, single consumption, and single-lane scope make the operator's intent observable and reduce accidental activation. They do not constrain what the authorized job can do.

The latch exists only in daemon memory and is never serialized. Every cancel, disconnect, mode transition, expiry, and completed consumption invalidates it. The yellow, red, and green backgrounds use reversible runtime-only lighting; they do not rewrite saved device configuration. When control returns to the official Codex mode, the DSCO renderer stops issuing lighting writes.

The complete route was then verified on the exact v0.4.1 unit over USB. The top chord changed the full background to yellow on its second key-down; the middle chord changed it to red; the Mac played each spoken cue; the wide key captured and transcribed “Run LS.”; and the resulting Sol-lane native DSCO job reported systems_agent=true, governance_model=none, and exit code 0. The authorization disappeared when the job was queued and the background returned to green. The sanitized live record omits both the token and command output.

Use case 3: a voice-addressed six-slot agent console

Provenance: exact-unit key events and official desktop behavior are live. The independent voice/slot coordinator is implemented host-side and remains separate from both firmware and the official Codex bridge.

The strongest interaction is already visible in the current settings. An Agent key can focus its assigned task, and the microphone key can be configured for Voice Chat. In that mode a quick tap starts a Voice Chat or toggles its microphone; a hold ends the call. The live capture proved that all six Agent keys and both switches under the microphone cap reach macOS cleanly over BLE. The Voice Chat session that opened during testing was the official desktop bridge responding to the physical gesture; the probe itself opens the HID device shared and does not synthesize that UI command.

The exact host configuration used during the live test. The screenshot is retained without account or device identifiers.

That gives the zero-custom-code workflow today:

1. Tap one of the six Agent keys to focus its assigned task.
2. Quickly tap the microphone cap to start Voice Chat in the focused context.
3. Speak the instruction, continue the conversation, and use the same six keys to move between live assignments.

The more powerful workflow is a chorded slot broker. Each transparent key is a stable physical address for a live agent instance rather than a static shortcut:

The local DSCO prototype now makes that vocabulary concrete without turning it into a hidden privilege channel. Encoder turns adjust a selected lane's runtime-only effort marker in 0.1 steps. Encoder press arms a single resume, but only for lanes with a durable Codex thread. On the current cap layout the action row is Play | YOLO | YEET | Stop: ACT06 is the primary pick/drop or resume action, ACT07 is the left-hand approval key, ACT08 is the right-hand reject key, and ACT09 is stop/back. The double-width microphone/spacebar still coalesces ACT10 and ACT11. The joystick remains an explicit agent/game stream unless the operator visibly enables the separate macOS pointer adapter.

Each slot needs a durable record such as:

{
  "slot": 2,
  "generation": 7,
  "task_id": "redacted-stable-task-reference",
  "role": "researcher",
  "state": "listening",
  "voice_session": "active",
  "last_heartbeat_ms": 120,
  "pending_approval": null
}

The generation is essential. If Slot 2 is replaced, a late transcript, button release, or approval from generation 6 must not affect generation 7. Likewise, a multi-slot voice brief should display its targets before the broker fans out the transcript; speech must not silently become a broadcast command.

The practical architecture is:

AG selector(s) + microphone gesture
  -> exact Report-6 events
  -> AgentRouter target set and wide-key coalescing
  -> voice/slot coordinator
       |- create, focus, resume, replace, or reject
       |- transcript source and end-of-speech boundary
       |- six stable task references with generation guards
       |- authorization, fan-out preview, and audit record
       `- state renderer -> six v.oai.thstatus entries
  -> Codex task, DSCO worker, local process, or remote agent adapter

There are three sensible transcript sources. The official Voice Chat path is the best user experience but needs a supported way to hand its transcript to a local slot broker. Push-to-talk dictation can insert text into the focused composer but is not a general event API. A separate local or API-backed speech service gives the broker a clean transcript stream but becomes another service to secure and operate. Scraping private desktop internals would be the most brittle choice and is not required to prove the control model.

Lighting should make the six instances legible without returning to decorative pink and blue. The project baseline is now green: deep emerald for idle, mint for queued, bright leaf green for running, and solid green for complete. Yellow is reserved for approval, red for failure, pale sage for paused, and gray for offline or cancelled. A selected listening slot can pulse between emerald and mint while the other five remain steady. That makes color operational state, not wallpaper.

The prototype also includes a local macOS command surface. The four-dot action key opens a floating overlay with six live lane cards and a short contextual palette. While it is open, the encoder rotates through Voice brief, Fast path, Model pair, Resume, Confirm fan-out, and Stop listening; encoder press and mouse click invoke the highlighted item. The palette sends only those allowlisted, generation-aware gesture requests to the local daemon. It cannot carry a free-form prompt, arbitrary firmware RPC, shell command, or permission change. That makes the device feel like a compact coordination console without turning its physical controls into a silent privilege-escalation channel.

What exists now is enough to prove the complete host-side path: physical target chords, a persistent six-slot coordinator, resumable bounded Codex workers, live per-slot lights, and local speech capture from the Mac microphone. The official Voice Chat gesture remains a separate, exact-unit interoperability fact. Production work remains around packaging, recovery, audit review, and additional runtime adapters; none of it requires flashing or opening the device.

Use case 4: a hybrid macOS controller

Provenance: exact v0.4.1 BLE events and status; host-side implementation; standard mouse and gamepad emission remains unresolved.

The device can operate as a spatial computer controller without pretending its capacitive pad is a trackpad. The pad exposes no continuous X/Y, pressure, contact-count, or swipe collection in either exact descriptor. The continuous two-dimensional source is the planar joystick. The useful composition is touch as an eventual mode clutch, joystick as the vector, encoder as scroll or depth, and keys as explicit actions.

The signed menu-bar application now exposes three visible modes:

Pointer actions are deliberately finite: left click, right click, double-click, drag lock, scroll, Escape, and release-all. The Python daemon does not receive general Accessibility authority. It publishes normalized axes and an allowlisted action queue to the signed AppKit owner, which bounds motion to the active display and releases held buttons on stale input, mode changes, disconnect, pause, or quit. Input Monitoring is required for device input; Accessibility is requested only when Pointer is selected.

Navigate is the safe default and the more important interaction model. The joystick opens a cockpit without disturbing the cursor, selects six visible commands plus a seventh Results sector, and keeps the reason for the current animation in the overlay. This makes the surface useful for paging through agent work even when Pointer mode is never enabled.

The exact BLE unit has entered Pointer and returned to Navigate while retaining v0.4.1 status, battery, layer, and connection telemetry. Offline tests cover dead-zone calibration, nonlinear response, radial hysteresis, click/drag state, malformed reports, timeout, and disconnect-to-neutral behavior. Live USB Report 4 emission remains pending because the unit is currently operating over BLE.

Use case 5: a game controller—with an important distinction

Provenance: exact-unit descriptor and events; implemented host-side mapper; system-wide virtual controller remains a distribution/integration step.

The USB descriptor's native gamepad collection is real, but the Codex profile was observed sending controls over Report 6, and the exact BLE descriptor omits Report 4 entirely. A native gamepad declaration is therefore not the same thing as a working factory gamepad mapping.

The immediately usable route is host-side translation:

codex-micro-probe gamepad --duration 30

The mapper turns AG00–AG05 into buttons 0–5, the action row into additional buttons, the wide cap into one coalesced button, the encoder press into a button, encoder turns into momentary dial pulses, and joystick polar coordinates into X/Y axes. It retains the raw polar sample so angle conventions can be corrected without destroying evidence.

That canonical state can be consumed directly by a game or simulator. An in-process virtual joystick API is another straightforward adapter. A system-wide virtual HID gamepad on macOS is a separate packaging problem: current Apple headers require the com.apple.developer.hid.virtual.device entitlement for IOHIDUserDevice, so a production bridge needs an appropriately signed helper or an existing trusted virtual-controller path.

The six illuminated keys are especially well suited to squad or ability selection, with each key showing cooldown, health, readiness, or ownership. The joystick can navigate or orbit; the dial can scrub, zoom, or select; ambient light can show global health or alert state. That is richer than pretending the device is a twelve-key keyboard.

Use case 6: a simulator and mission console, not a flight radio

It can credibly control a drone simulator or act as a secondary input to a ground-station application. It should not be treated as a primary flight transmitter.

The distinction is fundamental. The Micro provides one spring-centered two-axis joystick, not the four continuous axes normally used for manual multirotor flight. BLE, macOS scheduling, a userspace bridge, and a vendor HID protocol add failure modes that a safety-rated radio link is designed to avoid. The device also has no demonstrated independent emergency-stop channel.

A sensible simulator mapping is:

Yaw and altitude should remain under a second conventional controller or a well-bounded autopilot mode; they should not be improvised as latching encoder or button state. Likewise, a single key event must never arm motors.

Any real-aircraft experiment needs a safety architecture outside the Micro:

1. Prove the entire mapping in software-in-the-loop simulation first.
2. Let the flight controller—not the desktop bridge—own stabilization, geofencing, altitude limits, return-to-home, and loss-of-link behavior.
3. Require a fresh heartbeat and neutralize commands immediately when input is stale, centered, disconnected, or malformed.
4. Use bounded rates and setpoints; reject impossible jumps and out-of-range values.
5. Require an explicit, visible arming sequence plus an independent conventional RC takeover or physical kill mechanism.
6. Never count the two switches under the wide cap as independent safety confirmations.
7. Bench-test with propellers removed, then use a controlled test site and a qualified operator.

Under those constraints, the Micro is an excellent experimental mission or simulator console. Without them, it is an unreliable radio replacement. The interesting stretch is not “fly a drone directly over keyboard Bluetooth”; it is “use a programmable, illuminated control surface to command a flight system whose autopilot and failsafes remain in charge.”

What it takes to make the idea trustworthy

Direct access removes a software dependency, but it does not remove the need for a trust model.

HID and local permissions

Input Monitoring lets a process observe HID activity. Grant it only to trusted, identifiable binaries. No application-layer authentication was observed on the vendor channel, so USB physical access and BLE pairing are meaningful parts of the trust boundary.

Treat device events as untrusted input. Validate JSON shape, frame length, numeric range, control ID, and state transition before an event reaches a shell, deployment system, agent approval, purchase, or flight command.

Firmware and persistent state

Bootloader and filesystem mutation methods exist in the public-image method inventory. The clean-room tool blocks them structurally and does not provide a generic RPC command. That is a security property, not merely a conservative default.

The same principle applies to lighting. Runtime preview and status calls are characterized; v.oai.rgbcfg remains gated because its persistence semantics are unresolved. A pretty animation is not worth accidentally rewriting saved device configuration.

Disconnects and silent failures

A successful HID write is not proof of a working protocol. Every request needs a monotonic timeout and a matching response ID. A disconnect can happen after the write but before the reply. Reconnect logic must rediscover the device, re-read transport and descriptor facts, perform device.status, and negotiate features again.

Callbacks must stay alive, parsers must cap reassembly memory, malformed frames must fail closed, and downstream actions need idempotency. Unknown notifications should be logged safely for diagnosis, never executed speculatively.

Multiple clients and privacy

Shared HID access permits coexistence but does not arbitrate meaning. Use one lighting writer and one policy broker, then fan out normalized input to subscribers. Logs should redact device identifiers, local paths, prompts, credentials, and downstream payloads by default. Direct local integration can keep the raw HID stream on the machine; whether later agent or cloud adapters transmit data is a separate, explicit policy decision.

The honest edge of the map

The completed non-invasive work still cannot establish:

• PCB revision, exact bill of materials, GPIO assignments, matrix wiring, LED count, antenna design, test pads, or connector topology;
• the exact v0.4.1 binary, build flags, partition table, secure-boot state, flash-encryption state, or firmware-signing policy;
• the exact touch/profile report on the measured unit;
• joystick angle-zero direction, rotation convention, radial response curve, dead zone, quantization, and maximum event rate;
• whether the factory USB profile can actively populate native Report 4 without changing configuration;
• whether v.oai.rgbcfg writes NVS or the filesystem and how saved lighting is restored;
• schemas and side effects for untested diagnostics and RPCs; and
• whether a host updater offers a recovery path independent of the v0.4.0 partition layout.

No host-controllable haptic actuator has been proven. No real drone was flown. The canonical gamepad mapper and six-worker swarm are host-side integrations, not secret native firmware modes.

Those boundaries do not weaken the central finding. They keep it useful.

From accessory to instrument

At the beginning, the Codex Micro could be lit, paired, and apparently inert at the same time. The breakthrough was not a secret key combination. It was the recognition that keyboard events were the wrong abstraction. Report 6 exposed the device's actual language, and a matched status response proved that the conversation worked in both directions.

From there the pieces accumulated into an instrument. The exact v0.4.1 unit demonstrated direct BLE status exchange, all 13 switch positions, encoder events, full-range joystick input, reversible whole-device lighting, six independently controlled Agent lights, and sustained animation. Its exact USB and BLE descriptors showed why the two transports cannot be treated as interchangeable. The official v0.4.0 image supplied an architectural map of the ESP32-S3, storage, power, input, and lighting subsystems without being passed off as the live firmware.

The protocol is only half of the product. The other half is choreography: selection before action, visible state before approval, generation guards before resumption, a clear Stop control, and light that reports what software is doing rather than merely decorating the desk. In that model, six translucent keys are not six shortcuts. They are six stable addresses into work that can start, pause, disappear, and return.

That same loop scales sideways. A creative tool can turn joystick movement and encoder rotation into spatial control. A game or simulator can consume a normalized controller stream. A ground station can use the surface as a carefully bounded mission console while leaving stabilization and failsafes to the flight system. A local daemon can offer all of those meanings to any language while structurally withholding dangerous firmware operations.

The $250 question therefore has a satisfying answer. This is not merely a closed accessory waiting for one blessed application, and it is not valuable because it can imitate a larger keyboard. It is valuable because physical intent can enter our software through it, software state can return as light, and the rules in between can belong to us.

Reproduction and source notes

The public probe exposes conservative commands rather than arbitrary RPC:

codex-micro-probe discover --json
codex-micro-probe doctor
codex-micro-probe descriptor
codex-micro-probe status --json
codex-micro-probe listen --duration 30
codex-micro-probe gamepad --duration 30
codex-micro-probe agents --duration 30
codex-micro-probe fs-inventory

Primary public references:

• OpenAI Codex Micro product page
• Work Louder Creator Micro setup guide
• Work Louder firmware releases
• FreeMicro independent v0.4.1 protocol documentation

The clean-room implementation was written from measured HID interface facts, Apple's public IOKit headers, the official public firmware release, and independently documented wire behavior. It contains no vendor source, private application package, firmware binary, device serial number, or copied proprietary implementation.

Diagram atlas

A visual atlas of the same system keeps measured behavior, public-image analysis, host-side proposals, and unresolved hardware facts visibly separate.

1. One device, several identities

Reading the diagram. The chassis name, host-advertised product name, commercial SKU, and embedded project name belong to different layers. They are related, but none should be substituted for another. Evidence: claim ledger and live USB capture.

2. Non-invasive physical control map

Reading the diagram. All six AG00–AG05 and seven ACT06–ACT12 switch IDs were captured over BLE. The corrected physical action row is ACT06 Play/A, ACT07 YOLO, ACT08 YEET, ACT09 Stop: YOLO is left of YEET, with Play/A immediately left of YOLO and Stop immediately right of YEET. The wide voice / spacebar cap closes ACT10 and ACT11 within milliseconds, so host software must coalesce them. The diagram is a control-surface model, not a PCB, GPIO, or LED-routing claim. Evidence: BLE input matrix and current physical layout record.

3. USB/BLE host-device data path

Reading the diagram. The Codex profile sends its useful controls over vendor Report 6 on both transports. USB advertises a native Report 4 gamepad collection; the measured BLE descriptor does not. Application-level game state remains possible on either transport. Evidence: USB report map and BLE validation.

4. Report 6 framing and reassembly

Reading the diagram. A message can span many HID reports. macOS accepting a write does not prove that the device accepted its framing; a matched device.status response is the end-to-end health check. BLE's leading 0x06 is part of the 64-byte output buffer while the report-ID API argument remains 6. Evidence: protocol implementation and BLE status round trip.

5. Firmware partition map and the version boundary

Reading the diagram. The partition table and ESP32-S3 target are facts about the public v0.4.0 image. The shipping unit reports v0.4.1, whose binary was not obtained; the dashed bridge is inference, not version equivalence. The public table has a single factory app and no A/B OTA fallback. Evidence: derived firmware analysis.

6. Six-agent broker and status lighting

Reading the diagram. Selectors identify targets; verbs remain reusable. The implemented router emits auditable intents and the broker is the authority boundary before any external effect. The shown palette is the current code palette, distinct from decorative lighting themes. A bounded runner can report cancelled during shutdown; that runner state does not yet have a tile color. Evidence: agent-control implementation and swarm runner.

7. Game and drone-simulator bridge with a failsafe gate

Reading the diagram. Game-controller state mapping exists today; drone control does not. The safe next experiment is a simulator adapter behind a hold-to-enable gate. Any lost transport, stale report stream, dead-man release, parser error, or process exit must force safe output. Joystick angle-zero orientation remains unmeasured, so its transform is configurable. Real flight additionally needs an independent aircraft-side failsafe and physical kill path. Evidence: gamepad mapper and exact joystick capture.

8. Lighting domains and ownership

Reading the diagram. lights.preview drives the broad chassis domains and v.oai.thstatus drives six transparent Agent positions independently; the two were composed successfully over BLE. v.oai.rgbcfg may affect stored settings and remains deliberately untested. Visible zones do not reveal physical LED count or wiring. Evidence: lighting preview, six-tile acknowledgement, and composed animation.

9. RPC safety boundary

Reading the diagram. The probe exposes task-specific operations, not a generic RPC escape hatch. Destructive filesystem and bootloader methods are blocked before any HID write; unknown methods also fail closed. Runtime lighting is opt-in, and the potentially persistent RGB configuration requires a separate explicit acknowledgement. Evidence: protocol safety policy and method classification.

10. Voice-addressed six-slot agent lifecycle

Reading the diagram. The mode boundary is explicit: in Official Codex mode, the microphone gesture retains the observed desktop Voice Chat semantics; in DSCO Swarm mode, the local router produces a target set and coalesces the two switches under the wide voice cap before the implemented coordinator binds the request to one of six durable task slots. Every slot has a generation so a delayed transcript, release, or approval cannot affect a newly replaced agent. Multi-slot speech requires a visible target preview before fan-out. Evidence: interactive key validation, Voice Chat setting, agent router, and voice daemon.

11. Voice brief: hardware target, Mac audio, agent dispatch

Reading the diagram. The Codex Micro contributes target selection and a microphone-key gesture; it does not expose a USB or BLE audio-input interface. The local native helper opens the selected Mac microphone only after an explicit gesture, then binds the transcript to a generation-qualified agent slot. A timeout, disconnect, cancellation, or late generation fails closed. Optional spoken confirmation uses Mac audio output. Evidence: current physical layout, BLE input matrix, voice daemon, and native voice runtime.

12. Opt-in joystick desktop-control loop

Reading the diagram. The joystick's continuous angle/distance reports, the corrected Play/A and Stop positions, and encoder pulses are exact-unit observations. The native host implements an explicit, permission-gated macOS pointer bridge: joystick motion controls pointer velocity, Play/A clicks or drags, Stop sends Escape, and the encoder scrolls. Physical angle-zero orientation remains unresolved and therefore configurable. Transport loss, stale input, a mode switch, or permission loss must neutralize motion and release any held button. Evidence: BLE input matrix, current physical layout, computer-control implementation, and guided cursor overlay.

13. One swarm state, four feedback channels

Reading the diagram. The broker, not the LEDs, owns the swarm's semantic truth and projects it through four coordinated channels: six slot tiles, whole-device lighting, the macOS overlay, and optional Mac speech. v.oai.thstatus and lights.preview are exact-unit v0.4.1 capabilities; state-to-color arbitration, the overlay, and spoken cues are host policy. Green is the calm baseline, yellow is reserved for approval or arming, and red preempts decoration for a failure or blocked state. Official mode must release DSCO's input and lighting ownership to prevent competing writers. Evidence: six-tile live acknowledgement, backpiece visual lab, privilege-latch live proof, voice daemon, and menu-bar controller.

Community knowledge bridge

Source access date: 2026-07-31
Local evidence snapshot: 2026-07-31
Scope: public official documentation, public source repositories, public release artifacts, and this project's non-invasive exact-unit captures
Boundary: no private application code is reproduced; no community claim is promoted to an exact-unit fact without a matching capture

Executive synthesis

The public record now contains three unusually useful clean-room interoperability experiments:

1. FreeMicro replaces the vendor host software and talks directly to a shipping Codex Micro over macOS IOKit.
2. codex-micro-4-core2 replaces the Work Louder hardware with independent ESP32 firmware that the ChatGPT desktop host recognizes over BLE.
3. codex-micro-linux-bridge moves the physical device onto Ubuntu and forwards its HID traffic into a desktop runtime.

Our project closes the fourth side of that square: it independently opened the exact shipping unit on macOS, completed a real device.status round trip on firmware v0.4.1, decoded both USB and BLE descriptors, captured every Codex switch plus encoder and joystick input, and drove both whole-device and six-key lighting over BLE. Taken together, these are strong evidence that the valuable interface is a reproducible HID protocol rather than a hardware attestation or an inseparable dependency on a single desktop application.

That conclusion has limits. The protocol is undocumented by the vendors and may change. Public hardware replicas do not reveal the original PCB. A standard USB gamepad collection exists, but the Codex-profile controls observed here use the vendor channel instead, and the BLE descriptor omits the gamepad report. The correct integration strategy is therefore capability detection and versioned adapters, not assumptions based on the product name alone.

Evidence vocabulary

This report gives exact-unit evidence priority for statements about this unit, then official material for intended behavior, then independent implementations for corroboration. Static v0.4.0 findings are never silently attributed to the live v0.4.1 firmware.

Identity and version boundary

The names refer to related but different layers:

The public release feed currently marks v0.4.0 as the latest stable release and also lists v0.6.0-rc.13 as a pre-release with new Codex integration and connection behavior. That is not a license to treat the shipping Codex v0.4.1 unit, the generic Creator Micro 2 v0.4.0 asset, and the v0.6.0 release-candidate line as one monotonic firmware branch. The release notes and the live unit imply product- or build-specific versioning that remains undocumented.

Official baseline

Two official hardware details narrow the non-invasive model without proving the exact board assembly. Work Louder's reset procedure describes a top PCB linked to a lower PCB by a flat cable and identifies separate reset and boot buttons. That is credible platform-level evidence of a two-board construction. It still does not reveal the Codex unit's routing, component population, antenna, LED topology, or GPIO pinout.

Community source matrix

FreeMicro: independent host and protocol reference

Source: repository and wire protocol

Confirms independently:

• a shipping v0.4.1 unit can be used over USB and BLE without the ChatGPT or Work Louder Input process;
• VID/PID 303A:8360, vendor usage page 0xFF00, Report ID 6, and a 63-byte bidirectional payload;
• USB uses a 63-byte output without an in-buffer Report-ID prefix, while BLE needs 64 bytes beginning with 0x06; both calls still pass report ID 6;
• CRLF-delimited multi-report JSON-RPC, including compact and JSON-RPC 2.0 request forms;
• v.oai.hid, v.oai.rad, device.status, v.oai.rgbcfg, and v.oai.thstatus behavior;
• direct IOKit is the reliable macOS access route and Input Monitoring is required;
• encoder turns must not be filtered on act == 1, and the wide cap spans ACT10 plus ACT11.

Does not prove: the exact behavior of our unit; original PCB/BOM; every statically discovered RPC; protocol stability across future firmware; that a method acknowledging a message produces the same visible result on every unit.

Our bridge: the exact unit reproduced the BLE framing and status round trip, all 13 switch IDs, dual-switch wide-cap timing, act:2 encoder ticks, full-range joystick samples with an exact zero return, and all six Agent-key lighting entries. This is independent replication rather than reliance on FreeMicro alone.

OpenMicro: controller-to-agent semantic bridge

Source: stephenleo/OpenMicro

Confirms by implementation: a conventional gaming controller can drive Codex CLI, the Codex macOS app, and other coding harnesses through a semantic mapping layer. Its defaults map face buttons to submit/interrupt/voice/new-chat, stick flicks to workflows or thinking depth, and expose six configurable layers.

Does not prove: anything about the physical Codex Micro's HID protocol, firmware, PCB, native gamepad report, or lighting. Its controller is the input device and Codex is the target; that is the reverse direction from turning the Codex Micro into a general game controller.

Our bridge: exact v.oai.rad, encoder, and switch events provide enough normalized input to feed the same kind of semantic mapper. This supports using the pad as an application-level controller. It does not make the BLE device advertise as a native gamepad.

DIY Codex Micro: physical comparator, not an original-board teardown

Source: Nishkalkashyap/codex-micro-device

Confirms by construction: a visually similar 13-switch controller can be built around an ESP32-S3 with native USB, one GPIO per switch, an EC11 encoder, a 2U cap spanning two positions, and optional WS2812 lighting. That project documents 23 optional pixels on GPIO 47 with a separate regulated 5 V supply and level shifter.

Does not prove: that Work Louder uses those pins, LED count, electrical topology, switch scanning scheme, encoder, or power design. The project explicitly describes a hand-wired resemblance that emits keyboard shortcuts; it does not reproduce Report 6, BLE transport, the planar joystick, touch control, battery system, or live Agent status.

Our bridge: the official v0.4.0 image independently supports an ESP32-S3 family target, but the exact original board remains unopened and its GPIO/BOM remain unresolved. The replica is a useful lower-bound design, not evidence of the production board.

Linux bridge: transport portability and reconnect behavior

Source: Tomatio13/codex-micro-linux-bridge

Confirms by implementation: raw HID framing can be isolated from the host application and forwarded on Ubuntu. The project reports physical BLE plus desktop end-to-end validation on Ubuntu 24.04, scoped udev rules for 303A:8360, multi-report reassembly tests, and recovery when Bluetooth re-enumerates under a new /dev/hidrawN node.

Does not prove: physical USB operation on Linux, runtime success of its alternative uhid helper, behavior on other distributions, official Linux support, or the macOS ownership model. The repository labels these boundaries.

Our bridge: macOS exact-unit captures establish the same device identity, BLE framing, and reconnect-sensitive transport semantics on another operating system. Together, the two projects argue for a transport-neutral protocol core with small OS-specific adapters.

Codex Deck: six-agent control surface without the physical pad

Source: dazer1234/codex-stream-deck

Confirms by implementation: the six Agent slots, action positions, joystick directions, encoder commands, and live task states form a reusable control model that can be rendered on an Elgato Stream Deck and extended across Windows, macOS, and an optional private relay.

Does not prove: the physical device protocol or electronics. It relies on undocumented Codex desktop internals and explicitly warns that desktop releases may break compatibility.

Our bridge: Report-6 events supply the hardware-side equivalent of its virtual controls, while v.oai.thstatus supplies the six independent feedback channels. The combined lesson is to keep agent state and action semantics above the physical transport so either surface can be substituted.

Core2 compatibility firmware: independent device recognized by the host

Source: imliubo/codex-micro-4-core2

Confirms by implementation: an M5Stack Core2 can present an independently implemented BLE vendor HID surface that ChatGPT Desktop recognizes on macOS. The project reports real-hardware validation, Report ID 6 JSON-RPC, six Agent keys with status feedback, six command keys, four direction controls, dial actions, and battery reporting.

This is the strongest public evidence that original Work Louder hardware is not cryptographically required for host recognition. It demonstrates compatible firmware talking to the official host, complementing FreeMicro's official hardware talking to a compatible host.

Does not prove: original-board design, USB compatibility, Windows support, physical analog sampling, original LEDs/layers/updater, or long-term protocol stability. It implements touchscreen actions, not the original controls.

Our bridge: the exact unit supplies the original endpoint characteristics that the Core2 project emulates: BLE identity, Report 6 framing, input method names, device status, and six Agent-state outputs.

OpenAI Codex issue #34099: a reliability field report

Source: openai/codex issue #34099

This public issue reports intermittent HID read failures and a ten-second RGB RPC timeout on another macOS unit running v0.4.1, with both USB and a paired BLE profile in the environment. It records the same VID/PID, BLE product naming, firmware version, and v.oai.rgbcfg method seen elsewhere.

It is a user-submitted diagnostic report, not a vendor root-cause statement or an independently reproduced defect. Its transport-contention explanation is explicitly a hypothesis. Our short exact-unit sessions were stable enough for status, input, filesystem, and sustained lighting tests; they do not refute an intermittent failure that may require a longer window. The engineering response is clear even before root cause: expose active transport in logs, place deadlines around RPCs, treat disconnect as normal, rediscover by identity rather than path, and never let a lighting update block input processing.

Exact-unit corroboration matrix

Contradictions and their current resolution

1. lights.preview versus v.oai.rgbcfg

FreeMicro's current protocol document says lights.preview acknowledges but is visibly inert on its v0.4.1 unit, and identifies v.oai.rgbcfg as the working whole-device path. Our exact v0.4.1 unit acknowledged lights.preview and visibly turned blue over BLE; the photograph and parameters are retained. Both projects visibly confirm v.oai.thstatus for the six Agent keys.

Resolution: do not globalize either unit's whole-device result. Implement both methods behind a version/capability adapter, establish transport health with device.status, hold each test state long enough for visual observation, and restore host ownership afterward. v.oai.rgbcfg remains independently corroborated but deliberately untested on our unit because its persistence semantics were not yet characterized.

2. Which descriptor has the Feature item?

FreeMicro's transport table correctly says the 216-byte BLE descriptor adds a Feature item. A later sentence in the same file says USB adds that item to reach 275 bytes. The included 216-byte hex and our exact capture resolve the typo:

• BLE, 216 bytes: Reports 1, 2, 3, and 6; Report 6 has Input, Output, and Feature.
• USB, 275 bytes: Reports 1, 2, 3, 4, and 6; Report 4 is the native gamepad; Report 6 has Input and Output.

Resolution: the material transport capability difference is USB's Report 4 gamepad collection, not a USB-only Feature item.

3. v0.4.1 shipping behavior versus v0.6.0 release-candidate notes

The shipping Codex unit and FreeMicro both report v0.4.1 with working Codex methods. The generic Work Louder release feed describes v0.6.0-rc.13 as adding support for an upcoming Codex integration.

Resolution: treat these as potentially different build/product trains. Do not sort features solely by semantic version across products. Match product identity, descriptor fingerprint, device.status.version, and observed method behavior.

4. “Haptic” pad versus touch control

FreeMicro calls the lower-left control a haptic pad. OpenAI and Work Louder call it a touch sensor/control, and their documented behavior is layer/connection selection. Our v0.4.0 static inventory contains touch-related surfaces but no proven motor driver or host haptic command.

Resolution: touch input and three indicators are confirmed; a host-controllable vibration actuator is unresolved. “Haptic” is not evidence that force feedback exists.

5. Native gamepad capability versus observed Codex input

The USB descriptor contains an 11-byte gamepad Report 4, but every Codex-profile key, encoder tick, and joystick sample captured here arrived as Report-6 JSON-RPC. BLE omits Report 4 entirely. OpenMicro demonstrates that gaming controllers can be mapped into coding actions, not that Codex Micro emits a native gamepad stream in its current profile.

Resolution: game-control applications are practical through a host bridge that converts normalized Report-6 events into an application or virtual-device API. Native USB Report-4 emission on another Work Louder layer remains an unmeasured possibility; native BLE gamepad advertisement is refuted by the current descriptor.

6. Printed keycaps versus physical switch identity

Official docs emphasize remapping and swapping caps. FreeMicro warns against hard-coding legends. The exact unit's owner has already rearranged the caps.

Resolution: use AGxx, ACTxx, and encoder identifiers as the stable physical address. Store cap labels and logical actions in user configuration. Coalesce ACT10 and ACT11 unless the user intentionally enables separate wide-key behavior.

7. Cable presence versus active USB transport

Both official setup guides state that plugging in a cable while a BLE slot is selected charges the device without switching the communication path. Public reliability reports also show why guessing transport from cable presence is dangerous.

Resolution: inspect the IOKit transport property and prove the outbound path with a matched device.status reply. A charging flag is not a transport flag.

What the public hardware work actually adds

The hardware boundary is narrower than “unknown,” but wider than a teardown:

The DIY ESP32-S3 project proves that a simple one-pin-per-key design is viable; it does not move the original board's unknowns into the confirmed column.

Engineering consequences for this project

Protocol core

• Keep message reassembly, JSON-RPC parsing, and event normalization independent from the IOKit/hidraw transport.
• Select USB versus BLE framing from the enumerated transport and descriptor, never from cable or charging state.
• Treat a successful OS write as provisional. A matched read-only status reply is the health check.
• Preserve unknown methods and fields in logs while exposing only an allowlist for outbound calls.

Input and controller use

• Model six Agent keys, seven action switch IDs, encoder press, encoder ticks, and continuous polar joystick state separately.
• Convert joystick polar coordinates to Cartesian axes in the application layer; add dead-zone, calibration, rate limiting, and disconnect-to-neutral.
• Coalesce the wide key's two edges within a short window by default.
• A game-controller or drone-control experiment belongs behind a simulator and explicit dead-man/failsafe layer. The device is an input surface, not a certified flight controller.

Six-agent orchestration

• The six physical Agent IDs are stable routing slots; colors are output state, not process identity.
• Keep task state in the host and render it to v.oai.thstatus, matching the architecture independently demonstrated by Codex Deck and Core2 firmware.
• Use transparent multi-key selection as an application feature, not a firmware assumption.
• Do not let lighting or status refresh block event intake or agent-process cleanup.

Reliability and coexistence

• Open the device shared unless an explicit exclusive diagnostic requires otherwise.
• Expect vendor-host ownership changes and Bluetooth path renumbering.
• Rediscover by VID/PID, product, transport, descriptor fingerprint, and successful status reply—not by a cached registry path.
• Bound every request, surface the active transport in diagnostics, and drop lighting frames before dropping input when the link is congested.
• Make restoration explicit after temporary lighting tests; persistent RGB or filesystem methods remain outside the conservative allowlist.

Source-quality notes

• Official sources define intended product behavior but omit the wire protocol.
• Community repositories are primary evidence for their own implementations, not authoritative specifications of all shipping units.
• GitHub issue #34099 is primary evidence of one reporter's captured incident, not confirmation of a universal defect or root cause.
• Secondary reviews, reseller pages, and social posts were excluded from the technical claim chain when an official page or source repository was available.
• All repository links above point to mutable default branches or release pages; this report records the 2026-07-31 access date so later changes can be audited.

Bottom line

The combined evidence supports an open-integration thesis with unusually high confidence: the shipping v0.4.1 pad is directly usable by arbitrary macOS software through IOKit, and the Report-6 JSON-RPC interface is sufficiently reproducible that independent projects have replaced the host, replaced the hardware, and moved the transport to Linux.

What remains proprietary or unresolved is not the ability to communicate. It is the production hardware design, firmware source, compatibility commitment, and some version-dependent method behavior. A serious integration should build around the confirmed protocol, preserve exact provenance, and assume that transport, descriptors, and lighting methods may evolve.

Validation matrix

Updated 2026-07-31.

“Pending” means tooling exists but the physical interaction was not captured. “Not run” means the method was deliberately withheld. Neither is reported as a failure or silently upgraded to a confirmed capability.

Claim ledger

Every consequential statement is attached to a provenance class and an explicit status. Local evidence links remain relative to this research package.