ThingsBoard Edge supports only Kafka or in-memory queue (since v4.0) for message storage and communication between ThingsBoard services.
How to choose the right queue implementation?
#### ThingsBoard Edge service installation
In Memory queue implementation is built-in and default. It is useful for development(PoC) environments and is not suitable for production deployments or any sort of cluster deployments.
Kafka is recommended for production deployments. This queue is used on the most of ThingsBoard production environments now.
In Memory queue is built in and enabled by default. No additional configuration is required.
#### Step 4. ThingsBoard Edge Service Installation
To configure ThingsBoard Edge, you can use the following command to automatically update the configuration file with specific values:
```bash
@ -169,25 +151,21 @@ EOL'
{:copy-code}
```
##### [Optional] Database Configuration
In case you changed default PostgreSQL datasource settings (**postgres**/**postgres**) please update the configuration file (**/etc/tb-edge/conf/tb-edge.conf**) with your actual values:
```bash
sudo nano /etc/tb-edge/conf/tb-edge.conf
{:copy-code}
```
Please update the following lines in your configuration file. Make sure **to replace**:
- Replace 'postgres' with your actual PostgreSQL username;
- Replace 'PUT_YOUR_POSTGRESQL_PASSWORD_HERE' with your actual PostgreSQL password.
##### Configure PostgreSQL (Optional)
If you changed PostgreSQL default datasource settings, use the following command:
```bash
sudo sh -c 'cat <<EOL>> /etc/tb-edge/conf/tb-edge.conf
PUT_YOUR_POSTGRESQL_PASSWORD_HERE: Replace with your actual PostgreSQL user password.
##### [Optional] Update bind ports
If ThingsBoard Edge is going to be running on the same machine where ThingsBoard server (cloud) is running, you'll need to update configuration parameters to avoid port collision between ThingsBoard server and ThingsBoard Edge.
@ -206,7 +184,7 @@ EOL'
Make sure that ports above (18080, 11883, 15683) are not used by any other application.
#### Run installation script
#### Step 6. Run installation Script
Once ThingsBoard Edge is installed and configured please execute the following install script:
ThingsBoard Edge supports only Kafka or in-memory queue (since v4.0) for message storage and communication between ThingsBoard services.
ThingsBoard Edge supports SQL and hybrid database approaches.
In this guide we will use SQL only.
For hybrid details please follow official installation instructions from the ThingsBoard documentation site.
How to choose the right queue implementation?
In Memory queue implementation is built-in and default. It is useful for development(PoC) environments and is not suitable for production deployments or any sort of cluster deployments.
Kafka is recommended for production deployments. This queue is used on the most of ThingsBoard production environments now.
Hybrid implementation combines PostgreSQL and Cassandra databases with Kafka queue service. It is recommended if you plan to manage 1M+ devices in production or handle high data ingestion rate (more than 5000 msg/sec).
Create a docker compose file for the ThingsBoard Edge service:
##### In Memory
```bash
nano docker-compose.yml
@ -35,7 +57,6 @@ services:
volumes:
- tb-edge-data:/data
- tb-edge-logs:/var/log/tb-edge
${EXTRA_HOSTS}
postgres:
restart: always
image: "postgres:16"
@ -58,24 +79,20 @@ volumes:
```
##### [Optional] Update bind ports
If ThingsBoard Edge is going to be running on the same machine where ThingsBoard server (cloud) is running, you'll need to update docker compose port mapping to avoid port collision between ThingsBoard server and ThingsBoard Edge.
If ThingsBoard Edge is set to run on the same machine where the ThingsBoard server is operating, you need to update port configuration to prevent port collision between the ThingsBoard server and ThingsBoard Edge.
Please update next lines of `docker-compose.yml` file:
Ensure that the ports 18080, 11883, 15683-15688 are not used by any other application.
```text
ports:
- "18080:8080"
- "11883:1883"
- "15683-15688:5683-5688/udp"
Then, update the port configuration in the docker-compose.yml file:
```bash
sed -i ‘s/8080:8080/18080:8080/; s/1883:1883/11883:1883/; s/5683-5688:5683-5688\/udp/15683-15688:5683-5688\/udp/’ docker-compose.yml
{:copy-code}
```
Make sure that ports above (18080, 11883, 15683-15688) are not used by any other application.
#### Start ThingsBoard Edge
Set the terminal in the directory which contains the `docker-compose.yml` file and execute the following commands to up this docker compose directly:
Set the terminal in the directory which contains the docker-compose.yml file and execute the following commands to up this docker compose directly:
```bash
docker compose up -d
docker compose logs -f mytbedge
docker compose up -d && docker compose logs -f mytbedge
{:copy-code}
```
@ -90,11 +107,12 @@ docker-compose up -d
docker-compose logs -f mytbedge
```
#### Open ThingsBoard Edge UI
#### Step 3. Open ThingsBoard Edge UI
Once started, you will be able to open **ThingsBoard Edge UI** using the following link http://localhost:8080.
Once the Edge service is started, open the Edge UI at http://localhost:8080.
###### NOTE: Edge HTTP bind port update
Use next **ThingsBoard Edge UI** link **http://localhost:18080** if you updated HTTP 8080 bind port to **18080**.
If the Edge HTTP bind port was changed to 18080 during Edge installation, access the ThingsBoard Edge instance at http://localhost:18080.
Please use your tenant credentials from local Server instance or ThingsBoard Live Demo to log in to the ThingsBoard Edge.
ThingsBoard Edge supports only Kafka or in-memory queue (since v4.0) for message storage and communication between ThingsBoard services. Choose the appropriate queue implementation based on your specific business needs:
In Memory: The built-in and default queue implementation. It is useful for development or proof-of-concept (PoC) environments, but is not recommended for production or any type of clustered deployments due to limited scalability.
Kafka: Recommended for production deployments. This queue is used in the most of ThingsBoard production environments now.
In Memory queue is built in and enabled by default. No additional configuration is required.
#### Step 4. ThingsBoard Edge Service Installation
To configure ThingsBoard Edge, you can use the following command to automatically update the configuration file with specific values:
```bash
@ -101,25 +110,20 @@ EOL'
{:copy-code}
```
##### [Optional] Database Configuration
In case you changed default PostgreSQL datasource settings (**postgres**/**postgres**) please update the configuration file (**/etc/tb-edge/conf/tb-edge.conf**) with your actual values:
```bash
sudo nano /etc/tb-edge/conf/tb-edge.conf
{:copy-code}
```
Please update the following lines in your configuration file. Make sure **to replace**:
- Replace 'postgres' with your actual PostgreSQL username;
- Replace 'PUT_YOUR_POSTGRESQL_PASSWORD_HERE' with your actual PostgreSQL password.
##### [Optional] Configure PostgreSQL
If you changed PostgreSQL default datasource settings, use the following command:
```bash
sudo sh -c 'cat <<EOL>> /etc/tb-edge/conf/tb-edge.conf
PUT_YOUR_POSTGRESQL_PASSWORD_HERE: Replace with your actual PostgreSQL user password.
##### [Optional] Update bind ports
If ThingsBoard Edge is going to be running on the same machine where ThingsBoard server (cloud) is running, you'll need to update configuration parameters to avoid port collision between ThingsBoard server and ThingsBoard Edge.
@ -138,7 +142,7 @@ EOL'
Make sure that ports above (18080, 11883, 15683) are not used by any other application.
#### Run installation script
#### Step 6. Run installation Script
Once ThingsBoard Edge is installed and configured please execute the following install script:
// eventsConsumer's partitions are updated by stateService
responseTemplate.subscribe(withTopic(newPartitions,config.getRequestsTopic()));// TODO: we subscribe to partitions before we are ready. implement consumer-per-partition version for request template
responseTemplate.subscribe(withTopic(newPartitions,topicService.buildTopicName(config.getRequestsTopic())));// TODO: we subscribe to partitions before we are ready. implement consumer-per-partition version for request template
The **calculate()** function is a user-defined script that enables custom calculations using [TBEL](${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/tbel/) on telemetry and attribute data.
It receives arguments configured in the calculated field setup, along with an additional `ctx` object that provides access to all arguments.
It receives arguments configured in the calculated field setup, along with an additional `ctx` object that stores `msgTs` and provides access to all arguments.
### Function Signature
@ -44,7 +44,7 @@ Let's modify the function that converts Fahrenheit to Celsius to also return the
| `merge(other, settings)` | Merges with another rolling argument. Aligns timestamps and filling missing values with the previous available value. | Merged object with `timeWindow` and aligned values. | <spantb-help-popup="calculated-field/examples/merge-functions/merge_input"tb-help-popup-placement="top"trigger-text="Input"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_usage"tb-help-popup-placement="top"trigger-text="Usage"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_output"tb-help-popup-placement="top"trigger-text="Output"></span> |
| `mergeAll(others, settings)` | Merges multiple rolling arguments. Aligns timestamps and filling missing values with the previous available value. | Merged object with `timeWindow` and aligned values. | <spantb-help-popup="calculated-field/examples/merge-functions/merge_input"tb-help-popup-placement="top"trigger-text="Input"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_all_usage"tb-help-popup-placement="top"trigger-text="Usage"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_all_output"tb-help-popup-placement="top"trigger-text="Output"></span> |
| `merge(other, settings)` | Merges with another rolling argument. Aligns timestamps and filling missing values with the previous available value. | Merged object with `timeWindow` and aligned values. | <spantb-help-popup="calculated-field/examples/merge-functions/merge_input"tb-help-popup-placement="top"trigger-text="Input"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_usage"tb-help-popup-placement="top"trigger-text="Usage"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_output"tb-help-popup-placement="top"trigger-text="Output"></span> |
| `mergeAll(others, settings)` | Merges multiple rolling arguments. Aligns timestamps and filling missing values with the previous available value. | Merged object with `timeWindow` and aligned values. | <spantb-help-popup="calculated-field/examples/merge-functions/merge_input"tb-help-popup-placement="top"trigger-text="Input"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_all_usage"tb-help-popup-placement="top"trigger-text="Usage"></span><br><spantb-help-popup="calculated-field/examples/merge-functions/merge_all_output"tb-help-popup-placement="top"trigger-text="Output"></span> |
| `other` or `others` | Another rolling argument or array of rolling arguments to merge with. |
@ -187,29 +188,51 @@ function calculate(ctx, temperature, defrost) {
The result is a list of issues that may be used to configure alarm rules:
```json
[{
[
{
"ts": 1741613833843,
"values": {
"issue": {
"temperature": -3.12,
"defrostState": false
}
"issue": {
"temperature": -3.12,
"defrostState": false
}
}
}, {
},
{
"ts": 1741613923848,
"values": {
"issue": {
"temperature": -4.16,
"defrostState": false
}
"issue": {
"temperature": -4.16,
"defrostState": false
}
}
}]
}
]
```
### Function return format
The return format depends on the output type configured in the calculated field settings (default: **Time Series**).
### Message timestamp
The `ctx` object also includes property `msgTs`, which represents the timestamp of the incoming telemetry message that triggered the calculated field execution in milliseconds.
You can use `ctx.msgTs` to set the timestamp of the resulting output explicitly when returning a time series object.
```javascript
var temperatureC = (temperatureF - 32) / 1.8;
return {
ts: ctx.msgTs,
values: {
"temperatureC": toFixed(temperatureC, 2)
}
}
```
This ensures that the calculated data point aligns with the timestamp of the triggering telemetry.
##### Time Series Output
The function must return a JSON object or array with or without a timestamp.
@ -246,7 +269,7 @@ With timestamp:
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
}
}
```
@ -265,7 +288,7 @@ Array containing multiple timestamps and different values of the `airDensity` :
"delete-multiple-title":"Are you sure you want to delete { count, plural, =1 {1 calculated field} other {# calculated fields} }?",
"delete-multiple-text":"Be careful, after the confirmation all selected calculated fields will be removed and all related data will become unrecoverable.",
"test-with-this-message":"Test with this message",
"use-message-timestamp":"Use message timestamp",
"hint":{
"arguments-simple-with-rolling":"Simple type calculated field should not contain keys with time series rolling type.",
"arguments-empty":"Arguments should not be empty.",
@ -1079,7 +1080,8 @@
"max-args":"Maximum number of arguments reached.",
"decimals-range":"Decimals by default should be a number between 0 and 15.",
"expression":"Default expression demonstrates how to transform a temperature from Fahrenheit to Celsius.",
"arguments-entity-not-found":"Argument target entity not found."
"arguments-entity-not-found":"Argument target entity not found.",
"use-message-timestamp":"If enabled, the calculated value will be persisted using the timestamp of the telemetry that triggered the calculation, instead of the server time."
Viacheslav Klimov
1 year ago
GitHub