Turn an Espressif SoC into a Wi-Fi, Bluetooth and OpenThread co-processor for your host. Your main processor keeps running your application, while the ESP SoC handles the heavy lifting of the radio and network stack over a simple transport bus.
It supports Linux and MCU hosts over SDIO, SPI, and UART using an Espressif SoC as the coprocessor.
This high-level block diagram shows ESP-Hosted's relationship with the host MCU or Linux host and the ESP co-processor:
The host keeps the product logic. The ESP co-processor offloads the radio and network stack over your chosen transport bus. See Architecture for the details.
Releases are published to the ESP Component Registry as espressif/esp_hosted.
git clone --recurse-submodules https://github.com/espressif/esp-hosted-mcu.git esp_hostedThe repository is named esp-hosted-mcu, but the registry component is maintained as esp_hosted, so the repository is cloned into the esp_hosted directory for consistency.
esp-hosted/
├── coprocessor/ <------- co-processor code
├── common/ <------- CP + host shared (frame, tlv, mempool, serializers)
├── docs/
│ ├── getting-started-linux.md ⎫
│ ├── getting-started-mcu.md ⎪
│ ├── architecture.md ⎪
│ ├── transports/ ⎪
│ ├── features/ ⎬ Documentation
│ ├── design/ ⎪
│ └── ... ⎭
│
├── examples/ ⎫
│ ├── wifi/sta/ ⎪
│ │ ├── cp/ ⎪
│ │ ├── mcu_host/ ⎬ Examples organization
│ │ └── linux_802_3_host/ ⎪
│ ├── bluetooth/ ⎪
│ ├── network_split/ ⎪
│ └── ... ⎭
│
├── host/ <------- Host code
├── port/ <------- Linux and MCU host porting
├── tests/
└── tools/
coprocessor/
├── eh_cp_core/ <------- Core
├── eh_cp_transport/ <------- SPI/SDIO/UART bus drivers
└── features/ ⎫
├── eh_cp_feat_bt/ ⎪
├── eh_cp_feat_wifi/ ⎪
├── eh_cp_feat_nw_split/ ⎬ (Opt) Configurable features
├── eh_cp_feat_host_ps/ ⎪
└── ... ⎭
host/
├── eh_host_core/ <------- Platform-agnostic core
├── features/ ⎫
│ ├── eh_host_feat_bt/ ⎪
│ ├── eh_host_feat_wifi/ ⎪
│ ├── eh_host_feat_nw_split/ ⎬ (Opt) Configurable features
│ ├── eh_host_feat_power_save/ ⎪
│ └── ... ⎭
│
├── linux/ ⎫
│ ├── eh_host_linux_kmod/ <--- Linux kernel module ⎪
│ ├── eh_host_linux_python_ctypes/ ⎬ Linux specific
│ └── eh_host_linux_vserial/ <--- Virtual serial iface ⎭
└── mcu/
├── eh_host_mcu_transport/ <--- SPI/SDIO/UART bus drivers
└── eh_host_mcu_vserial/ <--- Virtual serial iface
port/
├── os/
│ ├── idf/ ⎫
│ ├── posix/ ⎬ OS-specific abstractions
│ └── stm32/ ⎭
└── idf_components/ <------- OS agnostic - pre-ported ESP-IDF components
The following guide demonstrates a Raspberry Pi host with an ESP32-C5 co-processor — but the solution is not tied to that hardware.
| What | Supported | Demonstrated |
|---|---|---|
| Host | Any Linux platform (with porting) | Raspberry Pi 3 or 4 or 5 |
| Co-processor | Any ESP SoC | ESP32-C5 (also C6, C61, C3, C2, S2, S3, ESP32) |
| Buses | SDIO | SDIO + UART | SPI | SPI + UART |
All |
- Get started: Follow the Linux Host guide to set up the Wi-Fi station example. It provides a step-by-step Raspberry Pi walkthrough for setup and verification.
- Using a different Linux platform? See the Linux Porting guide.
After verifying the Wi-Fi station example, move on to the supported examples.
The following guide demonstrates an ESP32-P4 host with an ESP32-C6 co-processor — again, not a hard requirement.
| What | Supported | Demonstrated |
|---|---|---|
| ESP Host | Any ESP SoC | ESP32-P4 with an ESP32-C6 as co-processor |
| Non-ESP MCU Host | Any MCU (with porting) | - |
| Co-processor | Any ESP SoC | ESP32-C6 (also C5, C61, C3, C2, S2, S3, ESP32) |
| Buses | SDIO | SPI Full-Duplex | SPI Half-Duplex (1/2/4 bit) | UART |
All |
- Get started: Follow the MCU Host guide to set up the Wi-Fi station example.
- Non-ESP MCU / RTOS? See MCU Porting guide.
After verifying the Wi-Fi station example, move on to the supported examples.
Each example is organised by role. Not every example has every role — the example's own README is the source of truth.
examples/<feature>/<scenario>/
├── cp/ co-processor firmware (ESP-IDF project) — always present
├── mcu_host/ generic MCU host application
├── esp_host/ ESP-IDF host (deep sleep, OpenThread, rich console)
└── linux_802_3_host/
├── kmod/ Linux kernel transport module
├── c_app/ C user-space application
└── py_app/ Python (ctypes) application
Flash cp/ to the ESP coprocessor, then build and run one host role (mcu_host, esp_host, or the appropriate linux_802_3_host components) on your matching host platform. Examples are grouped by functionality:
- Station — connect to an AP (recommended first network test).
- Scan — scan for nearby APs.
- SoftAP — co-processor as an access point.
- AP+STA — station and SoftAP concurrently.
- Enterprise — WPA Enterprise client.
- DPP — Device Provisioning Protocol.
- iTWT — individual Target Wake Time power save.
- Bluetooth Examples — BLE and Classic BT controller HCI (NimBLE / BlueDroid). On Linux, use BlueZ directly — no example needed.
- OpenThread CLI — Thread command-line interface.
- OpenThread Border Router — Thread border router.
- GPIO Expander — drive co-processor GPIOs remotely.
- Peer Data Transfer — send custom control/data payloads.
- External Coexistence — coordinate with external radios.
- Coprocessor OTA — update co-processor firmware over-the-air.
- Get CP FW Version — query the co-processor firmware version.
- MCU Hosted SDIO + SD Card Combined — share SDIO pins with an SD card.
- Hosted Events — listen to co-processor system events.
- API Exerciser — control-plane RPC verification.
- MCU Transport Config — configure transport pins and parameters.
- Memory Monitor — track co-processor heap.