documentation

README.md

@@ -12,6 +12,12 @@ with other subscribers as well.
 1. Copy the `flow3r_openhab` directory to `/sys/apps/flow3r_openhab` on the flow3r's flash filesystem.
 1. Reboot the flow3r and start the `OpenHAB` app
 
+## MQTT Topics
+
+* `flow3r-<macaddress>/event`: The app publishes events to this topic. see "Events" below.
+* `flow3r-<macaddress>/status`: The app publishes the string `Online` to this topic when started, and submits an `Offline` LWT message.
+* `flow3r-<macaddress>/ui_config`: You can publish a label for each petal to this topic, which will be shown on the flow3r's display. See "UI Config" below.
+
 ## Events
 
 The touch events detected by the flow3r are published to the topic `flow3r-<macaddress>/event`.
@@ -33,6 +39,88 @@ The keys and their values are defined as follows:
 | `duration` | The duration between start and end of the touch event in `ms`. |
 
 
+## UI Config
+
+The app subscribes to the topic `flow3r-<macaddress>/ui_config`, at which it listens for JSON arrays such as below:
+
+```json
+["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"]
+```
+
+Each position in the array corrensponds to one of the petals, and the text for each petal is shown on the display close to the corresponding petal.
+
+
+## Integration into OpenHAB
+
+The following is an example of how this can be integrated into OpenHAB.
+
+The recommended `Thing` definition is as follows:
+
+```yaml
+label: flow3r
+thingTypeUID: mqtt:topic
+configuration:
+  availabilityTopic: flow3r-<macaddress>/status
+  payloadNotAvailable: Offline
+  payloadAvailable: Online
+channels:
+  - id: event
+    channelTypeUID: mqtt:trigger
+    label: Event
+    configuration:
+      stateTopic: flow3r-<macaddress>/event
+  - id: ui_config
+    channelTypeUID: mqtt:string
+    label: UI Config
+    configuration:
+      commandTopic: flow3r-<macaddress>/ui_config
+```
+
+The UI Config can be performed easiest by creating a rule that is triggered by the `Online` message on the status topic:
+
+```yaml
+configuration: {}
+triggers:
+  - id: "1"
+    configuration:
+      thingUID: mqtt:topic:...
+      status: ONLINE
+    type: core.ThingStatusUpdateTrigger
+conditions: []
+actions:
+  - inputs: {}
+    id: "2"
+    configuration:
+      itemName: flow3r_ui_config  # item needs to be created and linked to the ui_config topic beforehand
+      command: '["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"]'
+    type: core.ItemCommandAction
+```
+
+For handling touch gestures, another rule can be created; the example below runs a JS script that parses the JSON payload and reacts on a long press on petal 10:
+
+```yaml
+configuration: {}
+triggers:
+  - id: "1"
+    configuration:
+      thingUID: mqtt:topic:...
+      channelUID: mqtt:topic:...:event
+    type: core.ChannelEventTrigger
+conditions: []
+actions:
+  - inputs: {}
+    id: "2"
+    type: script.ScriptAction
+    configuration:
+      type: application/javascript
+      script: >-
+        var payload = JSON.parse(this.event.event);
+		if (payload.petal == "10" and payload.duration > 1000) {
+		  console.log("longpress!");
+		}
+```
+
+
 ## License
 
 MIT License