RDK Firmware Upgrade API Information

RDK Firmware Upgrade is the module which is handling the PCI/PDRI image upgrades across various RDK profiles.

• The modules updates the Xconf endpoint with current image configurations and capabilities on bootup. 
• Parse the device configuration informations from XCONF server
• Download the new release versions from CDL/CDN 

The module mainly includes following components

All Library present in common_utilities repo mention below url

rdkcentral/common_utilities

RDK Firmware Upgrade is the module which is handling the PCI/PDRI image upgrades across various RDK profiles.

• The modules updates the Xconf endpoint with current image configurations and capabilities on bootup. 
• Parse the device configuration informations from XCONF server
• Download the new release versions from CDL/CDN 

The module mainly includes following components

All Library present in common_utilities repo mention below url

rdkcentral/common_utilities

rdkfwupgrader uses shared libraries from common_utilities for firmware downloads, device information, JSON processing, filesystem operations, security, and upload workflows.

1. Download Library — libdwnlutil

Source: dwnlutils/
Headers: downloadUtil.h, urlHelper.h

Provides HTTP/HTTPS download functionality using libcurl.

Features

• Firmware-image downloads
• Chunk and resume support
• Chunk retry delay
• Download throttling
• Progress tracking
• Download interruption
• mTLS authentication
• Custom HTTP headers
• JSON-RPC communication
• File and memory downloads
• Curl and HTTP status reporting
• Optional curl debug logging

Main APIs

void *doCurlInit(void);
void doStopDownload(void *curl);

int doHttpFileDownload(
    void *in_curl,
    FileDwnl_t *pfile_dwnl,
    MtlsAuth_t *auth,
    unsigned int max_dwnl_speed,
    char *dnl_start_pos,
    int *out_httpCode
);

int doAuthHttpFileDownload(
    void *in_curl,
    FileDwnl_t *pfile_dwnl,
    int *out_httpCode
);

int doInteruptDwnl(
    void *in_curl,
    unsigned int max_dwnl_speed
);

unsigned int doGetDwnlBytes(void *in_curl);
int setForceStop(int value);

int getJsonRpcData(
    void *in_curl,
    FileDwnl_t *pfile_dwnl,
    char *jsonrpc_auth_token,
    int *out_httpCode
);

Lower-level APIs 

CURL *urlHelperCreateCurl(void);
void urlHelperDestroyCurl(CURL *ctx);

size_t urlHelperDownloadFile(
    CURL *curl,
    const char *file,
    char *dnl_start_pos,
    int chunk_dwnl_retry_time,
    int *httpCode_ret_status,
    CURLcode *curl_ret_status
);

size_t urlHelperDownloadToMem(
    CURL *curl,
    FileDwnl_t *pFileData,
    int *httpCode_ret_status,
    CURLcode *curl_ret_status
);

int urlHelperGetHeaderInfo(
    const char *url,
    MtlsAuth_t *sec,
    const char *pathname,
    int *httpCode_ret_status,
    int *curl_ret_status
);

CURLcode setCommonCurlOpt(
    CURL *curl,
    const char *url,
    char *pPostFields,
    bool sslverify
);

CURLcode setMtlsHeaders(CURL *curl, MtlsAuth_t *sec);
CURLcode setThrottleMode(CURL *curl, curl_off_t max_dwnl_speed);

The historical API name urlHelperPutReuqest() is also retained for HTTP PUT operations.

Main structures
 

typedef struct filedwnl {
    char *pPostFields;
    char *pHeaderData;
    DownloadData *pDlData;
    DownloadData *pDlHeaderData;
    int chunk_dwnl_retry_time;
    char url[BIG_BUF_LEN];
    char pathname[DWNL_PATH_FILE_LEN];
    bool sslverify;
    hashParam_t *hashData;
} FileDwnl_t;
 

typedef struct credential {
    char cert_name[64];
    char cert_type[16];
    char key_pas[65];
#ifdef LIBRDKCERTSELECTOR
    char engine[32];
#endif
} MtlsAuth_t;

2. Device and System Library — libfwutils

Source: utils/
Headers: common_device_api.h, rdk_fwdl_utils.h, system_utils.h

Provides device information, firmware metadata, filesystem operations, and system utilities.

Device and firmware APIs 

int getDeviceProperties(DeviceProperty_t *pDevice_info);
int getImageDetails(ImageDetails_t *pImageDetails);

size_t GetAccountID(char *out, size_t size);
size_t GetModelNum(char *out, size_t size);
size_t GetMFRName(char *out, size_t size);
size_t GetBuildType(char *out, size_t size, BUILDTYPE *type);
size_t GetFirmwareVersion(char *out, size_t size);
size_t GetEstbMac(char *out, size_t size);
size_t GetPartnerId(char *out, size_t size);
size_t GetSerialNum(char *out, size_t size);
size_t GetTimezone(char *out, const char *cpuArch, size_t size);
size_t GetUTCTime(char *out, size_t size);
size_t GetCapabilities(char *out, size_t size);
size_t GetRemoteInfo(char *out, size_t size);
size_t GetRdmManifestVersion(char *out, size_t size);
size_t GetTR181Url(TR181URL type, char *out, size_t size);
size_t GetServURL(char *out, size_t size);

bool isMediaClientDevice(void);
bool RDK_isDbgSrvUnlocked(void);
bool CurrentRunningInst(const char *file);

Filesystem and system APIs 

int filePresentCheck(const char *file_name);
int getFileSize(const char *file_name);
int createDir(const char *dirname);
int ensure_directory_exists(const char *dir_path);
int createFile(const char *file_name);
int removeFile(char *filePath);
int fileCheck(char *filePath);
int folderCheck(char *path);

int findFile(char *dir, char *search);
int findPFile(char *dir, char *search, char *out);
int findPFileAll(char *path, char *search, char **out, int *found, int max);

int emptyFolder(char *dir);
int copyFiles(char *src, char *dst);
int tarExtract(char *input, char *output);
int arExtract(char *input, char *output);

unsigned int getFreeSpace(char *path);
unsigned int checkFileSystem(char *path);
unsigned int getFileLastModifyTime(char *file_name);
time_t getCurrentSysTimeSec(void);

int cmdExec(const char *cmd, char *output, unsigned int size_buff);
int getProcessID(char *process, char *output);

cmdExec() executes a Linux command and captures its output in a buffer limited to 4096 bytes. It must not be used with unvalidated user input.

3. JSON Library — libparsejson

Source: parsejson/
Header: json_parse.h

Provides cJSON-based parsing for configuration and server responses.

APIs 

int SetJsonVars(char *fileIn, char *fileOut, int setenvvars);

JSON *ParseJsonStr(char *json);
int FreeJson(JSON *json);
JSON *GetJsonItem(JSON *json, char *key);

size_t GetJsonValFromString(
    char *json,
    char *key,
    char *output,
    size_t maxlen
);

size_t GetJsonVal(
    JSON *json,
    char *key,
    char *output,
    size_t maxlen
);

char *GetJson(char *filename);

bool IsJsonArray(JSON *json);
unsigned GetJsonArraySize(JSON *json);
JSON *GetJsonArrayItem(JSON *json, unsigned index);

The caller must:

• Call FreeJson() for objects returned by ParseJsonStr().
• Call free() for buffers returned by GetJson().

4. Upload Library — libuploadutil

Source: uploadutils/
Headers: uploadUtil.h, codebig_upload.h, codebigUtils.h, upload_status.h

Supports diagnostic, status, telemetry, HTTP, CodeBig, and S3 uploads.

Features

• Metadata POST
• S3 pre-signed URL uploads
• CodeBig workflows
• HTTP PUT uploads
• Optional mTLS
• Certificate rotation
• Hash metadata
• Upload status reporting
• Optional OCSP validation

Main APIs 

void doStopUpload(void *curl);

int performHttpMetadataPost(
    void *in_curl,
    FileUpload_t *upload,
    MtlsAuth_t *auth,
    long *httpCode
);

int extractS3PresignedUrl(
    const char *result_file,
    char *out_url,
    size_t out_url_sz
);

int performS3PutUpload(
    const char *s3url,
    const char *localfile,
    MtlsAuth_t *auth
);

int performS3PutUploadEx(
    const char *upload_url,
    const char *src_file,
    MtlsAuth_t *auth,
    const char *md5_base64,
    bool ocsp_enabled,
    UploadStatusDetail *status
);

int performCodebigUpload(
    const char *device_id,
    const char *local_file,
    const char *backend_url,
    MtlsAuth_t *auth
);

5. Security and Configuration

Security support includes:

• HTTPS through libcurl
• Server certificate verification
• mTLS using PEM or P12 certificates
• Optional certificate-selector integration
• Optional certificate-engine support
• Optional OCSP validation
• CodeBig signed URLs and authorization headers

Common configuration files include:
 

/etc/device.properties
/etc/include.properties
/version.txt
/opt/secure/RFC/bootstrap.ini
/opt/www/authService/partnerId3.dat
/opt/swupdate.conf

Common build flags include:
 

CURL_DEBUG
GTEST_ENABLE
IS_LIBRDKCERTSEL_ENABLED
IS_LIBRDKCONFIG_ENABLED
USE_CPC_CODE
L2UPLOADENABLED

6. Firmware Upgrade Integration

A typical rdkfwupgrader workflow is:
 

1. Read device and firmware information
   -> libfwutils

2. Read JSON configuration or server responses
   -> libparsejson

3. Initialize curl and security settings
   -> libdwnlutil

4. Download firmware metadata and image
   -> libdwnlutil

5. Check files, storage, and image paths
   -> libfwutils

6. Upload status, logs, or diagnostic data
   -> libuploadutil