HTTP Integration

HTTP Integration opens an HTTP endpoint on the Edge. Devices and external systems post data to it (uplink), and the Edge can return commands to a device in the HTTP response (downlink). It is useful when:

• You stream device or asset data from an external system or a connectivity provider.
• You have a custom application that posts data over HTTP.
• You want to connect a device to ThingsBoard Edge with a custom HTTP-based protocol.

• A ThingsBoard server with tenant administrator access. The templates are created there.
• A ThingsBoard Edge instance connected to the server.
• curl to simulate a device.

The example device SN-001 posts a JSON message such as {"deviceName":"SN-001","temperature":33,"model":"test"}.

Converter templates are created on the server. The uplink converter decodes the HTTP payload into telemetry and attributes. The downlink converter encodes messages from the rule engine, for example shared attribute updates, into the response sent to the device.

1. On the server, go to Edge management > Templates and open the Converter tab. Click Add data converter and select Create new converter.

2. Set Converter type to Uplink, select HTTP as the Integration type, and enter the name HTTP uplink converter.

3. In Main decoding configuration, select TBEL or JS, paste the matching script, and click Add.

   • TBEL (recommended)
   • JavaScript

   // Decode an uplink message from a buffer
   // payload - array of bytes
   // metadata - key/value object
   
   var data = decodeToJson(payload);
   
   var deviceName = data.deviceName;
   var deviceType = data.deviceType;
   
   var result = {
   

   ▼Expand

1. On the Converter tab, click Add data converter and select Create new converter.

2. Set Converter type to Downlink, select HTTP as the Integration type, and enter the name HTTP downlink converter.

3. In Main encoding configuration, select TBEL or JS, paste the matching script, and click Add.

   • TBEL (recommended)
   • JavaScript

   // Encode downlink data from incoming Rule Engine message
   // msg        - JSON message payload
   // msgType    - e.g. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST'
   // metadata   - key/value pairs with message metadata
   // integrationMetadata - key/value pairs defined in the Integration
   
   var result = {
       contentType: "JSON",
       data: JSON.stringify(msg),
       metadata: {}
   

   ▼Expand

1. On the server, go to Edge management > Templates, open the Integration tab, and click Add integration.

2. On the Basic settings step, select HTTP as the Integration type. Keep the name HTTP integration or enter your own. Click Next.

3. On the Uplink data converter step, select Select existing, choose HTTP uplink converter, and click Next.

4. On the Downlink data converter step, select Select existing, choose HTTP downlink converter, and click Next.

5. On the Connection step, set Base URL to ${{baseUrl}} and click Add.

Base URL is the address of the Edge, including the scheme, for example http://10.7.3.0:8080. The integration endpoint is <Base URL>/api/v1/integrations/http/<integration key>. The ${{baseUrl}} placeholder lets you assign one template to several Edges: each Edge replaces it with the value of its own baseUrl server attribute. See Configuration placeholders.

Add the baseUrl attribute first. Without it, the assignment dialog warns Edge has missing attribute(s) and the Edge receives the literal placeholder.

1. On the server, go to Edge management > Edges and click the Edge. On the Attributes tab, with the Server attributes scope selected, click +. Enter baseUrl as the key and the Edge URL, for example http://10.7.3.0:8080, as the value. Click Add.

2. On the Details tab, click Manage integrations, then Assign to edge (+). Select HTTP integration and click Assign.

3. Log in to the Edge and go to Integrations > Integrations. Open the integration. Base URL shows the attribute value instead of the placeholder, and HTTP endpoint URL shows the full endpoint.

1. On the Edge, go to Integrations > Integrations, open the HTTP integration, and copy the HTTP endpoint URL.

2. Send a test message. Replace $YOUR_HTTP_ENDPOINT_URL with the copied URL:

   curl -v -X POST \
     -d '{"deviceName":"SN-001","temperature":33,"model":"test"}' \
     $YOUR_HTTP_ENDPOINT_URL \
     -H "Content-Type:application/json"

3. Open the Events tab of the integration. An Uplink event with status OK appears. Click the three dots in the Message column to see the payload.

4. The device SN-001 is created automatically. On the Edge, go to Devices & assets > Devices, open it, and select the Latest telemetry tab. The temperature key shows 33.

5. To see how the converter processed the message, go to Integrations > Data converters, open HTTP uplink converter, and select the Events tab. The In column shows the raw payload, the Out column the decoded result.

To send messages from the rule engine to the integration, add an integration downlink node to the root rule chain of the Edge.

1. On the Edge, go to Data processing > Rule chains and open Edge Root Rule Chain.

2. In the node search field, type integration downlink and drag the integration downlink node onto the canvas.

3. Enter a name, select HTTP integration in the Integration field, and click Add.

4. Connect the message type switch node to the new node and select the Attributes Updated and Post attributes link labels.

5. Click the checkmark icon (Apply changes) to save the rule chain.

Over HTTP, the Edge cannot push a message to the device. It stores the downlink and returns it in the response to the next uplink request from that device.

1. On the Edge, go to Devices & assets > Devices, open SN-001, and select the Attributes tab. Select the Shared attributes scope, click +, enter the key firmware and the value 01052020.v1.1, and click Add.

2. Open the Events tab of the integration. A Downlink: ATTRIBUTES_UPDATED event with status OK appears.

3. Send the uplink message from the previous section again. The response body contains the shared attribute, and a second event, Downlink, shows the response on the Events tab:

   {"firmware":"01052020.v1.1"}

4. To see the encoded message, go to Integrations > Data converters, open HTTP downlink converter, and select the Events tab.