codex-pico

KO | EN

gitlite — search

#chatbot #monitoring #hacktoberfest #machine-learning #graphql #claude-code #mcp #javascript #list #postgresql

(★ 9)

Raspberry Pi Pico 2 W firmware that emulates the Codex Micro keypad, with Stream Deck controls and optional HTTP and MQTT integrations.

File Explorer

ZIP Download

- architecture.md
- build-install.md
- home-assistant.md
- http-api.md
- mqtt.md
- provisioning.md
- - .gitignore
  - bridge_core.c
  - bridge_core.h
  - bridge_status_json.c
  - bridge_status_json.h
  - CMakeLists.txt
  - hid_bridge.h
  - hid_probe.py
  - lwipopts.h
  - main.c
  - network_http.c
  - network_http.h
  - network_mqtt.c
  - network_mqtt.h
  - network_wifi.c
  - network_wifi.h
  - README.md
  - tusb_config.h
  - usb_descriptors.c
  - wifi_store.c
  - wifi_store.h
- package-streamdeck.sh
- - plugin.svg
- - action.svg
  - plugin.png
  - [email protected]
- - asar.js
  - codex_icon_cache.js
  - codex_icon_extractor.js
  - codex_layout.js
  - react_svg.js
- - codex_icon_extractor.test.js
- .gitignore
- extract_codex_icons.js
- manifest.json
- node_hid_bridge.js
- package.json
- plugin.mjs
- pnpm-lock.yaml
- pnpm-workspace.yaml
- README.md
- - __init__.py
  - __main__.py
  - cli.py
  - device.py
  - firmware.py
  - flash.py
  - streamdeck.py
.gitignore
CHANGELOG.md
codex-bridge
CONTRIBUTING.md
LICENSE
README.md
requirements.txt
THIRD_PARTY_NOTICES.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

This repository turns a Raspberry Pi Pico 2 W into a physical bridge for Codex by emulating a supported Work Louder HID device. It can be controlled by the optional Stream Deck plugin or by network integrations through HTTP and MQTT.

```text
Stream Deck plugin -> Pico private HID -> Pico Work Louder HID -> Codex
Codex status HID -> Pico private HID -> Stream Deck plugin
```

The Pico deliberately exposes no CDC serial interface. Provisioning, status, and button commands use HID. Optional Pico 2 W builds can also expose HTTP and MQTT status/control surfaces for local integrations such as Home Assistant.

## Deliverables

- Pico 2 W firmware source in `firmware/pico2_hid`
- Stream Deck plugin source in `streamdeck_plugin`
- The `codex-bridge` build, flashing, provisioning, and packaging CLI
- Integration notes in `docs`

The firmware target is Raspberry Pi Pico 2 W. The optional Stream Deck integration targets macOS with Stream Deck 7.1 or newer.

## Quick Start

The Pico storage dependencies are downloaded by CMake at pinned commits. A normal Git checkout is sufficient; there are no Git submodules to initialize.

For the complete flow, follow `docs/build-install.md`.

`codex-bridge` requires Python 3.10 or newer. Create its repository-local environment with a 3.10+ interpreter:

```sh
python3.10 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
```

If `python3.10` has a different name on your system, use any Python 3.10+ interpreter. `./codex-bridge` only uses `.venv`, so it fails with clear setup instructions when that environment is missing or too old.

Check which parts of the toolchain are available:

```sh
./codex-bridge doctor
```

Build and flash the firmware you need:

```sh
./codex-bridge firmware flash base
./codex-bridge firmware flash http
./codex-bridge firmware flash mqtt
./codex-bridge firmware flash full
```

`flash` builds a missing artifact automatically, uses the private HID interface to reboot supported firmware into BOOTSEL, and falls back to physical BOOTSEL instructions when necessary. It can use either the mounted `RPI-RP2` volume or optional `picotool` to write the firmware. Network-enabled firmware then offers to run guided setup.

The Stream Deck integration is optional. To package and install it on macOS:

```sh
./codex-bridge streamdeck install
```

Firmware UF2 files are written under `dist/firmware`. The Stream Deck package is written under `dist/streamdeck`.

## Firmware Profiles

The firmware has four profiles. Every profile includes both the Codex-compatible HID interface and the private management HID interface:

- `base`: HID only, with no Wi-Fi, stored credentials, or network API.
- `http`: base plus Wi-Fi and the local HTTP status/control API on port 80.
- `mqtt`: base plus Wi-Fi and MQTT status/control; HTTP is not included.
- `full`: base plus Wi-Fi, HTTP, and MQTT.

Flash `full` when one Pico should expose every transport. To produce all four release artifacts without flashing them, run `./codex-bridge firmware build --all`.

MQTT currently uses plain TCP. HTTP has no authentication. Use these only on a trusted LAN and do not expose the Pico or broker to the Internet.

## Stream Deck Plugin

The plugin uses the official `@elgato/streamdeck` SDK through its `plugin.mjs` entrypoint, with Stream Deck's Node 24 runtime and `node-hid` to open the Pico private HID interface. It requires Stream Deck 7.1 or newer, but does not require a separately installed Node or Python runtime during normal operation. Node, pnpm, and the standard `zip` utility are only needed to package the plugin from source; Python HID is used by `codex-bridge` for device management.

The plugin renders live agent colours from Codex status and sends Stream Deck press/release edges to the Pico.

## Documentation

- `docs/architecture.md`: system shape and HID interfaces
- `docs/build-install.md`: build, flash, install, and verify the bridge
- `docs/provisioning.md`: Wi-Fi/MQTT credential provisioning
- `docs/http-api.md`: Pico HTTP API
- `docs/mqtt.md`: MQTT topics and command payloads
- `docs/home-assistant.md`: Home Assistant automation examples
- `CHANGELOG.md`: notable changes by release
- `CONTRIBUTING.md`: development setup, testing, and contribution expectations

## AI-Assisted Development

This project was developed with assistance from OpenAI Codex, including code generation, review, testing, documentation, and packaging work. AI-generated or AI-modified code can still contain defects, security issues, incomplete assumptions, or misleading documentation. Review the source, run the tests, and validate the firmware and integrations in your own environment before relying on them.

This project interacts with USB HID devices and can expose unauthenticated HTTP and unencrypted MQTT controls on the local network. Do not use those interfaces on untrusted networks or in safety-critical environments. The project is provided under the MIT License without warranty.

codex-pico

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

codex-pico

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README