From b7874f3cfb4d31b130cb02ee32fe3a43adb059fa Mon Sep 17 00:00:00 2001 From: Markus Storm Date: Sat, 17 Jul 2021 23:53:29 +0200 Subject: [PATCH] [mqtt] add .things example to bindings docs (#11007) * 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 --- .../README.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/bundles/org.openhab.binding.mqtt.generic/README.md b/bundles/org.openhab.binding.mqtt.generic/README.md index d96c92683b048..1d89049cf954d 100644 --- a/bundles/org.openhab.binding.mqtt.generic/README.md +++ b/bundles/org.openhab.binding.mqtt.generic/README.md @@ -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.