Channel Cluster

Cluster ID: 0x0504  |  Endpoint: Media endpoint (TV, set-top box, etc.)

Channel handles channel navigation and lineup management — channel switching, skipping, name-based search, querying the channel list, and the Electronic Program Guide (EPG). It is one of the core Clusters for media devices such as smart TVs and set-top boxes. Unlike MediaInput which manages physical input sources (HDMI, USB), Channel manages logical channels (CCTV-1, HBO).

Commands

The Channel Cluster has 6 client commands and 2 response commands. Basic tuning (ChangeChannelByNumber / SkipChannel) is supported by all devices. ChangeChannel requires channel list or lineup info support (CL or LI), and GetProgramGuide and recording commands require more advanced features. Click a command ID in the table below to jump to its detailed description.

Response Commands

ChangeChannel — Fuzzy Match Channel (0x00)

Fuzzy matches and switches channels using a string against the channel list. The device sequentially matches channel fields including Name, CallSign, AffiliateCallSign, and number (MajorNumber-MinorNumber). If exactly one channel matches, it automatically switches and updates CurrentChannel; if multiple or zero matches are found, the device notifies the controller via ChangeChannelResponse.

ChangeChannelResponse

Response to ChangeChannel, indicating the match result:

// ChangeChannel command response (ChangeChannelResponse)
// Match successful
{
  "Status": 0,         // Success
  "Data": null
}

// Multiple matches found
{
  "Status": 1,         // MultipleMatches
  "Data": "CCTV-5 Sports, CCTV-5+ Events"
}

// No channels matched
{
  "Status": 2,         // NoMatches
  "Data": null
}

↑ Back to Commands

ChangeChannelByNumber — Exact Tune (0x02)

Switches to a specific channel using the major number (MajorNumber) and minor number (MinorNumber). This is the most basic tuning command — it does not require the device to provide a channel list, and all devices implementing the Channel Cluster must support it. No response command is returned — on success, the CurrentChannel attribute updates.

↑ Back to Commands

SkipChannel — Relative Skip (0x03)

Skips a specified number of channels forward or backward relative to the current channel. Positive numbers skip forward (increasing channel numbers), negative numbers skip backward. The skip follows the device's internal channel ordering and wraps around at the end or beginning of the list.

↑ Back to Commands

GetProgramGuide — Query Program Guide (0x04)

Queries the Electronic Program Guide (EPG) data, returning the program list within the specified time range and channel range. This command requires the device to enable the EG (ElectronicGuide) feature. The response is returned via ProgramGuideResponse with pagination support.

↑ Back to Commands

RecordProgram — Schedule Recording (0x06)

Schedules recording of a specified program. Locates the program to record via its unique identifier (ProgramIdentifier) or external ID. This command requires the device to enable the RP (RecordProgram) feature. This command is only supported by devices with storage capabilities (e.g., set-top boxes with hard drives, DVRs).

↑ Back to Commands

CancelRecordProgram — Cancel Recording (0x07)

Cancels a previously scheduled recording via RecordProgram. The parameter structure is the same as RecordProgram, identifying the recording to cancel via ProgramIdentifier. Requires the RP feature.

↑ Back to Commands

Attributes

The Channel Cluster has 3 attributes. Click an attribute ID in the summary table below to jump to its detailed description.

Channel Information (0x0000 ~ 0x0002)

Describes the device's available channel list, operator lineup information, and the currently selected channel.

↑ Back to Attributes

Struct Definitions

The Channel Cluster uses two core structures to describe channel and lineup information.

ChannelInfoStruct

Describes the complete information for a channel. MajorNumber and MinorNumber are required fields; the rest are optional.

LineupInfoStruct

Describes the operator lineup information for the device's current connection. OperatorName and LineupInfoType are required fields.

Enum Values

StatusEnum

Match result status in ChangeChannelResponse:

ChannelTypeEnum

Describes the channel's transmission method / source type:

LineupInfoTypeEnum

Describes the lineup operator type:

Feature Bitmap

The Channel Cluster declares which optional capabilities the device supports via FeatureMap (0xFFFC):

Example Data

Read results of the Channel Cluster from a set-top box with CL + LI features enabled, currently viewing CCTV-6:

{
  // --- Current Channel ---
  "0x0002": {                       // CurrentChannel
    "MajorNumber": 6,
    "MinorNumber": 1,
    "Name": "CCTV-6 Movies",
    "CallSign": "CCTV6",
    "AffiliateCallSign": null,
    "Identifier": "cctv6-hd",
    "Type": 2                        // Terrestrial
  },

  // --- Channel List (requires CL feature) ---
  "0x0000": [                        // ChannelList
    {
      "MajorNumber": 1,
      "MinorNumber": 1,
      "Name": "CCTV-1 General",
      "CallSign": "CCTV1",
      "AffiliateCallSign": null,
      "Identifier": "cctv1-hd",
      "Type": 2                      // Terrestrial
    },
    {
      "MajorNumber": 5,
      "MinorNumber": 1,
      "Name": "CCTV-5 Sports",
      "CallSign": "CCTV5",
      "AffiliateCallSign": null,
      "Identifier": "cctv5-hd",
      "Type": 2
    },
    {
      "MajorNumber": 6,
      "MinorNumber": 1,
      "Name": "CCTV-6 Movies",
      "CallSign": "CCTV6",
      "AffiliateCallSign": null,
      "Identifier": "cctv6-hd",
      "Type": 2
    },
    {
      "MajorNumber": 100,
      "MinorNumber": 1,
      "Name": "HBO",
      "CallSign": "HBO",
      "AffiliateCallSign": "HBO East",
      "Identifier": "hbo-east",
      "Type": 1                      // Cable
    }
  ],

  // --- Lineup Info (requires LI feature) ---
  "0x0001": {                        // Lineup
    "OperatorName": "China Broadcasting",
    "LineupName": "Standard Digital",
    "PostalCode": "100000",
    "LineupInfoType": 0              // MSO
  }
}

Common Scenarios