Starter Guide

In this section, we will go through most of Cervello features by creating a simple fleet management solution using a virtual device simulation.

We will be using MQTT protocol in this section and MQTTBox, which is a MQTT client that can mimic a real sensor.

Other than MQTT, Cervello supports other connectivity protocols HTTP Protocol, CoAP Protocol

We will go through this guide in 7 steps:

Step 1: Login to Cervello

Step 2: Create an organization

Step 3: Create and configuring the device

Step 4: Connect the device

Step 5: Sending data to Cervello

Step 6: Visualizing device data

Step 7: Creating rule engine and Alarms

Step 8: Displaying alarms

Login To Cervello

Use your username and password to login to your Cervello account.

Login Page

To get a Cervello account, please contact us on support@cervello.io

Create an Organization

Once you are logged in, you can create a new organization by clicking on the Create Organization button.

Organizations List

Insert an organization name, and an optional description then click on OK button.

Organization Form

Choose the organization you have just created.

Create and Configure the Device

Devices are the core power of any IoT platform.

In a later chapter we will talk about devices with more information and how efficiently Cervello can handle vast amount of data from large and different types of devices.

You can create a new virtual device by clicking on Create Device button. Device Info Page You will be redirected to the devices page where you can insert data for the device. Create Device Form Insert data for the device then click OK to submit your virtual device.

Connecting the Device

We have successfully created a virtual device, now we can connect a physical device or a device simulator (MQTTBox in our case).

In order to connect any device/sensor to Cervello, you must obtain 3 keys (Device ID, Access Key, Access Token).

Lets first create access credentials to our virtual device.

Open the device actions dropdown and click on Manage Credentials. Manage Credentials Click Generate Credentials to create access credentials for this virtual device. Device Empty Credentials A new form will appear containing the access key and access token that we need to connect to Cervello. Device Credentials Data Note: Access credentials can only be used by one device at a time.

Copy the device ID and the other keys and save them securely, we will use them later.

Download and open MQTTBox

Click on Create MQTT Client to add a new client. MQTTBox Fill in the settings form to configure connecting to our virtual device MQTTBox Settings

MQTT Client Id: is the virtual device id.
Username: is the virtual device access key.
Password: is the virtual device access token.
Protocol: mqtt / tcp.
Host: broker.cervello.io.

And finally make sure that Append timestamp to MQTT client id? is unmarked.

Click on Save, and if everything is configured correctly, the top status button should show Connected text, and that means ou

Once you click Save, if everything is configured correctly, the top status button should change to Connected. MQTTBox Settings

And the Connection Status for the virtual device will also change to Connected MQTTBox Settings

That means our device is connected and authorized to communicate with Cervello.

Sending Data to Cervello

In this step we are going to explore how to send data from a device to Cervello using MQTT protocol.

Cervello offers huge flexibility in communications and doesn’t restrict publish topics or specific schema for the message payload.

Communication with Cervello through MQTT can be done in two ways:

Using procedural topic and payload schema

This is useful for a plug & play scenario.

Devices must send MQTT messages to the following topic format:

Telemetry data: /cervello/devices/{deviceId}/telemetry
Attribute data: /cervello/devices/{deviceId}/attribute

To find all device’s topics, go to the device page and click on Topics tab from the left-side items. Device Topics

Additionally, the payload message must be in the following JSON object format:

{
    "data": {
        "key": value
    }
}

Where key is the telemetry key, and value is the telemetry value.

Using custom topic and payload schema

This allows you to use customized topics and payload for communication through MQTT, this helpful in many cases, for instance, access to firmware is limited and changes will take a lot of time.

See VPI chapter for more details on how to use custom communication settings.


In this tutorial, we are going to use Cervello procedural topic, let’s publish some telemetry data using MQTTBox

MQTTBox Telemetries

To confirm that the message has been sent successfully, checkout the device’s telemetries page and you should see the following: Device Telemetries

Cervello will store all telemetry data sent by the device, in the next step we are going to explore how to bring data to life with visualizations.

Visualizing Device Data

First we need to assign the device to an application.

For details about application and how to create new application, please see the Application Manager chapter.

Create an application and from the device drop down actions click on Assign To Application and search for the application that you created. Device Topics Device Topics

Now go to the application and choose Dashboards from the side menu then click Create Dashboard. Application Dashboards

This will prompt you to the dashboard editor where you can visualize your data in different ways.

Click on the Application Dashboards icon to get started.

You will find tabs containing different types of components. We are simulating a sensor that’s sending a car speed, so we need a component that displays last value. KPI components are designed for that purpose, so let’s click on KPI tab and choose Angular Gauge component.

Click on the Angular Gauge

You will be prompted to settings form where we can configure our component, Now we need to choose data source for the component to display.

Angular Gauge

Fill in the form items Angular Gauge

Then click Save Component

Now for every message that the device sends and has the key SPEED, this gauge component will update with it’s value.

Creating Rule Engine and Alarms

We have managed to monitor our device in real time, but we need to be notified if something unexpected happens, like if the SPEED goes above a certain value.

Cervello allows us to achieve this through a very simple and highly customizable rule engine using VPI Editor (Visual Programming Interface).

Go back to the application page and choose VPI Editor from the left-side menu VPI Form

Insert VPI name and click OK to create a new VPI

Click on the VPI name to be redirected to the VPI editor where you can create workflows.

You will find a list of different components on the left side menu (we will go through each one of them in the VPI chapter).

For now lets use the components we need which are Device Telemetry, Data Transformation, Rules, Debug and Save Alarm.

You can use the search field to quickly find components, then drag and drop them into the grid to be able to use them.

Most components in the VPI have an input to pass the data to it to process, and an output to pass the processed data to the next component.

To connect components, click on the output of one component, and draw a link with the mouse cursor to the input of another component and save the VPI. Now connected components in the workflow can send to each other data in order.

VPI Components

Click on the save button VPI Components to save the VPI components.

Device Telemetry: This component will allow us to obtain any telemetry data the selected device sends to Cervello.T

Data Transformation: Which will help us transform the received data to be in JSON format.

Rules: Rules component is where all the conditional logic will be happening.

Debug: Debug component will help us debug our workflow by outputting data into the console tab.

Save Alarm: Creates an alarm for the device with given data.

Now let’s configure each component.

Double click on any component to open the settings form.

In Device Telemetry settings choose our device and click save. Device Telemetry Settings

Next in Data Transformation: component, we need to transform data from JSON string to JSON object. Data Transformation Settings

Rules: this is where we can set logical conditions, in our case we need to create a rule if SPEED value is above 100. Rules Settings

Save Alarm: this is where we can set logical conditions, in our case we need to create a rule if SPEED value is above 100. Save Alarm Settings

Let’s send another value and see how our workflow goes. Save Alarm Settings

Click Publish and watch the VPI Save Alarm Settings

Great! a speed alarm has been created in the device, in the next step we are going to explore how to display a device alarms in the dashboard.

Displaying Alarms

Final step is to monitor the device alarms from the dashboard. Let’s go back to the dashboard manager and add another component.

From the Tables tab, choose Alarms Table. Dashboard Alarm

Fill in the settings options and select our virtual device and save the component Dashboard Alarm Settings

Finally we have a dashboard to monitor a device speed and display any alarms for the device. Dashboard Components