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

  • For a complete IoT example involving Corrade and Node-Red please see the Corrade IoT external services project.
  • When subscribing to a topic, the command will return an UUID to the callback URL that can then be used to unsubscribe via a follow-up MQTT command call. UUIDs of existing subscriptions can be shown by issuing the MQTT command with the action parameter set to list.
  • MQTT subscriptions are part of Corrade's stored state and thereby retained across Corrade runs - the state file is placed under the State folder and is read at Corrade startup and saved after a successful subscription to an MQTT topic.
  • Passing the optional URL parameter when invoking the MQTT command with the action parameter set to subscribe will have the effect of additionally binding a Corrade notification for the MQTT subscription (and the notification tag set to the ID parameter value). When interfacing via Corrade's HTTP server or when scripting with LSL passing the URL parameter can thus spare the need to issue a follow-up notify command in order to be able to receive the messages from the MQTT server. This requires the mqtt notification to be enabled for the configured group or an error will be returned when attempting to subscribe to an MQTT topic.

secondlife/scripted_agents/corrade/api/commands/mqtt.txt ยท Last modified: 2021/10/05 16:58 by office

Access website using Tor Access website using i2p Wizardry and Steamworks PGP Key


For the copyright, license, warranty and privacy terms for the usage of this website please see the license, privacy, copyright and the plagiarism pages.