Particle.io

Einf├╝hrung

Mit Hilfe der Particle.io Integration l├Ąsst sich jedes beliebige Particle.io Ger├Ąt in die Datacake Cloud integrieren. Um Messwerte in die Datacake Cloud zu ├╝bertragen gen├╝gt hier ein einfaches Particle.publish("event","1.23"); und schon werden Messdaten entsprechend eines frei definierbaren Event Mappings in die Datacake Cloud ├╝bertragen.

Features

Dort k├Ânnen diese Messdaten f├╝r folgende Funktionen genutzt werden:

  • Erstellung von Echtzeit-Dashboards ├╝ber WYSIWYG Editor

  • Aufstellung von Regeln zur Benachrichtigung per SMS

  • Hochaufl├Âsende Langzeit-Datenspeicherung inkl. grafischer Auswertung

  • Export der Messdaten nach CSV, Excel oder JSON oder per REST-API

  • Einladen von Personen zur Zusammenarbeit inkl. Management f├╝r Rechte und Rollen

  • Bereitstellung des Portals an Kunden, Mitarbeitern, etc.

  • Erstellung globaler Dashboards

  • Nutzung einer managed Node-RED Variante namens Cake Red

  • Debug-├ťbersicht mit kontinuierlicher Speicherung der letzten 100 Particle.io Publishes

Notwendige Schritte

Die daf├╝r notwendigen Schritte sind ├╝berschaubar. Ist ein entsprechendes Particle.io Produkt / Ger├Ąt vorhanden, dann vergehen in der Regel nur wenige Minuten, bis Daten zur Cloud ├╝bertragen werden k├Ânnen. Diese Schritte sehen wie folgt aus:

  • Neues API-Device anlegen

  • Datenfelder erstellen

  • Particle.io Ger├Ąt verkn├╝pfen

  • Dashboard erstellen

  • Regeln erstellen

  • Kuchen essen!

Neues API-Device anlegen

Integrationen stehen in der Datacake Cloud als Erweiterung zu einem Ger├Ąt bereit. Wir nennen dies API-Device.Deshalb ist der erste Schritt zur Integration das Anlegen einen neuen Ger├Ąts - oder eben API-Device.

Hierzu navigieren Sie in der Seitenleiste in der Gruppe "Flotte" auf "Alle Ger├Ąte" und bet├Ątigen die Schaltfl├Ąche "Ger├Ąt hinzuf├╝gen", so wie im folgenden Screenshot dargestellt.

Nun sollte Ihr Browser folgenden Inhalt zeigen:

Hier w├Ąhlen Sie nun bitte den Ger├Ątetypen "API" aus und vergeben einen entsprechenden Namen f├╝r das neue Ger├Ąt. Diese k├Ânnen Sie sp├Ąter dann zu jedem Zeitpunkt ver├Ąndern.

Abschlie├čend best├Ątigen Sie die Eingabe mittels klick auf den Button "Ger├Ąt hinzuf├╝gen und konfigurieren". Dies wechselt dann auch automatisch zur Konfigurations-├ťbersicht, welche f├╝r den n├Ąchsten Schritt erforderlich ist.

Datenbank-Felder anlegen

Damit Messwerte gespeichert werden k├Ânnen, m├╝ssen entsprechende Felder in der Datenbank angelegt werden. Scrollen Sie dazu bitte in der Konfigurations-Ansicht des Ger├Ątes zur Gruppe "Felder" und klicken (wie auf folgendem Screenshot markiert) dort dann auf den Button "Feld hinzuf├╝gen".

Nun sollte sich folgende Ansicht zeigen:

Name

Hier k├Ânnen Sie einen Namen f├╝r das Feld w├Ąhlen. Dieser ist frei w├Ąhlbar und l├Ąsst sich auch sp├Ąter noch beliebig oft ver├Ąndern.

Identifier

Dies ist der Identifier des Messfeldes, welcher intern in der Datenbank das Feld eindeutig beschreibt. Dieser Identifier wird auch f├╝r die API genutzt und tauch in diversen Bereichen der Cloud immer wieder auf.

Keine Sorge! Auch wenn Sie den Namen des Feldes ├Ąndern, bleibt der Identifier erhalten.

Der Identifier ist aus technischen Gr├╝nden nur beim Anlegen des Feldes editierbar. Sobald Sie das Feld ├╝ber den "Speichern" Button angelegt haben, k├Ânnen Sie diesen nicht mehr editieren. Wenn Sie den Identifier ver├Ąndern wollen, m├╝ssen Sie das Feld l├Âschen und neu erstellen.

Typ

Achten Sie bitte beim Anlegen auf die korrekte Angabe des Typ! Sie k├Ânnen diesen zu einem sp├Ąteren Zeitpunkt aus technischen Gr├╝nden nicht mehr anpassen. Dies geht nur, wenn Sie das jeweilige Feld l├Âschen und anschlie├čend neu erstellen!

Integer

Speichert Integer-Zahlen ohne Flie├čkomma.

  • Aufbau u. Beispiel: Particle.publish("numberofcakes","42");

Location

Location speichert Geo-Koordinaten, welche z.B. f├╝r das Karten-Widget genutzt werden k├Ânnen, um Positionen einen Ger├Ąts anzeigen zu k├Ânnen.

  • Aufbau: Particle.publish("cakeplace","(<latitude>, <longitude>)");

  • Beispiel: Particle.publish("cakeplace","(51.96236,7.62571)");

Float

Speichert Flie├čkomma-Zahlen.

  • Aufbau u. Beispiel: Particle.publish("caketemp","3.21");

Boolean

Speichert Boolean-Zust├Ąnde.

  • Aufbau u. Beispiel: True = Particle.publish("aboolean","1");

  • False = Particle.publish("aboolean","0");

String

Speichert ganze String-Folgen.

  • Aufbau u. Beispiel: Particle.publish("whathesaid","hello world!");

Counter

Aktuell wird das Counter-Feld leider nur von der Datacake D Zero unterst├╝tzt. Wir sind gerade dabei die Funktionalit├Ąt auch f├╝r die API-Devices zu ├╝bertragen.

Beispiele

Schauen Sie weiter unten nach Code-Beispielen!

Einheit

Display Unit

In diesem Feld k├Ânnen Sie eine Einheit f├╝r den jeweiligen Messwert, in Form eines Freitextes definieren.

Unit

Hier stehen Ihnen diverse Einheiten als Vorauswahl zur Verf├╝gung. Hintergrund ist eine automatisierte Umrechnung in eine beliebige andere Einheit (siehe n├Ąchsten Punkt).

Display Unit

Wenn Sie eine vordefinierte Einheit ausgew├Ąhlt haben, so k├Ânnen Sie mit Hilfe des Drop-Downs eine Einheit ausw├Ąhlen, in welche der Messwert dann umgerechnet werden soll.

Float Digits

Wenn der jeweilige Typ des Feldes Nachkommastellen zul├Ąsst, k├Ânnen Sie hier festlegen mit welcher Pr├Ązision (Anzahl der Nachkommastellen) diese in der Datenbank abgebildet bzw. festgehalten wird. Tragen Sie dazu die gew├╝nschte Anzahl an Stellen als Zahl in die Maske ein.

Formel

Dieser Punkt umfasst ein eigenes Kapitel f├╝r sich. Wir schneiden das Thema aber dennoch kurz hier an. Mit Hilfe der Formeln lassen sich mathematische Berechnungen f├╝r den Messwert durchf├╝hren. Hier wird eine entsprechende Formel definiert.

Available Placeholders

Als Elemente der Formel stehen Ihnen z.B. Messwerte zur Verf├╝gung, um Berechnungen durchzuf├╝hren, die von mehreren Messwerten abh├Ąngig sind.

Datenbank-Felder, welche eine Formel zur Berechnung nutzen, sollten in der Regel rein virtuell definiert werden, sprich nicht von einem Device mit Messwerten versorgt werden. Hintergrund ist folgender:

Definieren Sie eine Formel in einem Feld, welches seinen Messwert ├╝ber ein angekoppeltes Device oder der REST-API erh├Ąlt, so wird der aus der Formel resultierende Wert nicht in der Datenbank gespeichert!

Beispiel

Folgender Screenshot zeigt angelegte Datenbankfelder f├╝r die Speicherung von Messdaten, welche durch den Particle.io Asset Tracker generiert wurden.

Integration konfigurieren

Um nun Ihr Particle.io Device mit dem Datacake-API Device zu verbinden, wird final noch die Particle.io Integration konfiguriert. Hierzu befindet sich am Ende des Konfigurations-Tab in der Gruppe "Integrations" eine Schaltfl├Ąche "Konfigurieren". Beim bet├Ątigen sollte folgender Inhalt zu sehen sein:

Das Particle.io Integrations Modal

Webhook erstellen

Die Daten werden von der Particle.io Device Cloud via Webhook zur Datacake Cloud ├╝bertragen. Dazu muss in der Particle Console eine entsprechende Webhook-Integration angelegt werden. Dies funktioniert sowohl f├╝r Devices in Particle-Produkten als auch in Ihrer pers├Ânlichen Device-Liste.

Neue Integration anlegen

In der Particle Console w├Ąhlen Sie in der Seitenleiste den Punkt "Integrations" aus und f├╝gen eine neue Integration ├╝ber einen Klick auf "New Integration" hinzu.

Es erscheint eine Auswahl an verf├╝gbaren Integrations. W├Ąhlen Sie hier den Typ "Webhook".

Webhook konfigurieren

Nach der Auswahl erscheint eine Konfigurations-Ansicht. Hier geben Sie folgende URL in das entsprechende Feld (URL) ein:

  • https://api.datacake.de/integrations/particle

Anschlie├čend legen Sie noch den Event-Namen des Events fest, welches Sie in Ihrem Particle.publish(); aufrufen, z.B. myevent f├╝r Particle.publish("myevent","1.23");

Schauen Sie sich dazu auch folgenden Screenshot an:

Particle Device-ID setzen

In der Datacake-Particle Integration muss nun die Eingabe der Device-ID Ihres Particle.io Ger├Ątes erfolgen. Dies bindet das API-Device an das jeweilige Particle Device.

Eine Particle.io Device ID kann nur einmalig verwendet werden. Ist sie also schon an einem API-Device gebunden, so kann diese nicht erneut z.B. zu einem weiteren API Device angebunden werden!

Event Mapping hinzuf├╝gen

Nun m├╝ssen Sie noch das Event-Mapping bestimmen. Hier muss das jeweilige Event ├╝ber den "Event Namen" festgelegt werden (im folgenden Screenshot rot markiert), sowie die Struktur der Daten beschrieben werden. Dazu w├Ąhlen Sie mit Hilfe des Drop-Down-Menus (im folgenden Screenshot blau markiert) die jeweiligen Felder aus.

Reihenfolge beachten!

Das Event Mapping erwartet, dass Sie die Felder exakt in der Reihenfolge ausw├Ąhlen, wie sie auch im Aufruf der Particle.publish(); Funktion vorkommt. Beachten Sie dazu das in dem Formular eingeblendete Beispiel!

Weiteres Mapping hinzuf├╝gen

Sollten Sie in dem Code Ihres Devices mehr als nur ein Particle.publish(); Event definiert haben, so k├Ânnen Sie selbstverst├Ąndlich weitere Event Mappings anlegen. Dazu klicken Sie einfach erneut auf die Schaltfl├Ąche und f├╝hren die oben beschriebenen Schritte erneut aus.

Folgender Screenshot zeigt eine beispielhafte Implementierung mit multiplen Event Mappings bzw. Publishes:

Code anpassen

Dieses Kapitel geht nun kurz auf die Struktur der Daten├╝bertragung ein. In der Regel m├╝ssen Sie keine gro├čartigen ├änderungen an Ihrer Firmware durchf├╝hren. Einzig beim ├ťbertragen von mehreren Werten pro Publish gilt es, eine Struktur einzuhalten. Diese wird im folgenden Kapitel n├Ąher beschrieben.

Konzept

Damit Sie Daten in die Datacake Cloud ├╝bertragen k├Ânnen, reicht es, dass Sie dazu Particle.publish(); in dem Code Ihres Ger├Ątes aufrufen und die Messdaten ├╝ber Semikolon-Separierte-Werte ├╝bergeben. In etwa wie folgt:

  • Particle.Publish("event","(51.96236,7.62571);42;1.23;hello world);

In diesem Beispiel w├Ąren die ├ťbertragenen Messwerte wie folgt:

  • Location = 51.96236, 7.62571

  • Integer = 42

  • Float = 1,23

  • String = "hello world"

Dieses Schema bezeichnen wir als "Event Mapping"

Aggregation

Wie im obigen Beispiel erkennbar, ist es nicht erforderlich, dass Sie f├╝r jeden Typ ein eigenes Particle.publish(); definieren. Sie k├Ânnen beliebig viele Felder in einem Publish zusammenf├╝gen. Hier ist die maximale Publish-Payload-Gr├Â├če, welche Seitens Particle.io festgelegt wird, die Grenze.

Beispiele

Koordinaten

Im folgenden Beispiel ├╝bertragen wir per GPS gewonnene Messdaten eines Particle.io Asset Tracker zur Datacake Cloud.

AssetTracker t;
Particle.publish("gps",
String::format(
"(%f,%f);%f;%d;%d;%f;%f",
t.readLatDeg(),
t.readLonDeg(),
t.getAltitude(),
t.getSatellites(),
t.getTinyGPSPlus()->getHDOP().value(),
t.getTinyGPSPlus()->getSpeed().kmph(),
t.getAngle()
);

Dashboard anlegen

Bleiben wir beim Beispiel des Asset Trackers und erstellen nun ein passendes Dashboard.

Wenn Sie ein Ger├Ąt das erste Mal anlegen, dann ist das Dashboard noch auf einer Default-Konfiguration gesetzt. Diese sieht in etwa wie folgt aus:

Die hier angegebenen ├ťberschriften und Einteilungen "Analoge, Digitale Eing├Ąnge" sowie "Temperatur" entstammen noch einer ├Ąlteren Version und verschwinden nach der Editierung bzw. Erstellung Ihres Dashboards.

Editierung starten

Um das Dashboard Ihres Device editieren bzw. erstellen zu k├Ânnen, m├╝ssen Sie es lediglich in den Edit-Mode versetzen. Dies geschieht mittels Schalter in der Tab-Leiste:

Nach dem Anklicken bewegt sich der Schalter und das Dashboard wechselt in den Edit-Mode. Dieser zeigt sich in etwa wie folgt:

Karten-Widget platzieren

Aus der Seitenleiste auf der rechten Seite k├Ânnen Sie einzelnen Widgets auf das Dashboard ziehen.

Zeile

Damit Widgets platziert werden k├Ânnen, muss vorab eine Zeile auf das Dashboard gelegt werden. Zeilen sind tr├Ąger der Widgets und k├Ânnen sp├Ąter z.B. in ihrer vertikalen Position neu angeordnet werden.

Im obigen Screenshot zeigt sich, dass bei erstmaligem editieren bereits automatisch eine erste Zeile angelegt worden ist (blauer Rahmen mit Steuerelementen).

Karten-Widget

F├╝r den Asset Tracker w├Ąhlen wir das Karten Widget aus der Seitenleiste und ziehen es per Drag and Drop auf die erste Zeile unseres Dashboards.

Karten-Widget konfigurieren

Nun muss das Datenbank-Feld mit der aktuellen Position des Asset Tracker mit dem Widget verkn├╝pft werden. Dazu ├Âffnet man die Einstellungen des Widgets ├╝ber den Konfigurations-Button des Widgets:

Es sollte sich Ihnen nun folgender Inhalt zeigen:

├ťber das Drop-Down-Menu "Feld" haben Sie Zugriff auf die jeweiligen, kompatiblen Felder. Hier w├Ąhlen Sie das Feld "Location" aus, welches wir weiter oben in dem Guide bereits in der Konfiguration angelegt hatten.

Dieses Feld h├Ąlt die Position und wir automatisch aktualisiert, wenn Particle.publish("gps".....); mit der jeweiligen Position vom Ger├Ąt versendet wird.

Widgets f├╝r Messfelder

Nun f├╝gen Sie eine weitere Zeile dem Dashboard hinzu. Gern oberhalb der Karte. In dieser Zeile f├╝gen wir nun f├╝nf "Wert"-Widgets hinzu:

Das Dashboard sieht dann in etwa wie folgt aus:

Felder mit Widget verkn├╝pfen

Nun m├╝ssen Sie bei dem Karten-Widget die Felder der Datenbank mit den jeweiligen Widgets verkn├╝pfen. Auch hier ├Âffnen Sie die Einstellungen des Widgets ├╝ber den entsprechenden Konfigurations-Button des Widgets:

In dem darauf folgenden Dialog w├Ąhlen Sie die entsprechenden Felder aus der Datenbank aus. Auch hier ist es so, dass beim Eintreffen neuer Messdaten diese dann automatisch ebenfalls an das Widget ├╝bertragen werden.

F├╝r die Demo w├Ąhlen wir einfach die zus├Ątzlichen Informationen, die das GPS-Modul des Asset Tracker liefert. Das resultierende Dashboard sieht dann wie folgt aus:

Regeln festlegen

Als einen abschlie├čenden Schritt erstellen wir nun eine Regel, die eine ├ťberwachung der Geschwindigkeit definiert und jedesmal eine SMS schickt, wenn die Geschwindigkeit ├╝ber 10 km/h steigt.

Regel erstellen

├ťber die linke Seitenleiste navigieren Sie unter der Gruppe "Administration" zum Punkt "Regeln":

Nun f├╝gen Sie eine neue Regel ├╝ber das Bet├Ątigen des Buttons "Regel hinzuf├╝gen" hinzu. Es sollte sich automatisch folgender Inhalt zeigen: