docs: describe the v2 controller's API, UI and tests

API.md now documents what the firmware serves: groups, combined
brightness, beat-driven sequences, import/export, /api/audio, patterns
over ESP-NOW, outputs, /ws, driver OTA, and how API calls become driver
messages and group commands. The user guide follows the current UI; the
in-app audio help describes the microphone instead of input devices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-11-03 20:42:03 +13:00
1 parent bfeeb958df
commit b2cd242390
5 files changed
+335 -429

No files matched your search

+5 -8
View File
@@ -10,17 +10,14 @@ or `python3 -m pytest test/api --host <ip>` (or set `LED_HOST`). Without a host
The tests create and delete profiles, presets, zones and so on. The sequence tests switch mic timing off and run the beat clock at 200 BPM for a few seconds; mic timing is switched back on afterwards. Before the run they save every collection (`GET /db/<name>`), and afterwards they write each one back (`PUT /db/<name>`). Zone play and preset send do go out over ESP-NOW. They use made-up driver names (`pytest-a`, `pytest-nobody`) so real drivers ignore them.
## v1 features v2 does not have yet
## Marking a missing feature
A test for v1 behaviour that v2 is missing is marked `@missing("<feature>")`. That is a strict `xfail`, so the test shows as `x`, and it fails as `XPASS(strict)` once the feature works. When that happens, remove the marker. To list what is still missing:
`helpers.missing("<feature>")` marks a test for behaviour the firmware does not have yet. It is a strict `xfail`: the test shows as `x`, and fails as `XPASS(strict)` once the feature works, so the marker gets removed. No test carries it now. `python3 -m pytest test/api --host <ip> -rx` lists marked tests.
```bash
python3 -m pytest test/api --host <ip> -rx
```
## Not ported
v1 tests that were not ported:
- the model and engine unit tests (`tests/models/`, `tests/engine_tests/`), which test Python modules that have no C counterpart;
- the Wi-Fi/TCP/UDP driver test servers.
- the model, engine and helper unit tests (`tests/models/`, `tests/engine_tests/`, most of `main`'s `tests/test_*.py`), which test Python modules that have no C counterpart;
- the Wi-Fi/TCP/UDP driver test servers and the bridge tests (the controller has no bridge or Wi-Fi driver transport).
The checks on exact driver messages became checks on status codes and replies, because ESP-NOW frames can't be captured from outside the board.