Cable Modem Monitor for Home Assistant

A custom Home Assistant integration that monitors your cable modem's signal quality, power levels and error rates, so line problems show up before they cause outages.

⭐ If you find this integration useful, please star this repo! It helps others find the project.

🤖 AI-Assisted Development: This project uses AI-assisted development (Claude) to accelerate implementation while maintaining human oversight for architecture and community decisions.

Quick Links

• Installation Guide
• Supported Modems
• Troubleshooting Guide
• Contributing Guide
• Development (for contributors)
• Changelog

---

Development

New contributor? Start with the Getting Started Guide (environment setup, running tests, your first commit).

Returning contributor? See the Contributing Guide for workflow, code style, and PR guidelines.

Architecture: Two runtime pip packages in packages/ (Core + Catalog) plus a thin HA adapter in custom_components/. A third package, Catalog Tools, holds the authoring tools (HAR analysis, YAML generation, verification) for contributors and maintainers; HA never installs it. See CONTRIBUTING.md for details.

---

At a Glance

What it monitors:

• 📊 Signal Quality: Power levels, SNR, frequency for every channel
• ⚠️ Error Tracking: Corrected & uncorrected errors per channel
• 🔌 Connection Health: Status, uptime, and last boot time
• 💓 Modem Health: Real-time ping, TCP and HTTP latency monitoring
• 📈 Trends: Full historical data for analysis and graphing

What it does:

• 🔄 Remote Control: Restart your modem from Home Assistant
• 🤖 Automation Ready: Trigger actions on signal degradation or errors
• 🔐 Local-Only: All processing on your Home Assistant instance — no cloud services
• 🛡️ Security Focused: CodeQL scanning
• 🔌 Plug & Play: Easy UI configuration, no YAML editing needed

See It In Action

Track your cable modem's health with comprehensive dashboards and real-time monitoring:

---

Features

Monitoring & Data Collection

• Comprehensive Channel Monitoring: Tracks all downstream and upstream channels
• Per-Channel Metrics: Power (dBmV), SNR (dB), frequency (Hz), corrected and uncorrected errors
• Summary Sensors: Total corrected and uncorrected downstream errors, where the modem's catalog entry declares them
• Unified Status: One sensor combining connection, health and DOCSIS lock (see Modem Status)
• System Information: Software version, uptime, channel counts, and last boot time
• Health Monitoring: Ping, TCP and HTTP latency, plus an automatic health status
• Login protection: Rejected credentials trip a circuit breaker that stops further login attempts until you re-enter credentials or reload the integration; on some modems repeated bad logins cause a lockout or even a restart

Control & Automation

• Modem Control: Restart your modem directly from Home Assistant
• Automation-Friendly: Last boot time sensor with timestamp device class for reboot detection
• Dashboard Ready: Create graphs and alerts based on signal quality

Developer Friendly

• Extensible: Each modem is a catalog entry of YAML config, with Python only for firmware quirks
• Well Tested: Core, Catalog, Catalog Tools and HA integration suites run in CI (badge above)
• Type Safe: Full type hints, mypy and pyright validation

Supported Modems

This integration supports modems from ARRIS, CommScope, Compal, Hitron, Motorola, Netgear, Sagemcom, SDMC, Sercomm, Technicolor and Ubee, including ISP-branded boxes such as Virgin Media and Xfinity. Compatibility varies with firmware and ISP customization.

View the Supported Modems List - Complete list with DOCSIS versions, ISP compatibility, verification status, and model timelines.

Help Expand Modem Support

The catalog grows when contributors with hardware step up. Two paths:

• Modem not listed? Use har-capture to record your modem's web interface, then file a request. See the Modem Request Guide for the user-facing walkthrough.
• Want to help more? If you have AI access, you can analyze captures and propose catalog entries yourself. See AI-Assisted Catalog Contribution.

Modem listed as ⏳ Awaiting? Report it working to help verify support.

Installation

HACS (Recommended)

Don't have HACS? Follow the HACS installation guide first.

1. Open HACS from the sidebar
2. Search for "Cable Modem Monitor"
3. Click Download
4. Restart Home Assistant

Testing a Beta Release

Betas don't auto-update; each one is a manual per-version install.

1. In HACS, open Cable Modem Monitor.
2. Click the ⋯ menu → Redownload.
3. Click Need a different version?.
4. Pick the desired beta from the Release dropdown.
5. Click Download and restart Home Assistant.

To return to stable: repeat the steps and pick the latest stable release.

Setup

1. Go to Settings → Devices & Services → Add Integration
2. Search for Cable Modem Monitor
3. Pick a manufacturer (or All to see every catalog entry)
4. Select your modem model and choose Channel Number mode (recommended — stable entity IDs across reboots) or Channel ID mode
5. Enter your modem's IP address (typically 192.168.100.1) and credentials if required

Options

After setup, configure via Settings → Devices & Services → Cable Modem Monitor → Configure:

• Host: Update modem IP / URL
• Credentials: Update username/password if your modem requires authentication
• Polling Interval: How often to fetch full modem status (30 seconds – 24 hours, default: 10 minutes)
• Health Check Interval: How often to run lightweight reachability probes (default: 30 seconds). Status comes from ICMP ping and a TCP connect; an HTTP HEAD measures latency where the modem supports it

Modem Model and Channel Identity are install-time choices, not editable here. See Known Limitations.

---

Available Sensors

All sensors use the cable_modem_ prefix. Supporting entities (system information, error totals and rates, latency, LAN statistics) sit in the device page's Diagnostic section.

Entity Naming Pattern:

System sensors: sensor.cable_modem_{metric} (e.g., sensor.cable_modem_status).

Channel sensor naming depends on the Channel Identity mode you picked at setup:

• Channel Number mode (recommended default — stable across reboots): sensor.cable_modem_{direction}_ch_{number}_{metric}
  • Example: sensor.cable_modem_ds_ch_1_power
  • Example: sensor.cable_modem_us_ch_3_frequency
• Channel ID mode (DOCSIS DCID-based): sensor.cable_modem_{direction}_{type}_ch_{id}_{metric}
  • Example: sensor.cable_modem_ds_qam_ch_1_power
  • Example: sensor.cable_modem_us_atdma_ch_3_frequency
  • DOCSIS 3.1 modems also have OFDM/OFDMA channels: sensor.cable_modem_ds_ofdm_ch_1_power

Channel Identity is set when you add the integration; to switch it, see Known Limitations.

Modem Status

• sensor.cable_modem_status: One state combining connection, health probes and DOCSIS lock, such as Operational, Unresponsive, Auth Failed, No Signal or Partial Lock. All ten states, in priority order, are in Understanding the Status Sensor.

System Information

• Modem Info: Detected model, with manufacturer, DOCSIS version, release date, and catalog status as attributes
• sensor.cable_modem_software_version: Modem firmware/software version
• sensor.cable_modem_last_boot_time: When the modem last rebooted (timestamp device class); Home Assistant renders it as relative age ("5 days ago"), which doubles as uptime
• sensor.cable_modem_ds_channel_count: Number of active downstream channels
• sensor.cable_modem_us_channel_count: Number of active upstream channels

Firmware and hardware versions also appear on the device info card. Other system fields your modem reports (provisioned speeds, for example) become sensors automatically, and LAN interface statistics get per-interface sensors for bytes, packets, errors, and drops.

Latency Monitoring

• sensor.cable_modem_ping_latency: Ping response time in milliseconds
• sensor.cable_modem_tcp_latency: TCP connect time in milliseconds
• sensor.cable_modem_http_latency: HTTP response time in milliseconds

Summary Sensors

• sensor.cable_modem_total_corrected_errors: Total corrected errors summed over downstream channels
• sensor.cable_modem_total_uncorrected_errors: Total uncorrected errors summed over downstream channels
• sensor.cable_modem_rate_corrected_errors: Corrected errors per minute
• sensor.cable_modem_rate_uncorrected_errors: Uncorrected errors per minute

The integration sums the totals from per-channel counters; no modem in the catalog reports one itself. What they cover depends on the modem:

• DOCSIS 3.1 and 4.0 modems: SC-QAM channels only. OFDM counters are not added in.
• DOCSIS 3.0 modems: every downstream channel, since all are SC-QAM.
• No totals: some catalog entries declare none, and these four sensors are not created. Where the modem reports per-channel error counts, those sensors still are, and a generated dashboard shows a note in place of the error graphs.

Per-Channel Downstream Sensors (for each channel)

Replace {type} with channel type (qam, ofdm) and X with the channel number:

• sensor.cable_modem_ds_{type}_ch_X_power: Power level in dBmV
• sensor.cable_modem_ds_{type}_ch_X_snr: Signal-to-Noise Ratio in dB
• sensor.cable_modem_ds_{type}_ch_X_frequency: Channel frequency in Hz
• sensor.cable_modem_ds_{type}_ch_X_corrected: Corrected errors
• sensor.cable_modem_ds_{type}_ch_X_uncorrected: Uncorrected errors

Per-Channel Upstream Sensors (for each channel)

Replace {type} with channel type (atdma, ofdma) and X with the channel number:

• sensor.cable_modem_us_{type}_ch_X_power: Transmit power level in dBmV
• sensor.cable_modem_us_{type}_ch_X_frequency: Channel frequency in Hz

Controls

The integration registers three buttons under the modem device:

• Restart Modem: Reboots the modem remotely (requires modem credentials)
• Update Modem Data: Triggers an immediate poll outside the regular cadence
• Reset Entities: Clears entity registry entries for this modem (useful after a modem swap or schema migration)

Services

• cable_modem_monitor.generate_dashboard: Generates a Lovelace dashboard YAML tailored to your modem's channel layout. Configurable: which graphs to include (status card, downstream/upstream power/SNR/frequency, errors, latency), graph_hours window (1–168), and short-title mode.
• cable_modem_monitor.request_refresh: Triggers an immediate data poll for the selected device.
• cable_modem_monitor.request_health_check: Runs an immediate health probe (ICMP / TCP / HTTP) outside the regular cadence.
• cable_modem_monitor.convert_channel_identity: Renames recorder statistics from the previous Channel Identity mode to the current one, so historical graphs survive a remove-and-re-add in the other mode. Modem must be online.
• cable_modem_monitor.orphaned_statistics: Lists recorder statistics left behind by a mode switch, channel rebonding, or a prefix change; call again with execute: true to purge them. See Ghost Statistics in History.

Understanding the Values

Downstream Power (dBmV)

• Ideal range: -7 to +7 dBmV
• Acceptable: -15 to +15 dBmV
• Poor: Below -15 or above +15 dBmV

Signal-to-Noise Ratio (dB)

• Excellent: Above 40 dB
• Good: 33-40 dB
• Acceptable: 25-33 dB
• Poor: Below 25 dB

Upstream Power (dBmV)

• Ideal range: 35-50 dBmV
• Acceptable: 30-55 dBmV
• Poor: Below 30 or above 55 dBmV

Corrected vs Uncorrected Errors

• Corrected errors: Normal in small amounts; modem can fix these
• Uncorrected errors: Indicate data loss; any sustained increase is concerning
• Monitor trends: Sudden increases may indicate line issues

Examples

Ready-to-use dashboard and automation examples are available in the Examples Guide.

Includes:

• Dashboard generator service — auto-generates Lovelace YAML tailored to your modem's channels
• Complete manual dashboard YAML for monitoring all channels
• Automations for error alerts, SNR warnings, and auto-restart
• Last boot time display format options

Removing the Integration

To remove a single modem:

1. Go to Settings → Devices & Services → Cable Modem Monitor.
2. Click the modem entry, open the ⋯ menu, and choose Delete.
3. Confirm. The integration logs out of the modem, removes its device and entities, and deletes the per-entry state it stored (the channel-bond baseline) and the entry's credentials. No restart is required.

Deleting the integration does not purge recorded sensor history; your Home Assistant recorder settings govern it. To clear leftover channel history, use the orphaned_statistics service or follow Ghost Statistics in History. To clear state history, see Leftover State History.

To uninstall completely, delete every modem entry as above, then remove Cable Modem Monitor from HACS (open it, ⋯ menu → Remove) and restart Home Assistant.

Known Limitations

• Model is fixed at install time. It identifies which modem this entry monitors. To point at a different modem, remove the integration and add it again.
• Channel Identity (number vs ID) is chosen at setup and not changeable afterward. To switch modes, remove and re-add the integration in the other mode, then call the convert_channel_identity service to carry your recorder statistics across.
• Remote restart depends on the modem. The Restart button appears only for modems whose firmware exposes a supported reboot path; others are monitored read-only.
• Channel-bond change alerts track totals only. The notification fires when the total downstream or upstream channel count changes, not on a per-type reshuffle that leaves the total unchanged (for example a DOCSIS 3.1 provisioning change that swaps one QAM channel for one OFDM channel).
• Requires a reachable modem interface on your LAN. Modems whose status page has been disabled by the ISP, or exposed only through the provider's cloud app, cannot be polled. See ISP Disabled Web Interface.

Troubleshooting

📖 The Troubleshooting Guide covers connection problems, missing sensors, and duplicate entities.

Privacy & Security

Privacy Protection

• 100% Local: All data stays on your Home Assistant instance — no cloud services
• Read-Only by Default: Only reads data from your modem; the only write action is a user-invoked restart
• Diagnostic Logs: Private IPs (RFC1918) and filesystem paths are scrubbed from log lines included in the diagnostics file. Modem identity (model, firmware, channel data) is included verbatim — review before sharing publicly. The diagnostics file embeds a _review_before_sharing checklist to help you spot anything sensitive
• HAR Captures: When onboarding a new modem, har-capture sanitizes HAR files (passwords, tokens, MACs) before you submit them
• Credentials: Kept in the Home Assistant config entry; the integration sends them only to the modem

Security Features

• CodeQL Scanning: Automated security analysis on every push to the main and feature branches, every pull request to main, and weekly.
  • Standard CodeQL Python suite: 100+ security queries covering OWASP Top 10 and broad CWE coverage — command injection, hardcoded credentials, SSL/TLS misuse, path traversal, XXE, and more.
  • Custom queries: One project-specific query at cable-modem-monitor-ql/queries/no_timeout.ql flags HTTP requests without explicit timeouts, which would otherwise hang the integration on unreachable modems.
• Security Documentation: See CodeQL Testing Guide for details
• Vulnerability Reporting: See SECURITY.md for responsible disclosure

Authentication Support

• HTTP Basic Authentication
• Form and JSON logins, including nonce, salted (PBKDF2) and encrypted (SJCL) variants
• Bearer-token, JSON-RPC, URL-token and HNAP/SOAP logins
• CBN logins (Compal and ARRIS)
• No authentication (for open modems)

License

MIT License - see LICENSE file for details. The project's names and logos are not covered by it; see TRADEMARKS.md.

Support

Cable Modem Monitor is maintained by one person, in the evenings, around a day job. What to expect from replies and reviews, and where to ask what, is in SUPPORT.md.

• GitHub Issues
• Home Assistant Community Forum

Resources

External Resources

• Home Assistant Releases
• HACS Brand Repository

Related Solent Labs Projects

• har-capture - Zero-dependency Python library for sanitizing HAR files. Contributors use it to capture a modem's web interface for a modem request without exposing passwords or network credentials.

Legal & Safety

⚠️ Disclaimer: This integration interacts with the user-facing diagnostic interface (LAN side) of your modem. It does not modify boot files, interact with the ISP side (WAN), or bypass any service limits.

Solent Labs™ is not affiliated with Arris, Motorola, Netgear, or any ISP. All product names are trademarks of their respective owners. Use this software at your own risk.