This page describes certain fundamental issues about using the IAP/MQ API.  It includes the following sections:

MQTT in IAP

The IoT Access Protocol (IAP) uses an MQTT message broker similar to brokers such as Mosquitto or ActiveMQ, known as the IAP message broker.  An IAP system typically includes central management software (CMS). It includes an IAP message broker, known as the CMS message broker or the CMS broker.  IAP Edge Servers typically include a local message broker, sometimes referred to as a segment message broker.

IAP does not require a specific broker, specific MQTT client library, or implementation as long as the chosen broker and clients support the appropriate versions of MQTT, as indicated in "Supported MQTT Version" below.

IAP is case-sensitive.

Supported MQTT Version

All MQTT components of an IAP system must support MQTT protocol version 3.1.1. 

MQTT version 3.1 or earlier is not supported.

IAP/MQ Topic Syntax

All IAP topics use a specific format as described in IAP/MQ Topic Syntax.

Persistent Clients vs Transient Clients

An IAP client can implement a persistent or a transient MQTT client. Most IAP clients are persistent clients.  

For a persistent client, the broker maintains events while the client is unavailable, whereas events are lost to a transient client while the transient client is disconnected. 

For example, a client subscribes to a certain set of topics in the IAP/MQ event channel. Then this client disconnects, and later re-connections. Publications made to the subscribed topics during the client's downtime will be delivered to the client if it is a persistent client. A transient client will not see publications that occurred during its downtime. 

But a side effect of a persistent client that never reconnects, is that the client can accumulate many messages that the broker keeps on that client's behalf. This issue is discussed in "Client Expiration" below.

MQTT clients implement persistence using a constant and unique client ID, and the MQTT property cleanSession=False when connecting to the IAP message broker.  Persistent clients must specify a unique MQTT client ID, and must re-use the same client ID in every session. An MQTT client identifier is between 1 and 23 characters long, UTF-8 encoded, and can consist of letters a-z, A-Z, digits 0-9. Some brokers also allow for additional characters; but that's not part of IAP/MQ. A client ID can be constructed from a combination of the MACID and a sequence number, or completely at random, and is often allocated by agreement among components.

Temporary tools, such as mobile servicing and diagnostic tools, should connect as transient clients, using a unique client ID and the MQTT property cleanSession=True when connecting.  This includes tools that do not expect to re-connect to the same system regularly or do not need to catch-up with the history of events and changes that occurred between connections.

Transient clients must specify a unique MQTT client ID, but can allocate a new client ID for every session, if necessary. A transient client ID begins with a unique identifier, which has the same format as a persistent client ID.

Client Expiration

A typical IAP message broker supports persistent client expiration at an interval of 2 hours. When a persistent client is disconnected for a duration exceeding this interval, the persistent client’s session is automatically cleared to free resources in the broker.

The SmartServer IoT segment broker expires disconnected persistent clients after 2 hours.

Message Payload

The payload for IAP/MQ messages is JSON encoded.  However, for readability, many of the examples in this document are shown in Javascript format, which eliminates the use double-quotes around keys, as shown in the following example.

CMS Connectivity

Connectivity between the CMS broker and individual segment brokers is not always present. Some systems may be designed to connect on a schedule and for limited duration only, other systems may simply use unreliable connections.  Tools cannot assume that the edge server is present at the time the tool makes a change. Tools can detect the presence or absence of connectivity, and indicate the state in the user interface. However, a tool shall not expect to receive immediate confirmation for a change through the feedback channel.

A well-designed IAP tool publishes changes to the request channel as necessary, and responds to updates received through the feedback channel as these updates become available.  It is important to note that the update received from the feedback channel reports the current system state at the time of the update, which may differ from the state that was requested with the request channel. This difference could be caused by an error processing the request or by a state change initiated by another client to the same system.

For example, a user interface tool might relay a human operator’s requests to turn a light on at 50% brightness. When the tool makes that request, it may reflect the new state of on at 50% as a tentative state, as yet unconfirmed. When the corresponding feedback is received, the tool can then update its user interface to show the confirmed state, which may not be on at 50%.

An IAP Site

An IAP-based system consists of one or more sites. A site is typically a physical location, often providing shared Internet access to components within the site.  Each site in an IAP-based system includes one or more segments, with one edge server controlling each segment.

Partial Object Assignment

IAP/MQ supports partial object assignment where appropriate. For example, a write request can request to a change affecting one datapoint within a device’s interface block, leaving other properties and datapoints within the same block unchanged.

Some objects cannot support partial write operations. For example, a datapoint value is considered an atomic item and can only be modified whole.  For information on datapoint values, device interface blocks, or device objects see Interface Blocks.

Where partial assignments are supported, empty assignments are also supported.  An empty assignment is essentially an assignment without a value change, triggering the renewed publication of the corresponding feedback item. The edge server decides whether such an empty assignment also affects the edge device.

Field and object assignments must be compatible, according to the following rules:

• Some properties may be read only. Tools may write these properties as long as the value doesn’t change.

• Some properties may be write only. Such a property is used explicitly in an assignment request within the request channel, but is not explicitly reported within the feedback channel.

• Some objects and operations require a minimum set of properties. For example, the device do topic accepts an action object. This object always requires an action property, which specifies the desired action (provision, delete, etc), and the selected action typically requires further mandatory arguments. 
  These operations fail unless the minimum required details are provided. Failure is reported with an error diagnostic.

• Some clients may not be aware of all properties received with an object. Clients must not act on object types and topics they don’t recognize, but a user interface client could list this data in some generic representation for expert users.

• Privileged clients can add properties to standard objects. For example, the processor for Control-M devices might add a cm.radio_channel property to the device’s configuration object. Clients must include this property when publishing, and ignore it unless it is known and understood.

• User interface components, such as the CMS, do not generally have the privilege to add properties.

• The feedback channel always reports the complete object, even though objects support partial assignment in the request channel.

Edge Servers and Partial Object Assignment

Wherever partial object assignment is supported, edge servers must also support request topics that reach into an object. For example, the
glp/0/T23w64q/rq/dev/lon/1/if/light/0 topic addresses a particular interface block named “light” within a device. This request topic accepts assignment of a complete or a partial light interface block object.  

The following shorthand notation illustrates the assignment of a partial object to this topic, affecting only the desc property within that block:

The following example yields the same result, but this time using a topic that reaches into the interface block object.

Topics can address items at any depth within the addressed object. For example, the light interface block might implement an sp datapoint. The datapoint object supports a monitor object to control datapoint monitoring, which in turn supports a rate property to specify the frequency at which a new actual value should be obtained.

The following alternative forms all produce the same result (setting the rate to 17) using partial object assignments:

Timestamps in IAP

The standard timestamp format in IAP is the MRU timestamp (described below).  In addition to this timestamp, data events can also use the ts format (described in the Event Properties table).  The ts timestamp is a simplified extended ISO 8601 timestamp in the YYYY-MM-DDTHH:mm:ss.sssZ format, always in UTC.

The MRU timestamp (described below) uses the format: YYYY-MM-DD HH:MM:SS.sss ZZZ 
Where:

• YYYY is the four-digit year, 
• MM is the two digit month, 
• DD is the two-digit day of the month, 
• HH is the hour of the day, always using the 24-hour clock, 
• MM the number of minutes in the hour, 
• SS the number of seconds in the minute, 
• sss the number of milliseconds within the second,
• ZZZ is the name of the timezone for wall time or ‘UTC’.  

For information on configuring the timezone, see the time object in the Segment Configuration table.

All numbers are padded with 0 to the left to meet the specified number of digits, if necessary.  Number groups are separated with a single hyphen, colon, period, or a single space character.

Most Recently Used (MRU) Timestamp

All messages published in the feedback channel must include a most recently used (mru) timestamp, using the standard IAP timestamp format. Messages posted in other channels may include an MRU timestamp.  All MRU timestamps are UTC timestamps.

Most recipients of messages ignore the MRU, but some special tools might use the MRU, for example, to prune stale objects which may have resulted from the deletion of items.  MRU timestamps are always ignored when assigned through the request channel.

Deletion of resources generally leaves one item behind, a status object which informs clients that reconnect in the future that the resource in question has been deleted. These items are typically pruned on a low frequency.