Device.Boot!
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.
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.
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.
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.
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.
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”].
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.
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!
Get your USP Agent certified now with the official Broadband Forum test platform.
