Geräteanbindung
Dieses Kapitel ist der Vertrag, in dem Ihre Hardware mit SensoCAN spricht. Ihr Gerät sendet Messwerte, SensoCAN ordnet jeden davon einem Sensor zu, den Sie konfiguriert haben, und übergibt ihn der Regelkette dieses Sensors. Dashboards, Alarme und Exporte arbeiten alle mit dem, was hier ankommt.
Zwei Protokolle transportieren dieselben Nutzdaten (payload):
- MQTT: eine dauerhafte Verbindung, aus der Sie veröffentlichen, sobald Daten vorliegen.
- HTTP: eine Anfrage je Messwert oder Stapel, ohne eine Verbindung offen zu halten.
Sie setzen ein unterstütztes BLE-Gateway statt eigener Firmware ein? Dann lesen Sie das Kapitel Gateways und Beacons.
Protokoll wählen
| MQTT | HTTP | |
|---|---|---|
| Verbindung | Dauerhaft, bleibt offen | Eine Anfrage nach der anderen |
| Rückmeldung je Nachricht | Keine | Vollständig: Anzahl der angenommenen, doppelten und abgelehnten Messwerte |
| Mehraufwand je Messwert | Sehr gering | Ein TLS-Handshake und Header je Anfrage |
| Firewall-Verträglichkeit | Benötigt einen offenen ausgehenden Port | Gewöhnliches HTTPS |
| Nachliefern gepufferter Messwerte | Unterstützt | Unterstützt |
| Am besten geeignet für | Batteriebetriebene Geräte, hohe Melderaten, Mobilfunkverbindungen | Geräte hinter restriktiven Netzen, Gateways mit reinem HTTP-Stack, Erstinbetriebnahme und Fehlersuche |
Eine MQTT-Veröffentlichung sagt Ihnen, dass die Nachricht das Gerät verlassen hat; ob der Messwert verstanden wurde, kann sie nicht sagen, denn es gibt keinen Rückkanal. Jede HTTP-Anfrage antwortet dagegen mit dem, was mit jedem einzelnen Messwert darin geschehen ist. Senden Sie bei der Erstinbetriebnahme der Firmware zuerst eine HTTP-Anfrage und lesen Sie die Antwort; wechseln Sie erst zu MQTT, wenn die Nutzdaten stimmen.
Was Sie zuerst von der Plattform brauchen
Alles, was Ihre Firmware braucht, steht auf der Seite Gerätedetails: Öffnen Sie Geräte und klicken Sie auf den Gerätenamen.
| Wert | Wo Sie ihn finden | Verwendung |
|---|---|---|
| Device UUID | Karte Geräteinformationen, mit einer Schaltfläche zum Kopieren | MQTT-Client-ID; Teil jeder HTTP-URL |
| MQTT-Topic | Karte Geräteinformationen, vollständig angezeigt, mit Schaltfläche zum Kopieren | Das Publish-Topic auf Geräteebene |
| MQTT-Benutzername und -Passwort | Schaltfläche MQTT-Anmeldedaten | Verbindung zum MQTT-Host |
| Zugriffstoken | Schaltfläche Token anzeigen | Der HTTP-Header Authorization |
| Sensor-Slug und Sensor-UUID | Tabelle Sensoren → einen Sensor öffnen | Einen Messwert an einen bestimmten Sensor richten |
Setzen Sie Topics oder URLs nicht von Hand zusammen. Die Seite gibt das fertige Topic aus, also den Kanal, unter dem dieses Gerät veröffentlicht, und die Schaltfläche MQTT-Payload-Beispiele daneben öffnet fertige Topics und Nutzdaten, die bereits mit den echten Kennungen dieses Geräts gefüllt sind.
Wer den Zugriffstoken oder das MQTT-Passwort besitzt, kann Messwerte im Namen dieses Geräts senden. Der Zugriffstoken lässt sich jederzeit über Token anzeigen neu generieren; das macht den alten sofort ungültig und sperrt das Gerät aus, bis Sie den neuen Wert aufspielen. Das MQTT-Passwort lässt sich nicht auf dieselbe Weise wechseln: Muss es geändert werden, wird es nur dann automatisch neu ausgestellt, wenn die gespeicherten Anmeldedaten verloren gehen oder sich nicht mehr entschlüsseln lassen.
Nutzdatenregeln für beide Protokolle
Verpacken Sie Messwerte in data. Die Nutzdaten tragen immer einen data-Schlüssel auf oberster Ebene, der entweder ein einzelnes Messwertobjekt oder ein Array solcher Objekte enthält. Alles außerhalb von data gilt nicht als Messwert.
value ist erforderlich und sollte eine Zahl sein. Über HTTP wird ein nicht numerischer Wert abgelehnt. Über MQTT lehnt ihn nichts ab, aber Regeln, Diagramme und Exporte erwarten alle eine Zahl.
timestamp ist optional. Senden Sie ihn nach ISO 8601 (2026-09-03T10:00:00Z). Lassen Sie ihn weg, erhält der Messwert den Zeitpunkt seines Eintreffens als Zeitstempel.
Abweichende Geräteuhren werden korrigiert, nicht bestraft. Geht der neueste Zeitstempel in den Nutzdaten dem Zeitpunkt ihres Eintreffens voraus, weil die Geräteuhr vorgeht, werden die gesamten Nutzdaten um genau diesen Versatz zurückverschoben: Der neueste Messwert landet auf der Eintreffzeit, und die Abstände zwischen den Messwerten bleiben erhalten. Nichts wird verworfen, weil es „in der Zukunft“ liegt; Sie müssen die Uhr also nie prüfen, bevor Sie einen Puffer leeren. Korrigierte Messwerte halten den angewendeten Versatz als clock_offset_seconds in ihren gespeicherten Metadaten fest, sodass korrigierte Daten von gemessenen Daten unterscheidbar bleiben. Zeitstempel in der Vergangenheit werden so gespeichert, wie sie gesendet wurden; das ist das gewöhnliche Nachliefern gepufferter Messwerte.
battery_voltage steht neben data, nicht darin. Senden Sie die Spannung in Volt als Zahl; angenommen wird der Bereich 0–100, ein Wert von 3.7 aus einer Lithiumzelle ist also typisch. Die Seite Gerätedetails zeigt ihn als Spannung, bezogen auf den für das Gerät konfigurierten Batterietyp, und leitet aus beidem den Prozentwert Ladezustand ab. Bei Geräten, die auf Direktstrom eingestellt sind, wird er ignoriert. Über MQTT können Sie battery_voltage auch allein veröffentlichen, ganz ohne data-Schlüssel, auf einem beliebigen Topic. Über HTTP muss jede Anfrage ein data-Objekt oder -Array enthalten: Einen Endpunkt (endpoint) nur für die Batterie gibt es nicht.
Zusätzliche Schlüssel werden mitgeführt. Jeder weitere Schlüssel in einem Messwertobjekt wird als Metadaten aufbewahrt und kann von Regeln gelesen werden: Firmware-Version, Signalstärke, Anzahl der Messungen. Höchstens 30 Schlüssel je Messwert, nur einzelne Werte (keine verschachtelten Objekte oder Arrays), Schlüsselnamen bis 64 Zeichen, Text wird bei 512 Zeichen gekürzt.
Wiederholungen werden unterdrückt. Bei einigen Sensortypen wird derselbe Wert, der innerhalb weniger Sekunden erneut für denselben Sensor gesendet wird, nicht zweimal verarbeitet. Einen Puffer erneut zu senden ist daher unbedenklich: Ein Duplikat ist nie ein Fehler.
Angenommen heißt nicht gespeichert
Ein angenommener Messwert wird an die Regelkette übergeben, die für diesen Sensor gilt, und diese Kette entscheidet, was als Nächstes geschieht – auch darüber, ob der Messwert gespeichert wird. Jedes Konto startet mit einer Standard-Regelkette, die alles speichert, was bei ihr ankommt. Ersetzen Sie sie durch eine eigene Kette ohne Speicherschritt, bekommt Ihr Gerät weiterhin gemeldet, dass seine Messwerte angenommen wurden, während auf der Geräteseite nichts erscheint. Prüfen Sie die Kette unter Verwaltung → Regelketten, bevor Sie Ihre Firmware verdächtigen.