ESP-Hosted turns an ESP32 into a Wi-Fi, Bluetooth and Thread coprocessor for Linux and microcontrollers

This repository is now the index, not the implementation

The most important structural fact about ESP-Hosted is visible in the repository root. The top level contains a `.gitlab-ci.yml`, a `.gitlab/` directory, a `LICENSES/` directory, the README and a `docs/` folder. There is no `src/`, no firmware tree and no host driver code.

That is because the work has been split. The README states that active development is currently taking place in two other repositories: `esp-hosted-linux` for the standard Linux solution and `esp-hosted-mcu` for the custom solution covering MCU and Linux hosts, each with its own issue tracker. What remains here is the shared description, the architecture documentation and the decision material.

For an engineer, that changes what to read. The two solution repositories are where you clone, where you file bugs and where you follow releases. This repository is where you decide which one you want, and the decision material is genuinely good.

The legacy table explains how the split happened. ESP-Hosted-NG was migrated to `esp-hosted-linux` and ESP-Hosted-FG to `esp-hosted-mcu`, and both legacy implementations now live under a `legacy/fg-ng` branch in this repository. The release tags follow the same pattern, with names like `release/ng-1.0.6` and `release/fg-1.0.0.0.0`, so the tag namespace tells you which generation a build belongs to.

The problem is a board with no radio and no vendor driver

ESP-Hosted is described as an open source connectivity solution that leverages Espressif SoCs as dedicated wireless co-processors for Linux systems and microcontrollers. The value proposition is that the radio protocol handling moves onto the co-processor, while the host gets full Wi-Fi, Bluetooth, BLE and Thread capabilities over standard peripheral buses.

The buses are SDIO, SPI, SPI-HD and UART, and combinations of them. That list matters more than it first appears, because it determines whether the project is usable in your situation. A board with an SDIO slot and a 3.3 volt rail can host a co-processor module; a board with only two spare GPIO pins is in SPI or UART territory, where throughput is lower and the bus has to be kept out of the way of timing sensitive work.

The security story is deliberately boring, which is a virtue here. The listed Wi-Fi security modes are Open, WPA, WPA2 and WPA3, meaning the co-processor speaks the same protocols the host would have spoken with its own radio. Classic Bluetooth, BLE and BTDM are supported across Bluetooth versions 4.2 to 6.0.

Two features are worth calling out because they change the shape of a product. Shared networking lets the ESP and the host use the same IP address, which avoids a second interface and a routing problem. And the low power modes exist for battery powered use cases, and in the MCU solution the ESP maintains connectivity while the host sleeps, so a system can wake up with the network already up.

The code is open on both sides of the link, the co-processor firmware and the host side, which is unusual for a wireless coprocessor and removes the usual question of what the vendor binary is doing on the bus.

FullMAC makes the ESP look like a native Linux radio

The `esp-hosted-linux` repository is the FullMAC solution, and its design goal is that nothing on the host has to know the radio is not really there.

On a Linux host, the application reaches `wpa_supplicant` through `cfg80211` on the control path, and the TCP/IP stack handles the data path. Below both sit the ESP-Hosted host driver and the bus driver, and below them the co-processor running the Wi-Fi and Bluetooth stacks. The 802.11 MAC itself runs on the ESP co-processor, which is what makes the arrangement FullMAC rather than a soft-MAC split.

The consequences for you are concrete. You get a native Wi-Fi interface named `wlan0`, and `cfg80211` integration means `wpa_supplicant` and NetworkManager work as they always did, so existing scripts and configuration keep working. The README lists the advertised properties as a single step solution, seamless out-of-the-box connectivity, a native `wlan0` interface, Linux `cfg80211` integration, `wpa_supplicant` and NetworkManager support, Bluetooth using HCI, and the 802.11 MAC running on the co-processor.

That last point is the trade-off. Putting the MAC on the ESP means the ESP is in the path of every frame, over a bus that is slower than the memory bus the real MAC would use. For a device doing ordinary networking that is a fine trade, and the benefit is that Linux treats the radio as radio hardware, which removes an enormous amount of work.

The use case table points this solution at standard Linux Wi-Fi configuration with NetworkManager or `wpa_supplicant`, at wanting a native wireless interface so existing tooling and scripts keep working, and at embedded Linux boards such as Raspberry Pi and BeagleBone.

The RPC solution moves Wi-Fi control into your application

The `esp-hosted-mcu` repository is the other path, and it is a different architecture rather than a variation on the first.

Instead of exposing a native Wi-Fi interface, the host talks to the co-processor over portable protobuf based RPC requests, with the application controlling everything. The design intent is that ESP-IDF APIs remain fully compatible, so `esp_wifi_*()` calls and the event handlers work on the host, and co-processor events arrive through `esp_event` transparently. On the data path there is an 802.3 Ethernet interface rather than a `wlan0`.

The framing is useful because it makes the cost explicit. The FullMAC path costs you bus bandwidth on every frame. The RPC path costs you a round trip on every control operation, and it puts the state machine in your application rather than in a driver. In exchange you get full control, a single co-processor firmware that serves both MCU and Linux hosts, and the same host application working on an MPU or an MCU.

Custom frames can be sent between host and co-processor, which is the escape hatch for anything the RPC layer does not cover.

The use case table sends this path to Linux with custom or proprietary control over Wi-Fi, to ESP-IDF application code that should run unchanged on the host, and to Wi-Fi in AP plus station mode on Linux. Bluetooth using HCI is present in both, and 802.15.4 support for Thread and Zigbee is listed for the MCU solution.

The repository also points at a detailed comparison document under `docs/`, and the decision tables cover embedded Linux boards where either works, Wi-Fi and Bluetooth together, classic Bluetooth, and connectivity kept up while the host sleeps.

Licence structure and the maintenance picture

The repository carries a `LICENSES/` directory rather than a single licence file at the root, a layout that lets each file carry its own licence terms. GitHub could not classify the licence from the repository metadata, so the authoritative terms are in that directory.

For a project whose code is split across three repositories, that arrangement is the right one, since the co-processor firmware, the host driver and the documentation can carry different terms. Anyone integrating it should check the licence in the repository they actually clone rather than relying on a badge.

The maintenance picture needs reading carefully, and it is where the split shows. The last push to this repository was on 2026-09-09 and it is not archived, so the documentation is still being worked on. The release tags here belong to the legacy implementations: ESP-Hosted-NG release 1.0.6 from 2026-04-13, ESP-Hosted-NG 1.0.4.0.0 from 2025-12-04 and ESP-Hosted-FG 1.0.0.0.0 from 2025-05-27. Current releases for the active solutions ship from the `esp-hosted-linux` and `esp-hosted-mcu` repositories, not from here.

That means a reader who checks the release list of this repository to decide whether the project is maintained will draw the wrong conclusion, and a reader who pins a version from these tags will pin a legacy build. The check that matters is in the two solution repositories.

The contributing guidance is specific about process. Contributions of bug reports, fixes, new features and documentation are welcome, every change goes through review, and for anything substantial the guidance is to open an issue first so the approach can be agreed before the code is written.

Editorial conclusion

Adopt ESP-Hosted if you need Wi-Fi, Bluetooth or Thread on a Linux board or microcontroller that lacks a radio, and you are willing to run a separate Espressif firmware on a co-processor. Do not adopt it if you need the host to own the Wi-Fi stack in a way the FullMAC path does not allow, because the MCU solution moves control into your application over RPC instead. Verify first which of the two solutions matches your host, since the Linux and MCU repositories have moved separately, that the bus you plan to use is one of the supported combinations, and that the current release tag for the branch you take corresponds to the firmware and host driver you are pairing.

Frequently asked questions

Official sources

1. espressif/esp-hosted on GitHub
2. Issues
3. README
4. Releases