aboutsummaryrefslogtreecommitdiffhomepage
path: root/backends/mqtt.md
diff options
context:
space:
mode:
authorcbdev <cb@cbcdn.com>2021-06-30 03:03:48 +0200
committercbdev <cb@cbcdn.com>2021-06-30 03:03:48 +0200
commitbc3d80e9e6c038c87a64432586670c663a23e53d (patch)
tree5a28b0004a7f3492455316f34bb2c783e670f944 /backends/mqtt.md
parent8a0a413f1dd5593189dd6b651babcff9b2495451 (diff)
parentf16f7db86662fcdbf45b6373257c90c824b0b4b0 (diff)
downloadmidimonster-bc3d80e9e6c038c87a64432586670c663a23e53d.tar.gz
midimonster-bc3d80e9e6c038c87a64432586670c663a23e53d.tar.bz2
midimonster-bc3d80e9e6c038c87a64432586670c663a23e53d.zip
Merge branch 'master' into debian/master
Diffstat (limited to 'backends/mqtt.md')
-rw-r--r--backends/mqtt.md85
1 files changed, 85 insertions, 0 deletions
diff --git a/backends/mqtt.md b/backends/mqtt.md
new file mode 100644
index 0000000..85784ef
--- /dev/null
+++ b/backends/mqtt.md
@@ -0,0 +1,85 @@
+### The `mqtt` backend
+
+This backend provides input from and output to a message queueing telemetry transport (MQTT)
+broker. The MQTT protocol is used in lightweight sensor/actor applications, a wide selection
+of smart home implementations and as a generic message bus in many other domains.
+
+The backend implements both the older protocol version MQTT v3.1.1 as well as the current specification
+for MQTT v5.0.
+
+#### Global configuration
+
+This backend does not take any global configuration.
+
+#### Instance configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|---------------------------------------|
+| `host` | `mqtt://10.23.23.1` | none | Host or URI of the MQTT broker |
+| `user` | `midimonster` | none | User name for broker authentication |
+| `password` | `mm` | none | Password for broker authentication |
+| `clientid` | `MM-main` | random | MQTT client identifier (generated randomly at start if unset) |
+| `protocol` | `3.1.1` | `5` | MQTT protocol version (`5` or `3.1.1`) to use for the connection |
+
+The `host` option can be specified as an URI of the form `mqtt[s]://[username][:password]@host.domain[:port]`.
+This allows specifying all necessary settings in one configuration option.
+
+#### Data exchange format
+
+The MQTT protocol places very few restrictions on the exchanged data. Thus, it is necessary to specify the input
+and output data formats accepted respectively output by the MIDIMonster.
+
+The basic format, without further channel-specific configuration, is an ASCII/UTF-8 string representing a floating
+point number between `0.0` and `1.0`. The MIDIMonster will read these and use the value as the normalized event value.
+
+Channels may be specified to use a different value range or even freeform discrete values by preconfiguring
+the channels in the instance configuration section. This is done by specifying options of the form
+
+```
+<channel> = range <min> <max>
+<channel> = discrete [!]<min> [!]<max> <value>
+```
+
+Example configurations:
+```
+/a/topic = range -10 10
+/another/topic = discrete !0.0 0.5 off
+/another/topic = discrete 0.5 !1.0 on
+```
+
+Note that there may be only one range configuration per topic, but there may be multiple discrete configurations.
+
+The first channel preconfiguration example will change the channel value scale to values between `-10` and `10`.
+For input channels, this sets the normalization range. The MIDIMonster will normalize the input value according to the scale.
+For output channels, this sets the output scaling factors.
+
+The second and third channel preconfigurations define two discrete values (`on` and `off`) with accompanying normalized
+values. For input channels, the normalized channel value for a discrete input will be the value marked with an exclamation mark `!`.
+For output channels, the output will be the first discrete value for which the range between `<min>` and `<max>` contains
+the normalized channel value.
+
+These examples mean
+* For `/a/topic`, when mapped as input, the input value `5.0` will generate a normalized event value of `0.75`.
+* For `/a/topic`, when mapped as output, a normalized event value `0.25` will generate an output of `-5.0`.
+* For `/another/topic`, when mapped as an input, the input value `off` will generate a normalized event value of `0.0`.
+* For `/another/topic`, when mapped as an output, a normalized event value of `0.75` will generate an output of `on`.
+
+Values above the maximum or below the minimum will be clamped. The MIDIMonster will not output values out of the
+configured bounds.
+
+#### Channel specification
+
+A channel specification may be any MQTT topic designator not containing the wildcard characters `+` and `#`.
+
+Example mapping:
+```
+mq1./midimonster/in > mq2./midimonster/out
+```
+
+#### Known bugs / problems
+
+If the connection to a server is lost, the connection will be retried in approximately 10 seconds.
+If the server rejects the connection with reason code `0x01`, a protocol failure is assumed. If the initial
+connection was made with `MQTT v5.0`, it is retried with the older protocol version `MQTT v3.1.1`.
+
+Support for TLS-secured connections is planned, but not yet implemented.