/
IAP/MQ Topic Syntax

IAP/MQ Topic Syntax

The syntax for topics is as follows:   

glp / {IAP_Version} / {SID} / {Channel} / {Resource_Type} [ / {Resource_Detail} ] [ / {Property_Path} ]

Example

glp/0/s1/fb/dev/lon/2/if/light/1 

Where:

glp

IAP topics always begin with glp, where glp is a constant keyword. A topic cannot begin with a slash.

IAP_Version

The topic must specify the IAP version. The current version is 0 (zero).  All IAP implementations support version 0 of the protocol. The number provided here indicates the highest protocol version supported. IAP supports all versions up to and including the maximum protocol version indicated with glp/0/{SID}/about/version.

There are cases where the CMS, edge servers, and edge devices may end up are aware of different versions of IAP. How this is handled by IAP depends on the specific situation, but in general the CMS uses the highest version required by the message that is supported by the CMS and the edge servers. For example:

  • In the case where the CMS is aware of version 0 only and an edge server reports supporting version 1, then the CMS uses only version 0.

  • In the case where the CMS is aware of version 2, and an edge server reports supporting version 1, then for messages that do not require version 1 or 2, the CMS uses version 0, and for messages that require version 1, the CMS uses version 1. In this case, the CMS never uses version 2.

  • The edge server and its components always publish to all supported versions.

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: 

[A-Za-z0-9][A-Za-z0-9.-_]*                                                   

The SID is assigned to the edge server when the segment is provisioned. A regular SID has the format shown above. A different address is used in place of the SID in certain specific circumstances, such as before the segment is provisioned, or to indicate a local address for the edge server. For information about SIDs before an edge server is provisioned, see Segment Discovery.

A local address for the edge server can be used for communication between IAP components within a segment. Topics using “.” for the SID are called local topics. Local topics are not relayed to the CMS or other segments through bridges. Topics using local addressing never traverse connections between CMS and a remote edge server.

A period identifier used outside the segment represents a segment-independent address.  And like local topics, segment-independent topics are not relayed across bridge connections. 

glp/0/./=logger/event                                                             

Note: The = sign is used to indicate that the topic is addressing a service, instead of an object.

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:

rq    

Request Channel. Tools use the request channel to publish messages requesting value or state changes.  Messages in the request channel flow from the tool or CMS to the edge server, and within the segment the messages flow to the edge processor or to another service. The request flows to the component responsible for acting on it.

All publishing to the request channel use MQTT properties QoS 2, retain=False.

fb

Feedback Channel. The feedback channel provides the system state from the edge processor or another component within the edge server to all clients.

All publishing to the feedback channel uses MQTT properties QoS=1, retain=True.

The fb channel is retained so that new clients receive the current system state when they subscribe to the feedback channel. A client can subscribe to the entire feedback channel, or only to selected topics and topic groups within the feedback channel.

All feedback channel objects include a timestamp of the most recent update for that object. This is provided in the mru property.

ev

Event Channel. The event channel provides diagnostics, such as errors, warnings, alarms, and similar information to all clients.

All publishing to the event channel use MQTT properties QoS=1, retain=False.

A new client will not receive events that occurred in the past, and neither will a disconnected non-persistent client. However a disconnected persistent MQTT client will receive events missed while it was disconnected. A persistent MQTT client is one that connects with the MQTT attribute "cleanSession" set to False.

bin

Binary Channel. Topics within the binary channel address a binary blob of data. There are no objects or properties within objects in the binary channel, and binary channel topics do not provide any hierarchy within the channel.

An IAP/MQ binary channel topic matches the following filter:

glp/0/+/bin/+/#                                                                

An IAP/MQ binary channel topic typically takes the form:

glp/0/{SID}/bin/{Handle}                                                 

But more topic elements are possible, such as:

glp/0/{SID}/bin/{Handle}/a/b/c                                          

Unlike the request, feedback, or event channel, a binary channel topic, such as glp/0/{SID}/bin/{Handle}/a/b, is independent and has no relation to glp/0/{SID}/bin/{Handle}/a.

Blobs of data within the binary channel are limited in size, and are usually considered short-lived. A use-case is that of embedded transfer of small binary images through IAP/MQ for use with the load action.

IAP/MQ infrastructure components support at least three simultaneous publications up to 128 KB, each within the binary channel. Publications exceeding the size limit, or exceeding the maximum number of simultaneous publications, can be refused with standard MQTT message codes, using no PUBACK with MQTT 3.1.1, or a negative acknowledgment with MQTT 5 (see Supported MQTT Version for the currently supported version of MQTT).

Simultaneous publications are those that are published with retain=true and are not yet deleted, plus those published with retain=false and not yet delivered to all subscribers.

Items are published into the binary channel using QoS=1 or 2, retain=true. The consumer of that data, such as the component executing a load action, is expected to remove that data by publishing null with retain=true to the same topic.

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.

Resource Type     

Resource                                                                  

about

Segment Information

alarm

Alarms

app

Apps

cfg

Segment Configuration

con

Connections

dev

Devices (see Device Syntax below)

grp

Groups

res

Resource Data Types

sev

Schedule Services

sts

Segment state

=system

Handle request

Note: The = sign is used to indicate that the topic is addressing a service, instead of an object.

Resource_Detail

The general syntax for the Resource Detail is:

[{Edge_Protocol_ID}/] {Handle}/{Object_Path}                                                                            

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 and grp Resource is shown below:

For a dev resource:

   glp/{IAP_Version}/{SID}/{Channel}/dev/{Edge_Protocol_ID}/{Handle}/{Object_Path}            


For a grp resource:

   glp/{IAP_Version}/{SID}/{Channel}/grp/{Handle}/{Object_Path}    

See Device Syntax below for more syntax information.

Property_Path

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:

glp/0/s1/rq/dev/lon/a/if/LightCntrl/0/nviLampValue/value                                                         


"glp/0/s1" is the segment address.

".../rq" addresses the request channel within the segment.

".../dev/lon/a" addresses a device object (.../Resource_Type/Edge_Protocol_ID/Handle).

".../if/LightCntrl/0" addresses an interface block within the device (.../Object_Path).

".../nviLampValue/value" is a property path within that interface block object.