Introduction

This document defines the mechanism by which the CPE communicates its supported features to the cloud. To ensure compatibility, especially in cases where the cloud introduces support for new groups or blobs not yet implemented in the CPE, RDK adopts a metadata-based approach.

When the CPE contacts the cloud server to retrieve the latest version of documents, during either a forced sync or a bootup sync then it includes the header X-System-Supported-Docs: in the request. This header contains a bitmask string that indicates which features are supported in the CPE firmware.

Within RDK, different features are managed by separate components. Accordingly, subdocs are organized into groups, each represented by a bit masked value. These values are comma-separated within the header. Each group’s position in the header is predefined and identified by its two most significant (MS) nibbles. The cloud can parse these bitstreams based on the group ID provided by RDK. Within each group’s bitmap, the cloud can check which bits are set to identify the supported features.

RDK reserves two MS nibbles for identifying the group; these remain constant. The remaining bits are used to indicate whether a specific subdoc is supported.

To specify the schema versions supported for each group, the metadata header X-System-Schema-Version is included. This header contains comma-separated entries, each combining a bitmask subdoc ID with its corresponding version number. This allows the cloud to determine the schema version supported by the CPE for each subdoc in a given firmware release. The order of versions in this header may differ from the bitstream order used in the supported-docs metadata. Since all subdoc versions begin at 1.0, RDK does not include this header or subdoc version information unless a version change has occurred.

Both version and supported-docs information are generated at build time and remain unchanged during CPE runtime.

Placeholders for each RDK subdoc group in the meta header 

Metadata for supported features in CPE

X-System-Supported-Docs: <Group1>,<Group2>,<Group3>,...,<GroupN>

Points for future: 

• New supported groups WILL NOT be added in between the existing list.  
• If a group/component uses all 24 bits available, then we will have to use a new bitstream at the end of existing ones with a different Group Id(2 MS nibble).
• For simplicity, during initial rollouts, groups are segregated based on RDKB components but there is no hard rule to tie a subdoc to a group as subdocs are identified based on the group Id. 

Version metadata

X-System-Schema-version: <bitmask1:version_1>,<bitmask2:version_2>,<bitmask3:version_3>,<bitmask4:version_4>,...

Bitstream patterns

In supported subdoc metadata, the bitmask represents a value in which all bits corresponding to supported subdocs are set within the least significant (LS) 6 nibbles.

In version metadata, bitmask value generated for identifying subdoc will have only a single bit set within the 6 LS nibbles.

As illustrated in the figure above, the two most significant (MS) nibbles serve as the group identifier field.

Sample Header with metadata

X-System-Product-Class: XB3
X-System-Model-Name: BananapiBPI-R4
Authorization: Bearer <JWT token>
IF-NONE-MATCH:NONE
Schema-Version: v1.0
Transaction-ID: 79098228695636680012
X-System-Schema-Version: 16777217-1.1, 16777218-1.2, 33554433-1.1, 50331649-2.0,....
X-System-Supported-Docs: 16777247,33554435,50331649,67108865,...
X-System-Boot-Time: 1557198030
X-System-Ready-Time: 1557199130
X-System-Current-Time: 1557199333
X-System-Status: Operational\Non-Operational
X-System-Firmware-Version: rdkb-generic-broadband-image_rdkb-2025q2-kirkstone_20

 X-System-Supported-Docs: 

This header will contain metadata for supported docs, populated according to the placeholders defined in this section.

As per the placeholders, in this sample request header  

• 16777219 corresponds to Subdocs of Group-1 of RDK 

• 33554435 corresponds to Subdocs of Group-2  

• 50331649 corresponds to Subdocs of Group-3 and so on 

The cloud converts each decimal bitmask value into its corresponding binary pattern for decoding the supported subdocs.

Example:

Each binary bit represents the enablement status of a specific subdoc within that group.

The mapping between bit positions and subdocs is explained here. 

If only two MS nibbles have bits turned ON, that means no feature is supported by that Group in that FW version

X-System-Schema-Version

 This header will hold comma separated strings where each string will have 2 parts.  

1. A bit mask generated from the combination of two MS nibbles and a subdoc position in the bitstream.
2. The version supported by that subdoc. 

Example:

Here, two MS nibbles can be directly translated to decimal to identify the position/group in the list represented by supported docs. 

Component to feature mapping 

The following table outlines the mapping between groups and features, as the cloud may not be aware of which RDK group is responsible for a specific subdoc.

Subdoc to bit position mapping

Bit Pattern of supported features 

This section will depict what feature/subdoc each bit field denotes in the bitmask: 

Group-1 

Group-2 

Group-3 

Group-4 

Group-5 

Group-6 

Group-7 

Group-8 

Group-9 

Group-10 

Group-11 

Group-12 

Group-13 

Group-14 

 Group-15 

Group-16 

Group-17 

Versioning in RDKB Components

In RDKB, a common JSON file namedwebconfig_metadata.jsonis shared among components during build time. This file defines the subdocs supported for each platform. When a new feature is introduced for a specific platform, its corresponding details must be added under that platform’s section inwebconfig_metadata.jsonas part of the feature’s code check-in.

During the build process, the scripts convert this JSON file into webconfig.properties and install it into the root file system.

webconfig_metadata.json will provide following details: 

• Platform for which a subdoc is added 

• Group Id 

• Name of the subdoc 

• Bit position in the 32-bit long bitstream for a group 

• Whether support is enabled or not 

• Version of schema 
  
  

Sample json file: metadata.txt

The placeholder for each group is predefined; however, the component owner can determine the bit position for any new subdoc added within that group. The bit positions for all defined features are identified and and shown here.

The following example illustrates how the bitstream mapping is used to generate the webconfig.properties file.

Group-1 bitstream as mentioned in here.

Sample webconfig.properties file with contents: 

/* WEBCONFIG_SUPPORTED_DOCS_BIT variable holds the bitstream of supported docs in each component.
Placeholder will be as:
<Group-1>,<Group-2>,<Group-3>,<Group-4>,<Group-5>,<Group-6>,<Group-7>,<Group-8>,<Group-9>,<Group-10>
*/
WEBCONFIG_SUPPORTED_DOCS_BIT=16777247,33554435,50331649,67108865,83886081,100663297,117440513,134217729,201326594,218103809,251658241

/* WEBCONFIG_DOC_SCHEMA_VERSION variable will hold the hex conversion of each nibble in above bit pattern.
If the supported schema version of a subdoc hasn’t changed from base version “1.0” then that need not have to be applied to header.*/
WEBCONFIG_DOC_SCHEMA_VERSION=16777217-2.0,16777220-1.3,16777224-2.1,33554433-1.1,67108865-2.0,117440513-3.0,...

/* Subdoc mapping as per bit position for each group.
Format:<Group><subdoc name>:<bit position>:<supported>
*/
WEBCONFIG_SUBDOC_MAP_1=portforwarding:1:true,wan:2:true,lan:3:true,macbinding:4:true,hotspot:5:true,bridge:6:false,connectedbuilding:7:true
WEBCONFIG_SUBDOC_MAP_2=privatessid:1:true,homesid:2:true,radio:3:false
WEBCONFIG_SUBDOC_MAP_3=moca:1:true
WEBCONFIG_SUBDOC_MAP_4=xdns:1:true
WEBCONFIG_SUBDOC_MAP_5=advsecurity:1:true
WEBCONFIG_SUBDOC_MAP_6=mesh:1:true,clienttosteeringprofile:2:true
WEBCONFIG_SUBDOC_MAP_7=aker:1:true
WEBCONFIG_SUBDOC_MAP_8=telemetry:1:true
WEBCONFIG_SUBDOC_MAP_9=trafficreport:1:false,statusreport:2:false
WEBCONFIG_SUBDOC_MAP_10=radioreport:1:false,interfacereport:2:false
WEBCONFIG_SUBDOC_MAP_11=telcovoip:1:false,telcovoice:2:false
WEBCONFIG_SUBDOC_MAP_12=wanmanager:1:false,wanfailover:2:true
WEBCONFIG_SUBDOC_MAP_13=voiceservice:1:true
WEBCONFIG_SUBDOC_MAP_14=cellularconfig:1:false
WEBCONFIG_SUBDOC_MAP_15=gwfailover:1:true,gwrestore:2:false
WEBCONFIG_SUBDOC_MAP_16=prioritizedmacs:1:true
WEBCONFIG_SUBDOC_MAP_17=lldqoscontrol:1:true
WEBCONFIG_SUPPLEMENTARY_DOCS=telemetry