Add AGENTS.md for project documentation and agent rules
This commit is contained in:
André Fiedler
63
AGENTS.md
Normal file
63
AGENTS.md
Normal file
@@ -0,0 +1,63 @@
|
|||||||
|
# AGENTS.md
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
This repository contains EggDuino firmware (EggBot protocol emulation) for an ESP32 build target using PlatformIO.
|
||||||
|
Use this file as the working contract for code agents in this repo.
|
||||||
|
|
||||||
|
## Repository Map
|
||||||
|
- `src/main.cpp`: firmware entrypoint (`setup`/`loop`), serial command processing, optional button/test toggles.
|
||||||
|
- `src/Functions.cpp`: EggBot command handlers (`SM`, `SP`, `EM`, `SC`, `QP`, etc.) and command registration.
|
||||||
|
- `src/Helper_Functions.cpp`: hardware init, motor/servo control, move preparation, ACK/error responses.
|
||||||
|
- `src/Config_Web.cpp`: optional Wi-Fi web UI and JSON config persistence via SPIFFS.
|
||||||
|
- `src/Logging.cpp`: ring-buffer log collection and `/api/logs` JSON serialization.
|
||||||
|
- `include/EggDuino.h`: global declarations, pin/microstep constants, cross-file API.
|
||||||
|
- `lib/SerialCommand/src/*`: local serial command parser implementation.
|
||||||
|
- `platformio.ini`: single build environment (`[env:uno]`) that actually targets `esp32dev`.
|
||||||
|
|
||||||
|
## Build, Flash, Monitor
|
||||||
|
- Build: `~/.platformio/penv/bin/pio run -e uno`
|
||||||
|
- Upload: `~/.platformio/penv/bin/pio run -e uno -t upload`
|
||||||
|
- Serial monitor: `~/.platformio/penv/bin/pio device monitor -b 115200`
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
- `platformio.ini` currently pins `upload_port = /dev/tty.usbserial-110`; treat this as machine-local and change only when required.
|
||||||
|
- There are no unit tests in this repository; a successful PlatformIO build is the minimum validation.
|
||||||
|
|
||||||
|
## Local Config And Secrets
|
||||||
|
- Wi-Fi config is provided by `src/credentials.h`.
|
||||||
|
- Keep `src/credentials.h` local-only; `.gitignore` already excludes it.
|
||||||
|
- For default behavior (no Wi-Fi web server), keep:
|
||||||
|
- `const char *kWifiSsid = 0;`
|
||||||
|
- `const char *kWifiPassword = 0;`
|
||||||
|
|
||||||
|
## Agent Rules For Code Changes
|
||||||
|
1. Preserve EggBot serial protocol behavior.
|
||||||
|
- Commands are wired in `makeComInterface()`.
|
||||||
|
- ACK/error responses are protocol-significant (`"OK\\r\\n"` and `"unknown CMD\\r\\n"`).
|
||||||
|
2. Keep movement math semantics intact.
|
||||||
|
- `prepareMove()` handles microstep correction and step error accumulation (`g_iRotStepError`, `g_iPenStepError`).
|
||||||
|
- Do not replace this with naive float-heavy logic unless explicitly requested.
|
||||||
|
3. Respect real-time loop constraints.
|
||||||
|
- `loop()` must remain non-blocking except for protocol-required waits.
|
||||||
|
- Avoid adding expensive dynamic allocation in high-frequency paths.
|
||||||
|
4. Keep hardware mapping centralized.
|
||||||
|
- Pin and microstep constants belong in `include/EggDuino.h`.
|
||||||
|
- If changing pinouts, update only there and keep ESP32/non-ESP32 guards coherent.
|
||||||
|
5. Do not hand-edit generated IDE metadata.
|
||||||
|
- `.vscode/c_cpp_properties.json` and `.vscode/launch.json` are generated by PlatformIO.
|
||||||
|
- Prefer edits in `platformio.ini` instead.
|
||||||
|
6. Keep edits minimal and targeted.
|
||||||
|
- Match existing style (global `g_*` variables, Arduino types, simple free functions).
|
||||||
|
- Avoid broad refactors unless explicitly requested.
|
||||||
|
|
||||||
|
## When Adding Config Parameters To Web UI
|
||||||
|
`Config_Web.cpp` currently has an empty `configParameters[]` array. To add persisted parameters:
|
||||||
|
1. Add the backing global variable (typically in existing global state).
|
||||||
|
2. Add a `ConfigParameter` entry to `configParameters[]` with key, pointer, description, default.
|
||||||
|
3. Ensure defaults are safe in `applyDefaults()` flow.
|
||||||
|
4. Rebuild and verify `GET/POST /api/config` still round-trips.
|
||||||
|
|
||||||
|
## Definition Of Done For Agents
|
||||||
|
Before finishing, run:
|
||||||
|
1. `~/.platformio/penv/bin/pio run -e uno`
|
||||||
|
2. Summarize changed files and any behavior-impacting protocol/hardware implications.
|
||||||
@@ -19,3 +19,15 @@ lib_deps =
|
|||||||
madhephaestus/ESP32Servo@^3.0.6
|
madhephaestus/ESP32Servo@^3.0.6
|
||||||
bblanchon/ArduinoJson@^6.21.5
|
bblanchon/ArduinoJson@^6.21.5
|
||||||
gin66/FastAccelStepper@^0.33.13
|
gin66/FastAccelStepper@^0.33.13
|
||||||
|
|
||||||
|
[env:uno_macos]
|
||||||
|
platform = platformio/espressif32
|
||||||
|
board = esp32dev
|
||||||
|
framework = arduino
|
||||||
|
monitor_speed = 115200
|
||||||
|
upload_speed = 115200
|
||||||
|
upload_port = /dev/tty.usbserial-110
|
||||||
|
lib_deps =
|
||||||
|
madhephaestus/ESP32Servo@^3.0.6
|
||||||
|
bblanchon/ArduinoJson@^6.21.5
|
||||||
|
gin66/FastAccelStepper@^0.33.13
|
||||||
|
|||||||
Reference in New Issue
Block a user