soilMoistureSystem/docs/MQTT_SETUP.md

EMQX + Home Assistant setup

Broker for this deployment: EMQX 6.0.1 at 192.168.1.31.

Note that EMQX 6.x still serves its management API under /api/v5 for backward compatibility — the API path is not a version indicator.

0. Broker state

Probed 2026-08-14, before and after the authenticator was created:

Check	Before	After
Listeners 1883 / 8883 / 8083 / 8084 / 18083	all open	all open
Anonymous MQTT connect	accepted	refused (bad username or password)
Connect with a made-up username/password	accepted	refused (not authorized)
Connect as soil-node from secrets.h	n/a	accepted
Publish to soil/#	allowed	allowed
Publish to homeassistant/sensor/#	allowed	allowed
Retained publish + replay to a new client	works	works
Management API (/api/v5/clients)	protected, HTTP 401	protected
Public /api/v5/status	200 (normal, by design)	200

The "before" column is what an EMQX install looks like with no authenticator configured: every client on the LAN can connect, subscribe to #, and publish anywhere — including to homeassistant/... discovery topics, meaning anything on the network could create or overwrite entities in Home Assistant.

In that state the MQTT_USER / MQTT_PASSWORD values in secrets.h are decorative: EMQX accepts them without checking, so a node connecting successfully proves nothing about whether the credentials are correct.

Re-run the check at any time:

python3 tools/check_broker.py

1. Enable authentication in EMQX ✅ done

Dashboard → http://192.168.1.31:18083

1. Access Control → Authentication, then Create (top right)
2. Mechanism Password-Based, Backend Built-in Database → Next
3. Configure:
   • UserID Type: username (matches the CONNECT packet's Username field, which is what MQTT_USER in secrets.h sets)
   • Password Hash: bcrypt
   • Salt Rounds: 10 (valid range 5–10; higher is better)
4. Create.

The moment an authenticator exists, EMQX stops accepting anonymous connections. Existing sessions stay up until they next reconnect, so there is a grace period — but create the accounts in step 2 immediately, and expect Home Assistant to fall off the broker until you give it credentials too.

2. Create one account per client

Click the authenticator row you just created, then the Users tab → Add:

Username	Used by
soil-node	every ESP32 node (they share this account; the MQTT client id is what stays unique, derived from each MAC)
homeassistant	the HA MQTT integration

Separate accounts matter here: it lets you write the ACLs in step 3, and it means rotating the node credential doesn't knock HA off the broker.

Use long random passwords. Generate them where they will not land in a terminal transcript, e.g. write straight to a file:

openssl rand -base64 24 > ~/soil-node.pass    # then open the file to read it

3. Restrict what each account may do (recommended)

Access Control → Authorization → Built-in Database, then add rules.

For soil-node — it only ever publishes, and never subscribes:

Action	Topic	Permission
Publish	soil/#	Allow
Publish	homeassistant/sensor/#	Allow
Subscribe	#	Deny

For homeassistant:

Action	Topic	Permission
Subscribe	homeassistant/#	Allow
Subscribe	soil/#	Allow
Publish	homeassistant/status	Allow

Then set no-match action to Deny in the authorization settings. Leaving it at the default Allow makes the rules above cosmetic — anything not explicitly matched is still permitted.

4. Fill in include/secrets.h

Already pre-filled with the broker address. Replace the four CHANGEME values:

#define WIFI_SSID     "..."
#define WIFI_PASSWORD "..."
#define MQTT_HOST     "192.168.1.31"
#define MQTT_PORT     1883
#define MQTT_USER     "soil-node"
#define MQTT_PASSWORD "..."

This file is gitignored. The broker IP is deliberately not in secrets.h.example, because that template is committed and the Gitea repo is public.

Why port 1883 and not 8883

TLS is available on 8883, but PubSubClient over WiFiClientSecure means shipping a CA bundle and paying a full handshake on every deep-sleep wake — meaningful battery cost on the remote nodes for a sensor reading that is not confidential, on a LAN. Plain 1883 with per-account ACLs is the sensible trade here. Revisit if these ever cross a network you don't control.

5. Point Home Assistant at EMQX

Settings → Devices & Services → MQTT → Configure.

• Broker 192.168.1.31, port 1883
• Username homeassistant, password from step 2
• Enable discovery, discovery prefix homeassistant (must match HA_DISCOVERY_PREFIX in include/config.h)

If MQTT is already configured against a different broker, repoint it — nodes publishing to EMQX will never appear in an HA that is listening to Mosquitto somewhere else. This is the single most common reason a node looks healthy on the wire but produces no entities.

6. Flash and verify

pio run -e mains -t upload -t monitor

Expected serial output:

=== Soil Node A1B2C3 (aa:bb:cc:a1:b2:c3) fw 1.0.0 ===
profile: mains | publishing every 60s
wifi: 192.168.1.x, rssi -55
mqtt: connecting to 192.168.1.31:1883 as soil-node-a1b2c3
discovery: publishing entities for soil-node-a1b2c3
state: {"node_id":"soil-node-a1b2c3","moisture_1":...}

Watch the broker side independently:

python3 tools/mqtt_watch.py --host 192.168.1.31 --user soil-node

Then confirm in HA: Settings → Devices & Services → MQTT → Soil Node XXXXXX with 6 moisture entities plus the diagnostics.

Troubleshooting

mqtt: connect failed, state N — N is PubSubClient's code:

N	Meaning	Likely cause
4	Bad credentials	MQTT_USER/MQTT_PASSWORD don't match the EMQX user
5	Not authorized	Authenticated, but ACL denied the connection
3	Server unavailable	Broker reachable but refusing
-2	Connect failed	TCP never established — wrong IP, firewall, VLAN
-4	Connection timeout	Broker accepted TCP but never sent CONNACK

Node publishes but no entities in HA. Almost always HA pointed at a different broker (step 5), or a discovery-prefix mismatch. Check that homeassistant/sensor/soil-node-xxxxxx/moisture_1/config exists on the broker with the watcher script.

Entities appear then go unavailable. On the mains profile that is the availability topic plus last-will doing its job — the node really did drop. On the battery profile it means expire_after elapsed, so the node missed more than ~2.5 sleep intervals.

Entities show unknown rather than a number. That is the firmware reporting a probe outside its calibrated window as null on purpose, not a transport problem. See CALIBRATION.md.