Videos

USP Records and USP Messages

Communications between a USP Controller and USP Agent are delivered using two separate constructs: the USP Message, and its container, the USP Record.

Both the USP Record and the USP Message are encoded in transit using “protocol buffers”. Protocol buffers is a standard developed by Google to allow protocol endpoints to easily understand the fields and values of messages transported between them using a clearly defined schema.

The USP Record

The schema for the USP Record is defined in the usp-record-1-1.proto file, which can be found with the USP specification. The USP Record is used to provide source and destination information about the message it contains, plus any session and security information if the optional end-to-end Session Context is used. The full details of how to use the USP Record and end-to-end session context can be found in the end-to-end message exchange section of USP.

A USP Record contains several elements.

  • version specifies which version of the USP protocol the endpoint is speaking.
  • to_id contains the Endpoint Identifier of the intended receiving endpoint. If this contains an Endpoint ID other than that of the receiving endpoint, the Record MUST be ignored.
  • from_id contains the Endpoint Identifier of the source USP Endpoint.
  • payload_security specifies how, if at all, the USP Message contained in the the record payload is secured. It can have a value of PLAINTEXT, meaning there is no application layer security on the payload, or TLS12, which means the payload is secured using TLS version 1.2 or later.
  • mac_signature and sender_cert are used when using a session context for end-to-end integrity protection of USP Records. 
  • record_type defines whether or not the USP Record is to be delivered within a Session Context. Record_type can have one of two values: no_session_context, or session_context.

When record_type is set to no_session_context, the last element in the USP Record is the payload, which contains a protobuf encoded USP Message.

About Session Context Session Context is an optional mechanism for USP. It allows two USP Endpoints to establish a protected, secure session with each other at the application layer. This is useful in situations were security cannot be guaranteed at the transport layer, or when USP messages need to cross intermediary systems like proxies or message brokers. We’ll cover session context in a separate training guide.

The USP Message

A USP Message itself is encoded using the usp-msg-1-1.proto file for its schema. Messages come in one of three types: Requests, Responses, and Errors. With the exception of the Notify message, Requests are sent from Controllers to Agents, who generate Responses or Errors after processing the message.

USP Messages contain a Header element and a Body element. The header contains two fields. The msg_id is used to coordinate Requests with Responses or Errors, and to handle duplicates. The msg_type contains an enumeration that explains what kind of message the body contains. Though required in the header, this field is meant for information only to assist controllers in more efficient processing.

The message type found in the message body should be treated as the correct type. The message Body contains the Request, Response, or Error. Responses occur when a message is processed and successfully acted upon, while Errors occur when the message was either not understood, or was not successfully acted upon. Due to the ability of some messages to allow for partial success, sometimes a Response will be sent even though some errors occurred during the operation.

There are nine types of Requests and Responses in USP.

  • Add - used for creating objects
  • Set - used for updating objects
  • Delete - used for removing objects
  • Get - used for reading an Agent’s instantiated data model
  • GetSupportedDM - used for for reading an Agent’s supported data model
  • GetInstances - used for reading the state of currently instantiated objects
  • Operate - used for invoking object specific commands on the Agent
  • Notify - used by the Agent to inform the Controller of events it has subscribed to
  • And GetSupportedProtocol, to handle version synchronization between Controller and Agent

 

Broadband Forum USP Agent Certification

Get your USP Agent certified now with the official Broadband Forum test platform.

Learn more