MQTT

MQTT server

The device primarily communicates over the internet using the MQTT server (broker). The address of this server is preset in the device but can be changed to use your own server.

You can install your own server on PC or on single board computers like Raspberry Pi-type, in a leased VPS server, etc. For common purposes, we can install MQTT Broker Mosquitto. You then connect the broker to the device itself, but also to your own application. Instead of an application or script, you can also choose the command line - for example: code: mosquitto_pub and: code:` mosquitto_sub` for sending or receiving messages.

Example mosquitto_pub for 100% window opening

mosquitto_pub  -t ion/nmfnjabs/%18fe34e010e2/cmd -m "open;100"

ion/nmfnjabs/%18fe34e010e2 is topic (in context of MQTT), where the device awaits commands (more info below), open;100 is the command to be executed. This example assumes the MQTT broker available on localhost and standard port.

MQTT protocol

Since most of the MQTT topics begins the same, we will only write PREFIX in the following text, which will match ion/<USER>/%<DEVICE_ID> . Where

  • USER is user signed in MQTT (in Smarwi called REMOTE_ID),
  • DEVICE_ID is a hexadecimal string that uniquely identifies your device..

Prefix example: ion/nmfnjabs/%18fe34e010e2. (please note % character before device identificator)

Concection, initial data

After connecting to the MQTT server, the device logs in to subscribe to the following topics:

  • PREFIX/cmd/#
  • PREFIX/s/+/cmd

The first topic is intended to send general commands for devices while the second one for commands designed for sensors, incl. internal ones.

Subsequently, the device sends a string “1” into the topic PREFIX/online and status data into the topic PREFIX/status. both with RETAIN index (ie permanent data in MQTT)

Topic PREFIX/online can be used to distinguish online/offline status (whether the device is connected), when you log out or disconnect your device, the message in this topic will be overwritten to “0” (this behavior is ensured by the MQTT broker using a Last Will message).

Any MQTT client should therefore for detection of connected devices follow the topic ion/<USER>/# or independently ion/<USER>/+/online and ion/<USER>/+/status

Device commands

Device commands correspond to commands for other APIs, except that the entire command, including parameters, is the content of the MQTT message, and semicolon (;) is used instead of slash (/).

E.g. to send command open with parameter 50 (open on 50%) we send the message “open;50” into topic PREFIX/cmd

Examples for sensors

Internal sensors have no public commands. Commands usable with other devices and external sensors will be added whenever new devices are released to the market.

Device status information

Information is in text form, individual information is separated by lines (LF character), each row has syntax key:value This information is automatically sent into topic PREFIX/status at each change of state.

Example of state information
     t:swr
     s:200
     e:0
     ok:1
     ro:0
     pos:c
     fix:0
     a:0
     fw:203.2.1
     mem:19928
     up:259284714
     ip:285870602
     cid:BedroomWindow
     rssi:-63
     time:1523292002
t
device type (swr)
s
state code
e
error code
ro
ridge inside the device
pos
window position (c - closed, o - open)
fix
window position fixed (window fixed by device)
ip
32bit number representing IP addres
cid
device name
rssi
signal strength
fw
device firmware version