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.