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
.clang-format
+25
View File
@@ -0,0 +1,25 @@
BasedOnStyle: LLVM
UseTab: Never
IndentWidth: 4
ContinuationIndentWidth: 4
IndentCaseLabels: true
ColumnLimit: 100
BreakBeforeBraces: Attach
AllowShortFunctionsOnASingleLine: None
AllowShortIfStatementsOnASingleLine: Never
AllowShortLoopsOnASingleLine: false
AllowShortBlocksOnASingleLine: Never
DerivePointerAlignment: false
PointerAlignment: Left
SpaceBeforeParens: ControlStatements
AlignConsecutiveAssignments: None
AlignConsecutiveDeclarations: None
SortIncludes: CaseSensitive
AGENTS.md
+26 -1
View File
@@ -44,6 +44,22 @@ Do not silently choose one requirement over another.
- Do not mark a milestone `COMPLETE` without concrete recorded evidence for - Do not mark a milestone `COMPLETE` without concrete recorded evidence for
every acceptance criterion. every acceptance criterion.
### Commit message handoff
- After completing every user prompt, provide a proposed commit message for
the resulting changes. This is mandatory when completing a milestone.
- Use the Conventional Commits format `type(scope): imperative summary`, or
`type: imperative summary` when no meaningful scope exists.
- Choose exactly one appropriate type from `feat`, `fix`, `refactor`, `perf`,
`test`, `docs`, `style`, `build`, `ci`, `chore`, or `revert`.
- Write the commit message in English, use an imperative summary beginning
with a lowercase verb, keep the subject at 72 characters or fewer when
practical, and do not end it with a period.
- Base the message on the actual completed changes and milestone outcome; do
not use vague summaries such as `update files` or `make changes`.
- Present the proposed commit message in the final response, but do not create
the Git commit unless the user explicitly requests it.
### Locked platform baseline ### Locked platform baseline
- Target ESP32-C6FH4 with 4 MB Flash. - Target ESP32-C6FH4 with 4 MB Flash.
@@ -65,6 +81,16 @@ Do not silently choose one requirement over another.
- Active game state need not survive reboot; Wi-Fi configuration must persist - Active game state need not survive reboot; Wi-Fi configuration must persist
in NVS. in NVS.
### Code style
- Follow the repository `.clang-format`.
- Format all modified C and C++ files with `clang-format`.
- Prefer simple, explicit code that is easy for beginners to read.
- Avoid clever one-liners and unnecessary abstractions.
- Use braces for all non-trivial control-flow blocks.
- Prefer descriptive variable and function names.
- Keep functions reasonably small.
### Build and verification ### Build and verification
- Parse the project configuration with - Parse the project configuration with
@@ -78,4 +104,3 @@ Do not silently choose one requirement over another.
- Test on the physical board before recording hardware acceptance evidence. - Test on the physical board before recording hardware acceptance evidence.
- Preserve exact commands and relevant outputs in the active milestone's - Preserve exact commands and relevant outputs in the active milestone's
evidence section. evidence section.
docs/MVP.md → MVP.md
View File
PLANS.md
+19 -11
View File
@@ -78,17 +78,19 @@ the read-only project sources.
- `MVP.md` contains the complete English product and acceptance specification. - `MVP.md` contains the complete English product and acceptance specification.
- `ARCHITECTURE.md` contains the English runtime, component, state-machine, - `ARCHITECTURE.md` contains the English runtime, component, state-machine,
protocol, memory, failure, and verification contracts. protocol, memory, failure, and verification contracts.
- `platformio.ini` resolves the environment `esp32-c6-mini` with - On 2026-09-03, `/home/sasa/.platformio/penv/bin/pio project config` exited
`espressif32@7.0.1`, ESP-IDF, explicit 4 MB build/upload size, `partitions.csv`, successfully and resolved environment `esp32-c6-devkitm-1` with
LittleFS, and `sdkconfig.defaults`. `espressif32@7.0.1`, ESP-IDF, explicit 4 MB build/upload sizes,
- Running `/home/sasa/.platformio/penv/bin/pio project config` successfully `partitions.csv`, LittleFS, and `sdkconfig.defaults`. PlatformIO subsequently
parsed and printed the canonical configuration. PlatformIO subsequently emitted a telemetry-cache permission warning during process shutdown; it did
emitted a sandbox-local telemetry cache permission warning during process not prevent configuration parsing.
shutdown; it did not prevent configuration parsing. - On 2026-09-03, an `awk` continuity and end-address check over
- Static partition arithmetic verified that the 2 MiB factory application ends `partitions.csv` reported the factory partition ending at `0x210000`, the
at `0x210000` and the 1,984 KiB LittleFS partition ends at `0x400000`. LittleFS partition ending at `0x400000`, and no gaps or overlaps from NVS
- `sdkconfig.defaults` contains `CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y` and through the end of Flash.
`CONFIG_LWIP_MAX_SOCKETS=16`. - On 2026-09-03, `rg` confirmed
`CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y` and `CONFIG_LWIP_MAX_SOCKETS=16` in both
`sdkconfig.defaults` and the generated ESP-IDF configuration.
- `docs/BOARD_PASSPORT.md` records the confirmed ESP32-C6FH4, 4 MB Flash, - `docs/BOARD_PASSPORT.md` records the confirmed ESP32-C6FH4, 4 MB Flash,
no-required-PSRAM baseline and the remaining explicit hardware unknowns. no-required-PSRAM baseline and the remaining explicit hardware unknowns.
- Canonical files were created outside `sources/`; the reference files under - Canonical files were created outside `sources/`; the reference files under
@@ -101,6 +103,12 @@ claim that firmware source code exists, that a firmware image builds, or that
the target board has passed runtime tests. Those claims require evidence in the target board has passed runtime tests. Those claims require evidence in
later milestones. later milestones.
Milestone 001 was reopened on 2026-09-03 after its recorded evidence was found
to disagree with the checked-in canonical files. The canonical `MVP.md`
location, explicit Flash configuration, generated SDK configuration, and board
passport were repaired and reverified before returning the milestone to
`COMPLETE`. No Milestone 002 implementation work was started.
## Milestone 002 — Firmware skeleton and reproducible build ## Milestone 002 — Firmware skeleton and reproducible build
**Status:** `NOT_STARTED` **Status:** `NOT_STARTED`
docs/BOARD_PASSPORT.md
+48 -66
View File
@@ -1,84 +1,66 @@
# Board passport # Board passport
## Identification status ## Confirmed hardware
The target PCB has not been identified from physical markings. No photograph The target contains an ESP32-C6FH4 (chip revision 0.2) with 4 MB of embedded
of the markings is available in the repository and no `sources/` directory is Flash and a 40 MHz crystal. It was identified electronically on 2026-08-27 with
present. A read-only `esptool.py flash_id` probe did identify the installed SoC `esptool.py` 4.11.0 through the native Espressif USB Serial/JTAG interface at
and flash, but it cannot identify the PCB manufacturer, board model/revision, `/dev/ttyACM0` (USB VID:PID `303a:1001`). No PSRAM was reported or is required.
built-in LED, or board-specific pinout.
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 ## Locked project baseline
markings;
- the manufacturer's product page, schematic, and pinout matching those
markings;
- the PCB/model ordering code that matches the photographs.
## Confirmed electronically The canonical build uses:
On 2026-08-27, the board appeared as `/dev/ttyACM0` with USB VID:PID - PlatformIO with `platformio/espressif32@7.0.1`;
`303a:1001` and product name `Espressif USB JTAG/serial debug unit`. - ESP-IDF;
`esptool.py` 4.11.0 reported: - 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; The PlatformIO board profile is a compatible compilation target. It is not
- 4 MB embedded flash, with 4 MB detected; evidence that the physical carrier is an Espressif ESP32-C6-DevKitM-1.
- 40 MHz crystal;
- native USB-Serial/JTAG mode.
The ESP32-C6FH4 ordering code and probe establish the 4 MB in-package flash. ## Canonical Flash layout
No PSRAM was reported. These are chip-level facts; they do not establish the
carrier PCB model or its LED and pin routing.
## 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 | 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
| PlatformIO Core | 6.1.19 | Installed locally | layout ends exactly at the confirmed 4 MB boundary. The area below `0x9000` is
| PlatformIO platform | `platformio/espressif32` 7.0.1 | Installed locally; `platformio.ini` is not version-pinned | reserved for the bootloader and partition table by the ESP-IDF layout.
| 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 current configuration is not yet a reproducible baseline: its generated ## Explicit unknowns
SDK configuration must be changed from 2 MB to the confirmed 4 MB and its
partition table must add LittleFS before firmware is uploaded.
## 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 - carrier PCB manufacturer, model, or revision;
ESP32-C6-DevKitM-1, the matching authoritative references are: - 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 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-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) - [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.
platformio.ini
+2 -2
View File
@@ -12,11 +12,11 @@
platform = espressif32 @ 7.0.1 platform = espressif32 @ 7.0.1
board = esp32-c6-devkitm-1 board = esp32-c6-devkitm-1
framework = espidf framework = espidf
board_build.flash_size = 4MB
board_build.partitions = partitions.csv board_build.partitions = partitions.csv
board_build.filesystem = littlefs board_build.filesystem = littlefs
board_build.sdkconfig_defaults = sdkconfig.defaults board_build.sdkconfig_defaults = sdkconfig.defaults
board_upload.flash_size = 4MB
lib_deps = https://github.com/joltwallet/esp_littlefs.git#v1.20.4 lib_deps = https://github.com/joltwallet/esp_littlefs.git#v1.20.4
extra_scripts =
monitor_port = /dev/ttyACM0 monitor_port = /dev/ttyACM0
monitor_speed = 115200 monitor_speed = 115200
sdkconfig.defaults
+1
View File
@@ -1 +1,2 @@
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
CONFIG_LWIP_MAX_SOCKETS=16 CONFIG_LWIP_MAX_SOCKETS=16
sdkconfig.esp32-c6-devkitm-1
+6 -14
View File
@@ -1008,24 +1008,16 @@ CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
# CONFIG_ESPTOOLPY_FLASHFREQ_20M is not set # CONFIG_ESPTOOLPY_FLASHFREQ_20M is not set
# default: # default:
CONFIG_ESPTOOLPY_FLASHFREQ="80m" CONFIG_ESPTOOLPY_FLASHFREQ="80m"
# default:
# CONFIG_ESPTOOLPY_FLASHSIZE_1MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_1MB is not set
# default: # CONFIG_ESPTOOLPY_FLASHSIZE_2MB is not set
CONFIG_ESPTOOLPY_FLASHSIZE_2MB=y CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
# default:
# CONFIG_ESPTOOLPY_FLASHSIZE_4MB is not set
# default:
# CONFIG_ESPTOOLPY_FLASHSIZE_8MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_8MB is not set
# default:
# CONFIG_ESPTOOLPY_FLASHSIZE_16MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_16MB is not set
# default:
# CONFIG_ESPTOOLPY_FLASHSIZE_32MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_32MB is not set
# default:
# CONFIG_ESPTOOLPY_FLASHSIZE_64MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_64MB is not set
# default:
# CONFIG_ESPTOOLPY_FLASHSIZE_128MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_128MB is not set
# default: # default:
CONFIG_ESPTOOLPY_FLASHSIZE="2MB" CONFIG_ESPTOOLPY_FLASHSIZE="4MB"
# default: # default:
# CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE is not set # CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE is not set
# default: # default:
@@ -3397,11 +3389,11 @@ CONFIG_SD_ENABLE_SDIO_SUPPORT=y
# MMU Config # MMU Config
# #
# default: # default:
CONFIG_MMU_PAGE_SIZE_32KB=y CONFIG_MMU_PAGE_SIZE_64KB=y
# default: # default:
CONFIG_MMU_PAGE_MODE="32KB" CONFIG_MMU_PAGE_MODE="64KB"
# default: # default:
CONFIG_MMU_PAGE_SIZE=0x8000 CONFIG_MMU_PAGE_SIZE=0x10000
# end of MMU Config # end of MMU Config
# #