DOCSIS 3.0 Upstream ATDMA Channel Statistics¶

Provides Access To DOCSIS 3.0 Upstream SC-QAM (ATDMA) Channel Statistics.

Endpoint¶

POST /docs/if30/us/atdma/chan/stats

Request¶

Use the SNMP-only format: Common → Request
TFTP parameters are not required.

Response¶

This endpoint returns the standard envelope described in Common → Response (status, message, device, data).

device is the top-level device identity block and contains device.mac_address and device.system_description (empty model when unavailable).

data is an object with the upstream channel entries plus an optional DWR window evaluation summary. Each entry contains the SNMP table index, the upstream channel_id, and an entry with configuration, status, and (where available) raw pre-EQ data (docsIf3CmStatusUsEqData).

Abbreviated Example¶

{
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "status": 0,
  "message": null,
  "data": {
    "entries": [
      {
        "index": 80,
        "channel_id": 1,
        "entry": {
          "docsIfUpChannelId": 1,
          "docsIfUpChannelFrequency": 14600000,
          "docsIfUpChannelWidth": 6400000,
          "docsIfUpChannelModulationProfile": 0,
          "docsIfUpChannelSlotSize": 2,
          "docsIfUpChannelTxTimingOffset": 6436,
          "docsIfUpChannelRangingBackoffStart": 3,
          "docsIfUpChannelRangingBackoffEnd": 8,
          "docsIfUpChannelTxBackoffStart": 2,
          "docsIfUpChannelTxBackoffEnd": 6,
          "docsIfUpChannelType": 2,
          "docsIfUpChannelCloneFrom": 0,
          "docsIfUpChannelUpdate": false,
          "docsIfUpChannelStatus": 1,
          "docsIfUpChannelPreEqEnable": true,
          "docsIf3CmStatusUsTxPower": 49.0,
          "docsIf3CmStatusUsT3Timeouts": 0,
          "docsIf3CmStatusUsT4Timeouts": 0,
          "docsIf3CmStatusUsRangingAborteds": 0,
          "docsIf3CmStatusUsModulationType": 2,
          "docsIf3CmStatusUsEqData": "0x08011800ffff0003...00020001",
          "docsIf3CmStatusUsT3Exceededs": 0,
          "docsIf3CmStatusUsIsMuted": false,
          "docsIf3CmStatusUsRangingStatus": "success"
        }
      },
      {
        "index": 81,
        "channel_id": 2,
        "entry": {
          "docsIfUpChannelId": 2,
          "docsIfUpChannelFrequency": 21000000,
          "docsIfUpChannelWidth": 6400000,
          "docsIfUpChannelModulationProfile": 0,
          "docsIfUpChannelSlotSize": 2,
          "docsIfUpChannelTxTimingOffset": 6436,
          "docsIfUpChannelRangingBackoffStart": 3,
          "docsIfUpChannelRangingBackoffEnd": 8,
          "docsIfUpChannelTxBackoffStart": 2,
          "docsIfUpChannelTxBackoffEnd": 6,
          "docsIfUpChannelType": 2,
          "docsIfUpChannelCloneFrom": 0,
          "docsIfUpChannelUpdate": false,
          "docsIfUpChannelStatus": 1,
          "docsIfUpChannelPreEqEnable": true,
          "docsIf3CmStatusUsTxPower": 48.5,
          "docsIf3CmStatusUsT3Timeouts": 0,
          "docsIf3CmStatusUsT4Timeouts": 0,
          "docsIf3CmStatusUsRangingAborteds": 0,
          "docsIf3CmStatusUsModulationType": 2,
          "docsIf3CmStatusUsEqData": "0x08011800ffff0001...0002",
          "docsIf3CmStatusUsT3Exceededs": 0,
          "docsIf3CmStatusUsIsMuted": false,
          "docsIf3CmStatusUsRangingStatus": "success"
        }
      }
    ],
    "dwr_window_check": {
      "dwr_warning_db": 6.0,
      "dwr_violation_db": 12.0,
      "channel_count": 2,
      "min_power_dbmv": 48.5,
      "max_power_dbmv": 49.0,
      "spread_db": 0.5,
      "is_warning": false,
      "is_violation": false,
      "extreme_channel_ids": [1, 2]
    }
  }
}

Data Fields¶

Field	Type	Description
`entries`	array	Upstream channel entries (same as prior format).
`dwr_window_check`	object	DWR evaluation summary, or null when unavailable.

DWR Window Check Fields¶

Field	Type	Units	Description
`dwr_warning_db`	float	dB	Warning threshold for the DWR spread.
`dwr_violation_db`	float	dB	Violation threshold for the DWR spread.
`channel_count`	int	—	Number of channels included in the evaluation.
`min_power_dbmv`	float	dBmV	Minimum transmit power across channels.
`max_power_dbmv`	float	dBmV	Maximum transmit power across channels.
`spread_db`	float	dB	Power spread across channels (max-min).
`is_warning`	bool	—	True when warning_db < spread_db <= violation_db.
`is_violation`	bool	—	True when spread_db > violation_db.
`extreme_channel_ids`	array	—	Channel IDs that define the min/max spread.

Channel Fields¶

Field	Type	Description
`index`	int	SNMP table index (OID instance) for this channel’s row in the CM table.
`channel_id`	int	DOCSIS upstream SC-QAM (ATDMA) logical channel ID.

Entry Fields¶

Field	Type	Units	Description
`docsIfUpChannelId`	int	—	Upstream channel ID (mirrors logical ID).
`docsIfUpChannelFrequency`	int	Hz	Center frequency.
`docsIfUpChannelWidth`	int	Hz	Channel width.
`docsIfUpChannelModulationProfile`	int	—	Modulation profile index.
`docsIfUpChannelSlotSize`	int	—	Slot size (minislot units).
`docsIfUpChannelTxTimingOffset`	int	—	Transmit timing offset (implementation-specific units).
`docsIfUpChannelRangingBackoffStart`	int	—	Initial ranging backoff window start.
`docsIfUpChannelRangingBackoffEnd`	int	—	Initial ranging backoff window end.
`docsIfUpChannelTxBackoffStart`	int	—	Data/backoff start window.
`docsIfUpChannelTxBackoffEnd`	int	—	Data/backoff end window.
`docsIfUpChannelType`	int	—	Channel type enum (e.g., `2` = ATDMA).
`docsIfUpChannelCloneFrom`	int	—	Clone source channel (if used).
`docsIfUpChannelUpdate`	bool	—	Indicates a pending/active update.
`docsIfUpChannelStatus`	int	—	Operational status enum.
`docsIfUpChannelPreEqEnable`	bool	—	Whether pre-equalization is enabled.
`docsIf3CmStatusUsTxPower`	float	dBmV	Upstream transmit power.
`docsIf3CmStatusUsT3Timeouts`	int	—	T3 timeouts counter.
`docsIf3CmStatusUsT4Timeouts`	int	—	T4 timeouts counter.
`docsIf3CmStatusUsRangingAborteds`	int	—	Aborted ranging attempts.
`docsIf3CmStatusUsModulationType`	int	—	Modulation type enum.
`docsIf3CmStatusUsEqData`	string	hex	Raw pre-EQ coefficient payload (hex string; raw octets).
`docsIf3CmStatusUsT3Exceededs`	int	—	Exceeded T3 attempts.
`docsIf3CmStatusUsIsMuted`	bool	—	Whether the upstream transmitter is muted.
`docsIf3CmStatusUsRangingStatus`	string	—	Ranging state name (e.g., `success`).

Notes¶

docsIf3CmStatusUsEqData contains the raw equalizer payload; decode to taps (location, magnitude, phase) in analysis workflows.
The hex string preserves original SNMP octets (for example FF stays FF, not UTF-8 encoded).
Use the combination of TxPower, timeout counters, and ranging status to corroborate upstream health with pre-EQ shape.
Channels are discovered automatically; no channel list is required in the request.
DWR warning and violation thresholds are evaluated against the min/max power spread for all channels returned.

DOCSIS 3.0 Upstream ATDMA Pre-Equalization¶

Provides Access To DOCSIS 3.0 Upstream SC-QAM (ATDMA) Pre-Equalization Tap Data For Plant Analysis (Reflections, Group Delay, Pre-Echo).

Endpoint¶

POST /docs/if30/us/scqam/chan/preEqualization

Request¶

Use the SNMP-only format: Common → Request
TFTP parameters are not required.

Response¶

This endpoint returns the standard envelope described in Common → Response (status, message, device, data).

device is the top-level device identity block and contains device.mac_address and device.system_description (empty model when unavailable).

data is an object keyed by the SNMP table index of each upstream channel.
Each value contains decoded tap configuration and coefficient arrays.

Abbreviated Example¶

{
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "status": 0,
  "message": null,
  "data": {
    "80": {
      "main_tap_location": 8,
      "forward_taps_per_symbol": 1,
      "num_forward_taps": 24,
      "num_reverse_taps": 0,
      "forward_coefficients": [
        { "real": 0, "imag": 4, "magnitude": 4.0, "magnitude_power_dB": 12.04 },
        { "real": 2, "imag": -15425, "magnitude": 15425.0, "magnitude_power_dB": 83.76 },
        { "real": -15426, "imag": 1, "magnitude": 15426.0, "magnitude_power_dB": 83.77 }
        /* ... taps elided ... */
      ],
      "reverse_coefficients": []
    },
    "81": {
      "main_tap_location": 8,
      "forward_taps_per_symbol": 1,
      "num_forward_taps": 24,
      "num_reverse_taps": 0,
      "forward_coefficients": [
        { "real": -15425, "imag": -15425, "magnitude": 21814.24, "magnitude_power_dB": 86.77 },
        { "real": 1, "imag": 3, "magnitude": 3.16, "magnitude_power_dB": 10.0 },
        { "real": 1, "imag": -15425, "magnitude": 15425.0, "magnitude_power_dB": 83.76 }
        /* ... taps elided ... */
      ],
      "reverse_coefficients": []
    }
    /* ... other upstream channel indices elided ... */
  }
}

Container Keys¶

Key (top-level under `data`)	Type	Description
`"80"`, `"81"`, …	string	SNMP table index for the upstream channel row (OID instance).

Channel-Level Fields¶

Field	Type	Description
`main_tap_location`	integer	Location of the main tap (typically near the filter center)
`forward_taps_per_symbol`	integer	Number of forward taps per symbol
`num_forward_taps`	integer	Total forward equalizer taps
`num_reverse_taps`	integer	Total reverse equalizer taps (often `0` for ATDMA)
`forward_coefficients`	array	Complex tap coefficients applied in forward direction
`reverse_coefficients`	array	Complex tap coefficients applied in reverse direction
`metrics`	object	Derived equalizer metrics and frequency response

Coefficient Object Fields¶

Field	Type	Units	Description
`real`	int	—	Real part of the complex coefficient
`imag`	int	—	Imaginary part of the coefficient
`magnitude`	float	—	Magnitude of the complex tap
`magnitude_power_dB`	float	dB	Power of the tap in dB

Equalizer Metrics Fields¶

Field	Type	Units	Description
`main_tap_energy`	float	—	Main tap energy (MTE)
`main_tap_nominal_energy`	float	—	Main tap nominal energy (MTNE)
`pre_main_tap_energy`	float	—	Pre-main tap energy (PreMTE)
`post_main_tap_energy`	float	—	Post-main tap energy (PostMTE)
`total_tap_energy`	float	—	Total tap energy (TTE)
`main_tap_compression`	float	dB	Main tap compression (MTC)
`main_tap_ratio`	float	dB	Main tap ratio (MTR)
`non_main_tap_energy_ratio`	float	dB	Non-main tap to total energy ratio (NMTER)
`pre_main_tap_total_energy_ratio`	float	dB	Pre-main tap to total energy ratio (PreMTTER)
`post_main_tap_total_energy_ratio`	float	dB	Post-main tap to total energy ratio (PostMTTER)
`pre_post_energy_symmetry_ratio`	float	dB	Pre-post energy symmetry ratio (PPESR)
`pre_post_tap_symmetry_ratio`	float	dB	Pre-post tap symmetry ratio (PPTSR)
`frequency_response`	object	—	Frequency response derived from tap coefficients

Frequency Response Fields¶

Field	Type	Units	Description
`fft_size`	integer	—	FFT size used to compute the response
`frequency_bins`	array[float]	—	Normalized bins from 0 to 1
`magnitude`	array[float]	—	Magnitude response per bin
`magnitude_power_db`	array[float]	dB	Magnitude power per bin
`magnitude_power_db_normalized`	array[float]	dB	Magnitude power normalized to the DC bin (bin 0)
`phase_radians`	array[float]	rad	Phase response per bin

Notes¶

Each top-level key under data is the DOCSIS SNMP index for an upstream SC-QAM (ATDMA) channel.
Forward taps pre-compensate the channel (handling pre-echo/echo paths); reverse taps are uncommon in ATDMA.
Use tap shapes and main-tap offset to infer echo path delay and alignment health.
Tap coefficients are signed integers; convert to floating-point as needed for analysis.
magnitude_power_db_normalized references the DC bin (bin 0) as 0 dB when non-zero.