flow3r-openhab/README.md

# flow3r-openhab

An app for the CCCamp 2023 [flow3r][flow3r] badge that submits detected touch gestures to an MQTT broker.

I wrote this so that the flow3r can be used as a remote control for
OpenHAB (which subscribes to the MQTT broker), but it should be usable
with other subscribers as well.

## Installation

1. Copy `flow3r_openhab/config.example.json` to `flow3r_openhab/config.json` and enter your configuration details.
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`.

Each event is a JSON string that looks like this:

```json
{"mode":"Numbers","petal":"2","event":"touch_tip","dx":8083,"dy":6960,"duration":150}
```

The keys and their values are defined as follows:

| Key | Value |
|:---|:---|
| `mode` | The mode that has been set via the `ui_config` topic, see "UI Config" below. |
| `petal` | The petal the event was detected on.  Uses the numbers printed on the PCB (1-10), rather than the `captouch` indexes (0-9). |
| `event` | The type of gesture that was detected.  One of `touch_tip`, `touch_base`, `swipe_up`, `swipe_right`, `swipe_down`, `swipe_left`, whereas `swipe_up` always means a swipe towards the tip of the petal, and `swipe_down` towards its base. |
| `dx` | The distance between start and end of the touch event in `x` (base-to-tip) direction.  Unitless number, as returned by [captouch's `position()` function][captouch]. |
| `dy` | The distance between start and end of the touch event in `y` (side-to-side) direction. |
| `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
{
  "mode": "Numbers",
  "labels": ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"]
}
```

* `labels`: 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.
* `mode`: The text is shown in big in the center of the display.  It is also sent with each event, so that subscribers can perform differnt actions depending on the active mode.


## 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: '{"labels":["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" && payload.duration > 1000) {
          console.log("longpress!");
        }
```


## License

MIT License

[flow3r]: https://flow3r.garden/
[captouch]: https://docs.flow3r.garden/api/captouch.html#captouch.CaptouchPetalState.position