{"id":11463,"date":"2023-12-27T10:45:47","date_gmt":"2023-12-27T10:45:47","guid":{"rendered":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/"},"modified":"2025-03-25T05:18:32","modified_gmt":"2025-03-25T05:18:32","slug":"firmware_upgrade","status":"publish","type":"page","link":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/","title":{"rendered":"Firmware Upgrade"},"content":{"rendered":"\n


\n <\/p>\n

\n
\n
\n
\n
<\/div>\n<\/div>\n<\/div>\n<\/div>\n
\n
\n
\n\n\n

Introduction<\/span><\/h2>\n\n\n

The Firmware upgrade component will upgrade the device firmware depending upon the configurations given against the device in XConf server. <\/span><\/span><\/span><\/span>This process involves determining which version to download, where to download it from (including support for FQDN and secure endpoints), the protocol for downloading (with HTTPS as the preferred method and fallback to HTTP or TFTP), and the ability to schedule firmware checks based on timezones and quiet times. Additionally, the reboot can be decoupled, allowing for a later or scheduled reboot after the firmware download.<\/span><\/span> <\/span><\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n
\n
\n
<\/div>\n<\/div>\n<\/div>\n
\n
\n
\n\n\n

Architecture<\/h2>\n\n\n
\n
<\/div>\n
\"FirmwareArchitecture\"<\/div>\n<\/div>\n

On the server side, the business logic determines which version of the firmware code needs to be provided for download. The firmware upgrade process is initiated by the device, which sends information such as its current firmware version and capabilities to the server. Based on this information, the server identifies the appropriate firmware version and provides the download location. The firmware upgrade mechanism uses the CPE to download the code from the server.<\/span><\/p>\n

On the device side, the firmware upgrade process is managed by the System rdkservices plugin(org.rdk.System<\/a>), which handles user-initiated upgrades through the updateFirmware<\/strong> method. This plugin invokes the deviceInitiatedFWDnld.sh<\/strong> script to communicate with the XConf server and fetch the required firmware information. Once the server responds with the firmware version and download instructions, the script initiates the download. After the download is complete, a device-specific script executes to handle platform-specific tasks and verify the integrity of the downloaded firmware. Following this verification, the script invokes the OEM Flash Utility to apply the new firmware.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n
\n
\n
<\/div>\n<\/div>\n<\/div>\n
\n
\n
\n\n\n

Configuration Details<\/h2>\n\n\n

CPE makes an HTTPS request to XConf to get firmware information. The request may be an HTTPS POST or GET. The response is a JSON string. An example GET for the production XConf instance would look like this. <\/p>\n

\n
\n
https:\/\/xconf.rdkcentral.com:19092\/xconf\/swu\/stb?eStbMac=AA:BB:CC:DD:EE:FF<\/pre>\n<\/div>\n<\/div>\n
The following table lists some of the parameters which may be sent.<\/p>\n
\n\n\n<\/colgroup>
Name<\/th>Example value<\/th>Description<\/th><\/tr>
capabilities<\/td>rebootDecoupled, RCDL, supportsFullHttpUrl etc.<\/td>
Specifies capabilities of the CPE that XConf needs to know about. This is a multi-valued parameter. More than one capability may be sent. Separate the values using url?capabilities=value1&capabilities=value2&capabilities=value3.<\/p>
These capabilities should not live forever. Once all CPEs are known to support a given capability, XConf should deprecate\/delete code that handles CPEs that don’t support the capability and CPE should stop sending the capability value.<\/p><\/td><\/tr>
env<\/td>PROD | VBN | QA | DEV<\/td>environment of the CPE.<\/td><\/tr>
eStbMac<\/td>AA:BB:CC:DD:EE:FF<\/td>MAC address of the CPE.<\/td><\/tr>
firmwareVersion<\/td>abc123<\/td>CPE’s current firmware version.<\/td><\/tr>
ipAddress<\/td>192.0.2.146<\/td>IP address of the device.<\/td><\/tr>
model<\/td>abcd<\/td>CPE model.<\/td><\/tr>
rebootImmediately<\/td>true|false<\/td>immediate reboot flag.<\/td><\/tr><\/tbody><\/table>\n\n\n<\/div>\n
JSON Response from XConf server<\/span>:<\/u><\/p>\n
XConf returns firmware information as a JSON string, as shown in the following sample.<\/span><\/p>\n
\n
\n
{\n\"firmwareDownloadProtocol\":\"tftp\",\n\"firmwareFilename\":\"rdkb-generic-broadband-image_rdkb-2024q1-dunfell_20240609064020.rootfs.wic\",\n\"firmwareLocation\":\"192.168.161.216\",\n\"firmwareVersion\":\"rdkb-generic-broadband-image_rdkb-2024q1-dunfell_20240609064020\",\n\"ipv6FirmwareLocation\":\"fe80::da3a:ddff:fe0a:aad2\/64\",\n\"rebootImmediately\":false,\n\"mandatoryUpdate\":false\n}<\/pre>\n<\/div>\n<\/div>\n
XConf should be able to add new values, and the CPE should still be able to process the JSON string by ignoring any values it doesn’t understand.<\/span><\/p>\n
Error Handling<\/u><\/p>\n
\n\n\n<\/colgroup>
Error<\/th>Description<\/th><\/tr>
500 Internal Server Error<\/td>On server error, CPE may implement retry logic or not. Most 500 errors will be caused by bad requests, but some may be temporary conditions.<\/td><\/tr>
Timeout<\/td>If the request to XConf times out, CPE should implement retry logic.<\/td><\/tr>
404 \/ Empty JSON<\/td>There are times when XConf does not wish to respond to the CPE. 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 CPE should ignore these responses (and not retry the request to XConf).<\/td><\/tr><\/tbody><\/table>\n\n\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n
\n
\n
\n
<\/div>\n<\/div>\n<\/div>\n
\n
\n
\n\n\n
Firmware Upgrade using RDK Community XConf Server<\/h2>\n\n\n
RDKM offers a reference XConf server that is publicly accessible at the URL <\/span>xconf.rdkcentral.com<\/a>. Users have the option to either use this XConf server or create their own.<\/span><\/p>\n
In RDKM XConf server- <\/span>xconf.rdkcentral.com<\/a><\/span>, user would be able to see two options in the landing page<\/span><\/p>\n
    \n
  1. XConf Admin UI<\/li>\n
  2. XConf Data service<\/li>\n<\/ol>\n
    <\/span><\/span><\/p>\n
    Users can configure firmware rules, configurations, telemetry settings, RFC settings, etc., in the admin UI. The data service currently provides the XConf version information, including which version is used, when it was last updated, and the commit information.<\/span><\/p>\n
    To know more about the process of firmware upgrade using the RDKM XConf server at xconf.rdkcentral.com<\/a>, please click here<\/a>. If you are interested in setting up a custom XConf server, please visit the XConf server user guide for configuration and feature validation<\/a> for detailed instructions on installation and usage.<\/p>\n<\/div>\n<\/div>\n<\/div>\n
    \n
    \n
    \n<\/div>\n<\/div>\n<\/div>\n<\/div>\n
    <\/p><\/body><\/html>\n","protected":false},"excerpt":{"rendered":"
    Introduction The Firmware upgrade component will upgrade the device firmware depending upon the configurations given […]<\/p>\n","protected":false},"author":28,"featured_media":0,"parent":11460,"menu_order":1,"comment_status":"open","ping_status":"closed","template":"","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"footnotes":""},"class_list":["post-11463","page","type-page","status-publish","hentry"],"yoast_head":"\nFirmware Upgrade - RDK Documentation Portal | Documentation<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Firmware Upgrade - RDK Documentation Portal | Documentation\" \/>\n<meta property=\"og:description\" content=\"Introduction The Firmware upgrade component will upgrade the device firmware depending upon the configurations given […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/\" \/>\n<meta property=\"og:site_name\" content=\"RDK Documentation Portal | Documentation\" \/>\n<meta property=\"article:modified_time\" content=\"2025-03-25T05:18:32+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"4 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/\",\"url\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/\",\"name\":\"Firmware Upgrade - RDK Documentation Portal | Documentation\",\"isPartOf\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png\",\"datePublished\":\"2023-12-27T10:45:47+00:00\",\"dateModified\":\"2025-03-25T05:18:32+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#primaryimage\",\"url\":\"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png\",\"contentUrl\":\"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png\",\"width\":597,\"height\":352},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documentation\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Device Management\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"Xconf\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/\"},{\"@type\":\"ListItem\",\"position\":5,\"name\":\"Firmware Upgrade\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/#website\",\"url\":\"https:\/\/developer.rdkcentral.com\/documentation\/\",\"name\":\"RDK Documentation Portal | Documentation\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/developer.rdkcentral.com\/documentation\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Firmware Upgrade - RDK Documentation Portal | Documentation","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/","og_locale":"en_US","og_type":"article","og_title":"Firmware Upgrade - RDK Documentation Portal | Documentation","og_description":"Introduction The Firmware upgrade component will upgrade the device firmware depending upon the configurations given […]","og_url":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/","og_site_name":"RDK Documentation Portal | Documentation","article_modified_time":"2025-03-25T05:18:32+00:00","og_image":[{"url":"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png","type":"","width":"","height":""}],"twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"4 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/","url":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/","name":"Firmware Upgrade - RDK Documentation Portal | Documentation","isPartOf":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/#website"},"primaryImageOfPage":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#primaryimage"},"image":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#primaryimage"},"thumbnailUrl":"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png","datePublished":"2023-12-27T10:45:47+00:00","dateModified":"2025-03-25T05:18:32+00:00","breadcrumb":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#primaryimage","url":"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png","contentUrl":"https:\/\/developer.rdkcentral.com\/documentation\/wp-content\/uploads\/sites\/16\/2024\/10\/FirmwareArchitecture.png","width":597,"height":352},{"@type":"BreadcrumbList","@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/firmware_upgrade\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/developer.rdkcentral.com\/documentation\/"},{"@type":"ListItem","position":2,"name":"Documentation","item":"https:\/\/developer.rdkcentral.com\/documentation\/"},{"@type":"ListItem","position":3,"name":"Device Management","item":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/"},{"@type":"ListItem","position":4,"name":"Xconf","item":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/device_management\/xconf\/"},{"@type":"ListItem","position":5,"name":"Firmware Upgrade"}]},{"@type":"WebSite","@id":"https:\/\/developer.rdkcentral.com\/documentation\/#website","url":"https:\/\/developer.rdkcentral.com\/documentation\/","name":"RDK Documentation Portal | Documentation","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/developer.rdkcentral.com\/documentation\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"}]}},"_links":{"self":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/11463","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/users\/28"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/comments?post=11463"}],"version-history":[{"count":3,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/11463\/revisions"}],"predecessor-version":[{"id":11522,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/11463\/revisions\/11522"}],"up":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/11460"}],"wp:attachment":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/media?parent=11463"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}