# 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.