2.7 KiB
Repository Guidelines
Project Structure & Module Organization
firmware/master contains the access-point, web server, calibration, and ESP-NOW receiver firmware. firmware/slave contains the sensor/transmitter firmware for remote nodes. Source files live under each src/ directory, and the Master web UI is served from firmware/master/data/index.html. Hardware documentation lives in hardware/schematics and hardware/cad. Top-level docs such as README.md and IMPLEMENTATION_STATUS.md describe project scope and phase status.
Build, Test, and Development Commands
Use PlatformIO from each firmware directory:
cd firmware/master && pio run
cd firmware/master && pio run -t upload
cd firmware/master && pio device monitor -b 115200
cd firmware/slave && pio run -e slave2
pio run builds the current environment, -t upload flashes hardware, and pio device monitor opens the serial console. Use named slave environments such as slave2 to build alternate NODE_ID values for multi-node setups.
Coding Style & Naming Conventions
The codebase is C++ for Arduino/ESP32 with 4-space indentation and opening braces on the same line. Keep header and implementation pairs aligned (imu_driver.h / imu_driver.cpp). Use PascalCase for classes (CalibrationManager), camelCase for functions and variables (readBatteryPercent), and UPPER_SNAKE_CASE for macros and config constants. Preserve the existing comment style: short section banners and targeted inline comments, not redundant narration.
Testing Guidelines
There is no automated unit-test suite yet. Treat a clean pio run for both Master and Slave as the baseline verification step. For behavior changes, validate on hardware through serial logs at 115200 baud and confirm the Master API/UI flow at http://192.168.4.1. Document any manual test coverage in the PR when changing IMU logic, ESP-NOW messaging, calibration, or battery reporting.
Commit & Pull Request Guidelines
Recent history uses concise, imperative commit subjects, for example: Implement Phase 1-4: MVP with differential measurement and median filtering. Follow that pattern and keep subjects focused on one change set. Pull requests should include a short summary, affected area (master, slave, hardware, or docs), manual validation steps, and screenshots or serial output when UI or device behavior changes. Link the relevant spec, issue, or phase task when applicable.
Configuration & Hardware Notes
Do not commit device-specific secrets or ad hoc MAC addresses without explanation. If slave pairing changes, update firmware/slave/src/config.h deliberately and mention it in review notes so others can reflash hardware correctly.