Post date: May 01, 2015 10:1:13 AM
Documentation of the MQTT binding Bundle
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.
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 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
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>], ..."}
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(.*,(.*),.*)]"}
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
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}]"}
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 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
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.
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.
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 }