Introduction

In RDK, User Initiated Firmware upgrade is handled by org.rdk.System Plugin through ‘updateFirmware’ method. System plugin will invoke ‘deviceInitiatedFWDnld.sh’  script to communicate with Xconf server and fetch firmware information. Image download will be initiated by ‘deviceInitiatedFWDnld.sh’. Once download is completed then a device specific script will be executed. The device specific script can have implementation specific to the platform and will invoke the Flash Utility after verifying integrity of the firmware.

Use case

Usecase description

• Admin: Responsible for configuring the XConf firmware control rules specific to the model and upload the stable release firmware image to the file server.
• File Server: It hosts the firmware upgrade package. Could be supporting various protocols (HTTP,HTTPS, FTP, SFTP, TFTP etc) but these are not coming under Xconf's scope. XConf provides a File Server to host the firmware upgrade package but it it does not mandate to use the same.
• XConf Server: When an STB queries for details about any available update, XConf shares the available details of firmware update package to STB after matching against its configured rules for that STB make & model.
• STB: This could be any RDKV flavor (IP/Hybrid STB, TV Platforms etc).  

How to prepare XConf Server

Xconf server provide information to STB like which Firmware version, From where to download the image and how(protocol) to download.

There are 3 significant steps involved in the Xconf firmware upgrade configuration:

1. Firmware Config – The firmware details will be configured here.

    Where : Go to Firmware - > Firmware Configs -> Create.

    How : Add your firmware details - File name ( Upgrading image name ), Version( Upgrading image name) and select your model name and save the details in Xconf server.

2. Firmware rule – Rule is to map your device to the configuration created.

    Where : Go to Firmware -> FirmwareRule - > Create.

     How : Select one of the default template like MAC_RULE.

Enter name of the rule, build condition (you can add estbMacAddress i.e. )

select the firmware config from the drop down list to map it with the rule

3. Download Location Filter – Here we can specify the download location URL and it’s protocol.

Where : Go to Firmware-> Download Location Filter -> Edit.

How : An Http location will be returned by default for all the devices. Enter FQDN and Full URL of the location.

The configuration will be available through below Xconf data service API: https://xconf.rdkcentral.com:9092/xconf/swu/stb/ 

Xconf Authorization Module Details

• Xconf server login page can be accessed from https://xconf.rdkcentral.com:19093/admin/ux/loginForm
• Xconf authorization works through servlet filter, the login page will be intercepted by the servlet filter. After successful login, backend API will be called to retrieve all the matching user information and permissions.
• The permissions can be admin permission-permitAll or list of permissions for each page like –read/write common, ‘read-dcm-stb’ etc. Each page has a permission verification on each access. There is permission verification in the UI action elements also. For example, if you want to edit or write a firmware rule, the user should have write firmware permission.
• For accessing the XCONF server,  refer this section Xconf Reference Setup Credentials

Create Environment

• Select Environments option within common list to enter Environments page.
• After entered Environments page press create button to add your device environment detail.
• Give ID and Description to setup Environment for your device and save those details in Xconf server

Create Model

• Select Models option within common list to enter Models page.
• After entered Models page press create button to add your device model detail.
• Give ID and Description to setup Model for your device and save those details in Xconf server.

Create Mac List

• Select MAC Lists option within common list to enter MAC Lists page.
• After entered MAC Lists page press create button to add your device MAC detail.
• Give Name and Data to set MAC detail for your device and save those details in Xconf server.

Create Firmware Config

Before configuring Firmware essentials, Ensure application type is stb.

• Select Firmware Configs option within common list to enter Firmware Configs page.
• After entered Firmware Configs page press create button to add your device firmware configuration detail.
• Give Description, File name ( Upgrading image name ), Version( Upgrading image name) and select your model name and save the details in Xconf server.

Create Firmware Rules

• Select Firmware Rule option within common list to enter Firmware Rule page.
• After entered Firmware Rule page press create button to add your device firmware Rule detail.
• After entered firmware Rule page you can see list of default templates(ENV_MODEL_RULE, IP_RULE, MAC_RULE etc.)
  Note: If we need to create new custom template, go to Firmware → Firmware templates. Enter the ID name. Select priority from the 'Priority' drop down menu. Add conditions. Once saved select the new template to create firmware rule
• Choose MAC_RULE(any required template) in this list of Template to add your device MAC list in Firmware Configuration.
• After we select the required template, 'Add firmware Rule' page will be displayed. Here the build conditions will be present from the 'template' that we added and in addition to that we can add additional Build Conditions also.
• Add your device specific eStbMac under build condition option.
• Select your firmware config under Action option and save your Firmware rule in XConf server.

Edit Download Location Round Robin Filter

• Place the upgrading image in download location file server.
• Select Download Location Filter option within common list to enter into Download Location Filter page.
• After entered Download Location Filter page press edit button to add your Download Location details.
• Enter FQDN and Full URL of the location. This location will be applied by default for all the devices.

Admin can set up an alternative download location for hosting the firmware image using any local file server . To add alternative location for the device, we need to override it from firmware rules.

•  Go to Firmware -> Firmware Rules -> Define Properties -> Create
•  A page will be displayed with options to select the template. Select ‘DOWNLOAD_LOCATION_FILTER’ from the list
• In this 'firmware rule' page with type 'DOWNLOAD_LOCATION_FILTER', we can specify the firmwareDownloadProtocol and firmware location . This property will override the default value set from ‘Download Round Robin location filter’.

For setting up Local File Server refer section "Setup a local File-Server" under Support Section. Below setup shows using hfs as file server:

Host the upgrade image in File-Server and copy the link address of the file url. Below snapshot was taken with another setup hence there is mismatch with the URI. Use the uri which is obtained from section "Setup a local File-Server", "link address of the image" (http://192.168.1.106:8001)

Add the firmwareDownloadProtocol and copied link address as the firmwareLocation in Xconf server.

Validation Steps

Verification via Xconf firmware Test page

After creating the Firmware configs and Firmware rules, go to Firmware->Test page and give a parameter that will match the one of the rules that you have created. Then matched rule will be displayed like below. 

Verification via curl command:

• Below curl GET request mocks the request being sent from an STB and its sample response is also given. It can be given as a curl command or as a get request browser.

root@raspberrypi-rdk-ipmc:/opt# curl --location --request GET 'https://xconf.rdkcentral.com:19092/xconf/swu/stb?eStbMac=B8:27:EB:EE:8C:0B'
{"firmwareDownloadProtocol":"http","firmwareFilename":"rdk-generic-ip-stb-client_rdk-next_20230116141625.rootfs.wic","firmwareLocation":"http://192.168.1.12","firmwareVersion":"rdk-generic-ip-stb-client_rdk-next_20230116141625","rebootImmediately":false,"mandatoryUpdate":false}

How to upgrade the Firmware 

Once the server side configurations are done, made the changes in the client side.

The cloud URL should be set in the file /etc/include.properties

CLOUDURL=https://xconf.rdkcentral.com:9092/xconf/swu/stb?eStbMac= 

• Activate the System Service Plugin in the Controller UI or execute the below command: 

curl -X POST http://127.0.0.1:9998/jsonrpc -d '{"jsonrpc":"2.0","id":"3","method":"Controller.1.activate","params": {"callsign":"org.rdk.System"}}'

• Provide the UpdateFirmware Curl command in the device console

curl -X POST http://127.0.0.1:9998/jsonrpc -d '{"jsonrpc":"2.0","id":"3","method":"org.rdk.System.1.updateFirmware","params":{}}' 

• Reboot the box after successful completion of image download and flashing.
• Verify the version of booted image which shows the downloaded image version.