IAP/MQ Topic Syntax

The syntax for topics is as follows:   

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





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


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.


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: 


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. 

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.


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:


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.


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.


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.


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:


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


But more topic elements are possible, such as:


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.


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                                                                  
aboutSegment Information
cfgSegment Configuration
devDevices (see Device Syntax below)
resResource Data Types
sevSchedule Services
stsSegment state

Handle request

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


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:


For a grp resource:


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:


"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.

Device Syntax 

.../dev / {Edge_Protocol_ID} / {Handle} / {Object_Path} [ / {Property_Path} ]

Following the 
dev resource element, device topics can include the following elements:  

Topic ElementDescription

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:

Protocol ID      Description                                                                                        
lonLON and LON/IP (ISO/IEC 14908-1, EN 14908-7, and ANSI/CTA 709.7)
bacBACnet (ISO 16484-5)


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.




        lon is the Edge Protocol ID
        2 is the Handle
        cfg is the Object Path

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:





        lon is the Edge Protocol ID
        2 is the Handle
        if/light/0, if/light/1, if/occ/0 are the Object Paths

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.


The following wildcards can be used in the topic syntax for MQTT subscriptions:  # and +

Clients can receive messages by creating subscriptions. A subscription may be to an explicit topic, in which case only messages to that topic will be received.   Or a subscription may include wildcards. The following table describes the two wildcards:


Can be used to represent all remaining levels of hierarchy.  This means that it must be the final character in a subscription.


Can be used to represent a single level of hierarchy in a subscription.