SID

The SID is the Segment Identifier, which is the logical address of the device that controls a segment.  In IAP, that device is either an edge server, or, an IAP-native edge device that is the only device on that segment. Such an edge device can still implement other object types, such as alarms or connections for itself, and uses the standard topic layout.

An SID consists of the letters A-Z, a-z, digits 0-9, and special characters period (.), hyphen (-), and underscore (_). Special characters are not allowed as the first character of a SID. A valid SID matches this regular expression: 

Changing a segment identifier requires that the segment be deprovisioned first, then re-provisioned with the new segment identifier.

Reserved SIDs:

• • Beginning an SID with one of the following characters is reserved for use within the edge server: %, &, $
    
  • No SID can begin with # or + to avoid confusion with MQTT topic wildcards.
    
  • No SID can contain a slash ( / ).

Wildcards and SIDs:

No tool or service should subscribe to IAP/MQ topics using a wildcard for the SID.  Do not subscribe with glp/0/+/..., always use the period for local topics and the specific SID for all other topics.  Exceptions to this are possible for exceptional services and diagnostic tools that need access to everything.  IAP/MQ developers need to exercise caution when specifying SIDs.

Channel

The IAP groups topics and message handling attributes into directional communication channels. Additional channels may exist within an edge server, but tools must not react to channel types that they are unaware of. When necessary, tools must process any unknown channel types verbatim. 

IAP includes the following channels, with the following identifiers:

Resource_Type

IAP supports a variety of resource types such as devices, groups, schedules, etc. The supported resource types includes those in the following list. Additional resources are used in special cases, typically within the edge server.

The general syntax for the Resource Detail is:

Depending on the Resource Type, the Resource Detail may include an Edge_Protocol_ID (such as for dev resources), and the Object_Path element can be multiple levels deep, depending on the object being specified.

Possible topic syntax for a dev Resource andgrp Resource is shown below:

See Device Syntax below for more syntax information.

Many resources allow topics to address a property within the selected object. This includes nested properties, which are separated with a single forward slash.

Consider the following example:

Topics separate device objects according to their edge protocol. The edge protocol identifiers are typically two or three-letter acronyms, defined by the edge protocol driver. When required, the edge protocol identifier follows the resource type identifier.

Edge servers may support the following edge protocols:

Handle

Handles are identifiers of addressable items used with IAP topics. The handle is a unique identifier within its scope. For example, every device object has a unique handle within its edge protocol and within its segment.

A handle is a case-sensitive string at least one character long, and consists of letters A-Z and a-z, digits 0-9, and special characters period (.), hyphen (-), and underscore (_).  A period can be used to separate parts of a handle, but cannot be used as the first character. The following characters are reserved, and must not be used: =, :, &

The handle is assigned by the tool that creates the primary item. For example, a tool might create a LonWorks device and assign handle "1" or "2" as shown in the example below.

Other handles are intrinsic to the principal item. For example, a device might have two "light" interface blocks, which appear with interface block address light/1 and light/2, respectively.

Tools allocate handles when creating resources through the request channel. Tools are responsible for allocating a unique handle.

For more information, see Handle Allocation.

The Object Path refers to the object addressed within the device.  Depending on the specific object, the Object Path can actually be multiple levels deep and can contain additional handles.

Each device supports a configuration object with the cfg endpoint in the request and the feedback channel.  In the request channel it is used to support modifications to the object configuration. In the feedback channel it provides the complete and correct configuration object at all times.

The following examples show the cfg endpoint in the feedback and request channels.

Other endpoints within a device are datapoints in the device's interface object (if), which contains sets of blocks of functionality. For example, one device might support two lights and one occupancy sensor, perhaps addressed with these topics:

Most object types support a status object (sts) in the feedback channel, and a do endpoint in the request channel used to invoke methods on the object.

Nested Properties

Many properties and nested properties within an addressable object can be addressed with the object path, but exceptions exist: a datapoint value, which is within most interface blocks, can only be written in its entirety, and can never be written only in parts. Therefore, a datapoint value can be addressed and written with an object path alone only if the datapoint implements a scalar type. Datapoints implementing complex types must be written with an object path that ends at the value property within the datapoint object.  

For example: value 1234 can be published to a scalar datapoint with a topic such as glp/0/1/rq/dev/lon/1/if/light/0/sp/value. 

A datapoint that implements a complex type such as a structure with r, g, b values, must be written in its entirety, for example by writing  {r: 0.5, g: 0.7, b: 0.83} to glp/0/1/rq/dev/lon/1/if/light/0/sp/value.