To use an ESP32 as a Raspberry Pi Wi-Fi co-processor, connect a supported ESP radio over a compatible bus, flash ESP-Hosted-Linux firmware, and load the matching Linux driver. Linux then gets a wlanX wireless interface and handles the network connection. This guide is for makers integrating a radio into a Linux single-board computer—not for applications that simply exchange messages between two devices already connected to Wi-Fi.
The work spans three layers: hardware, ESP firmware, and the Linux host. Get those aligned first; the Wi-Fi password comes later.
What ESP-Hosted-Linux does
ESP-Hosted-Linux, maintained by Espressif, lets Linux use a connected ESP as its wireless radio. The host retains the Linux wireless stack, including cfg80211 and nl80211, the kernel and userspace interfaces that standard Wi-Fi tools use.
That arrangement changes where you configure the connection. You select the access point and configure IP networking on Linux, rather than putting the network name and password into an ESP32 application sketch. Espressif supports both station operation—joining an access point—and access-point operation through normal Linux tools. This walkthrough focuses on joining an existing network.
There are two other arrangements worth separating before you reach for jumper wires:
- Ordinary application networking: Raspberry Pi and the ESP each use their own network interface. Their applications communicate over the network; the ESP is not Raspberry Pi’s radio.
- ESP-Hosted-MCU: More Wi-Fi connection management stays on the ESP, which acts as a more self-contained networking microcontroller.
Choose ESP-Hosted-Linux when you want the wireless interface managed by the Linux host itself.
Choose an ESP32 target and transport
Start with the exact chip identifier. “ESP32” names a family, and its members do not all support the same host connection.
A transport is the bus carrying traffic between Linux and the ESP. SDIO is a Secure Digital input/output bus; SPI is a Serial Peripheral Interface bus. ESP-Hosted-Linux also supports USB on ESP32-S31.
Espressif’s supported-hardware matrix lists these combinations:
| ESP target | Host transport | Wi-Fi band | Wi-Fi standards |
| ESP32 | SDIO, SPI | 2.4 GHz | 802.11b/g/n |
| ESP32-S2 | SPI | 2.4 GHz | 802.11b/g/n |
| ESP32-S3 | SPI | 2.4 GHz | 802.11b/g/n |
| ESP32-S31 | SPI, USB | 2.4 GHz | 802.11b/g/n |
| ESP32-C2 | SPI | 2.4 GHz | 802.11b/g/n |
| ESP32-C3 | SPI | 2.4 GHz | 802.11b/g/n |
| ESP32-C5 | SDIO, SPI | 2.4 GHz and 5 GHz | 802.11a/b/g/n/ac/ax |
| ESP32-C6 | SDIO, SPI | 2.4 GHz | 802.11b/g/n/ax |
| ESP32-C61 | SDIO, SPI | 2.4 GHz | 802.11b/g/n/ax |
If your connection needs 5 GHz, ESP32-C5 supplies that option. ESP32-C6 supports 2.4 GHz and gives you a choice of SDIO or SPI. For a USB connection, Espressif lists ESP32-S31; its Raspberry Pi USB setup requires neither GPIO wiring nor a Device Tree overlay.
Chip support is one prerequisite. Your Linux board also needs a usable controller for the chosen bus, the appropriate pin configuration, and kernel integration. Check the host board as well as the ESP target. A compatible kernel version alone does not establish that a particular board’s bus is ready.
What you need before starting
Have these pieces ready:
- A supported ESP board and a Linux host with a usable matching bus.
- Wiring appropriate to that transport, a stable power supply, and a shared ground for the wired SDIO or SPI arrangement.
- ESP-IDF, Espressif’s development framework, for building and flashing the ESP firmware.
- A Linux build environment for the corresponding host module.
- Linux networking tools and access to the ESP’s serial logs for troubleshooting.
Use Espressif’s Raspberry Pi reference for board-specific setup rather than applying a generic bus configuration blindly.
Wire ESP32-C6 SDIO to Raspberry Pi
For an ESP32-C6 connected over SDIO, Espressif supplies the following mapping between Raspberry Pi’s 40-pin header and the ESP’s default GPIO assignments. The Raspberry Pi column uses physical header pin numbers, not GPIO numbers.
| Signal | Raspberry Pi physical header pin | ESP32-C6 default connection |
| DAT3 | 13 | GPIO 23 |
| CLK | 15 | GPIO 19 |
| CMD | 16 | GPIO 18 |
| DAT0 | 18 | GPIO 20 |
| DAT1 | 22 | GPIO 21 |
| DAT2 | 37 | GPIO 22 |
| ESP reset | 31 | RST |
| Ground | 39 | Ground |
The hardware setup guide requires pull-up resistors on CMD and DAT0–DAT3. These resistors hold the signals high when they are not being driven. Espressif’s wiring diagram uses external 10 kΩ pull-ups, with a caution against duplicating resistors already fitted to the selected board.
Keep connections short, provide a solid ground return, and use a stable supply. SDIO and SPI signals use 3.3 V logic; do not apply 5 V to those signal lines. Check your particular development board’s power-input requirements separately from its logic voltage.
Wiring is only half of bus preparation. Raspberry Pi must also expose and configure the host controller and its pins. If SDIO transfers are unstable, Espressif recommends reducing the SDIO clock, alongside checking the electrical setup.
Choosing SPI instead? Its wiring also needs the Handshake and Data Ready signals, plus reset. Use the SPI-specific instructions; the SDIO table is not interchangeable with them.
Build the firmware and Linux driver
Once you have chosen a compatible target and transport, follow the sequence in Espressif’s quick start. The ESP firmware and Linux module must describe the same connection.
- Configure the ESP firmware. Select the exact ESP target and transport in the ESP-IDF workflow. This determines which chip and host connection the firmware will use.
- Build the ESP firmware. Compile the configuration selected in the previous step to produce the firmware for that target.
- Flash the ESP firmware. Write the resulting firmware to the ESP so it can operate as the host-connected radio.
- Prepare the Linux host bus. Apply the configuration appropriate to the board and transport, including the required controller, pin control, and Device Tree integration where applicable.
- Build the matching Linux host module. Select the
sdio,spi, orusbmodule for your connection. The driver is the Linux-side component that communicates with the ESP firmware. - Load the host module. Loading the driver brings the host-side connection into operation and allows Linux to expose the wireless interface.
Keep the board-specific configuration close at hand during these steps. A correct firmware image cannot compensate for an unconfigured host bus, and a correctly wired bus still needs its matching driver.
Configure Wi-Fi in Linux
With the firmware running and driver loaded, move to Linux’s network tools. Espressif’s station guide places both Wi-Fi association and IP configuration on the host.
- Find the wireless interface with
iw dev. Use the actual interface name shown by Linux; it may not bewlan0. - Inspect the interface with
ip link. This checks that the network device is present and lets you examine its link state. - Associate with your access point. Configure the ESP-backed interface through your Linux network manager or
wpa_supplicant, the service that handles Wi-Fi authentication and association. - Obtain an IP address. Use the normal Linux network manager or DHCP client. DHCP is the mechanism that obtains network configuration automatically from the local network.
Verify success and locate failures
Check the connection in layers. First, iw dev should identify the wireless interface. Then confirm association through your networking tool. Finally, check that Linux has obtained the intended IP configuration. An interface appearing is an important milestone, but it is not the same milestone as joining the access point.
If the interface fails to appear, inspect dmesg, Linux’s kernel log, and the ESP serial logs. Recheck the selected transport, host configuration, reset connection, power, and wiring before changing Wi-Fi credentials.
Common mistakes are using Raspberry Pi GPIO numbering in place of physical header numbering, assuming an ESP32-S3 supports the ESP32-C6 SDIO arrangement, omitting required pull-ups, and configuring a different transport on each side. Another easy trap: sending every networking command to wlan0 when Linux assigned a different name.
ESP32-C6 SDIO performance and recovery behavior
Espressif reports the following reference throughput measurements for ESP32-C6 over SDIO on 2.4 GHz Wi-Fi. Tx and Rx denote transmission and reception in the project’s measurement labels. The channel-width column describes the Wi-Fi radio channel, not the SDIO bus clock.
| Wi-Fi channel width | TCP Tx (Mbps) | TCP Rx (Mbps) | UDP Tx (Mbps) | UDP Rx (Mbps) |
| 20 MHz | 40.9 | 55.6 | 67.8 | 68.3 |
| 40 MHz | 41.7 | 51.0 | 90.4 | 58.4 |
TCP provides reliable, ordered delivery; UDP sends datagrams without TCP’s delivery and ordering guarantees. Those protocols produce separate throughput results, as do transmission direction and radio configuration.
The highest TCP result here is 55.6 Mbps, in the 20 MHz Rx row. The highest UDP result is 90.4 Mbps, in the 40 MHz Tx row. Espressif cautions that the reference measurements are not a standardized performance guarantee and that host details and direction methodology are incomplete across its results. Your Raspberry Pi setup should not be assigned either peak as a fixed operating speed.
In one reported ESP32-C6 build, cutting and restoring ESP power with a hardware switch caused the connection to disconnect and reconnect without a kernel-module crash or failure. That observation applies to that individual setup; it is not a general recovery guarantee.
Setup quick reference
- Hardware selection: Match the exact ESP target to a supported transport and a usable Linux host bus.
- SDIO wiring: Use physical Raspberry Pi header numbering, 3.3 V signaling, the required pull-ups, short connections, and a solid ground return.
- Firmware and driver: Select the same target and transport throughout the ESP and Linux setup.
- Interface check: Find the actual wireless interface with
iw devand inspect it withip link. - Network configuration: Associate through Linux’s network tools, then obtain the IP configuration through the host’s network manager or DHCP client.
- Bring-up diagnostics: Inspect
dmesgand ESP serial logs when the interface does not appear.
