Understanding TR-369 Set and Set Response Messages

SET Messages are used to request changes to specific settings or attributes of network devices. Each SET Message consists of the following components:

1. Header

• msg_id: A unique identifier for tracking and correlation with the response.
• msg_type: Specifies the message type as "SET," indicating a parameter modification request.

2. Body

• allow_partial: A flag indicating whether partial success is acceptable.
• update_objs: A collection of objects to be updated, defined by:
  • obj_path: The location of the parameter to be modified.
  • param_settings: A list of parameter-value pairs representing the new values to be applied.

Proto-Buffer Definition for SET Message

message Set {
  bool allow_partial = 1;
  repeated UpdateObject update_objs = 2;

  message UpdateObject {
    string obj_path = 1;
    repeated UpdateParamSetting param_settings = 2;
  }

  message UpdateParamSetting {
    string param = 1;
    string value = 2;
    bool required = 3;
  }
}

Example: SET Message

{
  "header": {
    "msg_id": "2023-05-15T22:37:12.695Z",
    "msg_type": "SET"
  },
  "body": {
    "request": {
      "set": {
        "allow_partial": true,
        "update_objs": [
          {
            "obj_path": "Device.LocalAgent.Controller.1.MTP.1.STOMP",
            "param_settings": [
              {
                "param": "Destination",
                "value": "I am a new value"
              }
            ]
          }
        ]
      }
    }
  }
}

In this example, the message requests an update to the Destination parameter at Device.LocalAgent.Controller.1.MTP.1.STOMP, setting it to "I am a new value."

USP SET Response Messages: Confirming Updates

Upon receiving a SET Message, the device processes the request and generates a SET Response Message (SetResp). This message confirms the outcome of the update request, detailing successes or failures.

Proto-Buffer Definition for SET Response Message

message SetResp {
  repeated UpdatedObjectResult updated_obj_results = 1;

  message UpdatedObjectResult {
    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;
        repeated UpdatedInstanceFailure updated_inst_failures = 3;
      }

      message OperationSuccess {
        repeated UpdatedInstanceResult updated_inst_results = 1;
      }
    }
  }

  message UpdatedInstanceFailure {
    string affected_path = 1;
    repeated ParameterError param_errs = 2;
  }

  message UpdatedInstanceResult {
    string affected_path = 1;
    repeated ParameterError param_errs = 2;
    map<string, string> updated_params = 3;
  }

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

Key Components of SET Response Messages

1. Updated Object Results:
   • requested_path: The path of the parameter being updated.
   • Operation Status: Indicates whether the operation succeeded or failed.
2. Success Results (oper_success):
   • updated_inst_results: Details of successfully updated instances, including the affected path and updated parameters.
3. Failure Results (oper_failure):
   • err_code and err_msg: Provide specific error details.
   • updated_inst_failures: Highlights the affected path and parameter-specific errors.

Example: SET Response Message (Success)

{
  "header": {
    "msg_id": "2023-05-15T22:37:12.695Z",
    "msg_type": "SET_RESP"
  },
  "body": {
    "response": {
      "set_resp": {
        "updated_obj_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.1.MTP.1.STOMP",
            "oper_status": {
              "oper_success": {
                "updated_inst_results": [
                  {
                    "affected_path": "Device.LocalAgent.Controller.1.MTP.1.STOMP.",
                    "updated_params": [
                      {
                        "key": "Destination",
                        "value": "I am a new value"
                      }
                    ]
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

In this response, the Destination parameter was successfully updated with the new value.

Example: SET Response Message (Error)

{
  "header": {
    "msg_id": "2023-05-15T23:28:31.457Z",
    "msg_type": "SET_RESP"
  },
  "body": {
    "response": {
      "set_resp": {
        "updated_obj_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.1.MTP.4",
            "oper_status": {
              "oper_failure": {
                "err_code": 7016,
                "err_msg": "CheckPathProperties: Object exists in schema, but instances are invalid: Device.LocalAgent.Controller.1.MTP.4"
              }
            }
          }
        ]
      }
    }
  }
}

This error response indicates that the update could not be completed due to invalid object instances, with specific details provided for troubleshooting.

Key Insights

1. SET Messages
   • Provide a structured way to request parameter modifications.
   • Support partial success for flexibility during bulk updates.
2. SET Response Messages
   • Confirm operation results, highlighting successes and failures.
   • Provide detailed error codes and messages for effective debugging.
3. Error Scenarios
   • Include comprehensive error handling to ensure clarity and resolution of update issues.

Conclusion

USP SET Messages and SET Response Messages form the backbone of device parameter management, enabling efficient configuration updates and customizations. By leveraging their robust structure and detailed feedback mechanisms, administrators can streamline device management and enhance network performance.

For developers and engineers, understanding the intricacies of these messages is critical to designing and managing scalable device ecosystems.

Explore additional USP documentation and resources 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