{"id":49336242,"url":"https://github.com/datanoisetv/esp-hosted-open","last_synced_at":"2026-05-02T06:00:58.633Z","repository":{"id":353830816,"uuid":"1221074889","full_name":"DatanoiseTV/esp-hosted-open","owner":"DatanoiseTV","description":"Patched fork of esp-hosted-mcu that exposes every radio of an Espressif co-processor over SDIO: Wi-Fi 6, 802.11p / ITS-G5 / V2X, FTM ranging, CSI sensing, ESP-NOW, 802.15.4 / Thread / Zigbee. Research / lab use only.","archived":false,"fork":false,"pushed_at":"2026-04-26T20:05:22.000Z","size":3388,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T03:51:16.586Z","etag":null,"topics":["802-11p","802-15-4","csi","esp-hosted","esp-idf","esp-now","esp32","esp32-c5","esp32-c6","esp32-p4","ftm","its-g5","monitor-mode","research","sdio","thread","v2x","wifi","wifi6","zigbee"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DatanoiseTV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T18:08:02.000Z","updated_at":"2026-04-28T17:20:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DatanoiseTV/esp-hosted-open","commit_stats":null,"previous_names":["datanoisetv/esp-hosted-open"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DatanoiseTV/esp-hosted-open","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatanoiseTV%2Fesp-hosted-open","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatanoiseTV%2Fesp-hosted-open/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatanoiseTV%2Fesp-hosted-open/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatanoiseTV%2Fesp-hosted-open/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DatanoiseTV","download_url":"https://codeload.github.com/DatanoiseTV/esp-hosted-open/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatanoiseTV%2Fesp-hosted-open/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32454170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["802-11p","802-15-4","csi","esp-hosted","esp-idf","esp-now","esp32","esp32-c5","esp32-c6","esp32-p4","ftm","its-g5","monitor-mode","research","sdio","thread","v2x","wifi","wifi6","zigbee"],"created_at":"2026-04-27T01:01:58.934Z","updated_at":"2026-04-30T04:00:44.104Z","avatar_url":"https://github.com/DatanoiseTV.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esp-hosted-open\n\n**A patched fork of [esp-hosted-mcu] that lets a host MCU drive\n*every* radio of an Espressif co-processor — including the parts\nEspressif's stock firmware deliberately hides.**\n\n[esp-hosted-mcu]: https://github.com/espressif/esp-hosted-mcu\n\nStock esp-hosted gives you `esp_wifi_*` over SDIO. That's wonderful\nfor making a P4 act like a Wi-Fi STA, and useless if what you actually\nwant is a 5.9 GHz V2X radio, a monitor-mode sensor, an ESP-NOW peer,\na Thread/Zigbee co-processor, an FTM ranging master, a CSI sensor, or\nanything else that lives below the regulated `esp_wifi_*` surface.\n\nThis fork keeps upstream esp-hosted-mcu *untouched* in `vendor/` and\nadds:\n\n- one slave-side overlay component (`phy_rpc_overlay/`) that calls\n  into `libphy.a` directly,\n- one host-side stub library (`esp_hosted_open`) that ships **46\n  request RPCs and 8 async event channels** over esp-hosted's\n  generic peer-data transport.\n\n---\n\n## ⚠️ Experimental — research / lab use only\n\nRead this carefully.\n\n| | |\n|---|---|\n| **Undocumented internals.** | We call symbols (`phy_11p_set`, `phy_change_channel`, `phy_force_rx_gain`, `phy_disable_cca`, `phy_bb_bss_cbw40`, …) that aren't in any public header. Espressif may rename, remove, or change them between IDF releases without warning. We pin against IDF v6.0 and treat each upgrade as something that needs re-validation. |\n| **Regulatory risk is on you.** | This firmware will happily tune to 5.9 GHz ITS channels, disable carrier sense, override the regulatory country database, and force RX gain past safe operating limits. Doing any of that on the air without a license is illegal almost everywhere. Use a shielded enclosure, a fully-cabled setup with attenuators, or a regulator-issued research permit. |\n| **Not safety-certified.** | Don't put this in a vehicle, drone, ISM-band product, medical device, or anything else that hurts people or property when it misbehaves. We provide no warranty, express or implied — Apache-2.0, \"AS IS\". |\n| **Don't blame Espressif.** | The bugs you find here are *ours*, not theirs. Don't open issues against esp-hosted-mcu or the IDF for behaviour we introduced. |\n| **Spectrum manners.** | If you actually emit on the air, do it deliberately, briefly, and on bands you're entitled to. Stomping on real V2X traffic is dangerous; stomping on real Wi-Fi or Zigbee is rude. |\n\nBy using this code you accept that you alone are responsible for any\nRF emissions and for compliance with your local regulations.\n\n---\n\n## All wireless tech the silicon can do\n\nThis repo aims to expose **everything** the chip can transmit and\nreceive, not just regular Wi-Fi:\n\n| Stack            | Coverage                                                                          | Where         |\n|------------------|-----------------------------------------------------------------------------------|---------------|\n| 802.11 a/g/n/ax  | channel/freq/band/bandwidth/rate, raw TX, promiscuous RX with filter, MAC override, protocol selection | this repo |\n| 802.11p OCB      | best-effort via `phy_11p_set` + `phy_change_channel(172..184)`                    | this repo     |\n| 802.11mc FTM     | initiator API + per-burst report event (rtt_raw, rtt_est, dist_est)               | this repo     |\n| CSI sensing      | `phy_csidump_force_lltf_cfg` + per-frame CSI capture event                        | this repo     |\n| ESP-NOW          | full lifecycle: init/peers/send + RX/TX-status events                             | this repo     |\n| 802.15.4 / Thread / Zigbee | enable, channel (11–26), pan ID, promisc, raw TX + RX events. Works on C6/H2/H4; returns `NOT_SUPPORTED` on C5/S2/S3/C2/C3 | this repo |\n| Bluetooth LE / HCI | full HCI bridge + Bluedroid stack                                               | upstream esp-hosted (`esp_hosted_bt.h`, `esp_hosted_bluedroid.h`) |\n| BT-radio low-level | `phy_bt_set_tx_gain_new`, `phy_bt_filter_reg` (for nRF24L01+-style hacks)        | this repo (partial — full shockburst sequencer pending) |\n\nRuntime **capability discovery** lets the same host code work\nunchanged across chip choices: `esp_hosted_open_get_caps(caps)`\nreturns a 4-byte bitmap, and `esp_hosted_open_has_capability(REQ_ID, caps)`\ntells you whether the slave's firmware actually exposes that RPC. Swap\na C5 slave for a C6 and Thread support lights up automatically while\nthe 5 GHz / 802.11p calls start returning `NOT_SUPPORTED`.\n\nFor the universal map of **which `libphy.a` symbol is exported on\nwhich chip**, see [docs/symbol-reference.md](docs/symbol-reference.md).\n\n---\n\n## Quick start\n\n### 1. Flash the slave (no IDF install needed)\n\n```sh\ngit clone https://github.com/DatanoiseTV/esp-hosted-open\ncd esp-hosted-open\nfirmware/flash.sh /dev/cu.usbserial-XXXX\n```\n\nThe merged binary in `firmware/c5_slave_merged.bin` is rebuilt by CI\non every push and attached to release tags. It writes to flash offset\n`0x0` on a 4 MB esp32c5, dio mode at 80 MHz.\n\n### 2. Wire it to your host\n\n| Signal | Default P4 GPIO | Notes |\n|--------|-----------------|-------|\n| CLK    | 18 | |\n| CMD    | 19 | |\n| D0–D3  | 14, 15, 16, 17 | |\n| RESET  | 54 | drives the C5's `EN` line |\n\nOverride these in your host project's `sdkconfig.defaults` if your\nhardware differs.\n\n### 3. Pull host + vendored upstream into your project\n\n```yaml\n# main/idf_component.yml\ndependencies:\n  espressif/esp_wifi_remote: \"^1.5\"\n  espressif/esp_hosted:\n    override_path: \"../../components/vendor/esp-hosted-mcu\"\n```\n\nCopy `vendor/esp-hosted-mcu/` and `host/` from this repo into your\nproject under `components/vendor/` and `components/host/`. Then\n`REQUIRES esp_hosted_open` in `main/CMakeLists.txt` and:\n\n```c\n#include \"esp_hosted.h\"          /* upstream — STA/AP/HCI/BLE       */\n#include \"esp_hosted_open.h\"     /* this fork — extra PHY + radios  */\n\nesp_hosted_init();               /* upstream link bring-up          */\nesp_hosted_open_init();          /* register our extra RPC handlers */\n\n/* Channel + 802.11p PHY toggle (C5 ITS-G5 example) */\nesp_hosted_open_set_country_permissive();\nesp_hosted_open_set_phy_11p(true);\nesp_hosted_open_set_channel(180);\nesp_hosted_open_set_agc_max_gain(255);\nesp_hosted_open_set_low_rate(false);\n\n/* Or send an ESP-NOW frame to a peer (works on every Wi-Fi chip) */\nesp_hosted_open_espnow_init();\nesp_hosted_open_espnow_add_peer(peer_mac, NULL, 0, 0, false);\nesp_hosted_open_espnow_send(peer_mac, \"hello\", 5);\n\n/* Or initiate FTM ranging */\nesp_hosted_open_register_ftm_cb(on_ftm_report, NULL);\nesp_hosted_open_ftm_initiate(ap_mac, /*frames*/16, /*period*/2, /*ch*/6);\n\n/* Or capture every 802.11 frame on the air */\nesp_hosted_open_register_raw_rx_cb(on_frame, NULL);\nesp_hosted_open_set_promisc_filter(WIFI_PROMIS_FILTER_MASK_ALL);\nesp_hosted_open_set_promisc(true);\n```\n\nThe full API surface is documented in\n[`host/include/esp_hosted_open.h`](host/include/esp_hosted_open.h).\n\n---\n\n## Architecture\n\n```\n   ┌──────────────────────────┐  SDIO 4-bit  ┌────────────────────────────┐\n   │   Host MCU (P4, S3, …)   │   @ 50 MHz   │  Espressif co-processor    │\n   │                          │              │  (C5: Wi-Fi 6 + BLE)       │\n   │  your application code   │ ◄──────────► │  (C6: + 802.15.4)          │\n   │  esp_hosted_open_*()     │              │  (H2/H4: 15.4 + BLE only)  │\n   │                          │              │                            │\n   │  ┌──────────────────┐    │              │  upstream esp-hosted-mcu   │\n   │  │  this repo's     │    │              │  + slave/components/       │\n   │  │  host/           │    │              │      phy_rpc_overlay/      │\n   │  │  esp_hosted_open │    │              │    ├ phy_rpc_handlers.c    │\n   │  └──────────────────┘    │              │    ├ phy_rpc_extras.c      │\n   │  + upstream esp_hosted   │              │    └ phy_rpc_wireless.c    │\n   └──────────────────────────┘              │  + libphy.a (binary blob)  │\n                                              └────────────────────────────┘\n                                                          │\n                               ┌──────────────────────────┼──────────────────────────┐\n                               ▼                          ▼                          ▼\n                        2.4 GHz Wi-Fi          5 GHz Wi-Fi (C5/C61)        2.4 GHz BLE / 802.15.4\n                        ESP-NOW                ITS / V2X channels          (per-chip support)\n```\n\nThe upstream esp-hosted snapshot (under `vendor/esp-hosted-mcu/`) is\nkept verbatim so rebases against future upstream releases stay\ntrivial. **No upstream files are modified** — every patch lives in\nthe sibling overlay directory. Same on the host side: our additions\nare a separate `host/` component layered on top of upstream's\n`esp_hosted` via a normal `REQUIRES`.\n\nThe slave-side overlay is split across three files for review-ability:\n\n- `phy_rpc_handlers.c` — matrix-row PHY hacks (channel, gain, CCA, …)\n- `phy_rpc_extras.c` — raw 802.11 TX/RX, promiscuous, CSI, FTM, MAC, protocol\n- `phy_rpc_wireless.c` — ESP-NOW + 802.15.4\n\n---\n\n## What's covered today (and what isn't)\n\n✅ **Build-verified** against ESP-IDF v6.0 via CI on every push:\nslave for esp32c5, P4 host example, host-runnable proto tests. Slave\nfits in the C5's 1.875 MB factory partition with 26 % free; host\nexample is ~580 kB on the P4 (43 % free in a 1 MB partition).\n\n❌ **No hardware testing has been performed.** Nothing in this repo\nhas been put on a scope, an SDR, or against a real ITS / Thread /\nnRF24 / FTM peer. The RPCs compile and the wire protocol round-trips\nin CI; what each one *actually does at the radio level* is inferred\nfrom `libphy.a` symbol names + community work, not measured. Don't\ntrust on-air behaviour until you've verified it yourself.\n\n⚠️ **Particularly suspect** until proven on hardware:\n\n- Whether `phy_11p_set(1, 0)` produces a waveform that real 802.11p\n  front-ends demodulate. The C5 PHY is a 20 MHz OFDM design; ETSI\n  802.11p uses 10 MHz channels. At best this is a 20-MHz Wi-Fi-shaped\n  frame on a 5.9 GHz channel that *some* 11p radios will accept.\n- The BT-radio TX-gain knob actually emitting on the band you expect.\n- The 802.15.4 path on a C6/H2/H4 (we've never built for those targets).\n- Whether the slave's queued event channel keeps up under load.\n\n⚠️ **No safety hooks.** A single host-side typo can put the radio\ninto states the FCC / ETSI test masks would fail. Lock down RF\nemission at the test-bench level, not in software.\n\n❌ **Still missing** (PRs welcome — see\n[docs/extending.md](docs/extending.md) for the recipe):\n\n- A complete BT-radio shockburst sequencer (preamble + CRC + address\n  registers) for nRF24L01+ emulation. The TX-gain knob is wrapped\n  but the rest of the BT-PHY surface needs scope-confirmed RE.\n- Mesh / SmartConfig sniff hooks.\n- `esp_wifi_set_event_mask` (suppress noisy `WIFI_EVENT_*` on the\n  slave so the host only gets what it cares about).\n\n---\n\n## Layout\n\n```\nvendor/esp-hosted-mcu/             upstream snapshot, untouched (Apache-2.0)\nslave/                             slave firmware project (esp32c5 default)\n  components/phy_rpc_overlay/      our fork patch — three files, see above\nhost/                              host-side stub library (esp_hosted_open)\n  include/                         esp_hosted_open.h  +  phy_rpc_proto.h\nfirmware/                          prebuilt c5_slave_merged.bin + flash.sh\ntests/host/                        gcc-only proto sanity checks\ndocs/                              extension recipe + universal symbol map\n.github/workflows/build.yml        CI: host tests + slave + merged image\n```\n\nEvery wireless RPC's underlying libphy.a / IDF symbol is enumerated\nacross all 10 Espressif chips in\n[docs/symbol-reference.md](docs/symbol-reference.md).\n\n---\n\n## Use cases this enables\n\n- **5.9 GHz / ITS-G5 / 802.11p** — protocol stack lives in\n  [esp32-c5-v2x](https://github.com/DatanoiseTV/esp32-c5-v2x)\n  (CAM/DENM encoders, GeoNetworking, BTP, asn1c-based codec). That\n  repo depends on this one for everything below the LLC layer.\n- **Monitor-mode capture** of arbitrary 802.11 traffic with\n  per-frame metadata (RSSI, channel, rate, QoS flag, timestamp)\n  forwarded to the host as `RAW_FRAME` events.\n- **CSI-based sensing** (presence, gesture, breathing) with per-frame\n  CSI buffers piped over SDIO.\n- **802.11mc FTM ranging** — single-call initiator with\n  millisecond-resolution distance estimates.\n- **ESP-NOW peer networks** at low latency, no IP overhead, no AP\n  needed — universal across every Wi-Fi-capable Espressif chip.\n- **Thread / Zigbee** when the slave is a C6 / H2 / H4 — same host\n  binary, capability bitmap takes care of the rest.\n- **Channel-busy ratio (CBR)** measurement for spectrum studies.\n- **Manual RX-gain sweeps** for sensitivity characterisation.\n- **Disabling CCA** for back-to-back loopback or PHY conformance work.\n- **Anything else the public esp-hosted API doesn't reach.** The\n  symbol reference enumerates 1366 `phy_*` exports across the chip\n  family — only a fraction is wrapped today.\n\n---\n\n## Contributing\n\nThis is research code. Issues, PRs, and \"I scoped this and here's\nwhat it looks like\" reports are all welcome. Particularly useful:\n\n- A new RPC for an unwrapped libphy symbol — follow\n  [docs/extending.md](docs/extending.md). The recipe is mechanical:\n  one packed struct + one host stub + one slave handler + one test\n  assertion.\n- Spectrum / scope evidence for what an undocumented symbol actually\n  does on a particular chip.\n- A documented success / failure on different module batches —\n  on-die radio tweaks vary across silicon revisions.\n\n---\n\n## Acknowledgements\n\n- Espressif for the underlying esp-hosted-mcu transport. This fork\n  keeps their code untouched in `vendor/`.\n- [opentrafficmap/its-g5-receiver-firmware](https://codeberg.org/opentrafficmap/its-g5-receiver-firmware)\n  for documenting the original `phy_11p_set(1, 0)` +\n  `phy_change_channel(ch, 1, 0, 0)` bootstrap sequence on the C5.\n\n---\n\n## License\n\nApache-2.0, matching upstream esp-hosted-mcu. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatanoisetv%2Fesp-hosted-open","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatanoisetv%2Fesp-hosted-open","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatanoisetv%2Fesp-hosted-open/lists"}