esp32-c3-adblock
A Pi-hole-style DNS ad-blocker that runs on a $2 ESP32-C3 — no PSRAM required.
📰 Featured on Tom's Hardware, XDA Developers, and Korben.
The trick everyone misses: you don't need to keep the blocklist in RAM. Store the
domains as sorted 40-bit hashes in flash and binary-search them. 140,000+ domains
fit in 0.7 MB of flash and are matched in ~10 ms, using **50 KB of RAM**.
query in ──▶ extract domain ──▶ FNV-1a hash (+ parent suffixes)
──▶ binary-search the flash hash table
├─ hit ──▶ answer 0.0.0.0 (sinkholed)
└─ miss ──▶ forward to upstream resolver, relay the reply
Why this is interesting
Most ESP32 DNS sinkholes load the blocklist (domain strings) into RAM, so they
demand PSRAM. This project stores fixed 5-byte (40-bit) hashes in flash instead:
|
string-in-RAM approach |
this (hash-in-flash) |
| Hardware |
ESP32 + PSRAM (~$8) |
ESP32-C3, no PSRAM (~$2) |
| 141k domains |
~2.5 MB of RAM |
0.67 MB of flash |
| RAM used |
most of it |
~50 KB |
| Lookup |
string compare |
18 flash reads (10 ms incl. WiFi RTT) |
| Collisions |
n/a |
0 at 141k (1 at 537k) |
Why 40 bits? It's the sweet spot for this flash budget. Collisions follow the
birthday bound — at 141k domains you get ~0, at 537k about 1 (i.e. one unlucky
domain gets over-blocked). Dropping to 32 bits would save 20% of the flash but
cost ~7 collisions at 250k; going to 64 bits wastes 3 bytes per domain to solve
a problem you don't have.
The same trick works on bigger chips — it isn't a C3 workaround. On a 16 MB
ESP32-S3 these hashes hold ~2.7M domains vs ~466k for strings in 8 MB of
PSRAM. Hashes in flash beat strings in PSRAM basically everywhere; the C3 just
makes it undeniable.
Hardware
- Any ESP32-C3 board (tested on a C3 SuperMini), 4 MB flash, no PSRAM needed
- Power it from a stable USB source (a phone charger or your router's USB port).
Cheap/loose USB-C→A adapters can brown out the radio during WiFi transmit.
- A USB-A → USB-C dongle lets it plug straight into the spare USB port on the
back of most routers — no power supply, no extra box.
Enclosure
A printable case for the C3 SuperMini: hardware/esp32-c3-supermini-enclosure.stl
Printing notes:
- No supports needed; 0.2 mm layers, ~15% infill is plenty.
- Keep the antenna end clear. The C3's PCB antenna is the zig-zag trace on the
short edge opposite the USB-C port — don't bury it in solid plastic or put metal
near it, or your RSSI will suffer.
- Leave the vents open: the board idles around 45–55 °C.
One USB flash to get going — after that, firmware and blocklist both update over WiFi (see below).
⚠️ Use a current PlatformIO — the VSCode PlatformIO extension's bundled core, or
pip install -U platformio in a venv. The distro/apt platformio package (e.g. 4.3.4) is
too old and fails with AttributeError: ... 'resultcallback' (issue #4). A one-click browser installer is on the way (hosting TBD).
# 1. (optional) set WiFi creds at compile time — or skip this and use the
# on-device setup portal (below). secrets.h is gitignored, stays local.
cp src/secrets.example.h src/secrets.h
# then edit src/secrets.h -> WIFI_SSID / WIFI_PASS
# 2. build the blocklist hash table (default = StevenBlack base + Hagezi Light,
# ~140k domains, WhatsApp/social safe)
python3 tools/build_blocklist.py data/blocklist.bin
# 3. flash firmware + the blocklist filesystem (the one and only USB flash)
pio run -t upload
pio run -t uploadfs
# 4. watch it boot, note the IP / open the dashboard
pio device monitor # -> http://c3adblock.local
WiFi setup (no re-flash needed)
If it can't connect (or you never set secrets.h), it starts an open access point
C3-AdBlock-XXXX with a captive portal — join it from a phone, pick your network,
type the password, done. To move it to a new network later: open http://c3adblock.local/forgetwifi,
or hold the BOOT button while powering on, and the setup portal comes back.
Over-the-air updates (no more USB)
The dashboard at http://c3adblock.local does it all:
4 MB flash tradeoff: firmware OTA needs two app slots, which leaves 1.3 MB for the
blocklist (**250k domains max**). The aggressive 537k "ultimate" list only fits the
single-app partition table (no firmware OTA). Pick your tradeoff in partitions.csv.
Use it
Point a device's DNS at the C3's IP, or add it as a secondary resolver behind
your main DNS. Test:
dig @<c3-ip> doubleclick.net # -> 0.0.0.0 (blocked)
dig @<c3-ip> github.com # -> real IP (forwarded)
Gotchas (learned the hard way)
Done / how it could grow
- ✅ Web dashboard — per-client block/allow counts, ban a client, add custom domains
- ✅ mDNS (
c3adblock.local) for discovery
- ✅ OTA — firmware + blocklist update over WiFi, plus scheduled remote blocklist pulls
- ✅ Captive-portal WiFi setup (no hardcoded creds) + one-click browser web-installer
- ⬜ Bucketed prefix index — ~18 flash reads/lookup → ~1–2 (issue #3), the throughput win
- ⬜ Act as the DHCP server (hand itself out as DNS) for true plug-and-play
Credits
Inspired by s60sc/ESP32_AdBlocker — the
"answer 0.0.0.0 for blocklisted domains" idea. This is an independent from-scratch
implementation focused on the hash-in-flash optimization for PSRAM-less chips.
License
MIT — see LICENSE.
这是一个 Pi-hole 风格的 DNS 广告拦截固件,可以跑在没有 PSRAM 的 2 美元 ESP32-C3 芯片上,把多达 53.7 万个被屏蔽域名以紧凑哈希的形式存在闪存而不是内存里。