From f483c0e50676d6a3b8eb8258daca1115550dd808 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 14 Feb 2021 02:12:22 +0100 Subject: MQTT backend documentation --- backends/mqtt.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 backends/mqtt.md (limited to 'backends/mqtt.md') diff --git a/backends/mqtt.md b/backends/mqtt.md new file mode 100644 index 0000000..895831c --- /dev/null +++ b/backends/mqtt.md @@ -0,0 +1,53 @@ +### The `mqtt` backend + +This backend provides input from and output to an 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) | +| `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 normalised event value. + +Values above the maximum or below the minimum will be clamped. The MIDIMonster will not output values out of those +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. -- cgit v1.2.3 From fca46bef7dd8448216d44f0777f0b5ef31ac5883 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 27 Feb 2021 16:54:06 +0100 Subject: Implement input/output mapping --- backends/mqtt.md | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) (limited to 'backends/mqtt.md') diff --git a/backends/mqtt.md b/backends/mqtt.md index 895831c..6623438 100644 --- a/backends/mqtt.md +++ b/backends/mqtt.md @@ -30,10 +30,42 @@ The MQTT protocol places very few restrictions on the exchanged data. Thus, it i 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 normalised event value. +point number between `0.0` and `1.0`. The MIDIMonster will read these and use the value as the normalized event value. -Values above the maximum or below the minimum will be clamped. The MIDIMonster will not output values out of those -bounds. +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 + +``` + = range + = discrete [!] [!] +``` + +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 `` and `` 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 -- cgit v1.2.3 From 921ce069a4770fbadad7bb4e806361e857469409 Mon Sep 17 00:00:00 2001 From: cbdev Date: Mon, 21 Jun 2021 22:03:17 +0200 Subject: Repository cleanup --- backends/mqtt.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'backends/mqtt.md') diff --git a/backends/mqtt.md b/backends/mqtt.md index 6623438..85784ef 100644 --- a/backends/mqtt.md +++ b/backends/mqtt.md @@ -1,6 +1,6 @@ ### The `mqtt` backend -This backend provides input from and output to an message queueing telemetry transport (MQTT) +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. @@ -18,7 +18,7 @@ This backend does not take any global configuration. | `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) | +| `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]`. -- cgit v1.2.3