Read and update application settings with the RobustOS UCI API

Use the RobustOS Unified Configuration Interface (UCI) to read application settings, change values and maintain configuration lists. A dotted tag identifies the setting; the API call determines whether you read, compare or modify it.

Applies to: C applications built with a matching RobustOS SDK and deployed to the exact device model and firmware for that SDK target. Use the librouter headers and libraries supplied with the selected SDK. API availability and declarations must match those headers.

Start with an installed sample_uci package or your application's configuration definition. Add a configuration page to the RobustOS Web interface explains the XML and package destinations. The C snippets below are application excerpts: keep the includes, initialization and link settings from the matching SDK sample.

Find the configuration tag

On the device command-line interface (CLI), inspect configuration with show:

show sample_uci all
show lan all

A scalar field can be addressed as sample_uci.option_string. For a network entry with id = 1 under lan, an IP field can be addressed as lan.network[1].ip. List IDs begin at 1. Use the IDs shown by your device; do not assume a contiguous list or convert them into zero-based array indexes.

The CLI supports completion: type set, then press Tab to explore configuration menus and fields. Use an approved administrative access method and do not submit an unrelated change merely to discover a tag.

UCI holds chosen configuration. To query current device or application state, use the USI status API instead.

Understand the result conventions

Use the types and constants from your SDK headers. status_t results use OK (0) for success and ERROR (-1) for failure where specified below. bool_t predicates use TRUE (1) or FALSE (0) for their stated test; do not assume a separate error result.

Check a string result for NULL before reading it. A returned empty string is different from a NULL pointer. uci_get() returns a borrowed pointer that you must not free; the lifetime and ownership of uci_list_get() must follow the selected SDK's contract. An integer getter that returns 0 on error cannot distinguish a valid zero from failure by that value alone.

Start and close a modification session

status_t uci_init(void);
status_t uci_close(void);

Call uci_init() before modifying configuration. Read-only configuration access does not require it. If you called uci_init(), call uci_close() before exiting. Both return OK or ERROR; check the initialization result before attempting writes.

Changing a value, applying it to services and saving it are separate actions. The device command uci apply applies changes without saving; uci save saves changes; uci commit saves and applies changes. Closing a UCI session is not a substitute for choosing the required apply/save workflow. Plan configuration changes against a development device because applying network settings can change your connection to it.

Read scalar values and test them

const char *uci_get(const char *tag);
int32_t uci_get_int(const char *tag);
bool_t uci_match(const char *tag, const char *value);
bool_t uci_check_bool(const char *tag);

Function	Inputs and result
`uci_get`	`tag` identifies the configuration item. Returns its value pointer, or `NULL` on error. Do not free the returned pointer.
`uci_get_int`	Reads the integer value at `tag`. Returns that value, or `0` on error; zero alone is inconclusive.
`uci_match`	Compares the item at `tag` with the supplied string `value`. Returns `TRUE` for a match and `FALSE` otherwise.
`uci_check_bool`	Returns `TRUE` when the value at `tag` is the string `"true"`; otherwise returns `FALSE`. Do not substitute numeric truth tests for this string contract.

This reading fragment assumes that the sample_uci configuration definition is installed:

const char *value = uci_get("sample_uci.option_string");
if (value != NULL) {
    printf("Option = %s\n", value);
}

if (uci_check_bool("sample_uci.option_bool")) {
    /* Handle the enabled setting. */
}

if (uci_match("sample_uci.option_enum", "select1")) {
    /* Handle this configured choice. */
}

The comments identify application-specific behavior, not missing SDK functions. An integer read of the same example would use uci_get_int("sample_uci.option_int"); handle its ambiguous zero result according to the field's allowed values and the selected SDK's error information.

Write a scalar value

status_t uci_set(const char *tag, const char *value);

tag identifies the item and value supplies its string value. The result is OK or ERROR. Initialize UCI first, check the write result, and then perform the intended apply/save action. Use the configuration definition to determine valid values; check the selected SDK for the validation and conversion behavior of uci_set().

Inspect and traverse a configuration list

int32_t uci_list_get_max_entry_num(const char *tag);
bool_t uci_list_entry_empty(const char *tag, uint32_t id);
const char *uci_list_get(const char *list_tag, uint32_t id,
                         const char *member_name);
bool_t uci_list_match(const char *list_tag, uint32_t id,
                     const char *member_name, const char *value);

tag or list_tag names the list itself, such as sample_uci.option_list. id is its one-based entry ID. member_name names a member within that entry, such as ip.

Function	Result and use
`uci_list_get_max_entry_num`	Intended to obtain the maximum entry number for traversal. Check the release header/sample before using its result as a loop bound: confirm both its maximum-entry result and failure indication for your SDK. Do not use an unconfirmed result as a populated-row count.
`uci_list_entry_empty`	Returns `TRUE` if the given entry is empty, otherwise `FALSE`. Check an entry before treating it as populated.
`uci_list_get`	Returns the specified member's value pointer, or `NULL` on error. Check the SDK's pointer ownership/lifetime contract.
`uci_list_match`	Compares the specified member with `value`; returns `TRUE` for a match, otherwise `FALSE`. This is a comparison, not a setter.

Once the maximum-entry contract is confirmed, traverse IDs starting at 1, skip empty entries, read the required member and check its pointer before use. Do not infer that a maximum entry number is a count of populated entries or that list IDs are contiguous.

Create, update and delete configuration entries

status_t uci_list_add(const char *tag, uint32_t id);
status_t uci_list_del(const char *tag, uint32_t id);
status_t uci_list_set(const char *list_tag, uint32_t id,
                      const char *member_name, const char *value);

Function	Action and result
`uci_list_add`	Add an entry with the specified list ID before setting its members. Returns `OK` or `ERROR`. Confirm occupied-ID and default-value behavior in the SDK before relying on it.
`uci_list_set`	Set `member_name` in entry `id` to string `value`. Returns `OK` or `ERROR`.
`uci_list_del`	Delete the entry with ID `id`. Returns `OK` or `ERROR`. This removes an entry; it is not equivalent to assigning an empty string to a member.

Use a UCI modification session for these operations and check each result. The return contracts do not establish transaction or rollback behavior for a series of changes.

Apply and verify a deliberate change

Record the exact tag and its original value on the device CLI.
Initialize UCI in your application, check the result, then write one harmless application-owned setting and check that result.
Choose whether the change should be applied, saved or both. In the device shell, uci apply applies without saving, uci save saves, and uci commit saves and applies. Use the operation intended for your application and firmware.
Close the initialized UCI session before exiting and check the result.
Read the resulting configuration, check the application's behavior, and test restart persistence separately if required.

Warning: Applying network settings can interrupt access to the device. For example, changing link_manager.primary_link to a configured link such as wwan2 can move the active connection. Use a development device with a recovery path. A link name does not prove which physical SIM is active; verify the device's status after a planned change.

Symptom	Check first
String read returns `NULL`	Installed configuration definition, exact tag and actual list entry ID
Integer read returns `0`	Allowed field values and the selected SDK's error information; zero alone is inconclusive
Write fails	`uci_init()` result, exact tag, valid value and write return value
Value changes but the service does not	Intended apply step and the application's use of the setting
Value reverts after restart	Required save workflow; `uci apply` alone does not save
List iteration skips or misreads data	One-based IDs, empty entries and a confirmed maximum-entry contract

Return to the RobustOS SDK guide for related development tasks.

Read and Change RobustOS Settings with the UCI C API