diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000..9e26695 --- /dev/null +++ b/.clang-format @@ -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 \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index d6d089d..822733f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,6 +44,22 @@ Do not silently choose one requirement over another. - Do not mark a milestone `COMPLETE` without concrete recorded evidence for 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 - 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 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 - 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. - Preserve exact commands and relevant outputs in the active milestone's evidence section. - diff --git a/docs/MVP.md b/MVP.md similarity index 100% rename from docs/MVP.md rename to MVP.md diff --git a/PLANS.md b/PLANS.md index 3fb4270..15cea81 100644 --- a/PLANS.md +++ b/PLANS.md @@ -78,17 +78,19 @@ the read-only project sources. - `MVP.md` contains the complete English product and acceptance specification. - `ARCHITECTURE.md` contains the English runtime, component, state-machine, protocol, memory, failure, and verification contracts. -- `platformio.ini` resolves the environment `esp32-c6-mini` with - `espressif32@7.0.1`, ESP-IDF, explicit 4 MB build/upload size, `partitions.csv`, - LittleFS, and `sdkconfig.defaults`. -- Running `/home/sasa/.platformio/penv/bin/pio project config` successfully - parsed and printed the canonical configuration. PlatformIO subsequently - emitted a sandbox-local telemetry cache permission warning during process - shutdown; it did not prevent configuration parsing. -- Static partition arithmetic verified that the 2 MiB factory application ends - at `0x210000` and the 1,984 KiB LittleFS partition ends at `0x400000`. -- `sdkconfig.defaults` contains `CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y` and - `CONFIG_LWIP_MAX_SOCKETS=16`. +- On 2026-09-03, `/home/sasa/.platformio/penv/bin/pio project config` exited + successfully and resolved environment `esp32-c6-devkitm-1` with + `espressif32@7.0.1`, ESP-IDF, explicit 4 MB build/upload sizes, + `partitions.csv`, LittleFS, and `sdkconfig.defaults`. PlatformIO subsequently + emitted a telemetry-cache permission warning during process shutdown; it did + not prevent configuration parsing. +- On 2026-09-03, an `awk` continuity and end-address check over + `partitions.csv` reported the factory partition ending at `0x210000`, the + LittleFS partition ending at `0x400000`, and no gaps or overlaps from NVS + through the end of Flash. +- 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, no-required-PSRAM baseline and the remaining explicit hardware unknowns. - 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 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 **Status:** `NOT_STARTED` diff --git a/docs/BOARD_PASSPORT.md b/docs/BOARD_PASSPORT.md index 3b4d410..f58e282 100644 --- a/docs/BOARD_PASSPORT.md +++ b/docs/BOARD_PASSPORT.md @@ -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. diff --git a/platformio.ini b/platformio.ini index 44abe5a..cca9c0d 100644 --- a/platformio.ini +++ b/platformio.ini @@ -12,11 +12,11 @@ platform = espressif32 @ 7.0.1 board = esp32-c6-devkitm-1 framework = espidf +board_build.flash_size = 4MB board_build.partitions = partitions.csv board_build.filesystem = littlefs board_build.sdkconfig_defaults = sdkconfig.defaults +board_upload.flash_size = 4MB lib_deps = https://github.com/joltwallet/esp_littlefs.git#v1.20.4 -extra_scripts = monitor_port = /dev/ttyACM0 monitor_speed = 115200 - diff --git a/sdkconfig.defaults b/sdkconfig.defaults index 28720b5..7d50b42 100644 --- a/sdkconfig.defaults +++ b/sdkconfig.defaults @@ -1 +1,2 @@ +CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y CONFIG_LWIP_MAX_SOCKETS=16 diff --git a/sdkconfig.esp32-c6-devkitm-1 b/sdkconfig.esp32-c6-devkitm-1 index f2a1f6c..e1ea586 100644 --- a/sdkconfig.esp32-c6-devkitm-1 +++ b/sdkconfig.esp32-c6-devkitm-1 @@ -1008,24 +1008,16 @@ CONFIG_ESPTOOLPY_FLASHFREQ_80M=y # CONFIG_ESPTOOLPY_FLASHFREQ_20M is not set # default: CONFIG_ESPTOOLPY_FLASHFREQ="80m" -# default: # CONFIG_ESPTOOLPY_FLASHSIZE_1MB is not set -# default: -CONFIG_ESPTOOLPY_FLASHSIZE_2MB=y -# default: -# CONFIG_ESPTOOLPY_FLASHSIZE_4MB is not set -# default: +# CONFIG_ESPTOOLPY_FLASHSIZE_2MB is not set +CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y # CONFIG_ESPTOOLPY_FLASHSIZE_8MB is not set -# default: # CONFIG_ESPTOOLPY_FLASHSIZE_16MB is not set -# default: # CONFIG_ESPTOOLPY_FLASHSIZE_32MB is not set -# default: # CONFIG_ESPTOOLPY_FLASHSIZE_64MB is not set -# default: # CONFIG_ESPTOOLPY_FLASHSIZE_128MB is not set # default: -CONFIG_ESPTOOLPY_FLASHSIZE="2MB" +CONFIG_ESPTOOLPY_FLASHSIZE="4MB" # default: # CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE is not set # default: @@ -3397,11 +3389,11 @@ CONFIG_SD_ENABLE_SDIO_SUPPORT=y # MMU Config # # default: -CONFIG_MMU_PAGE_SIZE_32KB=y +CONFIG_MMU_PAGE_SIZE_64KB=y # default: -CONFIG_MMU_PAGE_MODE="32KB" +CONFIG_MMU_PAGE_MODE="64KB" # default: -CONFIG_MMU_PAGE_SIZE=0x8000 +CONFIG_MMU_PAGE_SIZE=0x10000 # end of MMU Config #