For Internet of Things (IoT) Corrade bundles an integrated MQTT server. You can use an MQTT client, such as MQTT.js for JavaScript or mosquitto_client to subscribe to Corrade's MQTT server.

The MQTT server that Corrade implements, offers topics for the groups you have configured in Configuration.xml. For instance, given the configured group [Wizardry and Steamworks]:Support, a client would subscribe to the topic:

[Wizardry and Steamworks]:Support/password/group,message

where group, and message represent notifications to subscribe to, by sending the group name [Wizardry and Steamworks]:Support, password as the group password. Once subscribed to the group topic, the MQTT client shall receive the notifications that the client subscribed to asynchronously as they are published by Corrade.

An MQTT client can also publish a command, using the group name as the topic and the key-value pair command as the payload. Once the command has executed, the result shall be published by Corrade's MQTT server on the same topic. For example, assuming that the group is [Wizardry and Steamworks]:Support, that the password for the group is password and that the language is set to WAS, to publish a version command and retrieve the result it is necessary to first subscribe using the mosquitto_sub command:

mosquitto_sub \
    -V mqttv31 \
    -h corrade.home \
    -p 8883 \
    -t '[Wizardry and Steamworks]:Support/password'
    -v

where:

• corrade.home is the hostname or IP address of the Corrade server,
• 8883 is the port,
• [Wizardry and Steamworks]:Support is a configured group for Corrade,
• password is the group password

Next and separately, the mosquitto_pub command is used to publish the command:

mosquitto_pub \
    -V mqttv31 \
    -h corrade.home \
    -p 8883 \
    -t '[Wizardry and Steamworks]:Support/password'
    -m 'command=version&group=[Wizardry and Steamworks]:Support&password=password'

where:

• corrade.home is the hostname or IP address of the Corrade server,
• 8883 is the port,
• [Wizardry and Steamworks]:Support is a configured group for Corrade,
• password is the group password

If all goes well, the previously issued mosquitto_sub command will display the response from Corrade.

Corrade will accept subscriptions to multiple groups provided that the credentials for the group topics match the group. For instance, a client may bind to:

[Wizardry and Steamworks]:Support/password/group,message,local
[Wizardry and Steamworks]:Support/password/alert

in order to be able to route group, message, local and alert notifications separately.

Retrieve OwnTracks certificate generator:

wget https://raw.githubusercontent.com/owntracks/tools/master/TLS/generate-CA.sh

Comment or remove the line in generate-CA.sh reading: ''%%% subjectAltName = $ENV::SUBJALTNAME''.

Make the script executable:

chmod +x generate-CA.sh

and generate a certification authority and server certificates for Corrade:

generate-CA.sh SERVER_HOSTNAME

where:

• SERVER_HOSTNAME is the hostname of the machine that Corrade runs on.

This will generate ca.crt, ca.key, SERVER_HOSTNAME.crt and SERVER_HOSTNAME.key. Next step is to generate a PFX certificate using OpenSSL for Corrade:

openssl pkcs12 -export -out mqtt.pfx -inkey SERVER_HOSTNAME.key -in SERVER_HOSTNAME.crt -certfile ca.crt

When prompted for a password, just hit the enter key twice - there should be no export/import password set for the certificate. Finally, configure Corrade by editing Configuration.xml:

        <MQTTServer>
            <Enable>1</Enable>
            <IPAddress>0.0.0.0</IPAddress>
            <Port>8883</Port>
            <Certificate>
                <Path>mqtt.pfx</Path>
            </Certificate>
        </MQTTServer>

Assuming a group named [Wizardry and Steamworks]:Support and a password for the group password, then the following mosquitto command will subscribe to the group and message notifications:

mosquitto_sub \
    -V mqttv31 \
    -h corrade.home \
    -p 8883 \
    -cafile ca.crt
    -t '[Wizardry and Steamworks]:Support/password/group,message'
    -v