- Table of contents
As of release 1.0.013 of December 2013, Domotiga has support for MQTT. It can connect to a broker and publish data and subscribe to incoming data.
What is MQTT¶
MQTT (Message Queue Telemetry Transport) is a publish-subscribe based "light weight" messaging protocol for use on top of the TCP/IP protocol. MQTT for Sensor Networks (MQTT-SN) is a version of MQTT aimed at embedded devices on sensor networks, for example Zigbee and extends the MQTT protocol for wireless sensor networks (WSN).
The MQTT and MQTT-SN protocol specs can be found at the MQTT.org website.
You can enable MQTT support using Modules -> Publish Data -> MQTT:
The TCP Host and TCP port specify the address and port of the MQTT broker. 1883 is the official port used for MQTT.
The Client name specifies a unique client identifier. Client name must be specified and be less that 65535 characters. It must be unique across all clients connecting to the same server. The client name is used by the server to store data related to the client, hence it is important that the client name remain the same when connecting to a server if durable subscriptions or reliable messaging are required.
The User name and Password as used to log into the MQTT broker
The Publish and Subscr Topic fields give respectively the topic under which the MQTT plugin will publish it's data and the topic under which the MQTT plugin will get the data you want it to be subscribed to.
The Heartbeat specifies the interval Domotiga will sends as maxInactivityDuration to the broker and the interval Domotiga will send keep alive message <== Check!
Retain messages specifies <please fill in>
QoS can have three levels:
0 - Messages are delivered once, with no confirmation.
1 - Messages are at least delivered once, with confirmation required.
2 - Messages are delivered once but by using a four step handshake.
Installing MQTT doesn't have to be hard. There's are pre-compiled binaries for all major Linux distributions including Raspberry Pi and Windows and source code on http://mosquitto.org/download/. For Raspberry Pi, you do not need to add a specific repository as is described on the site but you can you do:
sudo apt-get install mosquitto mosquitto-clients
Once it's installed, you can do a couple of very simple tests to see if everything is up & running:
The broker (mosquitto) is automatically started after install.
Start a test publish.
In a shell, subscribe (in debug mode) to all messages sent to hello/world:
mosquitto_sub -d -t hello/world
Let's publish (send) in yet another shell a message to there and see if it works:
mosquitto_pub -d -t hello/world -m "Hello, MQTT. Just testing"
The subscriber should now show something like:
@ mosquitto_sub -d -t hello/world Client mosqsub/1547-raspberryp sending CONNECT Client mosqsub/1547-raspberryp received CONNACK Client mosqsub/1547-raspberryp sending SUBSCRIBE (Mid: 1, Topic: hello/world, QoS: 0) Client mosqsub/1547-raspberryp received SUBACK Subscribed (mid: 1): 0 Client mosqsub/1547-raspberryp received PUBLISH (d0, q0, r0, m0, 'hello/world', ... (25 bytes)) Hello, MQTT. Just testing@
With Domotiga publishing values¶
- Start the mosquitto broker
- Configure the MQTT Plugin to connect to the mosquitto broker as detailed by Configuration above.
- Check after configuration the Main log (be sure to check the Server Main log if you run a Client-Server setup)
- You want to see:
15:03:30 [Plugin] MQTT Client, Instance #1 enabled. 15:03:30 [MQTT] MQTT Client TCP interface connecting to broker 127.0.0.1:1883 15:03:30 [MQTT] TCP interface connected.
- And not:
14:05:15 [MQTT] MQTT Client TCP interface connecting to broker 172.20.0.55:1883 14:06:19 [MQTT] ERROR: Unable to connect. Connection refused. 14:06:26 [MQTT] MQTT Client TCP Server closed. ... 15:02:42 [MQTT] MQTT Client TCP interface connecting to Server localhost:1883 15:02:42 [MQTT] ERROR: Host 'localhost' not found. 15:03:30 [MQTT] MQTT Client TCP Server closed.
- You want to see:
- If publishing is taking is taking place and you have enabled 'Debug', you should see in the debug log something like:
15:21:54 [Devices] Device change triggered for device with id '71' and value1 '29.6' 15:21:54 [MQTT] Publishing Message '29.6' to Topic 'domotiga/Temperatuur buiten/value1' 15:21:54 [MQTT] > 30 28 00 22 64 6F 6D 6F 74 69 67 61 2F 54 65 6D 70 65 72 61 74 75 ...
- And if you start a subscriber:
$ mosquitto_sub -d -t domotiga/# Received CONNACK Received SUBACK Subscribed (mid: 1): 0 Sending PINGREQ Received PINGRESP Received PUBLISH (d0, q0, r0, m0, 'domotiga/Temperatuur woonkamer/value1', ... (2 bytes)) 26
With Domotiga receiving values¶
If you have configured the Subscr Topic in the setup to the default settings, "raw/#" (meaning all topics that start with raw/) you can publish a message and have Domotiga handle it:
$ mosquitto_pub -d -t raw/test -m "This is a test" Received CONNACK Sending PUBLISH (d0, q0, r0, m1, 'raw/test', ... (14 bytes))
If you did not configure anything but enabled Debug for MQTT and Devices and Auto Device Create, you will see in your debug log:
2014/07/29 15:30:51 [MQTT] < 30 18 00 08 72 61 77 2F 74 65 73 74 54 68 69 73 20 69 73 20 61 20 74 65 73 74 2014/07/29 15:30:51 [MQTT] Received published data. 2014/07/29 15:30:51 [MQTT] Received topic : raw/test 2014/07/29 15:30:51 [MQTT] Received message : This is a test 2014/07/29 15:30:51 [Devices] Interface with name 'MQTT Interface' has id '50' 2014/07/29 15:30:51 [Devices] Device of type 'Unknown' with address 'raw/test' and interface 'MQTT Interface' not found! 2014/07/29 15:30:51 [Devices] Auto create device 'Unknown device #1' failed, because of unknown type! 2014/07/29 15:30:51 [Devices] Please report device type 'Unknown' with address 'raw/test' and interface 'MQTT Interface' (50) to email@example.com
If you want to share your values with the world wide web, or do a quick test, you can also decide to sign up for a free account at CloudMQTT.
Their 'Cute Cat plan' allows 10 connections and 10Kbit/s of bandwidth.
Simply create an account and fill in the server name, port number, username and password in DomotiGa's MQTT settings.
This has the advantage that you don't have to open up and forward an incoming port on your firewall, or configure SSL.
If you want to check if your data arrives, install only the mosquitto mqtt client package and run:
$ mosquitto_sub -h <servername like m20.cloudmqtt.com> -u <user> -P <password> -p <port> -v -t "domotiga/#" domotiga/Power Usage/value1 670476 domotiga/Smoke Detector Temp/value1 24.50 domotiga/Power Usage/value1 670490 domotiga/Temp Sensor1/value1 23.28 domotiga/Temp Sensor2/value1 24.88 domotiga/Temp Sensor3/value1 23.36 domotiga/Temp Sensor4/value1 23.28 domotiga/Smoke Detector Battery Level/value1 8.61
Owntracks is an App that can inform DomotiGa on where you/your smartphone is so that based on that you can for example switch on/off the light and/or the heating. Owntracks works via MQTT, for more details see the Owntracks wiki.
The data published by Domotiga can be used to create a real-time website with websockets to display it all.