Learn how to create an ad-blocker using ESP32-C3, including setup, handling blocklists, and securing your device.
The ESP32-C3 has emerged as a low-cost, powerful platform for developing productivity-with-artificial-intelligence-displays/">Internet of Things (IoT) applications. One of the more interesting applications is creating a Pi-hole-styled DNS ad-blocker using this microcontroller. This project allows users to eliminate annoying advertisements on their network efficiently without the need for expensive hardware.
The uniqueness of this ad-blocker lies in its engineering-practices/">resource management. Most ESP32 DNS sinkholes attempt to load their blocklists into the RAM, necessitating PSRAM. In contrast, this project stores the blocklists as sorted 40-bit hashes in the flash memory. This approach allows for high efficiency, enabling over 140,000 domains to fit into approximately 0.7 MB of flash while maintaining quick lookups at around 10 milliseconds, using only 50 KB of RAM.
The method uses the well-known FNV-1a hashing algorithm, extracting the domain and using parent suffixes to store it in the flash as a hash. This allows for a binary search in the flash hash table to verify if a domain is blocked, leading to a hit where a 0.0.0.0 response is returned or a miss that forwards to the upstream resolver. This differs from conventional methods, giving the ESP32-C3 an edge.
The project can run on any ESP32-C3 board, with a tested configuration available on the C3 SuperMini, which requires 4 MB of flash memory and no PSRAM. However, if users want to utilize the classic ESP32 (DevKit / WROOM), it is also compatible. Powering up the board can be conveniently managed using a stable USB source—be it a phone charger or a router's USB port. Caution is advised as cheap USB-C to A adapters may lead to a brownout, especially during WiFi transmission.
Additionally, users can use a simple USB-A to USB-C dongle to connect directly into a router's USB port, eliminating the need for extra supplies.
The ESP32-C3 SuperMini can be housed in a 3D-printed enclosure specifically designed for it. The STL file for the enclosure is available online, making it easy for enthusiasts to print their case. To get started, users will need a USB flash drive. The firmware and blocklist can later update via WiFi, preventing the need for repeated physical access.
To begin flashing the ESP32 with the ad-blocker code, users need to employ PlatformIO. To ensure successful installation and avoid obstacles with outdated versions, it is crucial to use a current version of PlatformIO, whether that is the integrated extension in Visual Studio Code or a pip-installed version.
As a note, erroneous installations from system packages, like the one available in apt, should be avoided due to compatibility issues with the firmware.
One of the major advantages of this setup is the ability to implement custom blocklists. The binary-hash format allows for an efficient lookup system that maintains performance even as the list grows. The system not only blocks domains but also their respective subdomains. However, it should be noted that certain DNS features such as regex or wildcards are not supported when using a DNS hash list.
The WiFi setup does not require the device to be re-flashed. In cases where the device cannot connect to the WiFi network, it will automatically start as an open access point, allowing users to join and configure their settings via a captive portal. After the initial setup, users can reconfigure the device to connect to new networks by utilizing a straightforward process on the dashboard.
Firmware updates and managing the blocklist can easily be done over-the-air (OTA), allowing users to upload new settings without hassle. However, the device does require two application slots, which can limit blocklist size if users prioritize OTA capabilities.
Securitizing your ESP32-C3 ad-blocker is essential, as the device can be accessed through plain HTTP. The project enforces basic HTTP authentication to maintain some level of control, but it is crucial for users to change the default credentials from "CHANGE_ME_WEB_PASSWORD" to secure custom passwords. Failing to do so can expose the device to unauthorized access, as anyone on the same network could reflash or manipulate its configuration.
For additional protection against CSRF attacks, specific headers are necessary to authenticate requests. This raises the security level against common threats and ensures that commands are performed by authorized users only.
Every innovative project encounters challenges. Some of the hard lessons include ensuring users are aware of security measures and the necessary setup protocols. Careful documentation and community support will help bridge knowledge gaps.
The potential growth of the project lies in expanding capabilities. As the user community grows, customizing features such as advanced logging, compatibility with more blocklist formats, or integration with smart home devices could open new avenues. Additionally, enhancing security protocols to better protect user data remains a priority as IoT devices proliferate.
The ESP32-C3 offers an exciting opportunity for DIY enthusiasts to step into the world of ad-blocking without requiring complicated setups or expensive hardware. Its combination of simplicity, efficiency, and cost-effectiveness makes it a great choice for those looking to gain better control over their internet experience while reducing unwanted advertisements.
As technology continues to evolve, solutions like the ESP32-C3 DNS ad-blocker pave the way for smarter networking devices that not only provide utility but promote better online experiences. Keeping an eye on future developments within the ESP32 community may provide new tools and techniques to enhance the efficiency and security of these systems.
What hardware do I need to build the ESP32-C3 ad-blocker?
You will need an ESP32-C3 board with at least 4 MB flash memory, a USB flash drive for initial setup, and a reliable power source such as a phone charger or a router's USB port.
How do I customize my blocklist?
The ad-blocker lets users easily implement custom blocklists by uploading them through the web dashboard, which utilizes the binary hashing method for efficient domain blocking.
Is my setup secure?
Security features such as basic HTTP authentication and headers to prevent CSRF attacks help secure the device. Nonetheless, changing default credentials and being aware of network vulnerabilities is crucial.