Understanding TR-369 USP Add Messages: Adding New Elements to Network Devices

In device management, the Unified Service Protocol (USP) has streamlined the process of managing network devices, offering a standardized framework for seamless communication and information exchange. Among its core functionalities, Add Messages and their corresponding Add Response Messages play a critical role in enabling the creation of new elements or objects within a device’s ecosystem.

This post dives into the technical details of these messages, focusing on their structure, usage, and how they facilitate device expansion.

Add Request Messages

Add Messages are used in USP to request the addition of new elements or objects to a device. These messages comprise two essential components:

1. Header

• msg_id: A unique identifier for the message, ensuring traceability and correlation with the response.
• msg_type: Specifies the message type as "ADD," indicating a request to add new entities.

2. Body

• allow_partial: A flag indicating whether partial success is acceptable.
• create_objs: A list of objects to be created, each defined by:
  • obj_path: The target location where the new element will be added.
  • param_settings: A map of parameters and their initial values for the new object.

Add Message Proto-Buffer Definition

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;
  }
}

Example: Add Request Message

{
  "header": {
    "msg_id": "2023-05-05T23:26:05.274Z",
    "msg_type": "ADD"
  },
  "body": {
    "request": {
      "add": {
        "allow_partial": true,
        "create_objs": [
          {
            "obj_path": "Device.LocalAgent.Controller.",
            "param_settings": [
              {
                "param": "Enable",
                "value": "true"
              },
              {
                "param": "EndpointID",
                "value": "controller-temp04"
              }
            ]
          }
        ]
      }
    }
  }
}

This example demonstrates a request to add a new controller instance under the path Device.LocalAgent.Controller., initializing it with parameters like Enable set to true and an EndpointID.

Add Response Messages

Once a device processes an Add Request, it responds with an Add Response Message (AddResp). This message provides confirmation, details about the newly added object, or feedback in case of partial or complete failure.

Add Response Proto-Buffer Definition

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;
      }
    }
  }

  message ParameterError {
    string param = 1;
    fixed32 err_code = 2;
    string err_msg = 3;
  }
}

Components of Add Response Messages

1. Header
   • Mirrors the original request’s msg_id for correlation.
   • Specifies msg_type as "ADD_RESP."
2. Body
   • Contains a list of Created Object Results, each detailing the outcome of a specific requested addition:
     • requested_path: The target path of the addition request.
     • Operation Status: Indicates success or failure, including error codes and messages if applicable.
     • instantiated_path: The actual path of the newly created object, accounting for aliases or mappings.

Example: Add Response Message

Successful Case

{
  "header": {
    "msg_id": "2023-05-05T23:26:05.274Z",
    "msg_type": "ADD_RESP"
  },
  "body": {
    "response": {
      "add_resp": {
        "created_obj_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.",
            "oper_status": {
              "oper_success": {
                "instantiated_path": "Device.LocalAgent.Controller.3.",
                "unique_keys": [
                  {
                    "key": "Alias",
                    "value": "cpe-3"
                  },
                  {
                    "key": "EndpointID",
                    "value": "controller-temp04"
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

In this response, the newly added object’s actual path is returned (Device.LocalAgent.Controller.3.), along with unique identifiers.

Error Case
If the addition fails, the response includes error details:

{
  "header": {
    "msg_id": "2023-05-10T22:40:07.702Z",
    "msg_type": "ADD_RESP"
  },
  "body": {
    "response": {
      "add_resp": {
        "created_obj_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.",
            "oper_status": {
              "oper_failure": {
                "err_code": 7005,
                "err_msg": "FindUnusedController: Only 5 controllers are supported."
              }
            }
          }
        ]
      }
    }
  }
}

This error response indicates that the system supports only five controllers, and the attempt to add a sixth failed.

Key Takeaways

1. Add Messages
   • Facilitate the creation of new elements in a device’s ecosystem.
   • Include clear paths and initial parameter settings for precise execution.
2. Add Response Messages
   • Confirm the outcome of addition requests, including success, failure, or partial completion.
   • Provide detailed feedback for troubleshooting, including instantiated paths and error specifics.
3. Error Scenarios
   • Handle limitations or conflicts gracefully with comprehensive error reporting.

Conclusion

USP Add Messages and Add Response Messages are integral to expanding and managing device ecosystems. They offer a reliable method for adding new elements while providing detailed feedback to ensure smooth integration.

For engineers and developers, understanding the structure and flow of these messages is essential for designing scalable and robust device management systems.

Stay tuned for more deep dives into USP messaging and TR-369 implementations.

Explore technical documentation and resources at TR369.org.

4o

References:

1. TR-369 USP Specification, Broadband Forum, https://www.broadband-forum.org/tr-369
2. USP Record Definitions, GitHub Repository, https://github.com/BroadbandForum/usp