Understanding TR-369 USP GET Messages

Unified Service Protocol (USP), defined by the TR-369 standard, offers a reliable and structured method for communication and information exchange between network management systems and connected devices. Among its core functionalities, GET Messages and their corresponding Get Response Messages enable precise and efficient data retrieval from devices.

USP GET Messages: Structure and Function

USP GET Messages serve as requests to retrieve specific data points from devices. These messages have two main components:

1. Header

The header contains:

• msg_id: A unique identifier for the message, enabling correlation between requests and responses.
• msg_type: Set to "GET" to denote a data retrieval operation.

Let's see the Get Message proto-buff definition from the official usp proto-buffer file:

message Get {
  repeated string param_paths = 1;
  fixed32 max_depth = 2;
}

2. Body

The body defines the payload of the GET request and includes:

• param_paths: A list of parameter paths specifying the data points to retrieve.
• max_depth (optional): Specifies the hierarchical depth of data to retrieve.

Example: USP GET Request Message

{
  "header": {
    "msg_id": "Group_2023-04-22T01:24:39.763Z-3e93a748-db18-4c8e-9ea8-f917bec6014c",
    "msg_type": "GET"
  },
  "body": {
    "request": {
      "get": {
        "param_paths": [
          "Device.LocalAgent.MTP.1.CoAP.",
          "Device.LocalAgent.MTP.1.STOMP."
        ]
        "max_depth": 0
      }
    }
  }
}

In this example, the requester specifies two parameter paths (Device.LocalAgent.MTP.1.CoAP. and Device.LocalAgent.MTP.1.STOMP.) and requests top-level details (max_depth: 0).

USP Get Response Messages: Delivering Requested Data

After receiving a GET request, the device processes it and returns a Get Response Message (GetResp). This response contains the requested data or error details if the operation fails.

Components of a Get Response Message

1. Header
   • Mirrors the original request’s msg_id to ensure proper tracking.
   • Specifies the message type as "GET_RESP".
2. Body
   • Contains the GetResp payload, which includes:
     • Requested Path Results: A collection of results for each requested parameter path.
     • Resolved Path Results: Actual data retrieved, which may include mappings or aliases.
     • Result Parameters: Key-value pairs representing the retrieved parameter values.

USP Get Response Message Structure

Once a device receives a GET message, it proceeds to process the request and generate a Get Response (GetResp) message in response.

Let's see the GetResp Message proto-buff definition from the official usp proto-buffer file:

message GetResp {
  repeated RequestedPathResult req_path_results = 1;

  message RequestedPathResult {
    string requested_path = 1;
    fixed32 err_code = 2;
    string err_msg = 3;
    repeated ResolvedPathResult resolved_path_results = 4;
  }

  message ResolvedPathResult {
    string resolved_path = 1;
    map<string, string> result_params = 2;
  }
}

The GetResp message encapsulates valuable information pertinent to the request made. It consists of a collection of RequestedPathResults, each of which represents the outcome of a particular requested parameter path.

Example: USP Get Response Message

{
  "header": {
    "msg_id": "Group_2023-04-22T01:24:39.763Z-3e93a748-db18-4c8e-9ea8-f917bec6014c",
    "msg_type": "GET_RESP"
  },
  "body": {
    "response": {
      "get_resp": {
        "req_path_results": [
          {
            "requested_path": "Device.LocalAgent.MTP.1.CoAP.",
            "resolved_path_results": [
              {
                "resolved_path": "Device.LocalAgent.MTP.1.CoAP.",
                "result_params": [
                  {
                    "key": "Port",
                    "value": "5683"
                  },
                  {
                    "key": "Path",
                    "value": ""
                  },
                  {
                    "key": "EnableEncryption",
                    "value": "true"
                  }
                ]
              }
            ]
          },
          {
            "requested_path": "Device.LocalAgent.MTP.1.STOMP.",
            "resolved_path_results": [
              {
                "resolved_path": "Device.LocalAgent.MTP.1.STOMP.",
                "result_params": [
                  {
                    "key": "Reference",
                    "value": ""
                  },
                  {
                    "key": "Destination",
                    "value": ""
                  },
                  {
                    "key": "DestinationFromServer",
                    "value": ""
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

In this response, the requested paths (Device.LocalAgent.MTP.1.CoAP. and Device.LocalAgent.MTP.1.STOMP.) are resolved, and their corresponding parameters (e.g., Port, EnableEncryption) are returned as key-value pairs under result_params.

Key Technical Considerations

GET Messages

• Parameter Paths: Accurately specifying parameter paths ensures targeted and efficient data retrieval.
• Max Depth: Use max_depth judiciously to control the granularity of the returned data and avoid unnecessary payload size.

Get Response Messages

• Resolved Paths: Devices may return resolved paths that differ from the requested paths due to internal mappings or aliases.
• Error Reporting: Includes comprehensive error codes and messages for diagnosing issues.
• Result Parameters: Delivered as key-value pairs, allowing structured access to device information.

Use Cases for GET and Get Response Messages

1. Device Configuration Audit
   Retrieve specific configuration settings, such as encryption status or port assignments.
2. Monitoring Device Performance
   Query operational metrics, such as uptime or software version.
3. Troubleshooting
   Pinpoint and resolve configuration inconsistencies or errors using targeted parameter paths and detailed error messages.

Conclusion

USP GET Messages and Get Response Messages provide an efficient mechanism for retrieving structured device data in TR-369-compliant systems. By enabling precise queries and delivering detailed responses, they streamline device management processes and improve overall network operability.

For engineers and developers, understanding the structure and flow of these messages is essential to designing robust, scalable management systems that can handle the complexities of modern networks.

Stay tuned for future posts diving deeper into other USP message types and advanced use cases in device management.

Explore more technical documentation at TR369.org.

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