Carriots MQTT Broker

Introduction

This document describes one of the features that Carriots offers to work with the MQTT protocol: Make available to the user a dedicated broker to exchange the desired information. This information does not pass through the Carriots platform, it is only a broker for the user to use as desired.

MQTT is an open protocol widely adopted by many companies worldwide for data exchange with devices. For a more detailed description please read our Complete MQTT Documentation.

You can use too the MQTT protocol to send streams to Carriots. This feature is explained in our MQTT Documentation and the tutorial Example for Sending Streams using Python and the Paho Library.

Description

It may be useful to have a MQTT messaging broker to exchange information with the device. For this purpose, Carriots allows to enable topics on demand for each device. The information exchange using this worfflow does not go through the Carriots rule engine flow.

  • The Carriots Platform has an MQTT broker dedicated exclusively to this task.
  • The user can manage these topics for information exchange, because it is possible that not all devices have this need at the same time.
  • The user can activate / deactivate the MQTT topics for the device via:
    · Carriots External API
    · Carriots Control Panel

Operations that the user can perform

  • Create MQTT credentials
  • Create MQTT topics
  • Get MQTT topics
  • Delete MQTT topics
  • Update MQTT credentials
  • Remove MQTT configuration

These operations can be performed through Carriots Control Panel or external API. Please continue reading for more information on how to perform them.

Connection

HOST PORT Description
mqttbroker.carriots.com 1883
mqttbroker.carriots.com 8883 (TLS)

Authentication

To connect to a topic it will be necessary to establish an user + password via Control Panel or via External API. If the user does not select any, Carriots will automatically assign these access credentials. This information can be consulted in the control panel.

Encryption across the network can be handled with TLS. You can download a valid certificate HERE

Available topics

The MQTT topic name for the device will be assigned by Carriots and it will be the Device id_developer. This information can be consulted in the control panel.

Topic example: defaultDevice@userAccount.userAccount/topicname

Control Panel

MQTT credentials and topics can be assigned in the device creation / modification forms. Activating the "MQTT" switch toggles a subform where you can introduce username, password and topics names.

  • MQTT credentials and topics in Carrriot Control Panel

After saving the form you can see and copy the credentials created based on the entered data:

  • MQTT credentials and topics in Carrriot Control Panel

MQTT username is created following the pattern: [MQTT-username-entered].[device-id-developer]

Topics are created following the pattern: [device-id-developer]/[topic-name-entered]

The number of topics is limited . If you need to extend this functionality please contact us.

Finally, you can see and copy the MQTT data in the device show page too:

  • MQTT credentials and topics in Carrriot Control Panel

External API

API Connection Information:

Connection attribute Description
HOST api.carriots.com
PORT 80
443
HTTP VERB POST / PUT / GET / DELETE
ID_DEVELOPER_DEVICE Defined by user
USERNAME Defined by user
PASSWORD Defined by user
Create MQTT credentials
URL: http://api.carriots.com/mqttdevices/[id_developer_device]/credentials/
HTTP method: POST

Headers:

· carriots.apikey : your Carriots APIKEY

Body:

Attribute Description
username (mandatory) Username to connect
password (mandatory) Password to connect

Response codes

Code Description
200

Request example:

POST http://api.carriots.com/mqttdevices/defaultDevice@exampleuser.exampleuser/credentials/

POST HEADER:
carriots.apikey: a69exxxxxe03f5e6dd14b517b20d03a2dc3b3cxxxxc9c3979bac

POST PAYLOAD:

Response example:

Create MQTT topics
URL: http://api.carriots.com/mqttdevices/[id_developer_device]/topics/
HTTP method: POST

Headers:

· carriots.apikey : your Carriots APIKEY

Body:

Attribute Description
name (mandatory) Topic name

Response codes

Code Description
200

Request example:

POST http://api.carriots.com/mqttdevices/defaultDevice@exampleuser.exampleuser/topics/

POST HEADER:
carriots.apikey: a69exxxxxe03f5e6dd14b517b20d03a2dc3b3cxxxxc9c3979bac

POST PAYLOAD:

Response example:

Get MQTT topics
URL: http://api.carriots.com/mqttdevices/[id_developer_device]/topics/
HTTP method: GET

Headers:

· carriots.apikey : your Carriots APIKEY

Response codes

Code Description
200

Request example:

GET http://api.carriots.com/mqttdevices/defaultDevice@exampleuser.exampleuser/topics/

GET HEADER:
carriots.apikey: a69exxxxxe03f5e6dd14b517b20d03a2dc3b3cxxxxc9c3979bac

Response example:

Delete MQTT topics
URL: http://api.carriots.com/mqttdevices/[id_developer_device]/topics/
HTTP method: DELETE

Headers:

· carriots.apikey : your Carriots APIKEY

Body:

Attribute Description
name (mandatory) Topic name

Response codes

Code Description
200

Request example:

DELETE http://api.carriots.com/mqttdevices/defaultDevice@exampleuser.exampleuser/topics/

DELETE HEADER:
carriots.apikey: a69exxxxxe03f5e6dd14b517b20d03a2dc3b3cxxxxc9c3979bac

DELETE PAYLOAD:

Response example:

Update MQTT credentials
URL: http://api.carriots.com/mqttdevices/[id_developer_device]/credentials/
HTTP method: PUT

Headers:

· carriots.apikey : your Carriots APIKEY

Body:

Attribute Description
username (mandatory) Username to connect
password (mandatory) Password to connect

Response codes

Code Description
200

Request example:

PUT http://api.carriots.com/mqttdevices/defaultDevice@exampleuser.exampleuser/credentials/

PUT HEADER:
carriots.apikey: a69exxxxxe03f5e6dd14b517b20d03a2dc3b3cxxxxc9c3979bac

PUT PAYLOAD:

Response example:

Remove MQTT credentials
URL: http://api.carriots.com/mqttdevices/[id_developer_device]/
HTTP method: DELETE

Headers:

· carriots.apikey : your Carriots APIKEY

Response codes

Code Description
200

Request example:

DELETE http://api.carriots.com/mqttdevices/defaultDevice@exampleuser.exampleuser/

DELETE HEADER:
carriots.apikey: a69exxxxxe03f5e6dd14b517b20d03a2dc3b3cxxxxc9c3979bac

Response example:

SDK: MQTTPublisher class

MQTTPublisher class is a commodity class for publishing messages to a MQTT topic from Carriots.

Public constructors:

MQTTPublisher (int qualityOfService, String username, String password)

Constructs a MQTTPublisher object with a default configuration. This is recommended to use mqttbroker.carriots.com.

MQTTPublisher (String mqttBrokerDNS, int mqttBrokerPort, int qualityOfService, String username, String password)

Constructs a MQTTPublisher object assuming some configuration. This is recommended to use an external MQTT broker that admits TCP protocol as it is going to be connected using TCP.

MQTTPublisher (String mqttBrokerProtocol, String mqttBrokerDNS, int mqttBrokerPort, int qualityOfService, String username, String password, SSLCERTIFICATE)

Constructs a MQTTPublisher object with the full configuration set in the constructor. This is recommended to use an external MQTT broker with the SSL protocol. The certificate must be in one line, so carrier returns must be replaced with "n".

Public method:

publish (String topic, Object data)

Publishes a message to a topic. The message can be any data structure (String, Number, Boolean, Map, Collection...). You can publish messages to different topics with the same MQTTPublisher object if the MQTT broker configuration is the same.