HTTP Integration

HTTP Integration exposes an HTTP endpoint on the Edge that accepts inbound device data (uplink) and can send commands back to devices (downlink). It is useful when:

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

Integration and Converter templates are created in the Cloud (ThingsBoard PE server) and then assigned to Edge instances.

1. In the Cloud, go to Edge management > Integration templates and click the + button. Select HTTP as the type and name it Edge HTTP Integration, then click Next.

   

2. Create the Uplink converter. The uplink converter decodes the raw HTTP payload into ThingsBoard telemetry and attributes.

   • 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 = {
      deviceName: deviceName,
      deviceType: deviceType,
      attributes: {
          model: data.model,
          serialNumber: data.param2,
      },
      telemetry: {
          temperature: data.temperature
      }
   };
   
   // Helper functions 'decodeToString' and 'decodeToJson' are built-in
   return result;

   Select Create new, paste the script into the Decoder function field, and click Next.

   Uplink converter with TBEL decoder. Uplink converter with JavaScript decoder.

3. Create the Downlink converter. The downlink converter encodes outbound messages (e.g. attribute updates) into the format expected by the device.

   • 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: {}
   };
   
   return result;

   Select Create new, paste the script into the Encoder function field, and click Next.

   Downlink converter with TBEL encoder. Downlink converter with JavaScript encoder.

4. On the Connection page, set the Base URL to the IP address and port of your Edge instance in host:port format.

   To reuse this template across multiple Edge instances with different addresses, use the placeholder ${{baseUrl}} instead of a hardcoded value. The placeholder is replaced at assignment time by the value of the baseUrl attribute on each Edge.

   Click Add to save the integration template.

   

To send downlink messages from the Rule Engine to the HTTP integration, add an integration downlink node to the Edge Root Rule Chain.

Before assigning the integration template, add the baseUrl attribute to the Edge instance. This provides the ${{baseUrl}} placeholder value used in the integration configuration.

1. Go to Edge management > Instances, open your Edge, and navigate to the Attributes tab. Click + to add a new server attribute.

2. Enter baseUrl as the attribute name and your Edge IP:port as the value. Click Add.

3. Click the Manage edge integrations button on the Edge instance.

4. Click +, select the HTTP integration from the drop-down, and click Assign.

5. Log in to your Edge instance and go to Integration center > Integrations. Open the integration and confirm the ${{baseUrl}} placeholder is replaced with the attribute value.

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

2. Send a test uplink message using curl. Replace $DEVICE_NAME and $YOUR_HTTP_ENDPOINT_URL with actual values:

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

3. Open the Events tab on the integration. A message with status OK should appear. Click the three dots in the Message column to inspect the payload.

4. A new device is created automatically. Go to Entities > Devices on the Edge to see it.

5. To inspect how the Uplink Converter processed the message, go to Integration center > Data converters, open the uplink converter, and select the Events tab.

1. On the Edge, go to Entities > Devices, select your device, and open the Attributes tab. Under Shared attributes, click + and add a new attribute — for example, key firmware, value 01052020.v1.1. Save.

2. Verify the downlink was sent to the integration by opening the integration’s Events tab.

3. Send another uplink message with the same curl command to receive the downlink response:

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

   The terminal will show the response returned by ThingsBoard.

4. Inspect the downlink in the Downlink Converter. Go to Integration center > Data converters, open the downlink converter, and select the Events tab.