1. Using web interface

This tutorial will show how to do basic operations in dojot, such as creating devices, checking its attributes and creating flows, import/export, firmware update, generating certificates and device history report.


  • Who is this for: entry-level users

  • Level: basic

  • Reading time: 20m

1.1. Device management

This section will show how to manage device. For this tutorial we will show how to add two thermometers and a virtual device that will represent an alarm system that will monitor both sensors.

As described in Concepts, all devices are based on a template. To create one, you should access the template tab at the left and then create one new template, as shown below.

To create new devices, you should go back to the devices tab and create a new device, selecting the templates it will be based on, as shown below.

Note that, when you select the template in the right panel at device creation screen, all attributes are inherited from that device. You could add more templates as needed, keeping in mind that templates used to compose a device must not share an attribute with the same name.


As devices are tightly associated to templates, if you want to remove a template, you should remove all its associated devices first. If such thing happens the following error message will appear:

Error message when removing an used template


You can add and remove attributes from templates and they will be immediately available to devices. In case of new attributes being added, though, you should keep in mind that there must not be any device with templates which have attributes with same name. If such thing happens, the following message will appear:

Error while adding overlapping attributes

This snapshot was generated by creating a new template (ExtraTemplate) with one attribute, called level. Then a new device based on both templates was created and, afterwards a new attribute also called level was added to ThermTemplate.

When this happens, no modification is applied to the template (no attribute named “level” related to the “ThermTemplate” is created). However, it remains in the template configuration so the user can figure out what is happening. If the user refreshes the page, it will be reverted to what it was before the modification.

Now the physical devices can send messages to dojot. There are few things to pay attention to: the MQTT topic is <tenant>:<device-id>/attrs.

For simplicity’s sake, we’ll emulate one device using mosquitto_pub tool. We set the username parameter by using the -u flag of mosquitto_pub. See more about in Using API interface at topic Sending Messages.


In the videos we are using Mosca as the MQTT broker, so the messages are being sent to topics in the old format. If you are using VerneMQ, change them according to the forementioned pattern. Check Frequently Asked Questions for more info about the differences between them.


The examples are using insecure MQTT. The recommended approach is to use TLS. Check the section Using MQTT with security (TLS).

Now that we’ve created the sensors, let’s create a virtual one. This will be the representation of a alarm system that will be triggered whenever something bad is detected to these sensors. Let’s say they are installed in a kitchen. So it is expected that their temperature readings will be no more than 40C. If it is more than that, our simple detection system will conclude that the kitchen is on fire. This alarm representation will have two attributes: one for a severity level for a particular alarm and another one for a textual message, so that the user is properly informed of what’s happening.

Just as for “regular devices”, virtual devices also are based on templates. So, let’s create one, as shown below.

1.2. Flow configuration

Once we’ve created the virtual device, we can add a flow to implement the logic behind the alarm generation. The idea is: if the temperature reading is less than 40, then the alarm system will be updated with a message of severity 4 (mildly important) and a message indicating that the kitchen is OK. Otherwise, if the temperature is higher than 40, then a message is sent with severity 1 (highest severity) and a message indicating that the kitchen is on fire. This is done as shown below.

Note that the “change” nodes have a reference to an “output” entity. This can be thought as a simple data structure - it will have a message and a severity attributes that match those from the virtual device. This “object” is referenced in the output node as a data source for the device to be updated (in this case, the virtual device we’ve created). In other words, you can think of this as a piece of information carried from “change” nodes to the “virtual device” with names “msg.output.message” and “msg.output.severity”, where “message” and “severity” are the virtual device attributes.

So, let’s send a few more messages and see what will happen to that virtual device.

1.3. Import and Export

This section shows how to use the Import and Export features. These options allow your configuration data to be saved to a file, for Export, and loaded to dojot, for Import. This file has the JSON format and it contains the data from templates, devices, flows, remote nodes, and scheduling tasks that were entered in your tenant. To perform data configuration export procedure, expand the menu at the top right of the page, click “Import / Export” and then “Export” as shown below:

The exported file can be stored as a backup and later imported back into Dojot.

To perform data configuration import procedure, expand the menu in the upper right corner of the page, click “Import / Export” and then “Import.” In the window that appears it is possible to drag and drop your file or browse to the destination folder and select it. It is only allowed to add a JSON extension file, in the expected format, as illustrated in the following video:


When performing the import procedure all current tenant configuration, such as: devices, templates, flows, remote nodes and scheduling tasks, will be permanently deleted, so that new ones are created. History data is not part of importing and exporting!

1.4. Firmware update

During the lifetime of a device, you may need to update control software (firmware) to correct some issues you encounter while using it, or even add new features. Dojot currently supports the firmware upgrade procedure via the LwM2M communication protocol. For details regarding the procedure for integrating with your device please check the LwM2M protocol specification. If your device communicates via this protocol and has the firmware update procedure in place, you can follow the steps below to update your device version.

The firmware upgrade process consists of three steps:

  • image management;

  • image transfer to device;

  • image application on device;

The details of their implementation are as follows.

In order to enable the firmware management you must create a template and, once saved, enable the firmware manager. After that, you can upload the firmware images to the dojot repository that are associated with this template. Attention: the image extension must be “.hex”.

Note that when Firmware Manager is enabled, five attributes are assigned to the template. They are used to support image updating. Attribute names can be edited as required by the application. The attributes are:

  • Device State:

    • Current state of firmware update

  • Result of apply version:

    • Contains the result of downloading or updating the firmware

  • Sets which version to transfer:

    • Indicates to the IoT agent responsible for the device, what is the name and version of the firmware image to be downloaded and updated on the device

  • Trigger version update:

    • Actuator used to initiate firmware update procedure

  • Current version of the image:

    • Current version of the firmware image, provided by the device

After you create the template with the Firmware management option enabled, you can associate it with a device. So, you can then transfer an image and apply it to the device, as shown in the video below:

Note that in each step, the status and result of image processing are shown.

1.5. Generating certificates for devices

This section will show how to generate x509 certificates for a device, so that dojot can communicate with devices securely via TLS. To be able to send a publication, it is necessary to download the three files, the private key “admin 4302d4.key”, the device certificate “admin 4302d4.crt” and the CA certificate “ca.crt”.


The generation of certificates via the graphical interface (GUI) only works in deployments where it is possible to access the GUI via HTTPS or localhost.

To be able to execute the command of the example video it is necessary to be in the same directory as the 3 files attached. Command used in the example:

mosquitto_pub -h localhost -p 8883 -t admin: 4302d4/attrs -m '{"humidity": 7}' --cert "admin 4302d4.crt" --key "admin 4302d4.key" --cafile ca.crt

1.6. Generating device history report

This section will demonstrate how to generate a device history report. The report is able to show data for one or more attributes of the respective device. For this, it is necessary to select the desired attributes, define the period and click on “generate”.

1.7. Performing access to the Dashboard

The dashboard is part of GUI-V2, to access it you need to use another URL, in the current version just add to the end of the URL “/v2” in relation to the interface used in the previous items, for example, in the case of localhost it would be http://localhost:8000/v2, see more at Components and APIs. The login and password credentials are the same as those used in the rest of dojot. After logging in, a new screen will open and an ADD button will appear in the upper right corner, which will give you the options for various types of viewing. At this moment, in the first “General” screen it will be necessary to add a name for the visualization and optionally a description. The list of devices will appear on the next screen, if you do not find the desired device, you can search by name. After selecting the device, the attributes that are linked to it will be listed, and a color can be chosen to display each attribute, it is also possible to add a caption for each attribute. In “retrieve records by:“ it will be possible to configure some filters, you can select the type of historical data filter as the “last records”, in “order” (minute, hours, days and months), and you can also choose an interval time, in addition you can still view the records in “Real time”, as new data is received they will be displayed in the chosen view. After everything is configured, a summary will be shown with the chosen name and attributes. When accessing the views, it will be possible to change the size, fix (which will disable the option to change the size) and still delete the views.