MQTT API

Overview#

The Cayenne MQTT API is used to connect any device that you have with the Cayenne Cloud. After connecting your device you can send data from your device to the Cayenne dashboard and display it using widgets. You may also receive commands from Cayenne, allowing remote control and automation of your devices.

About MQTT#

MQTT is a lightweight messaging protocol designed to be used on top of TCP/IP. It uses an event and message (publish-subscribe) methodology that was designed especially for connections where small footprints, unreliable and/or limited bandwidth connections are found. This type of pattern is especially suited for IoT devices that get deployed in the field and often run on battery power and on constrained networks. With MQTT, the publish-subscribe pattern makes use of a broker that is responsible for distributing messages to clients.Clients can subscribe to varying levels of messages, depending upon how much or what kind of data they are interested.

Using MQTT with Cayenne#

MQTT is the preferred transport and API for sending data to the Cayenne Cloud, or for devices that receive commands from Cayenne. The Cayenne Cloud acts as a broker, managing the various sensor and actuator client devices that wish to send and receive data using the Cayenne Cloud.

Cayenne MQTT is straightforward and easy to use, offering several different ways of connecting your data to Cayenne.

Option 1: Use the Cayenne MQTT Libraries#

Using one of our libraries is the easiest way to get started using MQTT with Cayenne. The Cayenne libraries bundle an MQTT clientand all of the code examples you'll need to get your board connected and using MQTT with Cayenne.

We have prepared walkthroughs and libraries for some of the most common toolchain/IDE combinations to help get you up and running as quickly as possible. If you would like to use one of our libraries, the easiest way to get started is to jump to a section below and read through the information and guides provided there.

  • Arduino MQTT Library - For Beginner users. This is the easiest way to get started with using Arduino MQTT in your project. This section covers installing and configuring the popular Arduino IDE to use Cayenne's Arduino MQTT library. It also includes a walkthrough of setting up an Arduino board, sending sensor data to Cayenne and controlling an actuator from the Cayenne dashboard.

  • mbed MQTT Library - For Intermediate users. This section walks you through using the mbed C++ MQTT Library in your project that uses the mbed IDE. It includes an example of connecting a Nucleo board to Cayenne, writing code to send sensor data as well as control an onboard LED from the Cayenne dashboard.

  • C++ MQTT Library - For Advanced users. This section discusses the steps needed to make use of the Cayenne C++ MQTT library in your code. It also includes advice from the Cayenne team as to which areas of the code need to be updated/customized in order to implement support for new boards in a Cayenne library.

  • Embedded C MQTT Library - For Advanced users. This section discusses the steps needed to make use of the Embedded C MQTT library in your code. It also includes advice from the Cayenne team as to which areas of the code need to be updated/customized in order to implement support for new boards in a Cayenne library.

Option 2: Use raw MQTT API functions#

If you are integrating Cayenne into your existing or custom program, you may wish to only use raw MQTT calls for interacting with Cayenne. Typically you will have already chosen your own MQTT client, will already have implemented your own networking code, and you just need the Publish-Subscribe details for Cayenne’s MQTT API.

If you fall into this camp, you can jump straight to the MQTT Messaging Topics section where you’ll find the details for Cayenne's MQTT calls. We have also prepared a tutorial for using an MQTT client to manually publish and subscribe data so that you can test out using MQTT with Cayenne.

  • Manually Publishing / Subscribing - This will walk you through using the MQTT.fx client to manually publish and subscribe to Cayenne. This can help you test out using MQTT with Cayenne without having to connect an actual board or sensors. This is a great way to become familiar with the fundamentals of using MQTT with Cayenne.

Option 3: use HTTP to push MQTT data#

If you are interesting to push external data into a virtual device you can use Cayenne API HTTP endpoint to do so.

POST
https://api.mydevices.com/things/MQTT_CLIENT_ID/data
HeaderValue
AuthorizationBasic MQTT_USERNAME:MQTT_PASSWORD
Content-Typeapplication/json

Request Payload

[
{
"channel": 1,
"value": 16.4,
"type": "temp",
"unit": "c"
},
{
"channel": 2,
"value": 75,
"type": "rel_hum",
"unit": "p"
},
{
"channel": 5,
"value": 75,
"type": "batt",
"unit": "v"
},
{
"channel": 10,
"value": 1,
"type": "digital_sensor",
"unit": "d"
},
{...}
]

The payload must be a JSON array of objects, each having channel, value, type and unit porperties. Refer to the list of our supported data typesfor the type and unit properties.

MQTT Clients#

To interact with an MQTT broker you’ll need an MQTT client. Here’s a quick list of MQTT clients and resources:

Paho: The Eclipse Paho project provides open-source MQTT clients for C/C++, Python, Java, Javascript, Go and C#. If you are using one of Cayenne’s libraries, the Paho client is bundled in the library to make using MQTT with Cayenne easy.

MQTT.fx: A JavaFX based MQTT Client.

Libraries#

Using one of our libraries is the easiest way to get started using MQTT with Cayenne. The Cayenne libraries bundle an MQTT client and all of the code examples you'll need to get your board connected and using MQTT with Cayenne.

Cayenne Arduino MQTT

Includes everything you need for using Cayenne and MQTT in your Arduino IDE based project.

  • The Arduino MQTT Library is available directly through the Arduino IDE Library Manager. This is the recommended way of obtaining this library. See Add MQTT Library to Arduino IDE for a walkthrough of performing this.

  • Documentation - Covers installing and configuring the popular Arduino IDE to use Cayenne's Arduino MQTT library. It also includes a walkthrough of setting up an Arduino board and sending sensor data to Cayenne.

Cayenne mbed MQTT

Includes everything you need for using Cayenne and MQTT in your mbed IDE based project.

  • Refer to the README located in the mbed MQTT Github for information on using & obtaining mbed library versions.
  • Documentation - Walks you through using the mbed C++ MQTT Library in your project that uses the mbed IDE. It includes an example of connecting a Nucleo board to Cayenne, writing code to send sensor data as well as control an onboard LED from the Cayenne dashboard.

Cayenne C++ MQTT

Includes everything you need for using Cayenne and MQTT in your project that uses the C++ language.

  • Refer to the README located in the C++ Github for information on using & obtaining C++ library versions.
  • Documentation - Discusses the steps needed to make use of the Cayenne C++ MQTT library in your code. It also includes advice from the Cayenne team as to which areas of the code need to be updated/customized in order to implement support for new boards in a Cayenne library.

Cayenne Embedded C MQTT

Includes everything you need for using Cayenne and MQTT in your project that uses the C language.

  • Refer to the README located in the Embedded C Github for information on using & obtaining C++ library versions.
  • Documentation - Discusses the steps needed to make use of the Embedded C MQTT library in your code. It also includes advice from the Cayenne team as to which areas of the code need to be updated/customized in order to implement support for new boards in a Cayenne library.

Using the MQTT Libraries#

Create a Cayenne account

In order to use the Cayenne MQTT API, you will need to first create a Cayenne account. Visit the Cayenne website and create an account.

After creating your account, Cayenne will ask you which type of device you wish to add to your project. To add a device using the API, select Bring Your Own Thing from the list of devices presented. You will then be taken to a screen with details needed to help you connect your board to Cayenne.

Using Arduino MQTT#

The Cayenne Arduino MQTT library gives you everything you need to quickly get your board connected with Cayenne using MQTT and the Arduino IDE. Using the Arduino IDE is a fast and easy way to program your Arduino board. In this section we will walk you through setting up the Arduino IDE software so that you can write code that uses the Arduino MQTT library. We will then walk through an example of using the library, setting up and connecting an Arduino Uno board, adding a TMP36 Temperature Sensor.

Install Arduino IDE#

To use the Cayenne Arduino MQTT Library, the Arduino IDE software should be installed. Go to Arduino IDE to download and install the Arduino IDE software if you need it. Arduino IDE can be installed on Windows, Mac or Linux computers.

Add MQTT Library to Arduino IDE#

The Cayenne Arduino MQTT Library is a collection of code, known as sketch files, that makes it easy for you to connect and send data to and from sensors, actuators and devices connected to Arduino boards using MQTT. Cayenne sketch files can be combined with other sketch files for your IoT projects.

The Cayenne Arduino MQTT Library is available directly from the Arduino IDE Libraries list. To install the library, select Sketch > Include library > Manage Libraries. The Library Manager dialog will appear. From here, search for the Cayenne MQTT library and install it.

The Cayenne MQTT library has now been expanded in the libraries folder in your Arduino sketches directory. You can verify this by going to the Sketch > Include Library menu where you should now see the Cayenne MQTT library at the bottom of the drop-down menu under Contributed Libraries. The Cayenne MQTT library is now ready to be used in your project.

Configure Arduino IDE#

In order to successfully program your Arduino board, you will need to verify that the appropriate Board and Port are selected in the Arduino IDE.

First, verify that the correct Board is selected in the Tools > Board menu. Be sure to select the board type that you will be programming.

Then, verify that you have the correct Port selected for communicating with your Arduino. Pick the correct port based upon how you are connecting your Arduino to your PC/Mac.

Load the example sketch file#

After setting up your PC/Mac computer with the Arduino IDE and the Cayenne MQTT Library, you are ready to proceed with programming your board to connect with Cayenne. The Cayenne MQTT Library comes with several different examples, depending upon which type of connection your Arduino board will use to connect to the Internet. To proceed, we need to load the correct example file for our board.

Open the File > Examples > CayenneMQTT > Connections menu and select the appropriate sketch file example for the connection type you will be using. In our case, we’ll be using the W5100 shield, so we select the EthernetShieldW5100 example. Once selected, the example sketch file will open in the Arduino IDE.

TIP: If you aren’t sure which connection type you have, you can refer to Arduino Ethernet and WiFi Shields for more information.

Add MQTT Credentials#

The example sketch file includes everything we need to connect to Cayenne and publish our first set of test data, but it is missing our unique MQTT credentials that will allow us to connect this device into our account. Let’s add those now.

All of the required information we need can be found on the Cayenne dashboard’s Choose SDK and connect your device screen. Refer to this screen and copy & paste your MQTT Username, MQTT Password and Client ID into the sketch file. The example sketch file includes placeholders for these values, so we just need to update them with the values provided to us on our dashboard.

TIP: The credentials shown here are unique for your account and the current device being added. When programming new devices, always be sure to copy & paste from the Cayenne dashboard screen so that the correct values are used for your device.

Connect board to Cayenne#

Once you have double-checked the sketch file, select Sketch > Upload to upload the sketch file to your device. As soon as your Arduino device comes online and connects to Cayenne, your device’s dashboard will appear.

Congrats! Your hardware is now connected to the Cayenne Cloud!

Send sensor data#

Once our board is connected to our Cayenne dashboard, we can send some sensor data and get our very first widget added. For this example, we’ll be using a TMP36 Temperature Sensor. Begin by making sure that your TMP36 sensor is connected to the Arduino board. If you need help connecting this sensor, you can refer to the TMP36 Arduino Tutorial. As in the tutorial, our TMP36 sensor will be connected to the Arduino’s Analog Pin 0.

TIP: You can refer to this example file that includes all of the code used in our example for reading and sending our sensor’s data to Cayenne.

Reading the TMP36 sensor data#

The first step in handling our TMP36 sensor is to write some code to read the sensor’s current value. The TMP36 sensor doesn’t give us a Temperature reading, it will give us an output that is related to voltage. We’d prefer to show a temperature in Celsius on our dashboard, so we also need to convert the reading into a usable temperature. We start by adding the code to read and convert the TMP36 from Analog Pin 0 into celsius temperature.

Tip: Refer to the documentation for whatever sensor you are using in order to determine what kind of code needs to be written to read its sensor data.

Send Temperature reading to Cayenne#

Now let’s send our TMP36 temperature data up to Cayenne. This is easily accomplished, requiring only a single line of code. In this case, we’ll send the data to Cayenne using MQTT Channel 0.

TIP: There are many ways to read and send sensor data. Depending upon what device you are using and what goals you have in mind, you may choose a different way.

Once you have double-checked the sketch file, select Sketch > Upload to upload the sketch file to your device. Shortly after our board comes online, it will read the current temperature of our TMP36 sensor and send the reading to Cayenne. Cayenne will receive this data and automatically add a widget for it! Cayenne will do this automatically for any new MQTT data that you send it. Widgets created in this way are temporary by default, giving you an easy way to test sending new data to Cayenne. If you want to keep this widget permanently, simply click on the widget tile and it will become a permanent widget in your dashboard.

Congrats! Your hardware is now sending sensor data to the Cayenne Cloud!

Send sensor data to Cayenne#

Once our board is connected to our Cayenne dashboard, we can send some test data and get our very first widget added. For this example, we can continue to refer to the SimplePublish example. In addition to connecting to our dashboard, this example also includes two examples of publishing test data to our dashboard.

Once our board comes online, it will send two test data points to our dashboard, a temperature value and a luminosity value. As soon as Cayenne receives this data, it will automatically add widgets for them! Cayenne will do this automatically for any new MQTT data that you send it. Widgets created in this way are temporary by default, giving you an easy way to test sending new data to Cayenne. If you want to keep this widget permanently, simply click on the widget tile and it will become a permanent widget in your dashboard.

Congrats! Your hardware is now sending sensor data to the Cayenne Cloud!

Respond to actuator commands#

Now that we have our board connected to Cayenne and it has successfully sent test data to our dashboard, let’s take a look at how easy it is to add an actuator. When users change the state of actuators using the dashboard widgets, Cayenne publishes COMMAND messages. By subscring to these messages, we will be informed when our actuator's state was changed. We can then take action in response, such as telling a connected Light to turn on or off.

For this example, we will setup a Button widget on our dashboard and use it to send actuator commands to an imaginary actuator connected to our board. We will then take a look at the SimpleSubscribe code example that subscribes to data from Cayenne so that we know when our actuator's state was changed on the dashboard.

Add dashboard widget#

Let's start by adding a Button widget on the dashboard. From the Cayenne dashboard, click Add New > Device / Widget.

  1. Choose Custom Widget > Button.

  2. Give your actuator a name, for example enter “Light” into the Name field.

  3. We’ll be adding this actuator to our custom device, so make sure your device is selected in the Device field.

  4. Select 0 from the Channel field.

    Note: The SimpleSubscribe code doesn't care what channel our device is connected to, but normally we would want to make sure the Channel selected here matches up with the channel that our code uses later when watching for COMMAND messages sent from Cayenne. Our recommendation is to stick to using Channel == the Pin your actuator is connected to.

  5. We can specify an Icon for our actuator. Say we’re using it to control a Light, so let’s select a Light icon here.

  6. Click the Step 2: Add Actuator button. The light widget will then be added to our dashboard.

Write code for the actuator#

To properly handle actuator commands with Cayenne, it first helps to understand a bit about how Cayenne expects a well behaved client to react to actuator commands. Cayenne expects a client to:

  1. Subscribe to COMMAND messages from Cayenne.

  2. When a new COMMAND arrives, handle changing the status of the actuator connected to the board.

    Note: Cayenne will inform the listener which Channel was effected as well as what the new state is.

  3. After changing (or attempting) to change the actuator state, inform Cayenne what the current status now is.

    Note: It's very important to inform Cayenne what the correct state is. This ensures that the dashboard properly reflects the correct current state of the device.

  4. Inform Cayenne whether the event was handled OK or had an Error.

    Note: If there was an error, Cayenne will handle showing the error to the user so that they're aware of it.

With that background in place, let's discuss how to implement these tasks in code. The SimpleSubscribe example provides provides an example of dealing with COMMAND messages from Cayenne. You can find this example in Platform/Linux/Examples folder included with the library. It includes code to listen and react to all COMMAND messages received from Cayenne, making it easy for us to quickly test an example of controlling an actuator with the dashboard.

Note: The SimpleSubscribe example handles messages received from Cayenne by simplying responding back that the state was successfully changed. In order to be useful in your program, you will want to also make sure your code makes changes to your actuator's physical state. The code for accomplishing this is left for you to write for your device, just be sure to do so!

TIP: If you want more details beyond the sample code provided with the library, the Manually Publishing / Subscribing - Actuator's section also covers these steps in more detail.

Adding your MQTT Credentials

As before with the example, we need to fill in our MQTT Credentials into the code for the SimpleSubscribe example code. If we fail to do so, our device will not be able to connect to our account.

TIP: If you ever need to refer to the MQTT Credentials needed for operations such as this, you can refer back to the Configuration screen for your board. To do so, select the cogwheel menu for your board and then the Configure option. In the configuration screen that appears, you'll find the values that you need.

Compile, Upload and connect to Cayenne

After filling in your MQTT credentials into the code example, we are ready to run the SimpleSubscribe example. The C++ library includes a Makefile for building the examples. To use the Makefile, navigate to this file in source and run the make command. You can then run the SimpleSubscribe program. As soon as your device comes online and connects to Cayenne, you can use the Button widget on the dashboard, triggering actuator COMMAND messages to be sent to your board. The SimpleSubscribe code will handle these messages by replying back to our dashboard that the actuator was successfully changed and our dashboard will update to show the changed state.

Congrats! You can now use the button to send actuator commands to your board.

* Denotes default value for Unit.

MQTT Messaging Topics#

Using MQTT with Cayenne

MQTT is the preferred API protocol to send and receive data to and from myDevices dashboard. Payloads are plain text based or JSON, and topics follow a tree composed of a Username, a Client ID and a Channel ID, allowing for fine filtration and control. Therefore, MQTT does not require the use of a provisioning API. Data that is published to a backend topic can also be subscribed to by a user’s third party application.

Send Sensor data as JSON#

Sensor payload

TopicPUBSUB
v1/username/things/clientID/data/jsonXX

A JSON string payload for

[
{
"channel": 1,
"value": 16.4,
"type": "temp",
"unit": "c"
},
{
"channel": 2,
"value": 75,
"type": "rel_hum",
"unit": "p"
},
{
"channel": 5,
"value": 75,
"type": "batt",
"unit": "v"
}
]

Send individual Sensor data#

In order to send data, the channel ID needs to be appended to the data topic.

TopicPUBSUB
v1/username/things/clientID/data/channelXX

The data type and/or unit can be added to prefix the value, allowing the backend to process and display data without the need of configuring the data channel from the dashboard:

  • (string) type,unit=value

Receive Actuator command#

In order to receive a command for a given data channel, the device must subscribe to the “cmd” topic.

TopicPUBSUB
v1/username/things/clientID/cmd/channel X

Payload will contain a command sequence number followed by the value. The Developer is responsible for managing the value format.

  • (string) seq,value

Send Actuator Updated Value#

In order to let the dashboard know of the current status of an actuator, the device must publish that value to the corresponding channel. This will ensure that the widget state (on/off) remains consistent with the state of the actuator.

TopicPUBSUB
v1/username/things/clientID/data/channelX 

Payload must contain simply the true binary value of a digital actuator (1/0) or numerical value for analog actuators.

  • (string) 1
  • (string) 0.8

Send command response#

In order to let the system know of an actuator command, the device must publish a response on a common response topic.

TopicPUBSUB
v1/username/things/clientID/responseX 

Payload must contain the status “ok” or “error”, as well as the command sequence number and an optional message that will be displayed to the user in case of error.

  • (string) ok,seq
  • (string) error,seq=message

Examples#

Send Sensor Data to Channel 2

⇒ PUB v1/A1234B5678C/things/0123-4567-89AB-CDEF/data/2

temp,c=20.7

Receive Actuator Command on Channel 3

⇒ SUB v1/A1234B5678C/things/0123-4567-89AB-CDEF/cmd/3

⇐ 2otoExGxnMJz0Jn,0

Send updated Actuator value on Channel 3

⇒ PUB v1/A1234B5678C/things/0123-4567-89AB-CDEF/digital/3

1

Send a Command Response - OK

⇒ PUB v1/A1234B5678C/things/0123-4567-89AB-CDEF/response

ok,2otoExGxnMJz0Jn

Send a Command Response - Error

⇒ PUB v1/A1234B5678C/things/0123-4567-89AB-CDEF/response

error,2otoExGxn=ERROR MESSAGE