feat: add requirements and technical baseline
This commit is contained in:
@@ -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
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
+48
-66
@@ -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.
|
||||
|
||||
+2
-2
@@ -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
|
||||
|
||||
|
||||
@@ -1 +1,2 @@
|
||||
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
|
||||
CONFIG_LWIP_MAX_SOCKETS=16
|
||||
|
||||
@@ -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
|
||||
|
||||
#
|
||||
|
||||
Reference in New Issue
Block a user