ESP-HOSTED-Linux

August 26, 2026 · View on GitHub

1. Introduction

This is a Next-Generation ESP-Hosted specifically designed for a sophisticated hosts that run Linux operating system. This flavour of the solution takes more standard approach while providing a network interface to the host. User space applications such as hostapd, wpa_supplicant, iw etc, can be used with this interface.

This solution offers following:

  • 802.11 network interface which is a standard Wi-Fi interface on Linux host
  • Configuration of Wi-Fi is supported through standard cfg80211 interface of Linux
  • A standard HCI interface

Tip

Migrating from legacy esp_hosted (esp_hosted_ng/)? Please refer to our Migration Guide and helper tool tools/migrate_from_esp_hosted.py to check commit mappings or port your existing commits and uncommitted changes.

1.1 Connectivity Features

This solution provides following WLAN and BT/BLE features to the host:

  • WLAN Features:
    • 802.11b/g/n
    • WLAN Station
    • Security Modes: Open, WPA, WPA2, WPA3
  • BT/BLE
    • Classic Bluetooth
    • BLE 4.2
    • BLE 5.0

1.2 Supported ESP boards

ESP-HOSTED-Linux solution is supported on following ESP boards:

Supported TargetsESP32ESP32-S2ESP32-S3ESP32-C2ESP32-C3ESP32-C5ESP32-C6/C61

:warning: Note: Looking for other chipset? Please do check Coming Soon section.

1.3 Supported Hosts

  • ESP-HOSTED-Linux solution showcases examples for the following Linux based hosts out of the box:
    • Raspberry-Pi 3 Model B
    • Raspberry-Pi 3 Model B+
    • Raspberry-Pi 4 Model B
  • This solution is aimed for Linux based hosts only.
  • Although we try to help in porting, We expect users to get the transport interfaces like SDIO/SPI/UART configured on your Linux platform. Device tree configuration and device drivers could be some times tricky as every Linux platform has it different.
  • It is relatively easy to port this solution to other Linux based platforms. Please refer Porting Guide for the common steps.

1.4 Supported Transports

  • SDIO Only
    • Wi-Fi and Bluetooth, traffic for both runs over SDIO
  • SDIO+UART
    • Wi-Fi runs over SDIO and Bluetooth runs over UART
  • SPI Only
    • Wi-Fi and Bluetooth, traffic for both runs over SPI
  • SPI+UART
    • Wi-Fi runs over SPI and Bluetooth runs over UART

1.5 Feature Matrix

The below table explains which feature is supported on which transport interface for Linux based host.

ESP device Transport Interface Wi-Fi support Bluetooth support
ESP32 SDIO ✓ ✓
SPI ✓ ✓
UART ✕ ✓
SDIO(WiFi) + UART(BT) ✓ ✓
SPI(WiFi) + UART(BT) ✓ ✓
ESP32-S2
SPI ✓ ✕
ESP32-S3 SPI ✓ ✓
UART ✕ ✓
SPI(WiFi) + UART(BT) ✓ ✓
ESP32-C2 SPI ✓ ✓
UART ✕ ✓
SPI(WiFi) + UART(BT) ✓ ✓
ESP32-C3 SPI ✓ ✓
UART ✕ ✓
SPI(WiFi) + UART(BT) ✓ ✓
ESP32-C6 SDIO ✓ ✓
SPI ✓ ✓
UART ✕ ✓
SDIO(WiFi) + UART(BT) ✓ ✓
SPI(WiFi) + UART(BT) ✓ ✓
ESP32-C5 SPI ✓ ✓
UART ✕ ✓
SPI(WiFi) + UART(BT) ✓ ✓
SDIO ✓ ✓
SDIO(WiFi) + UART(BT) ✓ ✓
ESP32-C61 SPI ✓ ✓
SDIO ✓ ✓

Apart from these features, following features are supported.

  • Host sleep
    • We have tested this feature with imx8mm-lpddr4-evk. Please refer host_sleep documentation.

2. Hardware and Software setup and OTA

This section describes how to set up and use ESP-HOSTED-Linux solution. Please check Hardware and Software setup and OTA.

3. Get Started

3.1 User Guide

This section explains how to setup and use Wi-Fi and BT/BLE. This section assumes the network interface name as wlan0, if wlanX is already available in host, next available number will be assigned.

3.1.1 Wi-Fi

User space tool such as hostapd/wpa_supplicant/iw is used to setup Wi-Fi.

wlan0 interface can be used either as Station(sta) or Access Point(AP).

wlan0 can't function as both an AP (Access Point) and a Station at the same time, and there are no current plans to add that capability

Station

Following operations for station are supported as of now:

  • Scanning
  • Connect to AP
  • Disconnect from AP

Scanning

  • To scan nearby APs available, please use

    $ sudo iw dev wlan0 scan

Connect to AP

Open below fold to connect from three possible ways

Open

Open mode connect

Please configure AP in open mode and note the SSID

Create config & Trigger connection

  • wpa_supplicant already running on host operating system can interfere in testing. Execute following commands to prevent this.
$ sudo killall wpa_supplicant
  • Create wpa supplicant config using template below
$ cat ~/open.conf
network={
    ssid="MY_OPEN_SSID"
    key_mgmt=NONE
}

:warning: Do not copy paste this config. Please replace MY_OPEN_SSID with AP's SSID

  • Start the wpa supplicant for connection
$ sudo wpa_supplicant -D nl80211 -i wlan0 -c ~/open.conf

Verify connection

  • Verify the connection status using following command and verify ESSID:<ssid> in output
$ iwconfig wlan0
wlan0     IEEE 802.11  ESSID:"MY_OPEN_SSID"
          Mode:Managed  Frequency:2.437 GHz  Access Point: 00:0A:F5:14:33:5C
          Retry short limit:7   RTS thr:off   Fragment thr:off
          Power Management:on

Assign IP address

  • Use dhclient command to get IP. Please note, dhclient command may not be available on all Linux. Use DHCP client command supported on your Linux.
$ sudo dhclient -v wlan0
Internet Systems Consortium DHCP Client 4.4.1
Copyright 2004-2018 Internet Systems Consortium.
All rights reserved.
For info, please visit https://www.isc.org/software/dhcp/
Listening on LPF/wlan0/24:6f:28:80:2c:34
Sending on   LPF/wlan0/24:6f:28:80:2c:34
Sending on   Socket/fallback
.
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 7
DHCPOFFER of 192.168.43.32 from 192.168.43.1
DHCPREQUEST for 192.168.43.32 on wlan0 to 255.255.255.255 port 67
DHCPACK of 192.168.43.32 from 192.168.43.1
bound to 192.168.43.32 -- renewal in 1482 seconds.

Ping

$ ping <ip address of AP>

WPA/WPA2

WPA/WPA2 mode connect

Configure and start the AP in WPA or WPA2 or WPA/WPA2 mode. WPA2 is preferred among these. Note the SSID & Password to connect.

Create config & Trigger connection

  • wpa_supplicant already running on host operating system can interfere in testing. Execute following commands to prevent this.
$ sudo killall wpa_supplicant
  • Generate wpa_supplicant config
$ wpa_passphrase <ssid> <password>  > ~/wpa2.conf
  • Example config for WPA2
$ wpa_passphrase "MY_WPA2_SSID" "Passphrase"  > ~/wpa2.conf
$ cat ~/wpa2.conf
network={
	ssid="MY_WPA2_SSID"
	#psk="Passphrase"
	psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
}

:warning: Do not copy paste this config

  • Start the wpa supplicant for connection
$ sudo wpa_supplicant -D nl80211 -i wlan0 -c ~/wpa2.conf

Verify connection

  • Verify the connection status using following command and verify ESSID:<ssid> in output
$ iwconfig wlan0
wlan0     IEEE 802.11  ESSID:"MY_OPEN_SSID"
          Mode:Managed  Frequency:2.412 GHz  Access Point: XX:XX:XX:XX:XX:XX   
          Bit Rate=XXX Mb/s   Tx-Power=XX dBm   
          Retry short limit:X   RTS thr:off   Fragment thr:off
          Power Management:on
          Link Quality=70/70  Signal level=-20 dBm  
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:25   Missed beacon:0

Assign IP address

  • Use dhclient command to get IP. Please note, dhclient command may not be available on all Linux. Use DHCP client command supported on your Linux.
$ sudo dhclient -v wlan0
Internet Systems Consortium DHCP Client 4.4.1
Copyright 2004-2018 Internet Systems Consortium.
All rights reserved.
For info, please visit https://www.isc.org/software/dhcp/
Listening on LPF/wlan0/24:6f:28:80:2c:34
Sending on   LPF/wlan0/24:6f:28:80:2c:34
Sending on   Socket/fallback
.
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 7
DHCPOFFER of 192.168.43.32 from 192.168.43.1
DHCPREQUEST for 192.168.43.32 on wlan0 to 255.255.255.255 port 67
DHCPACK of 192.168.43.32 from 192.168.43.1
bound to 192.168.43.32 -- renewal in 1482 seconds.

Ping

$ ping <ip address of AP>

WPA3

WPA3 mode connect

Configure and start the AP in WPA3 mode. Note the SSID & Password to connect.

Create config & Trigger connection

  • wpa_supplicant already running on host operating system can interfere in testing. Execute following commands to prevent this.
$ sudo killall wpa_supplicant
  • Generate wpa_supplicant config using below template
$ cat ~/wpa3.conf
update_config=1
network={
    ssid="MY_WPA3_SSID"
    sae_password="MY_WPA3_Passphrase"
    key_mgmt=SAE
    ieee80211w=2
}

  • Change MY_WPA3_SSID to AP's SSID and MY_WPA3_Passphrase to Passphrase to connect

  • Start the wpa supplicant for connection

$ sudo wpa_supplicant -D nl80211 -i wlan0 -c ~/wpa3.conf

Verify connection

  • Verify the connection status using following command and verify ESSID:<ssid> in output
$ iwconfig wlan0
  wlan0     IEEE 802.11  ESSID:"MY_WPA3_SSID"
            Mode:Managed  Frequency:2.412 GHz  Access Point: C4:41:1E:BE:F0:B2
            Retry short limit:7   RTS thr:off   Fragment thr:off
            Power Management:on

Assign IP address

  • Use dhclient command to get IP. Please note, dhclient command may not be available on all Linux. Use DHCP client command supported on your Linux.
$ sudo dhclient -v wlan0
Internet Systems Consortium DHCP Client 4.4.1
Copyright 2004-2018 Internet Systems Consortium.
All rights reserved.
For info, please visit https://www.isc.org/software/dhcp/
Listening on LPF/wlan0/24:6f:28:80:2c:34
Sending on   LPF/wlan0/24:6f:28:80:2c:34
Sending on   Socket/fallback
.
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 7
DHCPOFFER of 192.168.43.32 from 192.168.43.1
DHCPREQUEST for 192.168.43.32 on wlan0 to 255.255.255.255 port 67
DHCPACK of 192.168.43.32 from 192.168.43.1
bound to 192.168.43.32 -- renewal in 1482 seconds.

Ping

$ ping <ip address of AP>

WPA2/WPA3 Enterprise

WPA2/WPA3 Enterprise mode connect

Note the SSID, username, and password of the WPA2/WPA3 enterprise AP to connect.

The ESP-HOSTED-Linux solution supports both WPA2 Enterprise and WPA3 Enterprise authentication modes through EAP (Extensible Authentication Protocol) when operating in Station mode.

Create config & Trigger connection

  • wpa_supplicant already running on host operating system can interfere in testing. Execute following commands to prevent this.
$ sudo killall wpa_supplicant
  • Generate wpa_supplicant config using below template for PEAP/MSCHAPv2
$ cat ~/wpa2_ent.conf
ctrl_interface=/var/run/wpa_supplicant
ap_scan=0
network={
    ssid="MY_ENTERPRISE_SSID"
    key_mgmt=WPA-EAP
    eap=PEAP
    identity="user@domain.com"
    password="user_password"
    ca_cert="/path/to/ca-cert.pem"
    phase2="auth=MSCHAPV2"
}
  • Alternative template for EAP-TLS
$ cat ~/wpa2_tls.conf
ctrl_interface=/var/run/wpa_supplicant
ap_scan=0
network={
    ssid="MY_ENTERPRISE_SSID"
    key_mgmt=WPA-EAP
    eap=TLS
    identity="user@domain.com"
    client_cert="/path/to/client-cert.pem"
    private_key="/path/to/private-key.pem"
    ca_cert="/path/to/ca-cert.pem"
}

  • Change MY_ENTERPRISE_SSID to AP's SSID, user@domain.com to your username, and user_password to your password

  • Update certificate paths to match your enterprise environment

  • Start the wpa supplicant for connection

$ sudo wpa_supplicant -D nl80211 -i wlan0 -c ~/wpa2_ent.conf

Verify connection

  • Verify the connection status using following command and verify ESSID:<ssid> in output
$ iwconfig wlan0
  wlan0     IEEE 802.11  ESSID:"MY_ENTERPRISE_SSID"
            Mode:Managed  Frequency:2.412 GHz  Access Point: C4:41:1E:BE:F0:B2
            Retry short limit:7   RTS thr:off   Fragment thr:off
            Power Management:on

Assign IP address

  • Use dhclient command to get IP. Please note, dhclient command may not be available on all Linux. Use DHCP client command supported on your Linux.
$ sudo dhclient -v wlan0
Internet Systems Consortium DHCP Client 4.4.1
Copyright 2004-2018 Internet Systems Consortium.
All rights reserved.
For info, please visit https://www.isc.org/software/dhcp/
Listening on LPF/wlan0/24:6f:28:80:2c:34
Sending on   LPF/wlan0/24:6f:28:80:2c:34
Sending on   Socket/fallback
.
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 7
DHCPOFFER of 192.168.43.32 from 192.168.43.1
DHCPREQUEST for 192.168.43.32 on wlan0 to 255.255.255.255 port 67
DHCPACK of 192.168.43.32 from 192.168.43.1
bound to 192.168.43.32 -- renewal in 1482 seconds.

Ping

$ ping <ip address of AP>

Disconnect from AP

  • Execute following command to disconnect from AP

    $ sudo iw dev wlan0 disconnect

  • Verify status using

    $ iwconfig wlan0
Access Point

Following operations for softAP are supported as of now:

hostapd (Host Access Point Daemon) is a user-space daemon that enables a Linux-based machine to act as a wireless access point. When combined with dnsmasq, a lightweight DHCP and DNS server, it provides a complete solution for managing Wi-Fi networks, including IP address assignment and name resolution.

make sure you have enabled ap_support with rpi_init.sh to user interface as Access point. Read Hardware and Software Setup and OTA

Supported Operations

  • Configuring the AP with hostapd
  • Managing connections (connect/disconnect)
  • Setting up DHCP and DNS with dnsmasq
Configuring AP with hostapd
  • Create a Configuration File for hostapd
$ nano ~/hostapd.conf
  • Here’s a sample configuration:
interface=wlan0
driver=nl80211
ssid=MY_SSID
hw_mode=g
channel=6
wmm_enabled=0
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_key_mgmt=WPA-PSK SAE
wpa_passphrase=MY_PASSPHRASE
rsn_pairwise=CCMP
sae_pwe=2
ieee80211w=2

Sample Configuration for AP on 5GHZ channel (ESP32C5)

interface=wlan0
driver=nl80211
ssid=MY_SSID
hw_mode=a
channel=36
wmm_enabled=0
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_key_mgmt=WPA-PSK SAE
wpa_passphrase=MY_PASSPHRASE
rsn_pairwise=CCMP
sae_pwe=2
ieee80211w=2

Change MY_SSID to AP's SSID and MY_PASSPHRASE to Passphrase to connect Security can configured by keeping the values of wpa_key_mgmt to SAE/WPA-PSK.

Start hostapd

To start the access point, run:

    $ sudo hostapd ~/hostapd.conf
Setting up DHCP and DNS

To set up DHCP and DNS with dnsmasq, follow these steps:

  • Installation

If dnsmasq is not already installed, you can install it using:

$ sudo apt-get install dnsmasq
  • Configuration

Create a Configuration File for dnsmasq Edit or create the dnsmasq configuration file:

$ sudo nano /etc/dnsmasq.conf

Sample configuration:

interface=wlan0          # Use the wireless interface
dhcp-range=192.168.1.2,192.168.1.100,255.255.255.0,24h  # DHCP range
domain-needed             # Don't forward short names
bogus-priv                # Never forward addresses in the non-routed address spaces
expand-hosts              # Use the expanded hostname

Adjust the dhcp-range to fit your network needs.

Restart dnsmasq

After saving the configuration, restart the dnsmasq service:

    $ sudo systemctl restart dnsmasq
Assign an IP Address

With dnsmasq running, clients will automatically receive an IP address when they connect.

Test Connectivity

Test the connection to ensure it is working:

    $ ping <ip address of station>

This documentation provides a comprehensive guide for setting up hostapd and dnsmasq to create a wireless access point with DHCP and DNS capabilities. Adjust configurations as necessary for your network environment.

3.1.2 Bluetooth/BLE

Following operations for station are supported as of now:

4. Design

4.1 System Architecture

This section explains building blocks of the solution. Following is the detailed system architecture diagram:

ESP-Hosted-cfg80211 design

Following are the key building blocks of the system:

  • ESP-HOSTED-Linux Driver

  • ESP-HOSTED-Linux Firmware

  • Third party components

4.1.1 ESP-HOSTED-Linux Driver

This runs on host platform and it implements following.

  • Transport driver
    • Implements transport layer over SDIO/SPI interface.
      Communication protocol is explained in further section.
  • Network Interface
    • Registers Wi-Fi interface wlan0 with Linux kernel.
      • This allows exchange of network data packets between Linux kernel and ESP firmware.
    • Implements needed cfg80211_ops to support configuration through wpa_supplicant or iw utility
  • HCI Interface
    • Applicable only when SDIO/SPI interface is being used for Bluetooth/BLE support
    • Registers HCI interface with the Bluetooth stack running on Linux host
      • This facilitates exchange of HCI packets between Linux kernel and ESP firmware

4.1.2 ESP-HOSTED-Linux Firmware

This implements ESP application that runs on ESP boards. It consists of the following.

  • ESP-HOSTED-Linux Application
    This implements following:
    • SDIO/SPI transport layer
    • Custom command/response implementation for configuration of Wi-Fi interface
    • Data path between Wi-Fi driver of ESP and Host platform
  • ESP-IDF Components
    ESP firmware mainly uses following components from ESP-IDF. Please check ESP-IDF documentation for more details.
    • SDIO/SPI/UART slave driver
    • Wi-Fi driver
    • HCI controller driver

4.1.3 Third Party Components

Third components such as following are essential for end to end working of this solution. Implementation or porting of these third party component is not in scope of this project.

  • TCP/IP stack
  • Bluetooth/BLE stack
  • nl80211/cfg80211 kernel module
  • User space applications
  • Linux UART driver

4.2 Transport Layer Protocol

This section explains transport layer protocol used for communication over SDIO/SPI bus. Please refer following to know more:

4.2.1 Payload Format

This section explains the header that encapsulates the data packets exchanged over SDIO and SPI interfaces.

  • Host and peripheral makes use of 12 byte payload header which precedes every data packet.
  • This payload header provides additional meta data about the packet. Based on this header, host/peripheral consumes the transmitted data packet.
  • Payload format is as below
FieldLengthDescription
Interface type4 bitsPossible values: STA(0), SoftAP(1), HCI (2), Priv interface(3). Rest all values are reserved
Interface number4 bitsUnused
Flags1 byteAdditional flags like MORE_FRAGMENT in fragmentation
Packet type1 byteType of packet Data(0), Command_req(1), Command_resp(2), Event(3), EAPOL_frame(4)
Reserved11 byteNot in use
Packet length2 bytesActual length of data packet
Offset to packet2 bytesOffset to the start of the data payload
Checksum2 bytesUnused as if now
Reserved21 byteNot in use

4.3 Porting Guide

Refer Porting Guide which explains how one can port the solution to other Linux host platforms.

5. Throughput Performance

Refer RAW throughput guide for verifying connection as well as throughput between host and ESP.

ESP deviceTransport InterfaceTCP TxTCP RxUDP TxUDP Rx
ESP32 SDIO 2.4 GHz (40MHz) 43.5 Mbps 24.8 Mbps 47.6 Mbps 49.1 Mbps
SDIO 2.4 GHz (20MHz) 32.4 Mbps 28.3 Mbps 36.1 Mbps 41.7 Mbps
SPI 7.47 Mbps 7.30 Mbps 7.39 Mbps 7.32 Mbps
ESP32-C3 SPI 15.8 Mbps 15.2 Mbps 17.1 Mbps 14.9 Mbps
ESP32-C5 SDIO 2.4 GHz (11n 40MHz) 62.3 Mbps 60.3 Mbps 97.2 Mbps 81.7 Mbps
SDIO 2.4 GHz (11ax 20MHz) 52.7 Mbps 42.4 Mbps 66.2 Mbps 49.4 Mbps
SDIO 5 GHz (11n 40MHz) 63.3 Mbps 52.5 Mbps 97.8 Mbps 81.3 Mbps
SDIO 5 GHz (11ax 20MHz) 54.8 Mbps 47.6 Mbps 68 Mbps 65 Mbps
ESP32-C6 SDIO 2.4 GHz (40MHz) 41.7 Mbps 51 Mbps 90.4 Mbps 58.4 Mbps
SDIO 2.4 GHz (20MHz) 40.9 Mbps 55.6 Mbps 67.8 Mbps 68.3 Mbps
SPI 16.2 Mbps 16.9 Mbps 17.5 Mbps 17.2 Mbps
ESP32-C61 SDIO 2.4 GHz (40MHz) 42.3 Mbps 41.5 Mbps 57.2 Mbps 45.3 Mbps
SDIO 2.4 GHz (20MHz) 42.6 Mbps 40.7 Mbps 64 Mbps 44.6 Mbps
SPI 13.3 Mbps 13.6 Mbps 13.9 Mbps 14 Mbps

Note

  • Host Platforms Used:
    • ESP32-C5: Tested on Raspberry Pi 5 with SDIO clock frequency set to 50 MHz.
    • Other Chipsets (ESP32, ESP32-C3, ESP32-C6, ESP32-C61): Tested on Raspberry Pi 4B with SDIO clock frequency set to 41.67 MHz.

6. Miscellaneous

6.1 Deassert CS for SPI

Problem: Some hosts, after completing an SPI transaction, introduce a delay before de-asserting the Chip Select (CS) line. The ESP SPI slave, seeing that the CS is still asserted, might start the next transaction prematurely, leading to data loss or corruption because the host is not ready.

Solution: To address this, the ESP firmware provides a Kconfig option, ESP_SPI_DEASSERT_HS_ON_CS. When this option is enabled, the firmware changes its behavior. Instead of de-asserting the Handshake (HS) signal at the end of a transaction, it waits for the CS line to be de-asserted by the host. This ensures that a new transaction doesn't start until the host has properly finished the previous one.

How to Enable:

You can enable this option using the idf.py menuconfig tool within the esp-hosted-linux project.

  1. Navigate to the ESP firmware directory:

    cd esp/esp_driver/network_adapter

  2. Launch the configuration menu:

    idf.py menuconfig

  3. In the menu, navigate to the following path: Example Configuration -> SPI Configuration

  4. Inside the SPI Configuration menu, you will find the option De-assert HS on CS.

  5. Select this option to enable it (set it to true).

  6. Save the configuration and exit menuconfig.

  7. Rebuild the firmware for the changes to take effect.

This option is defined in the Kconfig file located at main/Kconfig.projbuild within the network_adapter directory.

7. Coming soon

Tremendous work to be done ahead! Below is glimpse of upcoming release:

  • Functionality
    • Wifi Enterprise support

8. Want to support?

That's right. Being open source, we really appreciate the pull requests. Already raised pull request? Please be patient. We will review and merge your commit into the master.