Including UspPa in a device

The USP protocol agent (UspPa) is normally disabled in RDK-B.

To enable it, add the following line to your target device bit bake layer:

DISTRO_FEATURES_append = " usppa"

UspPa is currently enabled in the RaspberryPI build of RDK-B.

To disable it, comment out, or remove the above line from meta-cmf-raspberrypi/conf/distro/include/rdk-rpi.inc.

USP Database

The configuration settings for UspPa are stored in a database.

On the device, the database is located at "/nvram/usp-pa.db".

Modifying the factory reset file

The factory reset file contains the default configuration settings. 

If no USP database exists when UspPa starts, then a USP database will be created using the values in the factory reset file.

You will need to modify it to point to the USP Controller that you are using.

On the device, the factory reset file is located at "/etc/usp-pa/usp_factory_reset.conf".

After making changes to this file, you must (IMPORTANT) delete the USP database, then restart UspPa, in order for the changes to take effect.

Adding to the USP trust store

When connecting to a USP Controller, TLS may be used.

UspPa validates the Controller's TLS certificate using the CA certs located in "/etc/usp-pa/usp_truststore.pem". You can add CA certs to this file. After adding certs, you must restart UspPa for the changes to take effect.

Command Line Tool

UspPa may be invoked as a command line tool using the '-c' option.

For example you can get parameters, query the supported data model or stop the UspPa daemon process.

To see a list of commands supported in CLI mode use:

$ UspPa -c help

Troubleshooting

CCSP_ERR_INVALID_PARAMETER_NAME

If a USP Get results in the following error:

err_msg: "RDK_GetGroup: CcspBaseIf_getParameterValues() failed (9005 - CCSP_ERR_INVALID_PARAMETER_NAME)"

This error is caused by a mismatch between the supported data model in UspPa (as defined by UspPa's config files) and the supported data model in RDK-B. Most likely some parameters in RDK-B have been removed or renamed.

UspPa can discover the RDK-B data model at bootup and regenerate the data model config files.
To regenerate the files, on the device, delete out the following files from the directory /etc/usp-pa:

usp_dm_comps.conf
usp_dm_objs.conf
usp_dm_params.conf

When UspPa starts up again, it will regenerate the files. You could then copy the files back into your build environment at meta-rdk-broadband/recipes-rdkb/usp-pa/conf.

If you are still having problems:

When performing a 'get' operation UspPa attempts to get all specified parameters using a single RDK bus message. This is more efficient than requesting each parameter individually, however it has the downside that if the 'get' of any single parameter fails, all fail (the RDK response message does not provide a partial response in this case). So if you try to get all parameters of an object using a a partial path, and get the CCSP_ERR_INVALID_PARAMETER_NAME error, you need to determine which one is causing the error. You can use the GET_GROUPED_PARAMETERS_INDIVIDUALLY and SET_GROUPED_PARAMETERS_INDIVIDUALLY defines in vendor_defs.h to change the behaviour of UspPa to request parameters individually, and determine which parameter is actually causing the problem. You can then omit this parameter from usp_dm_params.conf.

For problems with get use:

UspPa -c get "Device."

UspPa will print the value of all parameters. If it failed to get a parameter, then it will print an error message of the form:

ERROR: [error-code] retrieving [parameter-name] ([textual-error-message])

For problems with set, you can consult the logs (obtained with -p option enabled) to determine which parameter is causing problems, or use 'UspPa -c set', to try setting each parameter in turn.

WARNING: No instances in Device.LocalAgent.Controller

WARNING: No enabled MTPs in Device.LocalAgent.MTP. USP Agent may only be usable via the CLI

If you get these errors, it means that UspPa does not have a valid configuration database. To fix this, delete out /nvram/usp-pa.db, and ensure that the first invocation of UspPa after that includes the '-r' option specifying the factory reset database to apply (The system daemon invocation uses this option). If the first invocation of UspPa after deleting the database is 'UspPa -c', make sure that you include the '-r' option, otherwise you will end up with an empty database again.

Questions

Why doesn't 'dmcli eRT getv Device.LocalAgent.' work ?

dmcli is used to explore the data model provider components on the RDK bus.
UspPa does not currently export USP Specific configuration parameters to the RDK bus, they only exist in the USP Agent.

Why isn't Device.LocalAgent in usp_dm_objs.conf and usp_dm_params.conf ?

The usp_dm_objs.conf and usp_dm_params.conf files are used to define which RDK data model provider components are imported into the USP Agent.

Device.LocalAgent (and a number of other data model objects) exist only in the USP Agent and so do not need to be imported. If you want to remove any of these USP-Agent-only objects, this must be done at compile time using the defines in vendor_defs.h (Example: REMOVE_DEVICE_TIME).