@xcons/cli-thingsboard

ThingsBoard Widget Management CLI - Command-line tool for creating, managing, and deploying ThingsBoard widgets with XCONS platform integration.

Quick Start

# 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

Widget Management

# 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]

Bundle Management

# 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

NPX Direct Usage (Recommended)

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

Global Installation

npm install -g @xcons/cli-thingsboard
xcons-thingsboard widget create my-widget

Project-based Installation

npm install @xcons/cli-thingsboard
npx xcons-thingsboard widget create my-widget

Development Workflow

# 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

TimeSeries Widget

xcons-thingsboard widget create energy-monitor --type timeseries

Device Control Widget

xcons-thingsboard widget create pump-controller --type rpc

Status Dashboard

xcons-thingsboard widget create status-panel --type latest

Info Panel

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

Installation Issues

# 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

Build Issues

# Use debug mode for details
xcons-thingsboard widget build --debug

# Refresh dependencies
npm install

# Check .xcon/config.json
cat .xcon/config.json

Server Connection Issues

# Test server access
ping your-server
telnet your-server 8080

# Use debug mode for installation
xcons-thingsboard widget install --debug

Comprehensive Documentation

For detailed usage guides, please visit our wiki documentation:

📚 General Guides

• Overview - CLI tool overview
• Installation - Detailed installation guide
• Configuration - Configuration settings

🔧 Widget Commands

• Widget Create - Create widget projects
• Widget Build - Build widget projects
• Widget Install - Deploy to ThingsBoard
• Widget List - List widgets
• Widget Delete - Delete widgets

📦 Bundle Commands

• Bundle Create - Create bundles
• Bundle List - List bundles

Support and Community

• 📖 Wiki: https://wiki.xcon.dev
• 🐛 Issue Tracker: GitHub Issues
• 💬 Community: XCONS Platform Forums
• 📧 Support: [email protected]

License

MIT © XCON Studio Team

Widget development made simple with XCONS ThingsBoard CLI!