Setup MQTT support to connect external devices

引言

系统架构

MQTT [1] is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. MQTT provides a publish/subscribe message pattern to provide one-to-many message distribution and decoupling of applications.

Node.js [2] is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications.

Node-RED [3] is a tool running in the Node.js platform providing a browser-based flow editor that makes it easy to wire together "flows". Flows can be then deployed to the runtime in a single-click.

Domoticz supports a number of hardware devices natively (rfxtrx433, zwave, smartmeter etc.). There are zillions of other devices out there, with a lot of interfaces. Using it's native MQTT interface Domoticz can publish events from inside to the outside world. Domoticz can also respond to actions requested by anyone (and passed on by the MQTT-broker). Now something has to take care of creating and interpreting these messages.

The Node-RED tool provides an alternative way to creating little programs (flows) to interface with anything you want. But maybe your application can create MQTT-messages on it's own that can be understood by Domoticz. Or maybe you like to create programs in Node.js itself. So using Node-RED is not mandatory, it does however provide a fun and attractive way to handle messages.

If you don't want to use MQTT it's also possible to use the internal LUA-engine of Domoticz (for instance using the commandArray['OpenURL'] functionality). So it also depends on your needs and preferences.

你需要做好的准备

• Domoticz running on a Raspberry Pi (Windows or Mac are supported but this tutorial focusses on a Pi)
• Node.JS (we'll install that later)
• Node-RED (we'll install that later)
• A MQTT broker (we'll install that later)
• A few Node-RED example Flows
• Add 'virtual' hardware to Domoticz: "Create a MQTT Client Gateway with LAN interface" (on localhost)

Installing software

Please note that the current Domoticz SDCard image has this included, and you do not need to install any software.

安装 Node.JS

1. NOTE: Do you need this, since node.red instalation later removes old node.js and npm and installs newer ones ?
2. Please follow the instructions to install nodejs.
3. After that, install some modules using the Node Package Manager:
   

sudo npm install -g mqtt url request

If you want to debug or auto-reload of the script, also install nodemon:

sudo npm install -g nodemon

...

安装 Mosquitto

It is highly recommended that if you are using Debian or Rasbian that you use the additional Mosquitto repositories. This will ensure you get the latest stable version of Mosquitto as determined by the project itself, rather than an outdated version via the Debian or Raspbian repositories.

Rather than re-iterating the install procedure here, the guide given at http://mosquitto.org/2013/01/mosquitto-debian-repository/ is simple and easy to follow, and we encourage you to give their process a shot.

安装 Node-RED

Instructions can be found here: [4]

Node-RED should now be available on HTTP port 1880

添加硬件 "MQTT Client Gateway"

Domoticz needs to subscribe to the Mosquitto MQTT message broker that is now running locally. Under Setup/Hardware add a device of type: "MQTT Client Gateway with LAN interface" with settings:

• Data Timeout: Disabled
• Remote Address: localhost
• Port: 1883
• Username: empty
• Password: empty

To finish press 'Add'.

To test if Domoticz receives data, create a Dummy Virtual temperature sensor.

• Under Setup/Hardware add a device of type: "Dummy (Does nothing, use for virtual switches only)" with the name of your choice ("Dummy" for example).
• In the corresponding entry of your just created "Dummy" hardware, click the "Create Virtual Sensors" button that appear following his type. Then enter the name of your choice (Let's say "Fictive Temp").
• Under Setup/Devices, get the "idx" number of your "Fictive Temp" device (Let's say it's 1).

Then publish a temperature measurement to the virtual sensor idx noted above (example idx 1) like:

mosquitto_pub -h localhost -m '{ "idx" : 1, "nvalue" : 0, "svalue" : "25.0" }' -t 'domoticz/in'

If the mosquitto_pub command is not found install the mosquitto client:

sudo apt-get install mosquitto-clients

可用的 MQTT 应用

Owntracks

Owntracks ([owntracks.org]) is an app (both Android and iPhone) which periodicaly sends the location of a device to a mqtt-broker (e.g. mosquitto). A Node-RED script could subscribe to the owntracks-topic and republish the info in a Domoticz compatible message so Domoticz can use the location info.

Domoticz与MQTT的通信

Communication from and to Domoticz works via JSON. Default MQTT topics of the Domoticz for incoming and outcoming messages are:

  domoticz/in
  domoticz/out

Domoticz 到 MQTT

{
 "idx" : 5,
 "name" : "Internal Temperature",
 "id" : "00080A",
 "unit" : 1 
 "dtype" : "Temp",
 "stype" : "TFA 30.3133",
 "nvalue" : 0,
 "svalue1" : "41.2",
 "Battery" : 100,
 "RSSI" : 12,
}

{
 "idx" : 7,
 "name" : "S0 P1",
 "id" : "123456",
 "unit" : 0
 "dtype" : "Energy",
 "stype" : "CM119 / CM160",
 "nvalue" : 0,
 "svalue1" : "90",
 "svalue2" : "2975.00",
 "Battery" : 100,
 "RSSI" : 12,
}

The format is compatible as described in Domoticz_API/JSON_URL's wiki page, except the "svalue" is split into multiple parts for easier parsing

MQTT 到 Domoticz

The format is compatible as described in the JSON wiki.

Update devices/sensors

Note: If "command" is not set, it defaults to "udevice", the two following messages are equivalent:

{
 "command": "udevice",
 "idx" : 7,
 "nvalue" : 0,
 "svalue" : "90;2975.00"
}

{
 "idx" : 7,
 "nvalue" : 0,
 "svalue" : "90;2975.00"
}

Sending a Switch Command

{"command": "switchlight", "idx": 2450, "switchcmd": "On" }
{"command": "switchlight", "idx": 2450, "switchcmd": "Set Level", "level": 100 }
{"command": "setcolbrightnessvalue", "idx": 2450, "hue": 274, "brightness": 40, "iswhite"=false }
{"command": "setcolbrightnessvalue", "idx": 2450, "hex": "RRGGBB", "brightness": 100, "iswhite"=false }
{"command": "setcolbrightnessvalue", "idx": 2450, "color": {"m":3,"t":0,"r":0,"g":0,"b":50,"cw":0,"ww":0}, "brightness": 40}

The options for setcolbrightnessvalue are explained on Domoticz_API/JSON_URL's#Set_a_light_to_a_certain_color_or_color_temperature

Sending a Scene Command

{"command": "switchscene", "idx": 24, "switchcmd": "On" }
{"command": "switchscene", "idx": 24, "switchcmd": "Toggle" }

Sending a Notification

Optional: priority, sound

{"command": "sendnotification", "subject": "My Subject", "body": "My Body", "priority": 0, "sound": "mysound" }

Set a User Variable

{"command": "setuservariable", "idx": 1, "value": "12.3" }

Request Device Info

{"command": "getdeviceinfo", "idx": 2450 }

Request Scene Info

{"command": "getsceneinfo", "idx": 1 }

Log message

{"command" : "addlogmessage", "message" : "MyMessage to log" }

More information & useful links

• Flows: This wiki-page is a collection of node-RED flows specific to Domoticz
• flows.nodered.org here you'll find the official Node-RED library
• MQTT Forum Topic (note: the topic also includes discussions/solutions when Domoticz did not yet have a native MQTT interface so ignore those)
• MyMQTT for Android usefull for reading the MQTT messages during testing.

Native MQTT Libraries

For interacting directly with Domoticz via MQTT.

NodeJS

sudo npm install node-domoticz-mqtt

See: https://www.domoticz.com/forum/viewtopic.php?f=21&t=10190

Python

You may use *paho-mqtt* library to communicate with domoticz MQTT client

sudo pip install paho-mqtt

See: https://pypi.python.org/pypi/paho-mqtt/1.3.1

Arduino

Needed! Please Help.

Here is a good starting point: https://github.com/knolleary/pubsubclient/blob/master/examples/mqtt_basic/mqtt_basic.ino
This project contains an Arduino sketch for a sonoff device with MQTT/Domoticz compatibility: https://github.com/arendst/Sonoff-MQTT-OTA-Arduino