espressif/esp-hosted

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.