Understanding TR-369 Operate and Operate Response Messages

TR-369 USP Operate Messages and Operate Response Messages form the backbone of device control and enable seamless interaction between control systems and devices. By leveraging these standardized messages, administrators can trigger actions or execute commands on the device.

Commands in the TR-369 protocol are distinct from the typical CRUD-N operations of REST-based concepts. They can be either synchronous or asynchronous operations and are represented as specific Messages. When addressing a command, it is structured similarly to Parameter Paths but with parentheses "()" appended to indicate that it is a command.

For example, consider the command "Device.IP.Interface.[Name=="eth0"].Reset()" which signifies the action of resetting the interface named "eth0".

In this post, we will explore the concept of USP Operate Messages, understand their purpose, delve into their structure, and highlight their significance in device control.

Let's see the Operate message proto-buff definition from the official usp proto-buffer file:

message Operate {
  string command = 1;
  string command_key = 2;
  bool send_resp = 3;
  map<string, string> input_args = 4;
}

USP Operate Messages adhere to a well-defined structure, comprising the following key components:

Msg Id: A locally unique identifier assigned by the Endpoint/Controller that generated this Message.
Msg Type: Type of the Message, it should be OPERATE in this specific request
Command: Command Path of an Object.
Command Key: A string used as a reference by the Controller to match the operation
Send Response: Indicates whether or not Controller expects a response in association with the operation request.
Input Args: A map of key/value pairs indicating the input arguments (relative to the Command Path in the command field) to be passed to the method indicated in the command field

{
  "header": {
    "msg_id": "2023-03-24T05:41:52.473Z",
    "msg_type": "OPERATE"
  },
  "body": {
    "request": {
      "operate": {
        "command": "Device.LocalAgent.Controller.1.SendOnBoardRequest()",
        "command_key": "SendOnboardRequest Key01"
        "send_resp": true,
        "input_args": [
          {
            "key": "KEY, NOT REQUIRED FOR THIS COMMAND BUT AS AN EXAMPLE",
            "value": "IN THIS CASE NOT REQUIRED BUT AS A SAMPLE, IT IS HERE!"
          }
        ]
      }
    }
  }
}

When a CPE device receives an Operate Message, it interprets the commands and performs the requested actions synchronously or asynchronously. The device validates the access privileges and the integrity of the provided information before executing the requested operations. Upon completion, for the synchronous messages, the device generates an Operate Response Message to communicate the status, any changes made, and any relevant data back to the control system.

Let's see the OperateResp message proto-buff definition from the official usp proto-buffer file:

message OperateResp {
  repeated OperationResult operation_results = 1;

  message OperationResult {
    string executed_command = 1;
    oneof operation_resp {
      string req_obj_path = 2;
      OutputArgs req_output_args = 3;
      CommandFailure cmd_failure = 4;
    }

    message OutputArgs {
      map<string, string> output_args = 1;
    }

    message CommandFailure {
      fixed32 err_code = 1;
      string err_msg = 2;
    }
  }
}

The following fields are available for the Operate Message Response Logs:

Msg Id: A locally unique identifier assigned by the Endpoint/Controller that generated this Message.
Operate Resp: Operate command response

{
  "header": {
    "msg_id": "2023-03-24T05:41:52.473Z",
    "msg_type": "OPERATE_RESP"
  },
  "body": {
    "response": {
      "operate_resp": {
        "operation_results": [
          {
            "executed_command": "Device.LocalAgent.Controller.1.SendOnBoardRequest()",
            "cmd_failure": {}
          }
        ]
      }
    }
  }
}

In the TR-369 USP protocol, a synchronous operation refers to an operation that is designed to be completed immediately after processing. Once the operation is complete, the output arguments are included in the Operate response. However, if the "send_resp" flag is set to false, it indicates that the Controller doesn't require the returned information, if any. In such cases, the Agent doesn't send an Operate Response, as there is no need to provide the response to the Controller.

An asynchronous operation in the TR-369 USP protocol is designed to perform processing on the CPE, with the expectation of returning results at a later time. Once the operation is complete, the output arguments are sent to Controller that has an active subscription to the operation and the relevant Object(s) through a Notify (OperationComplete) request.

When a Controller initiates an asynchronous operation using the Operate request, the Agent creates a Request Object instance in its data model. The Operate response includes a reference to the created Request Object. However, if the "send_resp" flag is set to false, it indicates that the Controller doesn't require the details of the Request Object and intends to ignore it.