// C3 AdBlock — DNS sinkhole + web dashboard for the ESP32-C3 (no PSRAM). // Blocklist = sorted 40-bit FNV-1a hashes in flash, binary-searched. // Dashboard at http://c3adblock.local : per-client stats, system info, // ban clients, add custom block domains. All control state persisted to flash. #include #include #include // WiFi event debugging #include #include #include #include #include #include // firmware OTA #include // remote blocklist fetch #include // https fetch #include // network firmware flashing (pio run over wifi) #include // captive portal #include "lwip/etharp.h" #include "lwip/netif.h" #include "secrets.h" // defines WIFI_SSID / WIFI_PASS — copy secrets.example.h and fill in // ---- config ---- static const IPAddress UPSTREAM(9, 9, 9, 9); // Quad9 static const uint16_t DNS_PORT = 53; static const char* BLOCKLIST_PATH = "/blocklist.bin"; static const int HASH_BYTES = 5; static const uint64_t HASH_MASK = (1ULL << (HASH_BYTES * 8)) - 1; // ---- globals ---- WiFiUDP dnsServer, upstreamCli; DNSServer dnsCaptive; WebServer web(80); File blocklist; uint32_t numHashes = 0, totalBlocked = 0, totalAllowed = 0; uint8_t buf[1500]; bool apMode = false; // true when running as setup AP static const char* WIFI_CREDS_PATH = "/wifi.txt"; struct Dev { uint32_t ip; uint8_t mac[6]; uint32_t blocked, allowed, lastSeen; bool banned; String label; }; static const int MAX_CLIENTS = 96; Dev clients[MAX_CLIENTS]; int numClients = 0; static const int MAX_CUSTOM = 200; String customDom[MAX_CUSTOM]; uint64_t customHash[MAX_CUSTOM]; int numCustom = 0; static const int MAX_BAN = 32; uint32_t bannedIP[MAX_BAN]; int numBanned = 0; // remote blocklist auto-update String updateUrl = ""; // URL of a prebuilt blocklist.bin (e.g. GitHub release asset) uint32_t updateIntervalH = 24; // hours between auto-fetches uint32_t lastCheckMs = 0; String updateStatus = "never"; // ---------- hashing / matching ---------- static uint64_t fnv40(const char* s, size_t n) { uint64_t h = 0xcbf29ce484222325ULL; for (size_t i = 0; i < n; i++) { h ^= (uint8_t)s[i]; h *= 0x100000001b3ULL; } return h & HASH_MASK; } static bool inFlash(uint64_t h) { int32_t lo = 0, hi = (int32_t)numHashes - 1; uint8_t b[HASH_BYTES]; while (lo <= hi) { int32_t mid = (lo + hi) >> 1; blocklist.seek((uint32_t)mid * HASH_BYTES); blocklist.read(b, HASH_BYTES); uint64_t v = 0; for (int k = 0; k < HASH_BYTES; k++) v |= (uint64_t)b[k] << (8 * k); if (v < h) lo = mid + 1; else if (v > h) hi = mid - 1; else return true; } return false; } static bool inCustom(uint64_t h) { for (int i = 0; i < numCustom; i++) if (customHash[i] == h) return true; return false; } static bool isBlocked(const char* domain) { const char* p = domain; while (p && *p) { uint64_t h = fnv40(p, strlen(p)); if (inFlash(h) || inCustom(h)) return true; const char* dot = strchr(p, '.'); if (!dot) break; const char* next = dot + 1; if (!strchr(next, '.')) break; p = next; } return false; } // ---------- persistence ---------- static void loadCustom() { numCustom = 0; File f = LittleFS.open("/custom.txt", "r"); if (!f) return; while (f.available() && numCustom < MAX_CUSTOM) { String l = f.readStringUntil('\n'); l.trim(); l.toLowerCase(); if (l.length() && l.indexOf('.') > 0) { customDom[numCustom] = l; customHash[numCustom] = fnv40(l.c_str(), l.length()); numCustom++; } } f.close(); } static void saveCustom() { File f = LittleFS.open("/custom.txt", "w"); if (!f) return; for (int i = 0; i < numCustom; i++) f.println(customDom[i]); f.close(); } static bool addCustom(String d) { d.trim(); d.toLowerCase(); if (d.startsWith("www.")) d = d.substring(4); if (!d.length() || d.indexOf('.') < 0 || numCustom >= MAX_CUSTOM) return false; for (int i = 0; i < numCustom; i++) if (customDom[i] == d) return false; customDom[numCustom] = d; customHash[numCustom] = fnv40(d.c_str(), d.length()); numCustom++; saveCustom(); return true; } static void removeCustom(String d) { d.toLowerCase(); for (int i = 0; i < numCustom; i++) if (customDom[i] == d) { for (int j = i; j < numCustom - 1; j++) { customDom[j] = customDom[j+1]; customHash[j] = customHash[j+1]; } numCustom--; saveCustom(); return; } } static bool isBannedIP(uint32_t ip) { for (int i = 0; i < numBanned; i++) if (bannedIP[i] == ip) return true; return false; } static void loadBanned() { numBanned = 0; File f = LittleFS.open("/banned.txt", "r"); if (!f) return; while (f.available() && numBanned < MAX_BAN) { String l = f.readStringUntil('\n'); l.trim(); IPAddress ip; if (l.length() && ip.fromString(l)) bannedIP[numBanned++] = (uint32_t)ip; } f.close(); } static void saveBanned() { numBanned = 0; for (int i = 0; i < numClients && numBanned < MAX_BAN; i++) if (clients[i].banned) bannedIP[numBanned++] = clients[i].ip; File f = LittleFS.open("/banned.txt", "w"); if (!f) return; for (int i = 0; i < numBanned; i++) { IPAddress ip(bannedIP[i]); f.println(ip.toString()); } f.close(); } // ---------- WiFi credential persistence ---------- static bool loadWiFiCreds(String& ssid, String& pass) { File f = LittleFS.open(WIFI_CREDS_PATH, "r"); if (!f) return false; ssid = f.readStringUntil('\n'); ssid.trim(); pass = f.readStringUntil('\n'); pass.trim(); f.close(); return ssid.length() > 0; } static void saveWiFiCreds(const String& ssid, const String& pass) { File f = LittleFS.open(WIFI_CREDS_PATH, "w"); if (!f) return; f.println(ssid); f.println(pass); f.close(); } static void clearWiFiCreds() { LittleFS.remove(WIFI_CREDS_PATH); } // ---------- client table ---------- static void getMac(uint32_t ip, uint8_t* mac) { memset(mac, 0, 6); ip4_addr_t ipa; ipa.addr = ip; struct eth_addr* eth = nullptr; const ip4_addr_t* ipret = nullptr; for (struct netif* nif = netif_list; nif; nif = nif->next) if (etharp_find_addr(nif, &ipa, ð, &ipret) >= 0 && eth) { memcpy(mac, eth->addr, 6); return; } } static Dev* getClient(uint32_t ip) { for (int i = 0; i < numClients; i++) if (clients[i].ip == ip) { clients[i].lastSeen = millis(); return &clients[i]; } if (numClients < MAX_CLIENTS) { Dev* c = &clients[numClients++]; c->ip = ip; c->blocked = c->allowed = 0; c->lastSeen = millis(); c->banned = isBannedIP(ip); c->label = ""; getMac(ip, c->mac); return c; } return nullptr; } // ---------- DNS ---------- static size_t parseQuery(const uint8_t* pkt, int len, char* out, uint16_t* qtype, int* qend) { if (len < 13) return 0; int i = 12; size_t o = 0; while (i < len) { uint8_t l = pkt[i++]; if (l == 0) break; if (l & 0xC0) return 0; if (o + l + 1 >= 250 || i + l > len) return 0; if (o) out[o++] = '.'; for (uint8_t k = 0; k < l; k++) out[o++] = tolower(pkt[i++]); } out[o] = 0; if (i + 4 > len) return 0; *qtype = (pkt[i] << 8) | pkt[i + 1]; *qend = i + 4; if (o > 4 && strncmp(out, "www.", 4) == 0) { memmove(out, out + 4, o - 3); o -= 4; } return o; } static int buildBlocked(int qend, uint16_t qtype) { buf[2] = 0x81; buf[3] = 0x80; buf[6] = 0; buf[7] = (qtype == 1) ? 1 : 0; buf[8] = 0; buf[9] = 0; buf[10] = 0; buf[11] = 0; if (qtype != 1) return qend; const uint8_t ans[] = {0xC0,0x0C, 0,1, 0,1, 0,0,1,0x2C, 0,4, 0,0,0,0}; memcpy(buf + qend, ans, sizeof(ans)); return qend + sizeof(ans); } static int forwardUpstream(int qlen) { upstreamCli.beginPacket(UPSTREAM, 53); upstreamCli.write(buf, qlen); upstreamCli.endPacket(); uint32_t t0 = millis(); while (millis() - t0 < 1000) { int sz = upstreamCli.parsePacket(); if (sz > 0) return upstreamCli.read(buf, sizeof(buf)); delay(1); } return 0; } static bool dnsOk = true; static void handleDns() { if (!dnsOk) { dnsServer.stop(); dnsServer.begin(DNS_PORT); upstreamCli.stop(); upstreamCli.begin(0); dnsOk = true; return; } // process up to 8 queries per tick — keeps up with multi-device flood for (int batch = 0; batch < 8; batch++) { int sz = dnsServer.parsePacket(); if (sz < 0) { dnsOk = false; return; } if (sz == 0) return; IPAddress cip = dnsServer.remoteIP(); uint16_t cport = dnsServer.remotePort(); int qlen = dnsServer.read(buf, sizeof(buf)); if (qlen < 13) continue; char domain[256]; uint16_t qtype = 0; int qend = qlen; size_t dl = parseQuery(buf, qlen, domain, &qtype, &qend); Dev* c = getClient((uint32_t)cip); bool ban = c && c->banned; bool blocked = ban || (dl && numHashes && isBlocked(domain)); int rlen; if (blocked) { rlen = buildBlocked(qend, qtype); totalBlocked++; if (c) c->blocked++; } else { rlen = forwardUpstream(qlen); totalAllowed++; if (c) c->allowed++; } if (rlen > 0) { dnsServer.beginPacket(cip, cport); dnsServer.write(buf, rlen); dnsServer.endPacket(); } } } // ---------- web ---------- static String macStr(const uint8_t* m) { char s[18]; snprintf(s, sizeof(s), "%02x:%02x:%02x:%02x:%02x:%02x", m[0],m[1],m[2],m[3],m[4],m[5]); return String(s); } static String jesc(const String& s) { String o; for (char ch : s) { if (ch == '"' || ch == '\\') o += '\\'; o += ch; } return o; } // ---- captive portal (AP mode) ---- const char PAGE_AP[] PROGMEM = R"HTML( C3 AdBlock Setup

🛡️ C3 AdBlock Setup

Select your WiFi network to get started.

enter SSID manually
)HTML"; const char PAGE[] PROGMEM = R"HTML( C3 AdBlock

🛡️ C3 AdBlock

CLIENTS

ClientMACBlockedAllowed

CUSTOM BLOCKED DOMAINS

BLOCKLIST — UPLOAD

build blocklist.bin with tools/build_blocklist.py, then upload here — no USB

BLOCKLIST — REMOTE AUTO-UPDATE

every h
device pulls a prebuilt blocklist.bin on a schedule (e.g. a GitHub release asset). last: —

FIRMWARE — OTA UPDATE

upload .pio/build/c3/firmware.bin — device verifies it and reboots into it
)HTML"; static void handleStats() { uint32_t up = millis() / 1000; char ut[24]; snprintf(ut, sizeof(ut), "%lud %luh %lum", up/86400, (up%86400)/3600, (up%3600)/60); String j = "{\"ip\":\"" + WiFi.localIP().toString() + "\",\"blocked\":" + totalBlocked + ",\"allowed\":" + totalAllowed + ",\"domains\":" + numHashes + ",\"rssi\":" + WiFi.RSSI() + ",\"temp\":" + String(temperatureRead(), 1) + ",\"heap\":" + ESP.getFreeHeap() + ",\"uptime\":\"" + ut + "\"" + ",\"upurl\":\"" + jesc(updateUrl) + "\",\"upiv\":" + updateIntervalH + ",\"upstat\":\"" + jesc(updateStatus) + "\"" + ",\"clients\":["; for (int i = 0; i < numClients; i++) { Dev& c = clients[i]; IPAddress ip(c.ip); j += (i ? "," : ""); j += "{\"ip\":\"" + ip.toString() + "\",\"mac\":\"" + macStr(c.mac) + "\",\"blocked\":" + c.blocked + ",\"allowed\":" + c.allowed + ",\"banned\":" + (c.banned?"true":"false") + "}"; } j += "],\"custom\":["; for (int i = 0; i < numCustom; i++) { j += (i ? "," : ""); j += "\"" + jesc(customDom[i]) + "\""; } j += "]}"; web.send(200, "application/json", j); } static void handleBan() { IPAddress ip; if (ip.fromString(web.arg("ip"))) { Dev* c = getClient((uint32_t)ip); if (c) { c->banned = !c->banned; saveBanned(); } } web.send(200, "text/plain", "ok"); } // ---------- blocklist swap (shared by upload + remote fetch) ---------- // The partition holds one list, so we free the old one before writing the new. // While swapping, numHashes=0 -> device fail-opens (forwards, no blocking). static void reopenBlocklist() { blocklist = LittleFS.open(BLOCKLIST_PATH, "r"); numHashes = blocklist ? blocklist.size() / HASH_BYTES : 0; } static void beginBlocklistSwap() { if (blocklist) blocklist.close(); numHashes = 0; LittleFS.remove(BLOCKLIST_PATH); LittleFS.remove("/blocklist.new"); } static bool commitNewBlocklist() { // /blocklist.new -> live (validated) File f = LittleFS.open("/blocklist.new", "r"); size_t sz = f ? f.size() : 0; if (f) f.close(); bool ok = sz > 0 && (sz % HASH_BYTES) == 0; // sorted hash blob -> 5-byte multiple if (ok) LittleFS.rename("/blocklist.new", BLOCKLIST_PATH); else LittleFS.remove("/blocklist.new"); reopenBlocklist(); return ok; } // ---------- OTA blocklist update (browser upload) ---------- static bool upOk = false; static File upFile; static void handleUploadDone() { web.send(upOk ? 200 : 500, "text/plain", upOk ? "ok" : "rejected: empty or size not a multiple of 5 (not a blocklist.bin?)"); } static void handleUpload() { HTTPUpload& u = web.upload(); switch (u.status) { case UPLOAD_FILE_START: upOk = false; beginBlocklistSwap(); upFile = LittleFS.open("/blocklist.new", "w"); Serial.printf("[ota] receiving %s\n", u.filename.c_str()); break; case UPLOAD_FILE_WRITE: if (upFile) upFile.write(u.buf, u.currentSize); break; case UPLOAD_FILE_END: if (upFile) upFile.close(); upOk = commitNewBlocklist(); Serial.printf("[ota] %s -> %u domains\n", upOk ? "OK" : "REJECTED", numHashes); break; case UPLOAD_FILE_ABORTED: if (upFile) upFile.close(); LittleFS.remove("/blocklist.new"); reopenBlocklist(); Serial.println("[ota] aborted"); break; } } // ---------- remote blocklist auto-update ---------- static void loadUpdateCfg() { File f = LittleFS.open("/update.cfg", "r"); if (!f) return; updateUrl = f.readStringUntil('\n'); updateUrl.trim(); String iv = f.readStringUntil('\n'); iv.trim(); if (iv.length()) updateIntervalH = iv.toInt(); f.close(); if (updateIntervalH < 1) updateIntervalH = 1; } static void saveUpdateCfg() { File f = LittleFS.open("/update.cfg", "w"); if (!f) return; f.println(updateUrl); f.println(updateIntervalH); f.close(); } static bool fetchBlocklist(String url) { url.trim(); if (!url.length()) { updateStatus = "no url set"; return false; } Serial.printf("[remote] GET %s\n", url.c_str()); WiFiClientSecure cs; cs.setInsecure(); // blocklist isn't secret -> skip cert pinning WiFiClient cl; HTTPClient http; http.setTimeout(20000); http.setFollowRedirects(HTTPC_STRICT_FOLLOW_REDIRECTS); // GitHub release -> CDN redirect bool https = url.startsWith("https"); if (!(https ? http.begin(cs, url) : http.begin(cl, url))) { updateStatus = "begin failed"; return false; } int code = http.GET(); if (code != HTTP_CODE_OK) { http.end(); updateStatus = "HTTP " + String(code); Serial.printf("[remote] %s\n", updateStatus.c_str()); return false; } beginBlocklistSwap(); File f = LittleFS.open("/blocklist.new", "w"); if (!f) { http.end(); updateStatus = "fs open failed"; reopenBlocklist(); return false; } WiFiClient* stream = http.getStreamPtr(); int len = http.getSize(); uint8_t b[1024]; size_t total = 0; uint32_t idle = millis(); while (http.connected() && (len < 0 || (int)total < len)) { size_t avail = stream->available(); if (avail) { int n = stream->readBytes(b, avail > sizeof(b) ? sizeof(b) : avail); if (n > 0) { f.write(b, n); total += n; idle = millis(); } } else { if (millis() - idle > 15000) break; delay(2); } } f.close(); http.end(); bool ok = commitNewBlocklist(); updateStatus = ok ? ("ok: " + String(numHashes) + " domains") : ("bad data (" + String(total) + "B)"); Serial.printf("[remote] %s\n", updateStatus.c_str()); return ok; } // ---------- firmware OTA (browser upload of firmware.bin -> reboot) ---------- static void handleFwUpdateDone() { bool ok = !Update.hasError(); web.send(ok ? 200 : 500, "text/plain", ok ? "ok, rebooting" : "firmware update failed"); if (ok) { delay(300); ESP.restart(); } } static void handleFwUpload() { HTTPUpload& u = web.upload(); if (u.status == UPLOAD_FILE_START) { Serial.printf("[fw-ota] %s\n", u.filename.c_str()); if (!Update.begin(UPDATE_SIZE_UNKNOWN)) Update.printError(Serial); } else if (u.status == UPLOAD_FILE_WRITE) { if (Update.write(u.buf, u.currentSize) != u.currentSize) Update.printError(Serial); } else if (u.status == UPLOAD_FILE_END) { if (Update.end(true)) Serial.printf("[fw-ota] %u bytes OK\n", u.totalSize); else Update.printError(Serial); } else if (u.status == UPLOAD_FILE_ABORTED) { Update.abort(); Serial.println("[fw-ota] aborted"); } } void setup() { Serial.begin(115200); delay(300); Serial.println("\n[c3-adblock] booting"); if (!LittleFS.begin(true)) Serial.println("LittleFS FAILED"); blocklist = LittleFS.open(BLOCKLIST_PATH, "r"); if (blocklist) { numHashes = blocklist.size() / HASH_BYTES; Serial.printf("blocklist: %u domains\n", numHashes); } loadCustom(); loadBanned(); loadUpdateCfg(); Serial.printf("custom: %d, banned: %d\n", numCustom, numBanned); // ---- WiFi: saved creds > secrets.h > AP mode ---- String staSSID, staPass; bool haveCreds = loadWiFiCreds(staSSID, staPass); // try LittleFS first if (!haveCreds && strlen(WIFI_SSID) > 0) { // fall back to secrets.h staSSID = WIFI_SSID; staPass = WIFI_PASS; haveCreds = true; } if (haveCreds) { // ---- WiFi event debugging (Arduino API) ---- WiFi.onEvent([](WiFiEvent_t event, WiFiEventInfo_t info) { Serial.printf("[wifi] disconnect reason=%d\n", info.wifi_sta_disconnected.reason); }, ARDUINO_EVENT_WIFI_STA_DISCONNECTED); WiFi.mode(WIFI_STA); WiFi.setSleep(false); // TX power + protocol fixes for Asus routers esp_wifi_set_max_tx_power(84); // 21 dBm esp_wifi_set_bandwidth(WIFI_IF_STA, WIFI_BW_HT20); wifi_config_t conf; esp_wifi_get_config(WIFI_IF_STA, &conf); conf.sta.pmf_cfg.capable = false; conf.sta.pmf_cfg.required = false; conf.sta.threshold.authmode = WIFI_AUTH_WPA2_PSK; // force WPA2 only esp_wifi_set_config(WIFI_IF_STA, &conf); WiFi.begin(staSSID.c_str(), staPass.c_str()); Serial.printf("WiFi connecting to %s", staSSID.c_str()); uint32_t t0 = millis(); while (WiFi.status() != WL_CONNECTED) { delay(300); Serial.print("."); if (millis() - t0 > 30000) break; // 30s timeout -> AP mode } } if (WiFi.status() == WL_CONNECTED) { esp_wifi_set_ps(WIFI_PS_NONE); // no power save = no UDP drops Serial.printf("\nWiFi up: %s\n", WiFi.localIP().toString().c_str()); if (MDNS.begin("c3adblock")) { MDNS.addService("http", "tcp", 80); Serial.println("dashboard: http://c3adblock.local"); } } else { // ---- AP mode: captive portal for WiFi setup ---- apMode = true; Serial.println("\nAP mode — join C3-AdBlock WiFi to configure"); WiFi.mode(WIFI_AP); uint8_t mac[6]; esp_read_mac(mac, ESP_MAC_WIFI_SOFTAP); char apName[32]; snprintf(apName, sizeof(apName), "C3-AdBlock-%02X%02X", mac[4], mac[5]); WiFi.softAP(apName, nullptr, 6, 0, 4); // channel 6, no password, max 4 clients WiFi.setTxPower(WIFI_POWER_19_5dBm); // max TX power dnsCaptive.start(53, "*", IPAddress(192, 168, 4, 1)); Serial.printf("AP: %s -> http://192.168.4.1\n", apName); } // ---- web routes (shared by STA and AP mode) ---- if (!apMode) { dnsServer.begin(DNS_PORT); upstreamCli.begin(0); } web.on("/", []() { web.send_P(200, "text/html", apMode ? PAGE_AP : PAGE); }); web.on("/stats.json", handleStats); web.on("/ban", handleBan); web.on("/addblock", []() { addCustom(web.arg("d")); web.send(200, "text/plain", "ok"); }); web.on("/unblock", []() { removeCustom(web.arg("d")); web.send(200, "text/plain", "ok"); }); web.on("/upload", HTTP_POST, handleUploadDone, handleUpload); web.on("/update", HTTP_POST, handleFwUpdateDone, handleFwUpload); web.on("/fetchnow", []() { fetchBlocklist(updateUrl); web.send(200, "text/plain", updateStatus); }); web.on("/setupdate", []() { if (web.hasArg("u")) updateUrl = web.arg("u"); if (web.hasArg("h")) { updateIntervalH = web.arg("h").toInt(); if (updateIntervalH < 1) updateIntervalH = 1; } saveUpdateCfg(); web.send(200, "text/plain", "ok"); }); web.on("/setwifi", []() { String s = web.arg("s"), p = web.arg("p"); s.trim(); if (s.length() == 0) { web.send(400, "text/plain", "ssid empty"); return; } saveWiFiCreds(s, p); web.send(200, "text/plain", "saved — rebooting..."); delay(500); ESP.restart(); }); web.on("/scan", []() { int n = WiFi.scanNetworks(); String j = "["; for (int i = 0; i < n; i++) { if (i) j += ","; String ssid = WiFi.SSID(i); ssid.replace("\"", "\\\""); j += "{\"ssid\":\"" + ssid + "\",\"rssi\":" + WiFi.RSSI(i) + ",\"open\":" + (WiFi.encryptionType(i) == WIFI_AUTH_OPEN ? "true" : "false") + "}"; } j += "]"; WiFi.scanDelete(); web.send(200, "application/json", j); }); web.on("/forgetwifi", []() { clearWiFiCreds(); web.send(200, "text/plain", "credentials cleared — rebooting..."); delay(500); ESP.restart(); }); web.onNotFound([]() { // captive portal catch-all — serve setup page for any path web.send_P(200, "text/html", apMode ? PAGE_AP : PAGE); }); web.begin(); if (!apMode) { ArduinoOTA.setHostname("c3adblock"); ArduinoOTA.begin(); } Serial.println(apMode ? "captive portal up" : "DNS :53 + dashboard :80 + OTA up"); } void loop() { if (!apMode) ArduinoOTA.handle(); if (apMode) dnsCaptive.processNextRequest(); web.handleClient(); if (!apMode) handleDns(); if (updateUrl.length()) { uint32_t now = millis(); if (lastCheckMs == 0) lastCheckMs = now; else if (now - lastCheckMs >= updateIntervalH * 3600000UL) { lastCheckMs = now; fetchBlocklist(updateUrl); } } delay(1); }