Expand and clarify AGENTS.md with detailed repository structure, critical development constraints, build/flash instructions, and validation guidelines.
This commit is contained in:
Kai Börnert
121
AGENTS.md
121
AGENTS.md
@@ -1,61 +1,94 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Scope
|
||||
These instructions apply to the entire repository unless a deeper `AGENTS.md` overrides them.
|
||||
|
||||
## Repository Overview
|
||||
`PlantCtrl` is a mixed-discipline repository with embedded firmware, shared Rust crates, hardware design files, and a Hugo-based website.
|
||||
`PlantCtrl` is a mixed-discipline repo: two embedded Rust firmware targets, a shared crate, KiCad hardware, and a Hugo site.
|
||||
|
||||
Top-level layout:
|
||||
- `Software/MainBoard/rust`: main embedded Rust firmware for the controller board (`plant-ctrl2`).
|
||||
- `Software/CAN_Sensor`: embedded Rust firmware for the CAN sensor / BMS board.
|
||||
- `Software/Shared/canapi`: shared Rust crate used by firmware projects.
|
||||
- `Hardware`: PCB, case, and related hardware design assets.
|
||||
- `Software/MainBoard/rust`: main firmware (`plant-ctrl2`) for ESP32-C6 controller board.
|
||||
- `Software/CAN_Sensor`: sensor firmware (`bms`) for CH32V203C8T6 (CAN sensor / BMS board).
|
||||
- `Software/Shared/canapi`: shared crate for CAN protocol/serialization — consumed by both firmware targets.
|
||||
- `Hardware`: KiCad PCB designs and 3D case files.
|
||||
- `DataSheets`: reference material; treat as source data, not generated output.
|
||||
- `website`: Hugo site based on the Blowfish theme.
|
||||
- `bin`: helper scripts and local tooling, if present.
|
||||
- `website`: Hugo site (Blowfish theme via git submodule at `website/themes/blowfish`).
|
||||
- `bin`: helper scripts and dev tooling.
|
||||
|
||||
## Critical Constraints
|
||||
- **No Cargo workspace** — each project has its own `Cargo.toml` and `Cargo.lock`. Run checks with `--manifest-path`.
|
||||
- **Both firmware targets require `nightly` toolchain** (`rust-toolchain.toml`). Main board uses `build-std = ["alloc", "core"]` in `.cargo/config.toml`.
|
||||
- **`no_std`/`no_main`** — both firmware crates are bare-metal. Do not introduce `std`-only dependencies.
|
||||
- **Main board clippy rules** (`src/main.rs`): `#![deny(clippy::mem_forget, clippy::unwrap_used, clippy::expect_used, clippy::panic)]`. Do not add `#[allow(...)]` without explicit user request.
|
||||
- **mcutie** (`src/mcutie_3_0_0/`): vendored sub-crate with `#![deny(unreachable_pub)]` and `#![warn(missing_docs)]`.
|
||||
- **Flash layout** (main board `partitions.csv`): 16 MB total — `ota_0` (3968K), `ota_1` (3968K), `storage` (8M LittleFS), `nvs` (16K), `otadata` (8K), `phy_init` (4K).
|
||||
- **CH32V203C8T6 memory** (`CAN_Sensor/memory.x`): 64 KB flash, 20 KB RAM. Tight budget — avoid allocations.
|
||||
- **ESP IDF config** (`sdkconfig.defaults`): `CONFIG_ESP_MAIN_TASK_STACK_SIZE=50000`, `CONFIG_FREERTOS_HZ=1000`, `CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE=y`.
|
||||
|
||||
## Firmware Build & Flash
|
||||
|
||||
### Main Board (ESP32-C6)
|
||||
```
|
||||
# Quick check (no build):
|
||||
cargo check --manifest-path Software/MainBoard/rust/Cargo.toml
|
||||
|
||||
# Full build + flash + monitor:
|
||||
bash Software/MainBoard/rust/flash.sh
|
||||
|
||||
# Build only (no flash):
|
||||
cargo build --release --manifest-path Software/MainBoard/rust/Cargo.toml
|
||||
|
||||
# Build OTA image without flashing:
|
||||
bash Software/MainBoard/rust/image_build.sh
|
||||
|
||||
# Erase OTA data partition (recover from bad flash):
|
||||
bash Software/MainBoard/rust/erase_ota.sh
|
||||
```
|
||||
|
||||
`flash.sh` rebuilds the webpack frontend (`src_webpack/`) then flashes via `espflash` at 921600 baud. The frontend is bundled into the firmware binary — do not run `npm` separately unless modifying `src_webpack/`.
|
||||
|
||||
### Sensor Board (CH32V203C8T6)
|
||||
```
|
||||
cargo check --manifest-path Software/CAN_Sensor/Cargo.toml
|
||||
cargo build --release --manifest-path Software/CAN_Sensor/Cargo.toml
|
||||
# Flash:
|
||||
wchisp flash Software/CAN_Sensor/target/riscv32imc-unknown-none-elf/release/bms
|
||||
```
|
||||
|
||||
Runner is preconfigured in `.cargo/config.toml` as `wchisp flash`. Debug via `openocd` + `gdb` (scripts in `CAN_Sensor/bin/`). See `CAN_Sensor/README.md` for MCU unlock steps.
|
||||
|
||||
### Shared Crate
|
||||
```
|
||||
cargo check --manifest-path Software/Shared/canapi/Cargo.toml
|
||||
```
|
||||
|
||||
### Cross-impact
|
||||
Any change to `canapi` (IDs, frame layout, serialization) must be checked against both firmware targets. The crate uses `bincode` for serialization.
|
||||
|
||||
## Architecture Notes
|
||||
- **Main board entry**: `Software/MainBoard/rust/src/main.rs` — `#[esp_rtos::main]` async entry, Embassy executor, ESP-HAL.
|
||||
- **HAL layer**: `src/hal/mod.rs` defines `PlantHal` trait; `esp.rs` and `v4_hal.rs` are concrete implementations.
|
||||
- **mcutie**: `src/mcutie_3_0_0/` is a vendored MQTT/HA client library.
|
||||
- **Webserver**: `src/webserver/` serves OTA, logs, static files over HTTP. Frontend in `src_webpack/`.
|
||||
- **Sensor entry**: `Software/CAN_Sensor/src/main.rs` — `#[embassy_executor::main]` async entry, CH32-HAL, CAN + USB CDC.
|
||||
- **Both targets**: Embassy executor, `heapless` for heapless data structures, `option-lock` for optional state.
|
||||
|
||||
## Website
|
||||
```
|
||||
cd website
|
||||
npm run dev # starts Hugo dev server with Blowfish theme
|
||||
```
|
||||
|
||||
Theme is a git submodule. Do not edit `website/themes/` directly — make customizations in `assets/` or `config/` instead.
|
||||
|
||||
## Working Rules
|
||||
- Keep changes tightly scoped to the user request; this repo spans hardware, firmware, and website code.
|
||||
- Prefer fixing the underlying cause instead of applying cosmetic workarounds.
|
||||
- Preserve existing file structure and naming unless the user explicitly asks for restructuring.
|
||||
- Avoid mass formatting or opportunistic cleanup in KiCad files, lockfiles, generated assets, or vendored dependencies.
|
||||
- Do not edit dependency directories such as `website/themes` or `Software/MainBoard/rust/src_webpack/node_modules` unless the user explicitly asks for vendor changes.
|
||||
- Do not edit dependency directories (`website/themes`, `src_webpack/node_modules`) unless explicitly asked.
|
||||
- When touching firmware code, keep resource usage and target constraints in mind; avoid unnecessary allocations or feature creep.
|
||||
|
||||
## Firmware Guidance
|
||||
- Shared protocol or serialization changes must be checked for impact across both `Software/MainBoard/rust` and `Software/CAN_Sensor`.
|
||||
- Prefer small, explicit changes in embedded code paths; do not introduce heavyweight abstractions without a clear payoff.
|
||||
- Keep `no_std`/embedded assumptions intact unless the code clearly opts into something else.
|
||||
- Be careful with feature flags, target-specific dependencies, and boot/runtime configuration in Cargo manifests.
|
||||
|
||||
## Hardware Guidance
|
||||
- Treat hardware directories as design artifacts, not generic text files.
|
||||
- Do not reorder, normalize, or bulk-edit PCB / CAD files unless the user specifically requests those changes.
|
||||
- If a software change depends on hardware assumptions, call that out clearly in the final handoff.
|
||||
|
||||
## Website Guidance
|
||||
- The site in `website` uses Hugo with the Blowfish theme.
|
||||
- Prefer editing site content, config, or custom assets over modifying vendored theme internals.
|
||||
- Keep frontend changes consistent with the existing site structure unless the user asks for a redesign.
|
||||
- Shared protocol or serialization changes must be checked for impact across both firmware targets.
|
||||
|
||||
## Validation
|
||||
Use the narrowest relevant check first.
|
||||
|
||||
Useful commands:
|
||||
- `cargo check --manifest-path Software/Shared/canapi/Cargo.toml`
|
||||
- `cargo check --manifest-path Software/CAN_Sensor/Cargo.toml`
|
||||
- `cargo check --manifest-path Software/MainBoard/rust/Cargo.toml`
|
||||
- `npm run dev` from `website` for local Hugo development if the environment has the required tools installed.
|
||||
|
||||
Validation notes:
|
||||
- Embedded firmware may require target-specific toolchains or hardware-adjacent tooling that is not always available.
|
||||
- If you cannot run a meaningful validation step, say so explicitly and describe the likely prerequisite.
|
||||
|
||||
## File Hygiene
|
||||
- Read large files in chunks.
|
||||
- Prefer targeted searches (`rg`, or `find` if unavailable) over broad scans.
|
||||
- Do not commit build outputs, generated binaries, or local IDE metadata unless the user explicitly requests it.
|
||||
- Use the narrowest relevant check first.
|
||||
- Embedded firmware may require target-specific toolchains or hardware-adjacent tooling. If you cannot run a meaningful validation step, say so explicitly and describe the likely prerequisite.
|
||||
|
||||
## Handoff Expectations
|
||||
- Summarize what changed, where it changed, and any validation performed.
|
||||
|
||||
Reference in New Issue
Block a user