diff --git a/AGENTS.md b/AGENTS.md index bd7e527..a45bbca 100644 --- a/AGENTS.md +++ b/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.