...

Pre-requisites

• The user must configure a local TFTP (Trivial File Transfer Protocol) or HTTP (Hypertext Transfer Protocol) server.
• Ensure that both the local HTTP/TFTP server and the device are on the same network

Overview

This page detailed details how to perform firmware upgrade via using RDKM XCONF XConf Server.

RDKM provides offers a reference XCONF server which can be accessed publicly using the URL xconfXConf server that is publicly accessible at the URL XConf.rdkcentral.com.    User can Users have the option either use this XCONF XConf server or can create their own XCONF server.

For custom XCONF If you are interested in setting up a custom XConf server, Please please visit the page  https://wiki.rdkcentral.com/display/RDK/XconfXConf+Server+-+User+guide+for+configuration+and+feature+validation provides the details of for detailed instructions on installation and a usage guide. This page details how to use the RDKM XCONF server

The primary focus of this page is to guide you through the process of firmware upgrade using the RDKM XConf server XConfxconf.rdkcentral.com. 

User would be able to see two options in the landing page

1.  XConf Admin UI
2. Xconf XConf Data service

Image Added

User needs to can configure the  firmware details firmware rules, configurations, Telemetry settings, RFC settings etc in the admin UI and in the dataservice option it currently tells which XCONF version is currently running and when it was updated lastly.

 Below diagram show the process flow of firmware upgrade via XCONF server

Image Removed

• 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).  

Configure the device in XCONF

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

. While  dataservice, currently tells the XConf version information - Which version is used, when was it updated lastly and the commit informations etc.

Configure the device in XConf Server

In order to configure the device information user needs to login to XConf admin UI . For getting the access details, refer this page XConf Reference Setup Credentials and fill the information in admin UI and press login button.

Image Added

Once logged in, Users need to do basic configuration like setting up the environment, Creating the model information, Saves the mac Lists, IP Lists. These configurations are required for all device management features like RFC, Firmware upgrade, Telemetry etc.

Common Configurations

...

Create Environment

• Select Environments option within common Common list to enter Environments Environment 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 XConf server

Image RemovedImage Added

Create Model

• Select Models option within common Common list to enter Models Model 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 XConf server.

Image RemovedImage Added

Create Mac List

• Select MAC Lists option within common 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.

Image Added

User also has the option to choose multiple mac address from a file. User can use a browse button on the right side of the UI to select the files which holds the mac addresses. 

Note: All formats are not accepted here. each line holds only a single mac address

Eg: 
AA:AA:AA:AA:AA:AA
BB:BB:BB:BB:BB:BB

• Press the Add '+' button
• Then press save

Create IP Lists

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

...

Image Added

As our requirement is to perform firmware upgrade, User need to configure the information  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 can be configured here.

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

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

Create Firmware Config

Before configuring Firmware essentials, Ensure application type is stb.

• • Select Firmware
Configs
• • Config option within
common
• • Firmware 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
• • XConf server.

...

Image Added

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

Create Firmware Rules

• • Select Firmware
Rule
• • Rules option within
common
• • Firmware 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.

Image Modified

...

3. Download Location

...

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

  There is a by default location available in Download Round Robin location filter’, but admin

...

• 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‘DOWNLOAD_LOCATION_FILTER’ 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.

Image Removed

...

•  Add the firmwareDownloadProtocol and the local http/tfp location as the firmwareLocation in XConf server. (Make sure local server and STB are in same network)

Image Added

By default, rebootImmediately flag will be false. If we need to perform reboot immediately after writing the image to other partition, User can configure REBOOT_IMMEDIATELY_FILTER

•  Go to Firmware -> Firmware Rules -> Define Properties -> Create
•  A page will be displayed with options to select the template. Select ‘REBOOT_IMMEDIATELY_FILTER’ from the list
• In this 'firmware rule' page with type 'REBOOT_IMMEDIATELY_FILTER', we can specify the 'rebootImmediately’ as true.

Image Added

Now we have everything configured in the XCONF server side. we can validate in the XConf Firmware test page to see the configurations set.

Verification using 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. 

How to

...

perform the Firmware upgrade in STB 

RDKUI has provides the option to upgrade perform the firmware upgrade. User can go to the option to Settings->Other Settings->Advanced Settings-> Device -> Firmware Update

Image Added

Select Check for Update

Image Removed

In this document, we are configuring local hfs server. 

Validations 

Validation performed in two devices. Amlogic skyworth and Sercomm realtek. 

Amlogic skyworth

We need to follow the same steps as mentioned in the How to Prepare for XCONF Server

To view the configurations set, we can use the Firmware Test page available as part of UI. 

Image Removed

You can specify any key value parameters here in this document Key value is used as "estbMac" and value as the <device mac address>

Image Removed

here download location filter is used. this is to configure for specifying local hfs server's ip and protocol

Image Removed

Initial screen

Image Removed

After clicking Check for Update the state will change to Downloading

Image Removed

Image Removed

Sercomm Realtek

The configuration used in Sercomm Realtek can be found same as the firmware test page as below. Here one more filter is configured which is rebootfilter this has rebootImmediately set to true , in addition to the Download filter. 

Which means when user clicks for "Check for Update", downloaded this firmware information configured in the XCONF server and boots up the image with that.  In the screenshoot, you would be able to see the image initially loaded was

sercom-generic-mediaclient-image_FBT_6.0.0-rc4_20231107155246 to sercom-generic-mediaclient-image_FBT_6.0.0-rc3_20231011085623

Image Removed

Initial screen

Image Removed

Image Removed

After clicking Check for Update the state will change to Downloading

Image Removed

...

Image Added

As this being the reference UI, Current implementation is using only the API calls not the Events of plugin and API is invoked only when a page transition is done. So we may need to go to the previous screen's in order to see the transitions

• State indicates validation is completed

Image Added

• State indicates when preparing for reboot 

Image Added

STB will check for upgrade and downloads to the other partition and next time boots up with this image. If reboot immediately filter is set to true in the XConf server, STB will go for immediate reboot once the image write is successful in the other partition.