Star
Try it now
Solutions
Customers
Use Cases
Partners
About Us
Pricing Docs Guides

Getting Started

Getting Started with ThingsBoard IoT Platform.

Getting Started

Introduction

The goal of this tutorial is to demonstrate the basic usage of the most popular ThingsBoard features. You will learn how to:

The tutorial is based on a popular facility monitoring use-case. We will show how to monitor temperature in a different parts of the building, raise alarms when temperature exceeds certain threshold and visualize collected data and alarms.

Video tutorial

We recommend you to review the following video tutorial. All the resources used in this tutorial are listed below for your convenience.

 

Tutorial resources

Live Demo and the installation guides

If you don’t have access to a running ThingsBoard instance, use either Live Demo or Installation Guide to fix this.

In case you decided to install your own ThingsBoard server and loaded the demo data ( “–loadDemo” option, according to the installation guides), the list of default accounts (login/password) and device credentials is located here.

Pushing data from the device

In order to simplify this guide, we will push data using HTTP, MQTT or CoAP protocol from your local PC. Please review connect your device guides for all available connectivity solutions and options and hardware samples to learn how to connect various hardware platforms to ThingsBoard.

Client-side libraries installation

Install preferred HTTP (cURL), MQTT (Mosquitto or MQTT.js) or CoAP (CoAP.js) client using following commands.

resources/curl-win.sh
 
NOTE: Starting Windows 10 b17063, cURL is available by default.
More info here: https://blogs.msdn.microsoft.com/commandline/2018/01/18/tar-and-curl-come-to-windows/
If you are using older version of Windows OS, you may find official installation guides here: https://curl.haxx.se/
resources/curl-macos.sh
 
brew install curl
resources/curl-ubuntu.sh
 
sudo apt-get install curl
resources/node-mqtt.sh
 
# Assuming you have Node.js and NPM installed on your Windows/Linux/MacOS machine
npm install mqtt -g
resources/mosquitto-ubuntu.sh
 
sudo apt-get install mosquitto-clients
resources/mosquitto-macos.sh
 
brew install mosquitto-clients
resources/node-coap.sh
 
sudo npm install coap-cli -g

Sample cURL command used in the video tutorial

This command works for Windows, Ubuntu and macOS, assuming that cURL tool is installed.

# Please replace $HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d "{\"temperature\": 25}" $HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

# For example, $HOST_NAME in case of live demo server:
curl -v -X POST -d "{\"temperature\": 25}" https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

# For example, $HOST_NAME in case of local installation:
curl -v -X POST -d "{\"temperature\": 25}" http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

Sample generator script

var msg = { temperature: +(Math.random()*5 + 25).toFixed(1)};
var metadata = {};
var msgType = "POST_TELEMETRY_REQUEST";

return { msg: msg, metadata: metadata, msgType: msgType };

Rule Engine guides

Rule Engine overview - learn the Rule Engine basics and architecture.

Rule Engine guides - learn how to use ThingsBoard Rule Engine.

Mail settings

Use this guide to configure SendGrid or use any other SMTP server available.

Other sample data files

Create some folder to store all necessary files for this tutorial. Download to this folder or create the following data files:

Please note that data in this files is basically in key-value format. You can use your own keys and values. See MQTT, CoAP or HTTP protocol reference for more details.

resources/attributes-data.json
 
{"firmware_version":"1.0.1", "serial_number":"SN-001"}
resources/telemetry-data.json
 
{"temperature":21, "humidity":55.0, "active": false}

Pushing data using MQTT, CoAP or HTTP

Download the following files to previously created folder according to the preferred client:

If you are using a shell script (*.sh) make sure that it is executable:

chmod +x *.sh

Before executing script don’t forget to:

Finally, execute corresponding *.sh or *.bat script to push data to the server.

Below are tabs with the content of the scripts provided.

resources/mqtt-js.sh
 
#!/bin/sh

# Set ThingsBoard host to "demo.thingsboard.io" or "localhost"
export THINGSBOARD_HOST=demo.thingsboard.io

# Replace YOUR_ACCESS_TOKEN with one from Device details panel.
export ACCESS_TOKEN=YOUR_ACCESS_TOKEN

# Read serial number and firmware version attributes
ATTRIBUTES=$( cat attributes-data.json )
export ATTRIBUTES

# Read timeseries data as an object without timestamp (server-side timestamp will be used)
TELEMETRY=$( cat telemetry-data.json )
export TELEMETRY

# publish attributes and telemetry data via mqtt client
node publish.js
resources/mqtt-js.bat
 
@echo off

REM Set ThingsBoard host to "demo.thingsboard.io" or "localhost"
set THINGSBOARD_HOST=demo.thingsboard.io

REM Replace YOUR_ACCESS_TOKEN with one from Device details panel.
set ACCESS_TOKEN=YOUR_ACCESS_TOKEN

REM Read serial number and firmware version attributes
set /p ATTRIBUTES=<attributes-data.json

REM Read timeseries data as an object without timestamp (server-side timestamp will be used)
set /p TELEMETRY=<telemetry-data.json

REM publish attributes and telemetry data via mqtt client
node publish.js
resources/publish.js
 
var mqtt = require('mqtt');

console.log('Connecting to: %s using access token: %s', process.env.THINGSBOARD_HOST, process.env.ACCESS_TOKEN);

var client  = mqtt.connect('mqtt://'+ process.env.THINGSBOARD_HOST,{
    username: process.env.ACCESS_TOKEN
});

client.on('connect', function () {
    console.log('Client connected!');
    client.publish('v1/devices/me/attributes', process.env.ATTRIBUTES);
    console.log('Attributes published!');
    client.publish('v1/devices/me/telemetry', process.env.TELEMETRY);
    console.log('Telemetry published!');
    client.end();
});
resources/mosquitto.sh
 
#!/bin/sh

# Set ThingsBoard host to "demo.thingsboard.io" or "localhost"
THINGSBOARD_HOST="demo.thingsboard.io"
# Replace YOUR_ACCESS_TOKEN with one from Device details panel.
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
# Publish serial number and firmware version attributes
mosquitto_pub -d -h "$THINGSBOARD_HOST" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "attributes-data.json"
# Publish timeseries data as an object without timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "$THINGSBOARD_HOST" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data.json"
resources/coap-js.sh
 
# Publish serial number and firmware version attributes
cat attributes-data.json | coap post coap://$THINGSBOARD_HOST/api/v1/$ACCESS_TOKEN/attributes
# Publish timeseries data as an object without timestamp (server-side timestamp will be used)
cat telemetry-data.json | coap post coap://$THINGSBOARD_HOST/api/v1/$ACCESS_TOKEN/telemetry
resources/curl.sh
 
# Publish serial number and firmware version attributes
# replace $THINGSBOARD_PORT with 8080 (in case of local installation) or 80 (in case of live-demo).
curl -v -X POST -d @attributes-data.json http://$THINGSBOARD_HOST:$THINGSBOARD_PORT/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
# Publish timeseries data as an object without timestamp (server-side timestamp will be used)
# replace $THINGSBOARD_PORT with 8080 (in case of local installation) or 80 (in case of live-demo).
curl -v -X POST -d @telemetry-data.json http://$THINGSBOARD_HOST:$THINGSBOARD_PORT/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

ThingsBoard Community Edition education course

Next steps



Your feedback

Don’t hesitate to star ThingsBoard on github to help us spread the word. If you have some questions about this sample - post it on the forum.