mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-11 07:32:11 +01:00
77 lines
5.2 KiB
Markdown
77 lines
5.2 KiB
Markdown
# MQTT Binding
|
|
|
|
> MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol.
|
|
> It was designed as an extremely lightweight publish/subscribe messaging transport.
|
|
|
|
MQTT is a server/client architecture.
|
|
|
|
A server, also called broker is not provided within this binding.
|
|
You can use any of the freely available MQTT Brokers like [Mosquitto](https://mosquitto.org/)
|
|
or [Moquette](https://moquette-io.github.io/moquette/) or install the [included Moquette broker](https://www.openhab.org/addons/integrations/mqttembeddedbroker/) as add-on.
|
|
|
|
This particular binding allows to configure connections to brokers via openHAB Things.
|
|
This binding does NOT allow you to link Channels to MQTT topics or perform auto-discovery of available
|
|
MQTT topics. Please check out the available extensions:
|
|
|
|
<!--list-subs-->
|
|
|
|
## Supported Bridges
|
|
|
|
* Broker: This bridge represents an MQTT Broker connection, configured and managed by this binding.
|
|
* SystemBroker: A system configured broker cannot be changed by this binding and will be listed as read-only system-broker.
|
|
|
|
## Bridge Configuration
|
|
|
|
Required configuration parameters are:
|
|
|
|
* __host__: The IP/Hostname of the MQTT broker. Be aware that this binding allows only one bridge / one connection per unique host:port.
|
|
* __port__: The optional port of the MQTT broker. If none is provided, the typical ports 1883 and 8883 (SSL) are used. Be aware that this binding allows only one bridge / one connection per unique host:port.
|
|
* __secure__: Uses TLS/SSL to establish a secure connection to the broker. Can be true or false. Defaults to false.
|
|
|
|
Additionally the following parameters can be set:
|
|
|
|
* __qos__: Quality of Service. Can be 0, 1 or 2. Please read the MQTT specification for details. Defaults to 0.
|
|
* __clientID__: Use a fixed client ID. Defaults to empty which means a user ID is generated for this connection.
|
|
|
|
Reconnect parameters are:
|
|
|
|
* __reconnectTime__: Reconnect time in ms. If a connection is lost, the binding will wait this time before it tries to reconnect. Defaults to 60000 (60s).
|
|
* __keepAlive__: Keep alive / heartbeat timer in s. It can take up to this time to determine if a server connection is lost. A lower value may keep the broker unnecessarily busy for no or little additional value. Defaults to 60s.
|
|
|
|
An MQTT last will and testament can be configured:
|
|
|
|
* __lwtMessage__: An optional last will and testament message. Defaults to empty.
|
|
* __lwtTopic__: The last will topic. Defaults to empty and therefore disables the last will.
|
|
* __lwtQos__: The optional qos of the last will. Defaults to 0.
|
|
* __lwtRetain__: Retain last will message. Defaults to false.
|
|
|
|
For more security, the following optional parameters can be altered:
|
|
|
|
* __username__: The MQTT username (since MQTT 3.1). Defaults to empty.
|
|
* __password__: The MQTT password (since MQTT 3.1). Defaults to empty.
|
|
* __certificatepin__: If this is set: After the next connection has been successfully established, the certificate is pinned. The connection will be refused if another certificate is used. Clear **certificate** to allow a new certificate for the next connection attempt. This option will increase security.
|
|
* __publickeypin__: If this is set: After the next connection has been successfully established, the public key of the broker is pinned. The connection will be refused if another public key is used. Clear **publickey** to allow a new public key for the next connection attempt. This option will increase security.
|
|
* __certificate__: The certificate hash. If **certificatepin** is set this hash is used to verify the connection. Clear to allow a new certificate pinning on the next connection attempt. If empty will be filled automatically by the next successful connection. An example input would be `SHA-256:83F9171E06A313118889F7D79302BD1B7A2042EE0CFD029ABF8DD06FFA6CD9D3`.
|
|
* __publickey__: The public key hash. If **publickeypin** is set this hash is used to verify the connection. Clear to allow a new public key pinning on the next connection attempt. If empty will be filled automatically by the next successful connection. An example input would be `SHA-256:83F9171E06A313118889F7D79302BD1B7A2042EE0CFD029ABF8DD06FFA6CD9D3`.
|
|
|
|
By default discovery services (like homie or homeassistant) are enabled on a broker.
|
|
This behaviour can be controlled with a configuration parameter.
|
|
|
|
* __enableDiscovery__:If set to true, enables discovery on this broker, if set to false, disables discovery services on this broker.
|
|
|
|
## Supported Channels
|
|
|
|
You can extend your broker connection bridges with a channel:
|
|
|
|
* __publishTrigger__: This channel is triggered when a value is published to the configured MQTT topic on this broker connection. The event payload (in `receivedEvent`) will be the received MQTT topic and its value, separated by the hash character (`#`).
|
|
|
|
Configuration parameters are:
|
|
|
|
* __stateTopic__: This channel will trigger on this MQTT topic. This topic can contain wildcards like + and # for example "all/in/#" or "sensors/+/config".
|
|
* __payload__: An optional condition on the value of the MQTT topic that must match before this channel is triggered.
|
|
|
|
## Legacy MQTT1-Binding
|
|
|
|
This binding is not supposed to run in parallel to the old mqtt1-binding.
|
|
Please uninstall the old binding before installing this binding.
|