TR-369 – The User Services Platform

Issue: 1 Amendment 4

Issue Date: July 2024

Cover Page

  1. USP Agent and Controller Architecture
  2. Receiving a X.509 Certificate
  3. Example: USP Request/Response over the CoAP MTP
  4. WebSocket Session Handshake
  5. USP Request using a WebSocket Session
  6. USP over STOMP Architecture
  7. USP over MQTT Architecture
  8. MQTT Packets
  9. Unix Domain Socket Binding
  10. UNIX Domain Socket Frame with Handshake Message
  11. UNIX Domain Socket Frame with USP Record Message
  12. Processing of Received USP Records
  13. E2E Segmentation and Reassembly
  14. TLS Session Handshake
  15. A successful request/response sequence
  16. A failed request/response sequence
  17. Operate Message Flow for Synchronous Operations
  18. Operate Message Flow for Asynchronous Operations
  19. Receiving a USP Record
  20. USP Record without USP Layer Secure Message Exchange
  21. Sending a USP Record
  22. Checking a Certificate
  23. Determining the Role
  24. Trusted Broker with Received Record
  25. Trusted Broker Sending a Record
  26. Deployment Unit State Diagram
  27. Execution Unit State Diagram
  28. Possible Multi-Execution Environment Implementation
  29. Execution Environment State Diagram
  30. Example of MTP Proxy in LAN with WAN Controller
  31. CoAP-STOMP MTP Proxy Example Flow
  32. IoT Data Model
  33. IoT individual device models
  34. IoT proxied device model
  35. IoT threshold trigger sensitivity
  36. IoT threshold trigger hold time
  37. IoT threshold trigger rest time
  38. IoT threshold trigger minimum duration
  39. Software Modularization Use Cases
  1. Proxy Building Block Functions
  2. Possible MTP Proxy Methods

The Broadband Forum is a non-profit corporation organized to create guidelines for broadband network system development and deployment. This Technical Report has been approved by members of the Forum. This Technical Report is subject to change. This Technical Report is owned and copyrighted by the Broadband Forum, and all rights are reserved. Portions of this Technical Report may be owned and/or copyrighted by Broadband Forum members.

Recipients of this Technical Report are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of this Technical Report, or use of any software code normatively referenced in this Technical Report, and to provide supporting documentation.

1. License

Broadband Forum hereby grants you the right, without charge, on a perpetual, non-exclusive and worldwide basis, to utilize the Technical Report for the purpose of developing, making, having made, using, marketing, importing, offering to sell or license, and selling or licensing, and to otherwise distribute, products complying with the Technical Report, in all cases subject to the conditions set forth in this notice and any relevant patent and other intellectual property rights of third parties (which may include members of Broadband Forum). This license grant does not include the right to sublicense, modify or create derivative works based upon the Technical Report except to the extent this Technical Report includes text implementable in computer code, in which case your right under this License to create and modify derivative works is limited to modifying and creating derivative works of such code. For the avoidance of doubt, except as qualified by the preceding sentence, products implementing this Technical Report are not deemed to be derivative works of the Technical Report.

2. NO WARRANTIES

THIS TECHNICAL REPORT IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT AND ANY IMPLIED WARRANTIES ARE EXPRESSLY DISCLAIMED. ANY USE OF THIS TECHNICAL REPORT SHALL BE MADE ENTIRELY AT THE USER’S OR IMPLEMENTER’S OWN RISK, AND NEITHER THE BROADBAND FORUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY USER, IMPLEMENTER, OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS TECHNICAL REPORT, INCLUDING BUT NOT LIMITED TO, ANY CONSEQUENTIAL, SPECIAL, PUNITIVE, INCIDENTAL, AND INDIRECT DAMAGES.

3. THIRD PARTY RIGHTS

Without limiting the generality of Section 2 above, BROADBAND FORUM ASSUMES NO RESPONSIBILITY TO COMPILE, CONFIRM, UPDATE OR MAKE PUBLIC ANY THIRD PARTY ASSERTIONS OF PATENT OR OTHER INTELLECTUAL PROPERTY RIGHTS THAT MIGHT NOW OR IN THE FUTURE BE INFRINGED BY AN IMPLEMENTATION OF THE TECHNICAL REPORT IN ITS CURRENT, OR IN ANY FUTURE FORM. IF ANY SUCH RIGHTS ARE DESCRIBED ON THE TECHNICAL REPORT, BROADBAND FORUM TAKES NO POSITION AS TO THE VALIDITY OR INVALIDITY OF SUCH ASSERTIONS, OR THAT ALL SUCH ASSERTIONS THAT HAVE OR MAY BE MADE ARE SO LISTED.

All copies of this Technical Report (or any portion hereof) must include the notices, legends, and other provisions set forth on this page.

Issue Number Approval Date Changes

Release 1.0

April 2018

Release contains specification for the User Services Platform 1.0

Corresponds to TR-181 Issue 2 Amendment 12

Release 1.0.1 August 2018
  • Added examples and clarifications to end-to-end messaging, use of endpoint ID, typographical fixes
Release 1.0.2 November 2018
  • Typographical and example fixes

Release 1.1

October 2019

Release contains specification for the User Services Platform 1.1

  • Adds MQTT support as a Message Transfer Protocol
  • Adds a theory of operations for IoT control using USP Agents
  • Clarifications on protocol functions, error messages, and updates to examples

Corresponds to TR-181 Issue 2 Amendment 13

Release 1.1.1 April 2020 Regenerated data model HTML using fixed version of the BBF report tool
Release 1.1.2 August 2020 Clarifies several examples, requirements, and error types
Release 1.1.3 November 2020 Corresponds to TR-106 Amendment 10 and TR-181 Issue 2 Amendment 14
Release 1.1.4 November 2020 Corresponds to TR-181 Issue 2 Amendment 14 Corrigendum 1

Release 1.2

January 2022

Release contains specification for the User Services Platform 1.2

  • Clarify the expected responses in result of an Operate message (R-OPR.4)
  • Deprecates the use of COAP as an MTP
  • GetSupportedDM
    • now provides the data types for parameter values
    • now allows the Agent to provide information about whether or not it will ignore ValueChange subscriptions on a given parameter
    • now provides information about whether a command is synchronous vs. asynchronous
    • now allows requests on specific object instances and handles divergent data models
  • Defines discovery mechanisms for Endpoints connected to STOMP and MQTT brokers
  • Clarifies the use of search paths vs. unique key addressing in the Add message
  • Clarifies the use of required parameters and defaults for unique keys in the Add message
  • Annex A
    • now provides a theory of operations for use of the USPEventNotif mechanism for bulk data collection using the Push! event
    • defines a new bulk data collection over MQTT mechanism
  • DHCP discovery mechanism now provides a Controller Endpoint ID to the Agent
  • Enhances ease of use and clarifies requirements for use of TLS in USP Record integrity
  • New USP records
    • adds USP connect and disconnect records for use independent of MTP
    • adds USP Record specific error mechanism and error codes
    • MQTT and STOMP no longer silently drop errors; they now report errors in the USP Record.
    • USP Records can now include an empty payload
  • Get requests
    • can now include a max_depth flag to limit response size
    • Get response format has been clarified to return separate elements for sub-object
  • Clarifies the requirements around processing an entire message in the event of a failed operation when allow_partial is true vs. false
  • Clarifies the response behavior for Get, Set, and Delete when using a path that matches no instances
  • Fixes and enhances the use of error codes for the Operate message
  • Clarifies and updates Controller credential/authentication theory of operations and flow diagrams
  • Clarifies the use of subjectAltName in certificates
  • Clarifies R-E2E.4
  • Deprecated and Obsolete terms are now defined in the References and Terminology section
  • Updated R-E3E.43
  • Deprecates R-MSG.2
  • Deprecates R-E2E.2
  • R-E2E.42 now makes TLS renegotiation forbidden
  • Modifies R-NOT.9 and adds R-NOT.10 adjusting how the Agent and Controller should handle the subscription_id field

Corresponds to TR-106 Amendment 11 and TR-181 Issue 2 Amendment 15

Release 1.3

June 2023

Release contains the specification for the User Services Platform 1.3

  • Adds Appendix VI, “Software Modularization and USP-Enabled Applications Theory of Operation”
  • Adds new Unix Domain Socket MTP
  • Adds two new messages, “Register” and “Deregister”, and associated error codes (primarily for use with Appendix VI but can be used in many scenarios)
  • Adds new Software Module Management features
  • Adds a note about the use of the new TriggerAction parameter in Subscription objects
  • Updates “Authentication and Authorization” to include the use of new SecuredRole
  • Updates the Add message to allow for Search Paths and clarifies the application of permissions during Add messages
  • Obsoletes CoAP as an MTP
  • Adds two new requirements regarding Unique Key immutability
  • Clarifies how Set should respond when using a Search Path where one or more objects fail to update
  • Updates the use of EndpointID in WebSocket arguments and adds an fqdn authority scheme
  • Addesses a potential attack vector with using MQTT, and updates other MQTT behavior
  • Updates Annex A to explain use of the “Exclude” parameter
  • Updates Discovery to include the use of DHCP options for agent-device association
  • Adds a note about USP protocol versioning and Controller/Agent behavior
  • Clarifies and updates the use of certain error codes
  • Clarifies the behavior of Get messages when asking for specific Multi-Instance Objects that don’t exist
  • Clarifies some behavior when responding via USP Records
  • Updates message flow diagrams to remove the implication of ordered responses
  • Adds new requirement R-SEC.4b for Trusted Brokers
Release 1.3.1 October 2023 This Corrigendum has the following fixes
  • Fix example by populating the empty UNIX Domain Socket references
  • Small fixes to UDS example images
  • Fix UnixDomainSocket path in example

Release 1.4

July 2024

Release contains the specification for the User Services Platform 1.4

  • Updated ResolvedPathResult Fields to clarify that R-GET.4 does not return parameters for which the Controller does not have Read permission for.
  • Added Appendix VI Usage of the Register Operation to define the Rules related to USP Services Registering data model paths.
  • Added TLS Support to the UDS MTP impacting Section Handling Failures to Deliver USP Records with new requirements (R-UDS.23a and R-UDS.23b) and updates to Appendix V1 Basic Solution Concepts.
  • Expanded Error Codes Section Applicability to multiple error codes from Error Message to Any, to send an operate response rather than USP error.
  • Updated GetSupportedDM Request Fields Section to expand the Register Message for Commands, Events, and Parameters. Updated Definitions Section with new definitions for Command Path and Event Path.
  • Updated R-OPR.4 and R-OPR.5 to align with R-OPR.1.
  • Updated Appendix 1 Basic Solution Concepts Section to define that the Execution Environment is no longer static, and is managed via USP Software Module Management.
  • Updated Handling of WebSocket Frames Section adding R-WS.14b to discourage the use of WebSocket fragmentation.
  • Updated Handling of the WebSocket Session Section adding note to R-WS.8 to clarify the encoding of USP Endpoint ID for URI use.
  • Opened up the OUI definition and Use of authorityscheme and authorityid Section R-ARC.2a to allow for not only the old 24-bit OUIs but to also allow for 36-bit OUIs.
  • Updated OnBoardRequest Section to state that the OnBoardRequest notification MUST be sent with send_resp=true, which included updates to R-NOT.5 and R-NOT-6 as well as the addition of R-NOT-6a to insure the Controller retries until a notification response is recieved.
  • Defined the term “Partial Path” in Definitions Section.
  • Fixed the Operate example in Operate Examples Section to include both sync and async data model commands.
  • Updated the GetSupportedDM to now indicate the unique keys of a table, which caused updates to the examples in GetSupportedDM Examples Section and the usp-msg-1-4.proto file within the GetSupportedDM message.
  • Updated Role Definition Section with clarifications to Role permissions applying to Supported and Instantiated Data model and the Secured Role as applying to “secured” parameter in the path(s), with examples of both.

Comments or questions about this Broadband Forum Technical Report should be directed to .