Comarch IoT Platform is a dedicated cloud application for all our IoT devices. With IoT Platform tailored to your needs, viewing the information collected by the devices is a breeze. We propose a solution which is:
-
intuitive – because navigating through the interface should never be frustrating, or consume too much of your time;
-
scalable – the database and its possibilities are ready to grow along with your business;
-
secure – all the data is encrypted, and the user access management is highly customizable;
-
reputable – many companies successfully use the Platform along with our IoT devices.
IoT Platform can be best described as a three-part system:
-
On the device side, there’s an interface which allows the devices to automatically send the data in real time, using a protocol such as MQTT or LwM2M;
-
At the core lies a cloud-stored database, in which the device data is saved;
-
The app external interface provides easy access to the data – both through a REST or Websocket API (for vertical applications) and through a website (for humans).
The architecture of Comarch IoT Platform – Smart Metering and Asset tracking are examples of our vertical applications.
To summarize – the IoT Platform most important functionalities include management of the IoT devices, telemetry, and an interface suitable both for users and for other applications.
Overview of the manual
The next chapter, "Getting started", provides a hands-on guide to basic configuration of the platform and the devices. It covers both the workflow setup and security management. Most of the tools and functionalities are described briefly here, and more details can be found in the following chapter "Components", which contains a description of every module of the Platform. For even more details and specifications, refer to the technical documentation.
Getting Started
Account creation
An individual account should be created for every person working on a project. Accounts are highly customizable in terms of access rights, and provide personalized dashboards for every person involved.
A project is a container for all devices working together. Their state and indications can be viewed within a project. Projects are isolated from each other.
At this point, either you have been granted an administrator account, or you have been assigned an administrator from Comarch to begin the setup for you. Feel free to contact us if you’re not sure which is the case. If the account has been pre-created for you, you can skip the next section and proceed to Connecting your first device.
Creating new accounts for users
Creating new user accounts is essential before you can add them to the project. If you have an administrator account, you can create new user accounts for your clients or coworkers. Visit https://{host}/auth/admin/master/console/host
-
Provide permissions. Proceed to section "Users" in the menu on the left, and provide the tenant administrator manage-users and view-realm permissions, as shown below:
-
Add new users. Log in as the tenant administrator and proceed to users management console at
https://sso.{host}/auth/admin/{tenant}/console/#/realms/{tenant}/users
-
As the user, check your email. An email with a temporary password will have been sent to the user. After logging in, the user will be prompted to change their password, and then redirected to the IoT Platform.
Creating new project
Visit the project site and log in with your credentials. You’ll be redirected to the projects directory. Click "Add new project" to create a new one. You should see the following window:
-
Project ID should be unique, but it’s not an issue at the moment as you are creating your first project. It’s best to choose something both short and descriptive, like the name of your service, or a key word that everyone will understand. Most important things to keep in mind are that it cannot be changed later and is case-sensitive.
-
Name does not have to be unique, and can be changed later. Think of it as something less binding and more arbitrary.
-
Description can (and probably should) be longer than the name, and should provide a brief summary of what the project is about.
After you click "approve", the project will be seen in the dashboard as follows:
Click on the project tile to select it. The project’s properties (name and description) can be modified by clicking the cogwheel icon:
Connecting your first device
To connect your first device, go to section "devices" and click "Add new device(s)". You should see a "Select device source" screen. You can either define device by yourself or define few devices. For your first device, it’s recommended to choose the first option. Click "next".
Option 1: Defining device by yourself (wizard)
You should see an "Add device screen". Here you can provide basic information about the device.
Device ID: unique indentifier of the device. It will be needed when you decide to assign rules or a channel to this device. If this section remains empty, the system will generate a random ID for you. The device ID cannot be changed later
Name: it helps you recognize devices easily. It does not have to be unique and can be changed later.
Device type: it depends on the type of device you are connecting. Click on the input window to see an expandable list, and choose the correct device type:
Tags: tags allow grouping devices according to your needs. After assigning a tag to a device, it’s possible to search for them easily by the tag, which is especially helpful if the project contains a lot of devices. One device can have multiple tags assigned.
Attributes: values not define directly on model, like geolocation. Attributes are added in JSON format.
The second step is adding properties to the device.
Depending on the device, it could be battery level, temperature, and more – for full list of properties available for your device, refer to its documentation. One device can, of course, have many properties. Here, you can add the following information:
Property Id: unique name (address) of property of device. While creating the first property, you can for example type "online".
Name: it does not have to be unique, rather descriptive. It can be the same as ID, for example the name "online" or "temperature" are perfectly valid – they’re both short and self-descriptive.
Description: description of device property , expressed as string (text value), double (numeric value), boolean (true/false), or data (other, specific data). For property "online", "boolean" is the correct type.
Unit: unit of the property, e.g. % or dB. You can also leave this field blank, for example for a property like "online".
The third step, channels, defines ways of connecting with the IoT Platform. IoT Platform supports connection via MQTT and LwM2M protocols. In this step, you can configure connection addresses, topics, credentials, etc.
|
Warning
|
Setting up a channel is necessary for the device to communicate with the Platform. |
The section "Available for assignment" contains created channels available to assign to a device. Most probably, there are no channels at this point and it is necessary to create one. To do so, select section "Create new channel".
-
Channel ID: unique identificator of the channel, like "outdoor-channel-3" or "d3th-3i54-12h4-294b".
-
Name: more descriptive, and not necessarily unique, name of the channel.
-
Description: a brief yet comprehensive description of the channel.
-
Type: refers to the type of the protocol – either MQTT or LwM2M.
-
Device ID: list of available devices. Select the preferred device’s ID from the expandable list.
-
MQTT Password: channel password of your choice. After entering the password, write it down in a safe place.
|
Tip
|
To change the password in the future, select tab "channels", find the channel you’d like to change password to, and click the three dots next to channel type. Select "edit", click the "I want to type new MQTT password" checkbox, and enter the password of your choice. |
Option 2: Define few devices (JSON)
It is also possible to add multiple devices using JSON-formatted text.
In the prompt text, you can see a sample formula for adding multiple devices. This view contains a built-in JSON validator, so a message will be shown if you miss any coma or a bracket. To finish, click "Add devices".
Creating a rule – introduction to rule engine
The rule engine allows you to set up a notification system in cases when you’d like to be informed about particular events, e.g. the device going offline or exceeding the limit of messages sent per hour. You don’t have to create any rule for the device setup to work, so you can skip this step now. Detailed instruction to creating rules is covered in section [Rule Engine].
Introduction to dashboards
To see the values of device properties, it is necessary to create a dashboard. When you first select "Dashboards", you should see a message saying "There is no dashboard available in this project". To create the first dashboard in the project, click "Add new dashboard". One project can have multiple dashboards. When creating a dashboard, you can give other users limited access to the content on the dashboard.
-
Guest: read-only. Guest can’t create and modify anything on projects.
-
Technician: read-write. Technician can read, create and edit the content on projects.
-
Owner: read, write and managing – beyond the technician functions, the owner can manage users in the project.
After clicking "Add dashboard", you should see a notification confirming successful creating of the dashboard. You can edit its properties and privacy settings (access rights) by clicking the cogwheel icon and choosing "edit dashboard". You can also toggle autorefresh, and set its time interval. Now, you can add widgets to your dashboard.
Widgets
A widget is a tile on the dashboard that displays the device property of your choice. When added to the dashboard, they will look like this:
A single value widget.
Or, in case of table and graph widgets, like this:
A table widget with three properties.
A graph widget, perfect to visualise values that change in time.
Adding new widget
To add a widget, click the "Add new widget" button. You should see the following screen:
-
Widget title is what will be shown on the dashboard, at the top of the tile.
-
Widget category can be either single value, graph, or table, as pictured above;
-
Device – the device which property you’d like to show, as indicated by its ID
-
Category: Properties (this should be the only possible option in this case)
-
Property: select the property of your choice from the expandable list.
Adding collaborators and securing your device
To ensure restricted access to the project, remember to give permissions only to your authorized coworkers. To add more people to the project, select "Members" and click "Add new members":
|
Warning
|
Make sure the users you want to add already have an account. If you have been granted an administrator account, make sure you have followed the instructions in Creating new accounts for users. |
You should see a window prompting you to add a new members to the project. To add a collaborator, type their email address and click "Add". By default, the new member will be added as a guest, but their role can be changed afterwards. To change the role, choose another from the expandable list:
Detailed information about scopes of particular roles are covered in section [Managing roles].
After completing all above steps, your project should be all set up and working. The next chapter provides more detailed information about each of the Platform’s components.
Components
This section provides more detailed description of each of the Platform’s components and their functionalities not mentioned in Getting Started section.
Device Management
List of devices and editing properties
Go to section "Devices" to see the full list of the devices in your project. To edit the device, click Action… and Edit device:
Here, among adding other attributes, you can apply geolocation tag to the device. Click on the map (or enter a JSON-formatted text, if you wish) to generate property "geolocation".
|
Warning
|
"Geolocation tag" is not a tag as used in "device tags". The resemblance is coincidental. |
While editing properties, you’ll approach the name device twin. A device twin is not a physical device, but a JSON document. For the time being, you can leave the field "desired propierties" blank. We’ll talk more about device twins in section Connectivity.
Filtering devices
It’s possible to filter the devices in the project using the filter field:
You can filter the devices by ID, name, device type, or tags. To filter, you need to use query syntax, for example: name:mydevice
|
Tip
|
If your device’s name contains spaces (for example "Temperature sensor", do not put in in quotations. Simply write |
|
Tip
|
The filter input is not case sensitive, meaning that you can filter by |
Connectivity
Command&Control – what you tell the device
When you change a setting on a device – for example, you add new property "online" or change the geolocation tag – you don’t connect directly to the device; rather, you change the contents of a device twin – a JSON document associated with your device. The changes in device twin are submitted to an MQTT topic which the physical device subscribes, meaning that it watches constantly for any changes and will update its state accordingly.
The main advantage of such solution is that the physical devices don’t have to be constantly connected to the Platform. If any of them goes offline, you can still operate on it on the Platform or change its properties. When the physical device goes back online, it will update its state according to the changes you made.
Telemetry – what the device tells the Platform
After the device changes its state, it sends its values to the Platform so you can see them in device history and visualize them on widgets. The history of all devices connected to the Platform are safely stored in Comarch Data Centers located around the world.
Rule engine
To create a rule for a device, go to section "Rules" (from the menu on the left) and click "Add new rule". A rule wizard will launch.
The first step of the wizard is entering basic information, consisting of:
Name – a descriptive name which will be seen in the rules dashboard, Description – a short description of the rule, Active – status of the rule (on/off).
The second step determines the conditions of the rule. The condition can either monitor the messages quota, messages throughput, or device property value.
a) Metrics quota allows you to monitor the number of messages sent by a device. For example, you might want to be notified when the total number of messages in the channel exceeds 100.
Operator – a mathematical operation to be performed on the property value;
Treshold – expressed as a number, determines the value to compare with the quota.
b) Metrics Throughput allows to examine the number of messages in a set period of time.
Channel ID: unique ID of the channel you’d like to set the condition on. Operator: the mathematical operation to apply Threshold: a number to compare the value with.
c) Device property value allows you to monitor the device state, e.g. the value of property "online" or "battery_level".
|
Warning
|
The properties need to be added to the device before setting a rule concerning them. |
Device: ID of the device you’d like to monitor.
Property: upon a click, a list of created properties will show. Choose the property you’d like to set the rule on.
After choosing a property, more settings for this property are shown. Depending on the property value, new options to set up a rule are shown. They vary depending on whether the value is numerical or non-numerical (string).
|
Tip
|
The option "ignore case" makes the strings comparation non-case-sensitive. |
After you finish, click "next step". The next step of the wizard sets the conditions for triggering the rule:
When: condition for triggering the alert – should all conditions be fulfilled, or only one.
Message: contents of the message which will be visible in section "Alerts".
Dampening: this functions prevents triggering the alert if an event occured e.g. only once, or in general less than the set number. It prevents one-off events – like, for example, a rise in temperature due to opening the fridge – from triggering the alert. Set the number to 0 if you’d like to be informed about every event without any dampening.
The last step defines the action to be performed after fulfilling the condition of the rule:
Notification "Send email": after fulfilling the condition, an email is sent to the chosen address with contents specified in "body".
Notification "MQTT action": allows to send an MQTT message to the address and topic of your choice. URL, topic, MQTT password and message body can be specified in this step.
-
URL: MQTT broker address.
-
Topic: the queue topic. Keep in mind that MQTT topic are case-sensitive!
-
User: the username of the subscriber
-
Password: the subscriber’s password
-
Body: the message text to be sent to the queue
Notification "WEB action": A HTTP request can be sent to a set URL. In this view, you can specify the URL, HTTP method and the request header and body.
Managing the roles
This section provides detailed description about scopes and limits of particular roles.
Guest is only here to view the project. They can’t see any dashboards or widgets, edit devices, channels or rules, or create new ones.
Technician has editing access to dashboards, widgets, channels and rules, but they can’t manage users in the project.
Owner, beyond the scope of the technician, can manage other members of the project and change their roles.
Accounting
When you use the Platform, you pay proportionally to the amount of data you used. The data is used when you send some information to the Platform or retrieve it. The accounting module is responsible for tracking the resource consumption. We implemented it through a system which can be divided into three components: an agent, responsible for tracking the usage of the data, storage, and a REST API allowing you to track the consumption yourself.
|
Warning
|
The storage only contains data from the last two months. If you need older accounting history, you’ll need to back it up on your side. |
Device history
The Platform implements the cold-warm-hot data framework, which allows for fast and reliable data retrieving. From the user’s point of view, the history of properties sent by the device can be displayed in a couple of ways.
Visualizing data from devices
Every device sends values of the declared properties to the platform. The device history can be seen either in a form of a list or as a graph. To view device history, click on the three dots next to the device, and select "Show device history":
The default form of viewing device history is a table. Here, you can switch to graph view (A), choose the property to be displayed (B) or choose the date range to filter the displayed results ©:
Moving the mouse above the graph lets you see precise coordinates of the point and the property value at this point (in this case, 1 234).
