Setting Up ESP32 Hardware - moonbench/catode32 GitHub Wiki
Hardware Requirements
- ESP32-C6 SuperMini OR ESP32-C3 development board
- SSD1306 OLED Display (128x64, I2C)
- 8 Push Buttons for input
Software Requirements
- Rust toolchain (install via rustup)
espflash(cargo install espflash)
Board Configuration
The project supports both ESP32-C6 and ESP32-C3 boards. Board selection is done through Cargo features on the catode32-firmware crate. Exactly one of c6 or c3 must be active. C6 is the default.
Build and flash for ESP32-C6:
cargo run
Build and flash for ESP32-C3:
cargo run --no-default-features --features c3 --target riscv32imc-unknown-none-elf
The two chips use different RISC-V variants, so the --target flag matters. C6 is riscv32imac-unknown-none-elf (with the A extension) and C3 is riscv32imc-unknown-none-elf (no A extension). The C6 target is set as the default in .cargo/config.toml, so you only need to pass --target when building for C3.
Wiring
Choose the wiring diagram for your board. Each button connects between GPIO pin and GND (internal pull-ups enabled).
ESP32-C6 Wiring
Display (I2C):
| Display Pin | ESP32-C6 Pin |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SDA | GPIO4 |
| SCL | GPIO7 |
Buttons:
| Button | GPIO Pin |
|---|---|
| UP | GPIO14 |
| DOWN | GPIO18 |
| LEFT | GPIO20 |
| RIGHT | GPIO19 |
| A | GPIO1 |
| B | GPIO0 |
| MENU1 | GPIO3 |
| MENU2 | GPIO2 |
ESP32-C3 Wiring
Display (I2C):
| Display Pin | ESP32-C3 Pin |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SDA | GPIO6 |
| SCL | GPIO7 |
Buttons:
| Button | GPIO Pin |
|---|---|
| UP | GPIO0 |
| DOWN | GPIO1 |
| LEFT | GPIO2 |
| RIGHT | GPIO3 |
| A | GPIO4 |
| B | GPIO5 |
| MENU1 | GPIO10 |
| MENU2 | GPIO11 |
Note: The ESP32-C3 configuration avoids strapping pins (GPIO2, GPIO8, GPIO9) to prevent boot issues.
Warning: The C3 build currently fails to compile and is untested on hardware. Deep sleep is C6-specific; see the
TODO(c3)note onenter_deep_sleepincrates/core/src/game.rs.
Installation
The firmware is a single Rust binary. There is no separate filesystem or asset upload step. Everything (game logic, sprites, translation strings) is compiled into one image and flashed to the device.
1. Set Up Build Tools (one-time)
Install Rust via rustup if you don't already have it. The rust-toolchain.toml in this repo pins the toolchain and installs the RISC-V targets automatically the first time you build.
Install espflash, which builds, flashes, and monitors the device:
cargo install espflash
The espflash runner is already wired up in .cargo/config.toml, so cargo run on the firmware crate will flash and start a serial monitor.
2. Build and Flash
For ESP32-C6 (default):
cargo run --release
For ESP32-C3:
cargo run --release --no-default-features --features c3 --target riscv32imc-unknown-none-elf
espflash auto-detects the serial port. If you have more than one device connected, pass --port after a -- separator:
cargo run --release -- --port /dev/tty.usbmodem1234
cargo run will build, flash, and drop you into the serial monitor. Press Ctrl+C to exit the monitor without resetting the device.