4. MQTT Guide

Here you will find the basic concepts of MQTT and the specification of how the messages are send to and from your device.

What is MQTT?

MQTT is a lightweight simple messaging protocol, designed for constrained devices with low-bandwidth. This means that it is the perfect solution for the Internet of Things and Home automation applications and it's usually more flexible stable and reliable than other protocols like WebSockets. MQTT allows you to send commands to control outputs, read and publish data from your devices and more.

Basics of MQTT

In MQTT there are 3 basic concepts:

Topics: these are like addresses for a message, here is how a topic would look like:

Topic: Home/Livingroom/Lamp/Turn

Message: ON

here the topic is Home/Livingroom/Lamp/Turn and the message is ON, and this is the basic structure of all messages that are sent through MQTT

Publish/Subscribe system:

Every device can subscribe to topics, and it will receive all the messages sent with the topics they are subscribed to, they can subscribe to multiple topics and also subtopics.

Also when publishing a message the devices must provide the topic so the message can be successfully delivered.

A device who is subscribed to Home/# will receive messages sent to Home/Livingroom and also those sent to Home/Bedroom just by using the # sign.

Broker:

Is the central device who allows and restricts connections and also, receives, filters, redirects and publishes messages to all devices connected. In this case, the broker is Smartnest Server.

Is MQTT only a tool to talk to the server?

No, you can also interconnect your devices using this protocol, for example, if you have a motion sensor and a lighting system, and they are too far away from each other, you don't need to install cables across the room to let them communicate, you can just make the light to subscribe to the topic Bedroom/Light and you can have the sensor publish to that topic, at the same time they will be connected to Smartnest and all the integrations.

Smartnest and MQTT

At Smartnest every device has a unique ID, this ID must be used as the first part of a topic.

If you are sending a message to the broker this must be the Id of the device which is sending the message.

If you are sending the message to another of your devices this should be the Id of the device you are sending the message to.

The following parts of the topic can be customized by the user, for example, this would be a valid topic from the device to Smartnest Broker:

jasds3421FDC1CDSCDSfdsas/Bedroom/Temperature Message:25

while this would be an invalid topic:

Bedroom/Temperature Message:25

Smartnest MQTT commands

There are some subtopics reserved for special purposes and here is the list of all the reserved topics:

Directives:

Directives are sent From the server to the device every time there is a new command from any of the integrations.

Topic	Message	Description	Supported types
DeviceID/directive/powerState	ON - OFF	Power state of the device	All
DeviceID/directive/percentage	0-100	New percentage	Light
DeviceID/directive/setpoint	-100 - 200	Temperature Setpoint	Thermostat
DeviceID/directive/lockedState	true - false	true means lock the device	Lock

Reports

Reports are sent from the device to the server to inform about a state change. This reports must be every time after receiving a directive and also when there is a change due to a physical interaction like pressing a button.

Topic	Message	Description	Supported types
DeviceID/report/powerState	ON - OFF	Power state has changed	All
DeviceID/report/percentage	0-100	Percentage has changed	Light
DeviceID/report/setpoint	-100 - 200	Setpoint has changed	Thermostat
DeviceID/report/temperature	-100 - 200	New temperature sensed	Thermostat, Temp Sensor
DeviceID/report/humidity	0 - 100	New humidity	Thermostat, Temp Sensor
DeviceID/report/pressure	>0	New pressure	Temp Sensor
DeviceID/report/scale	C - F	Select temperature scale	Thermostat, Temp Sensor
DeviceID/report/lockedState	true - false	Locked state has changed	Lock
DeviceID/report/online	true - false	the device is connected	All
DeviceID/report/info	(Any)	To show in the Web App	All
DeviceID/report/detectionState	true - false	Sensor logic value	Presence, Contact sensor
DeviceID/report/notification	(Any)	Send a push notification	All

Requests and responses

Requests are sent from the device to the server in order to ask for special information like time, the server will respond with a response topic.

Topic	Message	Description
DeviceID/request/time	GMT+XX	get the real time the message can include the timezone GMT+XX, if timezone is not present GMT+00 will be sent
DeviceID/response/time	HH:MM:SS	Answer the time request

Smartnest MQTT Rules

At Smartnest we are a community of Home Automation and we are all using the same resources so here are the rules that everyone must follow when using MQTT:

1. The connection will be only allowed when providing valid username and password

2. The connection will be allowed when the device ID used belongs to the username used

3. The first member of any published topic must be a valid Id from one of the devices from the username used

4. You must avoid sending the reserved topics too often every 500 ms is fine, but in general, avoid to put them in infinite for loops without delays.

The devices that don't follow these rules are automatically disconnected and blocked by the system, the first block is for 1 minute, the second is for 5 minutes, the third is for 10 minutes and so on.

If a device is reset it will take about 20 seconds for the server to note the change and allow the reconnection.