Skip to content

Commit

Permalink
[mqtt] add .things example to bindings docs (#11007)
Browse files Browse the repository at this point in the history
* Add .things example

based https://www.openhab.org/blog/2018-12-16-mqtt-arrives-in-the-modern-openhab-2-x-architecture.html

* removed bad copy'n'pasted sentence
  • Loading branch information
mstormi authored Jul 17, 2021
1 parent 932e313 commit e01532b
Showing 1 changed file with 35 additions and 0 deletions.
35 changes: 35 additions & 0 deletions bundles/org.openhab.binding.mqtt.generic/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,41 @@ mqttActions.publishMQTT("mytopic","myvalue", true)

The retained argument is optional and if not supplied defaults to `false`.

## Configuration via Text Files

*broker.things* file:

```
mqtt:broker:mySecureBroker [ host="192.168.0.41", secure=true, certificatepin=true, publickeypin=true ]
mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ]
mqtt:broker:myAuthentificatedBroker [ host="192.168.0.43",secure=true, username="user", password="password" ]
mqtt:broker:pinToPublicKey [ host="192.168.0.44", secure=true , publickeypin=true, publickey="SHA-256:9a6f30e67ae9723579da2575c35daf7da3b370b04ac0bde031f5e1f5e4617eb8" ]
```

In the first example a secure connection to a broker is defined. It pins the returned certificate and public key. If someone tries a man in the middle attack later on, this broker connection will recognize it and refuse a connection. Be aware that if your brokers certificate changes, you need to remove the connection entry and add it again.
The second connection is a plain, unsecured one. Use this only for local MQTT Brokers.
A third connection uses a username and password for authentication. The credentials are plain values on the wire, therefore you should only use this on a secure connection.
In a fourth connection, the public key pinning is enabled again. This time, a public key hash is provided to pin the connection to a specific server. It follows the form "hashname:hashvalue". Valid hashnames are SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 and all others listed in Java MessageDigest Algorithms.

### Example

Files can also be used to create topic things and channels and to combine them with a broker connection:

*mqtt.things* file:

```
Bridge mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ]
Thing mqtt:topic:mything "mything" (mqtt:broker:myUnsecureBroker) {
Channels:
Type switch : lamp "Kitchen Lamp" [ stateTopic="lamp/enabled", commandTopic="lamp/enabled/set" ]
Type switch : fancylamp "Fancy Lamp" [ stateTopic="fancy/lamp/state", commandTopic="fancy/lamp/command", on="i-am-on", off="i-am-off" ]
Type string : alarmpanel "Alarm system" [ stateTopic="alarm/panel/state", commandTopic="alarm/panel/set", allowedStates="ARMED_HOME,ARMED_AWAY,UNARMED" ]
Type color : lampcolor "Kitchen Lamp color" [ stateTopic="lamp/color", commandTopic="lamp/color/set", rgb=true ]
Type dimmer : blind "Blind" [ stateTopic="blind/state", commandTopic="blind/set", min=0, max=5, step=1 ]
}
```

## Limitations

* The HomeAssistant Fan Components only support ON/OFF.
Expand Down

0 comments on commit e01532b

Please sign in to comment.