Home Assistant

Home Assistant Integration

DOCSight can publish all channel data to Home Assistant via MQTT Auto-Discovery. This is entirely optional and not required to use DOCSight.

Setup

1. Make sure you have an MQTT broker running (e.g., Mosquitto)
2. In DOCSight Settings, expand the MQTT Broker section
3. Enter your broker host, port, and credentials
4. Topic Prefix: This controls where DOCSight publishes measurement data (e.g. docsight/health, docsight/channel/ds_ch1). The default is docsight. You can change it to anything you like, but it has nothing to do with the HA discovery prefix (see below).
5. Save. DOCSight immediately starts publishing.
6. In Home Assistant, the sensors appear automatically under the docsight device.

How it works

DOCSight publishes two types of MQTT messages:

Type	Topic Pattern	Purpose
Discovery configs	homeassistant/sensor/docsight/…/config	Tells HA which sensors exist and where to find their data
Sensor data	{topic_prefix}/health, {topic_prefix}/channel/…	The actual measurement values

The discovery prefix defaults to homeassistant (the HA default). If you changed your HA discovery prefix, set MQTT_DISCOVERY_PREFIX accordingly in DOCSight (Settings or .env).

Availability

DOCSight uses MQTT Last Will and Testament (LWT) so that sensors show as unavailable in Home Assistant when DOCSight is offline:

• On connect: publishes online to {topic_prefix}/status (retained)
• On clean shutdown: publishes offline before disconnecting
• On unexpected disconnect: the broker automatically publishes offline via LWT

All sensors reference this status topic. No manual configuration needed.

Additionally, DOCSight publishes a dedicated Status binary sensor (binary_sensor.docsight_status with device_class: running) that directly reflects the LWT status. This gives you a quick at-a-glance indicator in HA dashboards and can be used in automations to detect when DOCSight goes offline.

Device Link

By default, the HA device page links to http://docsight:{port}. If DOCSight runs behind a reverse proxy, set PUBLIC_URL in your .env (e.g. https://docsight.example.com) so the link works from anywhere.

TLS

DOCSight automatically enables TLS when using MQTT port 8883. For self-signed certificates, set MQTT_TLS_INSECURE=true in your .env to skip certificate verification.

Important

• The Topic Prefix in DOCSight Settings is not the HA discovery prefix. It only controls where your data gets published.
• If you see data in your MQTT broker (e.g. via MQTT Explorer) but HA doesn't detect the sensors, a discovery prefix mismatch is the most likely cause.

Sensors

Enabled by Default

DOCSight publishes many entities but only enables the most important ones by default. The rest can be enabled manually in Home Assistant (Settings > Devices > DOCSight > click on any disabled entity > Enable).

Enabled by default:

Sensor	Unit	Description
docsight_health		Overall health (good/tolerated/marginal/critical)
docsight_status		DOCSight online/offline (binary_sensor, device_class: running)
docsight_health_details		Detail text (human-readable issue summary)
docsight_ds_power_avg	dBmV	Average downstream power
docsight_ds_snr_min	dB	Minimum downstream SNR
docsight_ds_snr_max	dB	Maximum downstream SNR
docsight_ds_snr_avg	dB	Average downstream SNR
docsight_ds_correctable_errors		Total correctable errors
docsight_ds_uncorrectable_errors		Total uncorrectable errors
docsight_us_power_avg	dBmV	Average upstream power
docsight_gaming_quality_score	%	Gaming quality score (0-100)
docsight_gaming_quality_grade		Gaming quality grade (A/B/C/D/F)

Disabled by default (enable manually if needed):

Sensor	Unit	Description
docsight_ds_total		Number of downstream channels
docsight_ds_power_min	dBmV	Minimum downstream power
docsight_ds_power_max	dBmV	Maximum downstream power
docsight_us_total		Number of upstream channels
docsight_us_power_min	dBmV	Minimum upstream power
docsight_us_power_max	dBmV	Maximum upstream power

Per-Channel Sensors (~37 DS + 4 US)

Each DOCSIS channel gets its own set of sensors (all disabled by default):

• sensor.docsight_ds_ch{id} -- State: Power (dBmV)
  • Attributes: frequency, modulation, snr, errors, docsis_version, health
• sensor.docsight_ds_ch{id}_snr -- State: SNR (dB)
  • Dedicated sensor for per-channel SNR graphing
• sensor.docsight_us_ch{id} -- State: Power (dBmV)
  • Attributes: frequency, modulation, multiplex, docsis_version, health

Tip: The per-channel SNR sensors let you graph individual channel signal quality over time. Enable only the channels you care about under Settings > Devices > DOCSight > Entities.

Troubleshooting

Sensors don't appear in HA

1. Check that your MQTT broker is reachable (use the "Test Connection" button in DOCSight Settings)
2. Verify data is being published (use MQTT Explorer or mosquitto_sub -t '#' -v)
3. Make sure your HA MQTT integration uses the default discovery prefix homeassistant
4. The DOCSight Topic Prefix should be something simple like docsight (the default)
5. Restart DOCSight after changing MQTT settings

Sensors appear but show "unavailable"

• DOCSight may not be running. Check docker ps and docker logs docsight.
• If DOCSight just started, wait for the first poll cycle or trigger a manual poll from the dashboard.
• Check DOCSight logs for MQTT connection errors.

Example Automations

Alert on health degradation

automation:
  - alias: "DOCSight Health Alert"
    trigger:
      - platform: state
        entity_id: sensor.docsight_health
        to: "critical"
    action:
      - service: notify.mobile_app
        data:
          title: "Internet Health: Critical"
          message: "{{ states('sensor.docsight_health_details') }}"

Track upstream power over time

Add sensor.docsight_us_power_avg to a History Graph card in your HA dashboard.