maze32/README.md

maze32

maze32 is an ESP32-C6-hosted browser maze game. The firmware mounts LittleFS, serves compressed local pages, exposes a bounded health response, and connects to saved Wi-Fi credentials or starts a fallback provisioning access point.

Prerequisites

• PlatformIO Core installed at $HOME/.platformio/penv/bin/pio;
• a C11 host compiler available as cc;
• Python 3.

Build and verify

Parse the locked PlatformIO configuration:

$HOME/.platformio/penv/bin/pio project config

Run the portable host tests and deterministic asset check:

./scripts/run_host_tests.sh

Build the firmware. The PlatformIO hook checks the application image against the 2 MiB factory partition:

$HOME/.platformio/penv/bin/pio run

Generate compressed assets explicitly when needed:

$HOME/.platformio/penv/bin/python scripts/generate_web_assets.py

Build the LittleFS image. Asset generation runs automatically before packaging, and the PlatformIO hook checks the image against the 1,984 KiB littlefs partition:

$HOME/.platformio/penv/bin/pio run --target buildfs

Device commands

Upload the application and LittleFS image:

$HOME$/.platformio/penv/bin/pio run --target upload
$HOME$/.platformio/penv/bin/pio run --target uploadfs

Monitor startup at 115200 baud:

$HOME/.platformio/penv/bin/pio device monitor

A successful boot reports the firmware version, LittleFS capacity and use, network state, HTTP service startup, and health state serving.

The production integration/load procedure and its fixed resource thresholds are documented in docs/INTEGRATION_TESTING.md and docs/RESOURCE_BUDGET.md. Runtime counters and internal-memory samples are available from GET /diagnostics; the endpoint contains no credentials, session tokens, or game projection.

Wi-Fi provisioning and recovery

With no saved credentials, or after a failed station connection, the device starts an open access point named maze32-XXXX, where XXXX comes from the device MAC address. Connect to it and open:

http://192.168.4.1/provision

Scan for nearby networks, select or enter an SSID, and save the password. The device stores a schema-versioned configuration in NVS and retries in station mode. If the attempt fails, the fallback access point returns automatically. After a successful connection, /api/wifi/status reports the station address.

To recover from obsolete or incorrect credentials, reconnect to the fallback access point after the failed attempt and use Удалить настройки сети. The same reset operation is available as POST /api/wifi/reset. Saving or clearing credentials always invokes the runtime reconfiguration guard first; a future active match service can reject the operation until it has explicitly stopped the match.

The isolated on-device NVS/reboot diagnostic uses a deliberately unavailable SSID, refuses to overwrite unexpected saved credentials, and clears its test record after verifying fallback recovery:

$HOME/.platformio/penv/bin/pio run -e milestone-003-device-test
$HOME/.platformio/penv/bin/pio run -e milestone-003-device-test --target upload

Restore the normal firmware afterward with the standard upload command.