Skip to content

Setting Up ESP32 Hardware

Jump to bottom
Moonbench edited this page Oct 5, 2026 · 2 revisions

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 on enter_deep_sleep in crates/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.

Clone this wiki locally