Understanding TR-369 Notify and Notify Response Messages

Notify Messages and Notify Response Messages have a crucial role in the communication between TR-369 USP Endpoints and USP Controllers. They enable the Agent to notify the Controller about specific events, changes, or operations. The Controller, in turn, acknowledges the receipt of these notifications through Notify Response Messages, ensuring a robust and reliable communication system.

The Subscription mechanism in the TR-369 (USP) specification allows a Controller to establish a subscription to specific events occurring on the Agent. Once the subscription is set up, the Agent actively monitors the specified events. When the specified event conditions are met, the Agent generates a Notify Message containing the relevant event information and sends it to the subscribed Controller. This Notify Message serves as a real-time notification, informing the Controller about the occurrence of the subscribed event.

By utilizing the Subscription mechanism, a Controller can specify the event conditions it wants to monitor, such as a Parameter change, Object removal, wake-up event, or any other event defined in the USP data models. The Controller configures the subscription by providing the necessary criteria, such as the target Object, the event type, and any additional filtering parameters.

In this post, we will explore TR-369 USP Notify Messages and their corresponding Notify Response  Messages, shedding light on their role in carrying notifications or informing USP Controllers about an imported event in a CPE device.

Notify Request Messages:
The Notify Message includes details about the event, such as the event type, the affected Object or Parameter, and any relevant data associated with the event. Upon receiving the Notify Message, the Controller can take appropriate actions based on the event information, such as initiating further operations, updating its internal state, or triggering automated responses.

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

message Notify {
  string subscription_id = 1;
  bool send_resp = 2;
  oneof notification {
    Event event = 3;
    ValueChange value_change = 4;
    ObjectCreation obj_creation = 5;
    ObjectDeletion obj_deletion = 6;
    OperationComplete oper_complete = 7;
    OnBoardRequest on_board_req = 8;
  }

  message Event {
    string obj_path = 1;
    string event_name = 2;
    map<string, string> params = 3;
  }

  message ValueChange {
    string param_path = 1;
    string param_value = 2;
  }

  message ObjectCreation {
    string obj_path = 1;
    map<string, string> unique_keys = 2;
  }

  message ObjectDeletion {
    string obj_path = 1;
  }

  message OperationComplete {
    string obj_path = 1;
    string command_name = 2;
    string command_key = 3;
    oneof operation_resp {
      OutputArgs req_output_args = 4;
      CommandFailure cmd_failure = 5;
    }

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

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

  message OnBoardRequest {
    string oui = 1;
    string product_class = 2;
    string serial_number = 3;
    string agent_supported_protocol_versions = 4;
  }
}

The Notify request plays a significant role in the User Services Platform (USP) specification by enabling the transmission of generic "Event" messages. These events allow a USP Agent to emit notifications related to Objects defined in the USP data models. Much like commands, events are associated with specific Objects and are addressed using Parameter Paths. However, events are distinguished by appending an exclamation point "!" at the end of the Parameter Path to signify their nature as an event.

To illustrate this concept, let's consider an example event: Device. Boot!

{
  "header": {
    "msg_id": "Event-2023-05-29T21:34:30Z-1",
    "msg_type": "NOTIFY"
  },
  "body": {
    "request": {
      "notify": {
        "subscription_id": "default-boot-event-ACS",
        "event": {
          "obj_path": "Device.",
          "event_name": "Boot!",
          "params": [
            {
              "key": "Cause",
              "value": "LocalFactoryReset"
            },
            {
              "key": "CommandKey",
              "value": ""
            },
            {
              "key": "FirmwareUpdated",
              "value": "false"
            },
            {
              "key": "ParameterMap",
              "value": "{\"Device.LocalAgent.EndpointID\":\"proto::rx_usp_agent_mqtt\"}"
            }
          ]
        }
      }
    }
  }
}

In this case, the event is associated with the "Device" Object. The "Boot" portion of the event signifies a specific type of event related to the boot process of the device. By emitting this event, the USP Agent notifies interested parties, the USP Controller,  about the occurrence of a device boot event.

To illustrate this concept better, let's consider a different example (a value change): Device.DeviceInfo.FriendlyName

{
  "header": {
    "msg_id": "IAmAnExampleModifiedFromTR369Spec",
    "msg_type": "NOTIFY"
  },
  "body": {
    "request": {
      "notify": {
        "subscription_id": "default-boot-event-ACS",
        "send_resp": true,
        "value_change": {
          "param_path": "Device.DeviceInfo.FriendlyName",
          "param_value": "A value"
        }
      }
    }
  }
}

The Notify request in the TR-369 User Services Platform (USP) includes a flag called send_resp, which determines whether the Controller should send a Notify Response Message upon receiving the Notify request. This flag works in conjunction with the NotifRetry Parameter in the subscription Object.

When the NotifRetry flag is set to true, indicating that retrying is enabled, the Agent sends its Notify requests with send_resp set to true. In this case, the Agent expects to receive a response from the Controller to confirm the delivery of the notification. The Agent considers the notification delivered only when it receives a response from the Controller.

On the other hand, if the NotifRetry flag is set to false, the Agent does not require the use of the send_resp flag, and it doesn't consider the delivery state of the notification. In this scenario, the Agent does not expect a response from the Controller and should ignore the delivery status.

However, if the NotifRetry flag is set to true and the Agent doesn't receive a response from the Controller, it initiates a retry process based on a predefined algorithm. The details of the retry algorithm may vary depending on the implementation. The subscription Object also includes a NotifExpiration Parameter, which specifies the duration until the retry process should end if no successful delivery is achieved within that time frame.

Notify Response Messages:

In the Notify Response, there is a field called subscription_id, which contains the Subscription ID that was received with the Notify Request.

According to the latest version of the specification (TR-369 ver:1.2), the Agent should ignore the subscription_id field (R-NOT.9). This means that the Agent is not required to process or validate the subscription_id field in the Notify Response.

However, for backward compatibility with previous versions of the specification, the Controller is still required to include the matching subscription_id in the Notify Response (R-NOT.10). The Controller must populate the subscription_id field with the same Subscription ID that was presented in the Notify Request.

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

message NotifyResp {
  string subscription_id = 1;
}

Here is an example message for a NotifyResp type:

{
  "header": {
    "msg_id": "OnBoardRequest-2023-03-24T05:03:30Z-1",
    "msg_type": "NOTIFY_RESP"
  },
  "body": {
    "response": {
      "notify_resp": {"subscription_id": "boot-1"}
    }
  }
}

The Notify request, in conjunction with events, enables efficient event-driven communication and facilitates real-time updates within the USP ecosystem. Interested parties can subscribe to specific events of their interest, allowing them to stay informed about critical occurrences and take appropriate actions based on received event notifications.

1. Broadband Forum, "User Services Platform (USP)", TR-369 Issue 1 Amendment 2, January 2022, p. 125-132. https://www.broadband-forum.org/tr-369
2. USP Record Definitions, GitHub Repository, https://github.com/BroadbandForum/usp