VS Code

ioBroker Adapterentwicklung mit Microsoft Visual Studio Code (VSCode) auf Grundlage des ioBroker.template Adapters

!> Korrekturen, Ergänzungen und Änderungen sind Willkommen!

Die Doku entsteht ohne jegliche Erfahrungen mit VSCode in Verbindung mit node.js/ioBroker. Sollte die Vorgehensweise Verbesserungen nötig haben, bin ich für jeden Hinweis dankbar.

Stolpersteine: Wenn jemand "hängen" geblieben ist und vertiefende Informationen benötigt, bitte ein Issue aufmachen, damit die Doku ergänzt und verfeinert werden kann.

Der Adaptername in den Beispielen lautet iobroker.template-master-mhe.

Template

ioBroker Template Adapter: https://github.com/ioBroker/ioBroker.template

getestet in folgender Umgebung

  • ioBroker, lokal installiert
  • ioBroker.js-controller: 1.0.0
  • node.js: v6.10.2
  • npm: 3.10.10
  • Windows 10 Prof.
  • VSCode 1.12.1

Begleitende Informationen zur Adapterentwicklung allgemein und mit VSCode

Allgemeine Vorgehensweise - Template für einen Adapter verwenden

1. Download template

2. "npm install" im Ordner ausgeführt

3. grunt ausgeführt // ändert die Einstellungen im Template im vorhandenen Projekt

grunt rename --name=template-master-mhe --email=iobroker@digheim.de --author="Michael Herwig"
  • Adaptername, Author und E-Mail-Adresse wird über grunt an den notwendigen Stellen im Code geändert

4. Adapter-Ordner in VSCode laden

  • Ordnername anpassen. Hier im Beispiel von ioBroker.template-master in iobroker.template-master-mhe
  • VSCode: Datei/Ordner öffnen // oder STRG+K, STRG+O

5. In VSCode die Version des Templates angepasst (von 0.5.0 auf 0.0.2)

  • in io-package.json von 0.5.0 auf 0.0.2 geändert // verwendet von ioBroker
  • in package.json von 0.5.0 auf 0.0.2 geändert // verwendet von npm

6. nach ioBroker kopiert und Pfad/Name angepasst

7. Ordner in VSCode schliessen

  • VSCode: Datei/Ordner schliessen // oder STRG+K F

8. ioBroker/Admin -> Update durchführen

  • in der ioBroker Admin GUI auf Update klicken

9. Adapter herausgesucht und Instanz hinzugefügt

  • in der ioBroker Admin GUI auf das Plus beim Adapter drücken SCREENSHOT: Instanz des eigenen Adapters

  • Instanz des Adapters wird installiert und angezeigt SCREENSHOT: Instanz des eigenen Adapters

  • zum debuggen den installierten Adapter stoppen

10. Installierten Ordner von ioBroker in VSCode öffnen

  • VSCode: Datei/Ordner öffnen // oder STRG+K, STRG+O
  • ../node_modules/iobroker.template-master-mhe auswählen
  • hier kann nun der Adapter entwickelt und debuggt werden

Debuggen

1.) VSCode launch.json anpassen

Einmalig für alle Adapter muss die Einstellungen

  • SHIFT+STRG+P: und dann folgendes eingeben: >debug launch.json
  • oder über die Oberfläche: auf das Käfersymbol in der Seitenleiste und dann oben auf das Zahnrad

SCREENSHOT: VSCode Konfiguration der launch.json

launch.json Einstellungen zum Debuggen von ioBroker-Adaptern:

{
    // Use IntelliSense to learn about possible Node.js debug attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Programm starten",             // Name, der im VSCode Auswahlmenü neben dem grünen Play angezeigt wird
            "program": "${workspaceRoot}/main.js"
        },
        {
            "type": "node",
            "request": "attach",
            "name": "An den Prozess anfügen",       // Name, der im VSCode Auswahlmenü neben dem grünen Play angezeigt wird
            "address": "127.0.0.1",                 // Adresse, an dem der node.js Prozess läuft (bei Remote Debug, der Remote-Rechner)
            "port": 5858                            // Port, auf dem der node.js Debugger lauscht, der mit node --debug-brk ... gestartet wird
        }
    ]
}
  • Remote Debugging auf einem entfernten ioBroker ist ebenfalls möglich. Die IP Adresse muss dann von 127.0.0.1 angepasst werden.

2.) Terminal öffnen und Debugger starten

  • STRG+ö // öffnet das integrierte Terminal (die Tastenkombination ist Abhängig vom Betriebssystem und der VSCode Version)

  • im Terminal den neu installierten Adapter stoppen

      cd /opt/iobroker
  iobroker stop template-master-mhe

  • im Terminal den Debugger starten (bem Remote-Debugging muss vorher im Terminal eine Verbindung per SSH aufgebaut werden):

      node --debug-brk node_modules/iobroker.template-master-mhe/main.js --force --logs

    Wobei iobroker.template-master-mhe der Name des Adapters ist.

Anzeige im integriertem Terminal (Hinweis: es kann auch ein externes Terminal-Programm verwendet werden):

PS C:\ioBroker> node --debug-brk node_modules/iobroker.template-master-mhe/main.js --force --logs
Debugger listening on [::]:5858

SCREENSHOT: VSCode Debugger starten

Ausgabe im Terminal nach dem Starten des Debuggers:

starting. Version 0.0.2 in C:/ioBroker/node_modules/iobroker.template-master-mhe, node: v6.10.2
config test1: true
config test1: 42
stateChange template-master-mhe.0.testVariable {"val":true,"ack":false,"ts":1494753342714,"q":0,"from":"system.adapter.template-master-mhe.0","lc":1494753342714}
ack is not set!
stateChange template-master-mhe.0.testVariable {"val":true,"ack":true,"ts":1494753342715,"q":0,"from":"system.adapter.template-master-mhe.0","lc":1494753342714}
stateChange template-master-mhe.0.testVariable {"val":true,"ack":true,"ts":1494753342715,"q":0,"from":"system.adapter.template-master-mhe.0","lc":1494753342714}
check group user admin group admin: false
check user admin pw ioboker: true
stateChange template-master-mhe.0.testVariable {"val":null,"ack":true,"ts":1494753367809,"q":0,"from":"system.adapter.template-master-mhe.0","lc":1494753367809}
  • mit STRGF+C im Terminal abbrechen

Ausgabe im Terminal nach dem Stoppen des Debuggers:

cleaned everything up...
terminating
cleaned everything up...
PS C:\ioBroker>
  • in VSCode auf Debug gehen und unter Debuggen "An den Prozess anfügen" auswählen und starten
  • die Ausgabe wird im Reiter Terminal beim integrierten Terminal durchgeführt
  • mit STRGF+C im Terminal abbrechen

Erfahrungen

  • Adapter Icon des Templates wurde nach Grunt angepasst (umbenannt), aber im ioBroker/Admin nicht angezeigt
  • das richtige Icon wird erst nach Veröffentlichung des Adapters angezeigt

todo

  • VSCode mit Github nutzen
  • Beispiel an einem eigenen Adapter
  • klären: Debug nur mit node.js > 6.x oder ist 4.x auch möglich?

Dokumentation im Netz

zu Visual Studio Code

zu node.js

zu Git & Github

Allgemeine Tipps & Tricks

SSH mit Windows

Sonstiges

  • meine Einstellungen in settings.json für VSCode:
// Platzieren Sie Ihre Einstellungen in dieser Datei, um die Standardeinstellungen zu überschreiben.
{
    "window.zoomLevel": 0,
    "editor.minimap.enabled": true,                 // zeigt die kleine Codeübersichtskarte rechts neben dem Code an
    "editor.dragAndDrop": true,                     // ermöglicht markierte Codeteile per Drag und Drop zu verschieben0
    "workbench.editor.closeOnFileDelete": false,
    "files.autoSave": "afterDelay",                 // Auotmatisches Speichern der Dateien einstellen
    "files.autoSaveDelay": 1000,                    // Autosave nach 1000 ms
    "[javascript]": {},                             // Einstellungen für die SPrache "Javascript"
    "telemetry.enableCrashReporter": false,         //
    "workbench.colorTheme": "Quiet Light",          // Farbschema des Editors
    "telemetry.enableTelemetry": false,
    "workbench.iconTheme": "vs-seti",               // Icons für bekannte Dateieendungen. Wenn ja, welches Icon-Set soll verwendet werden
    "javascript.implicitProjectConfig.checkJs": true
}