How do USP notifications and subscriptions work in TR-369?

A device-management platform is only as current as the last thing each device told it. In USP (TR-369), what an Agent reports, to which Controller and how insistently is set by Subscriptions, and the report itself travels as a Notify message. This guide walks through the mechanism as the specification defines it.

How does a Controller subscribe to notifications?

A Subscription “tells an Agent which Notifications to send to a particular Controller” (§1.4). USP has no Subscribe message among its eleven request types (§7.3.3.2). Subscriptions live in the data model instead, as instances of the Multi-Instance Object Device.LocalAgent.Subscription.{i}., and their normative rules are in that Object’s description in the Device:2 Data Model (§7.6.1, R-NOT.0). A Controller creates one with an ordinary Add message (§7.6.1.1).

The Parameters of a Subscription answer four questions:

• What to watch. ReferenceList holds the Path Names or Search Paths it applies to (§7.6.1.1). To hear when a station joins the Wi-Fi network, a Controller subscribes to ObjectCreation on Device.WiFi.AccessPoint.1.AssociatedDevice.. To hear when someone else changes the SSID, it subscribes to ValueChange on Device.WiFi.SSID.1.SSID (§7.6.1.1).
• What to do. TriggerAction makes the Agent send a Notify, the default, update its own configuration, or both (§7.6.1.2).
• How hard to try. NotifRetry and NotifExpiration decide whether delivery is confirmed and when retrying stops (§7.6.2).
• Who it is for. Each Subscription has an ID and a Recipient, an entry of the Agent’s Controller table, as in the specification’s search expression [ID=="boot-1"&&Recipient=="Device.LocalAgent.Controller.1"] (§7.5.1.1).

The Controller also needs permission. Role permissions are written as four characters, rwxn, where n stands for Notify (§8.9.2.1). Once an event occurs, implementations should change their state and start the Notification within a window no longer than 10 seconds (R-NOT.0a).

1. AddThe Controller subscribesA new row in Device.LocalAgent.Subscription. names the paths, the notification type and the Recipient.
2. EventThe condition is metA Parameter changes, an instance is added or removed, an operation completes, or an Event such as Boot! fires.
3. NotifyThe Agent reportsThe Notify carries the subscription_id and, when NotifRetry is true, send_resp set to true.
4. NotifyRespThe Controller confirmsIt echoes the subscription_id. Without an answer, the Agent retries until NotifExpiration.

Which notification types does USP define?

A Notify carries exactly one of six notification types (§7.6.4.2):

Every Notify also carries the subscription_id that the Controller set when it created the Subscription. For an OnBoardRequest, which has no Subscription, the field is an empty string (R-NOT.7).

What do Boot! and other events look like?

Events are defined in the data model and tied to Objects, and their names end with an exclamation point, as in Device.Boot! (§2.6.3). Boot! is also the specification’s example of an Event notification: its Notify names Device. as the object and Boot! as the event, with parameters such as Cause, CommandKey, ParameterMap and FirmwareUpdated (§7.6.4.1).

Events and OperationComplete often work together. When a Controller runs an asynchronous Command with Operate, the Agent creates a Request Object, removes it when the operation ends, and sends the result in an OperationComplete notification, with the command_key the Controller chose, to every Controller subscribed to it (§7.7.2). For a firmware switch, the specification recommends subscribing to a ValueChange on DeviceInfo.SoftwareVersion or to the Boot! event: an unchanged version, or a FirmwareUpdated value of false, can mean the device had trouble booting the target image (Appendix II.2.1). The full sequence is in firmware upgrades with USP.

What happens if the Controller does not answer?

Delivery is confirmed only when the Subscription asks for it. Each Notify has a send_resp flag. If the Subscription’s NotifRetry Parameter is true, the Agent sets send_resp to true and considers the notification delivered only when the Controller responds. If it is false, the Agent should ignore the delivery state (§7.6.2). When send_resp is false, the Controller should not respond at all (R-NOT.8), and when it does respond, it must echo the same subscription_id (R-NOT.10).

Without a response, the Agent retries on a fixed algorithm (R-NOT.1). Two Parameters of each entry in the Agent’s Controller table set the pace: USPNotifRetryMinimumWaitInterval, 5 seconds by default, and USPNotifRetryIntervalMultiplier, 2000 by default, which the formula divides by 1,000, so each range doubles:

From the tenth retry on, the range stays fixed (R-NOT.2), and the Agent keeps trying until the notification is delivered or the Subscription’s NotifExpiration time is reached (§7.6.2). The retry count goes back to zero after a successful delivery and after a reboot (R-NOT.3, R-NOT.4). A Controller with the right permissions can change both Parameters at any time (R-NOT.1).

OnBoardRequest is the one notification that never gives up. It must be sent with send_resp set to true and retried until the Controller confirms it with a Notify Response (R-NOT.6, R-NOT.6a), as if it belonged to a Subscription whose NotifExpiration is 0, which means it does not expire (§7.6.3.4).

How is this different from TR-069?

The biggest difference is who gets told. The specification includes a note for TR-069 readers: a CWMP device does not notify the ACS of value changes the ACS itself caused, because with a single ACS there is no need. In USP, an Agent follows each Subscription “regardless of the originator of that subscription” (§7.6.1), and a ValueChange is sent “even if it is caused by the originating Controller” (§7.6.3.1). With several Controllers on one Agent, each one gets the notifications of its own Subscriptions, whoever made the change.

There is one nuance. Some Events are defined per Controller, such as those of Device.BulkData. or Device.LocalAgent.Threshold., and go only to the Controller that configured their source, even if another Controller has a Subscription (§4.1.3.1, R-MTP.4e). For the full comparison between the two protocols, read TR-069 vs TR-369, and for the rest of USP, start with what is TR-369.