XCon Studio

Appearance

@xcons/cli-thingsboard - Widget Install Kılavuzu ​

Bu dokümantasyon, XCONS ThingsBoard CLI ile widget kurulum işlemlerini detaylı olarak açıklar.

Widget Install Komutu ​

bash
xcons-thingsboard widget install [source] [options]

Parametreler ​

  • source (isteğe bağlı): Widget proje dizini. Belirtilmezse mevcut dizin kullanılır.

Seçenekler ​

  • -h, --host <host>: ThingsBoard sunucu adresi (örn: 192.168.233.132:8080)
  • -u, --user <email>: ThingsBoard kullanıcı adı/email
  • -p, --pass <password>: ThingsBoard şifresi
  • --override: Mevcut widget'ı onay almadan güncelle
  • -d, --debug: Detaylı debug çıktısı ile kurulum

Temel Kullanım ​

Mevcut Dizinden Kurulum ​

bash
# Widget proje dizinindeyken
xcons-thingsboard widget install

# Sunucu bilgileri ile kurulum
xcons-thingsboard widget install \
  -h 192.168.233.132:8080 \
  -u admin@domain.com \
  -p password

# Debug modu ile kurulum
xcons-thingsboard widget install --debug

Belirli Dizinden Kurulum ​

bash
# Belirli widget dizininden kurulum
xcons-thingsboard widget install ./my-widget

# Debug ve override ile
xcons-thingsboard widget install ./my-widget \
  -h server:8080 -u admin -p pass \
  --debug --override

İnteraktif Kurulum ​

bash
# Tüm parametreler interaktif sorulur
xcons-thingsboard widget install

İnteraktif Soru Sırası:

Installing widget to ThingsBoard server...
Widget Type: timeseries

ThingsBoard server connection required
? ThingsBoard server host (with port): 192.168.233.132:8080
? Username/Email: admin@domain.com
? Password: [gizli giriş]

Kurulum Süreci ​

1. Proje Validasyonu ​

Installing widget to ThingsBoard server...
Widget Type: timeseries

CLI önce projenin geçerli bir widget projesi olduğunu kontrol eder:

  • .xcon/config.json varlığı
  • Proje yapısının uygunluğu
  • Widget türünün geçerliliği

2. Build İşlemi ​

Building project using XCon build system...
[DEBUG] Build process starting
[DEBUG] Project validation passed
Build completed successfully
  Output size: 45.23 KB
  Build time: 1247ms

XCONS Build Engine ile widget derlenir:

  • TypeScript → JavaScript dönüşümü
  • Template ve CSS işleme
  • External kütüphane yönetimi
  • ThingsBoard wrapper ekleme

3. Widget Dosyalarını Okuma ​

Reading built widget files...
[DEBUG] Widget files: JS(45KB), Template(256B), Styles(512B), Resources(2)

Derlenmiş widget dosyaları okunur:

  • widget.js - Ana widget kodu
  • widget.template.html - HTML template
  • widget.styles.css - CSS stilleri
  • widget.metadata.json - Widget meta verileri
  • widget.resources.json - Harici kaynaklar (varsa)

4. Sunucu Bağlantısı ​

[DEBUG] Server: http://192.168.233.132:8080, User: admin@domain.com
[DEBUG] Authentication successful

ThingsBoard sunucusuna bağlantı ve kimlik doğrulama yapılır.

5. Bundle Yönetimi ​

Managing Xcon Studio bundle...
[DEBUG] Found existing bundle: bundle-id-here

"Xcon Studio" bundle'ı otomatik oluşturulur veya bulunur:

  • Bundle yoksa yeni oluşturulur
  • Bundle varsa mevcut kullanılır
  • Widget bundle'a otomatik eklenir

6. Widget Oluşturma/Güncelleme ​

Creating or updating widget on server...
[DEBUG] API request: POST /api/widgetType
Widget created successfully with ID: widget-id-here

Widget ThingsBoard'a yüklenir:

  • Mevcut widget'sa güncellenir
  • Yeni widget'sa oluşturulur
  • FQN (Fully Qualified Name) otomatik üretilir

7. Konfigürasyon Güncelleme ​

[DEBUG] Updated .xcon/config.json with widget ID: widget-id and FQN: xcons.widget.timestamp

Widget ID ve FQN bilgileri .xcon/config.json dosyasına kaydedilir.

Debug Modu ​

Debug modu detaylı işlem bilgisi sağlar:

bash
xcons-thingsboard widget install --debug

Debug Çıktısı İçerir:

  • Proje Analizi: Widget türü, mevcut ID, FQN bilgileri
  • Build Süreci: Derleme adımları, süre, dosya boyutu
  • Dosya Detayları: Her dosyanın boyutu ve içeriği
  • Sunucu İletişimi: API istekleri, yanıtlar, hatalar
  • Bundle İşlemleri: Bundle bulma, oluşturma, güncelleme
  • Widget İşlemleri: Oluşturma/güncelleme detayları

Debug Çıktı Örneği:

Debug mode enabled
[DEBUG] Widget installation started
[DEBUG] Project directory: /home/user/my-widget
[DEBUG] Widget type: timeseries, ID: none, FQN: none
Building project using XCon build system...
[DEBUG] Build process starting
[DEBUG] Project validation passed
Build completed successfully
  Output size: 45.23 KB
  Build time: 1247ms
[DEBUG] Build completed in 1247ms, size: 45.23KB
Reading built widget files...
[DEBUG] Widget files: JS(45KB), Template(256B), Styles(512B), Resources(2)
[DEBUG] Server: http://192.168.233.132:8080, User: admin@domain.com
[DEBUG] Authentication successful
Managing Xcon Studio bundle...
[DEBUG] Found existing bundle: 278b4440-f894-11ef-bf2f-f7b9477f8896
Creating or updating widget on server...
[DEBUG] API request: POST /api/widgetType
Widget created successfully with ID: 62289610-f894-11ef-bf2f-f7b9477f8896
[DEBUG] Widget created successfully: 62289610-f894-11ef-bf2f-f7b9477f8896
[DEBUG] Updated .xcon/config.json with widget ID and FQN
[DEBUG] Installation completed successfully

Override Modu ​

Override modu mevcut widget'ı onay almadan günceller:

bash
xcons-thingsboard widget install --override

Normal Mod vs Override Mod:

Normal Mod:

Widget with ID '62289610-f894-11ef-bf2f-f7b9477f8896' exists on server and will be updated. Continue? (Y/n)

Override Mod:

  • Onay sorusu atlanır
  • Widget doğrudan güncellenir
  • Hızlı geliştirme için idealdir

Pratik Örnekler ​

Geliştirme Ortamında Hızlı Test ​

bash
# Geliştirme sunucusunda hızlı test
xcons-thingsboard widget install \
  -h localhost:8080 \
  -u tenant@thingsboard.org \
  -p tenant \
  --override --debug

Üretim Ortamına Dikkatlice Yükleme ​

bash
# Üretim sunucusunda dikkatli kurulum
xcons-thingsboard widget install \
  -h production.company.com:8080 \
  -u admin@company.com \
  -p secure_password

CI/CD Pipeline'da Kurulum ​

bash
# Otomatik deployment için
export TB_HOST="ci-server:8080"
export TB_USER="ci-user"
export TB_PASS="ci-password"

xcons-thingsboard widget install \
  -h "$TB_HOST" -u "$TB_USER" -p "$TB_PASS" \
  --override

Çoklu Ortam Kurulumu ​

bash
# Farklı ortamlara aynı widget'ı yükle
environments=(
  "dev:localhost:8080:tenant@thingsboard.org:tenant"
  "staging:staging.company.com:8080:admin:staging123"
  "prod:prod.company.com:8080:admin:prod_password"
)

for env in "${environments[@]}"; do
  IFS=':' read -r name host port user pass <<< "$env"
  echo "Installing to $name environment..."
  
  xcons-thingsboard widget install \
    -h "$host:$port" -u "$user" -p "$pass" \
    --override --debug
  
  echo "Installation to $name completed"
  echo "---"
done

Widget Durumları ​

Yeni Widget Kurulumu ​

bash
# İlk kez kurulan widget
xcons-thingsboard widget install

Çıktı:

Widget 'timeseries' created successfully!

Widget Details:
  ID:     62289610-f894-11ef-bf2f-f7b9477f8896
  FQN:    xcons.temperature_monitor.1672531200000
  Type:   timeseries
  Server: http://192.168.233.132:8080

Mevcut Widget Güncelleme ​

bash
# Daha önce kurulmuş widget'ı güncelle
xcons-thingsboard widget install

Onay Sorusu:

Widget with ID '62289610-f894-11ef-bf2f-f7b9477f8896' exists on server and will be updated. Continue? (Y/n)

Çıktı:

Widget 'timeseries' updated successfully!

Widget Details:
  ID:     62289610-f894-11ef-bf2f-f7b9477f8896
  FQN:    xcons.temperature_monitor.1672531200000
  Type:   timeseries
  Server: http://192.168.233.132:8080

Geçersiz ID Durumu ​

Konfigürasyonda kayıtlı ID sunucuda yoksa:

Widget ID '62289610-f894-11ef-bf2f-f7b9477f8896' not found on server. Creating new widget instead.

CLI otomatik olarak yeni widget oluşturur.

Bundle Yönetimi ​

Xcon Studio Bundle ​

CLI otomatik olarak "Xcon Studio" bundle'ı yönetir:

json
{
  "title": "Xcon Studio",
  "alias": "xcon_studio", 
  "description": "Widget bundle created by XCONS CLI for custom widgets",
  "order": 0
}

Bundle İşlemleri ​

Bundle Bulma:

Managing Xcon Studio bundle...
[DEBUG] Found existing bundle: 278b4440-f894-11ef-bf2f-f7b9477f8896

Bundle Oluşturma:

  Xcon Studio bundle not found, creating new one...
  Created new Xcon Studio bundle: 278b4440-f894-11ef-bf2f-f7b9477f8896

Bundle'a Widget Ekleme:

  Adding widget FQN to bundle: xcons.temperature_monitor.1672531200000

Hata Durumları ve Çözümler ​

Build Hataları ​

Hata: Build failed: TypeScript compilation error

Çözüm:

bash
# Bağımlılıkları kontrol et
npm install

# TypeScript hatalarını düzelt
npx tsc --noEmit

# Tekrar build dene
xcons-thingsboard widget build --debug

Proje Yapısı Hataları ​

Hata: Directory is not a widget project. .xcon/config.json not found

Çözüm:

bash
# Doğru dizinde olduğunuzu kontrol edin
ls -la .xcon/

# Veya widget proje dizinine gidin
cd my-widget-project

# Veya dizin yolunu belirtin
xcons-thingsboard widget install ./path/to/widget

Sunucu Bağlantı Hataları ​

Hata: Connection refused - ThingsBoard server may be down or unreachable

Çözüm:

bash
# Sunucu durumunu kontrol et
ping 192.168.233.132
telnet 192.168.233.132 8080

# Host formatını kontrol et
xcons-thingsboard widget install -h http://192.168.233.132:8080

Kimlik Doğrulama Hataları ​

Hata: Authentication failed - Invalid username or password

Çözüm:

bash
# Kullanıcı bilgilerini ThingsBoard web arayüzünde test et
# Doğru kullanıcı türünü kullan

# Tenant kullanıcısı
xcons-thingsboard widget install \
  -h server:8080 \
  -u tenant@thingsboard.org \
  -p tenant

# Sistem yöneticisi
xcons-thingsboard widget install \
  -h server:8080 \
  -u sysadmin@thingsboard.org \
  -p sysadmin

Yetki Hataları ​

Hata: Access forbidden - User may not have permission to create widgets

Çözüm:

bash
# Yetkili hesap kullan
xcons-thingsboard widget install \
  -h server:8080 \
  -u admin@company.com \
  -p admin_password

# Sistem yöneticisi hesabı
xcons-thingsboard widget install \
  -h server:8080 \
  -u sysadmin@thingsboard.org \
  -p sysadmin

Bundle Oluşturma Hataları ​

Hata: Failed to create or update Xcon Studio bundle

Çözüm:

bash
# Manuel bundle oluştur
xcons-thingsboard widget-bundle create \
  -h server:8080 -u admin -p pass \
  -n "Xcon Studio" -o 0

# Tekrar widget install dene
xcons-thingsboard widget install --debug

Gelişmiş Kurulum Senaryoları ​

Otomatik Geliştirme Döngüsü ​

bash
#!/bin/bash

# Otomatik build ve install döngüsü
auto_deploy() {
    local widget_dir=$1
    local host=$2
    local user=$3
    local pass=$4
    
    cd "$widget_dir"
    
    echo "=== Auto Deploy: $widget_dir ==="
    
    # Build
    echo "1. Building widget..."
    xcons-thingsboard widget build --production
    
    if [ $? -ne 0 ]; then
        echo "Build failed, aborting deployment"
        return 1
    fi
    
    # Install
    echo "2. Installing widget..."
    xcons-thingsboard widget install \
        -h "$host" -u "$user" -p "$pass" \
        --override --debug
    
    if [ $? -eq 0 ]; then
        echo "3. Widget deployed successfully"
        return 0
    else
        echo "3. Deployment failed"
        return 1
    fi
}

# Kullanım
auto_deploy "./temperature-widget" "localhost:8080" "tenant" "tenant"

Çoklu Widget Kurulumu ​

bash
#!/bin/bash

# Birden fazla widget'ı aynı sunucuya kur
deploy_multiple_widgets() {
    local host=$1
    local user=$2
    local pass=$3
    shift 3
    local widgets=("$@")
    
    echo "=== Deploying ${#widgets[@]} widgets to $host ==="
    
    for widget_dir in "${widgets[@]}"; do
        if [ -d "$widget_dir" ]; then
            echo "Deploying: $widget_dir"
            
            xcons-thingsboard widget install "$widget_dir" \
                -h "$host" -u "$user" -p "$pass" \
                --override
            
            if [ $? -eq 0 ]; then
                echo "  SUCCESS: $widget_dir"
            else
                echo "  FAILED: $widget_dir"
            fi
            echo "---"
        else
            echo "  SKIP: $widget_dir (directory not found)"
        fi
    done
}

# Widget dizinleri
widgets=(
    "./temperature-monitor"
    "./humidity-tracker" 
    "./pressure-gauge"
    "./status-panel"
)

# Deployment
deploy_multiple_widgets "localhost:8080" "tenant" "tenant" "${widgets[@]}"

Versiyonlu Kurulum ​

bash
#!/bin/bash

# Widget versiyonunu yönet ve kur
versioned_install() {
    local widget_dir=$1
    local version=$2
    local host=$3
    local user=$4
    local pass=$5
    
    cd "$widget_dir"
    
    # Package.json'da versiyonu güncelle
    if [ -f "package.json" ]; then
        npm version "$version" --no-git-tag-version
    fi
    
    # Widget decorator'da versiyonu güncelle
    if [ -f "src/index.ts" ]; then
        sed -i "s/widgetVersion: '[^']*'/widgetVersion: '$version'/g" src/index.ts
    fi
    
    echo "Installing widget version: $version"
    
    # Build ve install
    xcons-thingsboard widget build --production
    xcons-thingsboard widget install \
        -h "$host" -u "$user" -p "$pass" \
        --override --debug
}

# Kullanım
versioned_install "./my-widget" "1.2.3" "server:8080" "admin" "pass"

Rollback Sistemi ​

bash
#!/bin/bash

# Widget backup ve rollback sistemi
backup_and_install() {
    local widget_dir=$1
    local host=$2
    local user=$3
    local pass=$4
    
    local timestamp=$(date +%Y%m%d_%H%M%S)
    local backup_dir="backups/widget_backup_$timestamp"
    
    # Mevcut konfigürasyonu backup al
    mkdir -p "$backup_dir"
    cp -r "$widget_dir/.xcon" "$backup_dir/"
    cp "$widget_dir/package.json" "$backup_dir/" 2>/dev/null || true
    
    echo "Backup created: $backup_dir"
    
    # Widget'ı kur
    echo "Installing widget..."
    xcons-thingsboard widget install "$widget_dir" \
        -h "$host" -u "$user" -p "$pass" \
        --override --debug
    
    local install_result=$?
    
    if [ $install_result -eq 0 ]; then
        echo "Installation successful"
        echo "Backup location: $backup_dir"
    else
        echo "Installation failed"
        
        # Rollback seçeneği sun
        read -p "Rollback to previous configuration? (y/N): " rollback
        if [[ $rollback =~ ^[Yy]$ ]]; then
            cp -r "$backup_dir"/* "$widget_dir/"
            echo "Rollback completed"
        fi
    fi
    
    return $install_result
}

NPM Scripts Entegrasyonu ​

package.json Scripts ​

json
{
  "scripts": {
    "build": "xcons-thingsboard widget build",
    "build:prod": "xcons-thingsboard widget build --production",
    "build:debug": "xcons-thingsboard widget build --debug",
    "install:dev": "xcons-thingsboard widget install -h localhost:8080 -u tenant -p tenant --override",
    "install:staging": "xcons-thingsboard widget install -h staging:8080 -u admin -p staging123 --override",
    "install:prod": "xcons-thingsboard widget install -h prod:8080 -u admin -p prodpass",
    "deploy:dev": "npm run build:prod && npm run install:dev",
    "deploy:staging": "npm run build:prod && npm run install:staging", 
    "deploy:prod": "npm run build:prod && npm run install:prod"
  }
}

Kullanım ​

bash
# Geliştirme ortamına deploy
npm run deploy:dev

# Staging ortamına deploy  
npm run deploy:staging

# Production'a deploy (onaylı)
npm run deploy:prod

Monitoring ve Logging ​

Kurulum İstatistikleri ​

bash
# Kurulum başarı oranını izle
installation_stats() {
    local log_file="widget_installs.log"
    
    echo "=== Widget Installation Statistics ==="
    
    if [ -f "$log_file" ]; then
        local total=$(wc -l < "$log_file")
        local successful=$(grep "SUCCESS" "$log_file" | wc -l)
        local failed=$(grep "FAILED" "$log_file" | wc -l)
        
        echo "Total installations: $total"
        echo "Successful: $successful"
        echo "Failed: $failed"
        echo "Success rate: $(( (successful * 100) / total ))%"
    else
        echo "No installation log found"
    fi
}

Otomatik Log Tutma ​

bash
# Her kurulum sonrası log tut
log_installation() {
    local widget_name=$1
    local result=$2
    local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
    
    echo "$timestamp|$widget_name|$result" >> widget_installs.log
}

# Wrapper fonksiyon
install_with_logging() {
    local widget_dir=$1
    local widget_name=$(basename "$widget_dir")
    
    echo "Installing widget: $widget_name"
    
    if xcons-thingsboard widget install "$widget_dir" --override; then
        log_installation "$widget_name" "SUCCESS"
        echo "Installation successful"
    else
        log_installation "$widget_name" "FAILED"
        echo "Installation failed"
        return 1
    fi
}

Sonraki Adımlar ​

Widget kurulumundan sonra:

  1. Widget Listeleme - Kurulu widget'ları görüntüleme
  2. Widget Build - Widget güncelleme ve yeniden derleme
  3. Widget Delete - Widget'ları kaldırma

Widget kurulumu tamamlandı. ThingsBoard dashboardlarınızda kullanmaya başlayabilirsiniz!