ChirpStack Integration

ChirpStack Integration connects ThingsBoard to a ChirpStack open-source LoRaWAN Network Server via HTTP webhook, decodes the LoRaWAN payload and maps it to ThingsBoard telemetry and attributes. In the reverse direction, ThingsBoard encodes Rule Engine messages via a downlink converter and delivers them to devices through the ChirpStack API.

Before creating the integration, ensure:

• You have access to ThingsBoard Cloud with integration functionality enabled for your tenant.
• You have permissions to create integrations and data converters.
• A running ChirpStack Network Server — see the ChirpStack Docker Compose guide, or see Start ChirpStack Network Server below for a quick Docker Compose setup.
• At least one device registered and connected in ChirpStack — see the ChirpStack device connection guide.

The quickest way to run ChirpStack locally is with Docker Compose. The official chirpstack-docker repository provides a ready-to-use Compose configuration.

1. Install Docker — make sure Docker and Docker Compose are installed on your host. See the Docker installation guide.

2. Clone the repository:

   git clone https://github.com/chirpstack/chirpstack-docker.git
   cd chirpstack-docker

3. Configure the region — EU868 is configured by default. To use a different supported region, follow the instructions in the repository README.md.

4. Start ChirpStack:

   docker compose up

   On the first run, some errors may appear in the logs while the database initializes — this is expected.

5. Connect a gateway — the Compose environment includes a ChirpStack Gateway Bridge instance pre-configured for EU868, accepting UDP packets on port 1700.

6. Open the web interface — navigate to http://localhost:8080 and log in with username admin and password admin.
   If ChirpStack runs on a remote host, replace localhost with its address.

The API key is used by ThingsBoard to authenticate requests to the ChirpStack API when sending downlink messages.

1. In the ChirpStack UI, go to Tenant ⇾ API Keys and click Add API key.
2. Enter a name for the key (e.g. ThingsBoard) and click Submit.
3. Copy and save the token — it is displayed only once.

Go to Tenant → API Keys and click Add API key Enter a name for the key (e.g. ThingsBoard) and click Submit Copy and save the token — it is displayed only once

The uplink converter receives each ChirpStack uplink message as raw bytes, decodes the LoRaWAN payload, and returns a structured object that ThingsBoard uses to create or update a device and store its telemetry and attributes.

If your device is in the built-in catalog, use the Library tab instead of writing a decoder — see Converters library for over 100 ready-made decoders.

For the full decoder function reference — all input parameters and output fields — see Uplink data converter.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.

In the Add data converter dialog:

3. Converter type — leave Uplink (selected by default).
4. Integration type — in the search field, enter ChirpStack and select ChirpStack from the list.
5. Name — enter a converter name, for example ChirpStack Uplink Converter.
6. Configure main decoding parameters:
   • Specifies the device naming template and entity type. The default value Device $eui uses the device EUI as the unique name in ThingsBoard.
   • The default decoder is pre-filled. Leave it unchanged for this guide.
     By default the editor opens in TBEL; use the TBEL / JS toggle (upper right) to switch languages.
   • TBEL (Recommended)
   • JavaScript

   /**
   * Decodes the incoming payload and returns a structured object containing telemetry data and attributes.
   *
   * @param {byte[]} input - The raw payload received as an array of bytes.
   * @returns {Object} output - The structured output with decoded telemetry and attributes.
   */
   
   function decodePayload(input) {
   // Initialize the output object with empty attributes and telemetry for clarity.
   var result = { attributes: {}, telemetry: {}};
   
   // Extract the timestamp from metadata (represented in milliseconds).
   var timestamp = metadata.ts; // ts is the timestamp parsed from the incoming message's time, or returns the current time if it cannot be parsed.
   
   if (metadata.payloadFormat == 'JSON') {
   // payloadFormat is 'JSON' when ChirpStack sends a pre-decoded JSON payload
   // (the uplink contains an "object" field produced by a codec/payload formatter).
   // All fields from the decoded object are put directly into telemetry.
   var decoded = decodeToJson(input);
   result.telemetry = {
   ts: timestamp,
   values: decoded
   };
   return result;
   }
   
   // payloadFormat is 'BINARY' when raw base64 payload is received (data field).
   
   // Decode serial number (SN) from the first 4 bytes of the payload.
   // Press '?' icon in the top right corner to learn more about built in helper functions and capabilities.
   result.attributes.sn = parseBytesToInt(input, 0, 4);
   
   // Combine the timestamp with decoded values and add it to the telemetry.
   result.telemetry = {
   ts: timestamp,
   values: {
   // Decode battery level from the 5th byte of the payload.
   battery: parseBytesToInt(input, 4, 1),
   // Decode temperature from the 6th and 7th bytes of the payload (divided by 100).
   temperature: parseBytesToInt(input, 5, 2) / 100.0,
   // Decode saturation from the 8th byte of the payload.
   saturation: parseBytesToInt(input, 7, 1)
   }
   };
   
   // Return the fully constructed output object.
   return result;
   // Same logic, less code:
   // return {
   //     attributes: {
   //         sn: parseBytesToInt(input, 0, 4)
   //     },
   //     telemetry: {
   //         ts: convertDateToTimestamp(metadata.time),
   //         values: {
   //             battery: parseBytesToInt(input, 4, 1),
   //             temperature: parseBytesToInt(input, 5, 2) / 100.0,
   //             saturation: parseBytesToInt(input, 7, 1)
   //         }
   //     }
   // };
   }
   
   var result = decodePayload(payload);
   // Uncomment this code block to overwrite values set in the main configuration window. Useful if you extract device/asset/customer/group names from the payload;
   // result.type = 'DEVICE'; // Entity type allows you to choose type of created entity. Can be 'DEVICE' or 'ASSET'.
   // result.name = 'Temperature Sensor'; // Device or asset name (the value must be unique)
   // result.profile = 'IndustrialSensorProfile'; // Device or asset profile name.
   // result.customer = 'MyCustomer'; // If customer is not null - created entity will be assigned to customer with such name.
   // result.group = 'SensorsGroup'; // If group is not null - created entity will be added to the entity group with such name.
   
   // Return the final result object.
   return result;

7. Check advanced decoding parameters — pre-populated for ChirpStack; leave defaults unless your setup differs.

8. Click Add.

Payload Formats

ChirpStack sends the LoRaWAN payload in one of two formats, indicated by metadata.payloadFormat:

What the Converter Receives

ThingsBoard passes two variables to the decoder:

Key metadata fields pre-populated for ChirpStack:

What the Converter Must Return

The decoder must return a plain object. The device name is resolved from the Main decoding configuration naming template unless overridden in the script:

*When name is not set, ThingsBoard applies the Main decoding configuration template. The default template Device $eui substitutes $eui with the device EUI from the ChirpStack message (e.g. Device 24e124538b223213). On the first uplink ThingsBoard creates the device; on subsequent uplinks it updates the existing one.

Understanding the Example Decoder

The example BINARY decoder expects an 8-byte payload with this layout:

BINARY — input → output. For the test payload "ALxhTl8JKVA=" used in Send Test Uplink:

{
  "attributes": { "sn": 12345678 },
  "telemetry": {
    "ts": 1742480572653,
    "values": { "battery": 95, "temperature": 23.46, "saturation": 80 }
  }
}

JSON — input → output. When a ChirpStack payload codec is active, the object field arrives pre-decoded and the converter writes all its fields directly to telemetry. If ChirpStack decodes the payload to:

{ "temperature": 23.5, "humidity": 60, "battery": 95 }

The converter produces:

{
  "telemetry": {
    "ts": 1742480572653,
    "values": { "temperature": 23.5, "humidity": 60, "battery": 95 }
  }
}

Adapting the Decoder to Your Device

• Match your payload structure — update byte offsets, lengths, and field names in decodePayload to match your device’s binary specification. Refer to your device’s payload documentation for the byte layout.
• Add or remove fields — add more parseBytesToInt calls (or parseBytesToFloat, string extraction, etc.) for additional sensors; remove entries your device does not transmit.
• Use a ChirpStack payload codec — configure a codec in ChirpStack and metadata.payloadFormat becomes 'JSON'. The decoder already handles this path — no binary parsing needed.
• Override device identity from the payload — set result.name, result.profile, result.group, or result.customer to derive device identity from payload content rather than the Main decoding configuration template.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Select ChirpStack as the integration type.
   • Enter a Name for the integration, or keep the default ChirpStack integration.
   • Enable integration and Allow create devices or assets are enabled by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the ChirpStack Uplink Converter created in the previous step.
   • Alternatively, click Create new to define the decoder inline, or use Library to load a vendor-provided preset.
   • Click Next.
4. Downlink data converter:
   • Click Create new to add a downlink converter inline, or
   • Click Skip — the downlink converter is only needed for sending commands to devices and can be added later.
5. Connection:
   • Enter the ThingsBoard server Base URL.
   • Copy the HTTP endpoint URL — you will need it when configuring ChirpStack.
   • Enter the Application server URL (the ChirpStack REST API address; with a standard Docker Compose installation, typically port 8090).
   • Enter the Application server API Token — obtained in Add a ChirpStack API key above.
   • Use API for ChirpStack 4+ is enabled by default — disable only when connecting to ChirpStack 3.x.
   Read more about each parameter in connection settings.
6. Click Add to complete the integration.

Go to Integrations center → Integrations (1) and click + Add integration (2). Set Integration type to ChirpStack (3) and click Next (4) Click Select existing (5), choose ChirpStack Uplink Converter from the list, and click Next (6) Click Skip (7) — the downlink converter can be added later Connection: enter the Base URL (8), copy the HTTP endpoint URL for ChirpStack (9), enter the Application server URL (10) and API Token (11), then click Add (12)

Base URL

The base address of the ThingsBoard server, used to construct the HTTP endpoint URL.

HTTP Endpoint URL

Auto-generated endpoint for this integration. Configure ChirpStack to forward uplink messages to this URL.

Application Server URL

The address of the ChirpStack REST API service. With a standard Docker Compose installation, this is typically port 8090.

Application Server API Token

API token used to authenticate ThingsBoard requests to the ChirpStack API when sending downlink messages. See Add a ChirpStack API key.

Use API for ChirpStack 4+

Enables the ChirpStack v4 API. Enabled by default — disable only when connecting to ChirpStack 3.x.

Execute Remotely

When enabled, ThingsBoard generates an Integration key and Integration secret that allow the integration to run as a separate process outside the ThingsBoard cluster — useful when the integration must reach services not accessible from the ThingsBoard server.

See Remote Integration for setup details.

To forward uplink messages from ChirpStack to ThingsBoard, add an HTTP integration to your ChirpStack application. If you already have a ChirpStack application with your devices registered, skip steps 1–2.

1. Open ChirpStack UI.
2. Go to Tenant ⇾ Applications and click Add application.
3. Name the application (e.g. ThingsBoard) and click Submit.
4. Open the application and navigate to the Integrations tab.
5. In the integration catalog, click + on the HTTP card.
6. Paste the copied HTTP endpoint URL field from the ThingsBoard integration. Click Submit.

Now every uplink from the device will be sent to ThingsBoard.

Go to Applications and click Add application Name the application and click Submit Open the application and navigate to the Integrations tab Click + on the HTTP card Paste the HTTP endpoint URL into Event endpoint URL(s) and click Submit HTTP integration added — uplink messages will now be forwarded to ThingsBoard

After the integration is created, send a test uplink and confirm that ThingsBoard received the message, decoded it correctly, and provisioned the device.

When a device sends an uplink message via ChirpStack, ThingsBoard automatically creates the device on the first uplink (provided Allow create devices or assets is enabled in the integration settings) and stores its telemetry and attributes.

If you do not have a physical device sending data, you can emulate a device message by sending an HTTP request directly to the ThingsBoard endpoint using curl — bypassing ChirpStack entirely. This is useful to verify that the integration and uplink converter are configured correctly before connecting real hardware.

Use this command to send a test uplink message. Replace $HTTP_ENDPOINT_URL with the HTTP endpoint URL copied from the integration.

curl -v \
  -H "Content-Type: application/json" \
  -d '{"deduplicationId":"7658d04d-7f1c-4eb6-900b-d948f3061a9d","time":"2026-03-20T14:42:52.653+00:00","deviceInfo":{"tenantId":"6e073e9a-6b4f-4747-b22c-7507e0fdebfb","tenantName":"ChirpStack","applicationId":"c3f2c4aa-07c8-4d6c-8a86-7ea2d4a52dca","applicationName":"Sample Application","deviceProfileId":"d8ee6c09-414c-4b2e-888a-8e8f86e2197a","deviceProfileName":"chirpstack-sensor","deviceName":"chirpstack sensor 001","devEui":"24e124538b223213","deviceClassEnabled":"CLASS_A","tags":{}},"devAddr":"01a44d4c","adr":true,"dr":5,"fCnt":153,"fPort":84,"confirmed":false,"data":"ALxhTl8JKVA=","rxInfo":[{"gatewayId":"24e124fffef64e9e","uplinkId":25127,"gwTime":"2026-03-20T14:42:52.653481+00:00","nsTime":"2026-03-20T14:42:52.670509207+00:00","timeSinceGpsEpoch":"1458052990.653s","rssi":-68,"snr":13.2,"channel":4,"location":{},"context":"Hw9+zQ==","crcStatus":"CRC_OK"}],"txInfo":{"frequency":867300000,"modulation":{"lora":{"bandwidth":125000,"spreadingFactor":7,"codeRate":"CR_4_5"}}},"regionConfigId":"eu868"}' \
  "$HTTP_ENDPOINT_URL"

Go to Integrations center ⇾ Integrations, open ChirpStack integration, and click the Events tab. Each successfully processed uplink appears as a row with status OK.

Open the Events tab of the ChirpStack integration to review received uplink messages and processing status. Open the event details to inspect the raw uplink message received from ChirpStack before conversion and processing.

To inspect converter processing, go to Integrations center ⇾ Data converters, click ChirpStack Uplink Converter, and open its Events tab:

• In shows the raw ChirpStack message
• Out shows the decoded result (attributes, telemetry)
• Metadata contains the integration name and any key-value pairs configured on the integration

Open the Events tab of the uplink converter to review converter execution history and inspect processed messages. The In view displays the raw ChirpStack uplink payload received by the converter. The Out view displays the parsed converter result, including extracted attributes and telemetry values. The Metadata view contains additional processing details such as the integration name used during conversion.

Go to Entities ⇾ Devices. Once an uplink is received, a new device named Device 24e124538b223213 (matching the devEui from the payload) appears.

After the first uplink message is processed, the ChirpStack integration automatically creates a corresponding device in ThingsBoard. The created device contains attributes and telemetry values extracted from the ChirpStack uplink payload by the converter.

The downlink converter (encoder) transforms a Rule Engine message into the payload delivered to the device through the ChirpStack API. For the full encoder function reference, see Downlink data converter.

1. Go to Integrations center ⇾ Integrations and open the ChirpStack integration.
2. Click the pencil icon to enter edit mode.
3. In the Downlink data converter field, click Create new.
4. Enter a name, paste the encoder script shown after these steps, then click Add.

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

/** Encoder **/

// Result object with encoded downlink payload
var result = {

  // downlink data content type: JSON, TEXT or BINARY (base64 format)
  contentType: "TEXT",

  // downlink data
  data: btoa(msg),

  // Optional metadata object presented in key/value format
  metadata: {
    DevEUI: metadata.cs_eui,
    fPort: metadata.cs_fPort
  }
};

return result;

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

/** Encoder **/

// Result object with encoded downlink payload
var result = {

  // downlink data content type: JSON, TEXT or BINARY (base64 format)
  contentType: "TEXT",

  // downlink data
  data: btoa(msg),

  // Optional metadata object presented in key/value format
  metadata: {
    DevEUI: metadata.cs_eui,
    fPort: metadata.cs_fPort
  }
};

return result;

5. Click Apply changes.

The encoder base64-encodes the entire Rule Engine message as the LoRaWAN payload. metadata.cs_eui and metadata.cs_fPort are populated by the get required fields node in the downlink rule chain, which reads the eui and fPort client attributes from the device. Both attributes must be set on each device before downlinks can be delivered.

Open the ChirpStack integration and click the edit button. In the Downlink data converter field, click Create new. Enter a name for the converter, paste the downlink encoder script into the converter editor and click Add. Click Apply changes to save the integration.

ChirpStack downlinks require two device-specific values — eui and fPort — that must be looked up from the device’s client attributes before calling the ChirpStack API. A dedicated rule chain handles this lookup cleanly. In the Root Rule Chain, a check relation presence node filters messages so that only devices managed by this ChirpStack integration enter the downlink flow, preventing unrelated devices from accidentally triggering it.

Download the rule chain file: downlink_to_chirpstack.json

1. Go to Rule chains and click + Add rule chain ⇾ Import rule chain.
2. Drag downlink_to_chirpstack.json into the import window and click Import.
3. The Downlink to ChirpStack rule chain opens - double-click the integration downlink node.
4. Set Integration to your ChirpStack integration and click Add.
5. Click Apply changes to save the rule chain.

Go to Rule chains, click + → Import rule chain, drop the JSON file, and click Import The Downlink to ChirpStack rule chain opens — double-click the integration downlink node Set Integration to ChirpStack integration and click Add Click Apply changes to save the Downlink to ChirpStack rule chain

The rule chain contains two nodes connected in sequence:

• get required fields — reads the fPort and eui client attributes from the device and copies them into message metadata as cs_fPort and cs_eui. If either attribute is absent on the device, the message takes the Failure path and no downlink is sent. Make sure both attributes are set on every device before testing.
• Send downlink — forwards the message to the ChirpStack integration, which runs the downlink converter and queues the encoded payload through the ChirpStack API.

1. Go to Rule chains and open the Root Rule Chain.
2. Search for check relation presence in the node panel and drag it onto the canvas.
3. Configure the check relation presence node:
   • Name: Check relation to ChirpStack integration
   • Direction: To originator
   • Relation type: ManagedByIntegration
   • Enable Check relation to specific entity
   • Set Type to Integration, and select your ChirpStack integration
   • Click Add
4. Connect the message type switch node to the check relation presence node using the Attributes Updated link.
5. Search for rule chain in the node panel and drag it onto the canvas.
6. Configure the rule chain node:
   • Name: Downlink to ChirpStack
   • Rule chain: Downlink to ChirpStack.
   • Click Add
7. Connect the check relation presence node’s True output to the rule chain node.
8. Click Apply changes to save the Root Rule Chain.

Open the Root Rule Chain and drag the check relation presence node onto the canvas Name the node, set direction to To originator, relation type to ManagedByIntegration, select ChirpStack integration, and click Add Connect the message type switch node to check relation presence using the Post attributes and Attributes Updated links Search for the rule chain node and drag it onto the canvas Name the node Downlink to ChirpStack, select the Downlink to ChirpStack rule chain, and click Add Connect the True output of check relation presence to the rule chain node, then click Apply changes

The encoder base64-encodes the entire Rule Engine message — adding or updating any shared attribute on the device triggers a downlink.

1. Go to Entities ⇾ Devices, select your device, open the Attributes tab.
2. Switch to Shared attributes, click + to add a new attribute.
3. Set the key (e.g. powerState) and a value (e.g. on).
4. Click Add.

Check the downlink converter Events tab:

• In shows the ATTRIBUTES_UPDATED message
• Out shows the encoded payload with DevEUI and fPort in metadata

Open the Events tab of the ChirpStack Downlink data converter and click the entry in the In column to inspect the incoming Rule Engine message. In — the Rule Engine message and metadata received by the downlink converter before encoding. Out — the encoded ChirpStack downlink payload generated by the converter and ready to be sent to the device.

How to read Debug Events

1. Go to Integrations center ⇾ Integrations, open the ChirpStack integration, and click the Events tab. Filter by Uplink.
2. Click on an event to inspect:

• In — the raw ChirpStack webhook message received by the integration
• Out — what the converter returned: decoded device name, attributes, and telemetry
• Error — error text, if any

Enable Debug mode on the integration to capture all raw input/output events. Starting from ThingsBoard 3.9, the full set of debug events is stored only during the first 1 hour; afterward, only error events are retained. Disable debug mode once the issue is identified.

• Integration overview
• Uplink data converter
• Downlink data converter
• Rule Engine