Fix caps bitmap, add runnable host example over SDIO, repo cleanup

A real bug: phy_rpc_resp_get_caps_t.caps[] was 4 bytes (32 slots,
0x000-0x01F). But RPCs at 0x020+ (TX_80211, ESP-NOW at 0x030,
802.15.4 at 0x040) were silently outside the bitmap, so
get_caps() / has_capability() returned false for everything past
0x01F. Grow to 16 bytes (128 slots, covering 0x000-0x07F).

  - PHY_RPC_CAPS_BYTES = 16; struct field, host stub, slave handler,
    and host tests all use the constant.
  - Slave's caps assembly split per module: phy_rpc_extras_fill_caps()
    and phy_rpc_wireless_fill_caps() each contribute the bits for the
    RPCs they own (with weak-symbol guards for chip-dependent paths
    like 802.15.4).
  - Host has_capability() now bounds-checks against
    PHY_RPC_CAPS_BYTES * 8.

While at it:

  - Wrap esp_wifi_set_event_mask (PHY_RPC_REQ_SET_EVENT_MASK at 0x027,
    response at 0x027|0x8000). Slave handler currently logs and
    returns ESP_OK; the actual esp_event filter wiring is TODO and
    documented in-line.
  - Reserve msg_id slots 0x050-0x053 for the full BT shockburst
    sequencer (preamble, address, CRC mode, raw burst TX) so the
    wire protocol stays stable when those land. No handlers yet —
    needs scope-confirmed RE.

Examples + CI:

  - examples/host_p4_demo/ — minimal P4 IDF project. Builds against
    the host stub library, exercises set_channel + get_caps +
    get_info + get_phy_rssi + ESP-NOW init/add_peer/send. SDIO is
    explicitly selected (CONFIG_ESP_HOSTED_SDIO_HOST_INTERFACE=y),
    SPI/SPI-HD/UART are explicitly disabled in sdkconfig.defaults.
  - .github/workflows/build.yml gains a host-example job that
    idf.py builds it for esp32p4 — closes the gap where a host-stub
    regression could pass CI.

Plumbing fixes that fell out of getting the example to compile:

  - vendor/esp-hosted-mcu/ -> vendor/esp_hosted/ (component-name
    mismatch; idf_component_manager's override_path requires the
    leaf dir to match the dependency name).
  - host/ -> esp_hosted_open/ (same reason; dependents say
    REQUIRES esp_hosted_open).

Build sizes (IDF v6.0):
  slave (esp32c5):     0x1631c0 (26% free in 1.875 MB factory)
  host example (P4):   0x90c90  (43% free in 1 MB)
  host tests:          3 passing, including new caps-bitmap layout

Prebuilt firmware refreshed.

Author: DatanoiseTV

.github/workflows/build.yml

@@ -15,6 +15,20 @@ jobs:
       - uses: actions/checkout@v4
       - run: make -C tests/host test
 
+  host-example:
+    name: build P4 host example (SDIO)
+    runs-on: ubuntu-latest
+    container:
+      image: espressif/idf:release-v5.5
+    steps:
+      - uses: actions/checkout@v4
+      - name: idf.py build (esp32p4)
+        working-directory: examples/host_p4_demo
+        run: |
+          . $IDF_PATH/export.sh
+          idf.py set-target esp32p4
+          idf.py build
+
   slave:
     name: build slave firmware
     runs-on: ubuntu-latest

host/CMakeLists.txt esp_hosted_open/CMakeLists.txthost/CMakeLists.txt renamed to esp_hosted_open/CMakeLists.txt

@@ -81,8 +81,8 @@ esp_err_t esp_hosted_open_set_bt_filter     (uint32_t reg_value);
 /* Capability discovery — bitmap indexed by request msg_id low byte;
  * tells the host which RPCs the slave's libphy.a actually exposes
  * on this chip. */
-esp_err_t esp_hosted_open_get_caps          (uint8_t caps[4]);
-bool      esp_hosted_open_has_capability    (uint32_t request_msg_id, const uint8_t caps[4]);
+esp_err_t esp_hosted_open_get_caps          (uint8_t caps[16]);
+bool      esp_hosted_open_has_capability    (uint32_t request_msg_id, const uint8_t caps[16]);
 
 /* ---------- Raw 802.11 TX / promiscuous RX ---------------------- */
 
@@ -200,6 +200,13 @@ typedef void (*esp_hosted_open_ieee154_rx_cb_t)(const uint8_t *frame, size_t len
 
 esp_err_t esp_hosted_open_register_ieee154_rx_cb(esp_hosted_open_ieee154_rx_cb_t cb, void *ctx);
 
+/* ---------- misc -------------------------------------------------- */
+
+/* Suppress noisy WIFI_EVENT_* notifications on the slave so the host
+ * only gets events it cares about. mask is a bitmap of event IDs;
+ * passing 0 re-enables everything. */
+esp_err_t esp_hosted_open_set_event_mask    (uint64_t mask);
+
 /* ---------- BLE / Bluetooth (already exposed by upstream) ----- */
 /*
  * BLE and BT classic come for free with the vendored esp-hosted:

host/include/esp_hosted_open.h esp_hosted_open/include/esp_hosted_open.hhost/include/esp_hosted_open.h renamed to esp_hosted_open/include/esp_hosted_open.h

@@ -115,6 +115,20 @@ extern "C" {
 #define PHY_RPC_REQ_IEEE154_SET_PROMISC PHY_RPC_MSG_REQ(0x043) /* uint8_t */
 #define PHY_RPC_REQ_IEEE154_TX_RAW    PHY_RPC_MSG_REQ(0x044)  /* raw frame */
 
+/* Wi-Fi event-mask suppression */
+#define PHY_RPC_REQ_SET_EVENT_MASK    PHY_RPC_MSG_REQ(0x027)  /* uint64_t mask */
+
+/* Reserved for BT-radio shockburst (nRF24L01+ emulation). The TX-gain
+ * knob (PHY_RPC_REQ_SET_BT_TX_GAIN) and filter override
+ * (PHY_RPC_REQ_SET_BT_FILTER) are wired; the rest of the sequence
+ * (preamble bytes, address registers, CRC mode, raw burst TX) needs
+ * scope-confirmed RE before slave handlers can land. msg_id slots are
+ * reserved here so the wire protocol stays stable when they ship. */
+#define PHY_RPC_REQ_BT_SET_PREAMBLE   PHY_RPC_MSG_REQ(0x050)  /* TBD */
+#define PHY_RPC_REQ_BT_SET_ADDRESS    PHY_RPC_MSG_REQ(0x051)  /* TBD */
+#define PHY_RPC_REQ_BT_SET_CRC_MODE   PHY_RPC_MSG_REQ(0x052)  /* TBD */
+#define PHY_RPC_REQ_BT_BURST_TX       PHY_RPC_MSG_REQ(0x053)  /* TBD */
+
 /* Response IDs (slave->host, sent via esp_hosted_send_custom_data
  * AFTER processing the matching request). Each carries a header with
  * the original op_id and an int32 status. */
@@ -169,6 +183,12 @@ extern "C" {
 #define PHY_RPC_RESP_IEEE154_SET_PROMISC  PHY_RPC_MSG_RESP(0x043)
 #define PHY_RPC_RESP_IEEE154_TX_RAW       PHY_RPC_MSG_RESP(0x044)
 
+#define PHY_RPC_RESP_SET_EVENT_MASK       PHY_RPC_MSG_RESP(0x027)
+#define PHY_RPC_RESP_BT_SET_PREAMBLE      PHY_RPC_MSG_RESP(0x050)
+#define PHY_RPC_RESP_BT_SET_ADDRESS       PHY_RPC_MSG_RESP(0x051)
+#define PHY_RPC_RESP_BT_SET_CRC_MODE      PHY_RPC_MSG_RESP(0x052)
+#define PHY_RPC_RESP_BT_BURST_TX          PHY_RPC_MSG_RESP(0x053)
+
 /* Async events (slave->host, no request/response correlation) */
 #define PHY_RPC_EVT_OCB_FRAME        PHY_RPC_MSG_EVT(0x001)  /* OCB-filtered LLC payload (V2X) */
 #define PHY_RPC_EVT_PHY_STATE        PHY_RPC_MSG_EVT(0x002)  /* periodic stats push */
@@ -391,6 +411,11 @@ typedef struct __attribute__((packed)) {
     uint8_t        frame[];
 } phy_rpc_req_ieee154_tx_raw_t;
 
+typedef struct __attribute__((packed)) {
+    phy_rpc_hdr_t hdr;
+    uint64_t       mask;          /* bitmap of WIFI_EVENT_* IDs to suppress */
+} phy_rpc_req_set_event_mask_t;
+
 /* Response bodies (after phy_rpc_resp_hdr_t) */
 
 typedef struct __attribute__((packed)) {
@@ -419,14 +444,16 @@ typedef struct __attribute__((packed)) {
     int8_t              celsius;
 } phy_rpc_resp_get_temperature_t;
 
-/* GET_CAPS reports which RPCs the slave's libphy.a actually exposes
- * on this chip — bit n is set iff request id (PHY_RPC_MSG_BASE | n) is
- * wired and the underlying symbol resolved at link time. The host
- * uses this to gracefully degrade. caps[0] covers msg ids 0x000-0x007,
- * caps[1] covers 0x008-0x00F, ..., caps[3] covers 0x018-0x01F. */
+/* GET_CAPS reports which RPCs the slave actually exposes on this
+ * chip — bit n of caps[] is set iff request id (PHY_RPC_MSG_BASE | n)
+ * is wired and the underlying symbol resolved at link time. The host
+ * uses this to gracefully degrade. 16 bytes covers msg ids
+ * 0x000-0x07F, which fits the current namespace plus all currently
+ * reserved future slots. */
+#define PHY_RPC_CAPS_BYTES 16
 typedef struct __attribute__((packed)) {
     phy_rpc_resp_hdr_t hdr;
-    uint8_t             caps[4];
+    uint8_t             caps[PHY_RPC_CAPS_BYTES];
 } phy_rpc_resp_get_caps_t;
 
 typedef struct __attribute__((packed)) {

host/include/phy_rpc_proto.h esp_hosted_open/include/phy_rpc_proto.hhost/include/phy_rpc_proto.h renamed to esp_hosted_open/include/phy_rpc_proto.h

@@ -324,6 +324,7 @@ esp_err_t esp_hosted_open_init(void)
         PHY_RPC_RESP_IEEE154_ENABLE,     PHY_RPC_RESP_IEEE154_SET_CHAN,
         PHY_RPC_RESP_IEEE154_SET_PANID,  PHY_RPC_RESP_IEEE154_SET_PROMISC,
         PHY_RPC_RESP_IEEE154_TX_RAW,
+        PHY_RPC_RESP_SET_EVENT_MASK,
     };
     for (size_t i = 0; i < sizeof(resp_ids) / sizeof(*resp_ids); i++) {
         esp_err_t err = esp_hosted_register_custom_callback(resp_ids[i], on_response, NULL);
@@ -552,19 +553,21 @@ esp_err_t esp_hosted_open_set_bt_filter(uint32_t reg_value)
                    &reg_value, sizeof(reg_value), NULL, 0, NULL);
 }
 
-esp_err_t esp_hosted_open_get_caps(uint8_t caps[4])
+esp_err_t esp_hosted_open_get_caps(uint8_t caps[16])
 {
     if (!caps) return ESP_ERR_INVALID_ARG;
+    memset(caps, 0, 16);
     size_t got = 0;
     return do_call(PHY_RPC_REQ_GET_CAPS, PHY_RPC_RESP_GET_CAPS,
-                   NULL, 0, caps, 4, &got);
+                   NULL, 0, caps, PHY_RPC_CAPS_BYTES, &got);
 }
 
-bool esp_hosted_open_has_capability(uint32_t request_msg_id, const uint8_t caps[4])
+bool esp_hosted_open_has_capability(uint32_t request_msg_id, const uint8_t caps[16])
 {
-    /* Low byte of msg_id is the index into our cap bitmap (0x000–0x01F). */
+    /* Low byte of msg_id is the bit index into our cap bitmap. 16 bytes
+     * × 8 bits = 128 slots, covering msg ids 0x00–0x7F. */
     uint32_t low = request_msg_id & 0xFFu;
-    if (low > 0x1F) return false;
+    if (low >= PHY_RPC_CAPS_BYTES * 8) return false;
     return (caps[low / 8] & (1u << (low % 8))) != 0;
 }
 
@@ -724,6 +727,12 @@ esp_err_t esp_hosted_open_ieee154_set_pan_id(uint16_t pan_id)
 esp_err_t esp_hosted_open_ieee154_set_promiscuous(bool enable)
 { ONE_BYTE_REQ(PHY_RPC_REQ_IEEE154_SET_PROMISC, PHY_RPC_RESP_IEEE154_SET_PROMISC, uint8_t, enable ? 1 : 0); }
 
+esp_err_t esp_hosted_open_set_event_mask(uint64_t mask)
+{
+    return do_call(PHY_RPC_REQ_SET_EVENT_MASK, PHY_RPC_RESP_SET_EVENT_MASK,
+                   &mask, sizeof(mask), NULL, 0, NULL);
+}
+
 esp_err_t esp_hosted_open_ieee154_tx_raw(const uint8_t *frame, size_t len, bool cca)
 {
     if (!frame || !len || len > 127) return ESP_ERR_INVALID_ARG;

host/src/phy_rpc.c esp_hosted_open/src/phy_rpc.chost/src/phy_rpc.c renamed to esp_hosted_open/src/phy_rpc.c

@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 3.16)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+# Point at the host stub library *as a single component* (not at its
+# parent — that would pull in slave/ etc. as accidental components).
+set(EXTRA_COMPONENT_DIRS
+    "${CMAKE_CURRENT_LIST_DIR}/../../esp_hosted_open"
+)
+# vendor/esp_hosted/ comes in via idf_component.yml override_path
+
+project(host_p4_demo)

examples/host_p4_demo/CMakeLists.txt

@@ -0,0 +1,5 @@
+idf_component_register(
+    SRCS "main.c"
+    INCLUDE_DIRS "."
+    REQUIRES esp_hosted_open esp_hosted nvs_flash esp_event esp_netif esp_wifi
+)

examples/host_p4_demo/main/CMakeLists.txt

@@ -0,0 +1,10 @@
+## Pulls esp_wifi_remote (and its deps eppp_link / esp_serial_slave_link /
+## wifi_remote_over_eppp) from the registry, but overrides esp_hosted to
+## use the vendored copy two levels up.
+dependencies:
+  idf:
+    version: ">=5.5"
+  espressif/esp_wifi_remote:
+    version: "1.5.1"
+  espressif/esp_hosted:
+    override_path: "../../../vendor/esp_hosted"

examples/host_p4_demo/main/idf_component.yml

@@ -0,0 +1,109 @@
+/*
+ * host_p4_demo — minimal P4 application that uses esp_hosted_open
+ * over SDIO to talk to an esp-hosted-open slave.
+ *
+ * What it does at boot:
+ *   1. esp_hosted_init()             — bring up SDIO transport
+ *   2. esp_hosted_open_init()        — register CITS custom-RPC handlers
+ *   3. get_caps()                    — see which RPCs the slave actually
+ *                                      exposes on this chip
+ *   4. get_info()                    — current slave state
+ *   5. set_channel(180)              — tune the C5 to CCH (5.900 GHz)
+ *   6. get_phy_rssi()                — single-shot RSSI poll
+ *   7. esp_now_init() + add_peer +
+ *      send                           — fire one ESP-NOW broadcast
+ *
+ * Each call uses *only* SDIO — no UART / serial console traffic, no
+ * SPI fallback. SDIO transport is asserted in sdkconfig.defaults.
+ */
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "esp_log.h"
+#include "esp_event.h"
+#include "esp_netif.h"
+#include "nvs_flash.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+#include "esp_hosted.h"
+#include "esp_hosted_open.h"
+#include "phy_rpc_proto.h"      /* PHY_RPC_REQ_* ids for capability checks */
+
+static const char *TAG = "host_demo";
+
+static void on_espnow_rx(const uint8_t *data, size_t len,
+                         const esp_hosted_open_espnow_meta_t *m, void *ctx)
+{
+    ESP_LOGI(TAG, "ESP-NOW rx %u B from %02x:%02x:%02x:%02x:%02x:%02x  rssi=%d",
+             (unsigned)len,
+             m->src_mac[0], m->src_mac[1], m->src_mac[2],
+             m->src_mac[3], m->src_mac[4], m->src_mac[5],
+             m->rssi_dbm);
+}
+
+void app_main(void)
+{
+    ESP_ERROR_CHECK(nvs_flash_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    ESP_ERROR_CHECK(esp_netif_init());
+
+    /* Bring up the SDIO transport to the slave. */
+    ESP_LOGI(TAG, "starting esp-hosted SDIO link…");
+    if (esp_hosted_init() != 0) {
+        ESP_LOGE(TAG, "esp_hosted_init failed");
+        return;
+    }
+    vTaskDelay(pdMS_TO_TICKS(1500));
+
+    /* Register the CITS custom-RPC layer. */
+    ESP_ERROR_CHECK(esp_hosted_open_init());
+    ESP_ERROR_CHECK(esp_hosted_open_register_espnow_rx_cb(on_espnow_rx, NULL));
+
+    /* Capability discovery — works for the full 0x000-0x07F namespace
+     * thanks to the 16-byte bitmap. */
+    uint8_t caps[16];
+    if (esp_hosted_open_get_caps(caps) == ESP_OK) {
+        ESP_LOGI(TAG, "slave caps:");
+        ESP_LOGI(TAG, "  channel set:      %d", esp_hosted_open_has_capability(PHY_RPC_REQ_SET_CHANNEL,    caps));
+        ESP_LOGI(TAG, "  802.11p:          %d", esp_hosted_open_has_capability(PHY_RPC_REQ_SET_PHY_11P,    caps));
+        ESP_LOGI(TAG, "  raw 802.11 TX:    %d", esp_hosted_open_has_capability(PHY_RPC_REQ_TX_80211,       caps));
+        ESP_LOGI(TAG, "  ESP-NOW:          %d", esp_hosted_open_has_capability(PHY_RPC_REQ_ESPNOW_INIT,    caps));
+        ESP_LOGI(TAG, "  802.15.4:         %d", esp_hosted_open_has_capability(PHY_RPC_REQ_IEEE154_ENABLE, caps));
+    }
+
+    esp_hosted_open_info_t info;
+    if (esp_hosted_open_get_info(&info) == ESP_OK) {
+        ESP_LOGI(TAG, "slave info: ch=%u tx=%d dBm 11p=%d cca=%d  fw=%s",
+                 info.channel, info.tx_power_dbm,
+                 info.phy_11p_armed, info.cca_enabled, info.fw_version);
+    }
+
+    /* Tune to ITS CCH (5.900 GHz). NOT_SUPPORTED on chips without 5 GHz. */
+    if (esp_hosted_open_has_capability(PHY_RPC_REQ_SET_CHANNEL, caps)) {
+        esp_err_t err = esp_hosted_open_set_channel(180);
+        ESP_LOGI(TAG, "set_channel(180): %s", esp_err_to_name(err));
+    }
+
+    int8_t rssi;
+    if (esp_hosted_open_get_phy_rssi(&rssi) == ESP_OK) {
+        ESP_LOGI(TAG, "PHY RSSI = %d dBm", rssi);
+    }
+
+    /* ESP-NOW broadcast — universal across every Wi-Fi-capable chip. */
+    if (esp_hosted_open_has_capability(PHY_RPC_REQ_ESPNOW_INIT, caps)) {
+        ESP_ERROR_CHECK(esp_hosted_open_espnow_init());
+        static const uint8_t broadcast[6] = {0xff, 0xff, 0xff, 0xff, 0xff, 0xff};
+        esp_hosted_open_espnow_add_peer(broadcast, NULL, 0, 0, false);
+        const char *msg = "hello from p4";
+        esp_err_t err = esp_hosted_open_espnow_send(broadcast,
+                                                    (const uint8_t *)msg,
+                                                    strlen(msg));
+        ESP_LOGI(TAG, "espnow_send broadcast: %s", esp_err_to_name(err));
+    }
+
+    /* Idle. SDIO transport drives everything via interrupts. */
+    while (1) vTaskDelay(pdMS_TO_TICKS(60000));
+}

examples/host_p4_demo/main/main.c

@@ -0,0 +1,23 @@
+CONFIG_IDF_TARGET="esp32p4"
+
+# Hosted Wi-Fi (radio lives on a remote chip)
+CONFIG_ESP_HOSTED_ENABLED=y
+CONFIG_ESP_WIFI_ENABLED=y
+
+# Peer-data RPC channel — required for esp_hosted_open custom RPCs
+CONFIG_ESP_HOSTED_ENABLE_PEER_DATA_TRANSFER=y
+CONFIG_ESP_HOSTED_MAX_CUSTOM_MSG_HANDLERS=32
+
+# === SDIO host transport ===
+# Explicitly select SDIO over the alternatives (SPI / SPI-HD / UART).
+CONFIG_ESP_HOSTED_SDIO_HOST_INTERFACE=y
+# CONFIG_ESP_HOSTED_SPI_HOST_INTERFACE is not set
+# CONFIG_ESP_HOSTED_SPI_HD_HOST_INTERFACE is not set
+# CONFIG_ESP_HOSTED_UART_HOST_INTERFACE is not set
+
+CONFIG_ESP_HOSTED_SDIO_SLOT_0=y
+CONFIG_ESP_HOSTED_SDIO_4_BIT_BUS=y
+CONFIG_ESP_HOSTED_SDIO_CLOCK_FREQ_KHZ=40000
+
+CONFIG_FREERTOS_HZ=1000
+CONFIG_LOG_DEFAULT_LEVEL_INFO=y