Node Red

Introduktion

Node-RED sticker ut som ett exceptionellt flödesbaserat programmeringsverktyg som sömlöst kopplar samman hårdvaruenheter, API och onlinetjänster. Använt tillsammans med Yggio, tjänar Node-RED flera viktiga syften::

• Fungerar som ett mjukvaruutvecklingskit för att skapa och validera Yggio-översättare och Flow-komponenter.
• Tjänar som ett simuleringsverktyg, vilket underlättar utbyte av data med Yggio för att utforska olika scenarier.
• Tillhandahåller ett verifieringsverktyg för att simulera olika integrationsmetoder och protokoll, vilket förenklar acceptanstestning för nya Yggio-programvaruversioner.
• Fungerar som ett integrationsverktyg, vilket möjliggör anslutningar till olika tredjepartstjänster och system.

Node-RED har dock sina begränsningar. Det kräver färdighet i JavaScript-programmering och fungerar endast för en användare, vilket gör att det saknar skalbarhet. Dessutom erbjuder det endast grundläggande skydd mot obehörig åtkomst genom en enkel inloggningsskärm, vilket kräver strikt brandväggsskydd.

Kom igång

För att integrera Node-RED med Yggio, börja med att installera Node-RED på en lämplig dator eller server enligt instruktionerna på Node-REDs webbplats. Det enklaste sättet är att använda de standardiserade nätverksmodulerna "MQTT IN" och "MQTT OUT" för att koppla till Yggios MQTT-mäklare för datautbyte. Därifrån kan användare snabbt skapa flöden och instrumentpaneler, samt simulera datamängder. Alternativt kräver användning av Yggios REST API för datainteraktion i Node-RED en mer avancerad programmeringskunskap.

För en snabb start, importera följande exempel på Node-RED-flöde till din Node-RED-installation:

Node-RED Exempel Flow JSON

Exempelflödet visar hur man använder MQTT för att publicera simulerad data och prenumerera på den från Yggios MQTT-mäklare. Dessutom inkluderar det ett exempel på hur man loggar in med Yggios REST API, sparar en token och utför en GET-förfrågan till /iotnodes och en tidsserie.

Gör följande konfigurationer i Yggio:

1. Gå till Yggio Swagger.
2. Hämta en giltig Yggio-token genom att navigera till /auth/local-endpointen. Klicka på 'Try it out,' ange ditt Yggio-användarnamn och lösenord, klicka på 'Execute,' och kopiera svarstoken till ditt urklipp.
3. Klicka på den gröna 'Authorize'-knappen uppe till höger, klistra in token i textrutan och klicka på 'Authorize.' Du är nu inloggad i Yggio API i Swagger och kan testa alla APIer.
4. Gå till /basicCredentialSet-endpointen och skapa en grundläggande autentiseringssats med ett lämpligt starkt användarnamn och lösenord.
5. Gå till /reservedMqttTopic-endpointen, använd basicCredentialSet och reservera 6 olika ämnen för 6 IoT-noder i Yggio. Ämnet måste följa strukturen: yggio/generic/v2/[youruniquedeviceid]

Gör följande konfigurationer i Node-RED:

1. Importera exempelflödet.
2. I den övre vänstra 'Start'-noden, uppdatera användarnamnet och lösenordet så att de matchar dina Yggio-uppgifter för att möjliggöra användningen av REST API.
3. I en av MQTT-utgångsnoderna som representerar Yggio-enheter, lägg till en ny MQTT-server med samma URL som Yggio-URL, och ange ditt användarnamn och lösenord i 'Säkerhets'-sektionen.
4. Lägg till ämnet för enhet 1 som skapades i steg 5 ovan.
5. Upprepa ovanstående steg för de återstående 5 MQTT-utgångsnoderna, och använd den MQTT-server som skapades tidigare.

Du kan nu ladda flödet och testa REST API-integrationen med GET /iotnodes genom att klicka på startknappen uppe till vänster. Du kommer att få ett felmeddelande från tidsseriedata, men bortse från det för tillfället. Om du går tillbaka till ditt Yggio-konto, bör det nu finnas en MQTT-nod som tar emot simulerad data med jämna mellanrum.

Gör den slutgiltiga konfigurationen för att få tvåvägskommunikation:

1. Gå till ditt Yggio-konto och klicka på den nya MQTT-noden.
2. Gå till fliken 'Kanaler' och skapa en ny MQTT-kanal. Välj kanaltypen basicCredentialSet och hänvisa till basicCredentialSetId som skapades tidigare.
3. Kopiera det kompletta ämnet från MQTT-kanalen till urklipp.
4. Återvänd till Node-RED, leta upp noden med namnet Device1-FromYggio och klicka på den. Detta är en MQTT in-nod.
5. Välj din befintliga MQTT-server och klistra in ämnet som kopierats från Yggio i ämnesfältet.
6. För att få tidsserien API-anropet att fungera, uppdatera IoT-nodens id i den lägre av de två 'Prepare API call' till _id i fliken 'Allmänt' i enhetslistan för din nya MQTT-nod.

Konfigurationen är nu klar, och du kan ladda upp den. Inom 1 minut kommer ytterligare 5 MQTT IoT-noder att skapas i Yggio. Du kan observera data som genereras i Node-RED, skickas till Yggio genom att publicera den på Yggios MQTT-mäklare, därefter prenumereras den på av Node-RED från Yggios MQTT-mäklare, för att sedan igen publiceras på Yggios MQTT-mäklare med en fördröjning på några sekunder. Du kommer också att se att tidsserie APIet nu börjar fungera.

För att se simulationen i aktion, gå till Enhetslistan i Yggio. Använd 'Välj många' för att markera de nya MQTT-noderna, gå till 'Charts' och undersök de olika fälten från simulationen. Med Node-RED och vissa tekniska JavaScript-programmeringskunskaper kan du snabbt integrera Yggio med olika system, skapa och verifiera Yggio-översättare samt utveckla Yggio Flow-komponenter. Du kan också importera denna snygga vyn till enhetslistan för att se den fungera i realtid:: Node-RED Device view.txt

Skapa Yggio översättare med Node-RED

Grunderna

Node-RED är ett utmärkt val att använda som ett programutvecklingskit (SDK) för att skapa Yggio-översättare och hantera komplexa dataflöden. Eftersom Node-RED är byggt på Node.js, precis som Yggio, använder båda plattformarna samma JavaScript-motor. Denna kompatibilitet säkerställer att en översättare som fungerar korrekt i en simulerad Node-RED-miljö och följer strikt JavaScript-syntax också kommer att prestera bra när den laddas upp till Yggio via översättar-API i Swagger.

Börja utveckla

Node-RED my first translator JSON

Importera flödet ovan till Node-RED. Det består av:

1. En injektor nod.
2. En funktionsnod som genererar simulerade data.
3. En funktionsnod som implementerar en översättare och returnerar resultatet.
4. En felsökningsnod för att göra datan synlig.
5. Ett flöde för att omvandla översättaren och specifikationen till en sträng, vilket skrivs ut i Node-RED-konsolloggen.
6. En specifikation som beskriver översättaren och dess utdata. Utdata-specifikationen för fältnamn och datatyper måste exakt matcha utdata från översättaren, annars kommer utdata-validering att misslyckas och inget resultat kommer att vara tillgängligt.

Detta enkla exempel demonstrerar en fungerande översättare som kan laddas upp till Yggio via API och anslutas till vilken enhet som helst som tillhandahåller fälten 'rssi' och 'snr'. Översättaren beräknar ett giltigt signalstyrkevärde, vilket är summan av 'rssi' och 'snr' om 'snr' är mindre än noll; annars använder den bara 'rssi'. Specifikationen som definierar utdatavärdena från översättaren måste matcha översättarens resultat exakt; avvikelse kommer att orsaka att valideringen misslyckas och översättarens resultat kommer att kasseras. Specifikationen fungerar som en överenskommelse med slutanvändaren om vilken data översättaren tillhandahåller. Om en översättare behöver tillhandahålla dynamiska resultat, lagra dem i ett JSON-objekt.

Hårdvaruavkodare

Med Node-RED är det vanligtvis snabbt och enkelt att integrera och verifiera en ny översättare i Yggio om tillverkaren har tillhandahållit en referens till JavaScript-dekoder. Samma översättningsflöde som beskrivs ovan används, där tillverkarens dekoder är innesluten inuti översättningsfunktionen, och den hexadecimala datan som ska avkodas överförs till den. Den standardiserade kodstrukturen ser ut som exemplet nedan, där funktionen 'rawTranslate' är tillverkarens dekoder:

function translate ({encodedData}) {
  const {hexEncoded, port} = encodedData;

  if (!hexEncoded || !port) {
    throw new Error('Expected fields hexEncoded and/or port are missing');
  }

  const decoded = rawTanslate({hexEncoded, port});

  return {
    result: decoded
  };
}

För att verifiera översättaren behöver du verkliga datastrukturer och förväntade resultat för varje datastruktur. Tillverkare brukar vanligtvis tillhandahålla exempel som kan användas för att skapa simulerade data för översättaren. Alternativt kan du distribuera en verklig enhet i Yggio och använda de datastrukturer som tas emot av Yggio som simulerad data för översättaren.

Om ingen referensdekoder är tillgänglig från tillverkaren blir uppgiften att skriva en dekoder mycket större och kan ta allt från några timmar till veckor att utveckla. Denna process innebär ofta komplex hantering av bitar och bytes, och olika datastrukturer kommer att behövas för att uppnå en tillfredsställande nivå av verifiering.

Dataflöden

Modellen för Yggio-översättare möjliggör för en översättare att skicka översättningsresultat till andra IoT-noder via 'additionalDeviceUpdates', förutsatt att alla administratörer för en enhet har skrivåtkomst till målnoden. Denna funktion gör det möjligt att hantera mycket komplexa användningsfall och visualisera berikad data i realtid, eftersom målnoderna dynamiskt kan bestämmas beroende på översättningen. Yggio stöder även atomiska uppdateringar av aggregeringsnoder genom delta uppdateringar, vilket säkerställer att oavsett i vilken ordning data anländer, kommer resultatet alltid att vara korrekt. Eftersom Node-RED stöder skapandet av flöden, även om inte dynamiskt som Yggio, är det ett utmärkt verktyg för att utveckla och verifiera översättare som implementerar komplexa och dynamiska dataflöden.

Principen för att sätta upp simuleringar av dataflöden

1. Utveckla översättarna med 'additionalDeviceUpdates' med den standardmetod som beskrivs ovan, genom att simulera förväntad indatadata och vidarebefordra den till översättarna.
2. När översättaren är klar, ladda upp den till Yggio via översättar-API.
3. Kopiera det ursprungliga flödesexemplet som beskrivs längst upp på denna sida och lägg till den nyutvecklade översättaren till MQTT-noderna.
4. Skapa eventuellt nödvändiga 'Generiska noder' som kan användas för att dela data.
5. Injicera data med Node-RED i simuleringen via Yggios MQTT-mäklare. Skapa vid behov flera noder med översättaren och verifiera alla förväntade beteenden.
6. Prenumerera på data från MQTT-noder och använd den för att utveckla eventuellt ytterligare krävda översättare för att hantera det kompletta dataflödet.
7. En nyckelfråga är att "additionalDeviceUpdates" behöver identifieraren för målnoden, ett enkelt sätt att göra identifieraren konfigurerbar är att använda contextMap.

Exempel på additionalDeviceUpdates:

function translate(iotnode) {
  const log = _.get(iotnode, 'log');
  const measurementFields = _.get(iotnode, 'contextMap.measurementFields','').split(',');
  const additionalDevice = _.get(iotnode,'contextMap.targetNodeSecret');
  const sourceDevice = _.get(iotnode,'name','unknown').replace(/\W/g, '-');
  let measurements = {};
  let result = {};

    // Transfer selected measurement fields to target node
  if (additionalDevice != undefined && measurementFields != undefined) {
    for (let i = 0; i < measurementFields.length; i++) {
      measurements[measurementFields[i]] = { [sourceDevice]: _.get(iotnode, measurementFields[i]) };
    }
    if (log != undefined && log.message != '')
      result = {
        ...result,
        'log': {
          'message': '',
          'type': '',
          'priority': '',
          'category': ''
        }
      };
  }
  else if (log == undefined || log.message == '')
    result = {
      'log': {
        'message': 'At least one of the 2 fields targetNodeSecret or measurementFields are missing in the contextMap.',
        'type': 'Error',
        'priority': 'Low',
        'category': 'Status'
      }
    }
    return {
      result,
      additionalDeviceUpdates:
        [{
          identifier: {
            secret: additionalDevice
          },
          result: { measurements }
        }],
    };
  }

Felsökning

Om din översättare fungerar felfritt i Node-RED-simuleringen men ingenting verkar hända när den laddas upp till Yggio, kan du vara osäker på vad du ska göra härnäst. Det finns tre potentiella typer av problem som kan orsaka detta:

1. Validering av översättarutdata mot specifikationen misslyckas, detta är den vanligaste orsaken och det är lätt att missa. Se till att:

• Granska alla möjliga utdatafält och deras datatyper, säkerställa en 100% matchning mot specifikationen, inklusive skiftläge för varje enskild tecken.
• Använd funktioner som Number(), String() och Array.isArray(myArray) för att tvinga fram datatyper och förhindra inkonsekvenser i datatyper.

2. Översättaren kraschar under utförandet: Om översättaren kraschar beror det troligen på inkorrekt hantering av datainmatningskombinationer. Den vanligaste orsaken är försök att tilldela eller referera till en obestämd variabel.

• Kopiera indata som skickas till översättaren från Yggio och lägg till den i din Node-RED-simulering. Detta kommer att visa om översättaren kraschar eller inte.

3. Översättaren misslyckas med att kompilera i Yggio: Om översättaren misslyckas med att kompilera i Yggio kan problemet vara relaterat till saknade semikolon eller andra kodproblem efter strängifiering.

• För att åtgärda detta, kör koden genom linters för att kontrollera om den är giltig JavaScript och JSON. Det finns gott om online JavaScript-validerare tillgängliga genom att söka på "Javascript online linter validation"."