bsncubed
8485ecb5b7
play/pause/toggle/stop/next/prev. Spotify commands run on the session task (same thread as cspot's frame handling) and the POST waits until they ran, so it answers the new state. HLS pause stops fetching and resume rejoins at the live edge; next/prev on HLS and anything on tone/off return 409. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
84 lines
9.3 KiB
Markdown
84 lines
9.3 KiB
Markdown
# aes67-ESP32-P4
|
|
|
|
AES67 sender on a Waveshare ESP32-P4-ETH (PoE). Sources: Spotify Connect (cspot) and HLS/m3u8, with failover. Riedel-style web UI and a reusable AES67 core (PTP, RTP TX, SDP/SAP, VLAN, syslog, health) meant for later AES67 projects.
|
|
|
|
Repo: https://gitea.apointless.space/bsncubed/aes67-ESP32-P4
|
|
|
|
## Read first
|
|
- `docs/aes67-core-base.md`: reusable core. Config schema, API, PTP (roles, Riedel defaults, status fields), AES67 TX/SDP/SAP, VLAN, syslog, temperatures, component layout.
|
|
- `docs/hardware-and-design-notes.md`: board pinout, chip revision caveat, project pipeline (cspot/HLS), failover, player API.
|
|
- `web/index.html`: finished web UI (single file). It is the API contract; firmware must match the JSON it reads and writes.
|
|
|
|
## Working rules
|
|
- **One change at a time** ("one fuckup at a time"). Change or test one variable per step; never stack several fixes or hypotheses. If something breaks, go back to the last known-good state.
|
|
- Follow the build order below. Finish and verify a step on hardware before starting the next.
|
|
- After every change: `idf.py build`, flash, and check the serial monitor output. Show the relevant log lines.
|
|
- Don't mark a step done until it has been verified on the board.
|
|
- Keep core and project separate: `components/aes67_*` must not depend on `main/` (sources/player). Project code plugs in through the config, status and route registries.
|
|
- `web/index.html`: keep the CORE / PROJECT markers. If the firmware needs an API change, change the doc and the page together.
|
|
- Small, focused commits per step.
|
|
|
|
## Toolchain
|
|
- ESP-IDF 5.5 or later (needed for the P4 and for `examples/network/vlan_support`). Target `esp32p4`.
|
|
- `idf.py set-target esp32p4`, `idf.py build`, `idf.py -p <PORT> flash monitor`
|
|
- Before first build: run `esptool.py chip_id` and `esptool.py flash_id`.
|
|
- Chip revision < v3.0 (engineering silicon, seen on some of these boards) needs `CONFIG_ESP32P4_SELECTS_REV_LESS_V3=y`.
|
|
Our board: **v1.3** (set in sdkconfig.defaults, min rev v1.0).
|
|
- Our board: **32 MB** flash (GigaDevice c8/4019). App slots must stay below 16 MB (cache mapping above 16 MB is experimental in IDF).
|
|
- Rev < 3 also limits Espressif's prebuilt audio libraries: `esp_audio_codec` must stay < 2.6 and `esp_audio_effects` < 1.4 (newer versions use P4 assembly that needs rev >= 3; the build fails with a message saying so). Check this for any new Espressif binary component.
|
|
- Embed `web/index.html` via `EMBED_TXTFILES` in `aes67_web`.
|
|
- cspot (Spotify, `external/cspot` git submodule, philippe44 fork, pinned): after cloning run `git submodule update --init external/cspot && git -C external/cspot submodule update --init cspot/bell`. Its nanopb code generator needs, in the IDF Python env: `python -m pip install protobuf grpcio-tools 'setuptools<81'` (after `. export.sh`). Our fixes to cspot/bell live in `components/spotify/patches/{cspot,bell}/*.patch` and are applied automatically at configure time; don't edit the submodule directly, add a patch.
|
|
- Flash over the network (normal way since step 2b; keep USB for recovery):
|
|
`curl -f --data-binary @build/aes67_p4.bin -H 'Content-Type: application/octet-stream' http://p4-aes67/api/ota`
|
|
The board reboots into the new image on trial; check `GET /api/ota` shows the new version with `pending_verify: false`.
|
|
- Serial: opening /dev/ttyACM0 can reset the board. Don't open it while an OTA image is on trial (a reset then counts as a failed boot and rolls back).
|
|
- Rollback test build (self-test always fails), in its own build dir:
|
|
`idf.py -B build-selftest-fail -DSDKCONFIG=build-selftest-fail/sdkconfig -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.selftest_fail" build`
|
|
|
|
## Board quick reference (full details in docs)
|
|
- Ethernet: IP101GRI, RMII, PHY addr 1, ref clock from PHY into GPIO50 (EMAC_CLK_EXT_IN).
|
|
MDC 31, MDIO 52, PHY reset/power 51, TX_EN 49, TXD0 34, TXD1 35, CRS_DV 28, RXD0 29, RXD1 30.
|
|
- No Wi-Fi/BT on this board.
|
|
- On-die temperature sensor only (driver/temperature_sensor.h).
|
|
|
|
## Build order / status
|
|
- [x] 0. Check chip revision and flash size; create IDF project and empty component stubs (layout in aes67-core-base.md). Set up the OTA partition table (two app slots, no factory) and PROJECT_VER from git now, so the layout never changes later.
|
|
- [x] 1. Ethernet: IP101 up, DHCP, IP logged. Ping works.
|
|
- [x] 2. Web server + config store (cJSON in NVS) + embedded index.html; /api/config, /api/status (stub values), /api/reboot.
|
|
- [x] 2a. Finding the device: mDNS (hostname.local + _http._tcp), then LLDP (switch shows name + IP).
|
|
- [x] 2b. Firmware update: /api/ota upload + rollback self-test. Test: update to a new build, then deliberately flash a build that fails its self-test and confirm it rolls back. After this, flash over the network; keep USB for recovery.
|
|
- [x] 3. PTP TimeReceiver: lock to an existing GM (Riedel), fill `status.ptp`. Confirm EMAC hardware timestamps work. First check whether the installed ESP-IDF has a PTP example/component for the P4 before writing one.
|
|
- [ ] 4. AES67 TX with a 1 kHz test tone, PTP-paced; /stream.sdp. Verify: import SDP on a Riedel Artist 4-wire AES67 port, and check packets/timestamps in Wireshark.
|
|
Done and checked with a receiver script (all ptimes, L16/L24, tone phase-locked to PTP); still open: the Riedel import and a Wireshark capture.
|
|
- [x] 5. SAP discovery, then syslog, then health/temperatures (one at a time). VLAN split moved to phase 2.
|
|
- [x] 6. PTP TimeTransmitter: BMCA roles (auto/master), hybrid mode.
|
|
- [ ] 7. Sources: HLS player, then cspot (Spotify Connect), then failover + /api/player.
|
|
- [x] 7.1-7.4 HLS plays on AES67 (PSRAM ring, TS demux + AAC, 44.1 -> 48 kHz). Tested with Triple J Hottest (TS, AAC-LC 44.1k).
|
|
- [ ] Come back to HLS (open items):
|
|
- Clock drift: the station's encoder clock vs our PTP clock is not corrected. Starts 3 segments (~30 s) behind live, so it shows after hours/days (skip when falling out of the live window, or buffering). Fix: steer the 44.1 -> 48 kHz ratio by a few ppm from the distance to the live edge / ring level.
|
|
- Download speed ~1.4 Mbit/s over TLS (fine for ~250 kbit/s; tune buffer sizes / per-chunk overhead).
|
|
- Not yet tested: HE-AAC variant (140k), other stations, fMP4/ADTS-only playlists, discontinuities (#EXT-X-DISCONTINUITY), network loss and recovery, long runs.
|
|
- Audio starts only after PTP lock (~20 s after boot): intended, TX needs PTP.
|
|
- [ ] cspot (Spotify Connect): login, audio, pause/skip/seek, app volume, live mode switching work; stays connected across track changes and past 6 min (7.5b). Fixed so far: logger NULL crash, Vorbis symbol clash, volume starting at 0, reconnect race (PR #3 patch), 6-minute AP resets (delayed Pong patch), app dropping the device (notifyAudioReachedPlayback). Open:
|
|
- OTA with a session: now ends the session first; 2 of 2 uploads with a running session were clean since. Flash writes still stall TX > 20 ms during uploads (stream stutters while updating).
|
|
- First connects sometimes fail ("Can't connect to spotify servers"), a retry works.
|
|
- Internal heap drops from ~365 KB to ~231 KB with a session; check what can move to PSRAM.
|
|
- Track display in the app can switch ~3-5 s early.
|
|
- Mute at 0 % volume not yet confirmed.
|
|
- Consider offering the delayed-Pong fix upstream (philippe44/cspot).
|
|
- An old, long-idle session can get out of sync with the app: it sends empty Load frames ("No tracks in frame") instead of Pause/Play, so controls do nothing. Quitting and reopening Spotify on the Mac fixes it.
|
|
- [x] failover (auto mode): no session or (with `failover_on_pause`) paused for `failover_delay_s` -> HLS; Spotify playing -> Spotify within ~1 s; 30 ms fades; HLS suspended while Spotify plays; cspot is held back (not drained) while it isn't Spotify's turn, so it resumes where it paused. Verified: no session -> HLS, play -> Spotify, pause stays (on_pause off), pause -> HLS after 5 s (on_pause on), play -> Spotify at the paused position.
|
|
- Open: `aes67_tx resync` (TX 20-27 ms late) ~11 s after each switch to Spotify (seen 3 times); clicks at switches not yet checked in a recording; HLS start sometimes hits CDN read timeouts.
|
|
- [ ] /api/player: GET and transport (play/pause/toggle/stop/next/prev) done. Next: seek/volume, source override/url.
|
|
- [ ] 8. Mono sum, gain, polish.
|
|
|
|
## Phase 2 (parked)
|
|
- [ ] VLAN split: AES67 untagged + internet tagged (inet.vlan_id/pcp), per aes67-core-base.md "Network". Needs a tagged VLAN with DHCP on the switch port. Config group `inet` and the UI fields exist already; nothing is applied yet.
|
|
- [ ] NTP (SNTP): servers as hostnames or IPs (e.g. `pool.ntp.org`, several allowed; names resolved via DNS, re-resolved on failure). Uses: seed the PTP clock with real time before becoming GM (today it starts at 1970), syslog timestamps. Needs a `time` config group + UI fields (change doc and page together).
|
|
|
|
## Phase 3 (parked)
|
|
- [ ] Remote access via VPN / Tailscale. There is no official Tailscale client for ESP32; options to evaluate first:
|
|
(a) no firmware change: a Tailscale subnet router on the LAN (e.g. the dev PC or a Pi) advertising the device's subnet;
|
|
(b) WireGuard on the device (e.g. the `esp_wireguard` component) to a WireGuard server or a Tailscale/Headscale-compatible peer.
|
|
Before exposing the web/API remotely: add authentication (bearer token) as noted in the OTA/security section of aes67-core-base.md. Keep AES67/PTP traffic off the tunnel.
|