Ansluta NB-IoT-enheter

NB-IoT-enheter läggs till i Yggio som generiska enheter. Yggio-delen av det här är kort. Enhetsdelen är det inte, eftersom en NB-IoT-enhet måste få veta hur den ska nå mobilnätet innan den kan nå något alls, och den delen konfigureras med AT-kommandon över en seriell konsol eller Bluetooth i stället för ett grafiskt gränssnitt.

Den här sidan täcker hela vägen, i den ordning du måste gå den. Yggio-stegen är desamma oavsett tillverkare. Enhetsstegen använder en spridd sensorfamilj som genomarbetat exempel, men sekvensen, och de flesta kommandona, gäller varje enhet byggd på en vanlig NB-IoT-modul.

En generisk enhet kan rapportera över MQTT, HTTP, CoAP, UDP eller rå TCP, och vilka av dem en viss enhet stödjer bestämmer tillverkaren. Den här guiden använder MQTT som genomarbetat exempel, eftersom det är den bäst stödda vägen och med bred marginal den enklaste att felsöka.

Den uppdelningen spelar roll när du läser stegen nedan:

• Att få enheten på mobilnätet, alltså SIM-kortet, konsolen och anslutningen, är samma arbete oavsett vilket protokoll enheten till slut talar. Steg 3, 4 och 5 gäller varje NB-IoT-enhet.
• Allt som rör inloggningsuppgifter, topics och anslutningen till Yggio är specifikt för MQTT. Steg 1, 2 och 6 ser annorlunda ut för en enhet som rapporterar över CoAP eller HTTP, vilka adresserar och autentiserar sig på andra sätt.

Om ett steg inte beter sig som beskrivet, gå till Felsökning av NB-IoT i stället för att ändra flera inställningar på en gång.

Innan du börjar

• Ett NB-IoT-SIM-kort. Det är inte samma sak som ett vanligt SIM för mobilt bredband, och ett vanligt kommer inte att ansluta.
• APN, och övriga anslutningsuppgifter, från den som levererade SIM-kortet.
• En telefon eller dator som når enhetens konsol. Många enheter använder Bluetooth och en app från tillverkaren; andra använder en USB-seriekabel.
• Enhetens manual, för kommandouppsättningen och den PIN-kod eller det lösenord som skyddar konsolen.
• Administratörsrättigheter i Yggio, eftersom credential set och det reserverade topicet skapas via API:et.
• Enhetens egna identifierare, oftast IMEI och en konsol-PIN, tryckta på enheten eller förpackningen.

Räkna med mer tid än du tror för den första enheten. När en fungerar går resten fort, och de flesta enheter kan läsa in en sparad konfigurationsfil i stället för att matas in kommando för kommando.

Steg 1: Skapa ett credential set (MQTT)

Ett credential set är det enheten autentiserar sig med. Skapa det via API:et:

POST /basic-credential-sets

{
  "username": "<ett namn för enheten eller gruppen>",
  "password": "<ett starkt lösenord>"
}

Svaret innehåller ett _id. Spara det; nästa steg behöver det.

{
  "_id": "<credential set id>",
  "username": "<ett namn för enheten eller gruppen>"
}

Använd ett lösenord som du är beredd att lägga på en enhet som kan komma att sända okrypterat. Se steg 6.

Steg 2: Reservera ett MQTT-topic (MQTT)

Det reserverade topicet är det som blir enheten i Yggio. Skapa ett per enhet och peka det mot det credential set du skapade i steg 1:

POST /reserved-mqtt-topics

{
  "topic": "yggio/generic/v2/<ditt enhets-id>",
  "basicCredentialsSetId": "<credential set id>"
}

Ett credential set kan äga flera topics, vilket är praktiskt när en anläggning har en handfull likadana enheter. Stava topicet noga: en felstavning här är den vanligaste orsaken till att data aldrig dyker upp, och den misslyckas tyst.

Steg 3: Montera SIM-kortet (alla enheter)

Bryt strömmen innan du rör SIM-kortet. Att montera det med enheten spänningssatt riskerar att skada modemet.

1. Öppna kapslingen.
2. Koppla loss strömbygeln eller batteriet och vänta en stund. Tryck några gånger på enhetens knapp för att ladda ur det som är kvar.
3. Lossa modemmodulen om SIM-hållaren sitter under den.
4. Sätt i nano-SIM-kortet med kontaktytan mot kretskortet. Det ska klicka och ligga i plan, utan att sticka ut.
5. Montera tillbaka modulen, försiktigt eftersom gängorna är i plast, och slå på strömmen igen.

Ge enheten en stund att starta innan du ansluter till den.

Steg 4: Nå enhetens konsol (alla enheter)

Enheter med Bluetooth-konsol annonserar sig oftast under ett kort fönster i stället för hela tiden. Vanligtvis öppnar antingen en strömcykling eller att hålla in knappen tills indikatorn blinkar ett fönster på ungefär en minut.

Anslut och ange sedan den PIN-kod eller det lösenord som finns i enhetens dokumentation. Konsolen bekräftar den innan den tar emot kommandon. De flesta enheter svarar sedan på ett kommando som skriver ut aktuell konfiguration, vilket är en bra första kontroll på att du verkligen pratar med den.

Steg 5: Ansluta till mobilnätet (alla enheter)

Det här är steget som tar tid, och det beror på SIM-leverantören och på vilka operatörer som har täckning där enheten sitter. Arbeta igenom det i ordning och ändra en sak i taget.

Ställ in APN. Det är den anslutningspunkt SIM-kortet ansluter genom, och den kommer från SIM-leverantören. På många nät räcker det här ensamt:

AT+APN=<apn från din SIM-leverantör>

Om den inte ansluter, begränsa sökningen. Ett modem som lämnas att skanna varje band och varje operatör kan hålla på länge, eller ge upp. Tre inställningar hjälper:

• Begränsa banden till dem din operatör faktiskt använder lokalt, så att modemet slutar leta bland resten. I Europa är band 8 och 20 vanliga för NB-IoT.
• Öka hur länge modemet får fortsätta försöka innan det slutar.
• Välj operatör uttryckligen, med operatörskod, i stället för att låta modemet välja.

Operatörskoden är landskoden följd av nätkoden, och din operatör publicerar sin.

Bekräfta anslutningen. De flesta moduler rapporterar signalstyrka löpande på konsolen, med ett värde som betyder "söker, inte ansluten". Leta upp det värdet i din manual, eftersom det skiljer sig mellan tillverkare, och vänta tills avläsningen ändras innan du går vidare. Allt efter det här beror på det. På en Dragino D20S-NB eller D23-NB är värdet 99.

Kontrollera SIM-kortet från andra hållet. SIM-leverantörens webbportal visar SIM-kortets status oberoende av vad enheten säger: om det är aktiverat, om det har anslutit till ett nät, vilket nät, och hur mycket data det har skickat. Det är det snabbaste sättet att skilja ett enhetsproblem från ett abonnemangsproblem, och det är värt att öppna innan du börjar ändra inställningar. Ett SIM-kort som aldrig har anslutit, eller aldrig aktiverades, blir inte hjälpt av något kommando på enheten.

Steg 6: Rikta enheten mot Yggio (MQTT)

Med enheten på nätet återstår att tala om vart den ska skicka data och hur.

Yggio accepterar flera protokoll, och MQTT är det rekommenderade. Det drar något mer ström än de lättare alternativen, men det är den bäst stödda vägen och den enklaste att felsöka.

Konfigurera i den här ordningen:

1. Logg- eller payloadformatet. Yggio förväntar sig ett platt JSON-objekt snarare än ett som innehåller arrayer. Många enheter har en inställning för det och den är lätt att missa.
2. Protokoll och payloadtyp, alltså MQTT med JSON-payload.
3. Starta om enheten, eftersom protokolländringar oftast kräver en omstart innan de får effekt.
4. Publiceringstopicet, som exakt ska matcha det reserverade topicet från steg 2. Vissa enheter kräver också att ett prenumerationstopic sätts, även när ingenting skickas tillbaka; läs manualen, eftersom vissa modeller slutar svara om det lämnas tomt eller sätts fel.
5. Serveradress och port. Port 1883 är okrypterad.
6. Klientidentifierare, användarnamn och lösenord från det credential set du skapade i steg 1.
7. Rapportintervallet. Väg batteritid mot hur färsk datan behöver vara; ett standardvärde på varannan timme är vanligt och ofta längre än nödvändigt, eller kortare än batteribudgeten tillåter.

Om kryptering. Port 1883 skickar data i klartext. Yggio accepterar också TLS, men att installera ett certifikat på en resursbegränsad enhet är betydligt mer involverat än resten av den här proceduren, och alla enheter hanterar det inte väl. Fatta ett medvetet beslut: för en publik badvattentemperatur kan det vara en rimlig avvägning, och för något personligt eller verksamhetskritiskt är det inte det.

Steg 7: Bekräfta att datan kom fram

Utlös en sändning, antingen genom att starta om enheten, bryta strömmen, eller hålla in knappen tills indikatorn bekräftar.

Återanslut till konsolen omedelbart och titta i loggen. En lyckad sändning namnger varje steg, så du ser hur långt den kom: adressen som slås upp, anslutningen som öppnas, inloggningen som lyckas, publiceringen som slutförs.

I Yggio dyker nu en enhet upp under det reserverade topicet, av typen Generic. Döp om den till något begripligt; topicet ligger kvar som det är.

Se den komma in med MQTT Explorer

Innan du bestämmer att något är fel, anslut MQTT Explorer till Yggios broker och prenumerera på ditt topic, med samma credential set som enheten använder. Då ser du meddelandet landa hos brokern i samma ögonblick det kommer, vilket berättar exakt var kedjan tar slut:

• Ingenting i MQTT Explorer, och ingenting i enhetens logg heller, betyder att enheten inte publicerar. Felet ligger på enheten eller i nätet.
• Ingenting i MQTT Explorer, men enhetens logg påstår att publiceringen lyckades, betyder att den publicerar någon annanstans än där du lyssnar. Jämför topic och inloggningsuppgifter tecken för tecken.
• Meddelandet syns i MQTT Explorer men ingen enhet dyker upp i Yggio. Nu ligger felet på Yggio-sidan, och det är den punkt där supporten kan hjälpa.

Det sista fallet är det enda där vi kan göra något användbart för dig, så det är värt att nå fram dit innan du skapar ett ärende. Allt före det löses snabbare med enhetens manual, SIM-leverantörens portal och Felsökning av NB-IoT.

Steg 8: Avkoda payloaden

Enheten levererar nu sina egna fältnamn och sina egna konventioner, och det är där en translator kommer in. Två saker är oftast värda att göra även för en enkel sensor.

Den första är att mappa tillverkarens fält till det namn Yggio förväntar sig. En enhet med flera ingångar numrerar dem ofta i stället för att använda namnet Yggio letar efter, så ingen av dem känns igen som en temperatur. Att kopiera den som används till temperature gör att den syns i förhandsgranskningar, vyer och diagram som vilken enhet som helst. På en Dragino D20S-NB eller D23-NB heter de tre ingångarna temperature1, temperature2 och temperature3.

Den andra är att hantera värdet en enhet skickar när en givare saknas. Många rapporterar ett fast värde utanför mätområdet i stället för ingenting alls, vilket sedan flyter in i diagram och medelvärden som om det vore verkligt. Läs i manualen vad din enhet skickar. En translator kan i stället göra om det till en uttrycklig status:

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'
    }
  };
}

Ett rimligt giltigt intervall skyddar också mot orimliga avläsningar från en sensor som någon har manipulerat, flyttat inomhus eller lämnat i solen.

För att skriva och ladda upp translatorer, se Translatorutveckling.

Genomarbetat exempel: en Dragino D20S eller D23-NB

De här sensorerna använder en vanlig NB-IoT-modul och konfigureras över Bluetooth med tillverkarens app. Konsolens PIN-kod är tryckt på förpackningen, och enheten annonserar sig under sitt IMEI.

Kommandona nedan är de som krävs för att ta en okonfigurerad enhet till data i Yggio, i den ordning de används. Tillverkaren dokumenterar hela kommandouppsättningen i Draginos wiki för NB-IoT-konfiguration, som är referensen för allt utöver den här sekvensen.

Vinkelparenteser markerar de enda värden du behöver byta ut. Allt annat skrivs in exakt som det står.

Del 1: kom ut på mobilnätet

Anslut över Bluetooth, ange PIN-koden och sedan:

AT+CFG
AT+APN=<apn från din SIM-leverantör>

AT+CFG skriver ut aktuell konfiguration, vilket bekräftar att konsolen tar emot kommandon. AT+APN är den inställning som alltid krävs.

På många nät räcker det. Där det inte gör det, begränsa modemets sökning i stället för att låta det skanna allt:

AT+QBAND=2,8,20
AT+CSQTIME=10
AT+COPS=1,2,"<operatörskod>"

• AT+QBAND=2,8,20 söker två band, 8 och 20, i den ordningen. Den inledande 2 är antalet, inte ett band.
• AT+CSQTIME=10 ger tio minuter att ansluta i stället för att ge upp tidigare.
• AT+COPS=1,2,"<operatörskod>" väljer en operatör manuellt i stället för automatiskt. 1 betyder manuellt, 2 betyder att koden är numerisk, och själva koden är landskoden följd av nätkoden, till exempel 24001. Din operatör publicerar sin.

Titta på konsolen. Så länge den skriver signalstyrka 99 har modemet inte anslutit. När den siffran ändras har det gjort det, och först då är det värt att gå vidare.

Del 2: rikta den mot Yggio över MQTT

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

• AT+CLOCKLOG=1,65535,0,0 ger en platt JSON-payload, utan de arrayer Yggio inte läser.
• AT+PRO=3,5 väljer MQTT som protokoll och JSON som payloadformat.
• ATZ startar om enheten. Protokolländringen får inte effekt förrän den gjort det.

Återanslut efter omstarten och skriv sedan in anslutningsuppgifterna:

AT+PUBTOPIC=yggio/generic/v2/<ditt enhets-id>
AT+SUBTOPIC=yggio/generic/v2/<ditt enhets-id>/subtopic
AT+SERVADDR=beta.yggio.net,1883
AT+CLIENT=<credential set id>
AT+UNAME=<credential set användarnamn>
AT+PWD=<credential set lösenord>
AT+TDC=3600
ATZ

• AT+PUBTOPIC måste exakt matcha det reserverade topicet från steg 2.
• AT+SUBTOPIC måste vara publiceringstopicet med /subtopic tillagt. Ingenting skickas någonsin tillbaka på det, men att lämna det tomt eller sätta det lika med publiceringstopicet gör att enheten slutar svara.
• AT+SERVADDR tar värdnamn och port. 1883 är okrypterad.
• AT+CLIENT är _id från credential set i steg 1, inte dess användarnamn.
• AT+TDC=3600 rapporterar varje timme. Fabriksinställningen är ofta 7200, alltså varannan timme.
• Den avslutande ATZ startar om enheten, vilket utlöser en sändning.

Återanslut omedelbart och titta i loggen. En fungerande enhet namnger varje steg när den passerar det: adressen som slås upp, anslutningen som öppnas, inloggningen som lyckas, publiceringen som slutförs.

Två egenheter att känna till i förväg

Kravet på prenumerationstopicet ovan är den första, och den är lätt att förlora en eftermiddag på, eftersom enheten helt enkelt slutar svara.

Den andra är att en ingång utan givare rapporterar -409.5, vilket ligger under absoluta nollpunkten och därför är ett markörvärde snarare än en avläsning. De tre ingångarna heter temperature1, temperature2 och temperature3, så det är en translator som gör om den du använder till temperature och markörvärdet till en status.

För allt som är bekräftat på den här hårdvaran, se enhetsspecifikt beteende.

Vart du går härnäst

• Felsökning av NB-IoT när ett steg inte beter sig.
• IoT-noder och nätverksprotokoll för den generiska enhetstypen och de övriga protokoll den tar emot.
• Nätverkstekniker för hur NB-IoT står sig mot alternativen.
• Sensative support om du kör fast på Yggio-sidan.