{"id":21009733,"url":"https://github.com/lily-osp/dns-mixer","last_synced_at":"2026-04-12T18:15:06.311Z","repository":{"id":218603896,"uuid":"746890074","full_name":"lily-osp/DNS-mixer","owner":"lily-osp","description":"Turn your ESP32/8266 into a DNS mixer to provide dynamic DNS resolution using multiple DNS servers","archived":false,"fork":false,"pushed_at":"2024-01-27T08:59:40.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"mas","last_synced_at":"2025-01-20T11:11:55.263Z","etag":null,"topics":["dns-server","esp32","esp8266","internet-positif","micropython"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lily-osp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-22T21:47:42.000Z","updated_at":"2024-08-21T10:56:12.000Z","dependencies_parsed_at":"2024-08-21T15:31:10.836Z","dependency_job_id":"5987aca3-0183-4bde-8b3c-8f06a0f787d0","html_url":"https://github.com/lily-osp/DNS-mixer","commit_stats":null,"previous_names":["1999azzar/esp32-dns-mixer","lily-osp/dns-mixer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lily-osp%2FDNS-mixer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lily-osp%2FDNS-mixer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lily-osp%2FDNS-mixer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lily-osp%2FDNS-mixer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lily-osp","download_url":"https://codeload.github.com/lily-osp/DNS-mixer/tar.gz/refs/heads/mas","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243431487,"owners_count":20289900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dns-server","esp32","esp8266","internet-positif","micropython"],"created_at":"2024-11-19T09:17:46.881Z","updated_at":"2025-12-25T18:43:19.298Z","avatar_url":"https://github.com/lily-osp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DNS Mixer\n\nWelcome to DNS-mixer! This is a MicroPython-based DNS forwarding service for ESP8266/ESP32 devices with OLED display support. The service handles DNS requests and forwards them to multiple DNS providers, ensuring reliability and redundancy in DNS resolution.\n\n\u003e **Quick Start**: New users should start with the [setup guides](setup/README.md) for comprehensive installation and configuration instructions.\n\n## Table of Contents\n\n1. [Introduction](#introduction)\n2. [Requirements](#requirements)\n3. [Hardware Setup](#hardware-setup)\n4. [Configuration](#configuration)\n   - [WiFi Configuration](#wifi-configuration)\n   - [DNS Providers](#dns-providers)\n5. [Building and Flashing](#building-and-flashing)\n6. [Usage](#usage)\n7. [Troubleshooting](#troubleshooting)\n8. [Contributing](#contributing)\n9. [License](#license)\n\n## Introduction\n\nDNS-mixer is a MicroPython-based DNS resolver for ESP8266/ESP32 devices that intelligently routes DNS queries through multiple DNS providers to bypass restrictions and ensure reliable name resolution. The device acts as a DNS server on your network, providing redundancy and failover capabilities.\n\n### Key Features\n\n- **Multi-Provider Failover**: Cycles through 9+ DNS providers (Quad9, Cloudflare, Google DNS, etc.) for maximum reliability\n- **Load Balancing**: Randomizes provider order to distribute load and avoid single points of failure\n- **Restriction Bypass**: Works around DNS blocking by trying multiple providers until one succeeds\n- **Router Integration**: Configure as DNS server in router settings for network-wide protection\n- **Enhanced OLED Display**: Real-time animated status messages, progress bars, and detailed processing feedback\n- **Visual Status System**: Animated connection progress, processing spinners, and success/failure indicators\n- **Low Resource Usage**: Optimized for ESP8266/ESP32 with minimal memory footprint\n\n## Requirements\n\n- ESP8266 or ESP32 development board\n- SSD1306 OLED display (128x64, I2C)\n- MicroPython firmware installed on the device\n- Network connectivity between the ESP device and client devices\n\n## Hardware Setup\n\n### OLED Display Connection\n\n- SDA: GPIO 4 (D2 on ESP8266)\n- SCL: GPIO 5 (D1 on ESP8266)\n- VCC: 3.3V\n- GND: GND\n\n\u003e **Detailed Setup Guide**: See [setup/server.md](setup/server.md) for comprehensive hardware setup instructions, wiring diagrams, and both automated and manual installation methods.\n\n### ESP32 vs ESP8266 Comparison\n\n| Feature                           | ESP8266                      | ESP32                                  |\n| --------------------------------- | ---------------------------- | -------------------------------------- |\n| **Processor**               | 32-bit RISC (80 MHz)         | Dual-core 32-bit (160-240 MHz)         |\n| **RAM**                     | 80 KB                        | 520 KB                                 |\n| **Flash**                   | External (up to 16 MB)       | External (up to 16 MB)                 |\n| **WiFi**                    | 802.11 b/g/n (2.4 GHz only)  | 802.11 b/g/n (2.4 GHz) + Bluetooth 4.2 |\n| **GPIO Pins**               | 17                           | 34                                     |\n| **ADC Channels**            | 1 (10-bit)                   | 18 (12-bit)                            |\n| **PWM Channels**            | 4                            | 16                                     |\n| **I2C**                     | 1                            | 2                                      |\n| **SPI**                     | 1                            | 4                                      |\n| **UART**                    | 1                            | 3                                      |\n| **Power Consumption**       | Lower                        | Higher                                 |\n| **Cost**                    | cheaper                      | more expensive                         |\n| **MicroPython Performance** | Good for simple tasks        | Better for complex applications        |\n| **DNS-mixer Suitability**   | Excellent (simpler, cheaper) | Excellent (more powerful, faster)      |\n\n**Recommendation**: Use ESP8266 for cost-effective deployments. Use ESP32 for more demanding applications or when you need Bluetooth connectivity.\n\n## Configuration\n\n### WiFi Configuration\n\nEdit the WiFi settings in `code/main.py` to match your network credentials:\n\n```python\nWIFI_SSID = \"your_wifi_ssid\"\nWIFI_PASSWORD = \"your_wifi_password\"\nSTATIC_IP = \"192.168.1.100\"  # Choose an available IP in your network\n```\n\n### DNS Providers\n\nThe device includes 9 pre-configured DNS providers optimized for reliability and restriction bypass:\n\n```python\nDNS_PROVIDERS_IPV4 = [\n    \"9.9.9.9\",        # Quad9 (Malware blocking)\n    \"1.1.1.1\",        # Cloudflare (Fast, privacy-focused)\n    \"8.8.8.8\",        # Google DNS (Widely accessible)\n    \"94.140.14.14\",   # AdGuard DNS (Ad blocking)\n    \"76.76.19.19\",    # Alternate DNS (Uncensored)\n    \"76.76.2.0\",      # Control D (Uncensored)\n    \"185.228.168.9\",  # CleanBrowsing (Security)\n    \"208.67.222.222\", # OpenDNS (Reliable)\n    \"80.80.80.80\"     # Freenom (Alternative)\n]\n```\n\n**Provider Benefits for Bypass:**\n\n- **Multiple Countries**: Providers from different jurisdictions reduce blocking likelihood\n- **Privacy-Focused**: Quad9, Cloudflare offer enhanced privacy\n- **Uncensored Options**: Alternate DNS, Control D provide unrestricted access\n- **Failover Speed**: 50ms timeout ensures quick switching between providers\n\n\u003e **Advanced Configuration**: For detailed configuration options, custom DNS providers, and advanced settings, see [setup/server.md](setup/server.md#configuration).\n\n## Building and Flashing\n\n### Quick Start (Recommended)\n\nUse the provided Makefile for easy building:\n\n```bash\n# Install build dependencies\nmake install-deps\n\n# Build for both ESP8266 and ESP32 (default)\nmake build\n\n# Or build for specific target\nmake build-esp8266\nmake build-esp32\n```\n\n### Using Build Script\n\nThe project includes automated build scripts for both boards:\n\n```bash\n# Build for ESP8266\n./build.sh esp8266\n\n# Build for ESP32\n./build.sh esp32\n```\n\n### Manual Build\n\n1. Install dependencies:\n\n```bash\npip install mpy-cross esptool\n```\n\n2. Compile the main script:\n\n```bash\nmpy-cross code/main.py\n```\n\n### Flashing to Device\n\nAfter building, use the deployment script or flash manually:\n\n```bash\n# Using the deployment script (recommended)\ncd build \u0026\u0026 ./deploy.sh /dev/ttyUSB0 esp8266\n\n# Or using make (after building)\nmake PORT=/dev/ttyUSB0 flash\n\n# Manual flashing with esptool\nesptool.py --port /dev/ttyUSB0 --baud 115200 write_flash --flash_size=detect 0 esp8266-firmware.bin\nesptool.py --port /dev/ttyUSB0 --baud 115200 --after no_reset write_flash --flash_size=detect 0x100000 build/main.mpy\n```\n\n### Automated Builds\n\nThe project includes GitHub Actions workflows for automated building:\n\n- **Development builds**: Trigger on every push to main/master branch\n- **Release builds**: Trigger on version tags (v*) and create GitHub releases with firmware archives\n\n\u003e **Complete Flashing Guide**: For detailed flashing instructions, troubleshooting, and alternative methods (including Thonny IDE), see [setup/server.md](setup/server.md#flashing-and-testing).\n\n## Usage\n\n### Basic Operation\n\nThe device will automatically:\n\n1. Connect to the configured WiFi network\n2. Start the DNS server on port 53\n3. Display connection status and statistics on the OLED screen\n4. Forward DNS requests to configured providers with failover\n\n### Router Configuration for Network-Wide DNS\n\nTo use DNS-mixer network-wide, configure your router to use it as the DNS server:\n\n#### 1. Access Router Admin Panel\n\n- Open browser and go to your router's IP (usually 192.168.1.1 or 192.168.0.1)\n- Login with admin credentials\n\n#### 2. Configure DNS Settings\n\nLook for DNS settings in:\n\n- **Network Settings \u003e DHCP Settings**\n- **Advanced \u003e Network \u003e DNS**\n- **WAN Settings \u003e DNS Configuration**\n\nSet the **Primary DNS** to your DNS-mixer's IP address (default: `192.168.8.180`)\n\n\u003e **Router Setup Guide**: For detailed router configuration instructions for ASUS, TP-Link, Netgear, and other brands, see [setup/otherdevices.md](setup/otherdevices.md#router-configuration-network-wide).\n\n#### 3. Alternative: Device-Level Configuration\n\nConfigure individual devices to use DNS-mixer:\n\n- **Windows**: Network Settings \u003e Change adapter options \u003e Properties \u003e IPv4 \u003e DNS server\n- **macOS**: System Preferences \u003e Network \u003e Advanced \u003e DNS\n- **Linux**: Edit `/etc/resolv.conf` or network manager\n- **Mobile**: WiFi settings \u003e Modify network \u003e Advanced \u003e DNS\n\n\u003e **Device Configuration Guide**: For step-by-step instructions for Windows, macOS, Linux, mobile devices, gaming consoles, and smart TVs, see [setup/otherdevices.md](setup/otherdevices.md).\n\n### Bypassing Restrictions\n\nDNS-mixer helps bypass DNS-based restrictions by:\n\n1. **Provider Failover**: If one DNS provider is blocked, it automatically tries others\n2. **Load Balancing**: Distributes requests across providers to avoid detection\n3. **Fast Switching**: 50ms timeout ensures quick fallback to working providers\n4. **Multiple Providers**: 9+ providers including international ones (Quad9, Cloudflare, Google, AdGuard, etc.)\n\n### OLED Display Status\n\nThe OLED display provides real-time visual feedback with detailed status messages and animations:\n\n#### **Connection Phase**\n\n- **\"Connecting...\"** - Animated dots showing connection progress\n- **\"WiFi Connected!\"** - Confirmation of successful WiFi connection\n- **\"DNS Server Ready\"** - Device ready to handle requests\n\n#### **Active Processing**\n\n- **\"Processing|\"** - Animated spinner (|, /, -, \\) during DNS resolution\n- **Provider name** - Shows which DNS provider is being tried\n- **\"Resolution OK\"** - Success confirmation with provider name\n- **\"Resolution Failed\"** - Error message when all providers fail\n\n#### **Statistics View**\n\n- **Total requests** - Cumulative DNS requests processed\n- **Success count** - Successful resolutions\n- **Failed count** - Unsuccessful attempts\n\n\u003e **📸 Demo Image**: See [demo.jpg](docs/images/demo.jpg) for a real photo of the OLED display showing live statistics.\n\n#### **Animations \u0026 Transitions**\n\n- **Progress bars** - Visual progress during connection\n- **Spinner animations** - Processing indicators\n- **Status transitions** - Smooth changes between states\n- **Auto-cycling** - Statistics display every few seconds of inactivity\n\n### LED Indicators\n\n- **5 blinks**: Device connected to WiFi\n- **1 short blink**: DNS request received\n- **1 very short blink**: DNS resolution successful\n- **1 long blink**: DNS resolution failed (all providers unreachable)\n\n## Troubleshooting\n\n\u003e **Detailed Troubleshooting**: For comprehensive troubleshooting guides including hardware issues, WiFi problems, DNS resolution failures, and device-specific problems, see:\n\u003e\n\u003e - [setup/server.md](setup/server.md#troubleshooting) - ESP device setup issues\n\u003e - [setup/otherdevices.md](setup/otherdevices.md#troubleshooting) - Client device configuration problems\n\n### Quick Troubleshooting Tips\n\nIf you encounter issues:\n\n- Verify OLED display shows connection status and IP address\n- Check LED indicators for error patterns\n- Test DNS resolution with `nslookup google.com [DNS_MIXER_IP]`\n- Ensure DNS-mixer IP is in your router's subnet\n- Monitor serial output for error messages\n\n## Contributing\n\nFeel free to contribute to this project by submitting issues or pull requests. Your feedback and improvements are highly appreciated.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flily-osp%2Fdns-mixer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flily-osp%2Fdns-mixer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flily-osp%2Fdns-mixer/lists"}