Repolode
Submit
M-Abozaid

M-Abozaid/esp32-c3-adblock

A Pi-hole-style DNS ad-blocker for the $2 ESP32-C3 that stores blocklist hashes in flash, so it needs no PSRAM.

Open-source alternative to:Pi-hole

View on GitHub
Stars
3,519
Forks
395
Open issues
34
Last commit
17 hours ago

What is it?

esp32-c3-adblock turns a small ESP32-C3 microcontroller board into a network DNS sinkhole. Devices on your network point their DNS at the board, which answers blocked domains with 0.0.0.0 and forwards every other query to an upstream resolver.

The main technique is storing each blocked domain as a sorted 40-bit FNV-1a hash in flash and binary-searching that table on lookup. This keeps the blocklist out of RAM, so the firmware uses about 50 KB of RAM and runs without PSRAM. The project reports roughly 141k domains fitting in about 0.7 MB of flash, and around 537k domains with the larger list.

The board serves a web dashboard with per-client block counts, custom ban and allow entries, and blocklist or firmware updates over WiFi. Blocklists are built with a Python script from hosts files, plain domain lists, or AdGuard-style rules.

Key features

  • 01Answers blocked domains with 0.0.0.0 over UDP DNS, forwarding other queries upstream.
  • 02Stores blocklist as 40-bit hashes in flash, using about 50 KB RAM and no PSRAM.
  • 03Web dashboard with per-client block counts and custom ban or allow entries.
  • 04Over-the-air firmware and blocklist updates, with scheduled remote blocklist pulls.
  • 05Captive-portal WiFi setup and mDNS discovery at c3adblock.local.
  • 06Blocklist builder accepts hosts files, plain domain lists, and AdGuard basic rules.

Use cases

  • Adding network-wide ad and tracker blocking to a home router without buying a Raspberry Pi.
  • Running a low-power secondary DNS resolver that blocks domains behind your main DNS.
  • Experimenting with embedded DNS filtering on a cheap ESP32-C3 board.

Quick start

  1. 1

    Copy the secrets template and edit it with your WiFi and dashboard credentials

    cp src/secrets.example.h src/secrets.h
  2. 2

    Build the blocklist hash table

    python3 tools/build_blocklist.py data/blocklist.bin
  3. 3

    Flash the firmware to the ESP32-C3 over USB

    pio run -t upload
  4. 4

    Flash the blocklist filesystem over USB

    pio run -t uploadfs

Things to know

  • Requires a current PlatformIO; the old apt-packaged version fails to build.
  • On 4 MB flash, firmware OTA updates limit the blocklist to about 250k domains.
  • Dashboard and OTA passwords must be set in secrets.h, or the device boots with public default credentials.
  • Traffic is plain HTTP with Basic Auth, so it is not encrypted on the LAN.

In collections

Embedded systems & microcontroller projects

Topics

#dns#esp32#adblock#dns-sinkhole#iot#embedded#pi-hole#adblocker#arduino#esp32-c3

FAQ

What is esp32-c3-adblock?
A Pi-hole-style DNS ad-blocker for the $2 ESP32-C3 that stores blocklist hashes in flash, so it needs no PSRAM. esp32-c3-adblock turns a small ESP32-C3 microcontroller board into a network DNS sinkhole. Devices on your network point their DNS at the board, which answers blocked domains with 0.0.0.0 and forwards every other query to an upstream resolver.
Is esp32-c3-adblock free to use? What license does it have?
esp32-c3-adblock is open source under the MIT license. Check the license terms before using it in commercial products.
Is esp32-c3-adblock still maintained?
Actively maintained. The last commit to esp32-c3-adblock was on Nov 6, 2026.
What can I use esp32-c3-adblock for?
Adding network-wide ad and tracker blocking to a home router without buying a Raspberry Pi. Running a low-power secondary DNS resolver that blocks domains behind your main DNS. Experimenting with embedded DNS filtering on a cheap ESP32-C3 board.
How do I install esp32-c3-adblock?
Copy the secrets template and edit it with your WiFi and dashboard credentials: cp src/secrets.example.h src/secrets.h Build the blocklist hash table: python3 tools/build_blocklist.py data/blocklist.bin Flash the firmware to the ESP32-C3 over USB: pio run -t upload Flash the blocklist filesystem over USB: pio run -t uploadfs
Where can I get esp32-c3-adblock?
The source code and installation instructions are on GitHub: https://github.com/M-Abozaid/esp32-c3-adblock

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects