ESP-Hosted

September 9, 2026 · View on GitHub

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.

1. Overview

This high-level block diagram shows ESP-Hosted's relationship with the host MCU or Linux host and the ESP co-processor:

Architecture at a Glance

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.

Release tracking

Releases are published to the ESP Component Registry as espressif/esp_hosted.

Cloning the repo

git clone --recurse-submodules https://github.com/espressif/esp-hosted-mcu.git esp_hosted

The 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.

2. Directory Structure

High Level

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

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

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

port/
├── os/
│   ├── idf/                         ⎫
│   ├── posix/                       ⎬ OS-specific abstractions
│   └── stm32/                       ⎭
└── idf_components/         <------- OS agnostic - pre-ported ESP-IDF components

3. Linux host

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.

4. MCU host

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.

5. Example Layout

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:

Wi-Fi

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 (MCU host) & OpenThread

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.