Introduction

While considering a use case where cloud may have added support to groups/blobs which CPE doesn’t support, approach that was decided is to have a metadata header with a bitmask indicating supported features in CPE.  

When CPE contacts cloud server to get the latest version of documents due a forced sync/bootup sync, then CPE may add a header X-System-Supported-Docs: to the request. This header will contain a bitmask string which indicates what feature is supported in CPE FW. 

Within RDK, each feature will be supported by different components. Hence the subdocs may be arranged into groups to form a series of bit masked values separated by commas. Placeholder of each group in the header could be predefined and can be identified by the two MS nibbles. So, cloud may parse the bitstreams as per the group ID shared by RDK. Within each group’s bitmap, cloud can check the bits turned ON to identify supported feature.  

Here RDK reserves two MS nibbles for identifying the group, hence it won’t change. Rest of the bits will be used to indicate a subdoc is supported or not.  

To identify schema version supported by each group, a new metadata header will be added as X-System-Schema-Version with comma separated version numbers along with a bit mask subdoc id. That will ensure cloud knows the schema version of subdoc supported by CPE in each FW release. Versions in the header may not follow the same ordinal status of bitstream in the supported docs metadata. As all subdoc versions start from 1.0, RDK need not have to add this header or version of a subdoc in header until there is a change in version of a subdoc. 

Both version and supported docs information is populated during build time. So, it won’t change during runtime in CPE. 

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:

Fig 1: Bits arrangement in bitstream.
 
In supported subdoc metadata, bitmask will be a value considering all bits corresponding to supported subdocs turned ON in LS 6 nibbles.  

In version metadata, bitmask value generated for identifying subdoc will be having only one bit turned ON in 6 LS nibbles.  

As mentioned in figure above, MS two nibbles will be group identifier field. 

Sample Header with metadata

X-System-Product-Class: XB3
X-System-Model-Name: TG1682G
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: 16777219, 33554435, 50331649,...
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: TG1682_DEV-default_20190510072402sdy.bin

 X-System-Supported-Docs: 

Here, metadata for supported docs will be populated as per placeholder mentioned here. 

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 

 Since cloud may not know about what RDK group hosts a particular subdoc, below table will give an idea of Group vs Feature mapping. 

Table 1: 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

This section is for RDKB component owners.  

In RDKB, a common JSON file (webconfig_metadata.json) will be shared among components during build time. File webconfig_metadata.json will provide information of subdocs supported per platform. When a new feature is coming in for a platform, then that feature details has to be added under that specific platform during a code check-in of feature. Build scripts will convert the json to webconfig.properties and install into 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

Placeholder for each group is predefined, but component owner can decide bit position for a new subdoc added in that group. Bit position for all the defined features are identified and shown in Section 3. 

As an example, how bitstream mapping will be considered to generate webconfig.properties is as shown below:

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=dns:1:true
WEBCONFIG_SUBDOC_MAP_5=adsecurity:1:true
WEBCONFIG_SUBDOC_MAP_6=mesh:1:true,clientsteeringprofile: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,televoice: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,grewafservice:2:false
WEBCONFIG_SUBDOC_MAP_16=prioritizedmacs:1:true
WEBCONFIG_SUBDOC_MAP_17=telmetrynotification:1:true
WEBCONFIG_SUPPLEMENTARY_DOCS=telemetry