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.

The mqtt backend¶