Thingboard API

Basic auth and get functions for Thingsboard REST API & Thingsboard's Postgres DB.
Promise like implementation
___

$3

- Fixed issue of clearing alarm. In the most cases earlier it doesn't work properly. In case of error, it returns http response code.
- Added methods:
- pushAlarm: Allows to create new alarm
- clearAlarm: Allows to change status of alarm to Cleared Unacknowledge

Bugs reporting to i.kovorotniy@2050.digital

___



- Installation
- Usage
- Error handling
- List REST API Functions
- GET
- createConnection
- get.objectID
- get.objectIDandKeys
- get.allObjectsIDbyType
- get.allObjectsIDandKeysByType
- PUSH
- push.createRelation
- push.pushAttributes
- push.createEntity
- push.pushAlarm
- DELETE
- delete.deleteEntity
- delete.deleteChilds
- delete.deleteEntitiesByType
- delete.clearAlarm
- List Postgres Functions
- postgres.get.allObjectsIDbyType
- postgres.get.allObjectsIDandKeysByType
- List of unclassified functions
- Extend child attributes by parent

Installation

``bash
npm i thingsboard_api
`

Usage

- Better use environment variable instead of costansts or hardcoded values!

`js
const TB = require('thingsboard_api');
const options = {
TB_HOST: 'ip_to_TB', //default: localhost
TB_PORT: 'port_to_TB', //default: 8080
TB_USERNAME: 'loginTB', //default: tenant@thingboard.org
TB_PASSWORD: 'passTB', //default: tenant
PG_HOST: 'ip_to_Postgres', //no defaults!
PG_PORT: 'port_to_Postgres', //no defaults!
PG_USERNAME: 'loginPostgres', //no defaults!
PG_PASSWORD: 'loginPostgres', //no defaults!

}

async function main(){
await TB.createConnection(options) //
const objectId = await TB.get.objectID('entity_name','asset'))
const objectIdsKeys = await TB.get.objectIDandKeys('entity_name2','device','key1,key2'))
}

main()

`

Error handling

- The most of functions support error and message keys in result object! (See update status!)
- Error description is in message key!
- Example:
`js
const result = await TB.get.objectID('some_entity_name', 'entity_type');
if (result.error){
return { "error": true, "message": result.message }
}
`

List REST API Functions

GET

$3

$3

List of options:
` js
const options = {
TB_HOST: 'ip_to_TB', //default: localhost
TB_PORT: 'port_to_TB', //default: 8080
TB_USERNAME: 'loginTB', //default: tenant@thingboard.org
TB_PASSWORD: 'passTB', //default: tenant
PG_HOST: 'ip_to_Postgres', //no defaults!
PG_PORT: 'port_to_Postgres', //no defaults!
PG_USERNAME: 'loginPostgres', //no defaults!
PG_PASSWORD: 'loginPostgres', //no defaults!

}
`

Usage
`js
const TB = require('thingsboard_api');
await TB.createConnection(options)
`

$3

$3

List of options:
`json
(name, entity_view) //string
`

Usage
`js
var TB = require('thingsboard_api');
var myObjectsID = await TB.get.objectID('myObject', 'asset')
`
Result
`js
"ea791310-78d2-11ea-a1c7-d1e730c27b32"
`

$3

$3

List of options:
`json
(name, type, keys) //string. for keys can be array
//If keys == null - Trying to get all attributes!
`

Usage
`js
var TB = require('thingsboard_api');
var myObjectID = await TB.get.objectIDandKeys('myObject', 'asset', 'key1,key2,key3')

let keys = ['key1','key2','key3']
var myObjectIDandAttrs = await TB.get.objectIDandKeys('myObject', 'asset', keys)
`
Result
`js
{
id: "ea791310-78d2-11ea-a1c7-d1e730c27b32",
name: "myObject",
type: "asset",
key1: "value1",
key2: "value2",
}
`

$3

$3

List of options:
`json
(type, entity_type) //string. type - custom type, entity_type - ASSET/DEVICE/ENTITY_VIEW
`

Usage
`js
var TB = require('thingsboard_api');
var allObjectsID = await TB.get.allObjectsIDbyType('device_type', 'device')

`
Result
`js
[
{
id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
name: "name1",
type: "device_type"
},

{
id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
name: "name2",
type: "device_type"
}
]
`

$3

$3

List of options:
`json
(type, entity_type, keys) //string. type - custom type, entity_type - ASSET/DEVICE/ENTITY_VIEW. For keys - can be array.
//If keys == null - Trying to get all attributes!
`

Usage
`js
var TB = require('thingsboard_api');
let keys = ['key1','key2','key3']
var allObjectsIDandAttrs = await TB.get.allObjectsIDandKeysByType('device_type', 'device',keys)

`

Result
`js
[
{
id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
name: "name1",
type: "device",
key1: "value1",
key2: "value2"
},

{
id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
name: "name2",
type: "device",
key1: "value1",
key2: "value2"
}
]
`

____

PUSH

$3

List of options:
`json
(name, entity_view, parentName, parentType) //string
`

Usage
`js
var TB = require('thingsboard_api');
var createRelation = await TB.push.createRelation("myChild",'asset',"myParent",'asset')
`
Result
- Response in success

`js
{ "success": true }
`

- Response in fail

`js
{ "error": true, "message": "error description goes here" }
`

____

$3

List of options:
`json
(name,entity_type,attributes) //string
`

Usage
`js
var TB = require('thingsboard_api');
let attributes = {
key1: "value1",
key2: "value2",
}
var pushAttributes = await TB.push.pushAttributes("myObject",'asset',attributes)
`
Result
- Response in success

`js
{ "success": true }
`

- Response in fail

`js
{ "error": true, "message": "error description goes here" }
`

___

$3

List of options:
`json
(name,type,attributes,entity_type,parentName,parentType,parentKeys,parentRelation)
// attributes - can be null, if no attributes to push
// parentName,parentType,parentKeys,parentRelation - can be null
// so no relation or cloning attributes will be done
//
// parentKeys - array of name of keys to clone from parent to new Entity
// parentRelation - boolean. If true - will call createRelation() to parentName
`

Usage
`js
var TB = require('thingsboard_api');
let attributes = {
key1: "value1",
key2: "value2",
}
let parentKeys = ["keyTestParent","keyTestParent2"]

var createEntity = await TB.push.createEntity("myAsset",'testType',attributes,"asset","ParentDevice","device",parentKeys,true))
`
Result
`js
id || false //if no relation and parentClonning

{
id: id,
statusAttributes: true || false,
statusRelation: true || false,
}
`

$3

- List of options:
- entityName: Stands for entity name (String)
- entityType: Stands for entity type: device, asset and etc. (String)
- alarmDetails: Stands for alarm description: 'Some alarm details' (String)
- alarmType: Stands for alarm type: 'Change state' (String)
- ts: ts in MS (Date)
- tenantId: Stands for tenat id, required for creating alarm (String)
- entityId: Stands for entity id (String)

- Response:
`js
{
entityId: 'e34f1a20-c1a8-11ea-892e-756ada0522f7', // entity id of device, asset and etc
alarmId: 'ec250090-c7fe-11ea-96a3-756ada0522f7' // alarm id
}
`

____

DELETE

$3

List of options:
`json
(name,entity_type,flagDeleteChilds)
// flagDeleteChilds - boolean, if true - will delete child entities in 3 level depth max
`

Usage
`js
var TB = require('thingsboard_api');

var deleteEntity = await TB.delete.deleteEntity("myOldObject",'asset',false)
`
Result
- Response in success

`js
{ "success": true }
`

- Response in fail

`js
{ "error": true, "message": "error description goes here" }
`

___

$3

List of options:
`json
(type,entity_type)

`

Usage
`js
var TB = require('thingsboard_api');

var deleteEntity = await TB.delete.deleteEntitiesByType("typeOfAssetsToDelete",'asset')
`
Result
- Response in success

`js
{ "success": true }
`

- Response in fail

`js
{ "error": true, "message": "error description goes here" }
`
___

$3

Will delete entities, whose has relation to 'name' in 3 level depth max
List of options:
`json
(name,entity_type)

`

Usage
`js
var TB = require('thingsboard_api');

var deleteChilds = await TB.delete.deleteChilds("Parent",'asset')
`
Result
- Response in success

`js
{ "success": true }
`

- Response in fail

`js
{ "error": true, "message": "error description goes here" }
`

$3

List of options:
- alarmId: Stands for identificator of alarm, created earlier

Response:
- In success:

`js
{ success: true }
`

- In error:

`js
{
error: true,
message: Some error msg description
}
`

List Postgres Functions

$3

$3

- List of options:
- type: String
- entity_type: String

- Description:
- type: custom type (Локомотив, and etc.)
- entity_type: ASSET, DEVICE, ENTITY_VIEW


- Usage
`js
const TB = require('thingsboard_api');
const allObjectsID = await TB.postgres.get.allObjectsIDbyType('device_type', 'device');
`
- Error handling:
- In case of error, target variable will have two options:
- error
- message

`js
allObjectsID = {
"error": true,
"message": "getAllObjectsIDbyType(), Error: error description"
}
`

Succesfull output example:
`js
[
{
id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
entity_name: "name1",
type: "device_type"
},

{
id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
entity_name: "name2",
type: "device_type"
}
]
`

___

$3

$3

- List of options:
- type: String
- entity_type: String
- keys: null by default, array of string optionally!

- Description:
- If keys are null, all possible attributes will be in response!
- type: custom type (Локомотив, and etc.)
- entity_type: ASSET, DEVICE, ENTITY_VIEW

- Usage

`js
const TB = require('thingsboard_api');
const keys = ['key1','key2']
const allObjectsIDandAttrs = await TB.postgres.get.allObjectsIDandKeysByType('device_type', 'device', keys)
`

- Error handling:
- In case of error, target variable will have two options:
- error
- message

`js
allObjectsIDandAttrs = {
"error": true,
"message": "getAllObjectsIDandKeysByType(), Error: error description"
}
`

- Succesfull output example:
`js
[
{
entity_id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
entity_name: "name1",
entity_type: "device",
key1: "value1",
key2: "value2"
},

{
entity_id: "0b507930-78d2-11ea-a1c7-d1e730c27b32",
entity_name: "name2",
entity_type: "device",
key1: "value1",
key2: "value2"
}
]
`

___

#### postgres.get.getAttrsAndValuesById(entity_id, attributeKeys) - get attributes keys and values according to array of attributeKeys

#### Information
- This function is mostly used with extentChildAttr() See index.js, so it returns data for future extending attributes of child or updating them,
that's why all values (bool_v, str_v and etc.) return for each attribute_key

- For getting

##### Steps:
- convert Thingsboard UUID to Postgres entity_id; Use postgres.toPostgresID(thingsboard_uuid) for converting

##### List of options:
- entity_id - string
- attributeKeys - array

##### Response:
`js
[
...,
{
entity_type: 'DEVICE',
entity_id: '1e9fbe382c16090a0332dde0dc34203',
attribute_type: 'CLIENT_SCOPE',
attribute_key: 'attribute_test_april2020',
bool_v: false,
str_v: '',
long_v: 0,
dbl_v: 0,
last_update_ts: null
},
...
]
`

____


#### postgres.toPostgresID(thingsboard_uuid) - convert Thingsboard UUID to Postgres ID

##### List of options:
- thingsboard_uuid - string

#### Response:
- postres id - string


___

#### postgres.insertIntoAttrsKeysVals(dataToWrite) - insert data into attribute_kv table

##### Information:
- Column names are define in object

##### List of options:
- dataToWrite - array of objects
`js
[
{
entity_type: 'DEVICE',
entity_id: '1ea6d07aaba34b094de3ddf86487a77',
attribute_type: 'CLIENT_SCOPE',
attribute_key: 'test_attr_key',
bool_v: null,
str_v: null,
long_v: null,
dbl_v: null,
last_update_ts: 1586949836446
},
{
entity_type: 'DEVICE',
entity_id: '1ea6d07aaba34b094de3ddf86487a77',
attribute_type: 'CLIENT_SCOPE',
attribute_key: 'Работа по программе',
bool_v: null,
str_v: null,
long_v: null,
dbl_v: null,
last_update_ts: 1586949836446
},
]
`

##### Response:
- To check if data was written to db compare insert count with response count

___

$3

`
- entity_type
- attribute_type
- attribute_key
- bool_v
- str_v
- long_v
- dbl_v
- last_update_ts
`

##### List of options:
- attributeObj - object
`js
{
entity_type: 'DEVICE',
entity_id: '1ea6d07aaba34b094de3ddf86487a77',
attribute_type: 'CLIENT_SCOPE',
attribute_key: 'Работа по программе',
bool_v: null,
str_v: null,
long_v: null,
dbl_v: null,
last_update_ts: 1586949836446
}
`
##### Response:
- To check if data was updated successfully count of entitities to update with update response count. Example for 1 obj:
`js
[ count: 1, command: 'UPDATE' ]
`
___

List of unclassified functions

$3

$3

- parent_id, child_id, child_type, attribute_keys are essential properties!
- Set necessary attribute keys in options.attributeKeys

##### List of options:
- options - object
`js
{
"parent_id": "some_thingsboard_id",
"child_id": "some_thingsboard_id",
"child_type": "DEVICE",
"attributeKeys": ['attribute_test_april2020', 'Отсутствие программы', 'inactivityAlarmTime', 'lastActivityTime', 'active'],
"updateAttrs": false,
}
`
##### Steps:
- If you want to add not existed attributes before to child set updateAttrs to false
- For updating child attributes using parent data, set updateAttrs to true`

##### Reponse:
- Function doesn't return any data!