Command-line tool for ThingsBoard widget management with XCONS platform integration
npm install @xcons/cli-thingsboardbash
Create a widget
npx @xcons/cli-thingsboard widget create temperature-sensor
Build the widget
cd temperature-sensor
npx @xcons/cli-thingsboard widget build --production
Deploy to ThingsBoard
npx @xcons/cli-thingsboard widget install -h your-server:8080 -u username -p password
`
Key Features
- š Rapid Widget Development: Modern TypeScript templates
- š§ Built-in Build Engine: No webpack configuration required
- š¦ Automatic Bundle Management: Auto-managed "Xcon Studio" bundle
- šÆ ThingsBoard Integration: Direct server deployment
- š Debug Support: Detailed operation tracking
- š Multi-Environment: Dev/staging/prod deployment
Core Commands
$3
`bash
Create widget project
xcons-thingsboard widget create [name] --type [timeseries|latest|rpc|static]
Build widget
xcons-thingsboard widget build [--production] [--debug]
Deploy to ThingsBoard
xcons-thingsboard widget install [--debug] [--override]
List server widgets
xcons-thingsboard widget list -h host -u user -p pass [--filter text] [--json]
Delete widget
xcons-thingsboard widget delete [name] -i id [--force]
`
$3
`bash
Create bundle
xcons-thingsboard widget-bundle create -n "Bundle Name" -o 10
List bundles
xcons-thingsboard widget-bundle list [--filter text] [--json]
`
Widget Types
| Type | Description | Use Cases |
|------|-------------|-----------|
| timeseries | Time series charts | Sensor data, trends |
| latest | Current value displays | Status panels, KPIs |
| rpc | Device control interfaces | Motor control, valve settings |
| static | Static HTML content | Info panels, documentation |
Installation Options
$3
`bash
npx @xcons/cli-thingsboard widget create my-widget
`
$3
`bash
npm install -g @xcons/cli-thingsboard
xcons-thingsboard widget create my-widget
`
$3
`bash
npm install @xcons/cli-thingsboard
npx xcons-thingsboard widget create my-widget
`
Development Workflow
`bash
1. Create widget project
xcons-thingsboard widget create sensor-dashboard --type timeseries
2. Navigate to project
cd sensor-dashboard
3. Install dependencies (prompted automatically)
npm install
4. Develop widget
- src/index.ts (TypeScript code)
- src/index.html (HTML template)
- src/style.css (CSS styles)
5. Build for testing
xcons-thingsboard widget build --debug
6. Deploy to ThingsBoard
xcons-thingsboard widget install -h localhost:8080 -u tenant -p tenant --debug
7. Optimize for production
xcons-thingsboard widget build --production
8. Deploy to production
xcons-thingsboard widget install -h prod-server:8080 -u admin -p password
`
Project Structure
`
my-widget/
āāā .xcon/
ā āāā config.json # Widget configuration
āāā src/
ā āāā index.ts # Main widget TypeScript code
ā āāā index.html # HTML template
ā āāā style.css # CSS styles
āāā dist/ # Compiled files
āāā package.json # NPM configuration
āāā tsconfig.json # TypeScript settings
āāā README.md # Project documentation
`
Examples
$3
`bash
xcons-thingsboard widget create energy-monitor --type timeseries
`
$3
`bash
xcons-thingsboard widget create pump-controller --type rpc
`
$3
`bash
xcons-thingsboard widget create status-panel --type latest
`
$3
`bash
xcons-thingsboard widget create help-guide --type static
`
System Requirements
- Node.js 18.0.0+
- NPM 9.0.0+
- ThingsBoard CE/PE 3.0+
Quick Troubleshooting
$3
`bash
Check Node.js version
node --version # Requires 18+
Clear NPM cache
npm cache clean --force
Use npx instead of global install
npx @xcons/cli-thingsboard widget create test-widget
`
$3
`bash
Use debug mode for details
xcons-thingsboard widget build --debug
Refresh dependencies
npm install
Check .xcon/config.json
cat .xcon/config.json
`
$3
`bash
Test server access
ping your-server
telnet your-server 8080
Use debug mode for installation
xcons-thingsboard widget install --debug
``