Build from source

The firmware is a Rust project. The source code is in the source code repository (link coming soon), under the MIT license. The ESP32-C3 and C6 use the standard Rust toolchain (RISC-V targets); the ESP32-S3 needs Espressif’s esp toolchain for Xtensa, installed by espup.

One-time setup – Rust targets, espflash, the esp toolchain for the S3 (add WITH_ELO=1 for Stockfish and fastchess to measure strength):

git clone <repository-url> esp32rustchess && cd esp32rustchess
WITH_S3=1 scripts/unix/setup.sh

On Linux the script adds you to the uucp / dialout group – log out and in again.

Build and flash – the chip is selected with CHIP:

scripts/unix/flash.sh                         # ESP32-C6 with display (default)
CHIP=esp32c3 scripts/unix/flash.sh            # ESP32-C3
CHIP=esp32s3 scripts/unix/flash.sh            # ESP32-S3
PORT=/dev/ttyACM1 CHIP=esp32s3 scripts/unix/flash.sh   # several boards connected
scripts/unix/monitor.sh                       # serial console only

Update: git pull and flash again.

One-time setup in PowerShell (open a new window after each install):

winget install --id Git.Git -e
winget install --id Rustlang.Rustup -e
winget install --id Microsoft.VisualStudio.2022.BuildTools -e --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

mkdir C:\esp; cd C:\esp           # a short path helps the S3 toolchain
git clone <repository-url> esp32rustchess
cd esp32rustchess
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
.\scripts\setup.ps1                 # Rust target for the C6, espflash
rustup target add riscv32imc-unknown-none-elf
cargo install espup --locked
espup install --targets esp32s3

Find the board’s port with espflash list-ports (espflash board-info --port COM5 shows the chip).

ESP32-C6:

.\scripts\flash.ps1 -Port COM5

ESP32-C3:

cd firmware
cargo build --release --no-default-features --features esp32c3 --target riscv32imc-unknown-none-elf
espflash flash --chip esp32c3 --partition-table partitions.csv --port COM6 target\riscv32imc-unknown-none-elf\release\esp32-chess

ESP32-S3:

cd firmware
cargo +esp build --release -Zbuild-std=core,alloc --no-default-features --features esp32s3 --target xtensa-esp32s3-none-elf
espflash flash --chip esp32s3 --partition-table partitions.csv --port COM7 target\xtensa-esp32s3-none-elf\release\esp32-chess
espflash reset --chip esp32s3 --port COM7

Do not flash with --flash-mode qio – several boards do not boot in QIO mode. If a board stops responding, hold BOOT, press RST, release BOOT and flash again.

Develop without a board

The simulator runs the same game hub, engine and web app on a PC:

cargo run --release -p chess-sim          # http://localhost:8080
cargo run --release -p chess-sim -- --uci # the engine as a UCI program (Arena, cutechess, …)
cargo test                                # unit tests of all libraries

Measure strength yourself

With all boards connected (for example through a USB hub):

WITH_ELO=1 scripts/unix/setup.sh
PROBE=1 scripts/unix/elo-all.sh                       # quick probe, ~15 min
LEVELS_esp32s3="2100 2400 2700" scripts/unix/elo-all.sh   # full run, ~15 h
scripts/unix/turnaj.sh                                # round robin between the boards
scripts/unix/elo-fit.py bench-results/elo-* bench-results/turnaj-*

Firmware for the browser installer

scripts/unix/site-firmware.sh     # merged images + manifest in site/static/firmware/

How it works