NB-IoT-Geräte anbinden

NB-IoT-Geräte werden in Yggio als generische Geräte angelegt. Der Yggio-Teil davon ist kurz. Der Geräteteil ist es nicht, denn einem NB-IoT-Gerät muss erst gesagt werden, wie es das Mobilfunknetz erreicht, bevor es überhaupt etwas erreichen kann, und dieser Teil wird mit AT-Befehlen über eine serielle oder Bluetooth-Konsole konfiguriert statt über eine grafische Oberfläche.

Diese Seite deckt den gesamten Weg ab, in der Reihenfolge, in der Sie ihn gehen müssen. Die Yggio-Schritte sind bei jedem Hersteller gleich. Die Geräteschritte nutzen eine verbreitete Sensorfamilie als durchgearbeitetes Beispiel, aber die Abfolge und die meisten Befehle gelten für jedes Gerät, das auf einem gängigen NB-IoT-Modul aufbaut.

Ein generisches Gerät kann über MQTT, HTTP, CoAP, UDP oder rohes TCP melden, und welche davon ein bestimmtes Gerät unterstützt, entscheidet der Hersteller. Dieser Leitfaden verwendet MQTT als durchgearbeitetes Beispiel, weil es der am besten unterstützte Weg und mit Abstand der am leichtesten zu diagnostizierende ist.

Diese Trennung ist wichtig, wenn Sie die Schritte unten lesen:

• Das Gerät ins Mobilfunknetz zu bekommen, also SIM-Karte, Konsole und Netzanmeldung, ist dieselbe Arbeit, unabhängig davon, welches Protokoll das Gerät am Ende spricht. Die Schritte 3, 4 und 5 gelten für jedes NB-IoT-Gerät.
• Alles rund um Zugangsdaten, Topics und die Verbindung zu Yggio ist MQTT-spezifisch. Die Schritte 1, 2 und 6 sehen für ein Gerät, das über CoAP oder HTTP meldet, anders aus, denn diese adressieren und authentifizieren sich anders.

Verhält sich ein Schritt nicht wie beschrieben, gehen Sie zur NB-IoT-Fehlerbehebung, statt mehrere Einstellungen auf einmal zu ändern.

Bevor Sie beginnen

• Eine NB-IoT-SIM-Karte. Das ist nicht dasselbe wie eine gewöhnliche Mobilfunk-SIM, und eine gewöhnliche wird sich nicht anmelden.
• Den APN und alle weiteren Verbindungsdaten von demjenigen, der die SIM-Karte geliefert hat.
• Ein Telefon oder einen Computer, der die Gerätekonsole erreicht. Viele Geräte nutzen Bluetooth und eine Hersteller-App; andere ein USB-Seriellkabel.
• Das Handbuch des Geräts, für den Befehlssatz und die PIN oder das Passwort, das die Konsole schützt.
• Administratorrechte in Yggio, denn Credential Set und reserviertes Topic werden über das API angelegt.
• Die Kennungen des Geräts, meist IMEI und eine Konsolen-PIN, aufgedruckt auf Gerät oder Verpackung.

Planen Sie für das erste Gerät mehr Zeit ein, als Sie erwarten. Sobald eines läuft, gehen die übrigen schnell, und die meisten Geräte können eine gespeicherte Konfigurationsdatei laden, statt Befehl für Befehl eingetippt zu werden.

Schritt 1: Ein Credential Set anlegen (MQTT)

Das Credential Set ist das, womit sich das Gerät authentifiziert. Legen Sie es über das API an:

POST /basic-credential-sets

{
  "username": "<ein Name für dieses Gerät oder diese Gruppe>",
  "password": "<ein starkes Passwort>"
}

Die Antwort enthält eine _id. Bewahren Sie sie auf; der nächste Schritt braucht sie.

{
  "_id": "<Credential-Set-ID>",
  "username": "<ein Name für dieses Gerät oder diese Gruppe>"
}

Nehmen Sie ein Passwort, das Sie bereit sind auf ein Gerät zu legen, das möglicherweise unverschlüsselt sendet. Siehe Schritt 6.

Schritt 2: Ein MQTT-Topic reservieren (MQTT)

Das reservierte Topic wird in Yggio zum Gerät. Legen Sie eines je Gerät an und verweisen Sie auf das Credential Set aus Schritt 1:

POST /reserved-mqtt-topics

{
  "topic": "yggio/generic/v2/<Ihre Geräte-ID>",
  "basicCredentialsSetId": "<Credential-Set-ID>"
}

Ein Credential Set kann mehrere Topics besitzen, was praktisch ist, wenn ein Standort eine Handvoll gleichartiger Geräte hat. Schreiben Sie das Topic sorgfältig: Eine Abweichung hier ist der häufigste Grund, warum nie Daten erscheinen, und sie schlägt lautlos fehl.

Schritt 3: Die SIM-Karte einsetzen (alle Geräte)

Trennen Sie die Stromversorgung, bevor Sie die SIM-Karte anfassen. Sie im spannungsführenden Zustand einzusetzen riskiert einen Schaden am Modem.

1. Öffnen Sie das Gehäuse.
2. Trennen Sie den Stromjumper oder die Batterie und warten Sie. Drücken Sie einige Male die Gerätetaste, um Restladung abzubauen.
3. Lösen Sie das Modemmodul, falls der SIM-Halter darunter sitzt.
4. Setzen Sie die Nano-SIM mit den Kontakten zur Platine ein. Sie sollte einrasten und bündig sitzen, ohne hervorzustehen.
5. Setzen Sie das Modul wieder ein, vorsichtig wegen der Kunststoffgewinde, und stellen Sie die Stromversorgung wieder her.

Geben Sie dem Gerät einen Moment zum Starten, bevor Sie sich verbinden.

Schritt 4: Die Gerätekonsole erreichen (alle Geräte)

Geräte mit Bluetooth-Konsole senden meist nur in einem kurzen Zeitfenster statt dauerhaft. In der Regel öffnet entweder ein Aus- und Einschalten oder das Halten der Taste, bis die Anzeige blinkt, ein Fenster von etwa einer Minute.

Verbinden Sie sich und geben Sie dann die PIN oder das Passwort aus der Gerätedokumentation ein. Die Konsole bestätigt sie, bevor sie Befehle annimmt. Die meisten Geräte reagieren anschließend auf einen Befehl, der die aktuelle Konfiguration ausgibt, was eine gute erste Prüfung ist, ob Sie tatsächlich mit ihm sprechen.

Schritt 5: Am Mobilfunknetz anmelden (alle Geräte)

Das ist der Schritt, der Zeit kostet, und er hängt vom SIM-Anbieter ab und davon, welche Betreiber dort Abdeckung haben, wo das Gerät sitzt. Arbeiten Sie ihn der Reihe nach durch und ändern Sie eine Sache nach der anderen.

Den APN setzen. Das ist der Zugangspunkt, über den sich die SIM-Karte verbindet, und er kommt vom SIM-Anbieter. In vielen Netzen reicht das allein:

AT+APN=<APN Ihres SIM-Anbieters>

Meldet es sich nicht an, engen Sie die Suche ein. Ein Modem, das jedes Band und jeden Betreiber absucht, kann lange brauchen oder aufgeben. Drei Einstellungen helfen:

• Beschränken Sie die Bänder auf die, die Ihr Betreiber vor Ort tatsächlich nutzt, damit das Modem aufhört, die übrigen zu durchsuchen. In Europa sind Band 8 und 20 für NB-IoT üblich.
• Erhöhen Sie, wie lange das Modem es versuchen darf, bevor es aufhört.
• Wählen Sie den Betreiber ausdrücklich über seinen Netzcode, statt das Modem wählen zu lassen.

Der Betreibercode ist der Ländercode gefolgt vom Netzcode, und Ihr Betreiber veröffentlicht ihn.

Die Anmeldung bestätigen. Die meisten Module melden die Signalstärke fortlaufend auf der Konsole, mit einem Wert, der "sucht, nicht angemeldet" bedeutet. Suchen Sie diesen Wert in Ihrem Handbuch, denn er unterscheidet sich je Hersteller, und warten Sie, bis sich die Anzeige ändert, bevor Sie weitermachen. Alles danach hängt davon ab. Bei einem Dragino D20S-NB oder D23-NB ist der Wert 99.

Die SIM-Karte von der anderen Seite prüfen. Das Webportal Ihres SIM-Anbieters zeigt den Status der SIM-Karte unabhängig davon, was das Gerät sagt: ob sie aktiviert ist, ob sie sich in einem Netz angemeldet hat, in welchem, und wie viele Daten sie gesendet hat. Das ist der schnellste Weg, ein Geräteproblem von einem Vertragsproblem zu unterscheiden, und es lohnt sich, das Portal zu öffnen, bevor Sie Einstellungen ändern. Eine SIM-Karte, die sich nie angemeldet hat oder nie aktiviert wurde, lässt sich durch keinen Befehl am Gerät reparieren.

Schritt 6: Das Gerät auf Yggio ausrichten (MQTT)

Ist das Gerät im Netz, sagen Sie ihm, wohin es Daten senden soll und wie.

Yggio akzeptiert mehrere Protokolle, und MQTT ist das empfohlene. Es braucht etwas mehr Energie als die leichteren Alternativen, ist aber der am besten unterstützte Weg und der am leichtesten zu diagnostizierende.

Konfigurieren Sie in dieser Reihenfolge:

1. Das Log- oder Payload-Format. Yggio erwartet ein flaches JSON-Objekt statt eines mit Arrays. Viele Geräte haben dafür eine Einstellung, und sie wird leicht übersehen.
2. Protokoll und Payload-Typ, also MQTT mit JSON-Payload.
3. Starten Sie das Gerät neu, denn Protokolländerungen greifen meist erst danach.
4. Das Publish-Topic, das exakt dem reservierten Topic aus Schritt 2 entsprechen muss. Manche Geräte verlangen zusätzlich ein Subscribe-Topic, auch wenn nie etwas zurückgesendet wird; prüfen Sie das Handbuch, denn bei manchen Modellen führt ein leeres oder falsches Subscribe-Topic dazu, dass das Gerät nicht mehr antwortet.
5. Serveradresse und Port. Port 1883 ist unverschlüsselt.
6. Client-Kennung, Benutzername und Passwort aus dem Credential Set aus Schritt 1.
7. Das Melde-Intervall. Wägen Sie Batterielaufzeit gegen die nötige Aktualität ab; ein Standardwert von zwei Stunden ist üblich und oft länger als nötig oder kürzer, als es das Energiebudget erlaubt.

Zur Verschlüsselung. Port 1883 sendet Daten im Klartext. Yggio akzeptiert auch TLS, aber ein Zertifikat auf einem ressourcenbeschränkten Gerät zu installieren ist deutlich aufwendiger als der Rest dieses Vorgehens, und nicht jedes Gerät unterstützt es gut. Entscheiden Sie bewusst: Für eine öffentliche Badewassertemperatur mag das ein vertretbarer Kompromiss sein, für alles Persönliche oder betrieblich Sensible ist er es nicht.

Schritt 7: Bestätigen, dass die Daten angekommen sind

Lösen Sie eine Übertragung aus, entweder durch einen Neustart, durch Aus- und Einschalten oder indem Sie die Taste halten, bis die Anzeige es bestätigt.

Verbinden Sie sich sofort wieder mit der Konsole und beobachten Sie das Log. Eine erfolgreiche Übertragung benennt jede Stufe, sodass Sie sehen, wie weit sie kam: die Adressauflösung, das Öffnen der Verbindung, die erfolgreiche Anmeldung, das abgeschlossene Publish.

In Yggio erscheint nun ein Gerät unter dem reservierten Topic, vom Typ Generic. Benennen Sie es sinnvoll um; das Topic bleibt wie es ist.

Mit MQTT Explorer beim Ankommen zusehen

Bevor Sie entscheiden, dass etwas nicht stimmt, verbinden Sie MQTT Explorer mit dem Yggio-Broker und abonnieren Sie Ihr Topic mit demselben Credential Set, das auch das Gerät nutzt. Dann sehen Sie die Nachricht in dem Moment beim Broker landen, in dem sie ankommt, und das sagt Ihnen genau, wo die Kette endet:

• Nichts in MQTT Explorer und auch nichts im Gerätelog bedeutet, dass das Gerät nicht publiziert. Der Fehler liegt beim Gerät oder im Netz.
• Nichts in MQTT Explorer, aber das Gerätelog meldet ein erfolgreiches Publish, bedeutet, dass es woanders publiziert als dort, wo Sie lauschen. Vergleichen Sie Topic und Zugangsdaten Zeichen für Zeichen.
• Die Nachricht erscheint in MQTT Explorer, aber in Yggio taucht kein Gerät auf. Jetzt liegt der Fehler auf der Yggio-Seite, und das ist der Punkt, an dem der Support helfen kann.

Der letzte Fall ist der einzige, in dem wir etwas Nützliches für Sie tun können, deshalb lohnt es sich, ihn zu erreichen, bevor Sie ein Ticket eröffnen. Alles davor löst sich schneller mit dem Gerätehandbuch, dem Portal des SIM-Anbieters und der NB-IoT-Fehlerbehebung.

Schritt 8: Die Payload decodieren

Das Gerät liefert nun seine eigenen Feldnamen und seine eigenen Konventionen, und hier kommt ein Translator ins Spiel. Zwei Dinge lohnen sich in der Regel selbst bei einem einfachen Sensor.

Das erste ist, das Feld des Herstellers auf den Namen abzubilden, den Yggio erwartet. Ein Gerät mit mehreren Eingängen nummeriert diese oft, statt den Namen zu verwenden, nach dem Yggio sucht, sodass keiner davon als Temperatur erkannt wird. Den tatsächlich genutzten auf temperature zu kopieren lässt ihn in Vorschauen, Ansichten und Diagrammen erscheinen wie bei jedem anderen Gerät. Bei einem Dragino D20S-NB oder D23-NB heißen die drei Eingänge temperature1, temperature2 und temperature3.

Das zweite ist der Umgang mit dem Wert, den ein Gerät sendet, wenn kein Fühler angeschlossen ist. Viele melden eine feste Zahl außerhalb des Messbereichs statt gar nichts, und die fließt dann in Diagramme und Mittelwerte ein, als wäre sie echt. Prüfen Sie im Handbuch, was Ihr Gerät sendet. Ein Translator kann daraus stattdessen einen ausdrücklichen Status machen:

function translate (iotnode) {
  const raw = _.get(iotnode, 'temperature1');
  const value = Number(raw);
  const isValid = _.isFinite(value) && value >= MIN_VALID && value <= MAX_VALID;
  return {
    result: {
      temperature: isValid ? _.round(value, 1) : undefined,
      temperatureStatus: isValid ? 'ok' : 'invalid'
    }
  };
}

Ein sinnvoller Gültigkeitsbereich schützt außerdem vor unsinnigen Messwerten eines Sensors, an dem manipuliert wurde, der nach innen versetzt oder in der Sonne vergessen wurde.

Zum Schreiben und Hochladen von Translatoren siehe Translator-Entwicklung.

Durchgearbeitetes Beispiel: ein Dragino D20S oder D23-NB

Diese Sensoren nutzen ein gängiges NB-IoT-Modul und werden über Bluetooth mit der App des Herstellers konfiguriert. Die Konsolen-PIN ist auf der Verpackung aufgedruckt, und das Gerät meldet sich unter seiner IMEI.

Die folgenden Befehle sind die, die es braucht, um von einem unkonfigurierten Gerät zu Daten in Yggio zu kommen, in der Reihenfolge ihrer Verwendung. Der Hersteller dokumentiert den vollständigen Befehlssatz im Dragino-Wiki zur NB-IoT-Konfiguration, das die Referenz für alles jenseits dieser Abfolge ist.

Spitze Klammern markieren die einzigen Werte, die Sie ersetzen müssen. Alles andere wird genau so eingegeben, wie es dasteht.

Teil 1: ins Mobilfunknetz kommen

Verbinden Sie sich über Bluetooth, geben Sie die PIN ein, dann:

AT+CFG
AT+APN=<APN Ihres SIM-Anbieters>

AT+CFG gibt die aktuelle Konfiguration aus, was bestätigt, dass die Konsole Befehle annimmt. AT+APN ist die eine Einstellung, die immer erforderlich ist.

In vielen Netzen genügt das. Wo nicht, engen Sie die Suche des Modems ein, statt es alles absuchen zu lassen:

AT+QBAND=2,8,20
AT+CSQTIME=10
AT+COPS=1,2,"<Betreibercode>"

• AT+QBAND=2,8,20 durchsucht zwei Bänder, 8 und 20, in dieser Reihenfolge. Die führende 2 ist die Anzahl, kein Band.
• AT+CSQTIME=10 gewährt zehn Minuten für die Anmeldung, statt früher aufzugeben.
• AT+COPS=1,2,"<Betreibercode>" wählt einen Betreiber manuell statt automatisch. Die 1 bedeutet manuell, die 2 bedeutet, dass der Code numerisch ist, und der Code selbst ist der Ländercode gefolgt vom Netzcode, zum Beispiel 24001. Ihr Betreiber veröffentlicht seinen.

Beobachten Sie die Konsole. Solange sie Signalstärke 99 ausgibt, hat sich das Modem nicht angemeldet. Ändert sich diese Zahl, hat es das, und erst dann lohnt es sich weiterzumachen.

Teil 2: es über MQTT auf Yggio ausrichten

AT+CLOCKLOG=1,65535,0,0
AT+PRO=3,5
ATZ

• AT+CLOCKLOG=1,65535,0,0 erzeugt eine flache JSON-Payload, ohne die Arrays, die Yggio nicht liest.
• AT+PRO=3,5 wählt MQTT als Protokoll und JSON als Payload-Format.
• ATZ startet das Gerät neu. Die Protokolländerung greift erst danach.

Verbinden Sie sich nach dem Neustart erneut und geben Sie dann die Verbindungsdaten ein:

AT+PUBTOPIC=yggio/generic/v2/<Ihre Geräte-ID>
AT+SUBTOPIC=yggio/generic/v2/<Ihre Geräte-ID>/subtopic
AT+SERVADDR=staging.yggio.net,1883
AT+CLIENT=<Credential-Set-ID>
AT+UNAME=<Credential-Set-Benutzername>
AT+PWD=<Credential-Set-Passwort>
AT+TDC=3600
ATZ

• AT+PUBTOPIC muss exakt dem reservierten Topic aus Schritt 2 entsprechen.
• AT+SUBTOPIC muss das Publish-Topic mit angehängtem /subtopic sein. Darauf wird nie etwas zurückgesendet, aber es leer zu lassen oder gleich dem Publish-Topic zu setzen führt dazu, dass das Gerät nicht mehr antwortet.
• AT+SERVADDR nimmt Host und Port. 1883 ist unverschlüsselt.
• AT+CLIENT ist die _id des Credential Sets aus Schritt 1, nicht dessen Benutzername.
• AT+TDC=3600 meldet stündlich. Die Werkseinstellung ist oft 7200, also alle zwei Stunden.
• Das abschließende ATZ startet das Gerät neu, was eine Übertragung auslöst.

Verbinden Sie sich sofort wieder und beobachten Sie das Log. Ein funktionierendes Gerät benennt jede Stufe, die es passiert: die Adressauflösung, das Öffnen der Verbindung, die erfolgreiche Anmeldung, das abgeschlossene Publish.

Zwei Eigenheiten, die man vorher kennen sollte

Die Anforderung an das Subscribe-Topic oben ist die erste, und man verliert leicht einen Nachmittag daran, weil das Gerät schlicht aufhört zu antworten.

Die zweite: Ein Eingang ohne angeschlossenen Fühler meldet -409.5, was unter dem absoluten Nullpunkt liegt und daher ein Platzhalterwert und kein Messwert ist. Die drei Eingänge heißen temperature1, temperature2 und temperature3, weshalb ein Translator den genutzten in temperature und den Platzhalter in einen Status verwandelt.

Für alles, was auf dieser Hardware bestätigt ist, siehe gerätespezifisches Verhalten.

Wie es weitergeht

• NB-IoT-Fehlerbehebung, wenn sich ein Schritt anders verhält.
• IoT-Knoten und Netzwerkprotokolle zum generischen Gerätetyp und den weiteren Protokollen, die er annimmt.
• Netzwerktechniken dazu, wie NB-IoT im Vergleich zu den Alternativen dasteht.
• Sensative Support, wenn Sie auf der Yggio-Seite feststecken.