PumpFuse Platform — MQTT & Home Assistant Reference

Platform-level MQTT topics, payloads, commands, and Home Assistant auto-discovery entities available on every PumpFuse product.
Covers availability, status, relay control, power telemetry, and event notifications.

For product-specific MQTT topics and HA entities, see the product's own MQTT/HA Reference (e.g., Watchdog MQTT/HA).

Overview

Every PumpFuse device publishes 7 topics and subscribes to 3 command topics at the platform level. It also registers 3 Home Assistant discovery entities for automatic dashboard integration.

Topic Prefix

All topics use the device's configured MQTT base topic:

{base}/...

Where {base} is set during provisioning (default: pumpfuse/<device_id>). Example: pumpfuse/test-board.

Broker Connection

• Protocol: MQTT 3.1.1 (no TLS)
• Client ID: pumpfuse_<full_mac_hex> (6 octets, e.g., pumpfuse_aabbccddeeff)
• Authentication: optional, configured via BLE provisioning or REST POST /api/v1/config
• LWT: {base}/availability → "offline" (QoS 1, retained)

Topics at a Glance

Published (Device → Broker)

Subscribed (Broker → Device)

Published Topics

availability

Topic: {base}/availability
QoS: 1 | Retained: Yes

Published on MQTT connect. The broker publishes the LWT ("offline") if the device disconnects unexpectedly.

status

Topic: {base}/status
QoS: 1 | Retained: Yes
Cadence: On every state change and every 60 seconds (heartbeat)

{
  "product": "pf-watchdog",
  "firmware": "1.0.0",
  "wifi_connected": true,
  "mqtt_connected": true,
  "relay": true,
  "telemetry_active": true,
  "telemetry_interval_s": 5,
  "power_w_last": 12.345,
  "power_sample_ts_ms": 1739260200000,
  "uptime_s": 3600,
  "ip": "192.168.40.114"
}

When republished (on state change):

• WiFi connected/disconnected
• MQTT connected/disconnected
• Relay toggled
• Telemetry settings changed

event

Topic: {base}/event
QoS: 0 | Retained: No

Published at the moment a notable event occurs.

{
  "event": "relay_changed",
  "message": "ON",
  "ts_ms": 1739260200000
}

Platform event types:

📝 Product-specific events are published to the product's own event topic (e.g., {base}/watchdog/event), not to this platform event topic.

relay/state

Topic: {base}/relay/state
QoS: 1 | Retained: Yes

ON

Plain text: ON (relay closed, power flowing) or OFF (relay open).

Published on connect (initial state) and on every relay change.

telemetry/state

Topic: {base}/telemetry/state
QoS: 1 | Retained: Yes

{
  "active": true,
  "interval_s": 5
}

Published on connect and on every telemetry settings change.

telemetry/active/state

Topic: {base}/telemetry/active/state
QoS: 1 | Retained: Yes

ON

Plain text: ON or OFF. Published alongside telemetry/state for HA switch compatibility.

power

Topic: {base}/power
QoS: 0 | Retained: No

{
  "power_w": 12.345,
  "ts_ms": 1739260200000
}

Published at telemetry_interval_s intervals, only when telemetry_active is true.

Commands

relay/set

Topic: {base}/relay/set
Payload: ON or OFF (case-insensitive)

Publishes relay/state, status, and event (type relay_changed) immediately.

Invalid payload publishes an event with type invalid_command.

telemetry/set

Topic: {base}/telemetry/set
Payload: JSON object

{
  "active": true,
  "interval_s": 10
}

Publishes telemetry/state, telemetry/active/state, status, and event (type telemetry_changed) on success.

Invalid JSON or out-of-range values publish an event with type invalid_command.

telemetry/active/set

Topic: {base}/telemetry/active/set
Payload: ON or OFF (case-insensitive)

Simple toggle that keeps the existing interval_s unchanged. Designed for the HA telemetry switch entity.

Publishes same topics as telemetry/set.

Home Assistant Auto-Discovery

The device publishes HA discovery configs on every MQTT connect. All use QoS 1, retained.

Discovery topic pattern:

homeassistant/<component>/<object_id>_<entity_id>/config

Where <object_id> = pumpfuse_<mac[3]:mac[4]:mac[5]> (last 3 MAC octets, hex).

All entities include:

• unique_id derived from MAC
• availability_topic → {base}/availability
• device block with name, manufacturer ("PumpFuse"), model (product display name), identifiers

Entities

1. Relay Switch

Standard HA toggle switch for relay control.

2. Power Sensor

Displays current power draw. Updates at telemetry_interval_s when telemetry is active.

3. Telemetry Switch

Toggle switch to enable/disable power telemetry streaming.

Publish Cadence

The publisher task runs at 200ms resolution, checking for state changes and heartbeat/telemetry timers.

Example Home Assistant Dashboard

type: entities
title: PumpFuse Device
entities:
  - entity: switch.<device>_relay
    name: Relay
  - entity: sensor.<device>_power
    name: Power
  - entity: switch.<device>_telemetry
    name: Telemetry

Replace <device> with the device's object ID prefix (derived from device name).

Product MQTT Topics

Products add their own topics under {base}/<product>/.... For example, the watchdog adds:

Products also register additional HA discovery entities through the platform's discovery system. See each product's MQTT/HA Reference for details.