Using an ESP32 Linux Wireless Co-processor on Raspberry Pi

For single-board computer enthusiasts and industrial hardware designers, the onboard wireless modules on the Raspberry Pi can sometimes feel like a black box. Closed-source firmware blobs, power-management quirks, and driver instability under heavy network loads have sent many developers searching for alternative wireless pathways.

Enter the Espressif ESP32. While widely known as a standalone microcontroller, the ESP32 can also function as a highly capable, low-cost Wi-Fi and Bluetooth co-processor. By running Espressif’s open-source ESP-Hosted-NG (Next Generation) firmware, you can offload wireless networking from the Raspberry Pi's CPU to an external ESP32 module connected via a high-speed Serial Peripheral Interface (SPI) bus. This setup integrates directly with the Linux kernel's mac80211 subsystem, exposing the ESP32 as a native wlan0 interface.

Designing the High-Speed SPI Physical Interconnect

Unlike USB-based wireless adapters, an SPI-based co-processor requires manual hardware wiring and precise pin mapping. Because SPI is a master-slave protocol where the Raspberry Pi (master) controls the clock line, the ESP32 (slave) cannot initiate data transfers on its own. To bypass this limitation, the ESP-Hosted architecture utilizes dedicated handshaking and reset lines.

To establish this interface, connect your ESP32 development board (such as an ESP32-WROOM-32E or ESP32-S3) to the Raspberry Pi's 40-pin GPIO header using the following physical wiring scheme:

• SPI MOSI: Pi GPIO 10 (Pin 19) to ESP32 GPIO 23
• SPI MISO: Pi GPIO 9 (Pin 21) to ESP32 GPIO 25
• SPI SCLK: Pi GPIO 11 (Pin 23) to ESP32 GPIO 19
• SPI Chip Select (CS): Pi GPIO 8 (Pin 24) to ESP32 GPIO 22
• Handshake (Data Ready): Pi GPIO 22 (Pin 15) to ESP32 GPIO 4
• Reset (EN): Pi GPIO 23 (Pin 16) to ESP32 GPIO 5
• Common Ground: Pi GND (Pin 6) to ESP32 GND
• Power Supply: Pi 3.3V (Pin 1) to ESP32 3V3 (Note: For production units, use a dedicated 3.3V regulator capable of delivering at least 500mA peak current to prevent brownouts during Wi-Fi transmission).

Keep the jumper wires as short as possible—ideally under 10 cm. High-speed SPI signals operating at 10 MHz or higher are highly susceptible to crosstalk and electromagnetic interference when routed over loose breadboard wires.

Compiling and Flashing the ESP-Hosted Firmware

Before the Raspberry Pi can talk to the ESP32, you must flash the microcontroller with the ESP-Hosted-NG slave firmware. This process requires Espressif's ESP-IDF (IoT Development Framework) toolchain installed on your development PC or directly on the Raspberry Pi.

First, clone the official repository and set up the build environment:

git clone --recursive https://github.com/espressif/esp-hosted.git
cd esp-hosted/esp_hosted_ng/esp/esp_driver

Set the target chip to match your specific hardware (in this case, the standard ESP32):

idf.py set-target esp32

Next, launch the configuration utility to define the communication interface and pin mappings:

idf.py menuconfig

Within the interactive menu, navigate to Example Configuration and apply these settings:

1. Set the Transport Layer to SPI.
2. Configure the SPI Handshake GPIO to 4.
3. Configure the SPI Data Ready GPIO to 22.
4. Save the configuration and exit.

Now, compile the firmware and flash it to your ESP32 over a USB connection:

idf.py build
idf.py -p /dev/ttyUSB0 flash

Once flashed, the ESP32 will boot and immediately enter a listening state, waiting for the Raspberry Pi to initiate the SPI handshake sequence.

Compiling the Host Kernel Module on Raspberry Pi OS

With the ESP32 ready, switch over to your Raspberry Pi. To allow the Linux kernel to recognize the ESP32 as a network interface, you must compile and load a custom kernel module designed for the mac80211 stack.

Start by updating your package repository and installing the necessary kernel headers and build tools:

sudo apt update
sudo apt install -y raspberrypi-kernel-headers build-essential git

Clone the ESP-Hosted repository directly onto the Pi and navigate to the host driver directory:

git clone https://github.com/espressif/esp-hosted.git
cd esp-hosted/esp_hosted_ng/host/linux

To register the physical SPI connection with the Pi's device tree, you need to compile a Device Tree Overlay. Create a file named esp32-spi.dts with the following configuration:

/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2835";

    fragment@0 {
        target = <&spi0>;
        __overlay__ {
            status = "okay";
            spidev@0 {
                status = "disabled";
            };
            esp32: esp32@0 {
                compatible = "espressif,esp32";
                reg = <0>;
                spi-max-frequency = <10000000>;
                handshake-gpios = <&gpio 22 1>;
                reset-gpios = <&gpio 23 1>;
            };
        };
    };
};

Compile this device tree source file into a binary overlay and move it to the system overlay directory:

dtc -I dts -O dtb -o esp32-spi.dtbo esp32-spi.dts
sudo cp esp32-spi.dtbo /boot/overlays/

Instruct the Raspberry Pi bootloader to load this overlay at startup by appending the following line to /boot/config.txt (or /boot/firmware/config.txt on Debian Bookworm):

dtoverlay=esp32-spi

Next, compile the kernel module itself using the provided Makefile:

make target=rpi

Once the build process completes successfully, load the compiled module into the running kernel:

sudo insmod esp32.ko

Initializing the Interface and Verifying Connectivity

If the hardware wiring, firmware, and kernel modules are aligned, the system log will report a successful handshake. Inspect the kernel ring buffer to confirm initialization:

dmesg | grep -i esp32

Your output should display messages indicating that the SPI device was detected, followed by the registration of a new wireless interface:

[   12.482019] esp32_spi: SPI connection established at 10 MHz
[   13.102394] esp32_wlan: Registered interface wlan1

You can now manage this interface using standard Linux networking utilities. Bring the interface online:

sudo ip link set wlan1 up

Scan for local Wi-Fi networks to verify that the ESP32 is actively listening and processing radio frequency signals:

sudo iw dev wlan1 scan | grep SSID

To connect to an access point, configure wpa_supplicant to manage the new interface by editing /etc/wpa_supplicant/wpa_supplicant-wlan1.conf with your network SSID and security key, then start the service:

sudo systemctl start wpa_supplicant@wlan1

Troubleshooting Clock Skew and Latency Bottlenecks

When running network traffic over a serial bus like SPI, you may encounter bottleneck issues or instability. Here is how to resolve the most common integration hurdles:

Frame Drops and RX Buffer Overruns

If you observe high packet loss during download tests, your SPI clock frequency may be set too low, or the host CPU is missing interrupt signals.

• Solution: Gradually increase the spi-max-frequency in your device tree overlay up to a maximum of 20000000 (20 MHz). Ensure that the handshake line is not sharing a pin with another active peripheral, as delayed interrupt handling will cause the ESP32's internal ring buffers to overflow.

Kernel Panics on Module Unload

If the host kernel crashes when running rmmod esp32, it is typically caused by active threads trying to access memory addresses that have already been deallocated by the driver.

• Solution: Always bring down the interface (sudo ip link set wlan1 down) and stop any active wpa_supplicant instances before attempting to unload the module.