EggDuino/AGENTS.md

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.