# 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/sasa/.platformio/penv/bin/pio`;
- a C11 host compiler available as `cc`;
- Python 3.

## Build and verify

Parse the locked PlatformIO configuration:

```sh
/home/sasa/.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/sasa/.platformio/penv/bin/pio run
```

Generate compressed assets explicitly when needed:

```sh
/home/sasa/.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/sasa/.platformio/penv/bin/pio run --target buildfs
```

## Device commands

Upload the application and LittleFS image:

```sh
/home/sasa/.platformio/penv/bin/pio run --target upload
/home/sasa/.platformio/penv/bin/pio run --target uploadfs
```

Monitor startup at 115200 baud:

```sh
/home/sasa/.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`.

## 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/sasa/.platformio/penv/bin/pio run -e milestone-003-device-test
/home/sasa/.platformio/penv/bin/pio run -e milestone-003-device-test --target upload
```

Restore the normal firmware afterward with the standard upload command.