(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.
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.
Start with a fresh Raspbian SD image of 2016-05-10 or later.
A network connection to the Pi is required for the initial installation for Raspbian 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.
Log in as "pi" and Install prerequisite packages to build the driver.
#make sure everything is up to date sudo apt-get update && sudo apt-get -y upgrade #install module build dependencies sudo apt-get -y install dkms raspberrypi-kernel-headers
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'
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'
Reboot to load the updated kernel and activate SDIO
After the reboot, log in and fetch the DKMS package for esp8089:
wget https://github.com/al177/esp8089/releases/download/1.9.20171208/esp8089-dkms_1.9.20171208_all.deb.gz gunzip esp8089-dkms_1.9.20171208_all.deb.gz
Check https://github.com/al177/esp8089 for the latest release in case I forget to update these instructions
Install the package (sub the filename from the wget above if different):
sudo dpkg -i esp8089-dkms_1.9.20171208_all.deb
This package will be automatically rebuilt and installed every time Raspbian installs a new kernel.
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 STA
The probe error is expected when the ESP restarts after the firmware is loaded.