Installation¶
C3PO is a Python package with a Qt6 UI. Install it from the c3po/ directory of the framework.
Requirements¶
- Python 3.11+
- A desktop environment (Qt6 / PySide6)
esptoolfor provisioning- Cross-compilers for the chips you will inject modules to (see below)
Install¶
Dependencies (installed automatically):
| Package | Version | Role |
|---|---|---|
| PySide6 | >= 6.6 | Qt6 UI |
| qasync | >= 0.27 | asyncio + Qt event loop |
| pycryptodome | >= 3.15 | ChaCha20-Poly1305, HKDF, HMAC |
| protobuf | >= 4.21 | C2 message framing |
| esptool | >= 4.0 | Flashing during provisioning |
| tomli | (Python < 3.11) | module.toml parsing |
Optional extras:
# RISC-V module compilation (C3 / C6 / H2)
sudo apt install gcc-riscv32-esp-elf
# Serial port auto-detection in the Provision view
pip install pyserial
Module cross-compilers¶
C3PO compiles modules for the target chip on demand. Install the matching ESP-IDF toolchains:
| Chip family | Toolchain |
|---|---|
| ESP32 / S2 / S3 (Xtensa) | xtensa-esp32-elf-gcc, xtensa-esp32s2-elf-gcc, xtensa-esp32s3-elf-gcc |
| C3 / C6 / H2 (RISC-V) | riscv32-esp-elf-gcc |
Toolchains are located via PATH or under ~/.espressif/tools/.
Run¶
# Default: listen on 0.0.0.0:2626
c3po --keystore keys.json --modules modules/
# Custom bind address / port
c3po --host 10.0.0.1 --port 4242 --keystore /path/to/keys.json --modules /path/to/modules
# Debug logging
c3po --keystore keys.json --modules modules/ --debug
CLI flags¶
| Flag | Default | Description |
|---|---|---|
--host |
0.0.0.0 |
C2 bind address |
--port |
2626 |
C2 port |
--keystore |
keys.json |
Path to the keystore (created automatically on first provisioning) |
--modules |
modules |
Path to the module catalog directory |
--debug |
off | Verbose debug logging |
keys.json is created automatically the first time you provision a device. You can also manage it from the Keystore view or build it by hand (see Security model for the format).