MQTT Control API

What is a CONTROL API

The broker and several plugins provide so-called control APIs. These APIs are implemented via specific MQTT topics, in a request-response message-workflow.

For example, the broker itself provides a $CONTROL/broker/v1 topic, where a client can publish requests.

note

The broker control API must be enabled explicitly by setting enable_control_api true in the broker configuration.

A request contains a list of commands and each command item can have a field named correlationData which will be included in the broker response message. A response messages will be published on the topic $CONTROL/broker/v1/response.

Every plugin has its own request/response topic and some commands require additional request parameters. The detailed information about these topics and parameters can be found in the sub-pages.

Making manual MQTT API requests

In normal operation API requests are expected to be made through the Cedalo Platform or a custom application, however it may be useful to be able to issue MQTT API requests manually. This can be done in a low-level manner using the commandline "request reponse" client mosquitto_rr. This tool subscribes to a single topic, publishes a message to another topic and waits for the response.

note

In the examples below we are not making use of encryption. The manual for mosquitto_rr contains all of the command line options to allow use to specify encryption for your production environment.

The mosquitto_rr -e argument is used to set the response topic and -t the request topic. Details of the request and response topics can be found in the API documentation for each plugin.

The message payload is a JSON object of the form:

{
    "commands": [{
        "command": "commandName",
        // further command parameters
    }]
}

For example, to use the Sparkplug-decode API we would use $CONTROL/cedalo/sparkplug-decode/v1 and $CONTROL/cedalo/sparkplug-decode/v1/response for the request and response topics respectively.

note

Your client must have the appropriate access rights to these topics to make the request.

We could then set the decode mode with the following command:

mosquitto_rr -u <username> -P <password> -h <hostname> -p <port> \
    -t '$CONTROL/cedalo/sparkplug-decode/v1' \
    -e '$CONTROL/cedalo/sparkplug-decode/v1/response' \
    -m '{"commands": [{ "command": "setDecodeMode", "decodeMode": "enhanced" }]}'

And receive the success response:

{
    "reponses": [{
        "command": "setDecodeMode"
    }]
}

If an error occurs, an error parameter will be present:

{
    "responses":[{
        "command": "setDecodeMode",
        "error": "Invalid decodeMode value",
    }]
}

Commands that return data in their response will include a data object. For example, to get the current Sparkplug-decode decode mode we can use the following command, including the optional user-specified correlationData parameter:

mosquitto_rr -u <username> -P <password> -h <hostname> -p <port> \
    -t '$CONTROL/cedalo/sparkplug-decode/v1' \
    -e '$CONTROL/cedalo/sparkplug-decode/v1/response' \
    -m '{"commands": [{ "command": "getDecodeMode", "correlationData":"my-uuid" }]}'

And receive the response:

{
    "responses":[{
        "command": "getDecodeMode",
        "data": {
            "decodeMode": "enhanced"
        },
        "correlationData": "my-uuid"
    }]
}