Channel Rebonding: Tracking Channel Lifecycle Without Losing History

[kwschulz]

TL;DR

When a modem reboots and bonds to different channels, existing sensor entities show "Unknown" while new channels have no entities. Rather than choosing between entity stability and channel tracking, what if channel lifecycle itself became valuable diagnostic data?

---

Background: Why Channel IDs Are Used

Cable modems display channel data in tables like this:

Row	Channel ID	Frequency	Power	SNR
1	21	237 MHz	0.5	41.4
2	29	759 MHz	-1.6	40.9
3	33	783 MHz	-3.0	40.2

Two numbers could be used for entity naming:

• Row number (1, 2, 3...) - the display position
• Channel ID (21, 29, 33...) - the DOCSIS Channel ID assigned by the ISP's CMTS

Channel ID was chosen for several reasons:

1. ISP diagnostics context: When troubleshooting with an ISP, they ask "what's the SNR on channel 21?" not "what's your first channel's SNR?"

2. Frequency correlation: Channel ID maps to specific frequency ranges. Channel 21 is always ~237 MHz. Tracking interference on a frequency means tracking that specific channel.

3. Error accumulation: Corrected/uncorrected errors accumulate per channel. If channel 21 has errors, tracking channel 21's history specifically matters.

4. DOCSIS 3.1 disambiguation: DOCSIS 3.1 modems have both SC-QAM and OFDM channels that can share the same Channel ID:

   QAM  Channel 33 @ 600 MHz
   OFDM Channel 33 @ 750 MHz  <- Same ID, different physical channel
   

   Using (channel_type, channel_id) as the composite key creates separate entities like sensor.ds_qam_ch_33_power and sensor.ds_ofdm_ch_33_power.

Why not row index? Index-based entities (slot_1, slot_2) seem appealing for stability, but channel tables are often fragmented - gaps appear when channels are unlocked. Row 1 might be Channel 5, row 2 might be Channel 13. The index does not provide meaningful continuity.

---

The Problem: Channel Rebonding

When a modem reboots (power outage, firmware update, ISP maintenance), it re-negotiates with the CMTS. The CMTS may assign different channels based on network conditions.

Current Behavior

Day 1: User installs integration
├── Modem has channels: 21, 29, 33
├── Entities created: ds_qam_ch_21, ds_qam_ch_29, ds_qam_ch_33
└── All show data ✓

Day 15: Modem reboots, CMTS assigns different channels
├── Modem now has: 22, 30, 34
├── Entities still only: ds_qam_ch_21, ds_qam_ch_29, ds_qam_ch_33
├── ds_qam_ch_21 → lookup fails → "Unknown" ✗
├── ds_qam_ch_22 → no entity exists → data discarded ✗
└── User must restart HA to fix

Result:

• Old entities show "Unknown" or "Unavailable"
• New channels have data but no entities to display it
• History graphs have issues (see home-assistant/frontend#27819)
• Home Assistant restart required to create entities for current channels

---

User Reports

Issue #42 comment (SB8200):

"The bottom channel numbers correspond to the Channel ID #s assigned, not the order of the Channels as listed on the page"

Issue #94 comment (TC4400):

"I did notice some DS channels that my modem doesn't have: 13,14,15,16,36,47,48,49. It's also missing channels that my modem does have: 8,9,10,11,33,34,35,36,37"

---

Reframing the Problem

Instead of viewing channel changes as a problem to hide, what if channel lifecycle is valuable diagnostic data?

A chart showing when channels were disconnected and new ones added over the past month could reveal:

• ISP maintenance patterns
• Network instability periods
• Correlation between channel changes and connectivity issues

The goal becomes:

• Maintain full history for all channels ever seen
• Show only active channels in normal dashboard views
• Track channel lifecycle as meaningful diagnostic information
• Give users control over how inactive channel data is handled

---

Proposed Behavior

Day 1: User installs integration
├── Modem has channels: 21, 29, 33
├── Entities created: ds_qam_ch_21, ds_qam_ch_29, ds_qam_ch_33
├── Each has attribute: state=active, last_seen=now
└── All show data ✓

Day 15: Modem reboots, CMTS assigns different channels
├── Coordinator fetches data: channels 22, 30, 34
├── Integration detects:
│   ├── Channels 21, 29, 33 are MISSING from new data
│   └── Channels 22, 30, 34 are NEW (no entities)
├── For missing channels (21, 29, 33):
│   ├── Keep entity
│   ├── Set state=inactive, last_seen=Day 15
│   └── Value shows "Inactive" state
├── For new channels (22, 30, 34):
│   ├── Create new entities dynamically
│   └── Set state=active, last_seen=now
└── No restart needed ✓

What the User Sees

Default dashboard (filtered to active channels):

DS QAM Ch 22 - Power: -1.2 dBmV
DS QAM Ch 30 - Power: -2.4 dBmV
DS QAM Ch 34 - Power: -1.8 dBmV

History/diagnostic view (all channels):

DS QAM Ch 21 - Inactive (last seen: Jan 15)
              └── History graph shows data from Jan 1-15, then stops
DS QAM Ch 22 - Active
              └── History graph shows data from Jan 15 onwards

Trigger Options

Entity scanning for new/removed channels could be triggered by:

• Automatic: Detecting modem reboot via uptime reset
• Manual: Button on the integration page (e.g., "Scan Channels" below "Update Modem Data")

---

Questions for the Community

1. How often do your channels change? After every reboot? Rarely? Never noticed?

2. Is channel lifecycle data interesting to you? Would you look at a chart showing when channels came and went?

3. Should inactive entities be disabled by default?

   • HA allows auto-disabling entities - inactive channels could be hidden until manually enabled
   • Or keep them visible but clearly marked as inactive?

4. What retention policy makes sense for inactive channels?

   • Keep forever (preserve all history)
   • Auto-remove after configurable period
   • Manual cleanup via service call
   • No opinion yet - let's see how it works first

5. Automation impact: Do you reference specific channel entities in automations? Would a state change to "Inactive" break anything?

---

Related Issues & References

• #42 - Original design decision discussion (SB8200)
• #87 - OFDM channel type disambiguation (S33)
• #94 - User experiencing rebonding problem (TC4400)
• home-assistant/frontend#27819 - History graph issues with entities lacking recent data

---

Looking forward to your feedback!

[kwschulz]

v3.14 update — partial solution to this problem:

In designing the v3.14 architecture, channel rebonding came up during HA integration planning. The approach addresses the immediate usability issue but doesn't solve the historical data question raised in this discussion.

What v3.14 does:

1. Channel count sensors are derived from the current poll data (len(downstream), len(upstream)), not tied to per-channel entities. So channel counts always reflect reality even when per-channel entities haven't caught up.

2. "Reset Entities" button carries forward from v3.13 — removes all entities from the registry and reloads the integration. After rebonding, this creates fresh entities for the current channel set. Since channel IDs change, the new entities get new entity_ids — history for the old channels still exists in the recorder database but isn't linked to the new entities.

3. Stability detection — v3.14's orchestrator includes a ChannelStabilityMonitor (built for restart recovery) that detects when channel counts have stabilized across consecutive polls. This same mechanism could be reused to detect genuine channel changes and notify the user to press Reset Entities, filtering out transient bonding during boot-up.

What it doesn't solve:

• Historical data continuity across rebonding — after a reset, old channel history is orphaned under the old entity_ids. The graphs discussion in this thread is still an open question.
• Automatic handling — auto-reset was considered but deferred due to edge cases (ISP maintenance, signal flapping). Could be added as an opt-in setting if users want it.
• Incremental entity creation (adding new channels without resetting existing ones) is worth exploring but needs more thought around removal and replacement.

The full channel lifecycle tracking proposed here (active/inactive states, history preservation) would be the right long-term answer. This is a step toward it.

[mtheli]

Interesting discussion. I did some research on how other DOCSIS monitoring projects handle this:

Most projects avoid the problem entirely by using stateless time-series databases. For example, fritzdocsis (Prometheus exporter for Fritz!Box Cable) calls .Reset() on all gauge vectors before writing the current channel data on each poll cycle — every scrape is a clean snapshot, and Prometheus handles staleness natively when channels disappear.

The HA equivalent would be the Dispatcher Signal pattern used by Z-Wave JS and ZHA — store the async_add_entities callback, compare current vs. known channels on each coordinator update, create new entities via dispatcher signal, and remove stale ones via entity_registry.async_remove().

That said, I think the v3.14 approach (stability detection + manual Reset Entities) is a reasonable pragmatic step. The full dynamic lifecycle model can build on top of that foundation later.

[kwschulz]

v3.14-alpha.16 update — position mode solves the core rebonding problem.

The channel identity work that landed in v3.14-alpha.16 takes a different path than stability detection (my March 25 update) or the dispatcher pattern above — simpler, and already shipped.

Position mode (new default): entities key on channel_number — the modem's stable internal row position. When the CMTS reassigns IDs after a reboot, row 1 stays row 1, row 2 stays row 2. History is continuous. No "Unknown" states, no manual reset.

ID mode (preserved for upgrades): entities key on (channel_type, channel_id) — matches ISP diagnostics. Best when you want "channel 21's SNR over time" even if that means gaps when the ID reassigns.

Existing installs default to ID mode via v1→v2 migration so history stays intact. Switching is opt-in via config flow.

New dev tool — convert_channel_identity: migrates recorder statistics between modes using HA's async_update_statistics_metadata API. The rename runs on the recorder thread (FIFO-ordered with clear tasks) so historical data follows the mode switch. Works in both directions — run it from Developer Tools → Services after switching modes.

What's still open: position mode treats rebonding as stability, not an event. The dispatcher-signal lifecycle model is still the right answer for users who want "channel 21 disappeared on March 15" as diagnostic data. Both paths are legitimate — position mode ships first because "graphs don't break on reboot" is what most users want.

Anyone running on position vs id mode in beta — feedback welcome.

[ccpk1]

I wanted to circle back on this. After spending more time using the integration for real-world troubleshooting, I realized my earlier lifecycle and reconciliation proposal missed some of the nuance already captured here in #97. I probably came in a little too eager to jump in and help without fully absorbing the background first!

Going back through this thread and dealing with my own modem interference issues recently, I lean strongly toward the direction stated in the first posts here regarding ID mode being the best approach. The main takeaway is that channel identity matters, rebonding is a fact of life, and users need both dashboard stability and historical troubleshooting data.

While the recent proposed entity lifecycle work in the HA adapter wasn't the right fit to merge at the time, I do think it laid some really solid groundwork. It introduced a dedicated lifecycle owner, separated the policy from the registry mechanics, and created a reconciliation boundary that is much easier to extend.

Building on that groundwork, my feedback / proposal would be:

1. Treat physical channel identity as the long-term backend model.
Entities should be anchored strictly to the channel_id (e.g., `sensor.cable_modem_ds_qam_ch_12_power). The volatile row/index information should just be retained as an entity attribute. This keeps the backend perfectly aligned with the real physical modem and recorder history, while preserving UI flexibility.

**2. The "Channel Name" feature is more of a UI and automation workaround. **
I think I get why "Channel Name" was introduced—it kept static dashboards tidy and prevented hardcoded automations from breaking when ISPs shuffled indices. But with a stronger lifecycle model, we don't need to sacrifice technical accuracy for UI maintenance.

For dashboards, pairing ID-based entities with a frontend card like auto-entities, the dashboard maintains itself dynamically. Here is a quick, real-world example of how auto-entities completely replaces the need for the Channel Name feature. It pulls the stable ID entities but sorts them perfectly using the index attribute:

type: custom:auto-entities
card:
  type: history-graph
  title: Downstream Power (dBmV)
  hours_to_show: 24
filter:
  include:
    - entity_id: sensor.cable_modem_ds_*_power
sort:
  method: attribute
  attribute: channel_index # Dynamically sorts by the modem's current physical layout
  numeric: true

For automations and custom monitors (like the custom Signal Health template I posted earlier), we should probably start thinking about this at the integration or device level anyway. Relying on static entity names is brittle because HA encourages users to rename things. By utilizing modern Jinja functions like device_entities('cable_modem') or integration_entities('cable_modem_monitor') in our templates, we can dynamically aggregate the entities and data on the backend grabbing these by attribute tags we control rather than name. This means users can name things whatever they want, we don't have to care, the ISPs can shuffle the channels, and the automations will never break. This is how I handle aggregations in other integrations I've built.

3. Support 3 reconciliation modes for different user needs.
There isn't one "correct" behavior here. A cleaner long-term model should give users the choice:

• Automatic: Strictly mirror the modem. Add new channels, remove dropped ones all dynamically.
• Add-Only: Add new channels, but leave dropped channels as unavailable. (This is critical for troubleshooters who need to preserve historical HA graph data when a channel dies).
• Manual: Do not discover or delete entities unless explicitly requested.

4. Make Reconciliation Timing Configurable.
Startup reconciliation is a great baseline, but DOCSIS networks dynamically shift profiles and drop channels mid-uptime. To reflect the actual channel lifecycle well, we should offer a configuration toggle: Reconcile on Startup vs. Reconcile every poll (or continuously managed at runtime).

5. Expose these actions via HA Services.
Rather than UI buttons, exposing actions like cable_modem.reconcile (with discover, purge, or full_sync payloads) makes lifecycle handling automatable for power users, while keeping the default path clean for casual users.

6. Enhance the dashboard generator service to support dynamic layouts.
The integration already has a nice service for generating dashboards. We could easily enhance this to offer a "dynamic" output mode that generates a dashboard leveraging auto-entities. We can still support the basic, static build as it exists today for users who prefer not to use custom HACS cards. But for any new dynamic dashboards we generate, it makes perfect sense to structure the YAML around device IDs and attribute tags. This would give users a nice, rebonding-resilient dashboard right out of the box.

Additional thought on entity generation:
If we are touching how entities are named and created anyway, it might be the perfect time to align the naming approach with modern Home Assistant standards. By utilizing has_entity_name: true, adopting proper translation keys, leveraging device names. This isn't critical at the moment but worth considering while changes are being made. ( Note - If we take this approach, the entity naming prefix logic could be removed since the first portion of the entity name wil by default be driven by device name 'cable_modem" which the user will then be able to easily rename in bulk via standard features by changing the device name.)

Final Summary
I'm sure a significant amount of effort went into building out the position/channel name approach and the new convert_channel_identity migration tools, and there may be more rationale behind the scenes than is stated here. But from my research and limited experience so far, I don't think treating the UI position as the backend entity key is the right long-term move for the integration.

The fun of being the project owner is that you ultimately get to decide the direction, and I am genuinely fine with whatever you choose! But from my own experience maintaining projects, I know it is sometimes helpful to hear direct, honest feedback from someone using the tool with a different perspective. Please don't feel like you need to justify whatever decision you make—that isn't my intent here.

I also want to be clear that I didn't write this up as just a "wish list" for you to go build. This proposal is grounded heavily in modern HA best practices, and honestly, 60-70% of the groundwork is already sitting in my development environment. It's an architecture I've built successfully in other integrations.

If we can align on the specifics, my goal is to actually submit the PRs to build this out myself. I think this bridges the gap between preserving the great diagnostic data this integration pulls and playing nicely with Home Assistant's architecture. That being said, I completely understand if this isn't a priority for you right now given your current roadmap—I just wanted to put the offer and the perspective on the table!