The Add Message in USP is used to create new instances of multi-instance objects in the Agent’s instantiated data model. This is used for a wide variety of service configurations such as creating new Wi-Fi networks. In USP, perhaps the most critical use of the Add message is with the Device.LocalAgent.Subscription. table, which lets a controller manage the notifications it wishes to receive from the Agent.
The protocol buffers definition of the Add Request, described in the usp-msg.proto file, is:
message Add {
bool allow_partial = 1;
repeated CreateObject create_objs = 2;
message CreateObject {
string obj_path = 1;
repeated CreateParamSetting param_settings = 2;
}
message CreateParamSetting {
string param = 1;
string value = 2;
bool required = 3;
}
}
The Add Request contains several fields.
allow_partial - This field is used in the Add, Delete, and Set messages to allow a controller to tell an Agent whether it’s okay to accept some changes, even if others given in the message fail to take effect.
create_objs - Next is a repeated number of elements of the CreateObject type. Each of these contains an obj_path specifying the object to be created, plus a second element (param_settings) containing a repeated set of parameters (param), and their values (value), that the Controller wishes to be set upon creation.
required - Each of the parameters in this list as a required field. If a required parameter fails to be configured upon object creation, the object itself must not be created by the agent, and is noted in the Add Response.
Here is an example Add Request.
header {
msg_id: "52867"
msg_type: ADD
}
body {
request {
add {
allow_partial: true
create_objs {
obj_path: "Device.WiFi.SSID."
param_settings {
{
param: "LowerLayers"
value: "Device.WiFi.Radio.1."
required: true
}
{
param: "SSID"
value: "NewSSIDName“
required: true
}
}
}
}
}
}
An Agent responds to an Add Request with either an Add Response, or an Error. Error messages occur when there is a general processing problem, or when allow_partial is set to false and one or more objects fail to be created.
The protocol buffers definition of the Add Response, described in the usp-msg.proto file, is:
message AddResp {
repeated CreatedObjectResult created_obj_results = 1;
message CreatedObjectResult {
string requested_path = 1;
OperationStatus oper_status = 2;
message OperationStatus {
oneof oper_status {
OperationFailure oper_failure = 1;
OperationSuccess oper_success = 2;
}
message OperationFailure {
fixed32 err_code = 1;
string err_msg = 2;
}
message OperationSuccess {
string instantiated_path = 1;
repeated ParameterError param_errs = 2;
map<string, string> unique_keys = 3;
}
}
}
The Add Response beings with a repeated set of elements of type CreatedObjectResults (created_obj_results). Each of these elements states which object path was requested (requested_path), and whether or not it succeeded or failed. If it failed, an oper_failure element is included, with an error message giving the reason for the failure. If it succeeded (oper_success), the Object’s Instance Identifier is returned (instantiated_path) along with a list of the instance’s unique keys (unique_keys). If any non-required parameters failed, these are noted in a set of ParameterError elements (param_errs).
Here’s an example of an Add Response to the above Request:
header {
msg_id: "52867"
msg_type: ADD_RESP
}
body {
response {
add_resp {
created_obj_results {
requested_path: "Device.WiFi.SSID."
oper_status {
oper_success {
instantiated_path: ""Device.WiFi.SSID.4."
{
unique_keys {
{
key: "BSSID"
value: "112233445566"}
{
key: "Name"
value: "GuestNetwork1"}
{
key: "Alias"
value: "cpe-alias-1"}
}
}
}
}
}
}
Get your USP Agent certified now with the official Broadband Forum test platform.
