ThingsBoard Widget Create

Detailed usage guide for creating new widget projects for ThingsBoard IoT platform.

Overview

The xcons thingsboard create command creates a ready-to-use TypeScript widget project for ThingsBoard IoT platform. It automatically sets up project structure, IDE configurations, ThingsBoard integration, and build system.

Command Syntax

bash

xcons thingsboard create [options]
npx @xcons/cli thingsboard create [options]

Options

Option	Shorthand	Type	Default	Description
`--name <name>`	`-n`	string	-	Widget project name
`--description <desc>`	`-d`	string	-	Widget description
`--no-interaction`	-	flag	false	No interactive questions

Usage Examples

1. Interactive Mode (Recommended)

Simplest usage - command asks for required information interactively:

bash

xcons thingsboard create

Interaction:

? ThingsBoard Widget name: device-tracker
? Widget description: Real-time IoT device tracking widget
? Do you want to run npm install now? Yes

2. With Name Parameter

Provide widget name as parameter:

bash

xcons thingsboard create -n device-tracker

Interaction:

? Widget description: Real-time IoT device tracking widget
? Do you want to run npm install now? Yes

3. Full Parameters

Provide all parameters on command line:

bash

xcons thingsboard create -n device-tracker -d "Real-time IoT device tracking widget"

Interaction:

? Do you want to run npm install now? Yes

4. Non-Interactive Mode

For CI/CD or script usage:

bash

xcons thingsboard create -n device-tracker --no-interaction

Behavior:

Widget name: device-tracker
Description: "device-tracker widget" (automatic)
npm install: Skipped
No questions asked

5. Direct with NPX

Without global installation:

bash

npx @xcons/cli thingsboard create -n my-tb-widget

ThingsBoard-Specific Configuration

1. Setting Provider

Edit .xcon/config.json file:

json

{
  "configurations": {
    "provider": "thingsboard",        // Automatically set
    "id": "device-tracker-widget",    // Add widget ID
    "type": "latest"
  },
  "projectType": "widget",
  "version": "1.0"
}

2. ThingsBoard Build Settings

Complete ThingsBoard build configuration:

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "device-tracker-widget",
    "type": "latest",
    "fqn": "com.example.DeviceTracker"
  },
  "build": {
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.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"
        }
      }
    ],
    "latestDataKeys": [
      {
        "name": "status",
        "label": "Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "singleEntity": true,
      "embedTitlePanel": true
    },
    "defaultConfig": {
      "title": "Device Tracker",
      "datasourceType": "entity",
      "timewindow": {
        "realtime": {
          "timewindowMs": 60000
        }
      }
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

3. ThingsBoard Data Keys

Timeseries Data Keys

For reading IoT device data:

json

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

Latest Data Keys (Attributes)

For device status and metadata:

json

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

4. ThingsBoard Type Parameters

json

{
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "maxDataKeys": 10,
      "singleEntity": true,
      "embedTitlePanel": true,
      "fullScreenButton": true,
      "fitScreenButton": true,
      "datasourcesOptional": false,
      "dataKeysOptional": false
    }
  }
}

Workflow

bash

# Create project
xcons thingsboard create -n device-tracker

# Navigate to directory
cd device-tracker

2. Installing Dependencies

Automatic installation (recommended):

bash

xcons thingsboard create -n device-tracker
# "Do you want to run npm install now?" → Yes

Manual installation:

bash

npm install

ThingsBoard Specific Scenarios

bash

xcons thingsboard create -n iot-map-widget
cd iot-map-widget

.xcon/config.json:

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "iot-map-widget"
  },
  "build": {
    "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": "deviceName",
        "label": "Device Name",
        "type": "attribute"
      }
    ],
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "singleEntity": true,
      "embedTitlePanel": true
    }
  }
}

bash

xcons thingsboard create -n sensor-dashboard
cd sensor-dashboard

.xcon/config.json:

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "sensor-dashboard"
  },
  "build": {
    "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,
      "embedTitlePanel": true,
      "comparisonEnabled": true
    },
    "defaultConfig": {
      "title": "Sensor Dashboard",
      "showLegend": true,
      "refreshInterval": 5000
    }
  }
}

bash

xcons thingsboard create -n alarm-widget
cd alarm-widget

.xcon/config.json:

json

{
  "configurations": {
    "provider": "thingsboard",
    "id": "alarm-widget"
  },
  "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
    },
    "defaultConfig": {
      "title": "Device Alarms",
      "backgroundColor": "#fff3e0"
    }
  }
}

Troubleshooting

Error: Widget not found in library

Solution 1 - Check provider:

json

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

Solution 2 - Check build:

bash

# Build first
xcons thingsboard build --production

# Check output
ls -la dist/widget.min.js

Issue: Data keys not working

Error: Widget not receiving data

Solution - Define data keys:

json

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

Error: onInit, onDataUpdated not working

Solution - Check ThingsBoard wrapper:

ThingsBoard wrapper is automatically added during build. Make sure provider is "thingsboard".

Best Practices

1. Data Keys Organization

Correct:

json

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

Wrong:

json

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

2. Datasource Limits

Recommended:

json

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

Not Recommended:

json

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

3. Refresh Interval

Good:

json

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

Bad:

json

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

Correct:

bash

xcons thingsboard create -n device-tracker
xcons thingsboard create -n sensor-monitor
xcons thingsboard create -n alarm-dashboard

Wrong:

bash

xcons thingsboard create -n "Device Tracker"  # No spaces
xcons thingsboard create -n device_tracker     # Dash instead of underscore

Command Output

Successful Creation

bash

$ xcons thingsboard create -n device-tracker

Creating ThingsBoard widget project...
Downloading and extracting ThingsBoard template from GitHub...
  Downloading ZIP file...
  Extracting files directly to widget directory...
ThingsBoard template downloaded and extracted successfully
Creating .xcon configuration...
.xcon/config.json created successfully
Updating .idea configuration files...
  Renamed xcon-web-cli.iml to device-tracker.iml
  Updated modules.xml to reference device-tracker.iml
  Cleared PropertiesComponent and RecentsManager in workspace.xml
.idea configuration files updated successfully
ThingsBoard widget project 'device-tracker' created successfully!
Location: /Users/dev/projects/device-tracker

? Do you want to run npm install now? Yes
Running npm install...
npm install completed successfully

Next steps:
cd device-tracker
npm run build
Develop your ThingsBoard widget

Non-Interactive Mode Output

bash

$ xcons thingsboard create -n device-tracker --no-interaction

Creating ThingsBoard widget project...
Downloading and extracting ThingsBoard template from GitHub...
ThingsBoard template downloaded and extracted successfully
Creating .xcon configuration...
.xcon/config.json created successfully
Updating .idea configuration files...
.idea configuration files updated successfully
ThingsBoard widget project 'device-tracker' created successfully!
Location: /Users/dev/projects/device-tracker
  Skipping npm install due to --no-interaction flag

Next steps:
cd device-tracker
npm install
npm run build
Develop your ThingsBoard widget

Frequently Asked Questions

Q: What's the difference between ThingsBoard widget and web widget? A: ThingsBoard widgets use IoT platform-specific lifecycle methods and data context. Web widgets run in general web applications.

Q: What are data keys? A: Definition of telemetry data coming from ThingsBoard to widget. There are two types: timeseries and attribute.

Q: What is maxDatasources? A: Determines how many IoT devices the widget can receive data from. -1 means unlimited.

Q: Can I convert provider to web later? A: Yes, you can change to provider: "web" in .xcon/config.json, but ThingsBoard-specific features won't work.

Q: I skipped npm install, how do I install later? A: Go to project directory and run npm install:

bash

cd device-tracker
npm install

ThingsBoard widget creation ready! Visualize your IoT devices.

ThingsBoard Widget Create ​

Overview ​

Command Syntax ​

Options ​

Usage Examples ​

1. Interactive Mode (Recommended) ​

2. With Name Parameter ​

3. Full Parameters ​

4. Non-Interactive Mode ​

5. Direct with NPX ​

ThingsBoard-Specific Configuration ​

1. Setting Provider ​

2. ThingsBoard Build Settings ​

3. ThingsBoard Data Keys ​

Timeseries Data Keys ​

Latest Data Keys (Attributes) ​

4. ThingsBoard Type Parameters ​

Workflow ​

1. Creating ThingsBoard Widget ​

2. Installing Dependencies ​

ThingsBoard Specific Scenarios ​

1. IoT Device Map Widget ​

2. Sensor Dashboard Widget ​

3. Alarm Widget ​

Troubleshooting ​

Issue: Widget not visible in ThingsBoard ​

Issue: Data keys not working ​

Issue: Widget lifecycle methods not called ​

Best Practices ​

1. Data Keys Organization ​

2. Datasource Limits ​

3. Refresh Interval ​

4. Widget Naming ​

Command Output ​

Successful Creation ​

Non-Interactive Mode Output ​

Frequently Asked Questions ​

ThingsBoard Widget Create

Overview

Command Syntax

Options

Usage Examples

1. Interactive Mode (Recommended)

2. With Name Parameter

3. Full Parameters

4. Non-Interactive Mode

5. Direct with NPX

ThingsBoard-Specific Configuration

1. Setting Provider

2. ThingsBoard Build Settings

3. ThingsBoard Data Keys

Timeseries Data Keys

Latest Data Keys (Attributes)

4. ThingsBoard Type Parameters

Workflow

1. Creating ThingsBoard Widget

2. Installing Dependencies

ThingsBoard Specific Scenarios

1. IoT Device Map Widget

2. Sensor Dashboard Widget

3. Alarm Widget

Troubleshooting

Issue: Widget not visible in ThingsBoard

Issue: Data keys not working

Issue: Widget lifecycle methods not called

Best Practices

1. Data Keys Organization

2. Datasource Limits

3. Refresh Interval

4. Widget Naming

Command Output

Successful Creation

Non-Interactive Mode Output

Frequently Asked Questions