TR-369 Training - Using path names to address service elements

Service Elements that are defined in the USP Data Model are addressed in USP Messages with a particular syntax called Path Names. Path Names are called such because they describe the “path” within the data model’s tree of objects used to reference a particular object or elements of that object to operate upon.

Addressing Objects

Object Paths directly address objects in the Agent’s Instantiated or Supported Data model. Static objects (that is, those that are not multi-instance), are addressed starting with the Root Data Model object (Device), with “dot” separators that lead to the desired object. For example, Device.LocalAgent.

Using Reference Paths

A reference parameter is a parameter in the data model that contains a path name to another service element. They operate a little differently than other path names - for example, object paths in a reference parameter do not end in a "."

Additionally, you can use the "+" decorator to tell an Agent to automatically follow a reference that is included in a reference parameter in order to address the referenced element directly. You can read more about using reference parameters in TR-369.

Using Reference Paths

A reference parameter is a parameter in the data model that contains a path name to another service element. They operate a little differently than other path names - for example, object paths in a reference parameter do not end in a "."

Additionally, you can use the "+" decorator to tell an Agent to automatically follow a reference that is included in a reference parameter in order to address the referenced element directly. You can read more about using reference parameters in TR-369.

Unless used in as a reference in a reference parameter, Object Paths always end in a “dot”.

Multi-instance objects are addressed differently, depending on if the Agent is reporting from its Supported or Instantiated Data Model. When retrieving the Agent’s supported data model using the GetSupportedDM message, multi-instance objects are addressed using {i} notation in the Path Name.

Using Instance Identifiers

Multi-instance objects that are currently instantiated on the Agent are addressed using an Instance Identifier. An instance identifier can take one of two forms.

Addressing by Instance Number

The first is an Instance Number. An Instance Number is expressed in the Path Name as a positive integer (>=1) with no additional surrounding characters. Instance numbers are assigned by the Agent when an object is created, and MUST not change until the object is removed. It’s also recommended that the Agent not re-use Instance Numbers for new objects if possible.

Addressing by Unique Key

The second method is to address an object by its Unique Key. Multi-instance objects are much like tables in a database. Each object defines a set of parameters that constitute its unique key - that is, no two objects can exist with the same values for that set of parameters. These are outlined in the description of each object. Some objects have multiple unique keys that are unrelated to each other.

For example, Device.Wifi.SSID. lists Alias, Name, and BSSID as unique keys. Each of these are independent of each other, so no two objects can exist with the same Alias, the same Name, OR the same BSSID.

Other objects have unique keys that are the union of one or more parameters. This is called a compound unique key. For these objects, all of the parameters together uniquely identify the object. For example, Device.NAT.PortMapping. specifies RemoteHost, ExternalPort, and Protocol as its unique key. No two objects can exist with the same values for all three of these parameters - if even one is different, it identifies a different object.

To use unique keys to address an object, use the following syntax. First, specify the path to the object’s name. In place of the instance number, use the following syntax (if the value is a string, use quotations to indicate this):

Device.WiFi.SSID.[BSSID==”AA:BB:CC:DD:EE:FF”].

For an object with a compound unique key, use double-ampersand “&&” and list all of the required keys.

Device.NAT.PortMapping.[RemoteHost==”172.16.1.5”&&ExternalPort==22&&Protocol==”TCP”].

Search Expressions and Wildcards

There is another method for addressing service elements. These are called search expressions or search paths in USP. You can use a search expression to address objects that have a particular parameter value (in the same fashion as unique keys), or to request objects that have parameter values in comparison to an operator like greater than, less than, equal, or not equal. For example, if you wanted to retrieve the statistics of a WiFi radio where the ErrorsSent are greater than 1000, you could use:

Device.WiFi.Radio.[Stats.ErrorsSent>1000].Stats.

To find the offending WiFi connection.

Lastly, USP also lets a controller use wildcards to address all instances of an object in the object path. For example, a Get message requesting Device.WiFi.Radio.*.Stats.ErrorsSent would return the ErrorsSent of every radio object.

Addressing Parameters, Commands, and Events

In addition to addressing Objects, Path Names are used to address parameters, commands, and events.

Parameters are addressed by simply ending the path with a parameter name:

Device.DeviceInfo.FriendlyName

Commands are addressed by ending the path with the command name, followed by open-and-closed parenthesis:

Device.Reboot()

Events are addressed by ending the path with the event name, followed by an exclamation point.

Device.Boot!

Build your USP/TR-369 solution

Test against an automated, scriptable USP Controller with thousands of pre-defined test cases.

Learn more

Develop your solution even faster with comprehensive automated test cases and a scriptable USP Controller.