USP Agent vs Controller: what is the difference, and what is an Endpoint ID?

Every USP exchange has two ends, and TR-369 gives each one a fixed job. Whether you run a NOC or build the platform behind it, you will meet both roles, Agent and Controller, and the identifier that names each of them, the Endpoint ID, in USP Records, WebSocket handshakes and certificates. This guide explains both, using only what the specification says.

What is the difference between a USP Agent and a Controller?

In USP, anything that sends or receives a Message is an Endpoint, “a termination point for a Message” (§1.4), and every Endpoint acts as one of two roles (§2.1):

• An Agent “is an Endpoint that exposes Service Elements to one or more Controllers” (§1.4). Service Elements are the Objects, Sub-Objects, Commands, Events and Parameters that make up a piece of functionality (§2.3).
• A Controller “is an Endpoint that manipulates Service Elements through one or more Agents” (§1.4). It usually acts as the interface to a user application or a policy engine (§2.1.2).

The direction is fixed: “Controllers only send messages to Agents, and Agents send messages to Controllers” (§2.1).

If you come from TR-069, the specification draws the parallel itself: it calls the Auto-Configuration Server “the CWMP equivalent of a Controller” (§7.6.1). The difference is the “one or more”. A Controller and an Agent have a USP Relationship when they can exchange messages, which usually means the Controller has been added to the Agent’s Controller table (§1.4), and that table can hold more than one Controller.

What does each side hold and need to know?

The two roles keep different things and need different facts about each other:

The two data models answer different questions on a support call. The Instantiated Data Model holds the Service Elements the Agent represents right now, with their state (§2.4.1). The Supported Data Model holds what the Agent understands (§2.4.2), and GetSupportedDM lets a Controller learn “what an Agent understands, rather than its current state” (§7.5.3).

A Controller acquires the Agent’s Endpoint ID, MTP details and credentials when the Agent first connects (§3.2). How the Agent finds its Controller in the first place is covered in how a USP Agent finds its Controller.

How is a USP Endpoint ID built?

Every Endpoint is named by an Endpoint Identifier, a USP-layer identifier that is unique, locally or globally depending on the scheme used to assign it (§2.2). It has three parts:

authority-scheme ":" [authority-id] ":" instance-id

• The authority-scheme says which kind of authority assigns the ID, and it dictates the format of the authority-id (§2.2).
• The authority-id identifies that authority. Some schemes require it to be empty, which is why IDs such as os::00256D-0123456789 contain a double colon (§2.2.1).
• The instance-id names the Endpoint itself. It may use only letters, digits, -, ., _ and percent-encoded characters (R-ARC.5), and it may be no more than 50 characters long (R-ARC.6). Shorter is better, “as end users could be exposed to Endpoint IDs” (§2.2.2).

In a certificate the ID is written as a URN in the Broadband Forum namespace, urn:bbf:usp:id: followed by the same three parts. Everywhere else, for example in the to_id and from_id fields of a USP Record, the namespace is left out (§2.2).

Which authority schemes can an Endpoint ID use?

The specification defines twelve schemes (§2.2.1), and requirement R-ARC.2a makes their rules mandatory:

The scheme also decides who answers for uniqueness: the owner of the OUI, CID, enterprise number or domain name (including the OUI inside os and ops), the assigning user or machine for user, and the Endpoint itself for self (§2.2.1). Before you assign IDs to a fleet, check three more requirements:

• R-ARC.3: the Broadband Forum OUI 00256D and Private Enterprise Number 3561 are reserved for BBF documentation and prototyping and must not be used by anyone else. That is why they appear in the examples above.
• R-ARC.4: the proto and doc schemes must not be used in production environments.
• R-ARC.4a: an Endpoint that uses fqdn must present TLS certificates with a subjectAltName that allows that domain name.

Where does the Endpoint ID appear on the wire?

Over a secure WebSocket connection, the Endpoint ID appears three times, in this order:

1. TLS handshakeIn the certificateThe subjectAltName carries the Endpoint ID in its URN form.
   • urn:bbf:usp:id:…
2. WebSocket handshakeIn the opening requestThe client offers the v1.usp subprotocol and puts its own Endpoint ID in the request URI.
   • eid=…
3. USP RecordIn every RecordTwo required fields name the target and the source Endpoints.
   • to_id
   • from_id

1. In the certificate. When an X.509 certificate authenticates an Endpoint, its subjectAltName must carry the URN form of the Endpoint ID, or for fqdn the domain name itself. When certificates authenticate at the MTP layer, Endpoints must not process Records whose from_id does not match the ID in the certificate (R-SEC.0a, §8.1).
2. In the WebSocket handshake. No USP Record is sent until TLS is complete, so the server cannot tell who the client is without looking inside the certificate (§4.3.2.1). The client sends the Sec-WebSocket-Protocol header with the value v1.usp (R-WS.9, R-WS.10) and adds its Endpoint ID to the request URI query as eid (R-WS.10b). A percent character in the ID is itself percent-encoded, so doc::agent%21 travels as doc::agent%2521 (R-WS.10c).
3. In every Record. Each USP Record carries the target Endpoint ID in to_id and the source in from_id, and both fields are required (§4.1.3.1).

Because the other side checks identity against this value, treat an Endpoint ID as permanent: one that changes after it has been used can also cause unpredictable behavior (§2.2.1). Certificates, trust and Controller roles are covered in TR-369 security.

Can an Agent and a Controller share an Endpoint ID?

Yes, within limits. An Agent and a Controller in the same USP Domain may use the same Endpoint ID, and every Endpoint must tolerate that (R-ARC.0, R-ARC.1). But Endpoints that share an ID must not talk to each other over USP (R-ARC.2), and unless the assigning authority says so, no relationship between them can be assumed (§2.2.1). In software modularization, sharing is even recommended: a USP Service that embeds both an Agent and a Controller should use one Endpoint ID for both, or the USP Broker cannot correlate them as a single USP Service (Appendix VI.2).

What USP does not give you is a safety net for duplicates within one role. It defines no process to identify or resolve an Endpoint ID that is not unique among all Agents or all Controllers, and the result is “unpredictable behavior” (§2.2.1). The only built-in rule is for self: an Endpoint that meets another one using the identical ID must change its own (§2.2.1).

For the bigger picture, messages, transports and data models included, start with what is TR-369.