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. .. admonition:: Example *mosquitto_pub* for 100% window opening :class: note :code:`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 :code:`ion//%` . 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: - :code:`PREFIX/cmd/#` - :code:`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 :code:`PREFIX/online` and status data into the topic :code:`PREFIX/status`. both with *RETAIN* index (ie permanent data in MQTT) Topic :code:`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 :code:`ion//#` or independently :code:`ion//+/online` and :code:`ion//+/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 :code:`open` with parameter 50 (open on 50%) we send the message "**open;50**" into topic :code:`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 :code:`PREFIX/status` at each change of state. .. code-block:: none :caption: Example of state information :name: state 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 .. glossary:: *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 .. _Mosquitto: https://mosquitto.org/