Lektion 2.9 Extern datadelning

I denna lektion utforskar vi hur man delar data utanför plattformen. Det finns tre huvudsakliga metoder:

1. HTTP Generic Webhooks: Vid en uppdateringshändelse skickas inkommande data, delta och ändringar till en angiven HTTP-endpoint.
2. MQTT Generic: Data kan publiceras på plattformens egen MQTT-broker eller omformateras och skickas till en extern broker via en MQTT-connector.
3. Dedikerade connectors: Använd en connector för att skicka data direkt till externa tjänster, som fastighetsautomationssystem som Delta Controls EnteliWeb eller Siemens Desigo CC.

I denna lektion fokuserar vi på de två första metoderna, som kan användas direkt inom plattformen utan att behöva åtkomst till ett externt system.

För att övervaka datan som publiceras med MQTT rekommenderar vi att använda MQTT Explorer. Det är ett kraftfullt verktyg för att prenumerera på MQTT-topics och se exakt vilken data som publiceras och under vilket topic.

MQTT-datadelning

MQTT är ett flexibelt sätt att dela data, och det finns två huvudmetoder:

1. Publicera på plattformens MQTT-broker med hjälp av Channels, vilket gör att andra system kan prenumerera på datan.
2. Publicera direkt till ett externt systems MQTT-broker.

MQTT-kanaler

När du skapar en MQTT-kanal måste du bestämma hur prenumeranter ska autentisera sig. Det finns två alternativ:

• Basic Credential Set: Använder ett användarnamn och lösenord. Detta är den vanligaste och enklaste metoden.

  Säkerhetstips: Använd ett lösenord med minst 14 blandade tecken.

• API User Token: Använder en token från en Yggio API-användare. Tokens går ut periodvis och måste förnyas, vilket kan vara utmanande för externa system.

  Denna metod är den säkraste och följer standardflödet för OAuth. Den används i Yggio-gränssnittet för livedata via MQTT-websockets.

Skapa en Basic Credential Set

Det rekommenderas att återanvända den Basic Credential Set som skapades i föregående lektion. Om du inte har någon, följ denna guide för att skapa en ny.

1. Öppna Swagger-dokumentationen. Klicka på bokikonen i navigeringsfältet och sedan på Swagger. För att köra en endpoint, klicka på Try it out.

2. Autentiseringsalternativ:

   • Om du är inloggad via en extern IDP eller med MFA aktiverat fungerar inte /auth/local. Hämta istället din token från webbläsarens utvecklarverktyg:
     • Tryck på F12 för att öppna felsökningsfönstret.
     • Navigera till Application → Cookies eller Storage → Cookies.
     • Kopiera din token och använd knappen Authorize i Swagger. Klistra in token i dialogrutan.
   • Om du bara har ett lösenord, gå till /auth/local och ange ditt användarnamn och lösenord i de rätta fälten.

3. Kör /users/me för att verifiera din autentisering.

4. Gå till POST /basic-credentials-sets, ersätt platshållarna för användarnamn och lösenord med dina riktiga autentiseringsuppgifter, och klicka på Execute. Detta genererar en Basic Credential Set. Kopiera det returnerade _id från svaret:

{
  "_id": "123456789abcdef",
  "username": "My_basicCredentialsSet_Name"
}

5. Gå till enheten du vill övervaka, eller välj flera enheter med Select Many. Öppna Channels och fyll i formuläret:
   • Ge kanalen ett beskrivande Name.
   • I fältet Recipient, klistra in din Basic Credential Set _id (använd endast bokstäver och siffror, inga citattecken).
   • All inkommande data från dessa enheter kommer nu att publiceras på plattformens MQTT-broker, vilket gör att externa system kan prenumerera och ta emot datan.

Kontrollera din kanaldata

För att se datan som publiceras på din kanal, använder vi MQTT Explorer.

1. Sätt upp din MQTT-anslutning i MQTT Explorer:
   • Uppdatera plattforms-URL:en så att den matchar din instans.
   • Ange dina MQTT-autentiseringsuppgifter.
   • Ställ in porten till 8883 och aktivera Validate certificate och Encryption.

2. Klicka på Advanced, ta bort standard-root-topicet (#) och systemtopicet ($SYS#), lägg sedan till ditt specifika topic. Detta måste göras, annars kommer plattformen att avvisa din anslutning.

3. Lägg till ditt topic att prenumerera på, det bör följa detta format: yggio/output/v2/[Ditt Basic Credential Set ID]/iotnode/#

4. Klicka på Connect. Du bör nu se data som publiceras av plattformen. Se till att din enhet får en upplänk för att se data.

Använd en MQTT-connector för att publicera på en extern tjänst

I föregående Lektion 2.8: Connectors skapade vi en MQTT-connector för att publicera på en extern tjänst och riktade den till ett inkommande topic på plattformens MQTT-broker.

5. För att övervaka datan du publicerar via MQTT-connectorn, konfigurera MQTT Explorer att prenumerera på den.

• Om du använder en ny basicCredentialSet behöver du sätta upp en ny anslutning genom att upprepa stegen ovan.
• När autentiseringsuppgifterna stämmer, lägg till ditt reserverade topic från föregående lektion: yggio/generic/v2/[Ditt reserverade topic]
• Gå tillbaka till Användarguide: MQTT-connector och följ alla steg i Publishing Data with the Generic MQTT Connector för att sätta upp en regel som publicerar data.

6. Klicka på Connect igen. Du kommer nu att se både datan du prenumererar på och datan du publicerar.

7. När allt fungerar, spara din anslutning för framtida användning.

Observera: För att detta exempel ska fungera måste både publicerad och prenumererad data använda samma MQTT-autentiseringsuppgifter. Om du använder olika autentiseringsuppgifter behöver du skapa separata anslutningar i MQTT Explorer.

Denna lektion är mycket praktisk, eftersom det finns många kommersiella scenarier där det är nödvändigt att använda en MQTT-connector-antingen för att publicera data till externa brokrar eller till ett inkommande topic på plattformens MQTT-broker.

HTTP-webhooks datadelning

HTTP-webhooks är enklare än MQTT, skapa bara kanaler på enheten och ange önskad URL-destination. Eventuella autentiseringsuppgifter eller API-nycklar bör läggas till inuti HTTP-URL:en som headers.

Connectors datadelning

Kanaler kan också använda connectors från vissa tjänster, hur kanalen konfigureras beror då på det externa systemet. Till exempel kräver kanalen Delta Control Enteliweb en Bacnet-konfiguration. Den ser vanligtvis ut så här:

[
  {
    "sourceField": "alarmFloodNumber",
    "deviceNumber": 125,
    "objectType": "binary-value",
    "instance": "810",
    "propertyName": "present-value",
    "createMissing": true,
    "objectName": "Washroom-11223344",
    "priority": "1",
    "dataType": "Boolean"
  }
]

Fråga

Hur prenumererar man effektivt på flera iotnodes?

Svar

Använd ett wildcard på rätt plats i topicet. Wildcards kan vara # för alla eller +. För mer information, se MQTT-specifikationen.

Fråga

Ingen MQTT-enhet visas i Yggio, hur kontrollerar jag om mitt topic med data har publicerats korrekt på Yggios MQTT-broker?

Svar

Använd MQTT Explorer i linje med instruktionerna ovan för att prenumerera på topics med användarnamn och lösenord på Yggios MQTT-broker.