MQTT

27 September 2018

  • C10 - added.
mqtt (Commands)
TypeCorrade progressive command
CommandMQTT
Parametersgroup, password, action
DescriptionThe MQTT command can be used to publish MQTT messages or subscribe to an MQTT topic given an MQTT server.
Permissionsbridge
Last ChangesC10 - added.

The MQTT command can be used to publish MQTT messages or subscribe to an MQTT topic given an MQTT server. The MQTT command has to be issued in order to be able to receive MQTT notifications. Whilst publishing a message to an MQTT server is synchronous, messages received from the MQTT on the subscribed topic are asynchronous.

Command Required Parameters Required Corrade Permissions Example
MQTT group, password, action bridge 
// Subscribe to an MQTT server listening on
// 127.0.0.1 and port 1443 with "corrade"
// as username and "corrade" as password
// and to the topic "SIML" and additionally
// bind to the MQTT notification to be
// able to receive messages.
llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "MQTT",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            // Subscribe to Corrade AI
            "action", "subscribe",
            // Corrade AI listening host.
            "host", "127.0.0.1",
            // Corrade AI listening port.
            "port", 1443,
            // Corrade AI credentials.
            "username", "corrade",
            "secret", "corrade",
            // Use the SIML module of Corrade AI.
            "topic", "SIML",
            // Send the result of the MQTT command to this URL.
            "callback", wasURLEscape(URL),
            // By adding an URL, Corrade will subscribe AND bind to the "MQTT" notification.
            "URL", wasURLEscape(URL)
        ]
    )
);
Parameter Possible Value Sub-Parameter Possible Value Description Example
action publish host An IP address Publish a message to an MQTT server. 
// The message to send - can also listen to local chat, for instance.
string text = "Hello!";
 
llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "MQTT",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "publish",
            "host", "127.0.0.1",
            "port", 1443,
            "username", "corrade",
            "secret", "corrade",
            "topic", "SIML",
            // The payload, ie: wasURLEscape( "Hash=something&Message=Hello!" )
            // Note the double escaping that is necessary to prevent collisions!
            "payload", wasURLEscape(
                wasKeyValueEncode(
                    [
                        // The hash is an identifier that will allow responses from Corrade AI
                        // for various messages to be distinguished. It can be any identifier
                        // but a handy way of generating an identifier is to hash the message.
                        "Hash", llSHA1String(text),
                        // Note the double escaping!
                        "Message", wasURLEscape(text)
                    ]
                )
            ),
            "callback", wasURLEscape(URL)
        ]
    )
);
port A port number.
topic A topic to send the message to.
payload A message payload.
username The username and password to use for authentication to the MQTT server.
secret
type Set to either text or binary.
QoS Quality of service level (defaults to 0).
retain Whether to retain the message (defaults to False).
subscribe host An IP address Subscribe to a topic from an MQTT server. 
llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "MQTT",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            // Subscribe...
            "action", "subscribe",
            // ... to an MQTT broker at 127.0.0.1
            "host", "127.0.0.1",
            // ... on port 1443
            "port", 1443,
            // ... using the following credentials
            "username", "corrade",
            "secret", "corrade",
            // ... to the SIML topic on the broker
            "topic", "SIML",
            // Send the result of the MQTT command to this URL.
            "callback", wasURLEscape(URL),
            // By adding an URL, Corrade will subscribe AND bind to the "MQTT" notification.
            "URL", wasURLEscape(URL)
        ]
    )
);
port A port number.
topic A topic to send the message to.
username The username and password to use for authentication to the MQTT server.
secret
execute True or False (default, False) Whether to execute commands sent to the topic that Corrade subscribes to.
notifications A list of notifications. Publish the requested notifications on the MQTT topic that Corrade subscribes to.
URL Optionally bind an MQTT notification for the subscription.
type Set to either text or binary.
QoS Quality of service level (defaults to 0).
ID An UUID used to track the binding (generated randomly by default).
unsubscribe session An MQTT subscription UUID Unsubscribe from an MQTT server topic. 
llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "MQTT",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "unsubscribe",
            "session", "8384fd9d-1d86-4991-a925-3dc2cf22f06c",
            // Also remove the notification URL.
            "URL", wasURLEscape(URL)
        ]
    )
);
URL Optionally remove the MQTT notification.
list List all MQTT subscriptions for the calling group 
llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "MQTT",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "list",
            "callback", wasURLEscape(URL)
        ]
    )
);

Notes