104 lines
3.2 KiB
Markdown
104 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
$HOME/.platformio/penv/bin/pio project config
|
|
```
|
|
|
|
Run the portable host tests and deterministic asset check:
|
|
|
|
```sh
|
|
./scripts/run_host_tests.sh
|
|
```
|
|
|
|
Build the firmware. The PlatformIO hook checks the application image against
|
|
the 2 MiB `factory` partition:
|
|
|
|
```sh
|
|
$HOME/.platformio/penv/bin/pio run
|
|
```
|
|
|
|
Generate compressed assets explicitly when needed:
|
|
|
|
```sh
|
|
$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:
|
|
|
|
```sh
|
|
$HOME/.platformio/penv/bin/pio run --target buildfs
|
|
```
|
|
|
|
## Device commands
|
|
|
|
Upload the application and LittleFS image:
|
|
|
|
```sh
|
|
$HOME$/.platformio/penv/bin/pio run --target upload
|
|
$HOME$/.platformio/penv/bin/pio run --target uploadfs
|
|
```
|
|
|
|
Monitor startup at 115200 baud:
|
|
|
|
```sh
|
|
$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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
$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.
|