node-red-contrib-essentim

Repository für ein Node-RED-Plugin. Es stellt eine Verbindung zur essentim Cloud her, um die flexible Verarbeitung von Daten aus der essentim Cloud zu ermöglichen.

Inhalt

Für diesen Zweck werden vier Nodes eingeführt: eine Konfigurationsnode und drei, die im Flow-Editor platziert werden können. Die eingeführten Nodes sind:

Nodes

Alle Nodes müssen zunächst mit einer essentim-connection-Konfigurationsnode konfiguriert werden.

1. Sensor readings

Diese Node empfängt live Sensordaten aus der essentim Cloud und gibt diese als Node-RED Nachrichten aus.

Optional können Sie zusätzlich die Felder Device und Channel anpassen. Standardmäßig sind diese auf den Wert "(all devices)" respektive "(all channels)" gesetzt. Sie können ein spezifisches Gerät und, falls Sie ein Gerät gewählt haben, einen spezifischen Channel einstellen.

Die sensor-readings-Node gibt dann live Sensormesswerte aus, die den gesetzten Filtern entsprechen. Hierbei können mehrere Messwerte in ein Objekt gruppiert werden. Welche Strukturen sich hieraus ergeben können, sehen Sie im Sensor readings-Schema.

2. Device state

Die Device state-Node sendet Gerätezustandsinformationen, wenn sich der verändert. Dies beinhaltet Alarme und den Batteriestatus. Hierfür muss Device auf ein verfügbares Gerät gesetzt werden.

Optional kann via das Feld Type gefiltert werden, ob die Node nur Alarme bzw. nur Batterieinformationen oder beides ausgeben soll. Beides heißt hier niemals, dass Informationen über beide Arten von Zustand in derselben Nachricht stehen; beides heißt nur, dass ausgehende Nachrichten vom einen oder vom anderen Typen sein können.

Außerdem kann, sofern Alarme (oder beides) verschickt werden, mit dem Feld Min. severity nach dem Mindestschweregrad (INFO, WARNING oder ERROR) gefiltert werden.

Das Format der möglichen Nachrichten dieser Node steht im Device state-Schema.

3. Channel status

Die Channel status-Node überwacht den Status aller Extension-Kanäle eines Gerätes. Jede Veränderung der Kanäle, d.h. ein An- oder Abstecken einer Extension, führt zu einer Node-RED Nachricht am Ausgang dieser Node.

Hierfür muss Device auf ein verfügbares Gerät gesetzt werden.

Das Format dieser Nachricht können Sie aus drei Optionen wählen, die Ihnen im Konfigurationsfeld Output view zur Verfügung stehen. Wie diese jeweils aussehen finden Sie im Channel status-Schema.

Channel-Status-Updates aus dieser Node eignen sich für die Verarbeitung von Status-Updates während eines Deployments und updaten NICHT die Channel-Felder von Nodes im Flow-Editor. Wollen Sie die Kanäle, die im Flow-Editor als Filter verfügbar sind updaten, können Sie im Konfigurationsdialog Ihrer essentim connection den Knopf Aktualisieren drücken oder Ihren Flow erneut deployen.

Konfigurationsnodes

Diese müssen nicht gesondert beachtet werden. Im Node-RED Flow-Editor ist das Aufsezten der Konfigurationsnodes in die Einstellungen der normalen Nodes integriert.

essentim connection

Die essentim connection-Node stellt eine Verbindung zur essentim Cloud her, damit Ihre Daten aus dieser in Ihr Node-RED kommen.

Bei der Konfiguration anderer Nodes werden Sie dazu aufgefordert, eine Connection auszuwählen — falls noch keine existiert, erstellen Sie eine. Beliebig viele Nodes können die gleiche essentim connection-Node verwenden.

Eine essentim connection konfiguriert man mit einem API-Token, der im Feld API Key eingetragen wird. Mittels diesem Token authorisiert sich Ihre essentim connection-Node gegnüber der essentim Cloud.

Dokumente

README

Sie lesen es.

CONTRIBUTING

Wenn Sie zu diesem Plug-in beitragen wollen, lesen Sie bitte CONTRIBUTING.md.

LICENSE

Beispiele

Unsere Flow-Beispiele können Sie im Flow-Editor über das Menüfeld oben rechts unter Import (alternativ drücken Sie ctrl+i) im Reiter Beispiele importieren. Hierfür benötigen Sie das Plug-in @flowfuse/node-red-dashboard.

Fehlerbehandlung

Ein rotes Dreieck an der oberen rechten Ecke einer Node weist Sie darauf hin, dass Sie nicht alle erforderlichen Konfigurationsfelder der Node ausgefüllt haben.

Darüber hinaus wird der Status jeder Node nachdem diese deployt wurde unter ihr im Flow-Editor angezeigt. Hier tauchen Fehler der Autorisierung, Verbindung oder Konfiguration mit hilfreichen Details auf. In den meisten Fällen sollten Sie einen grünen Kreis mit dem Wort "connected" sehen.

Schemata

1. Sensor readings

Von einem oder allen Geräten, optional mit Filterung nach Kanälen

• Struktur der msg.payload bei allen Geräten ist { serialNumber: ["1": {timestamp: x, value: x}, ... ], ... }
• bei nur einem Gerät folglich nur der Inhalt eines solcher Arrays { "1": {timestamp: x, value: x}, ... }
• bei einem Kanal: {timestamp: x, value: x} und msg.topic wird auf die Seriennummer.channed_id gesetzt

Beide Filter

message {
  topic: ,
  payload: {
    value: number,
    timestamp: ISODateTime
  }
}

Gerätefilter

message {
  topic: ,
  payload: {
    1: {
      value: number,
      timestamp: ISODateTime
    },
    2: [Beide Filter].payload,
    ...
  }
}

Jede Ganzzahl entspricht einer Kanalnummer, es kann eine beliebige Untermenge aller möglichen Kanäle in einer Nachricht sein.

Keine Filter

message {
  topic: ,
  payload: {
    [Seriennummer1]: {
      1: {
        value: number,
        timestamp: ISODateTime
      },
      ...
    },
    [Seriennummer2]: [Gerätefilter].payload,
    ...
  }
}

Die Seriennummern entsprichen denen der Geräte, es kann eine beliebige Untermenge aller möglichen Geräte in einer Nachricht sein.

2. Device state

Alarm

message {
  topic: browsePath,
  payload: {
    type: string,
    severity: string,
    message: string,
    data?: object
  }
}

Battery

message {
  topic: browsePath,
  payload: {
    powered: boolean,
    charging: boolean,
    percentage: number
  }
}

Wenn der Gerätefilter auf all devices gestellt ist, wird die Payload ein Dictionary sein mit Seriennummern als Schlüssel und entweder Batterie- oder Alarm-payloads als Werte.

3. Channel status

Das Format der Channel status-Nachrichten hängt von der Einstellung Output view ab.

Description -> connected

message {
  topic: browsePath,
  payload: {
    internal: boolean,
    [port 1 description]: boolean,
    [port 2 description]: boolean,
    ...
  }
}

Port-Beschreibungen sind oft "first", "second", "third", "fourth" (Spider) oder "left" und "right" (Sphere).

Name -> connected

message {
  topic: browsePath,
  payload: {
    [sensor 1 name]: boolean,
    [sensor 2 name]: boolean,
    ...
  }
}

Sensor-Namen bezeichnen meist was mit diesem gemessen wird, z.B. "Current in mA", "Voltage in V", "CO2" etc.

Channel number -> all info

message {
  topic: browsePath,
  payload: {
    1: {
      name: string,
      connected: boolean,
      description: string
    },
    2: {
      name: string,
      connected: boolean,
      description: string
    },
    ...
  }
}

Die Ganzzahlen als Schlüssel sind Kanalnummern. Die Felder name und description entsprechen den Schlüssel der vorigen zwei Output-views.

All channel views

Hier kriegen Sie ein Objekt mit den Feldern channels, names und descriptions, wobei jedes dieser Felder einmal das gesamte der zuvor genannten Payloads enthält.

Versionsanforderungen

• Node-RED Version >= 5.0.0
• node.js Version >= 22.0.0