Internet Watchdog — MQTT & Home Assistant Reference

PF-WATCHDOG-001 MQTT topics, state payloads, commands, and Home Assistant auto-discovery entities.
Broker: any MQTT 3.1.1 broker on the LAN. No TLS. No authentication required (configurable).

For platform base MQTT topics (availability, relay, telemetry, power), see the Platform MQTT/HA Reference.

Overview

The Internet Watchdog adds 2 publish topics and 3 command topics on top of the platform's base MQTT surface. It also registers 8 Home Assistant discovery entities for automatic dashboard integration.

Topic prefix

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

{mqtt_topic}/watchdog/...

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

Topics at a Glance

State Payload

Topic: {mqtt_topic}/watchdog/state
Retained: Yes
QoS: 0
Cadence: On every state change and every 60 seconds (heartbeat)

Payload

{
  "state": "monitoring",
  "internet_up": true,
  "enabled": true,
  "relay": true,
  "reboot_count": 0,
  "total_reboots": 5,
  "total_outages": 3,
  "consecutive_fails": 0,
  "scheduled_reboot": "04:00",
  "uptime_percent": 99.7,
  "last_check": "2026-02-11T10:30:00Z",
  "last_outage": "2026-02-10T03:15:22Z",
  "last_reboot": "2026-02-10T03:17:52Z"
}

Fields

When state is published

• After every ping check (whether state transitions or not)
• On enable/disable
• On stats reset
• On state machine transitions (grace → reboot, post-reboot, cooldown, max retries)
• On scheduled reboot trigger
• Heartbeat: every 60 seconds unconditionally

Event Payload

Topic: {mqtt_topic}/watchdog/event
Retained: No
QoS: 0

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

Payload

{
  "event": "outage_detected",
  "reboot_count": 0
}

Fields

Event types

Commands

Enable / Disable Monitoring

Topic: {mqtt_topic}/watchdog/enabled/set
Payload: ON or OFF (case-insensitive)

Publishes updated state immediately after.

Trigger Router Reboot

Topic: {mqtt_topic}/watchdog/reboot/set
Payload: PRESS

Triggers a manual router power-cycle. Ignored if device is already in rebooting or post_reboot_grace state.

Publishes manual_reboot event and updated state.

Reset Statistics

Topic: {mqtt_topic}/watchdog/stats/reset/set
Payload: PRESS

Resets all cumulative statistics to zero (total_reboots, total_outages, uptime counters, timestamps). Persists to NVS.

Publishes updated state immediately after.

Home Assistant Auto-Discovery

The device publishes HA discovery configs on MQTT connect. Discovery topics follow the standard pattern:

homeassistant/<component>/<unique_id>/config

All entities include:

• unique_id derived from device identity
• availability_topic pointing to {mqtt_topic}/availability
• device block with name, model, manufacturer, firmware version

Entities

1. Internet Status (Binary Sensor)

Shows as Connected / Disconnected in HA.

2. Watchdog State (Sensor)

Displays the current state machine state as text.

3. Total Reboots (Sensor)

4. Uptime Percentage (Sensor)

5. Scheduled Reboot (Sensor)

Displays "04:00" or "Disabled".

6. Monitoring Switch

Toggle switch in HA to enable/disable monitoring.

7. Reboot Router Button

One-tap button in HA to trigger a manual router reboot.

8. Reset Statistics Button

One-tap button in HA to zero all cumulative stats.

Example Home Assistant Automations

Push Notifications for All Events

This single automation covers all 9 watchdog event types. Each event sends a descriptive push notification to your phone via the Home Assistant Companion App.

Prerequisites:

• Home Assistant with MQTT integration connected to the same broker
• Home Assistant Companion App installed on your phone
• Replace notify.mobile_app_your_phone with your device's notify service (found in Developer Tools → Services)

alias: PumpFuse Internet Watchdog Alerts
triggers:
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: internet_restored
    id: restored
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: max_retries_exceeded
    id: max_retries
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: outage_detected
    id: outage
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: manual_reboot
    id: manual
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: scheduled_reboot
    id: scheduled
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: reboot_started
    id: reboot_started
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: enabled
    id: enabled
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: disabled
    id: disabled
  - trigger: mqtt
    topic: pumpfuse/+/watchdog/event
    value_template: "{{ value_json.event }}"
    payload: device_online
    id: device_online
conditions: []
actions:
  - action: notify.mobile_app_your_phone
    data:
      title: Internet Watchdog
      message: >-
        {% if trigger.id == 'restored' %}
          Internet restored after {{ trigger.payload_json.reboot_count }} reboot(s)
        {% elif trigger.id == 'max_retries' %}
          Internet still down after {{ trigger.payload_json.reboot_count }} reboots — needs attention
        {% elif trigger.id == 'outage' %}
          Internet outage detected — monitoring
        {% elif trigger.id == 'manual' %}
          Manual reboot triggered — router restarting
        {% elif trigger.id == 'scheduled' %}
          Scheduled reboot — router restarting
        {% elif trigger.id == 'reboot_started' %}
          Router power cycled (reboot #{{ trigger.payload_json.reboot_count }})
        {% elif trigger.id == 'enabled' %}
          Watchdog monitoring enabled
        {% elif trigger.id == 'disabled' %}
          Watchdog monitoring disabled
        {% elif trigger.id == 'device_online' %}
          PumpFuse device came online
        {% endif %}
mode: parallel
max: 5

Notes:

• The + wildcard in pumpfuse/+/watchdog/event matches any device ID, so one automation handles all PumpFuse devices.
• mode: parallel with max: 5 allows multiple events to fire simultaneously (e.g., outage_detected followed immediately by reboot_started).
• To notify multiple phones, add additional notify.mobile_app_* actions. You can also create a notify group to notify all phones with a single action.
• Push notifications do not expire by default in the HA Companion App — they persist until dismissed.

Dashboard Card (Lovelace)

type: entities
title: Internet Watchdog
entities:
  - entity: binary_sensor.<device>_internet_up
    name: Internet Status
  - entity: sensor.<device>_watchdog_state
    name: State
  - entity: sensor.<device>_uptime_percent
    name: Uptime
  - entity: sensor.<device>_total_reboots
    name: Lifetime Reboots
  - entity: sensor.<device>_scheduled_reboot
    name: Scheduled Reboot
  - entity: switch.<device>_watchdog_enabled
    name: Monitoring
  - entity: button.<device>_trigger_reboot
    name: Reboot Router
  - entity: button.<device>_reset_stats
    name: Reset Stats

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

Common Notes

Platform base topics

The platform publishes additional MQTT topics that are always available regardless of product:

Stale retained messages

After OTA firmware update, the previous watchdog/state retained message persists until the device publishes a new one (within 60 seconds of boot, or immediately on first state change).

MQTT broker configuration

The MQTT broker host, port, username, and password are configured at the platform level via BLE provisioning or REST API (POST /api/v1/config). The watchdog product does not add any MQTT-specific configuration — it uses the platform's connection.