OPENHAB MQTT Binding

Post date: May 01, 2015 10:1:13 AM

Documentation of the MQTT binding Bundle

Introduction

The MQTT binding bundle is available as a separate (optional) download. This binding allows openHAB to act as an MQTT client, so that openHAB items can send and receiveMQTT messages to/from an MQTT broker. It does not provide MQTT broker functionality, for this you may want to have a look at Mosquitto. There are test servers available at m2m.eclipse.org and test.mosquitto.org. To install, place this bundle in the folder ${openhab_home}/addons and add binding information to your configuration. See the following sections on how to do this.

OpenHAB provides MQTT support on different levels. The table below gives a quick overview:

The Mqttitude binding is also available which is an extension of this binding.

Configuration

Transport Configuration

In order to consume or publish messages to an MQTT broker, you need to define all the brokers which you want to connect to, in your openhab.cfg file. The following properties can be configured to define a broker connection:

mqtt:<broker>.url=<url> mqtt:<broker>.clientId=<clientId> mqtt:<broker>.user=<user> mqtt:<broker>.pwd=<password> mqtt:<broker>.qos=<qos> mqtt:<broker>.retain=<retain> mqtt:<broker>.async=<async>

The properties indicated by <...> need to be replaced with an actual value. The table below lists the meaning of the different properties.

Example Configurations

Example configuration of a simple broker connection:

mqtt:m2m-eclipse.url=tcp://m2m.eclipse.org:1883

Example configuration of a encrypted broker connection with authentication:

mqtt:mosquitto.url=ssl://test.mosquitto.org:8883 mqtt:mosquitto.user=administrator mqtt:mosquitto.pwd=mysecret mqtt:mosquitto.qos=1 mqtt:mosquitto.retain=true mqtt:mosquitto.async=false

Item Binding Configuration for Inbound Messages

Below you can see the structure of the inbound mqtt configuration string. Inbound configurations allow you to receive MQTT messages into an openHAB item. Every item is allowed to have multiple inbound (or outbound) configurations.

Item myItem {mqtt="<direction>[<broker>:<topic>:<type>:<transformer>], <direction>[<broker>:<topic>:<type>:<transformation>], ..."} 

Since 1.6 it is possible to add an optional 5th configuration like:

Item myItem {mqtt="<direction>[<broker>:<topic>:<type>:<transformer>:<regex_filter>], <direction>[<broker>:<topic>:<type>:<transformation>], ..."} 

Example Inbound Configurations

Number temperature {mqtt="<[publicweatherservice:/london-city/temperature:state:default]"} Number waterConsumption {mqtt="<[mybroker:/myHome/watermeter:state:XSLT(parse_water_message.xslt)]"}  Switch doorbell {mqtt="<[mybroker:/myHome/doorbell:command:ON]"} Number mfase1 {mqtt="<[flukso:/sensor/9cf3d75543fa82a4662fe70df5bf4fde/gauge:state:REGEX(.*,(.*),.*)]"}

Item Binding Configuration for Outbound Messages

Below you can see the structure of the outbound mqtt configuration string. Outbound configurations allow you to send an MQTT message when the an openHAB item receives a command or state update.

Item itemName {mqtt="<direction>[<broker>:<topic>:<type>:<trigger>:<transformation>]" }

When the message content for an outbound message is created, the following variables are always replaced with their respective value:

• • ${itemName} : name of the item which triggered the sending

  • ${state} : current state of the item

  • ${command} : command which triggered the sending of the message

Example Outbound Configurations

Switch mySwitch {mqtt=">[mybroker:/myhouse/office/light:command:ON:1],>[mybroker:/myhouse/office/light:command:OFF:0]"} Switch mySwitch {mqtt=">[mybroker:/myhouse/office/light:command:ON:1],>[mybroker:/myhouse/office/light:command:*:Switch ${itemName} was turned ${command}]"}

Event Bus Binding Configuration

In addition to configuring MQTT publish/subscribe options for specific openHAB items, you can also define a generic configuration in the openhab.cfg file which will act on ALL status updates or commands on the openHAB event bus.

The following properties can be used to configure MQTT for the openHAB event bus:

mqtt-eventbus:broker=<broker> mqtt-eventbus:statePublishTopic=<statePublishTopic> mqtt-eventbus:commandPublishTopic=<commandPublishTopic> mqtt-eventbus:stateSubscribeTopic=<stateSubscribeTopic> mqtt-eventbus:commandSubscribeTopic=<commandSubscribeTopic>

The properties indicated by <...> need to be replaced with an actual value. The table below lists the meaning of the different properties.

Example Configurations

Example configuration for a event bus binding, which sends all commands to an MQTT broker and receives status updates from that broker. This scenario could be used for example to link 2 openHAB instances together where the master instance sends all commands to the slave instance and the slave instance sends all status updates back to the master. The example below shows an example configuration for the master node.

mqtt-eventbus:broker=m2m-eclipse mqtt-eventbus:commandPublishTopic=/openHAB/out/${item}/command mqtt-eventbus:stateSubscribeTopic=/openHAB/in/${item}/state

Using the org.openhab.io.transport.mqtt bundle

When the default MQTT binding configuration options are not sufficient for your needs, you can also use the MQTT transport bundle directly from within your own binding.

MqttService

Using the MqttService, your binding can add custom message consumers and publishers to any of the defined MQTT brokers. You don't have to worry about (re)connection issues, all of this is done by the transport.mqtt bundle. The MqttService class is available to your binding through Declarative Services. A good example on how to use the MqttService can be found in the org.openhab.persistence.mqtt bundle.

Eclipse Paho

If the above service doesn't provide all the flexibility you need, you can also use the Eclipse Paho library directly in your binding. To make the library available, it's sufficient to add a dependency to the org.openhab.io.transport.mqtt bundle and to add org.eclipse.paho.client.mqtttv3 to your list of imported packages.

1)  Under /configurations/openhab.cfg   ######################## Mail Action configuration ############################$  mail:hostname=smtp.gmail.com  mail:port=587  mail:username=????? without the @gmail mail:password=?????  mail:from=??? yourname@gmail.com  mail:tls=true      ################################### MQTT Transport ######################################### #  mqtt:mymosquitto.url=tcp://localhost:1883  mqtt:mymosquitto.qos=0  mqtt:mymosquitto.retain=true  mqtt:mymosquitto.async=true   -----------------------------------------------------------------------------------------  2)  Under /configurations/items/demo.items   Switch itm_mailbox "Switch" (ALL)Number itm_mailboxmqtt "Mailbox RSSI [%.1f]" (ALL) {mqtt="<[mymosquitto:4124:state:default]"} Number itm_mailboxcnt "Mail Count [%.1f]" (ALL) {mqtt="<[mymosquitto:4122:state:default]"} DateTime itm_mailbox_time "Mailbox Last Updated [%1$tA, %1$tm/%1$td, %1$tI:%1$tM %1$tp]" Number itm_mailboxbat "Mailbox Battery [%.1f Volt]" (ALL) {mqtt="<[mymosquitto:4123:state:default]"}     ----------------------------------------------------------------------------------- 3)  Under /configurations/sitemap/demo.sitemap          Frame label="Mailbox"         {                 Switch item=itm_mailbox label="Mailbox" mappings=[OFF="Off"]                 Text item=itm_mailbox_time                 Text item=itm_mailboxmqtt                 Text item=itm_mailboxcnt                 Text item=itm_mailboxbat         }   -------------------------------------------------------------------------------- 4)  Under /configurations/rules/demo.rules  rule "send email and talk"         when                 Item itm_mailbox changed from OFF to ON         then                 playSound("aolmail.mp3")                 sendMail("myemailaddress@gmail.com", "subject line here" , "email body text")   end   rule "update mailbox"         when                 Item itm_mailboxmqtt received update         then                 sendCommand(itm_mailbox, ON)                 postUpdate(itm_mailbox_time, new DateTimeType()) end     -------------------------------------------------------------------------------------- END OF CONFIGURATIONS

//OpenHAB Configuration for UberSensor.ino   /* Item Definition Uber sensor Alarms and Notifications Control*/ Switch itm_NAA_auto "Auto Schedule Alarms/Notifications"  Switch itm_uber1_gas_alm_enb "Gas / Smoke Notifer" Switch itm_uber1_flame_alm_enb "Flame Notifier" Switch itm_uber1_bark_alm_enb "Bark Notifier" Switch itm_uber1_pir_alm_enb "Presence Notifier"  Switch itm_uber1_gas_alm_sta "Gas / Smoke Alarm Status" Switch itm_uber1_flame_alm_sta "Flame Alarm Status" Switch itm_uber1_bark_alm_sta "Bark Alarm Status" Switch itm_uber1_pir_alm_sta "PIR Presence Status"  Switch itm_uber1_light_sta "Living Room Light"  DateTime itm_uber1_gas_time "Gas Alarm Time [%1$tA, %1$tm/%1$td, %1$tI:%1$tM %1$tp]" DateTime itm_uber1_flame_time "Flame Alarm Time [%1$tA, %1$tm/%1$td, %1$tI:%1$tM %1$tp]" DateTime itm_uber1_bark_time "Bark Alarm Time [%1$tA, %1$tm/%1$td, %1$tI:%1$tM %1$tp]" DateTime itm_uber1_pir_time "PIR Presence Alarm Time [%1$tA, %1$tm/%1$td, %1$tI:%1$tM %1$tp]"  Number itm_uber1_gas_mqtt "Gas [%.1f]" (ALL) {mqtt="<[mymosquitto:1222:state:default]"} Number itm_uber1_flame_mqtt "Flame [%.1f]" (ALL) {mqtt="<[mymosquitto:1232:state:default]"} Number itm_uber1_pir_mqtt "PIR [%.1f]" (ALL) {mqtt="<[mymosquitto:1242:state:default]"} Number itm_uber1_bark_mqtt "Bark [%.1f]" (ALL) {mqtt="<[mymosquitto:1252:state:default]"} Number itm_uber1_temp_mqtt "Uber Temperature [%.1f]" (ALL) {mqtt="<[mymosquitto:1262:state:default]"} Number itm_uber1_hum_mqtt "Uber Humidity [%.1f]" (ALL) {mqtt="<[mymosquitto:1263:state:default]"} Number itm_uber1_light_mqtt "Light Sensor [%.1f]" (ALL) {mqtt="<[mymosquitto:1272:state:default]"}   ---------------------------------------------------------------------------------   /* Uber sensor rules */ /* -------------  Uber Sensor -------------------- */ rule "Uber Lighs"         when                 Item itm_uber1_light_mqtt received update         then                 if(itm_uber1_light_mqtt.state < 350)                 {                         sendCommand(itm_uber1_light_sta, OFF)                 }                 else                 {                          sendCommand(itm_uber1_light_sta, ON)                 } end   /*-----  uber - gas/smoke ---------- */ rule "Uber gas smoke threshold"         when                 Item itm_uber1_gas_mqtt received update         then                 if((itm_uber1_gas_mqtt.state > 220) && (itm_uber1_gas_alm_enb.state == ON))                 {                         sendCommand(itm_uber1_gas_alm_sta, ON)                 } end  rule "Uber gas smoke response"         when                 Item itm_uber1_gas_alm_sta changed from OFF to ON         then sendMail("ArduinoHomeAutomationOpenHAB@gmail.com", "gas / smoke" , "gas or smoke detected")                 //playSound("ding.mp3")                 postUpdate(itm_uber1_gas_time, new DateTimeType()) end  /* --------- uber flame ---------- */ rule "Uber flame threshold"         when                 Item itm_uber1_flame_mqtt received update         then                 if((itm_uber1_flame_mqtt.state < 900) && (itm_uber1_flame_alm_enb.state == ON))                 {                         sendCommand(itm_uber1_flame_alm_sta, ON)                 } end  rule "Uber flame response"         when                 Item itm_uber1_flame_alm_sta changed from OFF to ON         then                 sendMail("ArduinoHomeAutomationOpenHAB@gmail.com", "fire detected" , "fire detected")                 //playSound("ding.mp3")                 postUpdate(itm_uber1_flame_time, new DateTimeType()) end   /* --------- uber bark ---------- */ rule "Uber bark threshold"         when                 Item itm_uber1_bark_mqtt received update         then                 if(itm_uber1_bark_alm_enb.state == ON)                 {                         sendCommand(itm_uber1_bark_alm_sta, ON)                 } end  rule "Uber bark response"         when                 Item itm_uber1_bark_alm_sta changed from OFF to ON         then                 sendMail("ArduinoHomeAutomationOpenHAB@gmail.com", "bark detected" , "dog barked!!!")                 //playSound("ding.mp3")                 postUpdate(itm_uber1_bark_time, new DateTimeType()) end  /* --------- uber pir ---------- */ rule "Uber pir threshold"         when                 Item itm_uber1_pir_mqtt received update         then                 if(itm_uber1_pir_alm_enb.state == ON)                 {                         sendCommand(itm_uber1_pir_alm_sta, ON)                 } end  rule "Uber pir response"         when                 Item itm_uber1_pir_alm_sta changed from OFF to ON         then                 sendMail("ArduinoHomeAutomationOpenHAB@gmail.com", "pir detected" , "dog pired!!!")                 //playSound("ding.mp3")                 postUpdate(itm_uber1_pir_time, new DateTimeType()) end   -----------------------------------------------------------------     Frame label="Uber Sensor" {             Text item=itm_uber1_temp_mqtt             Text item=itm_uber1_hum_mqtt             Switch item=itm_uber1_light_sta             Switch item=itm_NAA_auto     }     Frame label="Uber Sensor Alarm Status" {             Switch item=itm_uber1_gas_alm_sta mappings=[OFF="Off"]             Switch item=itm_uber1_flame_alm_sta mappings=[OFF="Off"]             Switch item=itm_uber1_bark_alm_sta mappings=[OFF="Off"]             Switch item=itm_uber1_pir_alm_sta mappings=[OFF="Off"]     }     Frame label="Uber Sensor Alarm Enable" {             Switch item=itm_uber1_gas_alm_enb             Switch item=itm_uber1_flame_alm_enb             Switch item=itm_uber1_bark_alm_enb             Switch item=itm_uber1_pir_alm_enb     }