-
1Step 1
HARDWARE
(WiFi Pants owners skip to SOFTWARE below)
You'll need 6x 33 ohm resistors (either through-hole or SMT), some wire, and an ESP-12F module.
Some variants of the ESP-12E should work as well, but there are some that do not have the GPIO9 and GPIO10 pins connected to the edge, and others that have a different pinout than listed here. From what I can tell there is only one variant of the ESP-12F (labeled "ESP-12-F QIO L4" on the back) so that is a safer bet. ESP-12F also has an onboard 10uF capacitor across the input supply, which saves you from having to add one yourself.
You probably want something to mount the ESP-12F on. Perfboard is fine, as would be cardboard or just double-sided foam tape on the back of the Pi. No matter what you use, make sure that nothing is under the antenna or range will be greatly reduced. The ESP-12F LED is a good mark for the start of this keepout region.
I use outdoor double-sided foam tape on my hand-built boards since it's tough but not hard to reposition, and raises the module enough to not short against the board. Creative application of hot glue or epoxy putty might work fine as well.
-
2Step 2
Make the connections between the ESP-12F or -12E and the Raspberry Pi HAT. Keep wires short as possible, and minimize the number of times they cross over each other. If you're using magnet wire or Kynar (standard issue blue wire) you might want to use a heavier gauge for the 3.3V and GND. Ideally the wire lengths of the 6 SDIO signals should be identical, but even a couple of inches of difference shouldn't matter. If you can, keep SD_CLK close to the average length of the other wires.
The SDIO signals (names beginning "SD_") should have 33 ohm resistors in series (in between the Pi and ESP-12F connections). It may work with other slightly larger values, or with no resistor at all.
If using 1-bit SDIO instead of 4-bit, omit D2 and D3. There's not much of a good reason for this though.
A capacitor of 10uF or more may be needed between 3.3V and GND near the module, though a legit ESP-12F already has a 10uF supply cap onboard.
Wire it like this:
SDIO signal RPi HAT ESP-12F pin / signal ESP-03 pin / signal CLK 15 / GPIO22 14 / SCLK Flash pin 6 (CLK) CMD 16 / GPIO23 9 / CS0 Flash pin 1 (/CS) D0 18 / GPIO24 10 / MISO Flash pin 2 (DO) D1 22 / GPIO25 13 / MOSI Flash pin 5 (DI) D2 (optional for 1-bit) 37 / GPIO26 11 / GPIO9 Flash pin 7 (HOLD) D3 (optional for 1-bit) 13 / GPIO27 12 / GPIO10 Flash pin 3 (WP) - 1 or 17 / 3.3V 8 / VCC Module 1 / VCC - 2, 4, 14, or 20 / GND 15 / GND Module 8 / GND - 27 / ID_SD 3 / CH_PD Module 13 / CH_PD Note that the CH_PD signal is connected to the ID_SD signal. This must be mapped as a GPIO (GPIO0) and switched to an output and driven low then switched to an input again before the driver is loaded in order to reset the module. This will be added in the near future in the driver.
The ESP-03 column above is for people who want to use an ESP-03 module instead. This requires soldering to the pins of the SPI flash chip for some of the signals. The SPI flash may be desoldered first, or left in place.
-
3Step 3
SOFTWARE
Start with a fresh 32-bit Raspberry Pi OS SD image of 2023-05-03 or later.
A network connection to the Pi is required for the initial installation for the OS to fetch dependencies to build the driver module. This could be the onboard Ethernet of a model B Pi, a supported USB-Ethernet or USB-WiFi adapter, or the Pi Zero connected through another PC over USB.
-
4Step 4
Log in as "pi" or your user with sudo privs and Install prerequisite packages to build the driver.
#make sure everything is up to date sudo apt update && sudo apt -y upgrade #install module build dependencies sudo apt -y install dkms raspberrypi-kernel-headers
-
5Step 5
Add the line "dtoverlay=sdio,poll_once=off" to /boot/config.txt, or replace any existing "dtoverlay=sdio" line.
If you're using 4-bit SDIO, which you likely are, run this to set up the boot configuration:
#4-bit SDIO setup (for WiFi Pants board) sudo sed -i -e "/^dtoverlay.*sdio/d" /boot/config.txt sudo sh -c 'echo "dtoverlay=sdio,poll_once=off" >> /boot/config.txt'
If you're using 1-bit SDIO, use this instead (or the WiFi driver will crash when you load it):
#1-bit SDIO setup (NOT for WiFi Pants board) sudo sed -i -e "/^dtoverlay.*sdio/d" /boot/config.txt sudo sh -c 'echo "dtoverlay=sdio,poll_once=off,bus_width=1" >> /boot/config.txt'
-
6Step 6
If you didn't use ID_SD (GPIO0, HAT pin 27) as the CH_PD GPIO, provide the kernel module with the right one via a modprobe.d conf file. Replace "5" below with the correct GPIO number.
Skip this step if you are using a WiFi Pants board as it uses the default of GPIO0.
sudo sh -c 'echo "options esp8089 esp_reset_gpio=5" > /etc/modprobe.d/esp.conf'
-
7Step 7
Reboot to load the updated kernel and activate SDIO
sudo reboot
-
8Step 8
After the reboot, log in and fetch the DKMS package for esp8089:
wget https://github.com/al177/esp8089/releases/download/1.9.20230804/esp8089-dkms_1.9.20230804_all.deb.gz gunzip esp8089-dkms_1.9.20230804_all.deb.gz
Check https://github.com/al177/esp8089 for the latest release in case I forget to update these instructions
-
9Step 9
Install the package (sub the filename from the wget above if different):
sudo dpkg -i esp8089-dkms_1.9.20230804_all.deb
This package will be automatically rebuilt and installed every time Raspbian installs a new kernel.
-
10Step 10
Load the driver.
sudo modprobe esp8089
If the ESP8089/8266 is found, you should see these lines spread through dmesg:
[ 2.253368] mmc1: new high speed SDIO card at address 0001
[ 5.416128] ***** EAGLE DRIVER VER:bdf5087c3deb***** [ 5.618948] esp_sdio_init power up OK [ 6.140907] first normal exit [ 6.141112] esp_sdio_remove enter [ 6.249295] eagle_sdio: probe of mmc1:0001:1 failed with error -123 [ 6.249485] mmc1: card 0001 removed [ 6.333036] mmc1: new high speed SDIO card at address 0001 [ 6.716629] esp_host:bdf5087c3deb [ 7.126350] esp_op_add_interface STAThe probe error is expected when the ESP restarts after the firmware is loaded.
Discussions
Become a Hackaday.io Member
Create an account to leave a comment. Already have an account? Log In.
1-bit mode still makes some sense - two components off the BoM and two fewer precious GPIOs claimed by the SDIO interface (with more chance to avoid conflicts with other add-on boards). To that end I've made a pull-request re adding another overlay specifically for 1-bit mode, configuring only pins 22-25.
Are you sure? yes | no
I agree, but for most of the people following the directions verbatim it doesn't make sense to not wire those last two.
It's a shame the Pi bootloader overlay system doesn't allow for more complexity with parameters. It would be much easier if we could have a single boolean that could enable the correct number of GPIOs and set the bus width at the same time.
Are you sure? yes | no
I am a newbie.. i very much need this in my project... but i am not able to understand the procedure.. is there any way that you can simplify the instructions or make a sort of video on how to do this step by step? thanks in advance
Are you sure? yes | no
The instructions concern my early hack / proof-of-concept. At the moment I'd rather put my efforts into something that's easy to assemble or manufacture. The version in the instructions works, but requires some moderate soldering skill and a little improvisation.
Are you sure? yes | no
thanks any ways... waiting eagerly for a diy version.. so that i can get internet to my pi under $3 :)
Are you sure? yes | no
Thanks to those great instructions I was able to build this in less than half an hour. I did lame performance test (using my phone as an AP as I don't have any other at hand right now) and I'm getting 24Mbits/sec in iperf test, which is great. I'm not sure if it's not a phone limit, though.
Are you sure? yes | no
Excellent!
Is this using the ESP-03 and 4-bit mode?
I'm still not entirely certain where the bottlenecks are, though given that I've seen much higher rates than that on my custom board I don't entirely trust the ESP-03 modules I've tried to be optimal on the RF front.
Are you sure? yes | no
Yes, esp03, 4bit mode. I'm pretty sure that my phone acting as AP can't do much better than that so I'll retest this when I'm back home. Still this is higher tab I expected so this hack is awesome. Thanks!
Are you sure? yes | no
I'm getting reliably 30Mbit/s of UDP traffic without losses. What's interesting is that the speed is exactly the same when using 4bit and 1bit SDIO mode. iwconfig is reporting 54Mb/s which is maximum that is reported as supported rate by "iw list". Getting 30Mbit/s of real bandwidth on a 54Mb/s wifi link seems great to me. Even my (quite old) Thinkpad x201 that sits in the same place as ESP866 is performing slightly worse than that (~27Mbit/s).
Are you sure? yes | no
Great!
I have one of my custom boards rigged for 1-bit SDIO. I'll do an iperf run on that one since it has historically performed better than the ESP-03s.
On the Pi, the SDIO actually clocks at 41.66MHz and not 50MHz in high speed mode, so end-to-end throughput of 3/4 of the throughput of the bus itself is pretty good.
Are you sure? yes | no
Also I just tested hostapd. It works but unfortunately I can get "only" 10Mbit/s in iperf. Unfortunately combined AP/STA interface seems not supported but this still gives a lot of possibilities.
Are you sure? yes | no
My ESP-03 hairball only gives ~7Mib/s, I'm jealous ! https://twitter.com/gregeric/status/685139725309591552
Are you sure? yes | no
My ESP-12F hanging off the pi on dupoint cables gives me 28Mbit/s (1 bit mode) copying a file from my NAS. That's next to a decent N router. I expect its the antenna/SI of these modules is crap compared to the board that @ajlitt built.
Note that the ESP8266 only supports upto HT20, MCS7 (65Mbps / 72.2Mbps) anyway. https://nurdspace.nl/ESP8266#RF_specifications
Are you sure? yes | no
pi@raspberrypi:~/esp8089 $ sudo make install
mkdir -p -m 755 /lib/modules/4.1.15+-v7/misc
install -m 0644 esp8089.ko /lib/modules/4.1.15+-v7/misc
/sbin/depmod -a 4.1.15+-v7
depmod: WARNING: could not open /lib/modules/4.1.15+-v7/modules.order: No such file or directory
depmod: WARNING: could not open /lib/modules/4.1.15+-v7/modules.builtin: No such file or directory
What is the error?
Are you sure? yes | no
I also now have these warnings on a clean SD card reimage.
Are you sure? yes | no
Does it work despite the warnings? Does the running kernel match what rpi-source pulled down? Is there anything at all in the modules directory it's complaining about?
I haven't gone through the entire process since the last time I updated this, but I'm turning my attention back to the software end next week so I'll keep an eye out.
Are you sure? yes | no
@ajlitt I think it was the rpi-source kernel, building the latest kernel (to get bus_widh fix) didn't give me this warning.
Are you sure? yes | no
OK I solved this. The module is not being installed properly. It's a bug with rpi-source https://github.com/notro/rpi-source/issues/17
You need to go into the linux directory that rpi-source downloads. 'make clean' and then edit the Makefile to remove the EXTRAVERSION. then make an .scmversion file with a '+' in it. Then 'make modules_prepare'
Then go back to the esp8089 driver and 'make clean' it and then make/install it again.
You might want to remove the invalid /lib/modules/4.1.15+-v7 directory
Are you sure? yes | no
Great!
I'll look into making a separate install target for RPi in the driver makefile to work around this.
Are you sure? yes | no
The instructions works great, tested on RPI A+ with a ESP-03.
Are you sure? yes | no