How tuhinpal/esp-dns-ad-blocker works
This MicroPython project turns an ESP32 or Pico W into a DNS ad blocker with a browser-based blocklist manager. At startup, the application connects to WiFi, loads the persistent domain list, creates both servers, and runs DNS, web, and periodic-maintenance loops concurrently. DNS requests are checked against the blocklist and cache before being forwarded upstream; the web interface lists, adds, and removes blocked domains. The excerpts show these core flows, but not detailed hardware behavior beyond the WiFi manager or any web use of its WiFi reference.
Main entry points: main.py Application Orchestrator · dns_socket.py DNS Request Handler · blocklist_manager.py Blocklist Manager · web_socket.py Web Interface
Components 11
Device Runtime
- Application Orchestrator
main.py - WiFi Connection
wifi_manager.py
DNS Service
- DNS Request Handler
dns_socket.py - DNS Cache
dns_socket.py
Blocklist Management
- Web Interface
web_socket.py - Blocklist Manager
blocklist_manager.py - Persistent Blocklist
blocklist.txt
Other components
- ESP Device
- DNS Clients
- Cloudflare DNS
- Browser User
Connections 13
- ESP Device → Application Orchestrator: runs
README.md - Application Orchestrator → WiFi Connection: connects
main.py - Application Orchestrator → Blocklist Manager: initializes
main.py - Application Orchestrator → DNS Request Handler: starts DNS loop
main.py - Application Orchestrator → Web Interface: starts web loop
main.py - Application Orchestrator → DNS Request Handler: schedules maintenance
main.py - DNS Clients → DNS Request Handler: sends queries
README.md - DNS Request Handler → Blocklist Manager: checks domain
dns_socket.py - DNS Request Handler → DNS Cache: checks and updates
dns_socket.py - DNS Request Handler → Cloudflare DNS: forwards query
dns_socket.py - Browser User → Web Interface: sends requests
README.md - Web Interface → Blocklist Manager: lists and edits
web_socket.py - Blocklist Manager → Persistent Blocklist: loads and saves
blocklist_manager.py