Batchinstallation

Batchinstallation lägger till många enheter i plattformen samtidigt från en CSV-fil. En guide går igenom de inställningar som är lika för alla enheter, och CSV-filen bär det som skiljer sig per enhet.

Den uppdaterar också enheter som redan finns. Att köra en CSV-fil igen är det normala sättet att rätta en installation: korrigera metadatan i filen och kör den igen, och de fält du ändrade uppdateras på enheterna. Se Uppdatera befintliga enheter.

Guiden

Guiden har upp till sju steg. Vilka som visas beror på enhetstypen: steget Connector visas bara för LoRaWAN, och stegen Device Model och Translators visas inte för connector-enhetstyper.

Steg	Vad det sätter	Gäller
Device Type	type	Varje rad
Connector	connector, och LoRaWAN-fälten för den connectorn	Varje rad
Device Model	deviceModelName	Varje rad
Translators	Översättarna, deras versioner, uppgraderingspolicyer och parametrar	Varje rad
Upload File	Ingenting - här läggs CSV-filen in	-
Start Installation	Ingenting - visar antalet enheter och startar jobbet	-
Result	Ingenting - vad som lyckades och vad som misslyckades	-

Två knappar låter dig lämna ett steg osatt:

• Skip hoppar över just det steget. Fältet sätts då inte för någon rad, så CSV-filen måste tillhandahålla det.
• Skip until upload file hoppar över alla återstående steg i guiden och går direkt till CSV-filen. Använd den när filen redan innehåller allt.

Fält som guiden sätter

Detta är hela uppsättningen fält som guiden kan sätta på varje rad.

Steg	Fält
Device Type	type
Connector	connector, activationType, appEUI, classType, deviceProfileId, connectivityPlanId, priceModelMessagesCountTypesCompositeCode, lorawanVersionTypeCompositeCode, externalJoinServerEUI, processingStrategyId, domains, routeRefs, frequencyPlanId, loraWANVersion, loraWANPHYVersion
Device Model	deviceModelName
Translators	translatorPreferences, byggt från de översättare du väljer

CSV-filen har företräde framför guiden

Ett värde i CSV-filen vinner över samma värde satt i guiden. Guiden är ett standardvärde för varje rad; där en rad säger något annat används raden. Du kan alltså sätta en översättare i guiden för hela batchen och ändå ge tjugo av raderna en annan översättare i filen.

Per fält:

Fält	Om CSV-raden har det
type	Raden vinner. Guidens enhetstyp används bara där kolumnen saknas eller är tom
deviceModelName	Raden vinner, samma regel
Översättare (translatorXName med flera)	Raden vinner. En rad med ett översättarnamn behåller sina egna översättare, och guidens val läggs inte till på den
contextMap, name, description och allt annat	Bara CSV-filen sätter dessa; guiden har inget fält för dem

Steget Connector är undantaget

Värden från steget Connector följer inte regeln ovan: de skrivs över raden. Sätter du en connector i guiden ersätter den connectorn vad kolumnen connector än säger, och varje connector-fält du fyllt i ersätter också den kolumnen. Fält du lämnade tomma i guiden rörs inte, så CSV-filen tillhandahåller fortfarande dem.

Om din CSV-fil bär connector-värden per rad ska du hoppa över steget Connector i stället för att fylla i det, annars förkastas filens värden.

För Actility / Netmore ThingPark kan guiden härleda enhetsprofilen. När både LoRaWAN-versionen och klasstypen är satta kombineras de till deviceProfileId och de två källfälten tas bort, så du behöver inte leta upp profilen.

Installera enheter steg för steg

1. Öppna fliken Enheter, klicka sedan på "New device".

2. Tryck på "Batch mode".

3. Device Type - välj typen av enhet du installerar, sedan Continue.

4. Connector (endast LoRaWAN) - välj connector och, där connectorn behöver dem, LoRaWAN-inställningarna och enhetsprofilen. Att sätta dem här en gång undviker felmatchade värden för connector och enhetsprofil utspridda över filen.

   

   För vissa connector-typer hämtar guiden även värden specifika för den connectorn, till exempel connectivity plans, och listar respektive namn bredvid dess ID. Använd det ID:t i motsvarande CSV-kolumn, till exempel connectivityPlanId för Actility / Netmore ThingPark. Om inga hittas, eller om förfrågan misslyckas, visar guiden ett meddelande i stället för listan.

5. Device Model - ange enhetens modellnamn. Det identifierar enheten och är det som föreslår en lämplig översättare.

6. Translators - välj översättaren som ska användas för batchen, med version, uppgraderingspolicy och eventuella parametrar. Se Översättare nedan.

7. Upload File - dra CSV-filen till rutan, eller tryck på rutan och välj filen. Se Referens för CSV-filen.

8. Start Installation - kontrollera antalet enheter och starta sedan. När installationen har startat kan den inte stoppas.

9. Result - bekräfta vad som installerades, och se vad som misslyckades och varför.

Uppdatera befintliga enheter

Batchinstallation skapar inte bara. Att köra en fil igen uppdaterar de enheter den refererar till, vilket gör den till det snabbaste sättet att reparera en installation:

• Du installerade en batch och upptäckte sedan att metadatan var fel, eller att ett fält saknades.
• Redigera den kolumnen i samma CSV-fil och kör batchinstallationen igen.
• De fält som finns i filen uppdateras på enheterna. Kolumner du inte rörde lämnas som de är.

Behåll filen du installerade med. Den är både dokumentationen av installationen och verktyget för att rätta den.

För att uppdatera enheter du inte installerade från en fil, eller för att byta namn i bulk, använd Batchuppdatering i stället. Den arbetar från en export av de enheter du vill ändra.

När du har gått igenom guiden och laddat upp din CSV-fil kontrolleras filen och antalet enheter som hittades visas. Tryck på "Continue", sedan "Start Installation", och alla enheter installeras och provisioneras automatiskt.

Referens för CSV-filen

Filen måste vara en korrekt formaterad CSV-fil.

Olika enhetstyper behöver olika uppsättningar kolumner. Tabellerna nedan listar vad varje typ och varje nätverksserver förväntar sig.

Den här referensen gäller även Batchuppdatering. Båda funktionerna läser samma slags CSV, med samma avgränsare, samma filkodningar och samma regler om fältnamn. Batchuppdatering arbetar från en export av enheter som redan finns, så vilka kolumner den bryr sig om skiljer sig. Formateringsreglerna nedan är samma i båda.

Formateringsregler

• Avgränsare: komma eller semikolon. Båda accepteras.

• Omgivande blanksteg i värden trimmas bort.

• Filkodning: UTF-8, UTF-8 med byte order mark, UTF-16 med byte order mark samt Windows-1252 / ISO-8859-1 läses alla korrekt. Å, ä och ö klarar sig vilken av dessa ditt kalkylprogram än sparade, vilket spelar roll eftersom Excel med svensk eller Windows-locale ofta exporterar Windows-1252 i stället för UTF-8. När det inte finns någon byte order mark läses filen som UTF-8 och faller tillbaka på Windows-1252 om de byten inte är giltig UTF-8. Om du kan välja, spara som UTF-8: detekteringen är bara en heuristik, och UTF-16 utan byte order mark upptäcks inte.

• Fältnamn: skriv dem exakt som de står i tabellerna nedan. En felstavad eller felaktigt skiftlägessatt rubrik rapporteras inte som ett fel. Kolumnen behandlas som ett nytt fält och sparas under det namnet, så värdet hamnar tyst inte där du menade.

  Det finns en enda snäv tolerans. Plattformen skiftlägeskorrigerar en rubrik bara när hela rubriken matchar ett av de enkla fältnamn den känner: name, description, type, deviceModelName, connector, contextMap, secret, activationType, devEui, devAddr, appKey, appEUI, nwkSKey, appSKey, classType, deviceProfileId, connectivityPlanId, priceModelMessagesCountTypesCompositeCode, lorawanVersionTypeCompositeCode, externalJoinServer, externalJoinServerEUI, frequencyPlanId, loraWANVersion och loraWANPHYVersion. För dessa blir både devEUI och deveui till devEui.

  Allt annat är skiftlägeskänsligt, inklusive:

  • översättarkolumnerna - translator1Name, translator1Version, translator1UpgradePolicy och translator1.[fieldname] måste vara exakta
  • allt efter en punkt - bara delen före den första punkten korrigeras någonsin, så contextMap.installedBy behåller installedBy ordagrant
  • enhetens identifieringsfält i Enhetsidentifierare, som imei, sensorId, serialNumber, meterId, gatewayEui, wMbusDeviceId och macAdress
  • dina egna namn på kontextuella parametrar och översättarparametrar

  Vid tvekan: kopiera namnet ur tabellen i stället för att skriva det.

• Tal i översättarparametrar: ett värde i translatorX.[fieldname] som ser ut som ett tal sparas som ett tal i stället för som text.

• Äldre översättarkolumner i den gamla formen translatorPreferences.0... avvisas med ett fel. Använd den korta formen translatorXName nedan.

• Om du är osäker på om din data är giltig, kör en batch med ett par rader innan du kör hela filen.

Vanliga fält

Allmänt

Fält	Beskrivning
name	Enhetens namn
description	Fritextbeskrivning
type	Enhetstypen. Sätts av guidens steg Device Type där kolumnen saknas
deviceModelName	Används för att identifiera en översättare. Sätts av guidens steg Device Model där kolumnen saknas
connector	ID:t för önskad connector. Använd Connector helper tool, eller sätt den i guidens steg Connector
contextMap	Lägger till kontextuella parametrar. Se Kontextuella parametrar
translatorXName med flera	Tilldelar översättare. Se Översättare

LoRaWAN OTAA - Over the air activation

Fält	Beskrivning
activationType	OTAA, för ABP se tabellen längre ner
devEui	DevEUI, enhetens 64-bitars globalt unika identifierare, tilldelad av tillverkaren och tryckt på enheten. Den ändras aldrig, och det är den som LoRaWAN-servern känner enheten genom
appKey	Krypteringsnyckel, kallas appKey eller nwkKey beroende på tillverkare
appEUI	AppEUI, även kallad JoinEUI, 64-bitars identifierare för den join-server enheten ansluter genom. Krävs inte av ChirpStack

LoRaWAN ABP - Activation by personalisation

Fält	Beskrivning
activationType	ABP
devEui	DevEUI, enhetens 64-bitars globalt unika identifierare, som ovan
devAddr	DevAddr, enhetens 32-bitars adress på det här nätverket. Till skillnad från DevEUI är den inte globalt unik och den tillhör nätverket snarare än enheten: med OTAA tilldelar servern den under anslutningen, och med ABP sätter du den själv, vilket är varför den bara listas här
nwkSKey	Network session key, används för integritetskontrollen av meddelanden mellan enheten och nätverksservern
appSKey	Application session key, används för att kryptera nyttolasten mellan enheten och applikationen
appEUI	AppEUI / JoinEUI, som ovan. Krävs inte av ChirpStack

Generic

Fält	Beskrivning
secret	Identifieraren som enheten själv lägger i sin nyttolast eller URL så att Yggio vet vilken enhet som skickade datan. Minst 8 tecken. Välj den själv och konfigurera samma värde på enheten

Enhetsidentifierare

Varje enhet behöver något som identifierar den när data kommer in, och vilket fält det är beror på hur enheten når Yggio. Detta är de fält Yggio matchar inkommande data mot. Använd det som hör till din enhetstyp; en enhet behöver inte mer än ett.

Fält	Identifierar
secret	Generiska enheter, över HTTP, MQTT, CoAP eller UDP. Minst 8 tecken, valda av dig
devEui	LoRaWAN-enheter. Den 64-bitars tillverkartilldelade DevEUI:n
gatewayEui	LoRa-gateways. Gatewayens egen 64-bitars EUI
imei	SIM-baserade enheter, som Sodaq och andra NB-IoT- eller Cat-M-enheter. Modemets IMEI
serialNumber	Enheter som identifieras av sitt serienummer, som Celsiview
sensorId	Enheter vars nyttolast bär ett sensor-id, som IMBuildings över UDP
meterId	Mätarenheter
deviceIdentification	Elvaco CME-enheter. Åtta tecken eller färre
wMbusDeviceId	Wireless M-bus-enheter, tillsammans med manufacturer
manufacturer	Wireless M-bus-tillverkare: Easymeter (ESV), B Meters (BMT) eller Kamstrup (KAM)
bleAddress	BLE-enheter, via sin Bluetooth-adress
macAdress	Enheter som identifieras av MAC-adress. Stavas med ett d i plattformen, så använd den stavningen i kolumnen
nodeId	Z-Wave-noder, via nod-id
tag	Enheter som identifieras av ett tag-värde

Fält för nätverksservrar

ChirpStack

Fält	Beskrivning
deviceProfileId	ID:t för enhetsprofilen, kopiera från en befintlig enhets 'Data' -> 'Connectivity'

Netmore

Fält	Beskrivning
classType	A eller C
priceModelMessagesCountTypesCompositeCode	Använd Connector helper tool
lorawanVersionTypeCompositeCode	V100@SENSOR_COMMON, V101@SENSOR_COMMON, V102@SENSOR_COMMON, V103@SENSOR_COMMON eller V104@SENSOR_COMMON
externalJoinServer	true eller false. Sätt till true när enheten ansluter genom en join-server utanför Netmore
externalJoinServerEUI	Den 64-bitars EUI:n för den externa join-servern

Actility / Netmore ThingPark

Fält	Beskrivning
connectivityPlanId	Använd Connector helper tool
deviceProfileId	Kan vara vilken profil som stöds som helst. Vanliga är: LORA/GenericA.1.0.2a_ETSI_Rx2-SF12, LORA/GenericC.1.0.2a_ETSI_Rx2-SF12, LORA/GenericA.1.0.3a_ETSI, LORA/GenericC.1.0.3_ETSI, LORA/GenericA.1.0.4a_ETSI eller LORA/GenericC.1.0.4a_ETSI. Guiden kan härleda detta från LoRaWAN-versionen och klasstypen i stället

The Things Network

Fält	Beskrivning
frequencyPlanId	EU_863_870_TTN, US_902_928_FSB_2, AU_915_928_FSB_2, KR_920_923_TTN, AS_920_923
loraWANVersion	MAC_V1_0_0, MAC_V1_0_1, MAC_V1_0_2, MAC_V1_0_3, MAC_V1_0_4
loraWANPHYVersion	PHY_V1_0_2_REV_A, PHY_V1_0_2_REV_B, PHY_V1_0_3_REV_A, RP002_V1_0_0, RP002_V1_0_1, RP002_V1_0_2, RP002_V1_0_3, RP002_V1_0_4

Connector helper tool

I steget Upload File trycker du på "What should I put in the file?" för att öppna instruktionspanelen. Connector helper tool sitter längst ner i den.

Välj din connector i rullgardinsmenyn "Select connector" och dess ID visas nedanför. Det ID:t är värdet att använda i CSV-filens kolumn connector, vilket sparar dig från att leta upp det på annat håll.

Där connector-typen behöver mer än bara sitt ID listar verktyget även de värdena med respektive namn bredvid ID:t att lägga i filen - connectivity plans för Actility / Netmore ThingPark, till exempel, eller prismodeller för Netmore. Om inga hittas säger den det.

Översättare

Översättare är små program som avkodar eller omvandlar enhetsdata.

Välj en översättare

Enhetens modellnamn (Device model name) används för att rekommendera en lämplig översättare. Du kan dock välja vilken översättare du vill.

Flera översättare

Det är möjligt att ha flera översättare på en enhet. Översättarna "kedjas" då samman, vilket innebär att en översättare tar indata från de föregående översättarna såväl som från den ursprungliga enhetsdatan.

Versioner och uppgraderingspolicyer

En översättare kan ha många versioner. Du kan välja en version samt en uppgraderingspolicy, som avgör om en nyare version plockas upp automatiskt. Det finns fyra policyer:

Policy	Beteende
Inga uppgraderingar	Den valda versionen används alltid
Patch-uppgraderingar	Från 1.0.0 begränsas uppgraderingar till patch-utgåvor (1.0.x): endast buggfixar och säkerhetsuppdateringar
Minor-uppgraderingar	Från 1.0.0 begränsas uppgraderingar till minor- och patch-utgåvor (1.x). Kan innehålla nya funktioner, men bör förbli bakåtkompatibelt
Alla uppgraderingar	Innefattar automatiska uppgraderingar av major-version, som kan innehålla brytande ändringar. Aktivera bara detta om du kan verifiera uppdateringar i en kontrollerad miljö

En major-version betyder att översättarens datamodell har ändrats. När du själv byter version visar Yggio den gamla och den nya datamodellen sida vid sida och ber dig bekräfta - se Ändra major-version. En uppgraderingspolicy på Alla uppgraderingar passerar de gränserna automatiskt, utan att fråga, vilket är skälet till varningen i tabellen ovan.

Översättarkolumner i CSV-filen

Sätt översättare i guidens steg Translators för hela batchen, eller per enhet i CSV-filen. En rad som namnger en översättare behåller sina egna; guidens val läggs inte till ovanpå.

Fält	Beskrivning
translatorXName	Översättarens namn
translatorXVersion	Versionen av översättaren som ska användas. Om inget anges används den senaste versionen. Om version 1.x.x anges används den senaste versionen inom major-version 1.
translatorXUpgradePolicy	Uppgraderingspolicyn för denna översättare: - none - använd alltid den valda versionen - patch - t.ex. 1.0.0 → 1.0.x - minor - t.ex. 1.0.0 → 1.x - all - använd alltid den senaste versionen Standard är minor när kolumnen är tom eller värdet inte känns igen.
translatorX.[fieldname]	Används för att ange översättarparametrar. Lägg till en kolumn per parameter enligt mönstret translatorX.[fieldname], t.ex. translatorX.protocol. X är ett nummer från 1 till 4 (t.ex. translator1, translator2, translator3, translator4).

X är ett nummer från 1 till 4, så en enhet kan bära upp till fyra kedjade översättare. Dessa kolumnnamn är skiftlägeskänsliga; se Formateringsregler.

Använd translator1Name, translator1Version och translator1UpgradePolicy för att tilldela en översättare, och kolumnerna translator1.[fieldname] för att sätta dess parametrar. Upprepa med translator2, translator3 och translator4 för ytterligare översättare, som då kedjas samman.

name,translator1Name,translator1Version,translator1UpgradePolicy,translator1.protocol,translator2Name,translator3Name,translator4Name
MyDevice1,my-translator,1.0.0,minor,lorawan,my-other-translator,,
MyDevice2,my-translator,1.0.0,patch,lora,,,
MyDevice3,my-translator,1.x.x,,,,,
MyDevice4,my-translator,,minor,,my-2nd-translator,my-3rd-translator,my-4th-translator

För allt annat om översättare - katalogen, datamodellen, att skriva egna - se Översättare.

Kontextuella parametrar

Kontextuella parametrar är din egen metadata på en enhet: var den sitter, vem som installerade den, vad den hör till. Yggio tolkar dem inte, men de är sökbara och filtrerbara, de kan användas i vyer och egna frågor, och de är den vanliga platsen att dokumentera allt som enheten själv inte kan berätta.

Batchinstallation är det enklaste sättet att sätta dem, eftersom installationen är då du känner dem.

Kolumnen contextMap

Lägg till en kolumn per parameter, skriven i dot notation som contextMap.[namn]. Delen efter punkten är parameterns namn och tas exakt som du skriver det, så håll stavningen konsekvent mellan filer.

name,contextMap.placement,contextMap.installedBy
MyDevice1,floor,Markus
MyDevice2,roof,Sofia
MyDevice3,wall,Johan

Hur många parametrar som helst kan sättas på det här sättet.

Datatyper och hur du överstyr dem

Värden typas efter hur de ser ut. Ett värde som tolkas som JSON sparas som ett objekt eller en array, så {"floor":2} och [1,2,3] behåller sin struktur. Annars sparas ett numeriskt värde som ett tal, true och false som booleaner, och allt annat som text.

Det är oftast vad du vill, men det fångar också värden som bara ser numeriska ut: ett serienummer, ett rum som heter 0123, ett telefonnummer, ett postnummer med inledande nolla. Sparat som ett tal är den inledande nollan borta och värdet matchar inte längre vad som står tryckt på enheten.

Så när den uppladdade filen innehåller contextMap-kolumner visar steget Upload File en panel för contextMap-datatyper. Den listar varje parameter med ett exempelvärde ur din fil och den typ automatiken valde, samt en Force String-växel för att behålla kolumnen som text i stället.

Kontrollera kolumnen Auto type innan du fortsätter, och slå på Force String för allt som ska förbli text. I exemplet ovan lästes både Serienummer och Hårdvaruversion som tal, och en våning med värdet 0 likaså - alla tre är fall där du sannolikt vill bevara råtexten.

Kontextuella parametrar kan redigeras senare på enheten själv, eller i bulk med Select Many och Batchuppdatering. Att köra batchinstallationsfilen igen med en ändrad contextMap-kolumn uppdaterar dem också, som beskrivs under Uppdatera befintliga enheter.