Custom ESPHome Component for WebSocket Bridge

ESPHome
1

ws_bridge is an ESPHome external component for ESP32 (ESP-IDF framework) that connects directly to Home Assistant over a secure WebSocket (wss://). It allows remote ESP32 devices outside the local network to push entity states and receive control commands without an MQTT broker or a VPN.

Prerequisites (Required)

  • Home Assistant Custom Integration: Requires the hass-ws-bridge custom integration installed in Home Assistant.
  • Automatic Entity Registration: Once connected, hass-ws-bridge automatically registers devices and creates their corresponding entities inside Home Assistant based on the ESPHome configuration—no manual entity configuration needed on the Home Assistant side.

Key Features

  • Direct WSS Connection: Establishes an outbound WebSocket connection to Home Assistant’s standard /api/websocket endpoint using a Long-Lived Access Token.
  • NAT / Firewall Friendly: Operates via outbound connections, making it compatible with reverse proxies, Nabu Casa Remote UI, and Cloudflare Tunnels.
  • Automatic Entity Creation: Entities declared in the ESPHome YAML are automatically created and managed inside Home Assistant by hass-ws-bridge.
  • Supported Entity Platforms:
    • Read-only: sensor, binary_sensor, text_sensor
    • Controllable: switch, number, select, button
  • Sub-device Support: Groups multiple entities under distinct sub-devices in Home Assistant using ws_device_id.
  • Connection Management: Includes exponential backoff auto-reconnect, application-level ping/pong keep-alive, and periodic entity re-announcement.

Architecture

[Remote ESP32] ---> WSS (Outbound) ---> [Reverse Proxy / Nabu Casa] ---> [Home Assistant]
                                                                          (hass-ws-bridge integration)
                                                                           └─ Auto-creates entities

Configuration

esp32:
  board: esp32dev
  framework:
    type: esp-idf

external_components:
  - source: github://eigger/espcomponents@latest
    components: [ ws_bridge ]

ws_bridge:
  host: "your-ha-domain.com"
  port: 443
  ssl: true
  token: !secret ha_token

sensor:
  - platform: ws_bridge
    unique_id: temp1
    name: "Temperature"
    device_class: temperature
    unit_of_measurement: "°C"

switch:
  - platform: ws_bridge
    unique_id: relay1
    name: "Relay"
2 Likes