MIDI-MT - Smart Home device control module

Managing smart home devices

• MQTT communication protocol support

• Settings for the Smart Home device control module

• Setting up an MQTT connection

  • SSL/TLS - certificate configuration

  • PSK - setting up keys

• MQTT server settings

  • Structure of MQTT topics

• Control Binding Settings

• Advanced control binding settings

• Configuration file

• Log file

    MQTT - Message Queuing Telemetry Transport

You can integrate a MIDI keyboard into your smart home system to control various devices. Any Smart Home control environment that is based on the MQTT exchange protocol and includes an MQTT server is supported. In a Smart Home system, the MQTT protocol must be at least level 5.0, it is possible to work with earlier versions, but stability and full functionality for all commands is not guaranteed.

We recommend the following compatible solutions for Smart Home control:

• any system based on the MQTT broker mosquitto,
• Home Assistant,
• openHAB,
• MajorDoMo,
• ioBroker,
• Domoticz,
• MyController,
• IntraHouse,
• and so on..

Settings for the Smart Home device control module

• In the “MQTT server” field you must specify the IP address of the MQTT server.

• The “Port” field specifies on which port to send requests to the MQTT server, the default port number is 1883.

• The “Login” field must correspond to the account on the MQTT server.

• The “Password” field must also correspond to the account on the MQTT server.

• “PSK key” is another form of authorization, instead of the login/password pair. Only one thing is used.

• The “SSL/TLS enabled” option allows you to establish a secure connection if the MQTT server supports it.

• The “Self-signed certificate” option allows you to establish a connection with a server that has a self-signed certificate installed.

• The “CA certificate” field indicates the path to the MQTT server root certificate file, if you were issued one.

• The “MQTT topic prefix” field indicates an optional prefix to “MQTT topics”.

• Selecting “MQTT session logging level” turns on or off the recording of debugging information about network exchange and commands to the general log file.

Setting up an MQTT connection

SSL/TLS - certificate configuration

The certificate file, the path to which you must specify in the configuration, must consist, at a minimum, of the CA (Certificate Authority) certificate that signed the certificate of your MQTT server. If you have a chain of necessary certificates, then you need to place the root certificate in a separate folder, and add the remaining necessary certificates to it. For example Let's Encrypt's root certificate is named R3. If you are using a certificate from this company, then you just need to specify the path to the R3.cert or R3.pem file in PEM format.

In the case of a self-signed certificate, it is enough to indicate it by checking the box of the same name. In this case, the MQTT server certificate will be the same as the CA certificate.

To activate SSL/TLS, check the appropriate box. Use these options only if you want to encrypt communications between the client and server. On a local network, this is usually not worth doing. Since this increases the load on both the client and the server.

PSK - setting up keys

Working with PSK keys is not compatible with SSL/TLS settings. The connection can operate only in one of the specified modes; when all values ​​are filled in, priority is given to the connection based on PSK keys. PSK keys are used, as a rule, when working with external servers, the authorization settings of which occur through their own Web interface. For example AdaFruit MQTT or HiveMQ Public MQTT Broker.

The whole setup boils down to getting the key and copying it into the appropriate field. The second parameter of the PSK key binding is your login to the MQTT server, since you have already filled it out above, these are all the settings that can be applied.

MQTT server settings

MQTT topics

MIDI-MT uses the following MQTT topic structure:

    /sensor/<login for MQTT server>/<control identifier>/<value name>

Example of topics used. Let’s assume that your login for the MQTT server is ectrl9, the identifier of the control that smoothly regulates the lighting is called av1, and the control that turns the light on or off has the identifier b11. In this case, control commands will be sent to the following topics:

    /sensor/ectrl9/av1/level = from 0 to 127
    /sensor/ectrl9/b11/onoff = 1 or 0

The control name is set automatically, in accordance with the control identifier selected in the editor. You can get it by referring to the topic:

    /sensor/ectrl9/av1/title = "level 1"
    /sensor/ectrl9/b11/title = "on/off 1"

For some scenarios, information about the MIDI keyboard connection status will be useful. You can check its current status by referring to the topic:

    /sensor/ectrl9/state = 1 or 0

If you are not well versed in the MQTT protocol, or in the Smart Home device, in this case, we recommend reading the book:

• MQTT Essentials E-Book, or there is an online option:
• MQTT Essentials and MQTT version 5 Essentials.

Control Binding Settings

The necessary controls can be configured in the configuration editor. MQTT connection settings are saved in a configuration file, so it is possible to have an unlimited number of customized configurations that can be loaded as needed.

Advanced control binding settings

Additional properties can be defined for all types of controls. For example, assigning a topic to which values ​​will be written. You can also define the payload of values ​​and the description of the element yourself. The description of the controls will be displayed in the MQTT broker, remote control, and panel designer.
These settings can be made in the editor.

To be able to write data to arbitrary topics, you need to enable write access level in the MQTT broker. Example configuration in the acl.conf file for the mosquitto broker:

user ectrl9
topic readwrite #

The user value must correspond to an account on the MQTT server.

Buttons settings

• The “Topic” field should indicate the topic to which the data coming from the control will be written.
• The “ON” field indicates the value that will be written if enabled.
• The “OFF” field indicates the value that will be written if disabled.

Sliders settings

• The “Topic” field is filled in the same way as the button type.
  
• The “VAL” field indicates the value that will be written if the control’s values ​​change. The string must include the wildcard character {0}, which will be replaced by the value sent by the control.

Configuration file

The settings in the configuration file look like this:

{
    ...
    "mqtt": {
        "enable": true,            // блок настроек 'Умного Дома',
        "host": "192.168.22.1",    // учётная запись клиента
        "login": "ctrl9",          // на MQTT сервере
        "pass": "12345",
        "prefix": "",
        "sslpsk": "",
        "certcapath": "",
        "port": 1883,
        "loglevel": 16,
        "isssl": false,
        "selfsigned": false
    },
    ...
}

Log file

From practical recommendations: the logging level can help in debugging related to the first connection to the server. In the future, it is better to turn it off, as this creates additional load for the server, since it broadcasts all the information about its own actions. The log level has nothing to do with local messages.

Example log file

[07-25 -> 16:58:38] Common::MQTT::on_log: Client ctrl9-4687392 sending CONNECT
[07-25 -> 16:58:38] Common::MQTT::on_log: Client ctrl9-4687392 sending PUBLISH (d0, q0, r1, m1, 'sensor/ctrl9/state', ... (1 bytes))
[07-25 -> 16:58:38] Common::MQTT::SmartHome::Start: The Smart-Home control service is running.
[07-25 -> 16:58:38] Common::MQTT::on_log: Client ctrl9-4687392 sending PUBLISH (d0, q0, r1, m2, 'sensor/ctrl9/b37/title', ... (9 bytes))
...