XCon Studio

Appearance

@xcons/cli-thingsboard - Konfigürasyon Kılavuzu ​

Bu dokümantasyon, XCONS ThingsBoard CLI aracının konfigürasyon ayarlarını ve özelleştirme seçeneklerini detaylı olarak açıklar.

.xcon/config.json Dosyası ​

Her widget projesi .xcon/config.json dosyası ile konfigüre edilir. Bu dosya widget'ın temel ayarlarını ve derleme konfigürasyonunu içerir.

Temel Yapı ​

json
{
  "configurations": {
    "provider": "thingsboard",
    "id": "",
    "type": "timeseries",
    "fqn": ""
  },
  "build": {
    "entry": "index.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart",
      "lodash": "_"
    }
  },
  "data": {
    "dataKeys": [...],
    "latestDataKeys": [...],
    "defaultConfig": {...}
  },
  "projectType": "widget",
  "version": "1.0"
}

Konfigürasyon Bölümleri ​

1. Configurations Bölümü ​

Widget'ın temel tanımlama bilgilerini içerir.

json
{
  "configurations": {
    "provider": "thingsboard",
    "id": "cf355dd0-369a-11f0-a044-a9b78a26ce7f",
    "type": "timeseries",
    "fqn": "xcons.temperature_sensor.1640995200000"
  }
}

Alan Açıklamaları:

  • provider: "thingsboard" (sabit değer)
  • id: ThingsBoard sunucusundaki widget ID'si (otomatik doldurulur)
  • type: Widget türü (timeseries, latest, rpc, static)
  • fqn: Widget'ın Fully Qualified Name'i (otomatik üretilir)

2. Build Bölümü ​

Derleme işlemi ayarlarını kontrol eder.

json
{
  "build": {
    "entry": "index.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart",
      "lodash": "_",
      "moment": "moment",
      "jquery": "$"
    }
  }
}

Alan Açıklamaları:

  • entry: Ana kaynak dosyası (genellikle index.ts)
  • sourceRoot: Kaynak kodların bulunduğu dizin
  • outputFilename: Çıktı dosya adı
  • outputPath: Derlenmiş dosyaların kaydedileceği dizin
  • tsConfig: TypeScript konfigürasyon dosyası
  • externals: Harici kütüphane eşlemeleri

3. Data Bölümü ​

ThingsBoard widget veri yapılandırması.

json
{
  "data": {
    "dataKeys": [
      {
        "name": "temperature",
        "label": "Temperature",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "temperature"
        }
      },
      {
        "name": "humidity",
        "label": "Humidity",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "humidity"
        }
      }
    ],
    "latestDataKeys": [
      {
        "name": "status",
        "label": "Device Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      }
    ],
    "defaultConfig": {
      "title": "Temperature & Humidity Monitor",
      "backgroundColor": "#ffffff",
      "textColor": "#000000",
      "showLegend": true,
      "showTitle": true,
      "refreshInterval": 1000,
      "width": 8,
      "height": 6
    }
  }
}

Widget Türü Konfigürasyonları ​

TimeSeries Widget ​

json
{
  "configurations": {
    "type": "timeseries"
  },
  "data": {
    "dataKeys": [
      {
        "name": "temperature",
        "label": "Temperature (°C)",
        "type": "timeseries",
        "settings": {
          "dataKeyType": "temperature",
          "units": "°C",
          "decimals": 1
        }
      }
    ],
    "defaultConfig": {
      "timewindow": {
        "realtime": {
          "timewindowMs": 60000
        }
      },
      "showLegend": true,
      "enableAnimation": true
    }
  }
}

Latest Values Widget ​

json
{
  "configurations": {
    "type": "latest"
  },
  "data": {
    "latestDataKeys": [
      {
        "name": "temperature",
        "label": "Current Temperature",
        "type": "timeseries",
        "settings": {
          "units": "°C",
          "decimals": 1
        }
      },
      {
        "name": "status",
        "label": "Device Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      }
    ],
    "defaultConfig": {
      "datasourceType": "entity",
      "maxDatasources": 1,
      "showTitle": true
    }
  }
}

RPC Control Widget ​

json
{
  "configurations": {
    "type": "rpc"
  },
  "data": {
    "dataKeys": [],
    "latestDataKeys": [
      {
        "name": "deviceState",
        "label": "Device State",
        "type": "attribute"
      }
    ],
    "defaultConfig": {
      "targetDeviceAliases": ["device"],
      "rpcMethods": [
        {
          "method": "turnOn",
          "params": {},
          "timeout": 5000
        },
        {
          "method": "turnOff",
          "params": {},
          "timeout": 5000
        }
      ]
    }
  }
}

Static Widget ​

json
{
  "configurations": {
    "type": "static"
  },
  "data": {
    "defaultConfig": {
      "title": "Information Panel",
      "content": "Static HTML content",
      "showTitle": true,
      "backgroundColor": "#f8f9fa"
    }
  }
}

Harici Kütüphane Konfigürasyonu ​

Externals Ayarları ​

json
{
  "build": {
    "externals": {
      "chart.js": "Chart",
      "lodash": "_",
      "moment": "moment",
      "jquery": "$",
      "d3": "d3",
      "@angular/core": "ng.core"
    }
  }
}

Widget Decorator ile Kütüphane Tanımlama ​

typescript
@Widget({
  resources: [
    {
      type: 'js',
      url: 'https://cdn.jsdelivr.net/npm/chart.js',
      name: 'Chart.js Library'
    },
    {
      type: 'css',
      url: 'https://cdn.jsdelivr.net/npm/chart.js/dist/chart.css',
      name: 'Chart.js Styles'
    }
  ]
})

TypeScript Konfigürasyonu ​

tsconfig.json ​

Widget projesi için önerilen TypeScript konfigürasyonu:

json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "module": "CommonJS",
    "sourceMap": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "**/*.test.ts",
    "**/*.spec.ts"
  ]
}

NPM Package.json Konfigürasyonu ​

NPM Package.json ​

Widget projesi için temel package.json:

json
{
  "name": "my-widget",
  "version": "1.0.0",
  "description": "My ThingsBoard Widget",
  "scripts": {
    "build": "xcons-thingsboard widget build",
    "build:prod": "xcons-thingsboard widget build --production",
    "build:debug": "xcons-thingsboard widget build --debug",
    "install:server": "xcons-thingsboard widget install",
    "install:debug": "xcons-thingsboard widget install --debug"
  },
  "dependencies": {
    "@xcons/widget": "^1.0.0",
    "chart.js": "^4.0.0",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "@types/lodash": "^4.14.0",
    "typescript": "^5.0.0"
  }
}

Not: Webpack, ts-loader gibi build araçları dahili build engine tarafından otomatik yönetilir.

Gelişmiş Konfigürasyon Seçenekleri ​

Custom Data Keys Function ​

json
{
  "data": {
    "dataKeysFunction": "function() { return ctx.datasources.map(ds => ({ name: ds.name, label: ds.label, type: 'timeseries' })); }"
  }
}

Additional Type Parameters ​

json
{
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": 5,
      "maxDataKeys": 20,
      "singleEntity": false,
      "embedTitlePanel": true,
      "datasourcesOptional": false,
      "dataKeysOptional": false
    }
  }
}

Custom Default Config ​

json
{
  "data": {
    "defaultConfig": {
      "title": "Custom Widget Title",
      "backgroundColor": "#1e88e5",
      "textColor": "#ffffff",
      "borderRadius": 8,
      "padding": 16,
      "chart": {
        "type": "line",
        "options": {
          "responsive": true,
          "maintainAspectRatio": false
        }
      },
      "customSettings": {
        "refreshRate": 2000,
        "animationDuration": 300,
        "showGrid": true
      }
    }
  }
}

WebStorm/IntelliJ IDEA Konfigürasyonu ​

.idea/modules.xml ​

xml
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
  <component name="ProjectModuleManager">
    <modules>
      <module fileurl="file://$PROJECT_DIR$/.idea/my-widget.iml" filepath="$PROJECT_DIR$/.idea/my-widget.iml" />
    </modules>
  </component>
</project>

.idea/my-widget.iml ​

xml
<?xml version="1.0" encoding="UTF-8"?>
<module type="WEB_MODULE" version="4">
  <component name="NewModuleRootManager">
    <content url="file://$MODULE_DIR$">
      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
      <excludeFolder url="file://$MODULE_DIR$/dist" />
      <excludeFolder url="file://$MODULE_DIR$/node_modules" />
    </content>
    <orderEntry type="inheritedJdk" />
    <orderEntry type="sourceFolder" forTests="false" />
  </component>
</module>

Visual Studio Code Konfigürasyonu ​

.vscode/settings.json ​

json
{
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/*.js": {
      "when": "$(basename).ts"
    }
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true
  }
}

.vscode/launch.json ​

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Build Widget",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/xcons-thingsboard",
      "args": ["widget", "build", "--debug"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

Ortam Değişkenleri ​

CLI Ortam Değişkenleri ​

bash
# Debug modu
export XCON_DEBUG=true

# Build modunu zorla
export XCON_BUILD_MODE=production

# Custom registry
export XCON_REGISTRY=http://private-registry:4873

# Timeout ayarları
export XCON_TIMEOUT=30000

Widget Runtime Değişkenleri ​

bash
# Node.js hafıza ayarı
export NODE_OPTIONS="--max-old-space-size=4096"

# TypeScript compiler ayarları
export TSC_COMPILE_ON_ERROR=true

XCONS Build Engine Konfigürasyonu ​

XCONS CLI, dahili yapı motoru kullanır ve harici webpack konfigürasyonuna ihtiyaç duymaz. Tüm derleme ayarları .xcon/config.json dosyası ile kontrol edilir.

Dahili Build Engine Avantajları ​

  • Sıfır Konfigürasyon: Webpack ayarları otomatik optimize edilir
  • ThingsBoard Entegrasyonu: Otomatik wrapper ve kaynak işleme
  • TypeScript Desteği: Decorator ve metadata desteği dahili
  • External Library Yönetimi: Basit JSON konfigürasyonu ile
  • Optimizasyon: ThingsBoard widget'ları için özel optimizasyonlar

Build Process Kontrolü ​

json
{
  "build": {
    "entry": "index.ts",
    "sourceRoot": "src", 
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart",
      "lodash": "_"
    }
  }
}

Bu konfigürasyon ile dahili build engine:

  • TypeScript kaynak kodunu derler
  • External kütüphaneleri yönetir
  • ThingsBoard wrapper'ı otomatik ekler
  • Template ve CSS dosyalarını işler
  • Çıktıyı optimize eder

Konfigürasyon Validasyonu ​

Dahili Build Engine Debug ​

bash
# Build sürecini detaylı izle
xcons-thingsboard widget build --debug

# Build başarısını test et
xcons-thingsboard widget build --production

# Widget durumunu kontrol et
ls -la dist/
# Beklenen dosyalar:
# - widget.js (ana widget kodu)
# - widget.template.html (HTML template)
# - widget.styles.css (CSS stilleri)  
# - widget.metadata.json (widget meta verisi)

Yaygın Konfigürasyon Hataları ​

1. Yanlış Provider:

json
// ❌ Yanlış
{
  "configurations": {
    "provider": "iot-platform"
  }
}

// ✅ Doğru
{
  "configurations": {
    "provider": "thingsboard"
  }
}

2. Geçersiz Widget Type:

json
// ❌ Yanlış
{
  "configurations": {
    "type": "chart"
  }
}

// ✅ Doğru
{
  "configurations": {
    "type": "timeseries"
  }
}

3. Eksik Build Alanları:

json
// ❌ Eksik
{
  "build": {
    "entry": "index.ts"
  }
}

// ✅ Tam
{
  "build": {
    "entry": "index.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  }
}

Sonraki Adımlar ​

Konfigürasyon tamamlandıktan sonra:

  1. Widget Oluşturma - Widget projesi oluşturma
  2. Widget Derleme - Proje derleme işlemleri
  3. Widget Kurulum - ThingsBoard'a yükleme
  4. Widget Listeleme - Sunucu widget yönetimi

Konfigürasyon rehberi tamamlandı. Widget geliştirmeye hazırsınız!