Code Download (Xconf, DCM)

Created on June 21, 2022

Overview

Traditional code download were using eCM interface which had some limitations like URL resolution not supported. XCONF way of code download allows Code download from the Embedded STB  (eSTB) interface and provides set-top with

  • Which firmware version to download
  • From where to download
  • How (protocol) to download

RDK Code Download (RCDL)

Server side (Business logic) identifies which version of code need to be provided for download. Xconf download is triggered by the device ie: device reaches out to server sending information like current firmware and capabilities. It asks for which firmware version to download and from where to download. RCDL (RDK Code Download or Remote Code Download) uses eSTB interface to download code from server.

Xconf Code Download Highlights:

  • Users can set download protocol
    • HTTP as preferred method
    • Provide HTTP and TFTP endpoints
    • Default to TFTP if no HTTP support
  • Ability to publish capabilities from CPE device
    • rebootDecoupled (no need to reboot soon after firmware download. Reboot later or at a scheduled time)
    • supportsFullHttpUrl
  • Ability to decouple downloads from reboot
  • Ability to schedule firmware checks (During bootup/Later), Configurable based on timezones, quiet times
  • Ability to redirect to secure download end points

Get Configuration

An STB makes an HTTP request to Xconf to get firmware information. The request may be an HTTP POST or GET. The response is a JSON string. An example GET for the production Xconf instance would look like this.

https://<xconf server url>/xconf/stb?eStbMac=14:D4:FE:55:86:0A&env=PROD&model=abcd&DRfirmwareVersion=abc123

The following table lists some of the parameters which may be sent. 

NameExample valueDescription
capabilitiesrebootDecoupled , downloadScheduled , etc

Specifies capabilities of the STB that Xconf needs to know about. See capabilities table below for details. This is a multi-valued parameter. More than one capability may be sent. Separate the values using url?capabilities=value1&capabilities=value2&capabilities=value3

envPROD | VBN | QA | DEVThe environment this box is sitting in.
eStbMacab:e7:55:4d:cc:95MAC address of the STB.
firmwareVersionabcdSTB current firmware version.
ipAddress
For testing only. Overrides the source ip address of the HTTP request.
logLevelFATAL | ERROR | WARNING | INFOThe STB is echoing back a command it received from another path, such as SNMP or local control. A customer assistance engineer needs more diagnostic detail from this box’s log files. Xconf Server should set the logLevel parameter of the JSON response with this value, regardless of the configuration returned from the data store.
logLevelDuration0 0 0/1 1/1 * ? *The STB is echoing back a command it received from another path, such as SNMP or local control. A customer assistance engineer needs more diagnostic detail from this box’s log files. Xconf Server should set the logLevelDuration parameter of the JSON response with this value, regardless of the configuration returned from the data store.

mocaMac


MAC Address of the MoCA interface; currently ignored by xconf

modelabcdSTB model.
proxytrueInidcates that this request is coming from another service on behalf of a STB. The STB is identified by the eStbMac and the ipAddress (required in this case). Xconf Server should send a series of SNMP set requests indicating the firmwareVersion, firmwareFilename, firmwareLocation. XPM already does this, so use those SNMP MIBS.
rebootImmediatelytrue|false
timeZoneOffset-04:00Offset from UTC time. See http://joda-time.sourceforge.net/timezones.html If time parameter is sent this offset is assumed to have already been applied. So “time” parameter is always wall clock time. If timeZoneOffset is not sent, it defaults to UTC and “time” parameter if sent will be assumed to be UTC time.
uploadImmediatelytrue|false

Capabilities

The following table lists the different values for the capabilities parameter that may be send in request to Xconf. This is a multi-valued parameter. More than one capability may be sent.

 These capabilities should not live forever. Once all boxes are known to support a given capability, Xconf should deprecate/delete code that handles STBs that don’t support the capability and STB should stop sending the capability value.

CapabilityDescription
rebootDecoupledlets Xconf know that reboot has been decoupled from firmware download. If not specified in the rebootImmediately response, the STB will still reboot immediately after firmware download.
downloadScheduledlets Xconf know that STB is able to schedule firmware download based on information received from Xconf. ?? do we still want this ??
RCDL

STB is capable of performing HTTP firmware downloads using DNS resolved URIs. The download will run in the eSTB. Until this, the eCM performed the download. eCM does not have DNS and thus requires an IP address.

supportsFullHttpUrllets Xconf know that the STB can accept a full URL specifier (http://hostname.com); initially, the STB only accepted a hostname and prepended the hostname with the protocol, then appended it with a port and resource path. Xconf should specify the entire URL

Returned JSON Firmware Information

Xconf returns firmware information as a JSON string as follows (just a sample).

{
“firmwareDownloadProtocol”: “tftp”,
“firmwareFilename”: “<filename>sd-signed”,
“firmwareLocation”: “<ip_address>”,
“firmwareVersion”: “1.0.1.0.8”,

“firmwareIDK”: “[TBD]”,

“firmwareDownloadSchedule”: “[TBD]” 

“rebootImmediately”:false,
}

Xconf should be able to add new values and STB should still be able to process the JSON string. STB should ignore any values it doesn’t understand.

Error Handling

500 Internal Server Error

On server error STB may implement retry logic or not. Most 500 errors will be caused by bad requests, but some may be temporary conditions.

Timeout

If the request to Xconf times out, STB should implement retry logic.

404 / Empty JSON

There are times when Xconf does not wish to respond to the STB. In these cases it will send an HTTP 404 (not found) response and a prose text reason for why the response was not handled. The STB should ignore these responses (and not retry the request to Xconf).

Service & Scripts

Service Name  : /lib/systemd/system/swupdate.service

Helper Script  : /lib/rdk/swupdate_utility.sh

Main Script  : /lib/rdk/deviceInitiatedFWDnld.sh


Go To Top