Star

ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.

REST Connector Configuration

This guide will help you to get familiar with REST Connector configuration for ThingsBoard IoT Gateway.
Use general configuration guide to enable this Connector.
The purpose of this Connector is to create API endpoints and get data from received requests.
Connector is also able to push data to external HTTP(S) API based on the updates/commands from ThingsBoard.

This connector is useful when you have some HTTP(S) API endpoints in your device or some data in external resource and you would like to push this data to the ThingsBoard.

We will describe connector configuration file below.

Connector configuration: rest.json

Connector configuration is a JSON file that contains information about how to create API endpoints and how to process the data.
Let’s review the format of the configuration file using example below.


Example of REST Connector config file. Press to expand. Example listed below will create a server on a localhost using 5000 port. Connector will use basic HTTP authorization using username and password. Then, connector will create endpoints from a list of endpoints using endpoints from mapping section. See more info in a description below.
{
  "host": "127.0.0.1",
  "port": "5000",
  "mapping":[
    {
      "endpoint": "/test_device",
      "HTTPMethod": [
        "POST"
      ],
      "security":
      {
        "type": "basic",
        "username": "user",
        "password": "passwd"
      },
      "converter": {
        "type": "json",
        "deviceNameExpression": "Device ${name}",
        "deviceTypeExpression": "default",
        "attributes": [
          {
            "type": "string",
            "key": "model",
            "value": "${sensorModel}"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${temp}"
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${hum}",
            "converter": "CustomConverter"
          }
        ]
      }
    },
    {
      "endpoint": "/test",
      "HTTPMethod": [
        "GET",
        "POST"
      ],
      "security":
      {
        "type": "anonymous"
      },
      "converter": {
        "type": "custom",
        "class": "CustomConverter",
        "deviceNameExpression": "Device 2",
        "deviceTypeExpression": "default",
        "attributes": [
          {
            "type": "string",
            "key": "model",
            "value": "Model2"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${temp}"
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${hum}"
          }
        ]
      }
    }
  ]
}

General section

Parameter Default value Description
host http://127.0.0.1:5000 Domain address or ip of the server.
SSLVerify true Verify or no SSL certificate on the server if available.

Mapping section

This configuration section contains array of objects with endpoints that the gateway will create.
Also this section contains settings about processing incoming messages (converter).
After request receiving, the message from the request is analyzed to extract device name, type and data (attributes and/or timeseries values).
By default, the gateway uses Json converter, but it is possible to provide custom converter.

Note: You can specify multiple mapping objects inside the array.

Parameter Default value Description
endpoint /test_device Url address of the endpoint.
HTTPMethod GET HTTP method allowed for endpoint (GET, POST etc.).

Security section

This section provides configuration for client authorization at the gateway for every endpoint.

One type of security configuration is Basic authentication. The REST Connector waits for HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.

Parameter Default value Description
type basic Type of authorization.
username username Username for authorization.
password password Password for authorization.

Security section in configuration file will look like this:

    "security": {
      "type": "basic",
      "username": "username",
      "password": "password"
    }

Anonymous auth is the most simple option. It is useful for testing.

Parameter Default value Description
type anonymous Type of authorization.

Security subsection in configuration file will look like this:

    "security": {
      "type": "anonymous"
    }

Converter subsection

This subsection contains configuration for processing incoming messages.

Types of request converters:

  1. json – Default converter
  2. custom – Custom converter (You can write it by yourself, and it will use to convert incoming data.)

Json converter is default converter, it looks for deviceName, deviceType, attributes and telemetry in the incoming request from the client, with rules, described in this subsection:

Parameter Default value Description
type json Provides information to connector that default converter will be uses for converting data from the incoming request.
deviceNameExpression Device ${name} Simple JSON expression, uses for looking device name in the incoming message (value of the parameter “name” from the request will be used as device name).
deviceTypeExpression default Simple JSON expression, uses for looking device type in the incoming message (string “default” will be used as device type).
attributes   This subsection contains parameters of the incoming requests, that will be interpreted as attributes for the device.
… type string Type of incoming data for a current attribute.
… key model Simple JSON expression, uses for looking key in the incoming data, that will send to ThingsBoard instance as attribute key.
… value ${sensorModel} Simple JSON expression, uses for looking value in the incoming data, that will send to ThingsBoard instance as value of key parameter.
timeseries   This subsection contains parameters of the incoming message, that will be interpreted as telemetry for the device.
… type double Type of incoming data for a current telemetry.
… key temperature Simple JSON expression, uses for looking key in the incoming message, that will send to ThingsBoard instance as attribute key.
… value ${temp} Simple JSON expression, uses for looking value in the incoming message, that will send to ThingsBoard instance as value of key parameter.

Parameters in attributes and telemetry section may differ from those presented above, but will have the same structure.

Mapping subsection looks like:

    {
      "endpoint": "/test_device",
      "HTTPMethod": [
        "POST"
      ],
      "security":
      {
        "type": "basic",
        "username": "user",
        "password": "passwd"
      },
      "converter": {
        "type": "json",
        "deviceNameExpression": "Device ${name}",
        "deviceTypeExpression": "default",
        "attributes": [
          {
            "type": "string",
            "key": "model",
            "value": "${sensorModel}"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${temp}"
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${hum}"
          }
        ]
      }
    }

A custom converter is converter written for some device:

Parameter Default value Description
type custom Provides information to connector that custom converter will be uses for converting data from request.
deviceNameExpression SuperAnonDevice Device name.
deviceTypeExpression default Devcie type.
extension CustomRESTUplinkConverter Name of custom converter class.
extension-config   Configuration, for custom converter (You can put anything, there. It will be passed to the converter object on initialization).
key Totaliser  
datatype float  
fromByte 0  
toByte 4  
byteorder big  
signed true  
multiplier 1  

Custom converter usually needed if you want to collect data from some device with not regular structure in response or when the data needs some processing before sending it to the ThingsBoard.

Notate: Everything, you placed in the “converter” section will be passed to the custom converter as a configuration.

Mapping subsection in the configuration looks like:

      "converter": {
        "type": "custom",
        "deviceNameExpression": "SuperAnonDevice",
        "deviceTypeExpression": "default",
        "extension": "CustomRestUplinkConverter",
        "extension-config": [
          {
          "key": "Totaliser",
          "datatype": "float",
          "fromByte": 0,
          "toByte": 4,
          "byteorder": "big",
          "signed": true,
          "multiplier": 1
          }]
      }

Attribute update section

Configuration in this section are optional.
ThingsBoard allows to provision device attributes and fetch some of them from the device application. You can treat this as a remote configuration for devices. Your devices are able to request shared attributes from ThingsBoard. See user guide for more details.

The “attributeRequests” configuration allows configuring the format of the corresponding attribute request and response messages.

Parameter Default value Description
httpMethod POST HTTP method for request (GET, POST etc.).
SSLVerify false Verify or no SSL certificate on the server if available.
httpHeaders { “CONTENT-TYPE”: “application/json” } Object contains additional HTTP headers for request.
security   Security for request:
type basic Security type for request to the server (basic or anonymous).
username user Username for basic type of the security.
password passwd Password for basic type of the security.
timeout 0.5 Timeout for request.
tries 3 Count of tries to send data
allowRedirects true Allow request redirection.
deviceNameFilter .*REST$ Regular expression device name filter, uses to determine, which function to execute.
attributeFilter data Regular expression attribute name filter, uses to determine, which function to execute.
requestUrlExpression sensor/${deviceName}/${attributeKey} JSON-path expression uses for creating url address to send a message.
valueExpression {\”${attributeKey}\”:\”${attributeValue}\”} JSON-path expression uses for creating the message data that will send to url.

The attributeUpdates section will look like:

  "attributeUpdates": [
      {
        "HTTPMethod": "POST",
        "SSLVerify": false,
        "httpHeaders": {
          "CONTENT-TYPE": "application/json"
        },
        "security": {
          "type": "basic",
          "username": "user",
          "password": "passwd"
        },
        "timeout": 0.5,
        "tries": 3,
        "allowRedirects": true,
        "deviceNameFilter": ".*REST$",
        "attributeFilter": "data",
        "requestUrlExpression": "sensor/${deviceName}/${attributeKey}",
        "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
      }
  ],

Server side RPC section

ThingsBoard allows sending RPC commands to the device that is connected to ThingsBoard directly or via Gateway.

Configuration, provided in this section uses for sending RPC requests from ThingsBoard to device.

Parameter Default value Description
deviceNameFilter .* Regular expression device name filter, uses to determine, which function to execute.
methodFilter echo Regular expression method name filter, uses to determine, which function to execute.
requestUrlExpression http://127.0.0.1:5001/${deviceName} JSON-path expression, uses to create url address to send RPC request.
responseTimeout 1 Timeout for request.
httpMethod GET HTTP method for request (GET, POST etc.).
valueExpression ${params} JSON-path expression, uses for creating data for sending.
timeout 0.5 Timeout for request.
tries 3 Count of tries to send data
httpHeaders { “CONTENT-TYPE”: “application/json” } Object contains additional HTTP headers for request.
security   Security for request:
type anonymous Security type for request to the server (basic or anonymous).

There are 2 types of the RPC calls:

  1. With reply, after sending request the gateway will wait for response and send it to ThingsBoard.
  2. With no reply, after sending request the gateway will not wait for response.

Examples for both methods provided below.

  "serverSideRpc": [
    {
      "deviceNameFilter": ".*",
      "methodFilter": "echo",
      "requestUrlExpression": "http://127.0.0.1:5001/${deviceName}",
      "responseTimeout": 1,
      "HTTPMethod": "GET",
      "valueExpression": "${params}",
      "timeout": 0.5,
      "tries": 3,
      "httpHeaders": {
        "Content-Type": "application/json"
      },
      "security": {
        "type": "anonymous"
      }
    },
    {
      "deviceNameFilter": ".*",
      "methodFilter": "no-reply",
      "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
      "HTTPMethod": "POST",
      "valueExpression": "${params}",
      "httpHeaders": {
        "Content-Type": "application/json"
      }
    }
  ]

Next steps

Explore guides related to main ThingsBoard features: