Hoppa till huvudinnehåll

Generic MQTT Connector

Connector-detaljer Generic​

Den generiska MQTT-connectorn gör det möjligt för plattformen att publicera data antingen på sin egen MQTT broker eller på en extern MQTT broker. Den huvudsakliga skillnaden jämfört med en MQTT Channel är att publiceringen sker antingen via API:et eller via Rule Engine, och att datan kan omformateras innan publicering. Detta ger fördelen att både topic och dataformat kan anpassas för att matcha kraven hos ett externt system.

⚠️ Det är för närvarande inte möjligt att använda den generiska MQTT-connectorn för att prenumerera på en MQTT broker.

Publicera Data på Plattformens Interna MQTT Broker​

För att publicera data på plattformens MQTT broker måste ett basicCredentialSetId först skapas. Detta måste för närvarande göras via API:et/Swagger på endpointen: https://staging.yggio.net/swagger/#/BasicCredentialsSets/createBasicCredentialsSet

Steg​

  1. Logga in på Swagger med dina autentiseringsuppgifter: https://staging.yggio.net/swagger/#/Authorization/login
  2. Kopiera token.
  3. Gå till det övre högra hörnet i Swagger och lägg till token i rutan "Authorize".
  4. Navigera till endpointen Basic Credential Set och skapa ditt användarnamn och lösenord.
  5. Notera det returnerade ID:t.

Dessa autentiseringsuppgifter (användarnamn, lösenord och ID) kommer att användas tillsammans med topic av ditt externa system för att prenumerera på den publicerade datan.

connector-details-1

Nödvändig Information​

För att sätta upp en generisk MQTT-connector, ange följande:

  • a. Basic Credential Set ID: ID för det Basic Credential Set som definierar MQTT-användarnamnet och lösenordet.

Konfigurera Fjärrsystemet​

För att prenumerera på plattformens MQTT broker, konfigurera fjärrsystemet enligt följande:

  • a. MQTT broker URL: mqtt.staging.yggio.net
  • b. Port:
    • 8883 för säker TLS (rekommenderas starkt)
    • 1883 för okrypterad data
  • c. Topic: Base topic för plattformens interna MQTT broker kan inte konfigureras. Det kommer alltid att vara yggio/push/v1/<BasicCredentialsSetId>/#. Symbolen # i topic kommer att ersättas med en enhetsspecifik unik identifierare av publiceringskommandot.
  • d. MQTT username: Enligt definition i Basic Credential Set.
  • e. MQTT password: Enligt definition i Basic Credential Set.
  • f. MQTT version: Du kan prenumerera med antingen MQTT v3.1.1 eller MQTT v5.

Publicera Data på en Extern MQTT Broker​

För att publicera data på en extern MQTT broker måste den först konfigureras för att ta emot datan som publiceras av plattformen, dvs. topic, användarnamn och lösenord måste konfigureras och värd-URL:en vara känd.

connector-details-2

Konfigurera Fjärrsystemet​

Konfigurera fjärrsystemet enligt följande:

  • a. Port:
    • 8883 för säker TLS (rekommenderas starkt)
    • 1883 för okrypterad data
  • b. Topic: Base topic som plattformen ska publicera data på. Det faktiska publiceringskommandot lägger sedan till enhetens unika identifierare som subtopic.
  • c. MQTT username: Användarnamnet.
  • d. MQTT password: Lösenordet.

Nödvändig Information​

För att sätta upp en generisk MQTT-connector för att publicera på en extern MQTT broker, ange följande enligt konfigurationen i fjärrsystemet:

  • a. MQTT broker URL: URL:en till MQTT brokern
  • b. Port: Portnumret
  • c. Topic: Base topic som plattformen ska publicera data på.
  • c. MQTT username: Användarnamnet.
  • d. MQTT password: Lösenordet.

Använda Plattformens MQTT Broker som en Extern Broker​

Det är möjligt att använda plattformens MQTT broker som en extern broker i den generiska MQTT-integrationen. Detta öppnar upp för några intressanta användningsfall:

  • Dela data från en plattformsinstans till en annan.
  • Ta bort känslig data innan den delas med en annan användare.
  • Använd kommandoknappar (command buttons) för att utlösa händelser i plattformen.

Installationsinstruktioner​

  1. Logga in på Swagger i den plattformsinstans du vill publicera data till, genom att följa instruktionerna ovan. (Det kan vara samma instans där du konfigurerar den generiska MQTT-connectorn.)

  2. Skapa ett Basic Credential Set: https://staging.yggio.net/swagger/#/BasicCredentialsSets/createBasicCredentialsSet

  3. Reservera MQTT Sub Topics för alla IoT-noder du vill publicera data på: https://staging.yggio.net/swagger/#/ReservedMqttTopics/createReservedMqttTopic

    • Topic måste följa strukturen: yggio/generic/v2/<unik identifierare>

  4. Skapa den generiska MQTT-connectorn med följande konfiguration:

    • MQTT broker URL: mqtt.staging.yggio.net (eller en annan plattformsinstans)
    • Port: 8883 (Säker TLS)
    • Topic: yggio/generic/v2
    • MQTT username: Enligt definition i Basic Credential Set.
    • MQTT password: Enligt definition i Basic Credential Set.

Resultat​

När du publicerar data skapas en ny IoT-nod i plattformen. Du kan sedan:

  • Dela den med specifika användare, eller
  • Lägga till en anpassad översättare med specifik logik för att hantera den inkommande datan.

Publicera Data med den Generiska MQTT-connectorn​

I avsnitten ovan skapade vi olika typer av generiska MQTT-connectors men publicerade ingen data. För att publicera data måste du antingen:

  1. Lägga till en Send MQTT-åtgärd i en regel i Rule Engine, eller
  2. Skicka ett kommando direkt till connectorn via API:et.

Skapa en regel​

Att använda Rule Engine för att publicera data är det vanligaste användningsfallet för den generiska MQTT-connectorn.

Principen är enkel:

  • Använd valfri typ av trigger för regeln.
  • Lägg till en Send MQTT-åtgärd som pekar på den här connectorn.
  • I åtgärden bygger du den topic och den payload du vill publicera, med platshållare för de värden som kommer från den utlösande enheten.

Installationsinstruktioner​

  1. Gå till Rule Engine och skapa en regel.
  2. Lägg till en trigger: Device updated, Missing expected report, eller Button om du vill publicera på begäran från en Command Button-widget.
  3. Lägg eventuellt till ett Value threshold-villkor, så att regeln bara publicerar när värdet spelar roll.
  4. Lägg till en Send MQTT-åtgärd och koppla den till triggern, eller till den gren av villkoret som du vill att den ska köras på.
  5. I åtgärden väljer du den generiska MQTT-connectorn och fyller i:

  • Topic Den subtopic som läggs till efter connectorns base topic. Eftersom subtopic vanligtvis behöver vara unik per enhet är vanliga alternativ:

    • {{iotnode._id}}
    • {{iotnode.devEui}}
    • {{iotnode.secret}}

  • Payload Meddelandet som ska publiceras. Platshållare som {{iotnode.temperature}} och {{diff.temperature}} ersätts före publicering, så payloaden kan formas efter vad det mottagande systemet förväntar sig.

  1. På en åtgärd som är kopplad till ett villkor, sätt exekveringspolicyn: On enter, On exit eller Every event.

Både topic och payload stödjer platshållarsyntaxen {{path}}. För hela listan över platshållare och vad de ersätts med, se Rule Engine.

Exempel på topics och payloads

Kommandoknapp som trigger för att sätta effektnivå till 50 %

Topic{{iotnode._id}}
Payload{"powerLevel":50}

Kommandoknapp som trigger för att stänga av effekt

Topic{{iotnode._id}}
Payload{"command":"off"}

Omformatera temperatur till NGSI-LD-format

Topic{{iotnode.devEui}}
Payload{"temperature":{"value":{{iotnode.temperature}},"unit":"°C","type":"property"}}

Omformatera LoRaWAN-signalkvalitetsparametrar till NGSI-LD-format

Topic{{iotnode.devEui}}
Payload{"rssi":{"value":{{iotnode.rssi}},"unit":"dB","type":"property"},"snr":{"value":{{iotnode.snr}},"unit":"dB","type":"property"},"frameCount":{"value":{{iotnode.frameCount}},"type":"property"},"spreadingFactor":{"value":{{iotnode.spreadingFactor}},"type":"property"}}

Payloaden är själva meddelandet, så JSON:en behöver varken stringifieras eller få sina citattecken escapade, vilket den behövde i den äldre regelmotorn.

Command API​

Den generiska MQTT-connectorn publicerar data om den tar emot ett sendDownlink-kommando via API:et. Detta är ett exempel

curl --location --request PUT "https://staging.yggio.net/api/connectors/command" \
    --header "Authorization: Bearer <token>" \
    --header "Content-Type: application/json" \
    --data '{
        "command": "sendDownlink",
        "integrationName": "Generic",
        "connectorId": "<connector _id>",
        "data": {
            "mqttTopic": "subTopic",
            "message": "myMessage as stringified JSON"
        }
    }'