ADAM MQTT Manual

Edition V1.0 , Oct. 2017

1. Introduction of MQTT(Message Queue Telemetry Transport)

MQTT protocol is the lightweight messaging transport. Clients connect to the broker and the
MQTT message is forwarded by broker. Furthermore, ADAM is designed with features that make it
more flexible in the IoT applications.

Feature 1: Actively Publish MQTT Message

Advantech ADAM can be set up to actively publish I/O data in the form of MQTT message at a
user’s defined interval. This feature provides an efficient way to transmit data and lower the system
loading.

Feature 2: Shorten Downtime with Actively Alarm Event Notification

The alarm event is usually referred to the digital input status changes or analog input in out of the
user’s defined range. Advantech ADAM is designed with alarm trigger mechanism with instant notice.
The MQTT message will be published to broker at the moment that alarm conditions is reached.

2. MQTT Format for ADAM module

Digital Input/output module :

ADAM-6050/6051/6052/6060/6066
Description MQTT Topic JSON data Firmware
Get the I/O data Advantech/MAC ID /data {"s":1,"t":0,"q":192,"c":1, "dix":DI D version
of ADAM digital Example: status,"dox":DO status} : V6.01B11
input/output Advantech/0013430C981C/data and higher
module version
Set the value of a Advantech/MAC ID/ctl/dox {"v":DO status}, D version
digital output of Example: : V6.01B11
ADAM module Advantech/0013430C981F/ctl/do1 and higher
version
Will Topic Advantech/MACID/Device_Status { "status":"Device Status", D version
Example: "name":"Device :V6.01B13
Advantech/0013430C981F/ Name","macid":"MACID", And higher
Device_Status "ipaddr":"IP Address"} version
 ADAM-6250/6251/6256/6260/6266
Description MQTT Topic JSON data Firmware
Get the I/O data Advantech/MAC ID /data {"s":1,"t":0,"q":192,"c":1, "dix":DI AE version
of ADAM digital Example: status,"dox":DO status} : A1.06B02
input/output Advantech/0013430C981C/data and higher
module version
Set the value of a Advantech/MAC ID/ctl/dox {"v":DO status}, AE version
digital output of Example: : A1.06B02
ADAM module Advantech/0013430C981F/ctl/do1 and higher
version
Will Topic Advantech/MACID/Device_Status { "status":"Device Status", AE version
Example: "name":"Device : A1.06B03
Advantech/0013430C981F/ Name","macid":"MACID", And higher
Device_Status "ipaddr":"IP Address"} version

Analog Input modules: ADAM-6017

Description MQTT Topic JSON data Firmware
Get the I/O data Advantech/MAC ID /data {"s":1,"t":0,"q":192,"c":1, "aix":AI CE version
of ADAM Example: value,"ai_stx":condition, "dox":DO :V5.03 B03
Analog input Advantech/0013430C981C/data status, "do_stx":condition} and higher
module version
Get an analog Advantech/MAC ID/cfg/sensor/aix {"typ":"Range"} CE version
input range Example: :V5.04 B00
configuration. Advantech/0013430C981F/cfg/sensor/ai1 and higher
version
Set the value of a Advantech/MAC ID/ctl/dox {"v":DO status}, CE version
digital output of Example: :V5.03 B03
ADAM module Advantech/0013430C981F/ctl/do1 and higher
version
Set an analog Advantech/MAC ID/set/sensor/aix {"typ":"Range"} CE version
input Example: :V5.04 B00
configuration Advantech/00D0C9F94344/set/sensor/ai1 and higher
version
Will Topic Advantech/MACID/Device_Status { "status":"Device Status", CE version
Example: "name":"Device :V5.04 B00
Advantech/0013430C981F/ Name","macid":"MACID", and higher
Device_Status "ipaddr":"IP Address"} version
General
s: Reserved for further use, default value 1
t: Reserved for further use, default value 0
q: Reserved for further use, default value 192
c: Reserved for further use, default value 1

DI/O Module
dix: Digital Input status of channel(x-1)
example: {"di2":true} means status of DI channel 1 is true
dox: Digital Output status of channel(x-1)
example: {"do2":true} means status of DO channel 1 is true
DO status true:on, false:off
DI status true:on, false:off

AI Module
aix: Analog Input value of channel (x-1)
Note: If AI channel is disabled, AI value shows “9999.9999”
ai_stx: Condition of analog Input channel (x-1)

ai_stx value Condition

0 Channel disable
1 Streaming, normal
2 High latch
3 High momentary
4 Low latch
5 Low momentary

do_stx: Condition of digital output channel(x-1), only for ADAM-6017 Digital output

do_stx value Condition

1 Streaming, normal
2 DO change
typ: Input range
Range Input rage value

Range value Input range

0-20mA 0~20mA
4-20mA 4~20mA
+-20mA ±20mA
0-5V 0~5V
1-5V 1~5V
0-10V 0~10V
0-1V 0~1V
0-500mV 0~500mV
0-150mV 0~150mV
+-10V ±10V
+-5V ±5V
+-2.5V ±2.5V
+-1V ±1V
+-500mV ±500mV

1.3 MQTT Configuration

The MQTT of ADAM can be configured by ADAM.Net utility (V2.05.11 B05 and higher version)
or ASCII command.

Note :MQTT function must be disabled before configuration and enable the MQTT function after
configuration is done.

 Host (Broker IP)

Users set up the broker URL or IP address . ADAM module connection to broker over standard
MQTT protocol.

 Heartbeat (keep-Alive)
The broker will regularly check the connection with the ADAM at interval of heartbeat
(keep-Alive) setting. The minimum interval setting is 5 seconds.
 Dead band
Dead band is set to determine the minimum interval between publishing two MQTT messages. It
is set to prevent MQTT message from publishing excessively by noise.

 Retain Message
When the retain function is enabled. The broker will store the last message of the topic. If a new
subscription for the topic is made, the message will be sent to the client. Client is able to get the
last message and does not need to wait until the next message is updated.

 Will topic
If the client subscribes the topic for the ADAM which is disconnected, the broker will inform the
clients by sending the will message to whom subscribe the will topic
Will Topic of ADAM: Advantech/MACID/Device_Status
Will message:
{ "status":"Device Status", "name":"Device Name","macid":"MACID", "ipaddr":"IP Address"}
Will message example:
{"status":"disconnect","name":"ADAM6051","macid":"00D0C9FEFFF5","ipaddr":"10.0.0.1"}

 QoS(Quality of Service)
Users can choose the QoS level of publish/subscribe. Three levels of QoS (Quality of Service)
are defined in MQTT.
Level 0: broker/client deliver the message at most once
Level 1: broker/client deliver the message at least once
Level 2: broker/client deliver the message exactly once

 Publish/Subscribe Topic
The MQTT message is forwarded by broker based on the MQTT topic. Each message contains
the data value. When client publishs MQTT message to broker, the clients who subscribe the
topic will receive the MQTT message accordingly.
1.3.1Configuration by ADAM.Net utility
Click “Cloud button” in the function list to configure the MQTT setting

Users could set up the broker URL or IP address at “Host”. Three public broker sources link are
listed in the utility
- iot.eclipse.org
- test.mosquitto.org
- broker.mqttdashboard.com

1.3.2 Configuration by ASCII

Digital input/output modules:

ADAM-6050/6051/6052/6060/6066/6250/6251/6256/6260/6266

Command Description Remarks

%aaSETMQTTENxx Set MQTT enable/disable Return: >01
aa: always 01 Error: ?01
xx: 01 (enable),
00 (disable)
%aaSETMQTTADxx…x Set IP address of the broker Return: >01
aa: always 01 Error: ?01
xx…x: IP address/domain
(0~50 character)
%aaSETMQTTHBxxxx Set heartbeat interval Return: >01
aa: always 01 Error: ?01
xxxx: heartbeat interval in second
(0005~FFFF)
%aaSETMQTTPDxxxx Set publishing deadband Return: >01
aa: always 01 Error: ?01
xxxx: publishing deadband in
millisecond (0032~03E8)
%aaSETMQTTPRxx Set publishing retain Return: >01
enable/disable Error: ?01
aa: always 01
xx: 01 (enable),
00 (disable)
%aaSETMQTTPQxx Set publishing Qos Return: >01
aa: always 01 Error: ?01
(xx): publishing Qos (00~02)
%aaSETMQTTSQxx Set subscribing Qos Return: >01
aa: always 01 Error: ?01
(xx): publishing Qos (00~02)
ujhhhj%aaGETMQTTEN Get MQTT enable/disable Return: !01 (enable)
aa: always 01 !00 (disable)
Error: ?01
%aaGETMQTTAD Get IP address of the broker Return: !IP Address/Domain (IP
aa: always 01 Address/DomainName)
Error: ?01
%aaGETMQTTHB Get heartbeat interval Return: !xxxx (heartbeat interval in
aa: always 01 hex format)
Error: ?01
%aaGETMQTTPD Get publishing deadband Return: !xxxx (deadband in hex
aa: always 01 format)
Error: ?01
%aaGETMQTTPR Get publishing retain Return: !00 (enable)
enable/disable !01 (disable)
aa: always 01 Error: ?01
%aaGETMQTTPQ Get publishing Qos Return: !xx (publishing Qos in hex
aa: always 01 format)
Error: ?01
%aaGETMQTTSQ Get subscribing Qos Return: !xx (subscribing Qos in hex
aa: always 01 format)
Error: ?01

Analog input modules

ADAM-6017
Command Description Remarks
%aaSETMQTTENxx Set MQTT enable/disable Return: >01
aa: always 01 Error: ?01
xx: 01 (enable),
00 (disable)
%aaSETMQTTADxx…x Set IP address of the broker Return: >01
aa: always 01 Error: ?01
x…x: IP address/domain
(0~50 character)
%aaSETMQTTHBxxxx Set heartbeat interval Return: >01
aa: always 01 Error: ?01
xxxx: heartbeat interval in second
(0005~FFFF)

%aaSETMQTTSTxxxxxxxx Set publishing data streaming Return: >01

interval time Error: ?01
aa: always 01
xxxxxxxx: publishing data streaming
interval time in millisecond
(0032~FFFFFFFF)
%aaSETMQTTPRxx Set publishing retain Return: >01
enable/disable Error: ?01
aa: always 01
xx: 01 (enable),
00 (disable)
%aaSETMQTTPQxx Set publishing Qos Return: >01
aa: always 01 Error: ?01
(xx): publishing Qos (00~02)
%aaSETMQTTSQxx Set subscribing Qos Return: >01
aa: always 01 Error: ?01
(xx): publishing Qos (00~02)
%aaGETMQTTEN Get MQTT enable/disable Return: !01 (enable)
aa: always 01 !00 (disable)
Error: ?01
%aaGETMQTTAD Get IP address of the broker Return: !IP Address/Domain (IP
aa: always 01 Address/DomainName)
Error: ?01
%aaGETMQTTHB Get heartbeat interval Return: !xxxx (heartbeat interval
aa: always 01 in hex format)
Error: ?01
%aaGETMQTTST Get publishing data streaming Return: !xxxxxxxx (data streaming
interval time in hex format)
aa: always 01 Error: ?01
%aaGETMQTTPR Get publishing retain Return: !00 (disable)
enable/disable !01 (enable)
aa: always 01 Error: ?01
%aaGETMQTTPQ Get publishing Qos Return: !xx (publishing Qos in hex
aa: always 01 format)
Error: ?01
%aaGETMQTTSQ Get subscribing Qos Return: !xx (subscribing Qos in
aa: always 01 hex format)
Error: ?01
1.4 How to start the MQTT with ADAM
ADAM.Net utility provides the pages to simulate MQTT client to test the MQTT of ADAM modules.
Users are able to experience the benefits of the ADAM with MQTT in 4 steps.

Step 1 :Click “Tools” and “MQTT”, the page will forward to ADAM MQTT page

Step 2 :Set up the connection

In the connection configuration page, user is able to set up the client information. The default host is
public broker source” iot.eclipse.org” at port 80. Users can also set up the host URL or IP address.
Click “connect” when the configuration is done.

Note: 1. Path, Username, Password, TLS, Clean session function is not released
2. The webpage only supports the connection to broker over WebSocket
Step 3: Subscribe/Publish function
Subscribe
Users set up the topic and choose the QoS level, then click the subscribe button. The message of the
topic will be shown in the history field.
Publish
Set up publish topic, QoS and message, then click Publish button. The MQTT message will be
published to the broker. If the retain function is enabled. ADAM will receive the last message when
subscribes the topic.

Step 4: Review the MQTT Message

Users can read the last MQTT message and the historical messages in last message column and history
column.

Last message of ADAM module

History message of ADAM module