This paper will illustrate you about what is MQTT, how to use MQTT to create a device in the Cumulocity platform. We also look into publishing messages onto the platform to update different aspects of the device. Lastly we will send messages form the Cumulocity platform to the device.
Prerequisites
- You need to have a valid tenant with username and password.
- You need to be familiar with SmartREST and static templates. Documentation can be found at https://www.cumulocity.com/guides/reference/smartrest
- You need a tool MQTT fx installed, which can be downloaded from the following link
http://mqttfx.jensd.de/
MQTT Introduction
Besides REST, Cumulocity Core supports MQTT as second, native protocol. MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open, simple, and designed so as to be easy to implement. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.
Some references can be found on the MQTT web site. ( http://mqtt.org/documentation)
Configuring the MQTT Connection
We will first connect with the Cumulocity MQTT broker. Once connected, we will send command messages to a topic. Once you have downloaded and installed MQTT fx, open the application. You will see the following screen. Click on the gear icon.
Click on the plus icon to add a new connection.
To configure the MQTT connection, you need to configure the following connection parameters (see the screenshot below).
- Profile Name: The name of your connection.
- Profile Type: MQTT Broker
- Broker Address/Hostname: You need to pass the URL to your tenant. Append mqtt. To the URL. (e.g. mqtt.Cumulocity -dev.com)
- Broker Port: Set this to 1883.
- Client ID: You can use the "Generate a random ID" button (most tools will offer such a button) or fill one in yourself. This ID will be linked to your device..
The rest of the configurations are not relevant and therefore we will use the default values. Now navigate to the User Credentials tab and set the following properties.
- Username: You need to enter your tenant and username separated by a slash (tenant/username). You can use the same user that you use for logging into Cumulocity for this example.
-
Password: The password of the user.
Hit the apply button and your connection should be created. Now click on the connect button to connect to the MQTT Broker. The connection icon in the top right should turn green. You can also look into the Log tab for further details.
You are now connected with the MQTT Broker for CUMULOCITY. We will now look into how we can create a device in the CUMULOCITY platform, by sending messages to the Broker.
Sending Data
As mentioned earlier, there are predefined topics in CUMULOCITY. All MQTT "publish messages" in this tutorial will be sent to the topic "s/us". This is the topic used for CUMULOCITY Core's pre-provided static templates. CUMULOCITY Core provides predefined static templates, which are based on CSVs. The platform knows how to process such messages. For more information regarding SmartREST, refer to: https://docs.Cumulocity.com/guides/rest/smartrest/
Creating the device
The first message sent will create our device. Although the static templates support automatic device creation, in this example we will create the device manually. The template "100" will create a new device. It can be used with two optional parameters (deviceName, deviceType).
- Enter s/us in the text area.
- Then select Qos 0.
- Enter the code snippet into the message body:
100,My first MQTT device,c8y_MQTTdevice
- Click on the Publish button.
Navigate to the Log tab to check if the message was successfully published.
Afterward, you will find this device in the "Device Management Application" as a new device.
If you go to the identity tab of the device you will notice that there was an identity created automatically to link the device to the MQTT ClientId. Besides the name and the type, the device is empty so master data needs to be added.
Creating measurements
Now the device has some master data and we can start sending some measurements. There are a couple of measurements that can be created directly by using a static template:
- 210: Signal strength measurement
- 211: Temperature measurement
- 212: Battery measurement
The temperature and battery measurement just take the value and time as parameters. For the signal strength, you can pass two values .
Publish the following message:
210,-87
211,24
212,95
Always check the logs for details. After successful completion, you should see the measurement tabs is created on the device page.
Besides the measurements above we can also use the template "200" to create a more custom measurement. It will take the measurement fragment, series, value, unit, and time as its parameters.
200,myCustomTemperatureMeasurement,fahrenheit,75.2,F
After publishing this message, check if the new measurement shows up on the UI.
Creating alarms
In the next step, we want to create some alarms for this device. There are 4 templates to create alarms for the 4 alarm severities:
- 301: CRITICAL
- 302: MAJOR
- 303: MINOR
- 304: WARNING
Each of them note a type (which is mandatory), a text and a time (both optional).
301,gpio_critical,There is a GPIO alarm
304,simple_warning
Publish the message and check the platform for the changes. The alarm list of your device should now contain one critical alarm and one warning. Note that we did not set any text for the warning therefore it was created with a default alarm text.
With the next step, we want to clear the critical alarm again. To achieve this we use the template "306" which refers to the type of alarm that should be cleared. Publish the following message.
306,gpio_critical
Afterward, the critical alarm should be cleared. Note that you did not have to handle any alarm IDs with the MQTT implementation. CUMULOCITY Core will take over this part so that the device communication can be as easy as possible.
Creating Events
Next, we want to create some location events for the device. You can use this website https://www.latlong.net/ to get the latitude and longitude for your city if you want. The template "401" lets you create location events and takes latitude, longitude, altitude, accuracy and the time as parameters but for now, we will just use the first two. Publish the following message.
401,51.227741,6.773456
In "Device Management" you can see one event in the event list but the location has not been updated.
Receiving data
So far we have only used MQTT to send data from the client to the server. Now we want to send data from the server to the client. To achieve that we first need to subscribe to the responsible topic. We will do two subscriptions:
- s/ds : This will subscribe to the static operation templates for the device
- s/e : This will subscribe to an error topic that can be used for debugging
Navigate to the Subscribe tab in MQTT fx. Enter both topics one after another in the subscribe field and hit subscribe. The QoS selection does not matter for this example.
Afterward, your MQTT fx should look like this:
Receiving operations
At the current state the UI does not show any tabs for operations. Up to this point, it was unknown what exactly the device supports. But the list of supported operations can be modified with the template "114". A list of supported operations can be added here. We will add support for the configuration and shell.
Go back to the Publish tab and publish the following message.
114,c8y_Command,c8y_Configuration
After reloading the UI the two new tabs should appear ("Configuration" and "Shell").
We can now create a shell command from the UI and click "Execute". Enter a dummy command and click execute. Now open MQTT fx. You should be able to see the messages that you had sent.
