Understanding TR-369 USP GET Messages

Unified Service Protocol (USP), defined in the Broadband Forum’s TR-369 standard, is a framework that allows devices (like routers, smart home hubs, or gateways) to communicate with controllers (such as cloud servers or management platforms).

One of the most useful parts of USP is how it lets you ask devices for information. This is done using GET messages. When a device responds, it sends back a Get Response (GET_RESP) message.

Let’s break down how this works — simply and clearly.

What Is a USP GET Message?

A GET message is like saying:
“Hey device, please tell me this specific information.”

It consists of two parts:

1. Header

The header includes:

• msg_id: A unique ID that helps match the request to its response.
• msg_type: Always set to "GET" for this kind of message.

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 what you’re asking for:

• param_paths: These are the paths of the values you want. Each path refers to a specific setting or piece of data on the device.
• max_depth: (Optional) Limits how deep in the hierarchy you want to go. A 0 means only get top-level info.

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

This message asks the device to return basic (top-level) details about two components: the CoAP and STOMP message transfer protocols.

he requester specifies two parameter paths (Device.LocalAgent.MTP.1.CoAP. and Device.LocalAgent.MTP.1.STOMP.) and requests top-level details (max_depth: 0).

What Happens Next? The Device Sends a Get Response (GET_RESP)

After the device receives the GET request, it looks up the requested values and sends back a GET_RESP message.

Get Response – Structure

Just like the GET message, the response has a header and a body:

Header

• Same msg_id as the request.
• msg_type is "GET_RESP".

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.

Technical Notes and Tips

• Be specific with parameter paths. If the path doesn’t exist or isn’t accessible, the response will include an error.
• Use max_depth carefully. A higher depth means more data and larger messages.
• Resolved vs Requested Paths: The device might respond with a slightly different path due to internal naming or aliasing.
• Errors are detailed. You’ll get error codes and messages that help identify what went wrong.

When to Use GET and GET_RESP

Here are some practical use cases:

• Configuration Checks: See if encryption is enabled or what port a protocol uses.
• Monitoring: Check a device’s uptime or firmware version.
• Debugging: Narrow down config issues with focused queries.

How USP Makes This Work (TR-369 Background)

TR-369's Unified Service Data Model (TR-181) allows all these paths (like Device.LocalAgent.MTP.1.CoAP.) to follow a universal naming structure across vendors. This standardization is one of the biggest advantages of using USP — your code works the same whether you're querying a smart gateway or a CPE device from a different vendor.

The protocol also supports multi-controller environments, meaning several management systems can interact with the same device securely and in parallel — a huge step forward compared to older TR-069 setups.

Final Thoughts

USP GET and GET_RESP messages are straightforward but powerful. They let you fetch exactly the data you need from a device, in a structured, predictable format.

If you're building or managing a TR-369-based system, understanding these two message types is one of the first and most important steps.

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