64 lines
3.4 KiB
Markdown
64 lines
3.4 KiB
Markdown
# 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.
|