esp32-c3-adblock README

The project's README from github.com/M-Abozaid/esp32-c3-adblock. As one markdown file: README.md.

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

Enclosure

A printable case for the C3 SuperMini: hardware/esp32-c3-supermini-enclosure.stl

Printing notes:

Build & flash (PlatformIO)

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

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.

esp32-c3-adblock (M-Abozaid/esp32-c3-adblock)

c++
Searching Database…

3.2K ·GitHub
Esp32-c3-adblock
What is this?It is a Pi-hole-style DNS ad-blocker firmware that runs on a $2 ESP32-C3 chip with no PSRAM, storing up to 537k blocked domains as compact hashes in flash instead of RAM.
Is this a piece of software I install on existing hardware, or do I need to buy something?It is firmware you flash onto a cheap ESP32-C3 board (e.g. a C3 SuperMini) that then acts as a standalone network device with its own web dashboard.
How do I build and flash it?Use PlatformIO to build and flash it once over USB; after that, both firmware and the blocklist can be updated over WiFi via the device's web dashboard.
What tools do I need before flashing it?You need a current PlatformIO install (the VSCode extension's bundled core or a fresh pip install), since the older distro/apt PlatformIO packages fail.
What's the catch with the big 537k-domain blocklist?The full 'ultimate' 537k-domain list only fits the single-app partition table, which disables firmware OTA updates; with OTA enabled, only ~250k domains fit in the remaining flash.
Who would want to build this instead of a Raspberry Pi Pi-hole?Anyone wanting a tiny, cheap, low-power DNS ad-blocker that plugs directly into a router's spare USB port instead of running a full Pi-hole server.
Why store the blocklist as hashes in flash instead of domain strings in RAM?It avoids needing PSRAM entirely: 141k domains take ~0.67 MB of flash and ~50 KB of RAM as 40-bit hashes, versus ~2.5 MB of RAM for raw domain strings, with lookups done via binary search in flash (~10ms).
How does WiFi get configured without hardcoding credentials?If it can't connect or has no saved credentials, it starts an open access point called C3-AdBlock-XXXX with a captive portal where you pick your network and type the password; holding BOOT on power-up reopens this setup portal.
What can the web dashboard do?It shows per-client block/allow counts, lets you ban a client or add custom blocked domains, and handles OTA uploads for both the firmware and the blocklist.bin file.
Is there a risk of a legitimate domain getting falsely blocked?Yes, slightly: using 40-bit hashes has a small collision chance, roughly 0 collisions at 141k domains but about 1 collision expected at the full 537k-domain list, meaning one unlucky domain could be over-blocked.
What are similar projects?glasshouse, Arduino, smartknob, esphome, WLED, awesome-esp32, esp-idf, tiny-engineer
Which topics is it in?adblocker, pi-hole, ad-blocker, arduino, home-automation, esp32, dns, firmware, iot, embedded, hardware, dashboard
Creator
M-Abozaid
Size
1.5 MB
Stars
3.2K
Updated
CommitOct 06ReleaseblocklistOct 04
Age
3mo
Commits · 90 Days