ESPHome 2026.11 can reach MQTT brokers over WebSocket on ESP32 with ESP-IDF

ESPHome's MQTT component gets a transport option that lets an ESP32 connect to the broker over a WebSocket, plain or encrypted with TLS. The change by Ankur Kumar Pandey was opened in April and merged into the dev branch in the early hours of 21 October 2026, the day ESPHome 2026.10.0 came out. It is not part of 2026.10.0, so it should arrive with ESPHome 2026.11.

Who needs it

Normally ESPHome talks MQTT over a direct TCP connection to port 1883, or 8883 with TLS. That does not work when the broker sits behind a reverse proxy or a tunnel that only passes HTTP and HTTPS, as happens when services are exposed through a single web address. Many brokers, Mosquitto among them, can also accept MQTT over WebSocket, and that traffic goes through such proxies like any other web connection.

Configuration

The new options are transport and ws_path:

mqtt:
  broker: mqtt.example.com
  port: 443
  transport: wss
  ws_path: /mqtt

transport accepts tcp, ws or wss. tcp stays the default and behaves as before, including the switch to TLS when a certificate authority is set. ws is an unencrypted WebSocket and wss is a WebSocket over TLS. ws_path sets the path of the broker's WebSocket endpoint and defaults to /mqtt. The port must point at the broker's WebSocket listener, not at the regular MQTT port.

With wss, the existing certificate_authority, client_certificate, client_certificate_key and skip_cert_cn_check options apply to the TLS handshake. Without certificate_authority, the broker's certificate is checked against the certificate bundle built into the firmware, the same way the HTTP Request component does it. With plain ws the certificate options are rejected, since nothing is encrypted.

Limits

The option works only on ESP32 with the ESP-IDF framework. ESPHome rejects ws and wss during validation on ESP8266, RP2040, LibreTiny chips and on ESP32 with Arduino. The ESPHome command line tool, which uses its own MQTT client for logs, discovery and topic cleanup, follows the configured transport too, so esphome logs over MQTT keeps working with a WebSocket broker.

For devices on the same local network as the broker nothing changes, and plain TCP remains the simpler choice. The option is useful mainly for ESP32 devices outside the home, such as a sensor at a holiday cottage that reports to a broker published through an existing HTTPS proxy.