ThingsBoard Integration

ThingsBoard is an open-source IoT platform for data collection, processing, visualization, and device management. This guide shows how to integrate Haltian IoT data with ThingsBoard.

Compatibility

Prerequisites

• Haltian IoT MQTT credentials (API key ID and token)
• ThingsBoard instance (Cloud or self-hosted)
• Device ID mapping (UUID to physical device)

Architecture

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#73f9c1','primaryTextColor':'#143633','primaryBorderColor':'#143633','lineColor':'#143633'}}}%%
graph LR
    A[Haltian Sensors] --> B[Haltian IoT Platform]
    B --> C[MQTT Broker]
    C --> D[ThingsBoard<br/>MQTT Integration]
    D --> E[Uplink Converter]
    E --> F[ThingsBoard<br/>Device Entities]
    F --> G[Dashboards]
    
    style B fill:#143633,stroke:#143633,color:#fff
    style D fill:#73f9c1,stroke:#143633,color:#143633

Step 1: Create Uplink Converter

The uplink converter transforms Haltian IoT MQTT messages into ThingsBoard format.

1. Navigate to ThingsBoard → Data Converters
2. Click Add Data Converter → Create new converter
3. Set type to Uplink
4. Paste the following decoder code:

// Haltian IoT MQTT Uplink Converter for ThingsBoard
// Decodes Haltian IoT JSON messages and maps to ThingsBoard telemetry

// Decode payload to JSON
var payloadStr = decodeToString(payload);
var data = decodeToJson(payload);

// Extract device info from MQTT topic
var topic = metadata["topic"];
var topics = topic.split("/");
var deviceName = topics[topics.length - 1];       // Device UUID
var measurementName = topics[topics.length - 2]; // Measurement type

var deviceType = 'Haltian IoT device';
var manufacturer = 'Haltian IoT';

// Build telemetry map
var map = {};

foreach(element : data.entrySet()) {
    var k = element.getKey();
    var v = element.getValue();
    var p = measurementName + "." + k;
    map.put(p, v);
    
    // Special handling for position data
    if (measurementName == "position" && k == "value") {
        if (v.position_global && v.position_global.coordinates) {
            var lon = v.position_global.coordinates[0];
            var lat = v.position_global.coordinates[1];
            map.put("latitude", lat);
            map.put("longitude", lon);
        }
        if (v.position_local) {
            map.put("position_x", v.position_local.x);
            map.put("position_y", v.position_local.y);
            map.put("position_z", v.position_local.z);
        }
        if (v.accuracy) {
            map.put("position_accuracy", v.accuracy);
        }
    }
    
    // Flatten simple measurements
    if (measurementName != "position" && k == "value") {
        map.put(measurementName, v);
    }
}

// Return result for ThingsBoard
var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    telemetry: map
};

return result;

5. Click Add to save the converter

Step 2: Create MQTT Integration

1. Navigate to ThingsBoard → Integrations
2. Click Add Integration
3. Configure the integration:

4. Set the topic filter:

haltian-iot/events/{integration-id}/{api-key-id}/#

Replace {integration-id} and {api-key-id} with your actual values.

5. Click Add to create the integration

Step 3: Verify Data Flow

1. Navigate to Entities → Devices
2. Verify new devices appear as MQTT data is received
3. Devices are named by their Haltian IoT UUID

Check Device Telemetry

1. Click on a device
2. Navigate to Latest telemetry tab
3. Verify measurements are being received:

Step 4: Map Device Identifiers

Haltian IoT uses UUIDs for device identification. To map to physical devices:

Option A: Use ThingsBoard Labels

Add the TUID (from device QR code) to the device label:

1. Edit device in ThingsBoard
2. Set Label to the TUID (e.g., TSPR04EZU31901021)

Option B: Query Haltian IoT API

Use the Service API to get device mappings:

query GetAllDevices {
  devices(first: 100) {
    edges {
      node {
        id      # UUID used in MQTT
        tuid    # Physical device identifier
        name
      }
    }
  }
}

Step 5: Create Dashboards

Build dashboards using Haltian IoT device data:

1. Navigate to Dashboards
2. Create new dashboard
3. Add widgets with device data sources

Widget Configuration

Example Dashboard Layout

┌─────────────────┬─────────────────┐
│  Temperature    │    Humidity     │
│     23.5°C      │      45%        │
├─────────────────┼─────────────────┤
│  CO2 Level      │   Battery       │
│    850 ppm      │      85%        │
├─────────────────┴─────────────────┤
│         Temperature History        │
│  ────────────────────────────     │
└───────────────────────────────────┘

Advanced: Downlink Messages

Haltian IoT MQTT is primarily for uplink (sensor → cloud). For device commands:

• Use Haltian IoT Service API (GraphQL) for device configuration
• Downlink via MQTT is not currently supported

Improved Converter (Extended)

For more sophisticated data handling:

// Extended Haltian IoT Converter with device type detection

var payloadStr = decodeToString(payload);
var data = decodeToJson(payload);
var topic = metadata["topic"];
var topics = topic.split("/");

var deviceId = topics[topics.length - 1];
var measurementType = topics[topics.length - 2];
var eventKind = topics[topics.length - 3];

// Determine device type from measurement
var deviceType = 'Haltian IoT Sensor';
if (measurementType == 'position' || measurementType == 'position_zone') {
    deviceType = 'Haltian Asset Tag';
} else if (measurementType == 'presence' || measurementType == 'pir_count') {
    deviceType = 'Haltian Presence Sensor';
} else if (measurementType == 'co2' || measurementType == 'tvoc') {
    deviceType = 'Haltian Environment Sensor';
}

var telemetry = {};
var timestamp = null;

// Extract timestamp
if (data.measured_at) {
    timestamp = new Date(data.measured_at).getTime();
}

// Process value based on type
if (data.value !== undefined) {
    if (typeof data.value === 'object') {
        // Complex value - flatten
        foreach(prop : data.value.entrySet()) {
            telemetry[measurementType + '_' + prop.getKey()] = prop.getValue();
        }
    } else {
        // Simple value
        telemetry[measurementType] = data.value;
    }
}

// Add metadata
telemetry['last_measurement_type'] = measurementType;

var result = {
    deviceName: deviceId,
    deviceType: deviceType,
    telemetry: {
        ts: timestamp,
        values: telemetry
    }
};

return result;

Troubleshooting

No Devices Appearing

1. Check integration status in ThingsBoard
2. Verify MQTT credentials are correct
3. Ensure topic filter matches your integration/API key IDs
4. Check ThingsBoard logs for connection errors

Data Not Updating

1. Verify sensor is sending data (check Haltian IoT Studio)
2. Check uplink converter for errors
3. Ensure device hasn’t been renamed in ThingsBoard

Position Data Missing

The basic converter requires enhancement for position data. Use the extended converter above or add specific position handling.

Next Steps

• Stream API Reference - MQTT topic structure
• Service API - Query device metadata
• Measurement Types - All available measurements