Docs / Integrations / Home Assistant

Home Assistant MQTT Bridge

Stream sensor readings and control devices between Home Assistant and jettyd over MQTT.

Prerequisites

TLS required jettyd only accepts connections on port 8883 with TLS. Plain-text port 1883 connections are rejected.

Two integration paths

Choose the path that fits your setup:

Path A — Mosquitto bridge to jettyd

Recommended

Step 1 — Open the Mosquitto add-on config editor

In Home Assistant: Settings → Add-ons → Mosquitto broker → Configuration. Alternatively, SSH into the HA host.

Step 2 — Add the bridge config file

Create /share/mosquitto/conf.d/jettyd-bridge.conf with the following content, substituting your credentials:

connection jettyd-bridge
address mqtt.jettyd.com:8883
bridge_tls_version tlsv1.2
try_private false
start_type automatic

topic jettyd/# both 1

remote_clientid <JETTYD_CLIENT_ID>
remote_username <JETTYD_CLIENT_ID>
remote_password <JETTYD_PASSWORD>
Note The topic jettyd/# both 1 line mirrors all jettyd/… topics in both directions at QoS 1. Narrow this pattern if you only need one-way telemetry.

Step 3 — Restart the Mosquitto add-on

In the add-on page, click Restart. Wait ~10 seconds for the bridge to establish.

Step 4 — Verify the connection

Open the Mosquitto add-on log. You should see a line similar to:

Notice: connected to jettyd-bridge

If you see connection refused, double-check your credentials. If you see a TLS error, confirm the host system trusts the Let's Encrypt root CA (usually pre-installed on modern OS images).

Path B — HA MQTT integration pointing directly at jettyd

Alternative

Step 1 — Open the MQTT integration settings

In Home Assistant: Settings → Devices & Services → MQTT → Configure.

Step 2 — Enter the jettyd broker details

Step 3 — Save and test

Click Submit. HA will test the connection immediately. A green checkmark confirms it is connected.

Path B limitation With Path B, Home Assistant authenticates as a single jettyd device. All MQTT traffic from HA uses that one set of credentials. If you want multiple physical HA-connected devices to appear as separate jettyd devices, use Path A instead.

Testing your connection

After either path, publish a test telemetry payload from your workstation to confirm end-to-end delivery:

mosquitto_pub \
  -h mqtt.jettyd.com -p 8883 --tls-use-os-certs \
  -u "$JETTYD_CLIENT_ID" -P "$JETTYD_PASSWORD" \
  -t "jettyd/$JETTYD_TENANT_ID/$JETTYD_CLIENT_ID/telemetry" \
  -m '{"readings":{"temperature":22.0}}' \
  -q 1

Open the jettyd dashboard and confirm the reading appears under your device within 30 seconds.

Staging broker Test against mqtt-staging.jettyd.com:8883 before pointing production HA at mqtt.jettyd.com. Use the same credentials — the staging broker shares the same auth backend.

Troubleshooting