# espressif/esp-hosted architecture

> Architecture diagram of the GitHub repository espressif/esp-hosted, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/espressif/esp-hosted
- Repository: https://github.com/espressif/esp-hosted

## Overview

#### Purpose and variants
ESP-Hosted turns an Espressif SoC into a Wi-Fi/Bluetooth coprocessor attached to a Linux or MCU host over SPI, SDIO, or UART. The repository maintains two materially different stacks:
- **NG**: Linux-native 802.11/cfg80211 and Bluetooth HCI integration.
- **FG**: Ethernet-style host networking with protobuf RPC control; also includes an STM32 host port.
Core roots: `esp_hosted_ng/`, `esp_hosted_fg/`, `README.md`.

#### Build and firmware entry points
Each variant builds ESP firmware as an ESP-IDF network-adapter application, selected per supported ESP target through SDK defaults and partition tables. The ESP-IDF application entry is NG `esp_hosted_ng/esp/esp_driver/network_adapter/main/app_main.c`; FG centers on `esp_hosted_fg/esp/esp_driver/network_adapter/main/esp_hosted_coprocessor.c`. CI firmware assembly is driven by `.gitlab/ci/build_firmware.sh`.

The ESP endpoint is the boundary between Espressif Wi-Fi/BT facilities and the hosted wire protocol. It initializes the adapter, services control commands, and supplies SDIO/SPI slave implementations:
`esp_hosted_ng/esp/esp_driver/network_adapter/main/cmd.c`,
`esp_hosted_ng/esp/esp_driver/network_adapter/main/sdio_slave_api.c`,
`esp_hosted_ng/esp/esp_driver/network_adapter/main/spi_slave_api.c`.

#### NG Linux driver path
NG’s host is a Linux kernel driver, built from `esp_hosted_ng/host/Makefile` with module initialization in `esp_hosted_ng/host/main.c`. It exposes the coprocessor as standard Linux Wi-Fi through cfg80211, so normal host networking services such as NetworkManager and wpa_supplicant own Wi-Fi configuration:
`esp_hosted_ng/host/esp_cfg80211.c`,
`esp_hosted_ng/host/esp_cmd.c`,
`esp_hosted_ng/host/esp_bt.c`.

Its primary flow is Linux networking/Bluetooth APIs → NG driver command/data framing → SPI or SDIO transport → ESP firmware → radio stack. Transport-specific host boundaries are:
`esp_hosted_ng/host/spi/esp_spi.c`,
`esp_hosted_ng/host/sdio/esp_sdio.c`.

#### FG ESP coprocessor and protocol
FG separates data, control, and optional network-split behavior. The firmware-side control plane is implemented in:
`esp_hosted_fg/esp/esp_driver/network_adapter/main/slave_control.c`,
`esp_hosted_fg/esp/esp_driver/network_adapter/main/nw_split_router.c`,
`esp_hosted_fg/esp/esp_driver/network_adapter/main/slave_bt.c`.

Configuration RPC schemas are protobuf-defined, then generated into shared C bindings:
`esp_hosted_fg/common/proto/esp_hosted_config.proto`,
`esp_hosted_fg/common/esp_hosted_config.pb-c.c`.
This is the compatibility boundary for host applications and custom control behavior.

#### FG Linux host integration
FG’s Linux kernel driver presents an 802.3-oriented interface and bridges bus framing, firmware validation, Bluetooth, and host networking:
`esp_hosted_fg/host/linux/host_driver/esp32/main.c`,
`esp_hosted_fg/host/linux/host_driver/esp32/esp_if.h`,
`esp_hosted_fg/host/linux/host_driver/esp32/esp_fw_verify.c`.

Control clients do not use cfg80211. They call the reusable control library (`esp_hosted_fg/host/control_lib/src/ctrl_api.c`, `esp_hosted_fg/host/control_lib/src/ctrl_core.c`) through C shell/daemon support or Python bindings:
`esp_hosted_fg/host/linux/host_control/c_support/hosted_daemon.c`,
`esp_hosted_fg/host/linux/host_control/python_support/commands_lib.py`.

#### MCU host port and hardware abstraction
FG includes a concrete STM32 host architecture. Application/control code invokes a network-device abstraction, which dispatches through a common transport layer to SDIO or SPI drivers:
`esp_hosted_fg/host/stm32/app/app_main.c`,
`esp_hosted_fg/host/stm32/driver/network/netdev_api.c`,
`esp_hosted_fg/host/stm32/driver/transport/transport_drv.c`.

Platform wrappers isolate OS/board primitives for portable host-side code:
`esp_hosted_fg/host/linux/port/src/platform_wrapper.c`,
`esp_hosted_fg/host/stm32/port/src/platform_wrapper.c`.

#### Runtime and infrastructure boundaries
Material runtimes are ESP-IDF firmware on ESP32-family targets, Linux kernel-space drivers plus optional C/Python user-space control clients, and STM32 embedded firmware. External hardware interfaces are SPI, SDIO, and UART/serial; external host services are Linux networking/cfg80211 and Bluetooth HCI. Prebuilt ESP Wi-Fi support libraries are target-specific under `esp_hosted_ng/esp/esp_driver/lib/`, while protocol and platform abstractions prevent host implementations from directly coupling to ESP radio internals.

Main entry points: [`esp_hosted_fg/host/control_lib/src/ctrl_core.c`](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/control_lib/src/ctrl_core.c) (Control library), [`esp_hosted_ng/host/main.c`](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/main.c) (NG kernel driver), [`esp_hosted_fg/common/esp_hosted_config.pb-c.c`](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/common/esp_hosted_config.pb-c.c) (Generated C bindings), [`esp_hosted_fg/esp/esp_driver/network_adapter/main/esp_hosted_coprocessor.c`](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/esp/esp_driver/network_adapter/main/esp_hosted_coprocessor.c) (FG ESP coprocessor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ng["NG stack"]
  node_linux_services(("Linux Wi-Fi services<br/>external service"))
  node_ng_driver["NG kernel driver<br/>Linux kernel module<br/>[main.c]"]
  node_ng_cfg["cfg80211 integration<br/>Wi-Fi integration<br/>[esp_cfg80211.c]"]
  node_ng_commands["NG command framing<br/>protocol layer<br/>[esp_cmd.c]"]
  node_ng_bt["Bluetooth HCI<br/>Bluetooth integration<br/>[esp_bt.c]"]
  node_ng_bus["SPI / SDIO host transport<br/>bus drivers<br/>[esp_spi.c]"]
end

subgraph group_fg["FG stack"]
  node_fg_linux_driver["FG Linux driver<br/>802.3 kernel driver<br/>[main.c]"]
  node_fg_control_lib["Control library<br/>RPC client library<br/>[ctrl_core.c]"]
  node_fg_daemon["C daemon clients<br/>user-space control<br/>[hosted_daemon.c]"]
  node_fg_python["Python control clients<br/>user-space bindings<br/>[commands_lib.py]"]
  node_stm_app["STM32 application<br/>embedded host app<br/>[app_main.c]"]
  node_stm_netdev["STM32 network abstraction<br/>network device API<br/>[netdev_api.c]"]
  node_stm_transport["STM32 transport layer<br/>transport dispatcher<br/>[transport_drv.c]"]
  node_proto_schema["Control RPC schema<br/>protobuf schema"]
  node_proto_bindings["Generated C bindings<br/>protobuf bindings"]
end

subgraph group_esp["ESP firmware"]
  node_ng_esp_endpoint["NG ESP endpoint<br/>ESP-IDF application<br/>[app_main.c]"]
  node_ng_esp_bus["NG ESP slave transport<br/>SPI / SDIO slave<br/>[sdio_slave_api.c]"]
  node_fg_esp_endpoint["FG ESP coprocessor<br/>ESP-IDF application"]
  node_fg_control["FG control and split router<br/>firmware control plane<br/>[slave_control.c]"]
  node_radio(("ESP Wi-Fi / Bluetooth<br/>radio facilities"))
end

node_linux_services -->|"cfg80211"| node_ng_cfg
node_ng_cfg -->|"Wi-Fi operations"| node_ng_driver
node_ng_bt -->|"HCI integration"| node_ng_driver
node_ng_driver -->|"frames commands/data"| node_ng_commands
node_ng_commands -->|"uses"| node_ng_bus
node_ng_bus -->|"SPI or SDIO"| node_ng_esp_bus
node_ng_esp_bus -->|"delivers frames"| node_ng_esp_endpoint
node_ng_esp_endpoint -->|"adapter API"| node_radio
node_fg_linux_driver -->|"SPI / SDIO / UART framing"| node_fg_esp_endpoint
node_fg_daemon -->|"uses"| node_fg_control_lib
node_fg_python -->|"uses"| node_fg_control_lib
node_fg_control_lib -->|"serializes RPC"| node_proto_bindings
node_proto_schema -->|"generates"| node_proto_bindings
node_fg_control_lib -->|"control path"| node_fg_linux_driver
node_stm_app -->|"network operations"| node_stm_netdev
node_stm_netdev -->|"dispatches"| node_stm_transport
node_stm_transport -->|"SPI or SDIO"| node_fg_esp_endpoint
node_fg_esp_endpoint -->|"services control"| node_fg_control
node_proto_bindings -.->|"shared RPC contract"| node_fg_control
node_fg_control -->|"Wi-Fi / Bluetooth control"| node_radio

click node_ng_driver "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/main.c"
click node_ng_cfg "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/esp_cfg80211.c"
click node_ng_commands "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/esp_cmd.c"
click node_ng_bt "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/esp_bt.c"
click node_ng_bus "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/spi/esp_spi.c"
click node_fg_linux_driver "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/linux/host_driver/esp32/main.c"
click node_fg_control_lib "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/control_lib/src/ctrl_core.c"
click node_fg_daemon "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/linux/host_control/c_support/hosted_daemon.c"
click node_fg_python "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/linux/host_control/python_support/commands_lib.py"
click node_stm_app "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/stm32/app/app_main.c"
click node_stm_netdev "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/stm32/driver/network/netdev_api.c"
click node_stm_transport "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/stm32/driver/transport/transport_drv.c"
click node_proto_schema "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/common/proto/esp_hosted_config.proto"
click node_proto_bindings "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/common/esp_hosted_config.pb-c.c"
click node_ng_esp_endpoint "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/esp/esp_driver/network_adapter/main/app_main.c"
click node_ng_esp_bus "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/esp/esp_driver/network_adapter/main/sdio_slave_api.c"
click node_fg_esp_endpoint "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/esp/esp_driver/network_adapter/main/esp_hosted_coprocessor.c"
click node_fg_control "https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/esp/esp_driver/network_adapter/main/slave_control.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_linux_services,node_ng_driver,node_ng_cfg,node_ng_commands,node_ng_bt,node_ng_bus toneBlue
class node_fg_linux_driver,node_fg_control_lib,node_fg_daemon,node_fg_python,node_stm_app,node_stm_netdev,node_stm_transport,node_proto_schema,node_proto_bindings toneAmber
class node_ng_esp_endpoint,node_ng_esp_bus,node_fg_esp_endpoint,node_fg_control,node_radio toneMint
```

## Components

### NG stack

Linux-native Wi-Fi and Bluetooth integration.

- **Linux Wi-Fi services**: external service · NetworkManager and wpa_supplicant configure Wi-Fi through cfg80211.
- [NG kernel driver](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/main.c): Linux kernel module · Initializes the NG host driver and standard Linux interfaces. · `esp_hosted_ng/host/main.c`
- [cfg80211 integration](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/esp_cfg80211.c): Wi-Fi integration · `esp_hosted_ng/host/esp_cfg80211.c`
- [NG command framing](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/esp_cmd.c): protocol layer · `esp_hosted_ng/host/esp_cmd.c`
- [Bluetooth HCI](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/esp_bt.c): Bluetooth integration · `esp_hosted_ng/host/esp_bt.c`
- [SPI / SDIO host transport](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/host/spi/esp_spi.c): bus drivers · `esp_hosted_ng/host/spi/esp_spi.c`

### FG stack

Ethernet-style host networking and RPC control.

- [FG Linux driver](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/linux/host_driver/esp32/main.c): 802.3 kernel driver · Bridges Ethernet-style networking, bus framing, firmware validation, and Bluetooth. · `esp_hosted_fg/host/linux/host_driver/esp32/main.c`
- [Control library](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/control_lib/src/ctrl_core.c): RPC client library · Reusable protobuf control API and core. · `esp_hosted_fg/host/control_lib/src/ctrl_core.c`
- [C daemon clients](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/linux/host_control/c_support/hosted_daemon.c): user-space control · `esp_hosted_fg/host/linux/host_control/c_support/hosted_daemon.c`
- [Python control clients](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/linux/host_control/python_support/commands_lib.py): user-space bindings · `esp_hosted_fg/host/linux/host_control/python_support/commands_lib.py`
- [STM32 application](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/stm32/app/app_main.c): embedded host app · `esp_hosted_fg/host/stm32/app/app_main.c`
- [STM32 network abstraction](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/stm32/driver/network/netdev_api.c): network device API · `esp_hosted_fg/host/stm32/driver/network/netdev_api.c`
- [STM32 transport layer](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/host/stm32/driver/transport/transport_drv.c): transport dispatcher · Dispatches to SDIO or SPI drivers. · `esp_hosted_fg/host/stm32/driver/transport/transport_drv.c`
- [Control RPC schema](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/common/proto/esp_hosted_config.proto): protobuf schema · Shared compatibility boundary for configuration RPC. · `esp_hosted_fg/common/proto/esp_hosted_config.proto`
- [Generated C bindings](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/common/esp_hosted_config.pb-c.c): protobuf bindings · `esp_hosted_fg/common/esp_hosted_config.pb-c.c`

### ESP firmware

ESP-IDF coprocessor firmware for ESP32-family targets.

- [NG ESP endpoint](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/esp/esp_driver/network_adapter/main/app_main.c): ESP-IDF application · Initializes the adapter and services hosted commands. · `esp_hosted_ng/esp/esp_driver/network_adapter/main/app_main.c`
- [NG ESP slave transport](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_ng/esp/esp_driver/network_adapter/main/sdio_slave_api.c): SPI / SDIO slave · `esp_hosted_ng/esp/esp_driver/network_adapter/main/sdio_slave_api.c`
- [FG ESP coprocessor](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/esp/esp_driver/network_adapter/main/esp_hosted_coprocessor.c): ESP-IDF application · Firmware endpoint for FG data and control planes. · `esp_hosted_fg/esp/esp_driver/network_adapter/main/esp_hosted_coprocessor.c`
- [FG control and split router](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/esp/esp_driver/network_adapter/main/slave_control.c): firmware control plane · Services control RPC, Bluetooth, and optional network split routing. · `esp_hosted_fg/esp/esp_driver/network_adapter/main/slave_control.c`
- **ESP Wi-Fi / Bluetooth**: radio facilities · Target-specific ESP Wi-Fi support libraries back the coprocessor.

## Connections

- Linux Wi-Fi services → cfg80211 integration: cfg80211
- cfg80211 integration → NG kernel driver: Wi-Fi operations
- Bluetooth HCI → NG kernel driver: HCI integration
- NG kernel driver → NG command framing: frames commands/data
- NG command framing → SPI / SDIO host transport: uses
- SPI / SDIO host transport → NG ESP slave transport: SPI or SDIO
- NG ESP slave transport → NG ESP endpoint: delivers frames
- NG ESP endpoint → ESP Wi-Fi / Bluetooth: adapter API
- FG Linux driver → FG ESP coprocessor: SPI / SDIO / UART framing
- C daemon clients → Control library: uses
- Python control clients → Control library: uses
- Control library → Generated C bindings: serializes RPC
- Control RPC schema → Generated C bindings: generates
- Control library → FG Linux driver: control path
- STM32 application → STM32 network abstraction: network operations
- STM32 network abstraction → STM32 transport layer: dispatches
- STM32 transport layer → FG ESP coprocessor: SPI or SDIO
- FG ESP coprocessor → FG control and split router: services control
- Generated C bindings → FG control and split router: shared RPC contract
- FG control and split router → ESP Wi-Fi / Bluetooth: Wi-Fi / Bluetooth control