Balance Board Project

Important Links

• Waveshare ESP32-S3-Matrix: https://www.waveshare.com/wiki/ESP32-S3-Matrix

Build, Flash, and Monitor (ESP-IDF idf.py)

Prerequisites:

• ESP-IDF installed and environment exported (run export.sh / export.ps1 from your ESP-IDF install).
• Board connected over USB. Know its serial port (e.g., /dev/ttyACM0 on Linux, COMx on Windows, /dev/cu.usbmodem… on macOS).

Typical workflow from the project root:

1. Select target (example uses ESP32-S3; change if you use a different chip): idf.py set-target esp32s3

2. Configure (optional): idf.py menuconfig

3. Build the application: idf.py build

4. Flash and open serial monitor: idf.py -p flash monitor

• Exit monitor with Ctrl+].
• If you don’t specify -p, ESP-IDF will try to auto-detect.

Clean builds:

• Remove build artifacts entirely (useful if switching targets/IDF versions): idf.py fullclean

Running Unit Tests (ESP-IDF Unit Test App)

This project uses the ESP-IDF Unit Test App to run component tests. Tests live under each component’s test/ folder. Currently available:

• Component: utilities
  • QueuedNotificationService unit tests

Important: The idf.py -T option is only available in newer ESP-IDF versions. If your idf.py does not recognize -T, either update ESP-IDF or use the fallback method described below.

Option A — Using idf.py -T (newer ESP-IDF):

• Normal app builds do not include tests.
• Run the Unit Test App by selecting tests with -T.

Run only the utilities component tests: idf.py -T utilities -p flash monitor

Run all discovered component tests in the project: idf.py -T all -p flash monitor

Option B — Fallback for older ESP-IDF (no -T support): You can run tests using ESP-IDF’s Unit Test App project and point it to this repository’s components.

1. Open an ESP-IDF environment (run export.sh / export.ps1).
2. Change directory to the Unit Test App provided by ESP-IDF: cd "$IDF_PATH/examples/system/unit_test"
3. Configure CMake to discover this project’s components and select which tests to run by passing these options to idf.py: -D EXTRA_COMPONENT_DIRS="/home/efhilton/CLionProjects/balance_board/components"
   -D TEST_COMPONENTS="utilities"

Example commands to build, flash, and monitor only the utilities tests on the target: idf.py -D EXTRA_COMPONENT_DIRS="/home/efhilton/CLionProjects/balance_board/components" -D TEST_COMPONENTS="utilities" -p flash monitor

To run all tests available to the Unit Test App (including those discovered in this repo via EXTRA_COMPONENT_DIRS): idf.py -D EXTRA_COMPONENT_DIRS="/home/efhilton/CLionProjects/balance_board/components" -D TEST_COMPONENTS=all -p flash monitor

Notes:

• The Unit Test App will build and flash a special test firmware, then run the Unity tests and print results in the serial monitor.
• After running tests, return to your project directory and do a normal build/flash to restore your regular firmware.