sasa/maze32
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add requirements and technical baseline

Browse Source
This commit is contained in:
sasa
2026-09-03 00:07:15 +03:00
parent 65fe630333
commit dd16bc7ade
8 changed files with 127 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/BOARD_PASSPORT.md
+48 -66
View File
@@ -1,84 +1,66 @@
# Board passport
## Identification status
## Confirmed hardware
The target PCB has not been identified from physical markings. No photograph
of the markings is available in the repository and no `sources/` directory is
present. A read-only `esptool.py flash_id` probe did identify the installed SoC
and flash, but it cannot identify the PCB manufacturer, board model/revision,
built-in LED, or board-specific pinout.
The target contains an ESP32-C6FH4 (chip revision 0.2) with 4 MB of embedded
Flash and a 40 MHz crystal. It was identified electronically on 2026-08-27 with
`esptool.py` 4.11.0 through the native Espressif USB Serial/JTAG interface at
`/dev/ttyACM0` (USB VID:PID `303a:1001`). No PSRAM was reported or is required.
Required evidence to unblock Milestone 000:
These observations establish chip-level facts only. The carrier PCB maker,
commercial model, revision, GPIO routing, and any built-in LED remain unknown.
Firmware must not depend on those unverified details.
- clear photographs of both sides of the board, including all PCB and module
markings;
- the manufacturer's product page, schematic, and pinout matching those
markings;
- the PCB/model ordering code that matches the photographs.
## Locked project baseline
## Confirmed electronically
The canonical build uses:
On 2026-08-27, the board appeared as `/dev/ttyACM0` with USB VID:PID
`303a:1001` and product name `Espressif USB JTAG/serial debug unit`.
`esptool.py` 4.11.0 reported:
- PlatformIO with `platformio/espressif32@7.0.1`;
- ESP-IDF;
- the compatible `esp32-c6-devkitm-1` build profile;
- explicit 4 MB build and upload Flash sizes;
- `sdkconfig.defaults` with 4 MB Flash and 16 LwIP sockets;
- the root `partitions.csv` layout;
- LittleFS for browser assets;
- no OTA partition and no PSRAM requirement.
- ESP32-C6FH4 in QFN32, chip revision 0.2;
- 4 MB embedded flash, with 4 MB detected;
- 40 MHz crystal;
- native USB-Serial/JTAG mode.
The PlatformIO board profile is a compatible compilation target. It is not
evidence that the physical carrier is an Espressif ESP32-C6-DevKitM-1.
The ESP32-C6FH4 ordering code and probe establish the 4 MB in-package flash.
No PSRAM was reported. These are chip-level facts; they do not establish the
carrier PCB model or its LED and pin routing.
## Canonical Flash layout
## Current repository baseline (not hardware confirmation)
| Name | Type | Subtype | Offset | Size | End |
| ---------- | ---- | -------- | --------- | ---------- | ---------- |
| `nvs` | data | nvs | `0x9000` | `0x6000` | `0xF000` |
| `phy_init` | data | phy | `0xF000` | `0x1000` | `0x10000` |
| `factory` | app | factory | `0x10000` | `0x200000` | `0x210000` |
| `littlefs` | data | littlefs | `0x210000`| `0x1F0000` | `0x400000` |
| Item | Observed value | Status |
| ---------------------------- | ------------------------------- | --------------------------------------------------------------------- |
| PlatformIO Core | 6.1.19 | Installed locally |
| PlatformIO platform | `platformio/espressif32` 7.0.1 | Installed locally; `platformio.ini` is not version-pinned |
| Framework | ESP-IDF 6.0.1 | Current project setting conflicts with the Arduino-first MVP baseline |
| Arduino Core | Not installed | Cannot be pinned and verified against this board yet |
| PlatformIO board | `esp32-c6-devkitm-1` | Unverified candidate, not evidence of the physical model |
| Board-profile flash size | 4 MB | Unverified; profile metadata only |
| Detected physical flash size | 4 MB | Confirmed by `esptool.py flash_id` |
| Generated SDK flash size | 2 MB | Conflicts with the detected hardware and board profile |
| Generated partition table | Single application, no LittleFS | Does not meet Milestone 000 |
The partitions are contiguous from NVS through the end of Flash. The factory
application partition is 2 MiB, the LittleFS partition is 1,984 KiB, and the
layout ends exactly at the confirmed 4 MB boundary. The area below `0x9000` is
reserved for the bootloader and partition table by the ESP-IDF layout.
The current configuration is not yet a reproducible baseline: its generated
SDK configuration must be changed from 2 MB to the confirmed 4 MB and its
partition table must add LittleFS before firmware is uploaded.
## Explicit unknowns
## Candidate reference only
The following facts have not been verified and must not be assumed:
If the physical markings prove that the board is an Espressif
ESP32-C6-DevKitM-1, the matching authoritative references are:
- carrier PCB manufacturer, model, or revision;
- header and peripheral GPIO mapping;
- presence, GPIO, polarity, or type of a built-in LED;
- whether the carrier uses native USB only or includes another USB bridge;
- availability of optional external RAM or peripherals.
Clear photographs of both sides of the board and matching manufacturer
documentation are required before adopting any carrier-specific pin mapping.
## Candidate documentation
The `esp32-c6-devkitm-1` PlatformIO profile is used for compatibility only.
Espressif's DevKitM-1 documentation may be consulted as a candidate reference,
but its PCB-specific details remain noncanonical until physical markings prove
that the target is that model:
- [ESP32-C6-DevKitM-1 user guide](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c6/esp32-c6-devkitm-1/user_guide.html)
- [ESP32-C6-DevKitM-1 schematic](https://docs.espressif.com/projects/esp-dev-kits/en/latest/_static/esp32-c6-devkitm-1/schematics/esp32-c6-devkitm-1-schematics.pdf)
- [ESP32-C6-MINI-1 datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c6-mini-1_mini-1u_datasheet_en.pdf)
For that board only, Espressif documents an ESP32-C6-MINI-1(U) module with
4 MB in-package SPI flash, no PSRAM, a USB-C connector connected through a
USB-to-UART bridge, UART0 on GPIO16/GPIO17, native USB D-/D+ on GPIO12/GPIO13,
and an addressable RGB LED on GPIO8. These values are deliberately not adopted
as the target specifications until the markings match.
## Memory map and partition status
No partition CSV has been selected yet. The confirmed 4 MB capacity permits a
layout reserving, at minimum, NVS, PHY initialization, one application
partition, and one LittleFS data partition. Exact offsets and sizes still need
to be defined and checked against the framework's bootloader and partition
alignment requirements.
## Risks carried to the next action
- A generic “ESP32-C6 Mini” may not match Espressif's DevKitM-1 pinout, LED
polarity/type, or USB bridge. The flash capacity is confirmed independently.
- GPIO8, GPIO12, GPIO13, GPIO16, and GPIO17 must not be assigned from the
candidate documentation until the exact board is confirmed.
- Official `platformio/espressif32` 7.0.1 exposes the C6 DevKitM profile only
for ESP-IDF and its bundled Arduino Core 2.0.17 does not support ESP32-C6.
An exact Arduino-compatible PlatformIO platform/Core pairing must be chosen
and pinned after the board is identified, then proven by Milestone 001.
docs/MVP.md
-280
View File
@@ -1,280 +0,0 @@
# maze32 MVP
## 1. Product goal
maze32 is a local browser-based multiplayer maze race hosted by one ESP32-C6.
Two players explore the same maze in real time, search for their own keys and
exits, and try to leave first. Up to four observers may watch the complete
match.
The MVP must produce a fair, playable match whose normal target duration is
approximately five minutes. There is no match time limit.
## 2. Runtime model
- One ESP32-C6 runs the HTTP server, WebSocket server, maze generator, and the
authoritative game simulation.
- Both players and all observers use ordinary web browsers.
- Clients send intentions such as move or drop-key; they never determine the
result of an action locally.
- The server validates action order, movement cooldowns, collisions, item
ownership, visibility, victory, and draws.
- The server must never send hidden game state to a player client. Fog of war
is enforced when constructing the server response, not merely by hiding
elements in the browser.
## 3. Roles and lobby
### Players
- Exactly two player slots exist: Player 1 and Player 2.
- A player joins with a unique display name and receives a temporary session
token.
- The UI may suggest humorous available names.
- The first player becomes the lobby owner and is the only player who may
start the match.
- The second player is a participant without start authority.
- The match can start only when both player slots are occupied.
- Refreshing the browser restores the same player, slot, position, inventory,
and match state through the session token.
### Observers
- Up to four observers may connect without a password.
- Observers do not consume player slots.
- Observers are read-only: they cannot start, pause, or control a match.
- An observer sees the entire maze without fog of war, both current player
positions, keys and their holders, exits, compasses, vision artifacts, match
status, connection state, and final result.
- An observer disconnect does not pause the match.
### Start sequence
- When the lobby owner starts a ready match, both players receive the same
`3-2-1` countdown.
- Movement is rejected until the countdown completes.
- Both players become active at the same authoritative server instant.
## 4. Maze
### Dimensions and representation
- The initial configuration is `width = 128`, `height = 64`, or 8,192 cells.
- Width and height are runtime configuration values and must not be hard-coded
into game logic.
- Movement is orthogonal between cells; diagonal movement does not exist.
- Every playable cell and required object must be reachable.
### Symmetry and topology
- Geometry uses central symmetry under a 180-degree rotation:
`(x, y) -> (width - 1 - x, height - 1 - y)`.
- Player 2's start, key, exit, and other fairness-relevant placements are the
rotated counterparts of Player 1's placements.
- The maze contains cycles, alternative routes, dead ends, and many passages
between its conceptual halves.
- Players can enter either half through multiple routes, but the UI must not
identify a cell as belonging to either player.
- The maze is not a perfect maze with only one route between points.
### Starts, keys, and exits
- Players start at opposite, rotationally symmetric entrance cells.
- An entrance is only the starting point; it is not the player's exit.
- Each player has one unique key and one unique exit.
- A key opens only its matching exit, and only the owner of that key and exit
can win through them.
- Key and exit pairs are placed rotationally symmetrically and at equal route
distances for both players.
- Each key begins outside its owner's initial field of view.
- Each exit may be at any distant valid symmetric location.
- Map generation must make finding the key at least as challenging as the
subsequent search for the correct exit. Exact balance thresholds are
tunable and must be validated through generation metrics and playtesting.
### Landmarks and generated objects
- The maze contains visually distinctive landmarks to support human spatial
memory even though explored territory is not retained.
- Fairness-relevant landmarks and vision artifacts are generated in
rotationally symmetric pairs.
- The exact number and density of landmarks and artifact pairs are tunable
balance parameters. The MVP must place more than one vision artifact.
## 5. Movement and player interaction
- One accepted input moves a player by exactly one traversable cell in one of
four directions: up, down, left, or right.
- Players act independently; the server does not wait for alternating or
simultaneous turns.
- A small server-enforced minimum interval exists between accepted moves. Its
value is configurable for playtesting.
- Rejected movement into a wall does not change position and is not a
successful move.
- Players do not block each other and may occupy the same cell.
- A meeting occurs when both players occupy the same cell.
- There are no attacks, health, damage, or other combat mechanics in MVP.
Browser controls must support:
- keyboard movement on computers;
- directional swipes on touchscreens;
- an accessible drop-key action for both control modes.
## 6. Keys and inventory
- A player may carry at most one key.
- A player may pick up either key if the inventory slot is empty.
- The carried key disappears from its map cell and becomes server-owned
inventory state.
- A player always sees which key they carry.
- A player may voluntarily drop either their own or the opponent's key. It is
placed on the player's current cell.
- Entering a cell containing a key while already carrying one does not pick up
the second key.
- A player may carry the opponent's key elsewhere and drop it as sabotage.
- When players meet, every carried key is automatically transferred to its
correct owner. If both carry each other's keys, the keys swap owners in the
same authoritative event.
- Outside the current field of view, a player receives no information that the
opponent found, dropped, or carries a key.
- When the opponent is visible, their carried key identity is visible too.
- A player cannot open or use the opponent's exit, even while carrying the
matching opponent key.
## 7. Fog of war
- Normal vision radius is three cells around the player.
- Walls do not block vision.
- For the MVP, radius uses a square/Chebyshev neighborhood: a radius of three
exposes at most a `7 x 7` cell area, clipped by map boundaries.
- Once a cell leaves the current vision area it becomes completely unknown
again; there is no explored-map memory.
- Hidden cells reveal neither maze geometry nor stale objects or player
positions.
- The opponent is visible only while inside the current vision area and
disappears immediately after leaving it.
- Observers are exempt from fog of war.
## 8. Vision artifacts and compasses
### Vision artifacts
- The map contains multiple one-use vision artifacts.
- Entering an artifact cell activates it immediately and removes it from the
map; it cannot be stored or reused.
- The effect increases vision radius from three to six cells.
- The effect lasts for the next ten successful moves by that player.
- Failed move attempts do not consume an effect move.
- Additional artifact types are outside the MVP.
### Compasses
- The maze contains two stationary compasses, one associated with each
player's exit and placed fairly as a symmetric pair.
- A compass cannot be picked up.
- A player must enter the appropriate compass cell to activate its hint.
- On activation, the UI displays an arrow pointing toward that player's own
exit.
- A compass does not reveal a route or the exit coordinates.
## 9. Exit, victory, and draw
- A player can open only their own exit and only with their own key.
- Opening the exit is not itself a victory.
- After opening it, the player must perform one additional valid outward move
beyond the maze boundary through that exit.
- The server records the authoritative exit time.
- The first player to complete the outward move wins.
- If both authoritative exit times fall within a 200 ms window, the result is
a draw.
- The normal target match duration is approximately five minutes, but a
connected match continues indefinitely until victory or another defined draw
condition.
## 10. Connectivity and recovery
### Wi-Fi provisioning
- In normal operation the ESP connects to a previously configured Wi-Fi
network in station mode.
- Network credentials are stored in NVS and reused after reboot.
- When the configured network is unavailable or credentials have not been
saved, the ESP starts a fallback access point.
- The fallback web interface allows the user to configure and save an existing
Wi-Fi network.
### Player disconnection
- Loss of either player's WebSocket connection pauses the authoritative match.
- No player movement or turn-based effect duration advances while paused.
- The disconnected player has 60 seconds to reconnect with the existing
session token.
- A successful reconnect restores the same slot and resumes the same match
state.
- If the player does not reconnect within 60 seconds, the match ends in a draw.
- Reloading a page is treated as a reconnect, not as leaving the match.
## 11. Technical constraints
- Target: ESP32-C6FH4, 4 MB Flash, no required PSRAM.
- Build: PlatformIO, `espressif32@7.0.1`, ESP-IDF, compatible
`esp32-c6-devkitm-1` profile.
- Flash layout: 2 MiB factory application and 1,984 KiB LittleFS; no OTA in
MVP.
- Static browser assets reside in LittleFS and should be compressed for the
production image.
- HTTP serves the application and provisioning pages; WebSocket carries live
lobby, control, and match messages.
- The initial LwIP socket limit is 16.
- The implementation must be tested with two player connections and four
simultaneous observer connections on the physical device.
- Active lobby and match state may live in RAM and need not survive an ESP
reboot. Wi-Fi settings must survive reboot.
## 12. MVP acceptance criteria
The MVP is accepted when all of the following are demonstrated on the target
board:
1. The firmware builds with the locked PlatformIO configuration and fits the
application and LittleFS partitions.
2. Wi-Fi station setup persists in NVS, and failed station connection exposes
the fallback access-point configuration flow.
3. Two browsers can claim unique player names, restore their slots after page
refresh, enter the lobby, and start through the owner-controlled countdown.
4. Four additional browsers can observe the complete match simultaneously
without receiving control authority.
5. Repeatedly generated `128 x 64` maps are connected, centrally symmetric,
contain cycles and multiple cross-half passages, and preserve equal
player-relative placement metrics.
6. Player clients never receive cells or dynamic objects outside their current
allowed view; observer clients receive the complete state.
7. Keyboard and touch controls produce server-validated single-cell movement
with an enforced configurable cooldown.
8. Key pickup, one-slot inventory, dropping, sabotage, automatic owner return,
door restrictions, and visible-carried-key rules behave as specified.
9. Vision artifacts expand the view for exactly ten successful moves, and
compass cells display the correct direction to the activating player's own
exit.
10. An outward move through an opened own exit determines victory, and exits
within 200 ms produce a draw.
11. A player disconnect pauses the match, reconnection restores it, and a
60-second reconnect timeout ends it as a draw.
12. A representative match normally completes in approximately five minutes
after balance tuning, without imposing a hard match timer.
## 13. Explicitly outside MVP
- More than two active players or more than one concurrent match.
- More than four observers.
- Persistent accounts, passwords, cloud services, matchmaking, or internet
play.
- Spectator control or moderation tools.
- Physical display or gameplay buttons.
- ESP-NOW, BLE multiplayer, or multiple-device game simulation.
- Additional artifact types, combat, health, traps, or player elimination.
- Persistent match recovery after ESP reboot.
- OTA firmware partitions and OTA update flow.
- Dependence on PSRAM, an unverified LED, or an assumed board pinout.