example-dev.yaml

esphome:
  name: esp32-tailscale-dev
  friendly_name: "ESP32 Tailscale (dev)"

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf
    sdkconfig_options:
      # CONFIG_LOG_MAXIMUM_LEVEL_INFO and CONFIG_LOG_TAG_LEVEL_IMPL are now
      # set by the tailscale component __init__.py for all builds.
      # lwip tcpip_thread stack: ESP-IDF default 3072 is the documented minimum
      # and per Espressif's own lwip guide can overflow when callbacks log
      # verbosely ("esp_netif API calls can end up a few calls deep and
      # logging there can trigger a stack overflow"). Overflow silently
      # corrupts adjacent heap objects — including `lock_tcpip_core` (a
      # FreeRTOS mutex handle), which then makes every subsequent
      # xSemaphoreGive() return pdFALSE and trip
      # `sys_mutex_unlock: failed to give the mutex` on loopTask's next
      # lwip_write. Raise to 6144 for headroom under API log streaming.
      CONFIG_LWIP_TCPIP_TASK_STACK_SIZE: "6144"
      # Enable runtime core-lock ownership checks — LWIP_ASSERT_CORE_LOCKED()
      # guards throughout lwip fire earlier and with a clearer message if a
      # LOCK/UNLOCK ownership violation ever resurfaces.
      CONFIG_LWIP_CHECK_THREAD_SAFETY: y
      # Disable LWIP_TCPIP_CORE_LOCKING: with locking enabled, lwip_netconn_do_write
      # runs an UNLOCK/sem_wait/LOCK partial-write dance (api_msg.c:1913-1919) that
      # races with sent_tcp → do_writemore on tcpip_thread. When loopTask gets
      # preempted holding the core lock (e.g. during logger UART blocking), this
      # race fires an `offset < len` assert at api_msg.c:1738 and/or
      # `sys_mutex_unlock: failed to give the mutex` crash. Switching to the
      # mbox-based api path removes the race entirely.
      CONFIG_LWIP_TCPIP_CORE_LOCKING: n

# Load the tailscale component from your local checkout instead of GitHub.
# Every compile uses the current working-tree copy of components/tailscale,
# so you can edit the Python schema or C++ code and see it immediately.
# This is the file to use when you are modifying the component itself.
external_components:
  - source: components

# Entity definitions (mirrored from packages/tailscale/tailscale.yaml).
# Kept inline here so that this file is fully self-contained for dev work.
# If you add a new entity to the package, also add it here.
time:
  - platform: sntp
    id: tailscale_time
    servers:
      - 0.pool.ntp.org
      - 1.pool.ntp.org
      - 2.pool.ntp.org

binary_sensor:
  - platform: tailscale
    connected:
      name: "VPN Connected"
      icon: mdi:shield-check
      id: tailscale_connected
    key_expiry_warning:
      name: "VPN Node Key Expiry Warning"
      icon: mdi:key-alert
      id: tailscale_key_expiry_warning
    ha_connected:
      name: "HA API Connected"
      icon: mdi:home-assistant
      id: tailscale_ha_connected
    vpn_auto_rollback:
      name: "VPN Auto-Rollback"
      icon: mdi:backup-restore
      id: tailscale_vpn_auto_rollback

text_sensor:
  - platform: tailscale
    ip_address:
      name: "VPN IP"
      icon: mdi:ip-network
      id: tailscale_ip_address
    vpn_hostname:
      name: "VPN Hostname"
      icon: mdi:rename-box
      id: tailscale_vpn_hostname
    memory_mode:
      name: "Device Memory"
      icon: mdi:memory
      id: tailscale_memory_mode
    setup_status:
      name: "VPN Setup Hint"
      icon: mdi:lightbulb-on-outline
      id: tailscale_setup_status
    peer_status:
      name: "VPN Peer Status"
      icon: mdi:lan
      id: tailscale_peer_status
    magicdns:
      name: "VPN MagicDNS"
      icon: mdi:dns
      id: tailscale_magicdns
    network_name:
      name: "VPN Network"
      icon: mdi:network-outline
      id: tailscale_network_name
    key_expiry:
      name: "VPN Node Key Expiry"
      icon: mdi:calendar-clock
      id: tailscale_key_expiry
    auth_key_status:
      name: "VPN Auth Key Source"
      icon: mdi:shield-key-outline
      id: tailscale_auth_key_status
    ha_connection_route:
      name: "HA API Connection Route"
      icon: mdi:routes
      id: tailscale_ha_connection_route
    ha_connection_ip:
      name: "HA API Connection IP"
      icon: mdi:ip-network-outline
      id: tailscale_ha_connection_ip
    control_plane:
      name: "VPN Control Plane"
      icon: mdi:cloud-cog-outline
      id: tailscale_control_plane
    login_server:
      name: "VPN Login Server"
      icon: mdi:login-variant
      id: tailscale_login_server

text:
  - platform: tailscale
    auth_key:
      name: "VPN Auth Key Override"
      icon: mdi:key-variant
      id: tailscale_auth_key_override
      mode: password

button:
  - platform: tailscale
    reconnect:
      name: "VPN Reconnect"
      icon: mdi:connection
      id: tailscale_reconnect
  - platform: restart
    name: "Reboot"

sensor:
  - platform: tailscale
    peers_online:
      name: "VPN Peers Online"
      icon: mdi:account-network
      id: tailscale_peers_online
    peers_direct:
      name: "VPN Peers Direct"
      icon: mdi:lan-connect
      id: tailscale_peers_direct
    peers_derp:
      name: "VPN Peers DERP"
      icon: mdi:server-network
      id: tailscale_peers_derp
    peers_max:
      name: "VPN Peers Max"
      icon: mdi:account-multiple
      id: tailscale_peers_max
    uptime:
      name: "VPN Uptime"
      icon: mdi:timer-outline
      id: tailscale_uptime
    connections:
      name: "VPN Connect Count"
      icon: mdi:counter
      id: tailscale_connections

switch:
  - platform: tailscale
    vpn_enabled:
      name: "VPN Enabled"
      icon: mdi:vpn
      id: tailscale_vpn_enabled
    debug_log:
      name: "VPN Debug Log"
      icon: mdi:bug-outline
      id: tailscale_debug_log
      restore_mode: RESTORE_DEFAULT_OFF

# PSRAM init — dev hardware here is N16R8 octal/80MHz.
psram:
  mode: octal
  speed: 80MHz

tailscale:
  auth_key: !secret tailscale_auth_key
  hostname: "esp32-tailscale-dev"
  # max_peers: 16  # Optional, default 16
  # login_server: "http://192.168.1.42:8080"  # Optional: Headscale / self-hosted control plane

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  # use_address: "100.x.x.x"  # Set to your Tailscale VPN IP after first boot

logger:
  level: INFO
  # Raised from default 115200 to 921600: at 115200 baud (~11.5 KB/s),
  # the microlink DIAG logs saturate the UART TX FIFO; since ESPHome's
  # write_msg_ calls uart_write_bytes on a driver installed with
  # tx_buffer_size=0, it blocks on the hardware FIFO semaphore. Under
  # the resulting loopTask stall, task_wdt fires and/or lwip core-lock
  # invariants break. 921600 baud = 8x throughput, enough headroom to
  # keep the logger non-blocking even during peer-setup log bursts.
  baud_rate: 921600
  # TaskLogBuffer left at default (768). The prvSendItemDoneNoSplit assert
  # that previously crashed at ~50s with web_server enabled was resolved by
  # commit a881549 (wg_mgr→CPU0, DISCO key cache, throttled peer ingest).
  # Verified 2x clean (200s + 300s) with 2 SSE subscribers + browser + full
  # WG traffic @ 2026-04-12.
  hardware_uart: UART0
  # ml_* log levels controlled by tailscale: debug_log option

api:

# Previously required task_log_buffer_size: 0 workaround — no longer needed
# after commit a881549 resolved the timing race. Verified clean 2026-04-12.
web_server:
  port: 80

ota:
  platform: esphome