esp32-c3-adblock

Product Introduction

1. Definition: The esp32-c3-adblock is a DNS sinkhole application, a network-level ad-blocker, specifically engineered to run on the ultra-low-cost ESP32-C3 microcontroller. It functions as a lightweight, dedicated DNS server that intercepts and blocks requests to known advertising and tracking domains.
2. Core Value Proposition: This project solves the problem of implementing whole-network ad blocking without the cost, complexity, and power consumption of a dedicated Raspberry Pi or x86 server. Its primary innovation is storing a massive blocklist of over half a million domain hashes directly in the microcontroller's internal flash memory, eliminating the need for expensive PSRAM and enabling ad-blocking on a sub-$5 hardware platform.

Main Features

1. Hash-in-Flash Blocklist Engine: The core technical innovation. Instead of storing domain name strings in RAM, the system converts domains into compact 40-bit FNV-1a hashes, which are sorted and stored in the ESP32's SPI flash memory. DNS queries are processed by hashing the requested domain (and its parent suffixes) and performing a binary search on this flash-based table. This allows ~140,000 domains to fit in ~0.7 MB of flash with lookups completing in approximately 10 ms, using only about 50 KB of RAM.
2. Full-Featured Web Dashboard & Management: The device hosts a responsive web interface accessible via its IP address or mDNS (c3adblock.local). The dashboard provides real-time statistics (query counts, blocked vs. allowed, per-client activity), manual domain blocking/allowlisting, and client banning. All state-changing operations are protected by HTTP Basic Auth.
3. Over-the-Air (OTA) Update System: Enables complete maintenance without physical access. Users can update both the device's firmware and the domain blocklist directly from the web dashboard. The system supports scheduled, automatic updates from a remote URL (e.g., a pre-built blocklist hosted on GitHub), ensuring the blocklist stays current against new ad domains.

Problems Solved

1. Pain Point: High barrier to entry for network-wide ad blocking. Traditional solutions like Pi-hole require a always-on computer (Raspberry Pi) or virtual machine, involving higher upfront cost ($35+), setup complexity, and ongoing power draw (5-10W).
2. Target Audience: IoT hobbyists, privacy-conscious home users, students learning embedded networking, and developers seeking a minimalist, low-power network appliance. It's ideal for anyone wanting to block ads on their smart home or local network with minimal investment and footprint.
3. Use Cases: Plugging directly into a router's USB port for instant network ad-blocking; deploying as a portable ad-blocking travel router; serving as an educational platform for DNS protocol and embedded web server development; providing a secondary, dedicated DNS sinkhole in a homelab environment.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros:
     • Extremely Low Cost: Based on a ~$2 ESP32-C3 chip, total build cost is under $5.
     • Minimal Power Consumption: Draws less than 0.5W, allowing it to be powered indefinitely from a router's USB port.
     • No PSRAM Dependency: Innovative flash-based storage makes high-capacity blocklists possible on the most basic hardware.
     • Self-Contained & Wireless: Includes WiFi, a web server, and OTA updates for a fully managed experience.
   • Cons:
     • Throughput Limit: As a single-core microcontroller handling UDP DNS packets and web requests, it is not designed for very high query volumes (e.g., >1000 QPS) of a large enterprise.
     • Flash Storage Trade-off: The 4MB flash is shared between firmware, filesystem, and the blocklist. Using the dual-OTA partition scheme reduces maximum blocklist size to ~250k domains.
     • No Encrypted DNS (DoH/DoT): The DNS server operates only on standard, unencrypted UDP port 53. It cannot act as a client to upstream encrypted DNS resolvers.

2. Key Alternatives & Differentiation:

   • Pi-hole (Raspberry Pi): The gold standard. Runs on a Raspberry Pi (Linux) offering a vastly more powerful web interface, granular control, regex filtering, and unlimited list size. Differentiation: esp32-c3-adblock is 1/10th the cost, uses 1/20th the power, and is far simpler to initially deploy, but lacks advanced features and scalability.
   • AdGuard Home (x86/ARM Linux): A sophisticated, feature-rich competitor similar to Pi-hole. Differentiation: esp32-c3-adblock is not a general-purpose software package but a dedicated firmware for a specific, ultra-cheap hardware target, focusing on absolute minimalism and cost.
   • Other ESP32 DNS Blockers (e.g., ESP32_AdBlocker): Many exist but typically load the domain strings into RAM, requiring an ESP32 with PSRAM (more expensive). Differentiation: The hash-in-flash architecture is the key differentiator, enabling high-capacity blocking on the cheapest PSRAM-less ESP32-C3 and proving more storage-efficient even on larger chips.

Frequently Asked Questions (FAQ)

1. How many domains can the ESP32-C3 adblocker block? The default build blocks approximately 100,000 domains. By using a single-app partition scheme, it can hold a maximum of around 537,000 domain hashes before reaching the 4MB flash limit. The exact number depends on the selected partition layout.
2. Can I use this as my primary DNS server for my whole home network? Yes, you can configure your router's DHCP settings to give out the ESP32-C3's IP address as the primary DNS server for all connected devices. It is designed for this purpose in typical home networks with dozens of clients.
3. Is it safe to use? Does it support secure DNS (DoH/DoT)? The device provides a standard DNS-over-UDP (port 53) service. It does not serve encrypted DNS (DoH/DoT) to your clients. For security, its web dashboard uses HTTP Basic Auth to prevent unauthorized configuration changes, but the connection itself is not HTTPS/TLS encrypted due to hardware constraints.
4. What happens if there's a hash collision? A 40-bit hash space provides a low probability of collision. With 141,000 domains, the chance is effectively zero. At the maximum of 537,000 domains, the birthday paradox predicts roughly one collision, meaning one non-ad domain might be incorrectly blocked alongside an ad domain.
5. How do I update the blocklist or firmware? Updates are performed entirely over WiFi. You can manually upload a new blocklist.bin file via the web dashboard, set an automatic update URL, or upload a new .bin firmware file for an OTA update. You only need a USB cable for the initial flash.