The Cayenne MQTT protocol

In the last lecture we have seen the command message sent by Cayenne:

Trying the protocol with MQTTfx

The MQTTfx client allows you to

• manually configure a Cayenne client creating a connection profile.
  
  This profile contains the Cayenne credentials
  
  
  • Cayenne user name
    
    
  • Cayenne password
    
    
  • Cayenne client_id
    
    
• connect to the Cayenne MQTT broker at mqtt.mydevices.com
• publish messages in Cayenne MQTT format
• Subscribe to and receive Cayenne cmd messages and answer them

Starting MQTTfx

Setting up the profile

Copy Cayenne credentials

Connecting to Cayenne

Once the profile is created you can connect to Cayenne with the “connect” button.

You should see the “offline” note in on your Cayenne device page go away

Once connected we can start sending messages to Cayenne

Publish a message on Cayenne

Cayenne MQTT expects topics of the following form:

v1/username/things/clientID/data/channel

This tells Cayenne that “data” are going to be sent.

Replace “username” with your Cayenne user name and

“clientID” with the client ID of your device

We will send dummy temperature data to channel 0.

Therefore “channel” must be replaced by “0”.

The payload

The payload (the actual data) has the following form:

type,unit=value

In our case:

Type (temperature): temp

Unit (Celsius): c

Value: 29.3 (typical Ugandan temperature)

Our payload therefore becomes:

Temp,c=29.3

Publish the data message

MQTTfx data seen in Cayenne

Subscribing to cmd messages

In order to see the command messages e.g. those

sent by the push button we must first subscribe to them.

The format of a subscription is:

v1/username/things/clientID/cmd/channel

Since our push button is connected to channel 3

this is what we define as channel
.
v1/88253c70-76e9-11e9-9636-f9904f7b864b/things/
1ce44ea0-76ea-11e9-b4eb-6bf2c2412b24/cmd/3

Subscribing in MQTTfx

Clicking the button

Cayenne is waiting for a response

Treating the command

Normally we would treat the command by acting on the hardware.

If this was successful we would inform Cayenne that the new value was set:

Format:

v1/88253c70-76e9-11e9-9636-f9904f7b864b/things/
1ce44ea0-76ea-11e9-b4eb-6bf2c2412b24/data/3

and the topic would be the new value: in this case: 1

Sending the response

The switch shows “on”

The Cayenne MQTT client

With this information we understand how the Cayenne MQTT client works:

• In its begin method it gets the Cayenne credentials and saves them
  
  
  • It sets up a root topic string
    
    self.rootTopic = "v1/%s/things/%s" % (username, clientid)
    
    
  • It connects to WiFi and then to the Cayenne MQTT
    
    broker using the tcp protocol
    
    
  • It subscribes to the cmd topic

Measurement types

A big number of data types is defined in the Cayenne MQTT protocol
Have a look at the docs under”Supported data types”:

https://mydevices.com/cayenne/docs/cayenne-mqtt-api/#cayenne-mqtt-api-mqtt-messaging-topics

Only the most basic ones are implemented in our client:

Measurement units

The same is true for the units, here are the ones defined in the client:

Combining measurement and publishing

In session 2 we have seen how to readout sensors and control actuators

Now we have seen how to publish and how to subscribe to Cayenne messages

We have to combine those two in order to create a full cayenne IoT node.

SHT30 on Cayenne(1)

SHT30 on Cayenne(2)

Cayenne MQTT client subscribe

This is a little more tricky:

We have to create a callback function

and register it with the Cayenne MQTT client

When the push button or slider on Cayenne

are activated this function will be called

The function must find out from which channel

the request is coming, and which are the data

It must then act on the hardware correspondingly

The Cayenne MQTT client sends a response message

without our intervention

A Qt app and Cayenne MQTT

The graphical user interface of Cayenne is fairly limited.

Can we write an application with another GUI system interacting

with our devices connected to the Cayenne MQTT broker?

Example:

The WeMos D1 buzzer.

We want to play a song from a list of choices.

The Buzzer GUI

The Cayenne MQTT C library

The Cayenne MQTT C library contains everything we need

to communicate with the Cayenne MQTT broker:

• Network and CayenneMQTTClient data structures defined in include files
  
  
• NetworkInit and NetworkConnect to connect to the Network
  
  
• CayenneMQTTClientIni and CayenneMQTTConnect
  
  to connect to the Cayenne MQTT broker
  
  
• CayenneMQTTPublishDataInt to publish the song number

The end of the show

There is still work for you during the exercises session to

make you IoT node work with Sensor readout

Publishing the result on Cayenne (for the SHT30)

Subscribe to a command message from the Cayenne slider

to modify the settings of a colour component of your WS2812 rgb LED

For further study please consult:

https://afnog.iotworkshop.africa/do/view/AFNOG/AFNOGWorkshop2019

You will find plenty examples on

https://github.com/uraich?tab=repositories

Slide 1: Setting up and IoT

Session 4: Sending real measurement data to Cayenne and

receiving commands and executing them on the hardware

Uli Raich

formally CERN, Geneva, Switzerland

-- Uli Raich - 2019-05-15

Comments

<--/commentPlugin-->