ApplicationBasic Cluster

Cluster ID: 0x050D  |  Endpoint: Application endpoint (each content app occupies a separate Endpoint)

ApplicationBasic provides basic information about content apps (Content Apps) — including app name, vendor, version, runtime status, and unique identifier. It is a core Cluster in the Matter media/TV device ecosystem; each content app installed on a TV or set-top box exposes this Cluster through a separate Endpoint.

One App = One Endpoint

Matter's media architecture uses an "one Endpoint per app" model. For example, if a smart TV has 3 streaming apps installed (video, music, live), the device exposes their respective ApplicationBasic Clusters on Endpoints 3, 4, and 5. Controllers discover installed apps by enumerating Endpoints, then read each Endpoint's ApplicationBasic for app details.

Attribute Overview

ApplicationBasic has 8 attributes grouped into four categories. Click an attribute ID to jump to its detailed description.

ID Name Type Group Description
0x0000 VendorName string Vendor Info App vendor name
0x0001 VendorID vendor-id Vendor Info App vendor ID (assigned by CSA)
0x0002 ApplicationName string Vendor Info App name
0x0003 ProductID uint16 Product Identity App product ID
0x0004 Application ApplicationStruct Product Identity App unique identifier (catalog + ID)
0x0005 Status ApplicationStatusEnum Runtime Status App current runtime status
0x0006 ApplicationVersion string Runtime Status App version
0x0007 AllowedVendorList list<vendor-id> Access Control List of vendor IDs allowed to access this app

Vendor Information (0x0000 – 0x0002)

Describes the app's vendor and name. These attributes are determined after app installation and cannot be changed at runtime.

ID Name Type Description
0x0000 VendorName (Vendor Name) string Human-readable name of the app vendor, max 32 characters. E.g., "Netflix", "YouTube". Optional attribute
0x0001 VendorID (Vendor ID) vendor-id CSA vendor number of the app vendor. If the app vendor has not registered with CSA, this value is 0. Optional attribute
0x0002 ApplicationName（App name） string Human-readable name of the app, max 32 characters. E.g., "Netflix", "Spotify". Required attribute, and the only required attribute in ApplicationBasic

↑ Back to Attributes

Product Identity (0x0003 – 0x0004)

The app's product number and globally unique identifier. The Application attribute is the most important identifier — it uniquely locates an app through the catalog system.

ID Name Type Description
0x0003 ProductID (Product ID) uint16 Product number assigned by the app vendor. Combined with VendorID, identifies a specific app product. Optional attribute
0x0004 Application (App Identifier) ApplicationStruct Globally unique identifier for the app, consisting of catalog vendor ID and application ID (see ApplicationStruct below). Optional attribute
Application vs VendorID + ProductID

VendorID + ProductID identifies "which product by which vendor" — a vendor-dimension identifier. Application (ApplicationStruct) identifies "which app in which catalog" — a platform-dimension identifier. For example, the same video app may have an ID of "com.example.video" in the CSA catalog but a different ID in another platform catalog. Controllers typically use Application to locate and launch specific content apps.

↑ Back to Attributes

Runtime Status (0x0005 – 0x0006)

Describes the app's current runtime status and version information.

ID Name Type Description
0x0005 Status (Runtime Status) ApplicationStatusEnum Current runtime status of the app (see ApplicationStatusEnum below). Optional attribute
0x0006 ApplicationVersion (App Version) string App version string, max 32 characters. E.g., "2.1.0", "3.0.0-beta". Required attribute

↑ Back to Attributes

Access Control (0x0007)

Controls which vendors' Controllers can access this app's Clusters.

ID Name Type Description
0x0007 AllowedVendorList (Allowed Vendor List) list<vendor-id> List of vendor IDs allowed to access this content app. Only Controllers produced by vendors in this list can interact with this app's Clusters. Required attribute
AllowedVendorList and ACL Relationship

AllowedVendorList is an additional access control layer on top of the standard ACL (Access Control List). Even if a Controller passes ACL checks, it still cannot access Clusters on this app's Endpoint if its VendorID is not in AllowedVendorList (except ApplicationBasic itself). This mechanism allows content providers to restrict app control to only partner devices.

↑ Back to Attributes

Structs & Enums

ApplicationStruct (App Identifier Struct)

Uniquely identifies a content app through the catalog system. Different app catalogs (e.g., CSA, Google Play, Apple App Store) each have their own numbering system. CatalogVendorID specifies which catalog, and ApplicationID is the app identifier within that catalog.

Field Type Description
CatalogVendorID uint16 Vendor ID of the app catalog. Identifies which app catalog/platform the app comes from. E.g., CSA's own catalog or an OTT platform's catalog
ApplicationID string String that uniquely identifies the app within the catalog. Format defined by the catalog, typically reverse domain name style, e.g., "com.netflix.app"
Meaning of CatalogVendorID

CatalogVendorID is NOT the app vendor's VendorID, but rather the app catalog provider's VendorID. Think of it as: which "app store" the app is listed in. If CatalogVendorID corresponds to the CSA official catalog (value 0x60AE = 24750), then ApplicationID is the app identifier in the CSA catalog system.

ApplicationStatusEnum (App Runtime Status Enum)

Describes the current runtime and visibility status of a content app.

0
Stopped Stopped — app is not running, needs to be launched before use
1
ActiveVisibleFocus Foreground running — app is running, visible, and has user input focus (the currently active app)
2
ActiveHidden Background running — app is running but not visible (e.g., playing music in background)
3
ActiveVisibleNotFocus Visible without focus — app is running and visible, but user focus is on another app (e.g., picture-in-picture mode)
State Transition Scenarios

Typical state transition path: when the user opens an app, Stopped → ActiveVisibleFocus; when switching to another app, ActiveVisibleFocus → ActiveHidden (fully hidden) or ActiveVisibleFocus → ActiveVisibleNotFocus (picture-in-picture); when the user closes the app, it returns to Stopped. Controllers can subscribe to Status attribute changes to track the app lifecycle.

Commands

ApplicationBasic does not define any commands. App launching and control are handled by other Clusters:

  • ApplicationLauncher (0x050C) — handles launching, stopping, and hiding apps
  • MediaPlayback (0x0506) — handles playback control (play, pause, fast-forward, etc.)
  • ContentLauncher (0x050A) — handles launching specific content (e.g., opening a video)

ApplicationBasic's role is read-only information query — it tells the Controller "what this app is", not "what to do with this app".

Example Data

Read results of the ApplicationBasic Cluster from a streaming app (Endpoint 3) on a smart TV:

{
  // --- Vendor Information ---
  "0x0000": "StreamCo",            // VendorName = App vendor name
  "0x0001": 4996,                  // VendorID = 0x1384 (assigned by CSA)
  "0x0002": "StreamCo Player",     // ApplicationName = App name

  // --- Product Identity ---
  "0x0003": 101,                   // ProductID = App product ID
  "0x0004": {                      // Application (app identifier struct)
    "CatalogVendorID": 24742,      //   CatalogVendorID = CSA catalog
    "ApplicationID": "com.streamco.player"  //   ApplicationID = app ID
  },

  // --- Runtime Status ---
  "0x0005": 1,                     // Status = ActiveVisibleFocus (foreground, visible with focus)
  "0x0006": "2.1.0",               // ApplicationVersion = App version

  // --- Access Control ---
  "0x0007": [4996, 65521]          // AllowedVendorList = List of vendor IDs allowed to access this app
}
Typical Flow for Reading App Information

Standard flow for a Controller to discover installed apps on a device:

  1. Read the PartsList from Endpoint 0's Descriptor Cluster (0x001D) to get all Endpoint numbers
  2. For each Endpoint, read its Descriptor's ServerList and check if it contains 0x050D (ApplicationBasic)
  3. If found, read that Endpoint's ApplicationName (0x0002) and Application (0x0004) for the app name and identifier
  4. Read Status (0x0005) to determine if the app is currently running

Common Scenarios

Scenario 1: Discover and display all content apps on the TV

After the phone app connects to a smart TV, it needs to list all content apps installed on the TV in the interface (similar to the TV remote's app list).

  1. Read the Descriptor Cluster of Endpoint 0 to get PartsList (all child Endpoints)
  2. Check each Endpoint's ServerList one by one, filtering for those containing 0x050D
  3. For each app Endpoint, batch read ApplicationName, VendorName, ApplicationVersion, and Status
  4. Render the app list in the app interface, showing name, version, and runtime status (e.g., "Running" or "Stopped")

Note: Not all Endpoints are content apps — some may be other device types such as lights or sensors. More precise filtering can be achieved by checking if the Descriptor's DeviceTypeList contains Content App (0x0024).

Scenario 2: Locate and launch a specific app via app identifier

The user says "Open Netflix", and the Controller needs to find the Endpoint for Netflix and launch it.

  1. Iterate through all app Endpoints and read each Endpoint's Application (0x0004) attribute
  2. Compare CatalogVendorID and ApplicationID in ApplicationStruct to find the target app
  3. Check Status (0x0005): if already ActiveVisibleFocus (1), no action needed
  4. If Stopped (0) or another status, send the LaunchApp command via ApplicationLauncher Cluster (0x050C) to launch the app
  5. Subscribe to Status attribute changes to confirm the app successfully entered ActiveVisibleFocus state

Note: Launching an app is not ApplicationBasic's responsibility — it only provides information queries. The actual launch operation is performed by the ApplicationLauncher Cluster on the same Endpoint.