
没有无线连接功能的笔记本电脑似乎很罕见——但在选购高性能 Linux 单板计算机(SBC)时,缺少 WiFi 支持的情况却相当常见。与此同时,目前的无线网卡也往往不尽如人意:专有固件、短暂存在甚至仅有二进制闭源驱动的混乱局面,从未解决的怪异故障,有时甚至是完全没有源代码、还会“过期”的二进制块。也许这块 SBC 没有空闲 USB 接口来即插即用 WiFi 芯片,又或者你不想为冷门、难以采购的半孔模块做设计。
如果我告诉你,只要 SBC 还留有一个空闲的 SDIO 或 SPI 接口,这个问题就有一个独特解决方案,你会怎么想?有一张无线网卡值得大家共同支持:它当然并非完美,但为我们提供了更大的成长空间——它的固件在一定程度上开源,来自一家可靠的公司,而且几乎可以肯定很容易采购。我说的当然是 esp-hosted——通过 SDIO 或 SPI,把 ESP32 模块当作你的 WiFi/蓝牙网卡。
我最近在项目中加入了一颗 ESP32-C6,而配置 esp-hosted 的过程并不十分顺畅——因此这里提供一份指南,并讨论 esp-hosted 为何如此出色、又为何极具前景。剧透一下:它可以与切断电源的隐私开关配合工作,可以被改造为支持网状协议的协处理器,还有望帮助我们打造一张完全开源的 SDIO WiFi 网卡。
两大部分,支持大多数芯片
有必要先作一个简短澄清:esp-hosted 旗下其实有两个项目。一个是 esp-hosted-mcu(此前名为 esp-hosted-fg,即“第一代”),它把 ESP32 更像一个连接 WiFi 的微控制器来运行,并在 Linux 端提供相对有限但自给自足的接口;你的连接层面主要由 ESP32 模块管理,因此无论主机正在重启,甚至完全关机,它都会连接到你预设的 WiFi 网络。正因如此,esp-hosted-mcu 最适合用于微控制器,或者适合你希望 ESP32 成为一个完全自主的独立实体的场景。想把 ESP32 变成一块带 WiFi 连接功能的嵌入式控制器(EC)吗?那就选择 -mcu 版本。
esp-hosted-linux(此前名为 esp-hosted-ng,即“新一代”)把无线协议栈留在 Linux 端,ESP32 则充当 Linux 无线协议栈的一个相对轻量的代理。我在这里主要讨论 esp-hosted-linux,因为它在 Linux 下的表现最接近普通 WiFi 网卡的“原生”方式,但本文的许多内容对两者都适用。
esp-hosted 需要双方配合才能工作:一台还有空闲 SDIO 或 SPI 接口的 Linux 电脑,以及受支持列表中的 ESP32 芯片/模组。我选择了 ESP32-C6。常见的 ESP32-WROOM 模组已经绰绰有余,但大多数新芯片也得到支持。具体来说,ESP32-S2、-S3、-C2、-C3、-C5 和 -C6/C61 均可配合 esp-hosted-linux 工作;如果你正在使用类似 -S31 的芯片,请查看上级项目的问题跟踪列表。我使用 C6,是因为我以为它支持的功能最多,而且它只比其他芯片略贵一点,为什么不选它呢?然而!这是一个错误。如果我要重新设计一块新板,我会选择 ESP32-C5。结果发现,尽管 C 后面的数字更小,ESP32-C5 明显优于 ESP32-C6,尤其支持 5GHz。
接下来,需要通过 SDIO 或 SPI 进行接线。如果可用,我推荐使用 SDIO,因为它快得多。有一点要注意:确保你的单板计算机(SBC)的 SDIO 接口得到操作系统支持,不要处于“硬件已就绪,只差有人把驱动搞定”这种悬而未决的状态,除非你能成为那个人。如果你已经有开发板,可以把 SD 卡临时接到你认为的 SDIO 引脚上,以验证 SDIO 接口确实可用!
SDIO 本质上是一条全双工并行总线,包含一条控制信号(CMD)、一条时钟信号(CLK)和四条数据线(D0-D3)——如果你追求极简,也可以只用一条数据线 D0。这些信号线翻转速度很快,而且不是差分对,因此布线时要认真对待,按单端信号处理。我之后会写一篇更详细的 SDIO 文章,但在此之前,可以参考网上众多 SDIO 布局教程之一。下面是一份参考原理图:
一条简短的 SDIO 布局建议:确保下方有连续的接地回流路径,尽可能进行信号长度匹配(误差控制在 1 毫米以内?),并总体上尽量缩短 SDIO 链路。当从 Pi Zero 或标准尺寸树莓派的 40 针排针引出 SDIO 时,有些信号需要大量长度匹配,有些则完全不需要——这很正常,树莓派 GPIO 引脚定义就是如此,只需记得把它们匹配好。按照 ESP-Hosted 文档要求,同时加入串联电阻和上拉电阻。
除了 SDIO 信号,你还需要控制 EN 引脚,以便驱动在开始通信前将 ESP32 复位到已知良好状态。就这一点而言,如果 GPIO 不够用且不介意,也可以将 EN 接到 OLED 显示屏常用的经典 RC 电路上。驱动希望提供 EN,但并非严格强制要求;如果你自行处理 EN 切换,只需在驱动初始化脚本中设置 resetpin=-1。
你不必担心 BOOT 引脚。但需要确保有充足的 3.3V 供电:300 mA 到 400 mA。树莓派板子上的 3.3V 电源轨通常足以给 ESP32 供电,但在其他单板计算机上,你可能需要额外增加一个 3.3V 稳压器,以满足 ESP32 对 3.3V 电源的需求。最后同样重要的是,以某种方式引出 ESP32 的 USB 接口,因为烧录固件时需要用到它。幸运的是,固件只需烧录一次。
你需要完成三件事:确保 SBC 的 SDIO(或 SPI)接口已释放,编译并烧录 ESP32 固件,然后编译并加载驱动。当然,顺序并非固定,但三项缺一不可。
在树莓派上释放 SDIO 接口相对简单:只需快速修改 config.txt。你只需重新映射 SDIO 引脚,如果已有 WiFi 卡,还要禁用其蓝牙功能。“禁用蓝牙”这一步很可能是必需的,因为板载 WiFi 卡的固件通过 SDIO 上传,因此该卡的蓝牙部分本来就无法正常工作。这也会释放树莓派上的 UART 控制台端口,在调试 WiFi 接口启动时极为有用。顺便说一句,我怀疑 SDIO 设备树覆盖参数 poll_once=off 是否真的必要,而且它似乎会让 dmesg 日志刷屏。如果你需要消除这些日志,移除该 poll 选项可能是一个不错的起点。
在其他 SBC 上,你可能在 SDIO 上遇到麻烦,但只要接口不过于冷门,问题通常不会太大。如果你正在自制 SBC,并且有开发板,不妨将 microSD 插槽接到 SDIO 引脚上,按需添加上拉电阻,并用一张备用 microSD 卡调试 SDIO 接口启动。如果 microSD 卡能正常工作,那么 ESP32 很可能也能正常工作。
编译 ESP32 固件也相对简单。你可能不想在 SBC 上编译 ESP32 固件,因为它在执行 cmake 时可能耗尽内存并卡死。在树莓派 Zero 上,这种情况几乎必然发生。只需使用台式计算机编译固件,避免麻烦。或者,你可以跳过这些步骤,直接从 GitHub 的 Releases 标签页下载固件。这些固件目前仍保存在旧版仓库中,但我预计未来新版本会发布到 esp-hosted-linux 仓库,请留意。
请确保你的驱动程序与 ESP32 固件来自同一版本的 esp-hosted Git 仓库,可使用 git log 等命令查看最后一次提交。否则,驱动程序会发出警告并拒绝加载;如果你认为版本差异很小,可以打补丁移除该警告,但风险自负。
以传统方式完成驱动
现在,驱动程序——您需要在单板计算机(SBC)上直接编译驱动,除非您进行交叉编译。rpi_init.sh 脚本会编译并加载驱动,其中还有一些可能有用的说明。如果您的 SBC 内存为 512MB 或更少,请用编辑器打开 rpi_init.sh,找到 make -j8 命令,将其替换为 make -j2(甚至是 -j1)。否则,编译过程会耗尽内存并导致 SBC 卡死。
现在所有东西都连接好了吗?如果 SDIO 配置正确且固件已烧录,驱动将正常加载,并出现一个 wlan 接口。遇到问题?请运行 dmesg 查看驱动模块的调试输出。我喜欢在备用终端窗口中运行 dmesg -Hw,或者直接在后台运行。
rpi_init.sh 脚本是一个很好的调试工具,但在长期运行模块时您最好弃用它,主要是因为它每次运行都会重新编译模块。在同一目录下,您可以找到 esp_sdio.ko——这就是您刚才编译的 Linux 模块。执行以下操作:
sudo cp esp_sdio.ko /lib/modules/ uname -r /kernel/drivers>/code> sudo depmod -a
这或许算是一种变通方法,但现在您可以直接运行 modprobe esp_sdio,而不必从脚本目录中使用 insmod。此外,您还可以将模块名(esp_sdio)写入 /etc/modules,使其在每次启动时自动加载,这比重新运行脚本以及随之而来的重新编译要好得多。
当然,仍有一些不足之处。首先,该模块应通过设备树接口进行正确集成,这样就不必将其添加到 /etc/modules 中,而是可以通过设备树覆写(overlay)实现自动加载。它也应该像 esp8089 驱动一样集成 dkms。目前,每次内核升级后您都必须重新编译并将模块重新添加到内核模块目录中,而 dkms 可以彻底解决这个问题。吞吐量尚可,在默认 SDIO 频率下可以达到 40Mbps 至 50Mbps。如果您认为硬件足够强大、能够进一步压榨 SDIO 的性能上限,那就还有一些可调的参数和选项!
那么为什么要讨论这个呢?我有四个重要的理由。第一,这是我知道的唯一一张能够通过 SDIO 而不是占用 UART 端口来传递蓝牙的 WiFi 卡,这对树莓派 Zero 形态的主板尤其有用。仅此一点就已经非常酷了。
第二,虽然代码还不够完美,而且有很多待处理的拉取请求值得查看,但 esp-hosted 在我的项目中确实处理了硬件电源开关!当 ESP32 断电时不会出现内核模块崩溃或失败,它能够无缝断开和重新连接,硬件开关运转自如,我觉得这一点非常迷人。
接下来的两个理由都与这张本质上属于开放固件的 WiFi 卡有关。ESP32 的固件并非完全开源,因为射频部分传统上属于闭源代码,会以二进制形式编译进去,但已有一些相当出色的项目试图将 ESP32 WiFi 协议栈中的专有部分解放出来。随着越来越多的人参与进来,我们完全有可能将无处不在的 ESP32 模块变成真正开源固件的 Linux WiFi 卡,而且成本极低、随处可见。真正适合黑客使用的持久型 WiFi 卡,还有什么理由不爱它呢?
最后一个理由是最有趣的,而且甚至不需要将其开源化。在完成 SDIO 连接后,ESP32 仍留有大量空闲引脚,其中包括高速 SPI 引脚。谁说我们不能接上 LoRa 调制解调器来运行 Meshtastic/Meshcore 之类的程序呢?由于固件大部分是开源的,理论上可以在 WiFi/蓝牙之间的空隙中添加任何代码,然后将有效数据转发给 Linux 主机。另外我也注意到新款 ESP32 芯片原生支持 Zigbee 和 Thread,而将这些功能暴露给 Linux 也只是编写代码的问题。对我来说,这是最精彩的部分——有朝一日,我们或许可以将 ESP32 打造成面向任意 Linux 处理器的真正瑞士军刀式通信协处理器。
本文来源:https://hackaday.com/2026/10/07/esp32-as-your-raspberry-pis-linux-wireless-co-processor/
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
[[IMG0]]A laptop without wireless connectivity seems rare—but when shopping for a high-performance Linux single-board computer (SBC), the lack of WiFi support is quite common. Meanwhile, current wireless network cards are often unsatisfactory: the confusing landscape of proprietary firmware, fleeting availability, binary-only closed-source drivers, and unresolved quirky bugs, and sometimes entire binary blobs with no source code and even an "expiration date." Perhaps the SBC has no spare USB port for a plug-and-play WiFi chip, or you don't want to design for an obscure, hard-to-source half-size module.
What if I told you there's a unique solution to this problem, as long as your SBC has one free SDIO or SPI interface? There is a wireless network card worth everyone's support: it's not perfect, but it offers us room to grow—its firmware is partially open source, from a reliable company, and almost certainly easy to source. I'm talking about esp-hosted—using an ESP32 module as your WiFi/Bluetooth adapter via SDIO or SPI.
I recently added an ESP32-C6 to a project, and the process of configuring esp-hosted wasn't entirely smooth—so here's a guide, along with a discussion of why esp-hosted is so great and why it holds such promise. Spoilers: it works with a hardware kill switch, can be repurposed as a co-processor supporting mesh protocols, and could help us build a fully open-source SDIO WiFi network card.
Two Major Projects, Covering Most Chips
A brief clarification is necessary first: there are actually two projects under the esp-hosted umbrella. One is esp-hosted-mcu (formerly esp-hosted-fg, meaning "first generation"), which runs the ESP32 more like a microcontroller that connects to WiFi, providing a relatively limited but self-contained interface on the Linux side—your connection layer is primarily managed by the ESP32 module itself, so it stays connected to your preconfigured WiFi network whether the host is restarting or completely powered off. For this reason, esp-hosted-mcu is best suited for microcontroller use cases, or scenarios where you want the ESP32 to act as a fully autonomous entity. Want to turn the ESP32 into an embedded controller (EC) with WiFi capability? Choose the -mcu version.
esp-hosted-linux (formerly esp-hosted-ng, meaning "next generation") keeps the wireless protocol stack on the Linux side, with the ESP32 acting as a relatively lightweight proxy for Linux's wireless protocol stack. I'll focus mainly on esp-hosted-linux here, since its behavior under Linux most closely resembles that of a "native" WiFi adapter, but much of what follows applies to both.
esp-hosted requires cooperation from both sides to work: a Linux computer with a free SDIO or SPI interface, and an ESP32 chip/module from the supported list. I chose the ESP32-C6. The common ESP32-WROOM module is more than sufficient, but most newer chips are also supported. Specifically, ESP32-S2, -S3, -C2, -C3, -C5, and -C6/C61 all work with esp-hosted-linux; if you're using a chip like the -S31, check the upstream project's issue tracker. I picked the C6 because I thought it supported the most features and was only slightly more expensive than the others—why not? But! That was a mistake. If I were designing a new board from scratch, I would choose the ESP32-C5. It turns out that despite the smaller number after the C, the ESP32-C5 is significantly better than the ESP32-C6, especially with its support for 5GHz.
Next, wiring is required via SDIO or SPI. If available, I recommend SDIO since it is much faster. One thing to note: make sure your SBC's SDIO interface is supported by the operating system, rather than in that unresolved state of "the hardware is ready, someone just needs to sort out the drivers" unless you are that someone. If you already have a dev board, you can temporarily connect an SD card to what you think are the SDIO pins to verify the SDIO interface actually works!
SDIO is essentially a full-duplex parallel bus containing one control signal (CMD), one clock signal (CLK), and four data lines (D0-D3)—if you want minimal, you can use just a single data line D0. These signal lines toggle quite fast and are not differential pairs, so route them carefully and treat them as single-ended signals. I will write a more detailed article on SDIO later, but until then, you can refer to one of the numerous SDIO layout guides online. Below is a reference schematic:
A brief SDIO layout tip: ensure a continuous ground return path underneath, perform signal length matching as much as possible (within about 1mm?), and generally keep the SDIO trace as short as possible. When routing SDIO from a Pi Zero or the standard 40-pin header on a full-size Raspberry Pi, some signals require significant length matching while others don't at all—that's normal, it's just how the Raspberry Pi GPIO pinout is defined; just remember to match them properly. As required by the ESP-Hosted documentation, include both series and pull-up resistors.
In addition to the SDIO signals, you also need to control the EN pin to drive the ESP32 into a known-good state before communication begins. As for that, if GPIO pins are insufficient and you don't mind, you can also connect EN to the classic RC circuit commonly used for OLED displays. The driver prefers to provide EN, but it is not strictly required; if you handle the EN toggle yourself, simply set resetpin=-1 in the driver initialization script.
You don't need to worry about the BOOT pin. However, you need to ensure sufficient 3.3V power supply: 300 mA to 400 mA. The 3.3V power rail on Raspberry Pi boards is usually sufficient to power the ESP32, but on other single-board computers, you may need to add an extra 3.3V regulator to meet the ESP32's power requirements. Equally important is routing out the ESP32's USB interface in some way, as it is needed for flashing firmware. Fortunately, the firmware only needs to be flashed once.
There are three things you need to accomplish: ensure the SBC's SDIO (or SPI) interface is released, compile and flash the ESP32 firmware, and then compile and load the driver. Of course, the order is not fixed, but all three are indispensable.
Releasing the SDIO interface on a Raspberry Pi is relatively straightforward: just quickly modify config.txt. You just need to remap the SDIO pins, and if you already have a WiFi card, disable its Bluetooth functionality. The "disable Bluetooth" step is likely necessary because the firmware for the onboard WiFi card is uploaded via SDIO, so the Bluetooth portion of that card was never going to work properly anyway. This also frees up the UART console port on the Raspberry Pi, which is extremely useful when debugging the WiFi interface startup. By the way, I suspect the SDIO device tree overlay parameter poll_once=off is not really necessary, and it seems to flood the dmesg logs. If you need to eliminate those logs, removing that poll option might be a good starting point.
On other SBCs, you may run into trouble with SDIO, but as long as the interface isn't too obscure, the problem is usually not too big. If you're building your own SBC and have a development board, consider connecting the microSD slot to the SDIO pins, adding pull-up resistors as needed, and debugging the SDIO interface startup with a spare microSD card. If the microSD card works fine, the ESP32 will most likely work as well.
Make sure your driver and ESP32 firmware come from the same version of the esp-hosted Git repository; you can check the last commit using commands like git log. Otherwise, the driver will issue a warning and refuse to load; if you believe the version difference is minor, you can patch out the warning, but you do so at your own risk.
Completing the driver the traditional way
Now, the driver—you need to compile it directly on the single-board computer (SBC) unless you cross-compile. The rpi_init.sh script compiles and loads the driver, and there are some notes in it that may be useful. If your SBC has 512 MB or less of memory, open rpi_init.sh in an editor, find the make -j8 command, and replace it with make -j2 (or even -j1). Otherwise, the compilation process will exhaust memory and cause the SBC to freeze.
Are all the connections ready? If the SDIO configuration is correct and the firmware is flashed, the driver will load normally and a wlan interface will appear. Encountering issues? Run dmesg to see the debug output of the driver module. I like to run dmesg -Hw in a spare terminal window, or run it directly in the background.
The rpi_init.sh script is a great debugging tool, but for long-term operation of the module, it is best to abandon it, mainly because it recompiles the module every time it runs. In the same directory, you can find esp_sdio.ko—that's the Linux module you just compiled. Do the following:
sudo cp esp_sdio.ko /lib/modules/$(uname -r)/kernel/drivers/ sudo depmod -a
This might count as a workaround, but now you can run modprobe esp_sdio directly instead of using insmod from the script directory. Additionally, you can write the module name (esp_sdio) into /etc/modules so it loads automatically on every boot, which is much better than re-running the script and its accompanying recompilation.
Of course, there are still some shortcomings. First, the module should be properly integrated through the device tree interface so that instead of adding it to /etc/modules, it can auto-load via a device tree overlay. It should also integrate DKMS like the esp8089 driver. Currently, you have to recompile and add the module back to the kernel module directory after every kernel upgrade, while DKMS can completely solve this problem. Throughput is decent, reaching 40 Mbps to 50 Mbps at the default SDIO frequency. If you think your hardware is powerful enough to squeeze more performance out of SDIO, there are some adjustable parameters and options!
So why discuss this? I have four important reasons. First, this is the only WiFi card I know of that can deliver Bluetooth via SDIO rather than consuming a UART port, which is especially useful for Raspberry Pi Zero form-factor boards. Just that alone is pretty cool.
Second, although the code is not yet perfect and there are many pending pull requests worth reviewing, esp-hosted does handle the hardware power switch in my projects! When the ESP32 is powered down, there are no kernel module crashes or failures; it can disconnect and reconnect seamlessly, and the hardware switch operates smoothly, which I find fascinating.
The next two reasons relate to the fact that this is essentially an open-firmware WiFi card. The ESP32 firmware is not entirely open source because the RF portion traditionally belongs to closed-source code and is compiled in as binaries, but there are already quite impressive projects trying to free the proprietary parts of the ESP32 WiFi protocol stack. As more people get involved, it's quite possible to turn the ubiquitous ESP32 module into a truly open-firmware Linux WiFi card at very low cost and with wide availability. What better reason is there to love a persistently hackable WiFi card?
The last reason is the most interesting and doesn't even require open-sourcing the firmware. After completing the SDIO connection, the ESP32 still has plenty of free pins left, including high-speed SPI pins. Who says we can't connect a LoRa modem and run something like Meshtastic/Meshcore? Since the firmware is mostly open source, in theory you can add any code in the gaps between WiFi and Bluetooth, then forward the payload to the Linux host. I've also noticed that the new ESP32 chips natively support Zigbee and Thread, and exposing those capabilities to Linux is just a matter of writing code. For me, this is the most exciting part—one day we might be able to mold the ESP32 into a true Swiss Army knife communications coprocessor for any Linux processor.
Source: https://hackaday.com/2026/10/07/esp32-as-your-raspberry-pis-linux-wireless-co-processor/ If there are copyright issues, please contact: 13951431913#139.com or leave a comment on the right.