2025IoT-project-ThingsBoard/report/report.md

# ThingsBoard Assessment

Team 8

Jarne Clauw
Tibo De Peuter
Mathis De Witte

## Introduction

Idk small introduction text

## ThingsBoard installation

Setup of ThingsBoard...

## Using ThingsBoard for Telemetry Data Injection

In this guide, we will walk through the process of setting up and using ThingsBoard to inject telemetry data. This includes creating a tenant (i.e. a business that owns or produces devices and assets), adding customers (i.e. an individual, or an organization that purchases or uses tenant devices and / or assets) and devices, and visualizing data on a dashboard. By the end of this section, you will be able to monitor telemetry data live in ThingsBoard.

### Creating a tenant

A tenant is the highest-level organizational unit in ThingsBoard, and all other entities like customers, devices and dashboards are linked to a tenant.

Start by navigating to `http://localhost:8080`, where you will land on the login page. Use the following credentials to log in:
- **Email**: `sysadmin@thingsboard.org`
- **Password**: `sysadmin`
Once logged in, you will be redirected to the home page.

![Sysadmin home page.](images/sysadmin_home.png)

To create a new tenant, go the the **Tenants** page from the sidebar and click the **+** icon
, or click **Add Tenant** button directly from the home page.

![Creating a tenant.](images/create_tenant.png)

Fill in the required information for the tenant and click **Add**. The tenant will appear in the tenant list.

![List of tenants.](images/tenant_list.png)

To enable login for the tenant, you need to create an admin user. Click on the three dots next to the tenant name and select **Manage Tenant Admins**. Fill in the user details and click **Add**. Activate the account via email if needed.

![Creating a tenant admin.](images/create_tenant_admin.png)

If successful, you will be redirected back to the home page, but now logged in as the tenant's sysadmin.

![Tenant home page.](images/tenant_home.png)

Now that the tenant is set up, we can proceed to add a customer in the next section.

### Setting up a customer

A customer represents an organization or group that will have access to specific devices and dashboards. We will set everything up as the tenant administrator account.

In the **Customers** section, click the **+** icon to create a new customer.

![Creating a customer.](images/create_customer.png)

Once created, the customer will appear in the customer list.

![List of customers.](images/customer_list.png)

To create a dashboard for the customer, navigate to the **Dashboards** section and click **Add Dashboard**. This will create an empty dashboard. Always make sure to save the dashboard before leaving the page.

![Creating a dashboard.](images/create_dashboard.png)

To inject data into the dashboard, we need to add a device from which the data will come. Navigate to **Entities > Devices** and click **Add Device**.

Fill in the required information for the device and assign it to the customer created earlier. After adding the device, you get a screen showing the instructions on how to send telemetry data to the platform.

![Adding a device.](create_device_1.png)

![Device credentials instructions.](images/create_device_2.png)

For HTTP it essentially comes down to the following.

```
curl http://<server>/api/v1/<access_key>/telemetry --header Content-Type:application/json --data "{<key>:<value>}"
```

When you try this out, you should see that the device is active and telemetry data has been received.

![An active device.](images/device_active.png)

The last thing we need to do as a tenant, is to create a regular user account.

Navigate to **Customers** and click on **Manage customer users**. Click on the **+** icon to add a new user and fill in the required information.

![Creating a user](images/create_user.png)

After activating the account, you will be redirect to the home page of this user account. This user can not change any settings to the dashboard, devices ... as this is a read-only account. You could give the user the right privileges through role-based permissions, but this requires the Professional Edition of ThingsBoard!

### Visualizing telemetry data

Now that the everything is set up and we are able to send telemetry data, we can visualize the data on the dashboard. To make changes we need to be logged in as the tenant!

Navigate to **Dashboards** and select the dashboard associated with the customer. Edit the dashboard and click **Add Widget**. We chose for **Charts > Line Chart** as our visualization. The chart has many options, but we will set the most basic ones.
- Changed the window to display the last 10 minutes.
- Chose the created device as our source.
- Changed the series to use the `memory_used` key-value pair.
- Changed the series to read from MB but convert to GB
- Changed the Y axes to better display the memory used.

![Creating a widget on the dashboard.](images/dashboard_widget.png)

To make this dashboard a live display of the memory used, we need to keep sending telemetry data. This is why we made a small script to do this, and made it as a docker service.

```bash
while true; do
	memory_used=$(free -m | grep 'Mem' | awk '{print $3}')
	curl -s http://thingsboard-ce:8080/api/v1/qTbjXOHQTgRYzjbn3UxF/telemetry --header Content-Type:application/json --data "{memory_used:$memory_used}"
	sleep 1
done
```

This should send the used memory to the platform every second.

The following is how the dashboard looks from the user account.

![Dashboard from the perspective of the user.](dashboard_customer.png)

A lot more can be done, but then we suggest to read the [documentation](https://thingsboard.io/docs/).

## Discussion

### Question 2
Q: *Due to processing constraints, one of our end nodes cannot convert the measured voltage
from a TMP36 sensor to temperature. Is it possible to accomplish this conversion at
Thingsboard? How this could be done?*

A: Yes this is possible, there are generally two ways of doing this:
1. You could add a script node to the rule chain which receives the (voltage) sensor data and transforms this into the temperature through a certain function.
2. There is now also a new feature in Thingsboard called "Calculated fields". This way is generally more elegant as it doesn't require you changing the rule chain. The calculated fields can be configured at both the device level and the device profile level. We can either use a "Simple calculated field" for simple arithmetic functions, or we can use a "Script calculated field", which allows us more control over the computation on the data. These scrips are written in a language called "TBEL".

sources:
- https://thingsboard.io/docs/user-guide/rule-engine-2-0/overview/
- https://thingsboard.io/docs/user-guide/rule-engine-2-0/tutorials/transform-incoming-telemetry/
- https://thingsboard.io/docs/user-guide/calculated-fields/

### Question 3
Q: *We have a node monitoring pumps vibration on a water station. We need to predict when
vibration will reach critical levels so we can schedule preventive maintenance for the pump
and avoid unplanned downtime. Briefly describe how this could be accomplished with
ThingsBoard.*

A: This too can be done by calculated fields. For this field we would probably want to use a "Script calculated field" as it allows us to access historical data (through the variable ctx). The function will need to do some analysis on thi historical data and based on that estimate when a device would need preventive maintenance. The output of this script should be an Attribute, as we want a single answer for when to plan the maintenance.

source:
- https://thingsboard.io/docs/user-guide/calculated-fields/

### Question 4
Q: *Alarms are an important part of telemetry monitoring. Describe how they work in
ThingsBoard and what options are available to send notifications when an alarm is triggered.*

A: Alarms are defined for certain device profiles which you choose. If certain telemetry data is sent that meets certain conditions, the alarm will be triggered. This will be visible in your notifications. The alarms can also be displayed in a dashboard that is associated with a device of the device profile.

Personalized notifications can be delivered via email, SMS or other third party systems through the Notification Center.

It's also possible to send notifications to your smartphone through the Thingsboard Mobile Application

sources:
- https://thingsboard.io/docs/user-guide/device-profiles/#alarm-rules
- https://thingsboard.io/docs/getting-started-guides/helloworld/#step-6-alarm-notifications

## Conclusion

Conclusion and lessons learned

## References

Do we add them to where we use them or here at the end of the report?