ThingsBoard Widget Configuration

Custom configuration settings and features for the ThingsBoard platform.

Overview

When the ThingsBoard provider is selected, the widget works integrated with the ThingsBoard IoT platform and platform-specific features are available.

Provider Definition

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "my-thingsboard-widget",
    "type": "latest"
  }
}

ThingsBoard Platform Features

1. Type Parameters (ThingsBoard Specific)

Special data configuration for ThingsBoard widgets:

json

{
  "data": {
    "dataKeys": [
      {
        "name": "latitude",
        "label": "Latitude",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "latitude"
        }
      },
      {
        "name": "longitude",
        "label": "Longitude",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "longitude"
        }
      }
    ],
    "latestDataKeys": [
      {
        "name": "status",
        "label": "Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "maxDataKeys": -1,
      "singleEntity": false,
      "embedTitlePanel": true,
      "datasourcesOptional": false,
      "dataKeysOptional": false,
      "hideDataTab": false,
      "hideDataSettings": false
    },
    "defaultConfig": {
      "title": "ThingsBoard Widget",
      "backgroundColor": "#ffffff",
      "showLegend": true,
      "refreshInterval": 1000,
      "datasourceType": "entity",
      "timewindow": {
        "realtime": {
          "timewindowMs": 60000
        }
      }
    }
  }
}

additionalTypeParameters (ThingsBoard Specific)

Special parameters for ThingsBoard platform:

Parameter	Type	Default	Description
`maxDatasources`	number	1	Maximum number of datasources (-1: unlimited)
`maxDataKeys`	number	-1	Maximum number of data keys (-1: unlimited)
`singleEntity`	boolean	false	Single entity support
`embedTitlePanel`	boolean	true	Show title panel
`datasourcesOptional`	boolean	false	Are datasources optional
`dataKeysOptional`	boolean	false	Are data keys optional
`hideDataTab`	boolean	false	Hide data tab
`hideDataSettings`	boolean	false	Hide data settings
`fullScreenButton`	boolean	true	Full screen button
`fitScreenButton`	boolean	true	Fit to screen button
`comparisonEnabled`	boolean	false	Comparison mode

Example:

json

{
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": 5,
      "maxDataKeys": 10,
      "singleEntity": true,
      "embedTitlePanel": true,
      "fullScreenButton": true,
      "fitScreenButton": true,
      "comparisonEnabled": false,
      "hideDataTab": false,
      "hideDataSettings": false
    }
  }
}

defaultConfig (ThingsBoard Specific)

Default configuration for ThingsBoard widget:

json

{
  "data": {
    "defaultConfig": {
      "title": "IoT Device Monitor",
      "backgroundColor": "#ffffff",
      "textColor": "#000000",
      "color": "#2196F3",
      "showLegend": true,
      "showTitle": true,
      "enableAnimation": true,
      "fullScreenButton": true,
      "fitScreenButton": true,
      "comparisonEnabled": false,
      "refreshInterval": 1000,
      "datasourceType": "entity",
      "settings": {},
      "datasources": [],
      "decimals": null,
      "width": 8,
      "height": 8,
      "timewindow": {
        "realtime": {
          "timewindowMs": 60000
        }
      }
    }
  }
}

2. Data Keys (ThingsBoard)

Timeseries Data Keys

json

{
  "data": {
    "dataKeys": [
      {
        "name": "temperature",
        "label": "Temperature",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "temperature",
          "units": "°C",
          "decimals": 1,
          "color": "#FF5722"
        }
      },
      {
        "name": "humidity",
        "label": "Humidity",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "humidity",
          "units": "%",
          "decimals": 0,
          "color": "#2196F3"
        }
      }
    ]
  }
}

Latest Data Keys (Attributes)

json

{
  "data": {
    "latestDataKeys": [
      {
        "name": "status",
        "label": "Device Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      },
      {
        "name": "lastUpdate",
        "label": "Last Update",
        "type": "attribute",
        "settings": {
          "dataKeyType": "timestamp"
        }
      }
    ]
  }
}

Dynamic Data Keys Function

json

{
  "data": {
    "dataKeysFunction": "function() { return [{name: 'temp', label: 'Temperature', type: 'timeseries', settings: {dataKeyType: 'temperature'}}]; }",
    "latestDataKeysFunction": "function() { return [{name: 'status', label: 'Status', type: 'attribute', settings: {dataKeyType: 'status'}}]; }"
  }
}

4. External Libraries (ThingsBoard Optimized)

External library management optimized for ThingsBoard platform:

json

{
  "build": {
    "externals": {
      "leaflet": "L",
      "chart.js": "Chart",
      "moment": "moment"
    }
  }
}

ThingsBoard Build Profiles

Development Profile (ThingsBoard)

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "iot-widget"
  },
  "build": {
    "debug": true,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  },
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": -1,
      "maxDataKeys": -1,
      "embedTitlePanel": true
    },
    "defaultConfig": {
      "refreshInterval": 1000
    }
  }
}

Production Profile (ThingsBoard)

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "iot-widget"
  },
  "build": {
    "debug": false,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "leaflet": "L",
      "chart.js": "Chart"
    }
  },
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "maxDataKeys": 10,
      "embedTitlePanel": true,
      "fullScreenButton": true
    },
    "defaultConfig": {
      "refreshInterval": 1000,
      "timewindow": {
        "realtime": {
          "timewindowMs": 60000
        }
      }
    }
  }
}

Custom Scenarios

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "device-tracker",
    "type": "latest"
  },
  "build": {
    "entry": "tracker.ts",
    "sourceRoot": "src",
    "outputFilename": "tracker.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "leaflet": "L"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "latitude",
        "label": "Latitude",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "latitude"
        }
      },
      {
        "name": "longitude",
        "label": "Longitude",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "longitude"
        }
      },
      {
        "name": "speed",
        "label": "Speed",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "speed",
          "units": "km/h"
        }
      }
    ],
    "latestDataKeys": [
      {
        "name": "status",
        "label": "Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "singleEntity": true,
      "embedTitlePanel": true,
      "fullScreenButton": true
    },
    "defaultConfig": {
      "title": "Device Tracker",
      "datasourceType": "entity",
      "timewindow": {
        "realtime": {
          "timewindowMs": 300000
        }
      }
    }
  }
}

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "sensor-dashboard",
    "type": "latest"
  },
  "build": {
    "entry": "dashboard.ts",
    "sourceRoot": "src",
    "outputFilename": "dashboard.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "temperature",
        "label": "Temperature",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "temperature",
          "units": "°C",
          "decimals": 1,
          "color": "#FF5722"
        }
      },
      {
        "name": "humidity",
        "label": "Humidity",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "humidity",
          "units": "%",
          "decimals": 0,
          "color": "#2196F3"
        }
      },
      {
        "name": "pressure",
        "label": "Pressure",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "pressure",
          "units": "hPa",
          "decimals": 1,
          "color": "#4CAF50"
        }
      }
    ],
    "latestDataKeys": [
      {
        "name": "batteryLevel",
        "label": "Battery",
        "type": "attribute",
        "settings": {
          "dataKeyType": "battery",
          "units": "%"
        }
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 5,
      "maxDataKeys": 20,
      "singleEntity": false,
      "embedTitlePanel": true,
      "comparisonEnabled": true
    },
    "defaultConfig": {
      "title": "Sensor Dashboard",
      "showLegend": true,
      "refreshInterval": 5000,
      "datasourceType": "entity",
      "width": 12,
      "height": 10
    }
  }
}

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "alarm-widget",
    "type": "latest"
  },
  "build": {
    "entry": "alarm.ts",
    "sourceRoot": "src",
    "outputFilename": "alarm.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  },
  "data": {
    "latestDataKeys": [
      {
        "name": "alarmType",
        "label": "Alarm Type",
        "type": "alarm",
        "settings": {
          "dataKeyType": "alarm"
        }
      },
      {
        "name": "alarmSeverity",
        "label": "Severity",
        "type": "alarm",
        "settings": {
          "dataKeyType": "severity"
        }
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "singleEntity": true,
      "embedTitlePanel": true,
      "hideDataTab": false
    },
    "defaultConfig": {
      "title": "Alarms",
      "datasourceType": "entity",
      "backgroundColor": "#fff3e0"
    }
  }
}

Timewindow Configuration

Realtime Timewindow

json

{
  "data": {
    "defaultConfig": {
      "timewindow": {
        "realtime": {
          "timewindowMs": 60000
        }
      }
    }
  }
}

History Timewindow

json

{
  "data": {
    "defaultConfig": {
      "timewindow": {
        "history": {
          "timewindowMs": 3600000,
          "interval": 1000
        }
      }
    }
  }
}

Aggregation

json

{
  "data": {
    "defaultConfig": {
      "timewindow": {
        "realtime": {
          "timewindowMs": 3600000,
          "interval": 60000
        },
        "aggregation": {
          "type": "AVG",
          "limit": 200
        }
      }
    }
  }
}

ThingsBoard Platform Validation

Configuration Check

CLI automatically performs ThingsBoard-specific validation:

Required fields:

json

{
  "configurations": {
    "provider": "thingsboard"  // REQUIRED
  },
  "build": {
    "entry": "...",           // REQUIRED
    "sourceRoot": "...",      // REQUIRED
    "outputFilename": "...",  // REQUIRED
    "outputPath": "..."       // REQUIRED
  }
}

Error Messages (ThingsBoard Specific)

Invalid ThingsBoard configuration:

Error: ThingsBoard wrapper validation failed: Missing datasource configuration

Data key configuration error:

Error: dataKeys must be an array for ThingsBoard widgets

Performance Optimization (ThingsBoard)

Bundle Size Optimization

json

{
  "build": {
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/widget": "XConWidgetCore",
      "leaflet": "L",
      "chart.js": "Chart",
      "moment": "moment"
    }
  }
}

Bundle size comparison:

NO Externals: ~600KB
WITH Externals: ~60KB (10x smaller!)

Troubleshooting (ThingsBoard Specific)

Problem: Widget not showing in ThingsBoard widget library

Solution 1 - Check provider:

json

{
  "configurations": {
    "provider": "thingsboard"  // Not "web"!
  }
}

Solution 2 - Type Parameters:

json

{
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "embedTitlePanel": true
    }
  }
}

Data Keys Not Working

Problem: Widget not receiving data

Solution - Define data keys:

json

{
  "data": {
    "dataKeys": [
      {
        "name": "temperature",
        "label": "Temperature",
        "type": "timeseries"
      }
    ]
  }
}

Best Practices (ThingsBoard)

1. Datasource Limits

Recommended:

json

{
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": 5,      // Reasonable limit
      "maxDataKeys": 20          // Manageable amount
    }
  }
}

Not Recommended:

json

{
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": -1,      // Unlimited (performance issue)
      "maxDataKeys": -1           // Unlimited (performance issue)
    }
  }
}

2. Refresh Interval

Good:

json

{
  "data": {
    "defaultConfig": {
      "refreshInterval": 5000    // 5 seconds (balanced)
    }
  }
}

Bad:

json

{
  "data": {
    "defaultConfig": {
      "refreshInterval": 100     // 100ms (too fast, performance issue)
    }
  }
}

3. Data Keys Organization

Correct:

json

{
  "data": {
    "dataKeys": [              // Timeseries data
      {"name": "temp", "type": "timeseries"}
    ],
    "latestDataKeys": [        // Attribute data
      {"name": "status", "type": "attribute"}
    ]
  }
}

Incorrect:

json

{
  "data": {
    "dataKeys": [              // Mixed types (confusing)
      {"name": "temp", "type": "timeseries"},
      {"name": "status", "type": "attribute"}
    ]
  }
}

Example Configurations

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "simple-iot-widget"
  },
  "build": {
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  },
  "data": {
    "dataKeys": [
      {
        "name": "value",
        "label": "Value",
        "type": "timeseries"
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "embedTitlePanel": true
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "advanced-iot-widget",
    "type": "latest",
    "fqn": "com.example.AdvancedIoTWidget"
  },
  "build": {
    "debug": false,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/widget": "XConWidgetCore",
      "leaflet": "L",
      "chart.js": "Chart"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "latitude",
        "label": "Latitude",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "latitude"
        }
      },
      {
        "name": "longitude",
        "label": "Longitude",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "longitude"
        }
      }
    ],
    "latestDataKeys": [
      {
        "name": "status",
        "label": "Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "maxDataKeys": 10,
      "singleEntity": true,
      "embedTitlePanel": true,
      "fullScreenButton": true,
      "fitScreenButton": true,
      "comparisonEnabled": false
    },
    "defaultConfig": {
      "title": "IoT Device Tracker",
      "backgroundColor": "#ffffff",
      "showLegend": true,
      "refreshInterval": 1000,
      "datasourceType": "entity",
      "timewindow": {
        "realtime": {
          "timewindowMs": 60000
        }
      }
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

Migration Guide

Migration from Web to ThingsBoard

Web config:

json

{
  "configurations": {
    "provider": "web"
  },
  "data": {
    "additionalTypeParameters": {
      "refreshInterval": 1000,
      "autoRefresh": true
    }
  }
}

ThingsBoard config:

json

{
  "configurations": {
    "provider": "thingsboard"
  },
  "data": {
    "dataKeys": [
      {"name": "value", "type": "timeseries"}
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "embedTitlePanel": true
    },
    "defaultConfig": {
      "refreshInterval": 1000,
      "datasourceType": "entity"
    }
  }
}

Your ThingsBoard widget configuration is ready!

ThingsBoard Widget Configuration ​

Overview ​

Provider Definition ​

ThingsBoard Platform Features ​

1. Type Parameters (ThingsBoard Specific) ​

additionalTypeParameters (ThingsBoard Specific) ​

defaultConfig (ThingsBoard Specific) ​

2. Data Keys (ThingsBoard) ​

Timeseries Data Keys ​

Latest Data Keys (Attributes) ​

Dynamic Data Keys Function ​

4. External Libraries (ThingsBoard Optimized) ​

ThingsBoard Build Profiles ​

Development Profile (ThingsBoard) ​

Production Profile (ThingsBoard) ​

Custom Scenarios ​

1. IoT Device Tracker Widget ​

2. Multi-Sensor Dashboard Widget ​

3. Alarm Widget ​

Timewindow Configuration ​

Realtime Timewindow ​

History Timewindow ​

Aggregation ​

ThingsBoard Platform Validation ​

Configuration Check ​

Error Messages (ThingsBoard Specific) ​

Performance Optimization (ThingsBoard) ​

Bundle Size Optimization ​

Troubleshooting (ThingsBoard Specific) ​

Widget Not Showing in ThingsBoard ​

Data Keys Not Working ​

Best Practices (ThingsBoard) ​

1. Datasource Limits ​

2. Refresh Interval ​

3. Data Keys Organization ​

Example Configurations ​

Minimal ThingsBoard Widget ​

Advanced ThingsBoard Widget ​

Migration Guide ​

Migration from Web to ThingsBoard ​

ThingsBoard Widget Configuration

Overview

Provider Definition

ThingsBoard Platform Features

1. Type Parameters (ThingsBoard Specific)

additionalTypeParameters (ThingsBoard Specific)

defaultConfig (ThingsBoard Specific)

2. Data Keys (ThingsBoard)

Timeseries Data Keys

Latest Data Keys (Attributes)

Dynamic Data Keys Function

4. External Libraries (ThingsBoard Optimized)

ThingsBoard Build Profiles

Development Profile (ThingsBoard)

Production Profile (ThingsBoard)

Custom Scenarios

1. IoT Device Tracker Widget

2. Multi-Sensor Dashboard Widget

3. Alarm Widget

Timewindow Configuration

Realtime Timewindow

History Timewindow

Aggregation

ThingsBoard Platform Validation

Configuration Check

Error Messages (ThingsBoard Specific)

Performance Optimization (ThingsBoard)

Bundle Size Optimization

Troubleshooting (ThingsBoard Specific)

Widget Not Showing in ThingsBoard

Data Keys Not Working

Best Practices (ThingsBoard)

1. Datasource Limits

2. Refresh Interval

3. Data Keys Organization

Example Configurations

Minimal ThingsBoard Widget

Advanced ThingsBoard Widget

Migration Guide

Migration from Web to ThingsBoard