
由 Zed(M-Abozaid)开发的 esp32-c3-adblock 是一款开源、类 Pi-hole 的 DNS 广告拦截器,可在无需 PSRAM 的 2 美元 ESP32-C3 微控制器开发板/模组上运行。它通过过滤 DNS 请求,拦截家庭或小型办公室网络中各设备的广告和跟踪域名。
该项目不在 RAM 中存储域名字符串,而是将其以排序后的 40 位 FNV-1a 哈希形式存入闪存,并通过二分查找检查 DNS 请求。当收到 UDP DNS 查询时,C++ 固件提取域名,对其进行哈希(包括上级后缀),然后在闪存哈希表上执行二分查找。如果域名位于黑名单中,ESP32-C3 返回 0.0.0.0 以阻止请求;否则,它将查询转发给上游 DNS 服务器,并将响应返回给客户端。该方法可在约 0.7 MB 闪存中容纳超过 14 万个域名,仅占用约 50 KB RAM。一次查找约需 10 毫秒(含 Wi-Fi 往返时间),大约需要 18 次闪存读取。
安装在 3D 打印外壳中的 ESP32-C3 SuperMini DNS 广告拦截器,配有 USB-C 转 USB-A 适配器,可直接连接路由器
esp32-c3-adblock 的要求与亮点:
直接连接至路由器 USB 端口的 ESP32-C3 SuperMini DNS 广告拦截器(图像经 AI 增强)
该项目包含一个可通过 http://c3adblock.local 访问的 Web 控制面板,用户可在其中查看各客户端被拦截和允许的 DNS 请求、屏蔽特定设备,并向黑名单添加自定义域名。初始 Wi-Fi 设置通过强制门户处理,用户无需硬编码 Wi-Fi 凭据。
该设备还支持固件和拦截列表的空中升级(OTA),并可按计划自动更新,从指定 URL 下载预构建的拦截列表文件。在 4MB 的 ESP32-C3 开发板上,固件 OTA 升级需要两个应用分区,因此仅能保留约 1.3MB 闪存用于存储拦截列表,可容纳最多 25 万个域名。若使用规模更大的 53.7 万域名拦截列表,用户需切换为单应用分区布局,但这会禁用固件 OTA 升级。
网页仪表盘显示拦截列表统计信息、已连接客户端、Wi-Fi 信号强度、内存使用情况和自定义拦截域名(图片经 AI 增强)
值得注意的是,该项目采用了 40 位哈希宽度;开发者表示,在有限的闪存预算下,这是最优选择。在包含 14.1 万个域名时,哈希冲突几乎为零。若将列表扩大至激进的 53.7 万个域名,大约会出现一次冲突,即一个域名被误拦截。若改用标准的 32 位哈希,虽可节省闪存空间,但在 25 万个域名规模下大约会产生七次冲突。
开发者表示,该项目受到 s60sc 的 ESP32_AdBlocker 启发,但属于独立实现,采用闪存而非 PSRAM 来存储大规模拦截列表。相同思路也可用于性能更强的芯片。例如,在 16MB 的 ESP32-S3 上,使用 40 位哈希可存储约 270 万个域名;相比之下,在 8MB PSRAM 中以字符串形式存储仅能容纳约 46.6 万个域名。
C++ 源代码、PlatformIO 构建说明以及可 3D 打印的外壳文件均可在 GitHub 仓库中获取。
Debashis Das 是一名技术内容撰稿人和嵌入式工程师,拥有超过五年的行业经验。他精通嵌入式 C 语言、PCB 设计和 SEO 优化,能够将复杂的技术主题转化为清晰易懂的内容。
支持CNX Software!您可以通过加密货币进行捐赠,在Patreon上成为赞助者,或在亚马逊、速卖通上购买商品。我们也会在文章中使用联盟营销链接,如果您点击这些链接后完成购买,我们将获得相应佣金。
本文来源:https://www.cnx-software.com/2026/10/09/open-source-esp32-c3-dns-ad-blocker-supports-up-to-over-500000-domains-without-psram/
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
Developed by Zed (M-Abozaid), the esp32-c3-adblock is an open-source, Pi-hole-style DNS ad blocker that runs on a $2 ESP32-C3 microcontroller board/module without requiring PSRAM. It blocks ads and tracking domains across devices on a home or small office network by filtering DNS requests.
Instead of storing domain strings in RAM, the project stores them as sorted 40-bit FNV-1a hashes in flash memory and uses binary search to check DNS requests. When a UDP DNS query comes in, the C++ firmware extracts the domain, hashes it (including parent suffixes), and performs a binary search against the flash hash table. If the domain is on the blocklist, the ESP32-C3 returns 0.0.0.0 to block the request. Otherwise, it forwards the query to an upstream DNS server and returns the response to the client. This method fits over 140,000 domains into ~0.7 MB of flash memory while using only ~50 KB of RAM. A lookup takes around 10 ms (including WiFi round-trip time), requiring about 18 flash reads.
ESP32-C3 SuperMini DNS ad blocker in a 3D-printed enclosure with a USB-C to USB-A adapter for direct connection to a router
esp32-c3-adblock requirements and highlights:
ESP32-C3 SuperMini DNS ad blocker connected directly to a router’s USB port (Image enhanced with AI)
The project includes a web dashboard accessible at http://c3adblock.local, where users can view per-client blocked and allowed DNS requests, block specific devices, and add custom domains to the blocklist. Initial Wi-Fi setup is handled through a captive portal, so users do not need to hardcode their Wi-Fi credentials.
It also supports over-the-air (OTA) updates for both firmware and blocklists, along with scheduled automatic updates that download prebuilt blocklist files from a specified URL. On a 4MB ESP32-C3 board, firmware OTA updates require two app slots, leaving around 1.3MB of flash for the blocklist. This allows the device to store up to 250,000 domains. To use the larger 537,000-domain blocklist, users need to switch to a single-app partition layout, which disables firmware OTA updates.

Web dashboard showing blocklist statistics, connected clients, Wi Fi signal strength, memory usage, and custom blocked domains (Image enhanced with AI)
What’s odd is the 40-bit width; the developer says it’s the optimal size for this flash budget. At 141k domains, collisions are near zero. Expanding the list to an aggressive 537k domains results in roughly one collision (one over-blocked domain). Dropping to a standard 32-bit hash would save flash space but cause around seven collisions at 250k domains.
The developer mentions that the project is inspired by s60sc’s ESP32_AdBlocker , but it is an independent implementation that uses flash memory instead of PSRAM to store large blocklists. You can use the same approach on more powerful chips. For example, a 16MB ESP32-S3 could store around 2.7 million domains using 40-bit hashes, compared to around 466,000 domains stored as strings in 8MB of PSRAM.
You can find the C++ source code, PlatformIO build instructions, and the 3D-printable case in the GitHub repository .
Debashis Das is a technical content writer and embedded engineer with over five years of experience in the industry. With expertise in Embedded C, PCB Design, and SEO optimization, he effectively blends difficult technical topics with clear communication