# esp_hosted_avb
AVB extensions for ESP-Hosted: a small additive message channel that
lets a host MCU running an AVB stack make the Wi-Fi radio calls on its
coprocessor that ESP-Hosted does not forward, without forking
ESP-Hosted. The coprocessor runs stock ESP-Hosted with this component
linked in.
This is a third-party component from Scramble Tools, not part of
Espressif's ESP-Hosted. It was called `esp_ptp_rpc` before version
0.5.0; the message IDs did not change, so hosts and coprocessors built
under either name understand each other.
The source lives at <https://github.com/scrambletools/esp_hosted_avb>.
The component is published in the ESP Component Registry
(<https://components.espressif.com>) under the **scrambletools**
namespace, so depend on it as:
```yaml
dependencies:
scrambletools/esp_hosted_avb: "*"
```
Old github.com/scrambletoolsllc/... links redirect to the
scrambletools repos.
## Why
In a P4+C6 split (the canonical AVB-over-Wi-Fi topology: ESP32-P4 host
runs Ethernet + gPTP, ESP32-C6 coprocessor owns the Wi-Fi radio), the
host needs to drive a few Wi-Fi calls on the coprocessor side that
ESP-Hosted's upstream RPC catalogue does not expose. The most pressing
one is `esp_wifi_set_vendor_ie()` — required to publish IEEE
802.1AS-2020 §12.7 `FollowUpInformation` in the AP's beacon Vendor IE.
The host's local `libnet80211` has no radio behind it, so calling
`esp_wifi_set_vendor_ie()` from host code is a silent no-op — beacons
go out with zero Vendor IE bytes from our OUI. The same holds for
`esp_wifi_config_11b_rate()`, which keeps an AP's beacons and
management frames off 1 Mbps, and the AP's association list.
Rather than forking ESP-Hosted, this component uses the upstream's
own additive escape hatch: its **peer data** feature. The host sends a
packed buffer via `hosted_avb_peer_send(msg_id, ...)`; the coprocessor's
registered callback unpacks and dispatches to the matching
`esp_wifi_*` call locally on the C6.
## How it works
```
Host (P4) — gPTP, AVB stack Coprocessor (C6) — Wi-Fi radio
──────────────────────────── ──────────────────────────────
hosted_avb_peer_send( → set_vendor_ie_callback() →
HOSTED_AVB_MSG_SET_VENDOR_IE_REQ, esp_wifi_set_vendor_ie(...)
packed buf) [installs IE in beacons]
↓
handler reads ack ← HOSTED_AVB_MSG_SET_VENDOR_IE_ACK (esp_err_t)
```
Wire format is defined in `include/hosted_avb_proto.h` (one short
header, both sides include it). `include/hosted_avb_peer.h` wraps
esp-hosted's peer data calls on the host and the coprocessor. The
coprocessor-side handler in `hosted_avb.c` registers itself at startup
as an esp-hosted feature, so the coprocessor application does not need
to call `hosted_avb_init()` from `app_main`; it just works once this
component is linked in.
## Messages implemented
| ID | Name | Direction | Payload |
| --- | --- | --- | --- |
| `0x50545001` | `HOSTED_AVB_MSG_SET_VENDOR_IE_REQ` | host → coprocessor | 4-byte header + full `vendor_ie_data_t` buffer |
| `0x50545002` | `HOSTED_AVB_MSG_SET_VENDOR_IE_ACK` | coprocessor → host | `int32_t esp_err_t` |
| `0x50545003` | `HOSTED_AVB_MSG_ASSOCIATIONS_REQ` | host → coprocessor | `uint8_t` version |
| `0x50545004` | `HOSTED_AVB_MSG_ASSOCIATIONS` | coprocessor → host | `hosted_avb_associations_t` |
| `0x50545005` | `HOSTED_AVB_MSG_CONFIG_11B_RATE_REQ` | host → coprocessor | `hosted_avb_config_11b_rate_t` |
| `0x50545006` | `HOSTED_AVB_MSG_CONFIG_11B_RATE_ACK` | coprocessor → host | `int32_t esp_err_t` |
| `0x50545007` | `HOSTED_AVB_MSG_CLOCK_LINK_ARM` | host → coprocessor | `hosted_avb_clock_link_arm_t` |
| `0x50545008` | `HOSTED_AVB_MSG_CLOCK_LINK_ARM_ACK` | coprocessor → host | `hosted_avb_clock_link_arm_t` |
| `0x50545009` | `HOSTED_AVB_MSG_CLOCK_LINK_EDGE` | coprocessor → host | `hosted_avb_clock_link_edge_t` |
| `0x5054500A` | `HOSTED_AVB_MSG_WIFI_TIME` | coprocessor → host | `hosted_avb_wifi_time_t` |
| `0x5054500B` | `HOSTED_AVB_MSG_FTM_TRANSFER` | host → coprocessor | ESP-AVB-Bridge `ftm_time_transfer_t` |
| `0x5054500C` | `HOSTED_AVB_MSG_FTM_ASSOCIATIONS` | host → coprocessor | ESP-AVB-Bridge admitted stations |
| `0x5054500D` | `HOSTED_AVB_MSG_FTM_RESPONDER_STATUS` | coprocessor → host | ESP-AVB-Bridge `ftm_time_responder_status_t` |
`ASSOCIATIONS` lists the stations associated with the coprocessor's
access point, with a random per-boot `radio_boot` and a `generation`
that advances with every change. The coprocessor sends it after each
join, leave and AP stop has been forwarded to the host, and in answer
to `ASSOCIATIONS_REQ`. `esp_ptp` reconciles its gPTP peers to it, so
the host sends Announce and Signaling only to stations the radio has.
The list follows the coprocessor's Wi-Fi events: the raw AP event
updates it and the report goes out once esp-hosted has reposted the
event for the host. The `LIFECYCLE` flag says the list is live; without
it `esp_ptp` goes by the host's own association events. Other
coprocessor components can follow the same list through the weak
`hosted_avb_associations_changed` and `hosted_avb_associations_forwarded`
hooks.
`CONFIG_11B_RATE_REQ` calls `esp_wifi_config_11b_rate()` on the
coprocessor, which esp-hosted does not forward. With 802.11b off, an
access point sends its beacons, management and group addressed frames
at 6 Mbps OFDM instead of 1 Mbps DSSS; on the bench that cut
management airtime from about 30 to 5 ms a second. The radio accepts
the call only between `esp_wifi_init()` and `esp_wifi_start()`, so the
host sends it after `esp_wifi_set_config()` and waits for the ACK
before starting Wi-Fi. A coprocessor without this message never
answers; the host should time out and carry on. Setting the protocol to
802.11g/n through esp-hosted does not do this: the beacons stay at
1 Mbps.
The clock link (`CONFIG_HOSTED_AVB_CLOCK_LINK`, on both sides) times a
wire from a host GPIO to a coprocessor GPIO: R52 on the Waveshare
ESP32-P4-WIFI6-POE-ETH, P4 GPIO6 to C6 GPIO2. For each edge the host
sends `CLOCK_LINK_ARM`, the coprocessor arms and answers `ARM_ACK`, the
host pulses the wire, and both chips latch the edge on a 40 MHz timer in
hardware (GPIO event to timer capture). The host reads its EMAC PTP
clock, and the coprocessor its Wi-Fi MAC clock, between two latches of
that timer, and the coprocessor sends its latch back in `EDGE`. Each
edge pairs the host's PTP clock with the coprocessor's timer and MAC
clock (`hosted_avb_clock_link_latest()`), and the host logs a fit every
10 s. On the bench, at 4 edges a second, the fit left 25 to 32 ns rms
(about 100 ns peak to peak over 8 s), close to the 25 ns timer and 40 ns
PTP clock steps.
With the link running, `hosted_avb_clock_link_to_host()` puts a
coprocessor timer time (`hosted_avb_clock_link_coprocessor_read()` on
the coprocessor gives readings in it) on the host's PTP clock, through a
fit over the last 32 edges, and `hosted_avb_clock_link_fit()` hands the
fit itself to the coprocessor's side. The fit starts again when the
coprocessor restarts. On the coprocessor, `hosted_avb_clock_link_map_mac()`
maps the Wi-Fi MAC clock, which FTM timestamps run on, onto the link's
timer.
`WIFI_TIME` carries one FTM session of a coprocessor station's time
engine (ESP-AVB-Bridge's `ftm_time_engine`): gPTP time from the
responder's Follow_Up against the coprocessor's clock-link timer, or why
the session gave none. The host side (`CONFIG_HOSTED_AVB_WIFI_TIME`,
`hosted_avb_wifi_time_start()`) puts each on the host's PTP clock and
logs, every 10 s, how far it sat from that clock (`WIFITIME`) and the
sessions by measurements and Follow_Ups received (`WIFISESS`).
`hosted_avb_wifi_time_set_callback()` hands each measurement on, for
example to esp_ptp's external time source. On a host
synchronized by wire that difference is the transfer's error: on the
bench, one Wi-Fi hop, about 290 ns standard deviation with a mean within
50 ns, 98.5% of sessions measured.
`0x5054_5000` (`"PTP\0"`) is the message-ID base; the low byte is the
opcode. Reserved for future expansion (e.g. FTM-frame Vendor IE
install when Espressif exposes that path).
## Building
### Host side
Add the dependency to your project's `main/idf_component.yml`:
```yaml
dependencies:
scrambletools/esp_hosted_avb: "*"
```
Then `#include "hosted_avb_proto.h"` and `"hosted_avb_peer.h"`, and
call `hosted_avb_peer_send()` with the message IDs above. Most
host-side consumers will not call this component directly —
`esp_ptp` handles the vendor IE and association messages on behalf of
the AVB stack, and ESP-AVB-Bridge sends `CONFIG_11B_RATE_REQ` before it
starts its access point.
#### Coprocessor firmware updates
On a host (`CONFIG_ESP_HOSTED_HOST`), `hosted_avb_coprocessor_fw.h`
writes a coprocessor app image over esp-hosted's OTA calls:
`hosted_avb_coprocessor_fw_store()` checks the image is for the
coprocessor's chip and from `CONFIG_HOSTED_AVB_COPROCESSOR_PROJECT`
(default `avb_bridge_coprocessor`), writes it to the coprocessor's spare
OTA slot and lets the coprocessor check it again;
`hosted_avb_coprocessor_fw_activate()` switches the coprocessor to it.
The two have the signatures of esp_avb's coprocessor firmware object,
so a host offers the coprocessor's firmware to ATDECC controllers by
registering them with `esp_avb_register_coprocessor_fw()` (the header
shows how). ESP-AVB-Bridge and ESP-AVB-Endpoint boards with a Wi-Fi
coprocessor do.
### Coprocessor side
The coprocessor build also adds this component and enables the handler
and esp-hosted's peer data:
```
CONFIG_HOSTED_AVB_BUILD_COPROCESSOR_HANDLER=y
CONFIG_ESP_HOSTED_CP_FEAT_PEER_DATA=y
```
The handler self-registers at startup; the coprocessor app does not
need to know about this component. It takes three of the coprocessor's
eight peer data handlers.
esp-hosted 3.x is required on both sides; version 0.6.0 was the last
to build against 2.x.
## Status
Vendor-IE install, association reporting and the 802.11b switch are
live. Future opcodes will land here as the AVB-over-Wi-Fi plan needs
them; the wire format is versioned only via opcode additions to keep
host and coprocessor sides loosely coupled.
## License
MIT.
ef7ed0817bbb68d0da9f6d8cb03f2cd75e02dbc7
idf.py add-dependency "scrambletools/esp_hosted_avb^0.9.0"