ESP32-C3 NetGuard is a lightweight, fast, and feature-rich parental control gateway and routing manager built expressly for the ESP32-C3 microcontroller.
NetGuard acts as an intercepting DNS gateway on your network, allowing administrators to group devices, define strict bedtimes, and conditionally route traffic using custom DNS protocols. It is bundled with a sleek, modern React Progressive Web App (PWA) interface, ensuring an intuitive management experience from any mobile device or desktop browser.
- Device Management: Automatically detect connected clients via DHCP intercepts and assign them friendly names for easy tracking.
- Access Profiles (Grouping): Organize devices into distinct profiles (e.g., "Kids", "Adults", "IoT").
- Scheduled Blocking (Bedtimes): Define exact start and end times for internet cutoffs on a per-profile basis.
- DNS Routing: Conditionally route specific profiles through custom upstream DNS servers for filtering or tracking.
- Secure Authentication: Locally authenticated dashboard ensures only network administrators can alter routing rules.
- Real-time Polling & PWA: The dashboard operates as an installable Progressive Web App, securely polling your ESP32 in the background to reflect network statistics, hardware temperatures, and access states dynamically.
When accessing the dashboard for the first time, authenticate using:
- Username:
admin - Password:
adminpass123
(Note: It is highly recommended to change this password in the Settings tab immediately after your first login.)
First-Time Installation (USB Only): Because the ESP32 chip requires the baseline web server and Over-The-Air (OTA) architecture to be present before accepting wireless updates, your very first installation must be conducted physically via a USB cable.
- Navigate to the Releases section on GitHub.
- Download the latest
firmware.binpayload. - Flash the
.binto your ESP32-C3 device using a standard serial flashing tool (e.g., Espressif's Flash Download Tools or esptool.py) over your COM port. - Power on the device, and look for the newly emitted C3NetGuard-Setup WiFi network on your phone or laptop.
- Connect to it, and a captive portal will appear (or visit
http://192.168.4.1) prompting you to securely designate your home WiFi network. - Once connected, visit
http://c3netguard.localin your browser to load the dashboard! - CRITICAL ROUTER SETUP: For NetGuard to actively intercept and manage your devices, you must log into your main home router's admin panel and change your primary DHCP DNS Server to point to the local IP address of your ESP32-C3. If you skip this step, devices on your network will naturally bypass the gateway!
Mobile Users (PWA) To manage NetGuard from your phone, navigate to https://sasa97a.github.io/ESP32_C3_NetGuard/ in your mobile browser. Do not use the dashboard directly in the browser. Instead, use your browser's menu to "Install" or "Add to Home Screen" to install it as a fully-functioning Progressive Web App (PWA).
Desktop Users
Navigate to the Releases page and download the dedicated desktop application tailored for your operating system (Windows .exe, macOS .dmg etc.).
- Note on Unsigned Apps: Because these application binaries are currently unsigned, your operating system (like Windows SmartScreen or macOS Gatekeeper) will likely flag them as an unknown publisher. You will need to explicitly click "More info" > "Run anyway" (Windows) or allow it through your security settings (Mac) to open the application.
Subsequent Updates (OTA):
Once NetGuard is running, all future version upgrades can be performed wirelessly! Simply download the newest .bin from GitHub, navigate to the Settings tab in your dashboard, and use the Flash Firmware upload tool.
- Note on OTA Reboots: Because the ESP32 physically drops its network connection to instantly hardware-reboot upon a successful flash, the dashboard may occasionally report a false "Connection Error" right at 100%. This is a known, harmless UI quirk. Simply wait a few moments and refresh the page to see your updated dashboard!
NetGuard allows you to apply different content filters to different profiles by supplying specific DNS IPs. While NetGuard manages when devices can connect, your upstream DNS selection dictates what they can safely access. Here are several popular, free options you can plug into your profiles:
- Cloudflare Families (Blocks Malware & Adult Content):
1.1.1.3 - AdGuard Family (Blocks Ads, Trackers & Adult Content):
94.140.14.15 - OpenDNS Family Shield (Blocks Adult Content):
208.67.222.123 - Standard Unfiltered (Best for unrestricted 'Adults' or 'IoT' profiles):
1.1.1.1(Cloudflare) or8.8.8.8(Google)
Single-Device Dashboard Access: The ESP32-C3 is a highly efficient but extremely localized microcontroller. It enforces a strict physical limit on concurrent TCP sockets. Because the React PWA acts as a live monitor and aggressively polls the gateway for status updates in the background, keeping the dashboard open on multiple devices simultaneously (e.g., your smartphone and your desktop) will rapidly exhaust the processor's connection pool.
- Best Practice: Keep the dashboard actively open on only one device at a time to prevent UI freezing and silent connection rejections.
If you wish to compile the firmware from source, this project relies on PlatformIO.
- Backend Compilation: Execute
pio run -e c3to compile the firmware. - Frontend Compilation: The dashboard interface is built using Vite and React. Navigate to the
frontend/directory and runnpm run devfor live compilation, ornpm run buildto package the static assets.
- External Links: Clicking external links (such as GitHub release URLs) inside the Tauri desktop wrapper does not currently break out into the host OS's default system browser.
- Firmware Flashing: The OTA firmware upload feature is currently restricted within the compiled Desktop versions due to strict file-bridging protocols. Please use the web dashboard via your mobile PWA app for OTA updates.
- Multiple Instances (Non-Singleton): Launching the Desktop application multiple times will generate duplicate floating windows rather than returning focus to the originally opened running instance.
Refer to the embedded LICENSE file (if applicable) for distribution rules.