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 and firmware update.

Note

  • 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.

Now we have one template from which devices can be “instantiated”. All devices based on it will accept messages via MQTT that are sent to “/devices/thermometers” topic. 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.

Attention

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

Attention

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 card 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: as we defined the MQTT topic (all devices will send to /devices/thermometer topic), the devices must identify themselves using the client-id parameter from MQTT protocol. Another way of doing that is to just use the default topic scheme (which is /{SERVICE}/{DEVICE_ID}/attrs.

Just for the sake of simplicity, we’ll emulate one device using mosquitto_pub tool. We set the client-id parameter by using the -i flag of mosquitto_pub.

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 notification of severity 4 (mildly important) and a message indicating that the kitchen is OK. Otherwise, if the temperature is higher than 40, then a notification is sent with severity 1 (highest severity) and a message indicating that the kitchen is on fire. This is done as shown belown.

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.

If you are interested on how to use the data generated by these devices in your application, check the Building an application tutorial.

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:

Attention

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.

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.