Give an operator a RobustOS page for changing your application's settings and a separate view of its current state. RobustOS can generate these pages from XML definitions, so a basic settings page does not require custom JavaScript.

Applies to: RobustOS application packages that use the UCI and USI integration supplied with their matching SDK and firmware. Start with the sample_uci package included in that SDK. Check the page layout and available tags on the development device before deploying your application.

Separate settings from current state

The Unified Configuration Interface (UCI) holds configuration: values an operator chooses, such as an enabled flag or an integer limit. USI supplies status: values your program reports, such as a running counter or device information. Both use dotted tags to identify individual values, but their read functions and memory ownership differ.

Information	Definition and access	Example
Operator configuration	UCI XML; uci_get(), uci_set() and related functions	sample_uci.option_int
Application or system status	USI XML; usi_update(), usi_get() and related functions	sample_uci.counter

Define a field, publish or change its value, and check its appearance as separate actions. Adding a counter to the status XML creates its presentation; your application still has to update the counter. Reading a device status value does not change its configuration.

Before continuing, complete the first application workflow. Keep the SDK image, target and device firmware recorded with this experiment. Use an authorized device command-line interface (CLI) for tag discovery and a device shell only where the steps explicitly require one.

Start from the supplied sample

1. In the SDK workspace, inspect package/sample_uci, including its XML definitions, application source, lifecycle script and package Makefile. Preserve an original copy before changing the sample.
2. Check how the package installs its configuration and status definitions. The integration uses /etc/router/uci/<package>.xml and /etc/router/usi/<package>.xml as package destinations; follow the supplied package's installation rules.
3. Build and install the sample for the chosen device using the package-build and installation sequence from the first application guide. For this package, the SDK build target is package/sample_uci/install.
4. Open the sample's page under Services > SDK Sample Uci. Check the Sample Uci and Status tabs before modifying their definitions.

A working baseline lets you distinguish a package installation problem from a mistake in your own XML or application code. If the selected SDK does not include this sample, obtain the corresponding integration example for that release before proceeding.

Define the configuration page

The following definition contains a Boolean field, a string, an integer, an enumeration and a list. Use it to understand the sample's UCI XML. Keep the definition filename and installation rule consistent with your package.

<sample_uci desc="configuration of SDK Sample Uci"
            group="Services" group_weight="40"
            menu="SDK Sample Uci" menu_weight="901">
    <option_bool type="bool" desc="Bool Type Option" default="false"
                 tab="Sample Uci" tab_weight="0" area="General Settings" />
    <option_string default="test" desc="String Type Option" />
    <option_int type="int" desc="Integer Type Option" range="1..100"
                default="10" row_help="This is an integer type config option." />
    <option_enum type="enum" desc="Enum Type Option"
                 range="select1 select2" default="select1"
                 range_desc="Select_1 Select_2" />
    <option_list desc="List Example" area="List Type Options" max_entry_num="20">
        <id type="int" range="1..20" desc="Index"
            col_width="80" area="Popup Window Title" />
        <mac type="MAC_ADDR" unique="true" desc="MAC Address" col_width="140" />
        <ip type="IP_ADDR" unique="true" desc="IP Address" col_width="140" />
    </option_list>
</sample_uci>

The element names become the names used in tags. For example, the integer is sample_uci.option_int; an IP value in list entry 1 is sample_uci.option_list[1].ip. The display labels are separate: changing desc="Integer Type Option" changes the label, not the tag.

The example shows the relationship between the XML fields and the generated controls. Saved values and the appearance of controls can differ from the defaults and from other firmware versions.

These definitions omit optional SNMP OIDs for readability; the SDK 5.0.3 sample XML includes OIDs. The supplied USI sample also includes a cli_help attribute for its command-line help text. Add OIDs only when your application needs SNMP integration and its identifiers have been allocated for that purpose; do not copy sample OIDs into an unrelated application.

Arrange the page

Use layout attributes to place the application in the navigation and group its fields:

Attribute	Purpose
group, group_weight	Put application pages in Services, using group weight 40.
menu, menu_weight	Set the application's menu label and position. The default menu weight is 1000; this sample uses 901.
tab, tab_weight	Name and order tabs, such as configuration and status. The examples use weights 0 and 20.
area	Group related fields into an area.
desc	Supply a field's displayed label.
area_help, row_help	Add optional help for an area or a single configuration row.

Introduce each tab or area at the appropriate field in the definition, following the supplied sample. Keep the names stable if you later customize the generated JavaScript: they also determine generated page filenames.

Constrain field values

Attribute	Effect
type	Select string, int, enum or bool; the default is string. Special string types include IP_ADDR, NETMASK and MAC_ADDR.
range	Set a string-length range, integer range or available enumeration values, according to the field type.
range_desc	Give display descriptions for enumeration values.
default	Set the field's default value.
pattern	Supply a regular expression for string validation. Confirm expression support in the selected firmware before adding a custom rule.
max_entry_num	Mark a list and set its maximum number of entries.
unique	Require the field's value to be unique across list entries.
col_width	Include a list field in the overview table and set its displayed width; the documented range is 10–200.
oid	Assign an optional SNMP object identifier. OID-bearing definitions can generate a MIB. Use OIDs allocated for your application; in the SDK 5.0.3 sample, the top-level UCI and USI OIDs are 1001 and 1000 respectively.

In the SDK 5.0.3 sample on R1520 with RobustOS 5.6.0, a duplicate MAC or IP in the unique list can show “Invalid MAC / IP Address”. Check both the address format and existing entries. The sample string field does not declare a pattern; add a suitable pattern when your application requires format validation. Keep the actual application-side checks as well as the UI definition appropriate for the data you consume. Test the allowed minimum, maximum and invalid input for each field you add; a page rendering successfully does not establish that every validation rule works as intended.

Connect the page to your application

The XML defines the page and its configuration tags. Your application still has to read those tags and use their values. Read-only UCI access does not require uci_init(); configuration writes do. Keep the page definition, the application read or write, and the resulting behavior as separate checks.

Read and update application settings with the RobustOS UCI API explains scalar and list access, returned values, and the difference between writing, applying and saving configuration.

To show a running counter or other live state, install a separate USI XML definition under /etc/router/usi/<package>.xml. Use the USI status workflow to add a Status tab and publish values from your program. A UCI configuration field does not automatically become an application status value.

Check the generated integration

1. Confirm that the package installs its XML definitions and that Services > SDK Sample Uci appears.
2. Check the field types, labels, defaults, list controls and help text against the XML.
3. Test each field's allowed minimum, maximum and invalid input on the development device.
4. Change a harmless application-owned setting through the Web interface. Read its tag through UCI and verify the corresponding application behavior.
5. Add and inspect list entry 1; also test how the application handles an empty entry.
6. When persistent configuration is required, complete the firmware's save workflow and check the value after restart. Verify saving separately from applying a change.

Symptom	Check first
Application menu or tab is missing	XML package destinations; root element, group, menu and tab names; package installation result
A field has an unexpected control or label	type, desc, range and the applicable tab and area attributes
A tag returns no value	Actual configuration tag; list entry ID; whether the configuration definition was installed
A configuration change has no runtime effect	The write result, the intended apply step and the application's use of the setting
A value changes back after restart	Whether the required save workflow was completed

Continue with a custom file upload control when the generated configuration controls do not cover your application's input needs.