27 September 2018
mqtt (Commands) | |
---|---|
Type | Corrade progressive command |
Command | MQTT |
Parameters | group , password , action |
Description | The MQTT command can be used to publish MQTT messages or subscribe to an MQTT topic given an MQTT server. |
Permissions | bridge |
Last Changes | C10 - 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) ] ) ); |
MQTT
command call. UUIDs of existing subscriptions can be shown by issuing the MQTT
command with the action
parameter set to list
.State
folder and is read at Corrade startup and saved after a successful subscription to an MQTT topic.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.For the contact, copyright, license, warranty and privacy terms for the usage of this website please see the contact, license, privacy, copyright.