diff options
| -rw-r--r-- | backends/mqtt.c | 8 | ||||
| -rw-r--r-- | backends/mqtt.md | 53 |
2 files changed, 59 insertions, 2 deletions
diff --git a/backends/mqtt.c b/backends/mqtt.c index 29f0436..41fa772 100644 --- a/backends/mqtt.c +++ b/backends/mqtt.c @@ -580,7 +580,7 @@ static int mqtt_maintenance(){ static int mqtt_handle_publish(instance* inst, uint8_t type, uint8_t* variable_header, size_t length){ mqtt_instance_data* data = (mqtt_instance_data*) inst->impl; - char* topic = NULL, *payload = NULL; + char* topic = NULL, *payload = NULL, *conversion_end = NULL; channel* changed = NULL; channel_value val; uint8_t qos = (type & 0x06) >> 1, content_utf8 = 0; @@ -647,7 +647,11 @@ static int mqtt_handle_publish(instance* inst, uint8_t type, uint8_t* variable_h //FIXME implement input mappings changed = mm_channel(inst, u, 0); if(changed){ - val.normalised = strtod(payload, NULL); + val.normalised = clamp(strtod(payload, &conversion_end), 1.0, 0.0); + if(payload == conversion_end){ + LOGPF("Failed to parse incoming data for %s.%s", inst->name, data->channel[u].topic); + return 0; + } mm_channel_event(changed, val); } } 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. |