feat(dns_server): Add DnsServer component enabling captive portal beahvior, udpate Provisioning example to use it (#594)

* feat(dns_server): Add `DnsServer` component for implementing basic captive portals

* doc: update

* update provisioning component / example to act as captive portal

* improve API and update examples / docs

* update docs

* add missing sdkconfig defaults and partition for ci build

* target s3 in ci by default

Author: finger563

.github/workflows/build.yml

@@ -63,6 +63,8 @@ jobs:
           target: esp32
         - path: 'components/display_drivers/example'
           target: esp32
+        - path: 'components/dns_server/example'
+          target: esp32s3
         - path: 'components/drv2605/example'
           target: esp32
         - path: 'components/encoder/example'

.github/workflows/upload_components.yml

@@ -54,6 +54,7 @@ jobs:
             components/csv
             components/display
             components/display_drivers
+            components/dns_server
             components/drv2605
             components/encoder
             components/esp-box

components/dns_server/CMakeLists.txt

@@ -0,0 +1,5 @@
+idf_component_register(
+    INCLUDE_DIRS "include"
+    SRC_DIRS "src"
+    REQUIRES base_component logger socket
+)

components/dns_server/README.md

@@ -0,0 +1,67 @@
+# DNS Server
+
+Simple DNS server component for implementing captive portals on ESP32 devices.
+
+## Features
+
+- Responds to all DNS queries with a configured IP address
+- Lightweight implementation suitable for embedded systems
+- Built on top of espp::UdpSocket for efficient UDP communication
+- Useful for captive portal implementations where all domains should resolve to the device
+
+## Usage
+
+```cpp
+#include "dns_server.hpp"
+
+// Create DNS server that responds with the AP's IP
+espp::DnsServer::Config dns_config{
+  .ip_address = "192.168.4.1",
+  .log_level = espp::Logger::Verbosity::INFO
+};
+espp::DnsServer dns_server(dns_config);
+
+// Start the DNS server
+if (dns_server.start()) {
+  fmt::print("DNS server started\n");
+} else {
+  fmt::print("Failed to start DNS server\n");
+}
+
+// ... server runs in background ...
+
+// Stop when done
+dns_server.stop();
+```
+
+## How It Works
+
+The DNS server listens on UDP port 53 (the standard DNS port) and responds to all A record queries with the configured IP address. This creates a "captive portal" effect where:
+
+1. When a device connects to your WiFi AP, it tries to reach the internet
+2. All DNS queries are answered with your device's IP address
+3. The device's captive portal detection triggers
+4. The user is directed to your web interface
+
+## Integration with Provisioning
+
+This component is designed to work seamlessly with the `espp::Provisioning` component to create a complete captive portal experience for WiFi provisioning.
+
+## API
+
+### Configuration
+
+- `ip_address`: The IP address to respond with for all DNS queries (typically your AP's IP)
+- `log_level`: Logging verbosity level
+
+### Methods
+
+- `start()`: Start the DNS server
+- `stop()`: Stop the DNS server
+- `is_running()`: Check if the server is currently running
+
+## Limitations
+
+- Only responds to A record queries (IPv4)
+- Does not support AAAA records (IPv6)
+- Minimal DNS implementation focused on captive portal use case

components/dns_server/example/CMakeLists.txt

@@ -0,0 +1,22 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.20)
+
+set(ENV{IDF_COMPONENT_MANAGER} "0")
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+# add the component directories that we want to use
+set(EXTRA_COMPONENT_DIRS
+  "../../../components/"
+)
+
+set(
+  COMPONENTS
+  "main esptool_py nvs_flash dns_server wifi"
+  CACHE STRING
+  "List of components to include"
+  )
+
+project(dns_server_example)
+
+set(CMAKE_CXX_STANDARD 20)

components/dns_server/example/README.md

@@ -0,0 +1,38 @@
+# DNS Server Example
+
+This example demonstrates the use of the `dns_server` component to create a simple DNS server that responds to all queries with a single IP address. This is commonly used for captive portal implementations.
+
+## How to use example
+
+### Hardware Required
+
+This example can be run on any ESP32 development board.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+## Example Output
+
+```
+[DNS Server Example/I][0.739]: Starting DNS Server Example
+[DNS Server Example/I][0.739]: Starting WiFi AP: ESP-DNS-Test
+[DNS Server Example/I][0.889]: WiFi AP started successfully
+[DNS Server Example/I][0.889]: Connect to SSID: ESP-DNS-Test with password: testpassword
+[DNS Server Example/I][0.899]: AP IP Address: 192.168.4.1
+[DNS Server Example/I][0.899]: Starting DNS server on 192.168.4.1:53
+[DNS Server Example/I][0.909]: DNS server started successfully
+[DNS Server Example/I][0.909]: All DNS queries will resolve to: 192.168.4.1
+```
+
+## Testing
+
+1. Connect your phone or computer to the WiFi network "ESP-DNS-Test" with password "testpassword"
+2. Try to ping any domain: `ping google.com` - all domains should resolve to 192.168.4.1
+3. The captive portal detection should trigger automatically on most devices

components/dns_server/example/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRC_DIRS "."
+                       INCLUDE_DIRS ".")

components/dns_server/example/main/dns_server_example.cpp

@@ -0,0 +1,71 @@
+#include <chrono>
+#include <system_error>
+#include <vector>
+
+#include "dns_server.hpp"
+#include "logger.hpp"
+#include "wifi.hpp"
+
+using namespace std::chrono_literals;
+
+extern "C" void app_main(void) {
+  espp::Logger logger({.tag = "DNS Server Example", .level = espp::Logger::Verbosity::INFO});
+
+  logger.info("Starting DNS Server Example");
+
+#if CONFIG_ESP32_WIFI_NVS_ENABLED
+  // Initialize NVS
+  esp_err_t ret = nvs_flash_init();
+  if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+    ESP_ERROR_CHECK(nvs_flash_erase());
+    ret = nvs_flash_init();
+  }
+  ESP_ERROR_CHECK(ret);
+#endif
+
+  // Initialize WiFi in AP mode
+  std::string ap_ssid = "ESP-DNS-Test";
+  std::string ap_password = "testpassword";
+
+  logger.info("Starting WiFi AP: {}", ap_ssid);
+
+  espp::WifiAp ap{espp::WifiAp::Config{
+      .ssid = ap_ssid,
+      .password = ap_password,
+      .channel = 1,
+      .max_number_of_stations = 4,
+  }};
+
+  logger.info("WiFi AP started successfully");
+  logger.info("Connect to SSID: {} with password: {}", ap_ssid, ap_password);
+
+  // Get the AP IP address
+  std::string ap_ip = ap.get_ip_address();
+  logger.info("AP IP Address: {}", ap_ip);
+
+  // Create and start DNS server
+  logger.info("Starting DNS server on {}:53", ap_ip);
+
+  espp::DnsServer::Config dns_config{.ip_address = ap_ip,
+                                     .log_level = espp::Logger::Verbosity::INFO};
+
+  espp::DnsServer dns_server(dns_config);
+  std::error_code ec;
+  if (!dns_server.start(ec)) {
+    logger.error("Failed to start DNS server: {}", ec.message());
+    return;
+  }
+
+  logger.info("DNS server started successfully");
+  logger.info("All DNS queries will resolve to: {}", ap_ip);
+  logger.info("");
+  logger.info("To test:");
+  logger.info("1. Connect your device to WiFi network '{}'", ap_ssid);
+  logger.info("2. Try pinging any domain (e.g., ping google.com)");
+  logger.info("3. All domains should resolve to {}", ap_ip);
+
+  // Run forever
+  while (true) {
+    std::this_thread::sleep_for(1s);
+  }
+}

components/dns_server/example/partitions.csv

@@ -0,0 +1,5 @@
+# ESP-IDF Partition Table
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     0x9000,  0x6000,
+phy_init, data, phy,     0xf000,  0x1000,
+factory,  app,  factory, 0x10000, 1500K,

components/dns_server/example/sdkconfig.defaults

@@ -0,0 +1,16 @@
+# Flash size
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+CONFIG_ESPTOOLPY_FLASHSIZE="4MB"
+
+# CONFIG_ESP32_WIFI_NVS_ENABLED=n
+
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions.csv"
+CONFIG_PARTITION_TABLE_OFFSET=0x8000
+CONFIG_PARTITION_TABLE_MD5=y
+
+# Common ESP-related
+#
+CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=4096
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192