MQTT & Home Assistant Reference

PF-SUMP-001  |  v1.1  |  Updated: 2026-02-27  |  Broker: any MQTT 3.1.1, LAN-only

Overview & Topics

The Sump Pump Monitor adds 6 publish topics and 7 command topics on top of the platform's base MQTT surface. It registers 23 Home Assistant discovery entities (26 total including 3 platform entities).

Topic prefix

{mqtt_topic}/sump/...

Where {mqtt_topic} is set during provisioning (default: pumpfuse/<device_id>).

Topics at a Glance

State Payload

Topic: {mqtt_topic}/sump/state  |  Retained: Yes  |  QoS: 0

Cadence: On every state change and every 60 seconds (heartbeat)

Payload

{
  "pump_running": false,
  "current_run_s": 0,
  "current_power_w": 0.0,
  "alerts": [],
  "protection_mode": "active",
  "protection_auto_disabled": false,
  "lockout_active": false,
  "lockout_remaining_s": 0,
  "lockout_retries_used": 0,
  "lockout_alert": null,
  "run_count_total": 87,
  "runs_last_24h": 7,
  "total_runtime_s": 2958,
  "last_outage_s": 0,
  "last_run_end_ms": 1708300000000,
  "last_run_dur_s": 34,
  "last_run_avg_w": 762.4,
  "last_run_peak_w": 812.0,
  "idle_w": 0.0,
  "active_w": 780.0,
  "on_threshold_w": 234.0,
  "inter_run_gap_mean": 21600.0,
  "alert_enable_mask": 7,
  "relay_cut_mask": 1,
  "inactivity_alert_min": 7200,
  "anomaly_lockout_min": 10,
  "lockout_max_retries": 3,
  "rhythm_hex": "000000010001000200010000...",
  "rhythm_head": 142,
  "rhythm_last_bin_ms": 1708300200000
}

Same 30 fields as REST GET /sump/status — all three interfaces use the same serializer. See REST API Reference for the full field table.

When state is published

• Pump starts or stops
• Alert fires or clears
• Lockout starts or ends
• Config changes
• Stats reset
• Heartbeat: every 60 seconds unconditionally

Cycle Payload

Topic: {mqtt_topic}/sump/cycle  |  Retained: Yes  |  QoS: 0

Cadence: On each completed pump cycle

{
  "start_ms": 1708299965000,
  "end_ms": 1708300000000,
  "dur_s": 35,
  "avg_w": 762.4,
  "peak_w": 812.0,
  "std_w": 18.7,
  "sample_count": 35,
  "samples": [210.5, 810.2, 795.0, 780.1, 770.3, 762.8]
}

Same 8 fields as REST GET /sump/last-run. See REST API Reference for the full field table.

Rhythm Payload

Topic: {mqtt_topic}/sump/rhythm  |  Retained: Yes  |  QoS: 0

Cadence: Every 5 minutes (on bin advance)

{
  "bins": "000000010001000200010000...",
  "head": 142,
  "last_bin_ms": 1708300200000
}

To reconstruct chronological order: start at head + 1 (wrapping at 288) and read 288 characters.

Alerts Payload

Topic: {mqtt_topic}/sump/alerts  |  Retained: Yes  |  QoS: 0

Cadence: On alert fire or clear

{
  "active": ["power_anomaly_low"],
  "history": [
    { "event": "alert_fired", "timestamp_ms": 1738886400000 },
    { "event": "alert_cleared", "timestamp_ms": 1738886420000 }
  ]
}

Learn Payload

Topic: {mqtt_topic}/sump/learn  |  Retained: Yes  |  QoS: 0

Cadence: On protection mode change or baseline update (after each cycle during learning)

{
  "mode": "active",
  "cycle_count": 87,
  "wattage_mean": 780.0,
  "wattage_cv": 8.2,
  "wattage_ready": true,
  "runtime_mean": 34.0,
  "runtime_cv": 28.5,
  "runtime_ready": true,
  "cycle_rate_mean": 7.2,
  "cycle_rate_cv": 45.0,
  "cycle_rate_ready": true,
  "inter_run_gap_mean": 21600.0,
  "inter_run_gap_cv": 38.0,
  "inter_run_gap_ready": true,
  "idle_w": 0.0,
  "active_w": 780.0
}

Same 17 fields as REST GET /sump/learn. See REST API Reference for the full field table and readiness thresholds.

Event Payload

Topic: {mqtt_topic}/sump/event  |  Retained: No  |  QoS: 0

Published at the moment an event occurs. Fire-and-forget.

Alert fired

{
  "event": "alert_fired",
  "alert": "power_anomaly_low",
  "timestamp_ms": 1738886400000,
  "power_w": 520.0,
  "run_dur_s": 12,
  "relay_cut": true
}

Alert cleared

{
  "event": "alert_cleared",
  "alert": "power_anomaly_low",
  "timestamp_ms": 1738886420000,
  "duration_s": 20
}

Power outage

{
  "event": "power_outage",
  "timestamp_ms": 1738800000000,
  "outage_s": 3600
}

Protection auto-disabled

{
  "event": "protection_auto_disabled",
  "alert": "power_anomaly_low",
  "timestamp_ms": 1738972800000
}

Mode change

{
  "event": "mode_change",
  "timestamp_ms": 1739145600000,
  "from": "learning",
  "to": "active"
}

Lockout reset

{
  "event": "lockout_reset",
  "timestamp_ms": 1739232000000
}

Device boot

{
  "event": "device_boot",
  "timestamp_ms": 1739318400000,
  "reason": "power_on"
}

Event types summary

Commands

Alert Enable Mask

Topic: {mqtt_topic}/sump/alert_enable/set  |  Payload: Integer 0–31

Bit positions: 0=power_anomaly_low, 1=power_anomaly_high, 2=long_run, 3=frequent_cycling, 4=inactivity

Relay Cut Mask

Topic: {mqtt_topic}/sump/relay_cut/set  |  Payload: Integer 0–7

Inactivity Alert Window

Topic: {mqtt_topic}/sump/inactivity_alert/set  |  Payload: Integer 1–43200 (minutes)

Anomaly Lockout Duration

Topic: {mqtt_topic}/sump/anomaly_lockout/set  |  Payload: Integer 1–480 (minutes)

Lockout Max Retries

Topic: {mqtt_topic}/sump/lockout_retries/set  |  Payload: Integer 1–10

Reset Lockout

Topic: {mqtt_topic}/sump/lockout/reset/set  |  Payload: PRESS

Clears active lockout, re-enables protection, resets retry counter.

Reset Statistics

Topic: {mqtt_topic}/sump/stats/reset/set  |  Payload: PRESS

Zeros all stats, clears history, resets learning. Device re-enters learning mode.

Home Assistant Auto-Discovery Entities

The device publishes HA discovery configs on MQTT connect. 26 entities total (23 product + 3 platform).

Binary Sensors (7)

Sensors (9)

Number Entities (5)

Buttons (2)

Platform Entities (3)

Example Automations

Push Notifications for All Sump Events

This single automation covers all sump pump event types via the HA Companion App.

alias: PumpFuse Sump Pump Alerts
triggers:
  - trigger: mqtt
    topic: pumpfuse/+/sump/event
    value_template: "{{ value_json.event }}"
    payload: alert_fired
    id: alert_fired
  - trigger: mqtt
    topic: pumpfuse/+/sump/event
    value_template: "{{ value_json.event }}"
    payload: alert_cleared
    id: alert_cleared
  - trigger: mqtt
    topic: pumpfuse/+/sump/event
    value_template: "{{ value_json.event }}"
    payload: power_outage
    id: power_outage
  - trigger: mqtt
    topic: pumpfuse/+/sump/event
    value_template: "{{ value_json.event }}"
    payload: protection_auto_disabled
    id: protection_auto_disabled
conditions: []
actions:
  - action: notify.mobile_app_your_phone
    data:
      title: Sump Pump Monitor
      message: >-
        {% if trigger.id == 'alert_fired' %}
          {% set names = {
            'power_anomaly_low': 'Low Power (dry run)',
            'power_anomaly_high': 'High Power (blockage)',
            'long_run': 'Excessive Run',
            'frequent_cycling': 'Short Cycling',
            'inactivity': 'Expected Run overdue'
          } %}
          Alert: {{ names.get(trigger.payload_json.alert,
                              trigger.payload_json.alert) }}
        {% elif trigger.id == 'alert_cleared' %}
          Cleared: {{ trigger.payload_json.alert }}
            ({{ trigger.payload_json.duration_s }}s)
        {% elif trigger.id == 'power_outage' %}
          Power outage detected
            ({{ trigger.payload_json.outage_s // 60 }} minutes)
        {% elif trigger.id == 'protection_auto_disabled' %}
          ⚠️ Protection auto-disabled for
            {{ trigger.payload_json.alert }}
        {% endif %}
mode: parallel
max: 5

Dashboard Card (Lovelace)

type: entities
title: Sump Pump Monitor
entities:
  - entity: binary_sensor.<device>_pump_running
  - entity: binary_sensor.<device>_power_anomaly_low
  - entity: binary_sensor.<device>_power_anomaly_high
  - entity: binary_sensor.<device>_long_run
  - entity: sensor.<device>_protection_mode
  - entity: sensor.<device>_runs_last_24h
  - entity: sensor.<device>_baseline_power
  - entity: button.<device>_reset_lockout
  - entity: button.<device>_reset_stats

Replace <device> with the device's object ID prefix.