The RDK firmware upgrader, the RDK agent at the CPE device side with the goal to provide an efficient and safe way to upgrade Firmware on the Field boxes. The module has the capability to

• Ping cloud server to get new Firmware images
• Download the images to secure location
• Verify the signature of the downloaded firmware
• Flash the image onto the box using manufacture library APIs

The module supports the upgrade of multiple Firmware types to RDK unit (RDK Video and stream boxes.)

• PCI
• PDRI
• Remote Firmware
• Additional supports to deploy and updates security certificate bundles 

Repository

rdkcentral/rdkfwupdater

The module also does the latest firmware image verification of installed firmware on every boot cycle and during maintenance window time.

This framework is design and developed to download latest firmware from the SSR server by communication with XCONF server. When device boot up it communicate with XCONF server and get the firmware details as a response and then check either running/active firmware compare with XCONF response firmware. If the firmware is different then it proceeds for downloading new firmware and flashing to the device bank. The framework also supports to download and flash PDRI and peripheral firmware. If the firmware is same, then download won't start and firmware upgrader application exit. Same procedure is applicable during maintenance window time.

Here the firmware images are signed and deployed to SSR server during the build time and box will download the firmware from SSR server based on the XCONF response information available.

Sub Functionalities

This service provides the download location (URL) required for RDK download Manager for dynamic Apps/packages/certs/tools installation. This module is responsible to trigger RDM Application. The module will do the security evaluation of the downloaded packages and verify the signature to ensure the installation of packages. 

RDK Firmware Upgrader

The App or binary name as part of rootfs is "rdkvfwupgrader". This module having below components

rdkv_main: This is the main process name for the module which will use all the below sub-components to collect the required data for xconf communication, download the image types from the SSR end points and flashing to the memory.

Sub-components

deviceutils

This component is responsible to get all device information like build info, partner id, mac address etc.

Below are the Function use to get device information.

BuildRemoteInfo:  Formats the "periperalFirmwares" string for remote info part of xconf communication

getJsonRpc : This is the API use to get JSONRPC data. The first argument is http post data and second argument holds the downloaded data. As part of post data need to send curl header which contains content type and authorization token.

getInstalledBundleFileList: gets the list of bundles installed on a device

GetServURL - gets the correct XCONF URL based on device configuration.

GetTimezone: This function is use to get the timezone of the device.

GetAdditionalFwVerInfo: This function is use to get the PDRI image details from the device.

GetInstalledBundles: This function is use to extract the bundle installed in the device.

GetUTCTime: gets a formatted UTC device time.

GetCapabilities - gets the device capabilities.

GetPartnerId - gets the partner ID of the device.

GetTargetProposition - gets the TargetProposition of the device.

GetSerialNum - gets the serial number of the device.

GetExperience - gets the experience of the device.

GetAccountID - gets the account ID of the device.

GetModelNum - gets the model number of the device.

GetBuildType - gets the build type of the device in lowercase.

GetFirmwareVersion - gets the firmware version of the device.

GetEstbMac - gets the eSTB MAC address of the device.

GetRemoteInfo - gets the remote info of the device.

flash

Handles flashing of downloaded PCI and PDRI images.

The component:

• Calls the platform-specific /lib/rdk/imageFlasher.sh utility.
• Updates firmware and image-download status.
• Sends update and maintenance events.
• Handles reboot and post-flash processing.

iarmInterface

This component provides an API interface to use IARM-related calls. The application uses init_event_handler() function to initialize and register IARM Event. IARM Event is used to receive the event from other modules. Here maintenance manager sends an event when the device mode changes. There are 2 modes foreground and background. If the mode is foreground the firmware download happens at limited speed which is called throttle mode and if the mode is background then the download happens at full speed which is un-throttle mode.

eventManager: This is used to send IARM broadcast events to other modules. This application sends firmware download status to maintenance manager and system manager.

All the firmware download state macro is defined as part of iarmInterface.h file

Broadcast Event For Maintenance Manager:

Broadcast Event For System Service

jsonparse

This component is responsible for processing the xconf response and parse the json file. Then create a data structure to use further.

The firmware upgrader queries Xconf to check whether any upgrade is available for this device. The API is used to communicate with the Xconf and below are its typical parameters. The device details are fetched using the APIs as part of the deviceutils component.

It is built into librdksw_jsonparse. The Main APIs are

size_t createJsonString(

  char *pPostFieldOut,

  size_t szPostFieldOut

); 

int getXconfRespData(

  XCONFRES *pResponse,

  char *pJsonStr

); 

int processJsonResponse(

  XCONFRES *response,

  const char *myfwversion,

  const char *model,

  const char *maint

);

createJsonString

Builds the device-information query sent to XConf. The request can contain fields such as:

eStbMac,firmwareVersion,additionalFwVerInfo,env,model,manufacturer,partnerId,
activationInProgress,osClass,accountId,experience,migrationReady,serial,localtime,
dlCertBundle,dlAppBundle,rdmCatalogueVersion,timezone,capabilities

Example:

eStbMac=00:11:22:33:44:55&firmwareVersion=example-image&env=prod&model=MODEL&manufacturer=Vendor&partnerId=partner&activationInProgress=false&osClass=Linux&accountId=1234&serial=ABC123&localtime=Wed Nov 26 13:44:09 UTC 2025&dlCertBundle=&dlAppBundle=&rdmCatalogueVersion=&timezone=UTC&capabilities=rebootDecoupled&capabilities=RCDL&capabilities=supportsFullHttpUrl

XConfResponse

The current XConf response structure is:

typedef struct xconf_response { 
  char cloudFWFile[128];
 char cloudFWLocation[CLD_URL_MAX_LEN];
char ipv6cloudFWLocation[CLD_URL_MAX_LEN];
char cloudFWVersion[64];
char cloudDelayDownload[8];
char cloudProto[6];
char cloudImmediateRebootFlag[12];
char peripheralFirmwares[256];
char dlCertBundle[64];
char dlAppBundle[64];
char cloudPDRIVersion[64];
char rdmCatalogueVersion[512];
/* Direct CDN per-artifact URLs */
char firmwareUrl[CLD_URL_MAX_LEN];
char remCtrlUrl[CLD_URL_MAX_LEN];
char pdriUrl[CLD_URL_MAX_LEN];
} XCONFRES;

XConf response fields

{
"firmwareDownloadProtocol":"http",
"firmwareFilename":"lib32-application-test-image-RPI4-raspberrypi4-64-rdke-feature-RDKECOREMW-863-OTA.wic.tar.gz",
"firmwareLocation":"https://tools.rdkcentral.com:8443/images/",
"firmwareVersion":"lib32-application-test-image-RPI4-raspberrypi4-64-rdke-feature-RDKECOREMW-863-OTA.wic.tar.gz",
"rebootImmediately":false
}

rfcInterface

This component provided rfc api to use for getting rfc value and setting rfc value.

This component is responsible for reading the rfc value and writing the rfc value. Below are the rfc used in this module.

1. RFC_THROTTLE: This is used to enable the throttle download feature. Using this feature we can control the download speed. RFC_TOPSPEED value is used to decide the speed of the download. This feature is used for a better experience for the user while watching videos.
2. RFC_INCR_CDL: This is used to enable the incremental/chunk download. Using this feature we can resume the download if the download is failed due to slow internet(curl error code 18) and max time out (curl error code 28). Using this feature we can save the network usage data and quick firmware upgrade.
3. RFC_DIRECT_CDN: This is use for enable direct cdn feature. If this feature is enable image download happen using signing url provided by xconf server.

Firmware download and upgrade engine

The core download engine is implemented in:

• src/rdkv_upgrade.c
• src/chunk.c
• src/include/rdkv_upgrade.h

The implementation is built into librdksw_upgrade.

Context-based upgrade API

The previous scalar upgradeRequest interface has been replaced by RdkUpgradeContext_t.

typedef struct {
    int upgrade_type;
    int server_type;
    const char *artifactLocationUrl;
    const void *dwlloc;
    char *pPostFields;
    const char *immed_reboot_flag;
    int delay_dwnl;
    const char *lastrun;
    char *disableStatsUpdate;
    const DeviceProperty_t *device_info;
    int *force_exit;
    int trigger_type;
    const Rfc_t *rfc_list;
    int download_only;
    bool direct_cdn;
} RdkUpgradeContext_t;

The main request function is:

int rdkv_upgrade_request(
    const RdkUpgradeContext_t *context,
    void **curl,
    int *pHttp_code
);

Main download functions

int downloadFile(
    const RdkUpgradeContext_t *context,
    int *httpCode,
    void **curl
);

int codebigdownloadFile(
    const RdkUpgradeContext_t *context,
    int *httpCode,
    void **curl
);

int retryDownload(
    const RdkUpgradeContext_t *context,
    int retry_cnt,
    int delay,
    int *httpCode,
    void **curl
);

int fallBack(
    const RdkUpgradeContext_t *context,
    int *httpCode,
    void **curl
);

Supported download behavior

The upgrade engine supports:

• XConf downloads.
• SSR/direct downloads.
• CodeBig downloads.
• HTTP retry processing.
• Direct-to-CodeBig fallback where enabled.
• Incremental/chunk downloads.
• Download resumption.
• Download throttling.
• State-red recovery.
• Force-stop handling.
• HTTP status reporting.
• PCI, PDRI, peripheral, and XConf upgrade types.

Direct CDN behavior

Direct CDN is enabled through SWDLDirect.Enable.

When enabled:

• XConf can provide a separate URL for each artifact.
• CodeBig fallback is skipped.
• PCI, PDRI, and peripheral artifacts can be processed independently.
• HTTP 403 responses are treated as token-expiration responses and cause the caller to refresh the XConf URL.
• mTLS certificate acquisition is skipped for normal Direct CDN downloads.
• The state-red recovery path can still use the recovery certificate.

The Direct CDN flow is implemented through src/directcdn.c and the per-artifact orchestration in src/rdkv_main.c

RDK Firmware Upgrader Capability

1. Communicate with XCONF server and get the response.
2. Processing of XCONF response and extract the firmware image details.
3. Download and flash PCI image from the SSR server to device flash memory.
4. Download and flash PDRI image from the SSR server to device flash memory.
5. Download and flash peripheral image from the SSR server to device flash memory.
6. retry download if download fail other than image not found on server error.
7. Trigger RDM Application.
8. Download cert bundle.
9. Support state red recovery download if the download is fail due to invalid certificate.
10. Support incremental download. This feature needs to be enable using "Device.DeviceInfo.X_RDKCENTRAL-COM_RFC.Feature.IncrementalCDL.Enable" RFC
11. Support Throttle download based on download speed mentioned. This feature needs to be enable using "Device.DeviceInfo.X_RDKCENTRAL-COM_RFC.Feature.SWDLSpLimit.Enable" RFC

Low Level Design Flow From Start To End

1. Trigger: This module is triggered by Maintenance Manager, boot-up, scheduled window, application, TR-69/SNMP, delayed download, or State Red recovery.
2. Initialization: Initializes logging, telemetry, IARM, signal handling, device information, current image details, RFC settings, and download directory. Prevents multiple updater instances using the PID file.
3. Validation: Check device exclusion, existing update activity, previous reboot status, and current image information. Enters State Red recovery when required.

4. XConf Communication: Builds the XConf request using device details such as MAC, model, partner ID, firmware version, serial number, bundles, timezone, and capabilities. The request is sent using the configured Direct or Codebig connection. Below is the sample XCONF query request.

   eStbMac=D8:3A:DD:0A:43:71&firmwareVersion=lib32-middleware-test-image-RPI4-20251118074027&env=dev&model=RPI4&manufacturer=RaspberryPi&partnerId=community&activationInProgress=false&osClass=Not Available&accountId=1234&serial=10000000e33bf0d4&localtime=Wed Nov 26 13:44:09 UTC 2025&dlCertBundle=&rdmCatalogueVersion=&timezone=Asia/Calcutta&capabilities=rebootDecoupled&capabilities=RCDL&capabilities=supportsFullHttpUrl

   
   

5. Response Processing: Once the query request is formed then this module send the request to XCONF server and get the response. Parses the JSON response for PCI, PDRI, peripheral firmware, bundle, download, and reboot information. Validates that the firmware matches the device model if image is invalid then this module is exit with error message. The response is in json format.

   { "firmwareDownloadProtocol":"http", "firmwareFilename":"lib32-application-test-image-RPI4-raspberrypi4-64-rdke-feature-RDKECOREMW-863-OTA.wic.tar.gz", "firmwareLocation":"https://tools.rdkcentral.com:8443/images/", "firmwareVersion":"lib32-application-test-image-RPI4-raspberrypi4-64-rdke-feature-RDKECOREMW-863-OTA.wic.tar.gz", "mandatoryUpdate":false, "rebootImmediately":false }

   
   

6. Download: Processes the updates in order PCI → PDRI → peripheral firmware. Supports Direct CDN, SSR, Codebig fallback, retries, throttling, mTLS, and resumable/chunked downloads. If the download is failed due to certificate validation error, then state red recovery download will trigger. This is a kind of recovery server which is use static certificate to download image.

7. Flash: Flashes PCI and PDRI images through the device-specific /lib/rdk/imageFlasher.sh. PDRI processing includes the required filename handling and PCI/PDRI synchronization delay. PDRI upgrades do not require a reboot.

8. Peripheral Updates : Compares installed and previously downloaded versions. Downloads only required peripheral packages and report them through PeripheralUpgradeEvent.

9. Post-Processing: Updates firmware status, security-stage information, flashed-image records, and State Red status. Handles reboot requirements through Maintenance Manager or /rebootNow.sh, based on the XConf and platform configuration

10. Status and Cleanup: Publish progress and result through IARM, Maintenance Manager, RFC, status files, and telemetry. Remove temporary flags, release resources, unregister IARM, and exit with the final status.

Firmware Download Trigger Sequence Diagram in RDK-V Device:

Below Sequence diagram is for device where maintenance manager is running

Sequence Diagram RDKE

1. In above Sequence Diagram Maintenance Manager is parg of rdkservices module. Which is responsible for all the device maintenance activity.
2. rdkvfwupdater is a binary having iarm, rfc and flash app in a single monolithic image.
3. download lib, utils lib and jason parser all 3 are part of common-utilities component. This module will provide all 3 shared library which can link to other module. 

New Refactor Design

• RDK Firmware Upgrade API Information
• Validation of firmware upgrader in RDKE RPI builds