-
Notifications
You must be signed in to change notification settings - Fork 0
MQTT Binding
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 receive MQTT 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 or use sudo apt-get install openhab-addon-binding-mqtt
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:
Level | Description | Usage | Bundle |
Transport | Shared transport functions for setting up MQTT broker connections. | Ideal if you want to roll your own binding using MQTT as the transport. | o.o.io.transport.mqtt |
Item binding | Allows MQTT publish/subscribe configuration on item level | Ideal for highly customized in and outbound message scenarios. | o.o.binding.mqtt |
Event bus binding | Publish/receive all states/commmands directly on the openHAB eventbus. | Perfect for integrating multiple openHAB instances or broadcasting all events. | o.o.binding.mqtt |
Persistence | Uses persistent strategies to push messages on change or a regular interval. | Perfect for persisting time series to a public service like Xively. (See MQTT persistence.) | o.o.persistence.mqtt |
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>
mqtt:<broker>.keepAlive=<keepAlive>
The properties indicated by <...>
need to be replaced with an actual value. The table below lists the meaning of the different properties.
Property | Description |
broker | Alias name for the MQTT broker. This is the name you can use in the item binding configurations afterwards. |
url | URL to the MQTT broker, e.g. tcp://localhost:1883 or ssl://localhost:8883 |
clientId | Optional. Client id (max 23 chars) to use when connecting to the broker. If not provided a default one is generated. |
user | Optional. User id to authenticate with the broker. |
pwd | Optional. Password to authenticate with the broker. |
qos | Optional. Set the quality of service level for sending messages to this broker. Possible values are 0 (Deliver at most once),1 (Deliver at least once) or 2 (Deliver exactly once). Defaults to 0. |
retain | Optional. True or false. Defines if the broker should retain the messages sent to it. Defaults to false. |
async | Optional. True or false. Defines if messages are published asynchronously or synchronously. Defaults to true. |
keepAlive | Optional. Integer. Defines the keep alive interval in seconds. Defaults to 60. |
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>], ..."}
Property | Description |
direction | This is always "<" for inbound messages. |
broker | The broker alias as it is defined in the openHab configuration. |
topic | The MQTT Topic to subscribe to. |
type | Describes what the message content contains: a status update or command. Allowed values are 'state' or 'command'. |
transformation | Rule defining how to transform the received message content into something openHab recognizes. Transformations are defined in the format of TRANSFORMATION_NAME(transformation_function). Allowed values are 'default' or any of the transformers provided in the org.openhab.core.transform bundle. Custom transformations can be contributed directly to the transform bundle by making the Transformation available through Declarative Services. Any other value than the above types will be interpreted as static text, in which case the actual content of the message is ignored. |
regex_filter(optional, since 1.6) | A string representing a regular expression. Only messages that match this expression will be further processed. All other messages will be dropped. Use Case: If multiple different data is sent over one topic (for example multiple sensors of one device), it is possible to distinguish the messages for different items. Example ".*" will match every message, ".*\"type\"=2\n.*" will match every message including type=2. |
Number temperature "temp [%.1f]" {mqtt="<[publicweatherservice:/london-city/temperature:state:default]"}
Number waterConsumption "consum [%d]" {mqtt="<[mybroker:/myHome/watermeter:state:XSLT(parse_water_message.xslt)]"}
Switch doorbell "bell [%s]" {mqtt="<[mybroker:/myHome/doorbell:command:ON]"}
Number mfase1 "mfase1 [%.3f]" {mqtt="<[flukso:/sensor/9cf3d75543fa82a4662fe70df5bf4fde/gauge:state:REGEX(.*,(.*),.*)]"}
Below you can see the structure of the outbound mqtt configuration string. Outbound configurations allow you to publish (send) an MQTT message to the MQTT broker when an item receives a command or state update, and other MQTT clients that are subscribed to the given topic on the same broker, like Arduino devices for example, will receive those messages.
Item itemName { mqtt="<direction>[<broker>:<topic>:<type>:<trigger>:<transformation>]" }
Property | Description |
direction | This is always ">" for outbound messages. |
broker | The broker alias as it was defined in the openHAB configuration. |
topic | The MQTT Topic to publish messages to. |
type | 'state' or 'command'. Indicates whether the receiving of a status update or command triggers the sending of an outbound message. |
trigger | Specifies a specific OpenHAB command or state (e.g. ON, OFF, a DecimalType, ..) which triggers the sending of an outbound message. Use `*` to indicate that any command or state should trigger the sending. |
transformation | Rule defining how to create the message content. Transformations are defined in the format of TRANSFORMATION_NAME(transformation_function). Allowed values are 'default' or any of the transformers provided in the org.openhab.core.transform bundle. Custom transformations can be contributed directly to the transform bundle by making the Transformation available through Declarative Services. Any other value than the above types will be interpreted as static text, in which case this text is used as the message content. |
When the message content for an outbound message is created, the following variables are replaced with their respective value:
- ${itemName} : name of the item which triggered the sending
- ${state} : current state of the item (only for type 'state')
- ${command} : command which triggered the sending of the message (only for type 'command')
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.
Property | Description |
broker | Name of the broker as it is defined in the openhab.cfg. If this property is not available, no event bus MQTT binding will be created. |
statePublishTopic | When available, all status updates which occur on the openHAB event bus are published to the provided topic. The message content will be the status. The variable ${item} will be replaced during publishing with the item name for which the state was received. |
commandPublishTopic | When available, all commands which occur on the openHAB event bus are published to the provided topic. The message content will be the command. The variable ${item} will be replaced during publishing with the item name for which the command was received. |
stateSubscribeTopic | When available, all status updates received on this topic will be posted to the openHAB event bus. The message content is assumed to be a string representation of the status. The topic should include the variable ${item} to indicate which part of the topic contains the item name which can be used for posting the received value to the event bus. |
commandSubscribeTopic | When available, all commands received on this topic will be posted to the openHAB event bus. The message content is assumed to be a string representation of the command. The topic should include the variable ${item} to indicate which part of the topic contains the item name which can be used for posting the received value to the event bus. |
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.
###Windows
###FreeBSD
- Classic UI
- iOS Client
- Android Client
- Windows Phone Client
- GreenT UI
- CometVisu
- Kodi
- Slack
- Chrome Extension
- Cosm Persistence
- db4o Persistence
- Amazon DynamoDB Persistence
- Exec Persistence
- InfluxDB Persistence
- JDBC Persistence
- JPA Persistence
- Logging Persistence
- mapdb Persistence
- MongoDB Persistence
- MQTT Persistence
- my.openHAB Persistence
- MySQL Persistence
- rrd4j Persistence
- Sen.Se Persistence
- SiteWhere Persistence
- AKM868 Binding
- AlarmDecoder Binding
- Anel Binding
- Arduino SmartHome Souliss Binding
- Asterisk Binding
- Astro Binding
- Autelis Pool Control Binding
- BenQ Projector Binding
- Bluetooth Binding
- Bticino Binding
- CalDAV Binding
- Chamberlain MyQ Binding
- Comfo Air Binding
- Config Admin Binding
- CUL Transport
- CUL Intertechno Binding
- CUPS Binding
- DAIKIN Binding
- Davis Binding
- Denon Binding
- digitalSTROM Binding
- DMX512 Binding
- DSC Alarm Binding
- DSMR Binding
- eBUS Binding
- Ecobee Binding
- EDS OWSever Binding
- eKey Binding
- Energenie Binding
- EnOcean Binding
- Enphase Energy Binding
- Epson Projector Binding
- Exec Binding
- Freebox Binding
- Freeswitch Binding
- Frontier Silicon Radio Binding
- Fritz AHA Binding
- Fritz!Box Binding
- FritzBox-TR064-Binding
- FS20 Binding
- Garadget Binding
- Global Caché IR Binding
- GPIO Binding
- HAI/Leviton OmniLink Binding
- HDAnywhere Binding
- Heatmiser Binding
- Homematic / Homegear Binding
- HTTP Binding
- IEC 62056-21 Binding
- IHC / ELKO Binding
- ImperiHome Binding
- Insteon Hub Binding
- Insteon PLM Binding
- IPX800 Binding
- IRtrans Binding
- jointSPACE-Binding
- KNX Binding
- Koubachi Binding
- LCN Binding
- LightwaveRF Binding
- Leviton/HAI Omnilink Binding
- Lg TV Binding
- Logitech Harmony Hub
- MailControl Binding
- MAX!Cube-Binding
- MAX! CUL Binding
- MiLight Binding
- MiOS Binding
- Mochad X10 Binding
- Modbus Binding
- MPD Binding
- MQTT Binding
- MQTTitude binding
- MystromEcoPower Binding
- Neohub Binding
- Nest Binding
- Netatmo Binding
- Network Health Binding
- Network UPS Tools Binding
- Nibe Heatpump Binding
- Nikobus Binding
- Novelan/Luxtronic Heatpump Binding
- NTP Binding
- One-Wire Binding
- Onkyo AV Receiver Binding
- Open Energy Monitor Binding
- OpenPaths presence detection binding
- OpenSprinkler Binding
- OSGi Configuration Admin Binding
- Panasonic TV Binding
- panStamp Binding
- Philips Hue Binding
- Picnet Binding
- Piface Binding
- PiXtend Binding
- pilight Binding
- Pioneer-AVR-Binding
- Plex Binding
- Plugwise Binding
- PLCBus Binding
- Powermax alarm Binding
- Primare Binding
- Pulseaudio Binding
- Raspberry Pi RC Switch Binding
- RFXCOM Binding
- RWE Smarthome Binding
- Sager WeatherCaster Binding
- Samsung AC Binding
- Samsung TV Binding
- Serial Binding
- Sallegra Binding
- Satel Alarm Binding
- SimpleBinary Binding
- Sinthesi Sapp Binding
- Smarthomatic Binding
- Snmp Binding
- Somfy URTSI II Binding
- Sonance Binding
- Sonos Binding
- Souliss Binding
- Squeezebox Binding
- Stiebel Eltron Heatpump
- Swegon ventilation Binding
- System Info Binding
- TA CMI Binding
- TCP/UDP Binding
- Tellstick Binding
- TinkerForge Binding
- Tivo Binding
- UCProjects.eu Relay Board Binding
- VDR Binding
- Velleman-K8055-Binding
- Wago Binding
- Wake-on-LAN Binding
- Waterkotte EcoTouch Heatpump Binding
- Weather Binding
- Wemo Binding
- Withings Binding
- XBMC Binding
- xPL Binding
- Yamahareceiver Binding
- Zibase Binding
- Z-Wave Binding
- Asterisk
- DoorBird
- FIND
- Foscam IP Cameras
- LG Hombot
- Worx Landroid
- Heatmiser PRT Thermostat
- Google Calendar
- Linux Media Players
- Rainforest EAGLE Energy Access Gateway
- Roku Integration
- ROS Robot Operating System
- Telldus Tellstick
- Zoneminder
- Wink Hub (rooted)
- Wink Monitoring
- Transformations
- XSLT
- JSON
- REST-API
- Security
- Service Discovery
- Voice Control
- BritishGasHive-Using-Ruby
- Dropbox Bundle
A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.
Please update the wiki if you do come across any out of date information.
- Rollershutter Bindings
- Squeezebox
- WAC Binding
- WebSolarLog
- Alarm Clock
- Convert Fahrenheit to Celsius
- The mother of all lighting rules
- Reusable Rules via Functions
- Combining different Items
- Items, Rules and more Examples of a SmartHome
- Google Map
- Controlling openHAB with Android
- Usecase examples
- B-Control Manager
- Spell checking for foreign languages
- Flic via Tasker
- Chromecast via castnow
- Speedtest.net integration