wificap — a receive-only 802.11 capture appliance
Firmware for the Waveshare ESP32-C5-LCD-1.47. It surveys both bands, parks on one channel, detects WPA2 four-way handshakes live on its own screen, and writes pcap-with-radiotap to a microSD card that Wireshark and aircrack-ng read without conversion.
Built as a lecture demonstration for CS410/510 IoT Security. The page that explains what it is for is wificap.html.
It only ever receives
The radio is brought up in WIFI_MODE_NULL: no station interface, no soft-AP,
nothing that can associate, probe, or transmit. There is no deauthentication
command and no injection path, deliberately. A classroom demonstration that
deauthenticates a network to force a handshake is touching networks belonging
to everyone in the building, and the demonstration stops being one you can
run in front of people.
The cost is honest: you capture a handshake when a device happens to join the network, not when you want one. See “Showing a handshake on demand” below.
Why not ESP32 Marauder
Marauder is the obvious tool and it does support the ESP32-C5 as a first-class target as of v1.20.0. It cannot run on this board:
- Every Marauder C5 target requires the 8 MB
default_8MBflash layout. This board is an ESP32-C5HF4 — 4 MB, inside the package, not expandable. Confirmed withesptool flash_id. - The 1.47” board is not a listed target. The Waveshare board Marauder supports is the larger ESP32-C5-Touch-LCD-3.5, a different device. The wiki is explicit: “Never substitute a binary merely because two devices use the same ESP32 family.”
If you want Marauder, use a C5-DevKitC-1 or a Seeed XIAO ESP32-C5, both of which are listed targets with 8 MB. This firmware exists because the board with the screen is the one that makes a good demo.
Build and flash
Needs ESP-IDF v5.5 or newer. The ESP32-C5 is a preview target before v5.5 and dual-band promiscuous receive is not something to run on preview support.
. $IDF_PATH/export.sh
idf.py set-target esp32c5
idf.py build
idf.py -p /dev/ttyACM0 flash
The BSP and LVGL are pulled from the ESP Component Registry; nothing is vendored. Insert a FAT32 microSD card before powering up.
Driving it
Commands go over the USB serial/JTAG console at 115200. Every reply is one
line beginning with a tag — OK, ERR, STAT, AP, HS, FILE — so the
console is equally usable by a person and by a script.
| command | what it does |
|---|---|
survey |
hop the channel plan, collect BSSIDs. Writes nothing. |
aps |
list access points seen, with channel, RSSI and SSID |
park <ch> |
stop on one channel. This is the capture mode. |
target <bssid> |
filter to one BSSID and park on its channel |
notarget |
clear the filter |
rec hs |
write management + EAPOL frames to the card |
rec all |
write everything the filter passed |
rec off |
stop and close the file |
hs |
handshake progress per station pair |
stat |
one machine-readable status line |
ls / get <f> / rm <f> |
list, download, delete captures |
selftest |
check the EAPOL parser and state machine |
Survey first, then park
This is the one thing the firmware is really teaching, so it is worth stating plainly: channel hopping and handshake capture are mutually exclusive. A sweep of 28 channels puts you on any given channel about 3.5% of the time, while a four-way handshake completes in a few milliseconds. Sweeping to find the target and then parking is not a convenience, it is the only way the capture can work.
survey # let it run ~20 s
aps # pick a target
target aa:bb:cc:dd:ee:ff
rec hs
The host tool
host/wificap.py drives the same console from a laptop and
pulls captures over the USB cable, so a demo does not end with ejecting a card
and hunting for an adapter.
./wificap.py survey --seconds 20
./wificap.py watch --target aa:bb:cc:dd:ee:ff --record hs
./wificap.py pull -o ./captures
pull verifies a CRC32 computed on the board against one computed on the
host. A serial transfer that silently drops a chunk produces a pcap that opens
cleanly and is subtly wrong, which is worse than one that fails loudly.
What lands on the card
Classic pcap, link type 127 (IEEE802_11_RADIOTAP). The radiotap header
carries channel frequency, RSSI and noise floor, so per-frame signal strength
survives into the analysis — without it the capture is bare 802.11 frames and
every RSSI is lost.
Beacons are recorded even in rec hs mode, because the SSID is an input to
the PMK and a capture holding a handshake but no beacon has no SSID in it.
Two things worth knowing:
- Timestamps start at zero, not wall clock. There is no RTC on the board and it never joins a network to ask. Frame ordering and inter-frame timing are correct; the absolute date is not.
- Frames are truncated at
CONFIG_WCAP_SNAPLEN, 512 bytes by default. That holds a complete beacon and a complete EAPOL-Key frame, which is everything a handshake analysis needs, and keeps the SD write rate well below the point where it competes with the display for the shared SPI bus.
Showing a handshake on demand
You cannot schedule someone else’s device to reconnect, and this firmware will not force one. Two honest options:
- Bring your own AP and client. Toggle Wi-Fi off and on on a phone associated to a WPA2-PSK network you control. That is a real handshake and the banner lights up.
selftest. Runs synthetic M1–M4 frames through the same classifier and state machine the live path uses, and reports what each was classified as. It touches neither the radio nor the capture file, and removes its synthetic pair afterwards so it cannot be mistaken for evidence.
> selftest
OK selftest M1=1 M2=2 M3=3 M4=4 state=f
Reading the screen
WIFICAP plan 28/28 sw 10 uptime, free heap
5 GHz band
153 channel — the big number
ap / eapol / wrote / drop counters, right
112 f/s ████████░░░░░░░░ how busy this channel is
████████████████░░░░░░░░ dwell progress (amber when parked)
▇▇▁▃▅▇▁▁▃▅▇▇▁▃▅▇▁▁▃▅▇▇▁▃▅▇▁▁ per-channel heat strip
PARK rec:hs a5c340 PSU-IoT mode, recording, target
HS a5c340>f42912 12-- +PMKID the handshake line
The heat strip is one cell per planned channel: white is where the radio is now, dark red is a channel the radio refused — which is not the same as a quiet channel, and the two are indistinguishable in a capture.
The handshake line latches. It stays after the event, because the point is that someone can glance over a minute later and still see it caught something.
drop is the counter to watch. It counts frames lost because the SD writer
fell behind, and a capture that silently drops frames looks exactly like a
quiet channel.
Why M1+M2 is already enough
An offline dictionary attack needs the two nonces and one MIC over a known EAPOL body. M1 carries the ANonce, M2 carries the SNonce and a MIC — so M1+M2 is sufficient, and so is M2+M3. Waiting for all four is a mistake people make because the handshake has four messages; M4 is frequently lost to a retry. The firmware flags a pair as crackable on that basis, not on seeing all four.
Memory
This board has ~148 KiB of usable DRAM and no PSRAM. The LVGL frame buffer,
the Wi-Fi driver’s rx pools, the capture ring, FatFS and the console REPL all
compete for it. Raising any one of them without lowering another does not
produce a warning — it produces ESP_ERR_NO_MEM from esp_wifi_init() at
boot, and a reboot loop whose only visible symptom is a flashing screen.
The knobs, in idf.py menuconfig under “wificap”, and in
sdkconfig.defaults:
| setting | default | note |
|---|---|---|
WCAP_RING_BYTES |
16384 | raise if drop moves, memory permitting |
WCAP_SNAPLEN |
512 | full beacon and full EAPOL-Key |
BSP_DISPLAY_LVGL_BUF_HEIGHT |
40 | 80 costs 25 KB more and starves the radio |
ESP_WIFI_DYNAMIC_RX_BUFFER_NUM |
32 |
Layout
main/
main.c startup, task creation, the receive-only posture
capture.c promiscuous callback, EAPOL parsing, handshake state, selftest
scan.c radio bring-up, channel-plan probing, survey/park scheduler
pcap.c SD mount, radiotap + pcap writer task
ui.c the screen
console.c the command interface
host/
wificap.py host-side driver and capture downloader
Legal
Capturing a handshake from a network you do not administer is interception. Use your own access point and your own client. The firmware’s refusal to transmit limits what it can do to you; it does not decide what you point it at.