Production-ready Tailscale VPN client for the ESP32 platform with WiFi and 4G cellular support. Should work on most ESP32 variants (ESP32, ESP32-S3, ESP32-P4, etc.) — ESP32-S3 with PSRAM recommended for production.

• Full Tailscale Protocol Support

  • ts2021 coordination protocol
  • WireGuard encryption (ChaCha20-Poly1305)
  • DISCO path discovery (PING/PONG/CALL_ME_MAYBE)
  • DERP relay with dynamic region discovery (up to 32 regions)
  • STUN for public IP / NAT type discovery (IPv4 + IPv6)
  • Delta updates (PeersChanged, PeersRemoved, PeersChangedPatch)
  • MagicDNS hostname resolution (short name or FQDN)
  • Key expiry detection and auto re-registration

• WiFi + 4G Cellular

  • WiFi primary with automatic cellular failback
  • PPP cellular data — real lwIP sockets, direct UDP, NAT hole-punching
  • AT socket bridge fallback for carriers that reject PPP auth
  • Multi-carrier: PAP (IMSI-based) and CHAP (credential-based) automatic selection
  • Seamless network rebind — switch between WiFi and cellular without destroying the VPN session (~330ms rebind, ~7s recovery)
  • Network health monitoring with automatic failback to WiFi when recovered

• Production Ready

  • Fully async, task-based architecture (no polling loop)
  • Tested with 300+ peer tailnets (PSRAM-backed 512KB buffers)
  • NVS peer cache — DISCO probing starts immediately on reboot
  • Proactive H2 WINDOW_UPDATE for fast MapResponse downloads
  • Key expiry handling with reusable auth keys

• Broad Hardware Support

  • Tested on ESP32-S3, ESP32-WROOM-32D, and HiLetgo ESP-32S
  • Should work on most ESP32 variants with WiFi and sufficient RAM
  • Memory-optimized: ~85-116KB SRAM static, PSRAM for large tailnet buffers

• HTTP Config Server

  • Web UI at http://<vpn-ip>/ — system monitor, peer management, device settings
  • REST API: /api/settings, /api/peers, /api/peers/allowed, /api/monitor, /api/status, /api/restart
  • All settings persist in NVS — no rebuild needed
  • Ifdef-gated: zero cost when disabled

• Advanced Features

  • Zero-copy WireGuard receive (raw lwIP PCB, for 30fps+ video streaming)
  • DISCO peer filtering / allowlist (reduces jitter on large tailnets)
  • Priority peer (guaranteed WG slot even when peer table is full)
  • Headscale / Ionscale compatible (configurable control plane host)
  • Credential security: all secrets in git-ignored sdkconfig

• ESP-IDF v5.0 or later (tested with v5.3)
• ESP32 with WiFi (ESP32-S3 with PSRAM recommended)
• Tailscale account with auth key (generate at https://login.tailscale.com/admin/settings/keys)
• For cellular: ESP32-compatible 4G cellular module (e.g., SIM7600, SIM7670) + active SIM card

MicroLink uses standard ESP-IDF APIs — any ESP32 variant with WiFi and sufficient RAM should work. ESP32-P4, ESP32-C3, ESP32-C6, etc. Boards with PSRAM are recommended for large tailnets (100+ peers).

git clone https://github.com/CamM2325/microlink.git
cd microlink/examples/basic_connect    # or: cellular_connect, cellular_heartbeat, failover_connect

Add these settings to your sdkconfig.defaults file:

# PSRAM Configuration (required for ESP32-S3 with PSRAM)
CONFIG_SPIRAM=y
CONFIG_SPIRAM_MODE_OCT=y
CONFIG_SPIRAM_TYPE_AUTO=y
CONFIG_SPIRAM_SPEED_80M=y
CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY=y
CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=4096
CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL=32768

# Partition table (app needs ~1MB+)
CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE=y

# TLS/HTTPS (required for DERP and control plane)
CONFIG_ESP_TLS_USING_MBEDTLS=y
CONFIG_MBEDTLS_SSL_PROTO_TLS1_2=y
CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=y
CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN=y

# Networking
CONFIG_LWIP_IPV4=y
CONFIG_LWIP_IP4_FRAG=y
CONFIG_LWIP_IP4_REASSEMBLY=y

# Stack size
CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192

cp sdkconfig.credentials.example sdkconfig.credentials
# Edit sdkconfig.credentials with your WiFi SSID/password, Tailscale auth key, etc.

Or run idf.py menuconfig → MicroLink V2 → Credentials to set them interactively.

Credentials are stored in sdkconfig (which is gitignored) so they are never accidentally committed to version control.

source ~/esp/esp-idf/export.sh
idf.py build
idf.py -p /dev/ttyACM0 flash monitor

From any device on your tailnet:

tailscale ping esp32-microlink

You should see:

pong from esp32-microlink (100.x.x.x) via DERP(dfw) in 150ms

MapResponse buffers (H2 + JSON) are allocated from PSRAM only during coordination polling, then freed. Peak PSRAM usage is ~1MB (~12% of 8MB). Leaves 200KB+ SRAM free for your application.

Boards without PSRAM can reduce H2/JSON buffers to 64KB via menuconfig (sufficient for ~30 peers). Total SRAM usage: ~140KB. Suitable for simple sensor reporting, heartbeats, and small data payloads. Not recommended for large tailnets or memory-heavy applications.

# sdkconfig.defaults for ESP32 without PSRAM
CONFIG_ML_H2_BUFFER_SIZE_KB=64
CONFIG_ML_JSON_BUFFER_SIZE_KB=64
CONFIG_ML_MAX_PEERS=8

MicroLink v2 uses a fully async, task-based architecture. All protocol operations run concurrently in dedicated FreeRTOS tasks with queue-based IPC — no polling loop needed.

┌─────────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐
│ coord_task  │  │ derp_tx  │  │ net_io   │  │ wg_mgr  │
│ (Tailscale  │  │ (DERP    │  │ (select  │  │ (WG +   │
│  control)   │  │  relay)  │  │  loop)   │  │  DISCO) │
└──────┬──────┘  └────┬─────┘  └────┬─────┘  └────┬────┘
       │              │             │              │
       └──────────────┴─────────────┴──────────────┘
                          │
                    Queue-based IPC
                          │
                ┌─────────┴─────────┐
                │   WiFi / Cellular  │
                │  (ml_net_switch)   │
                └───────────────────┘

Key differences from v1:

• No microlink_update() polling — all tasks run independently
• Queue-based IPC instead of shared state + mutexes (no deadlocks)
• Dedicated DERP TX task (non-blocking sends)
• select() loop in net_io for multiplexed packet routing

// Get a default configuration
microlink_config_t config = {
    .auth_key = "tskey-auth-...",
    .device_name = "my-sensor",
    .enable_derp = true,
    .enable_disco = true,
    .enable_stun = true,
    .max_peers = 16,
};

// Initialize (creates tasks, does NOT connect yet)
microlink_t *ml = microlink_init(&config);

// Start connecting (WiFi must be up)
microlink_start(ml);

// Check connection state
microlink_state_t state = microlink_get_state(ml);
bool connected = microlink_is_connected(ml);

// Get our VPN IP
uint32_t vpn_ip = microlink_get_vpn_ip(ml);
char ip_str[16];
microlink_ip_to_str(vpn_ip, ip_str);
// ip_str = "100.x.y.z"

Connection states: ML_STATE_IDLE → ML_STATE_WIFI_WAIT → ML_STATE_CONNECTING → ML_STATE_REGISTERING → ML_STATE_CONNECTED

// Create UDP socket bound to VPN IP
microlink_udp_socket_t *sock = microlink_udp_create(ml, 9000);

// Send to a peer
uint32_t dest = microlink_parse_ip("100.x.y.z");
microlink_udp_send(sock, dest, 9000, data, len);

// Blocking receive with timeout
uint32_t src_ip;
uint16_t src_port;
size_t recv_len = sizeof(buffer);
esp_err_t err = microlink_udp_recv(sock, &src_ip, &src_port, buffer, &recv_len, 5000);

// Or use a callback for immediate handling
microlink_udp_set_rx_callback(sock, my_rx_handler, user_data);

// Cleanup
microlink_udp_close(sock);

// Connect to a peer over the WG tunnel (triggers handshake if needed)
microlink_tcp_socket_t *sock = microlink_tcp_connect(ml, "100.x.y.z", 5055);

// Send data
microlink_tcp_send(sock, data, len);

// Blocking receive with timeout (milliseconds)
size_t recv_len = sizeof(buffer);
esp_err_t err = microlink_tcp_recv(sock, buffer, &recv_len, 5000);

// Check connection status
bool up = microlink_tcp_is_connected(sock);

// Cleanup
microlink_tcp_close(sock);

TCP sockets are routed through the WireGuard tunnel by binding to the VPN IP internally. The connect call will wait up to 30 seconds for the WG handshake to complete if the peer tunnel isn't already up.

// Resolve short name or FQDN to VPN IP (local lookup, no network call)
uint32_t ip = microlink_resolve(ml, "npc1");           // short name
uint32_t ip = microlink_resolve(ml, "npc1.tail1234.ts.net");  // FQDN

int count = microlink_get_peer_count(ml);
for (int i = 0; i < count; i++) {
    microlink_peer_info_t info;
    microlink_get_peer_info(ml, i, &info);
    char ip[16];
    microlink_ip_to_str(info.vpn_ip, ip);
    printf("Peer: %s (%s) %s\n", info.hostname, ip,
           info.direct_path ? "direct" : "via DERP");
}

// State change notification
microlink_set_state_callback(ml, on_state_change, user_data);

// Peer discovered/updated
microlink_set_peer_callback(ml, on_peer_update, user_data);

// Raw data received (alternative to UDP socket API)
microlink_set_data_callback(ml, on_data, user_data);

// Instead of microlink_init() directly, use the net_switch module:
ml_net_switch_config_t ns_config = {
    .wifi_ssid = "MyWiFi",
    .wifi_pass = "MyPassword",
    .cell_tx_pin = 43,
    .cell_rx_pin = 44,
};
ml_net_switch_init(&ns_config);
ml_net_switch_start();

// Get the MicroLink handle (same API as above)
microlink_t *ml = ml_net_switch_get_handle();

// Switch the VPN to a new network interface without destroying the session.
// Preserves WG peer state, crypto keys, VPN IP, and DISCO state.
// Closes/recreates DISCO+STUN sockets, signals coord+DERP to reconnect.
// ~330ms rebind, ~7s VPN recovery.
esp_err_t ret = microlink_rebind(ml);

The ml_net_switch module calls microlink_rebind() automatically during WiFi↔cellular transitions.

microlink_stop(ml);
microlink_destroy(ml);

// Erase all stored keys and cached peers (call BEFORE init)
microlink_factory_reset();

MicroLink supports full bidirectional UDP communication over the Tailscale VPN. The ESP32 can both send and receive without waiting for a peer to initiate.

1. Magicsock Mode: WireGuard and DISCO share a single UDP socket — no port conflicts
2. Direct Path Discovery: DISCO protocol finds the optimal path (direct UDP or DERP relay)
3. Cryptokey Routing: Packets are routed based on peer's VPN IP using /32 allowed IPs
4. CallMeMaybe: On UDP socket creation, triggers WG handshakes to all known peers

# On PC — send to ESP32, receive echo
echo "hello" | nc -u 100.x.y.z 9000

# On PC — listen for ESP32-initiated messages
nc -u -l 9000

MicroLink uses PPP for cellular data, giving real lwIP sockets instead of routing through AT commands. This enables direct UDP, STUN, and NAT hole-punching — eliminating the DERP relay hop for peers on non-symmetric NATs.

Measured on a ~20 peer tailnet. Boot and MapResponse times increase with tailnet size — a 300+ peer tailnet will take significantly longer for the initial MapResponse download.

When PPP is active, the modem UART carries raw IP packets via the PPP protocol. lwIP creates a ppp_netif network interface, and all standard BSD socket calls (connect, send, recv) work directly — no AT command overhead. This is the same mechanism your phone uses for cellular data.

If PPP authentication fails (e.g., carrier rejects CHAP/PAP), MicroLink automatically falls back to the AT socket bridge. This uses the modem's internal TCP/IP stack via AT commands (AT+CIPOPEN, AT+CIPSEND, etc.). It's slower but works with any carrier.

PPP authentication is automatic — CHAP with credentials when provided, PAP with empty credentials for IMSI-based carriers. Falls back to AT socket bridge if PPP fails.

During large downloads (MapResponse parsing, delta updates), DISCO/STUN/WG probes continue with elevated RTTs (800-1800ms vs 500ms normal). Once the download completes, latency returns to normal. All protocol tasks run concurrently without blocking each other.

Enable CONFIG_ML_ENABLE_CONFIG_HTTPD=y in sdkconfig.defaults to get a web UI accessible at http://<vpn-ip>/ from any device on your tailnet.

System Monitor — Real-time ESP32 temperature, WiFi RSSI (or cellular indicator), uptime, heap/PSRAM usage, DERP region, peer count, per-task stack watermarks. Auto-refreshes every 3 seconds.

Peer Allowlist — Manage which peers receive DISCO probes. Changes take effect immediately (no restart). On large tailnets (200+ devices), this limits DISCO probing to only the peers that matter.

All Tailnet Peers — Paginated peer list (25 per page) with search/filter, direct/DERP path status, and one-click "Allow" buttons. Peers not in the allowlist show a "Not Allowed" badge when filtering is active.

Device Settings — WiFi, Tailscale auth key, device name, cellular APN, plus advanced settings (max peers, DISCO heartbeat, priority peer, control plane host for Headscale/Ionscale, debug flags). All persist in NVS and take effect on restart.

Resource usage — ~28KB flash, ~7KB RAM (6KB HTTP task stack + 1KB NVS config). Ifdef-gated: zero cost when disabled (CONFIG_ML_ENABLE_CONFIG_HTTPD=n).

REST API — All functionality available via JSON endpoints:

Device naming — Set a prefix (e.g. sensor) to auto-generate sensor-a1b2c3 from MAC, or set a full custom name. Tailscale creates the DNS entry: your-name.your-tailnet.ts.net.

All settings via idf.py menuconfig → MicroLink V2 Configuration.

MicroLink V2 Configuration
├── Core
│   ├── Enable zero-copy WireGuard receive    [ ]
│   ├── Maximum simultaneous WireGuard peers  (16)
│   ├── Maximum cached peers in NVS           (64)
│   ├── Priority peer VPN IP                  ()
│   ├── HTTP/2 receive buffer size (KB)       (512)
│   └── JSON parse buffer size (KB)           (512)
├── Credentials
│   ├── WiFi SSID                             ()
│   ├── WiFi Password                         ()
│   ├── Tailscale Auth Key                    ()
│   └── Device Name                           ()
├── Cellular Modem
│   ├── Enable cellular modem support         [ ]
│   ├── Cellular board type                   (Waveshare SIM7600X)
│   ├── Cellular UART TX GPIO pin             (43)
│   ├── Cellular UART RX GPIO pin             (44)
│   ├── Modem PWRKEY GPIO pin                 (-1)
│   ├── Modem DTR GPIO pin                    (-1)
│   ├── Cellular APN                          ()
│   ├── SIM Card PIN                          ()
│   ├── PPP CHAP username                     ()
│   └── PPP CHAP password                     ()
├── Network Switching
│   ├── Enable WiFi/Cellular network switching [ ]
│   ├── WiFi connect timeout (ms)             (30000)
│   ├── Health check interval (ms)            (30000)
│   └── WiFi failback check interval (ms)     (120000)
└── HTTP Config Server
    ├── Enable HTTP configuration server       [ ]
    └── Maximum peers in allowlist             (16)

V2 uses fully dynamic DERP discovery — no manual region configuration needed. On startup, MicroLink:

1. Parses the DERPMap from the Tailscale MapResponse (supports up to 32 regions)
2. Selects the optimal home region based on latency
3. Automatically fails over to other regions if the primary becomes unavailable
4. Ensures the ESP32 connects to the same DERP region it advertises as PreferredDERP

Important: The ESP32 must connect to the same DERP region it advertises. Tailscale peers send packets to whichever DERP region you advertise as your PreferredDERP. If there's a mismatch, DISCO PING/PONG packets won't reach your device.

MicroLink supports custom coordination servers like Headscale and Ionscale. This allows you to run your own private Tailscale-compatible control plane.

Configuration: Set the control plane host via the HTTP config server web UI (Device Settings → Control Plane Host) or programmatically via ctrl_host in the config struct.

Server key: MicroLink automatically fetches the server's Noise public key from the /key endpoint via HTTPS. No manual key configuration required.

Notes:

• Generate auth keys from your Headscale/Ionscale admin interface, not from Tailscale
• If your custom server uses self-signed certificates, add them to the ESP32's certificate bundle
• MicroLink implements ts2021 — ensure your coordination server supports this version
• DERP discovery is automatic from the server's DERPMap

For applications requiring high data throughput (e.g., video streaming at 30fps+), MicroLink offers an optional zero-copy WireGuard receive mode.

idf.py menuconfig
# Navigate to: MicroLink V2 Configuration
# Enable: "Enable zero-copy WireGuard receive (high-throughput mode)"

Zero-copy mode uses a raw lwIP PCB callback that runs in tcpip_thread and demultiplexes:

• WireGuard packets → wireguardif_network_rx() directly (zero copy, same thread)
• DISCO packets → Lock-free SPSC ring buffer to wg_mgr task
• STUN responses → Dedicated buffer for STUN module

This avoids the overhead of BSD socket syscalls and buffer copies, achieving lower latency and higher throughput.

Zero-copy mode contributed by dj-oyu.

• Check auth key is valid and not expired
• Ensure WiFi is connected (or cellular registered)
• Check coordination server connection in logs
• Try a fresh auth key from https://login.tailscale.com/admin/settings/keys

• Verify DISCO and DERP are enabled in config
• Check DERP connection in serial logs — look for "DERP: connected to region X"
• Look for "PONG sent" in logs
• Ensure the ESP32's advertised PreferredDERP matches the region it's actually connected to

• DERP relay: 30-150ms (WiFi), 300-600ms (cellular PPP) — this is normal
• Direct connections are faster: 5-50ms (WiFi), 265-390ms (cellular PPP)
• Wait for DISCO to discover a direct path (may take 30-60 seconds)
• If stuck on DERP, check NAT type — symmetric NAT blocks direct connections

• H2 buffer too small for your tailnet size
• Increase ML_H2_BUFFER_SIZE_KB and ML_JSON_BUFFER_SIZE_KB in menuconfig
• For 300+ peers, use 512KB (default). For 600+, use 1024KB.
• Ensure PSRAM is enabled: CONFIG_SPIRAM=y

• Check carrier APN is correct
• For CHAP carriers (Soracom), set ML_CELLULAR_PPP_USER and ML_CELLULAR_PPP_PASS
• For IMSI-based carriers (EIOT/BICS), leave PPP credentials empty
• Check serial log for "PPP CHAP auth failed" — this triggers automatic AT socket fallback
• AT socket bridge is slower but functional — the fallback is working as intended

• Ensure PSRAM is enabled in sdkconfig (see Quick Start section)
• Check that CONFIG_SPIRAM=y is set
• Verify your board has PSRAM (most ESP32-S3 dev boards do)

• Add CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE=y to sdkconfig.defaults
• Clean build: rm -rf build sdkconfig && idf.py build

• Check UART wiring: ESP32 TX → modem RXD, ESP32 RX ← modem TXD, shared GND
• Modem needs separate USB-C power and 15-30 seconds to boot after power-on
• After SIM swap, power-cycle the modem (not just ESP32)
• Check serial log for AT command responses

If the device is in a bad state (wrong keys cached, stale peer data):

microlink_factory_reset();  // Call before microlink_init()

This erases all NVS-stored keys and peer cache. The device will re-register on next boot.

The ESP32-S3 can get warm during continuous operation, especially with:

• High-frequency polling or data transmission
• Active WiFi + cellular simultaneously
• Verbose debug logging

1. Disable debug logging — reduces CPU load significantly
2. Use a heatsink on ESP32-S3 for 24/7 operation
3. Monitor heap — use the HTTP config server's system monitor or add periodic logging
4. Adequate TX intervals — 30 seconds between heartbeats is sufficient for most applications
5. DISCO allowlist — on large tailnets, limit DISCO probing to only the peers you need

The HTTP config server provides real-time heap monitoring. For standalone monitoring:

static uint32_t last_heap_log = 0;
uint32_t now = xTaskGetTickCount() * portTICK_PERIOD_MS;
if (now - last_heap_log > 60000) {  // Every 60 seconds
    ESP_LOGI(TAG, "Free heap: %lu, min: %lu, PSRAM: %lu",
             esp_get_free_heap_size(),
             esp_get_minimum_free_heap_size(),
             heap_caps_get_free_size(MALLOC_CAP_SPIRAM));
    last_heap_log = now;
}

• TESTING_GUIDE.md — Hardware setup, build, flash, test procedures
• docs/ARCHITECTURE.md — System design and task model
• docs/LARGE_TAILNET.md — Scaling considerations for 300+ peers
• docs/TAILSCALE_REFERENCE.md — Tailscale protocol reference patterns

• Tailscale for the protocol specification
• Headscale for open-source coordination server insights
• WireGuard for the cryptographic foundation
• lwIP for the TCP/IP stack
• wireguard-lwip for WireGuard-lwIP integration

Malone Technologies LLC

MicroLink includes improvements from community forks:

• dj-oyu — Zero-copy WireGuard receive mode, PONG rate-limiting, adaptive probe intervals, symmetric NAT port spray, and path discovery optimizations. Originally developed for high-throughput video streaming on RDK-X5 smart pet camera.

• GrieferPig — WireGuard peer lookup fix to prefer peers with valid keypairs, preventing handshake failures with stale peer references.

MIT License — see LICENSE

This is an independent implementation created for educational and interoperability purposes. It is not affiliated with or endorsed by Tailscale Inc. Use at your own risk.