Complete Setup Guide

Step-by-step instructions to get your DNS-Mixer up and running, from ESP8266/ESP32 configuration to router and device setup.

Quick Start Overview

🔧

1. Setup ESP

Flash firmware and configure WiFi

📡

2. Configure Router

Set DNS-Mixer as network DNS

📱

3. Setup Devices

Configure individual devices

✅

4. Verify

Test DNS resolution

ESP8266/ESP32 Setup

Prerequisites

Hardware Required

  • ESP8266 or ESP32 board
  • SSD1306 OLED display (128x64)
  • Micro-USB cable
  • 3.3V power supply

Software Required

  • Python 3.x
  • esptool for flashing
  • mpy-cross compiler
  • Terminal/Command prompt

Network Requirements

  • WiFi network access
  • DHCP-enabled router
  • Available IP address
  • Internet connectivity

Hardware Wiring

Connect the SSD1306 OLED display to your ESP board:

OLED Pin ESP8266 Pin ESP32 Pin Description
VCC 3.3V 3.3V Power supply
GND GND GND Ground
SCL GPIO 5 (D1) GPIO 22 I2C Clock
SDA GPIO 4 (D2) GPIO 21 I2C Data
⚠️

Important Notes

  • Use 3.3V, not 5V power for the OLED display
  • Double-check pin connections before powering on
  • ESP32 may require different I2C pins depending on the board variant

Method 1: Automated Setup (Recommended)

1. Install Dependencies

# Create virtual environment python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install required tools pip install mpy-cross esptool

2. Clone and Build

git clone https://github.com/lily-osp/DNS-mixer.git cd dns-mixer make build-esp8266 # or make build-esp32

3. Configure WiFi

Edit the WiFi settings in code/main.py:

WIFI_SSID = "Your_WiFi_Name" WIFI_PASSWORD = "Your_WiFi_Password" STATIC_IP = "192.168.1.100" # Choose unused IP in your network

4. Flash to ESP

make PORT=/dev/ttyUSB0 flash
This method handles all dependencies automatically

Method 2: Manual Setup

1. Install MicroPython Firmware

# Download firmware from https://micropython.org/download/ # For ESP8266: esptool.py --chip esp8266 --port /dev/ttyUSB0 write_flash -z 0x0 esp8266-20220618-v1.19.1.bin # For ESP32: esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash -z 0x1000 esp32-20220618-v1.19.1.bin

2. Alternative: Thonny IDE

  1. Install Thonny IDE
  2. Open Thonny and connect to your ESP board
  3. Go to Tools → Options → Interpreter
  4. Select MicroPython (ESP8266/ESP32)
  5. Thonny will install the firmware automatically

3. Upload Code

# Using ampy pip install adafruit-ampy mpy-cross code/main.py ampy -p /dev/ttyUSB0 put code/main.mpy # Or using Thonny IDE # 1. Open code/main.py in Thonny # 2. Save directly to ESP device

Testing Your Setup

Expected Behavior

  • Boot Sequence: OLED shows "Connecting..." with progress animation
  • WiFi Connection: Display shows "WiFi Connected!" briefly
  • Ready State: Shows "DNS Server Ready" and IP address
  • DNS Requests: LED blinks and OLED shows processing status

Troubleshooting

WiFi Issues
  • Check SSID and password in code
  • Verify WiFi signal strength
  • Try different WiFi channels
OLED Issues
  • Verify I2C connections
  • Check 3.3V vs 5V power
  • Test different I2C pins

Router Configuration

Network-Wide DNS Setup

Configure your router to use DNS-Mixer for all devices on your network. This provides automatic protection for all connected devices.

Step 1: Find Router IP

Windows
ipconfig # Look for "Default Gateway"
macOS
System Preferences -> Network # Check "Router" field
Linux
ip route show # or check /etc/resolv.conf

Step 2: Access Router Admin

  1. Open browser and enter router IP (usually 192.168.1.1)
  2. Enter admin username/password (default: admin/admin)
  3. Navigate to DNS or Network settings

Step 3: Configure DNS

Router brand-specific instructions:

Router Brand Menu Path Setting
ASUS Advanced Settings → WAN → Internet Connection Set "DNS Server" to DNS-Mixer IP
TP-Link Network → WAN → Dynamic IP Set "Primary DNS" to DNS-Mixer IP
Netgear Advanced → Setup → Internet Setup Set "DNS Address" to DNS-Mixer IP
Generic DNS/Network Settings Set Primary DNS to DNS-Mixer IP
All devices on your network will now use DNS-Mixer automatically

Individual Device Configuration

Windows Configuration

Windows 10/11

  1. Right-click Start → Settings (⚙️)
  2. Network & Internet → Status
  3. Change adapter options
  4. Right-click network → Properties
  5. Internet Protocol Version 4 (TCP/IPv4) → Properties
  6. Select "Use the following DNS server addresses"
  7. Preferred DNS server: [DNS-Mixer IP]

Windows 7/8

  1. Control Panel → Network and Sharing Center
  2. Change adapter settings
  3. Right-click connection → Properties
  4. Internet Protocol Version 4 (TCP/IPv4) → Properties
  5. Select "Use the following DNS server addresses"
  6. Preferred DNS server: [DNS-Mixer IP]

Command Line (All Windows)

# Set DNS for WiFi netsh interface ipv4 set dns "Wi-Fi" static 192.168.1.100 # Set DNS for Ethernet netsh interface ipv4 set dns "Ethernet" static 192.168.1.100

macOS Configuration

macOS Monterey/Ventura/Sonoma

  1. System Settings → Network
  2. Select network connection
  3. Click Details... button
  4. Select DNS tab
  5. Click + to add DNS server
  6. Enter DNS-Mixer IP address

Older macOS Versions

  1. System Preferences → Network
  2. Select connection → Advanced...
  3. DNS tab → Click + button
  4. Enter DNS-Mixer IP address

Terminal Method

# Temporary change (resets on reboot) sudo bash -c 'echo "nameserver 192.168.1.100" > /etc/resolv.conf' # Using networksetup networksetup -setdnsservers Wi-Fi 192.168.1.100 networksetup -setdnsservers Ethernet 192.168.1.100

Linux Configuration

Ubuntu/Debian (Network Manager)

  1. Settings → Network
  2. Select connection → ⚙️ (settings)
  3. IPv4 tab → DNS section
  4. Set to Manual
  5. Enter DNS-Mixer IP

Ubuntu/Debian (Netplan)

# Edit /etc/netplan/01-netcfg.yaml network: version: 2 ethernets: eth0: dhcp4: true nameservers: addresses: [192.168.1.100] sudo netplan apply

Red Hat/CentOS/Fedora

sudo bash -c 'echo "nameserver 192.168.1.100" >> /etc/resolv.conf'

Mobile Devices

Android

  1. Settings → Network & internet → Wi-Fi
  2. Long-press your Wi-Fi network
  3. Modify network → Advanced options
  4. IP settings → Static
  5. Scroll to DNS 1
  6. Enter DNS-Mixer IP

iOS/iPadOS

  1. Settings → Wi-Fi
  2. Tap ⓘ next to your network
  3. Configure DNS → Manual
  4. Delete existing DNS servers
  5. Tap Add Server
  6. Enter DNS-Mixer IP

Gaming Consoles & Smart TVs

PlayStation 4/5

  1. Settings → Network → Settings
  2. Select connection → Advanced Settings
  3. IP Address Settings → Manual
  4. DNS → Manual
  5. Primary DNS: DNS-Mixer IP

Xbox One/Series X|S

  1. Settings → Network → Network settings
  2. Select network → Advanced settings
  3. DNS settings → Manual
  4. Primary DNS: DNS-Mixer IP

Smart TVs

  1. Settings → Network → Network Status
  2. Select network → IP Settings
  3. Set DNS to Manual
  4. Enter DNS-Mixer IP

Verification & Testing

Test DNS Resolution

Windows

nslookup google.com [DNS_MIXER_IP]

macOS/Linux

dig google.com @[DNS_MIXER_IP] # or nslookup google.com [DNS_MIXER_IP]

Web Browser

# Visit any website # Check if it loads successfully

Expected Results

  • DNS server responds from your DNS-Mixer IP
  • Domain resolution completes successfully
  • Websites load normally
  • OLED display shows DNS activity

OLED Display Verification

DNS-Mixer OLED Display

When working correctly, your DNS-Mixer OLED display should show real-time statistics similar to this demo image. The display updates automatically with each DNS request processed.

Test Bypass Functionality

Verify that DNS-Mixer can work around restrictions:

# Test with potentially restricted domains nslookup twitter.com [DNS_MIXER_IP] nslookup youtube.com [DNS_MIXER_IP] nslookup github.com [DNS_MIXER_IP] nslookup wikipedia.org [DNS_MIXER_IP]

Monitor the OLED display to see which DNS providers are being used for each query.

Performance Monitoring

Check OLED Statistics

The OLED display shows real-time statistics:

  • Total: Total DNS requests processed
  • Success: Successfully resolved queries
  • Failed: Queries that failed all providers

Expected Performance

  • DNS resolution: 50-200ms average
  • Success rate: 99.5%+
  • LED activity: Blinks on each request
  • OLED updates: Real-time status changes

Next Steps

Explore Use Cases Technical Details Back to Home

Getting Help

If you encounter issues during setup: