MQTT

Yggio tillhandahåller en MQTT-broker, vilket gör det enkelt att publicera och prenumerera på realtidsdatastreamar.

Ta emot data (Som datakonsument)

Om du vill ta emot data från enheter behöver du prenumerera på ett ämne (topic) i Yggios MQTT-broker.

Format för MQTT-topic:

yggio/output/v2/[ID]/iotnode/[iotnodeId]

[ID]: Din identifierare – antingen ett användar-ID, klientapplikations-ID eller ID för en uppsättning grundläggande autentiseringsuppgifter (basic credentials).
[iotnodeId]: Det unika ID:t för IoT-noden som skickar data.

För att ta emot all data kopplad till ditt ID kan du prenumerera på:

yggio/output/v2/[ID]/#

Steg för att ta emot data:

Skapa en kanal:
Skapa en kanal med ditt användar-ID eller dina grundläggande autentiseringsuppgifter. Se denna guide för instruktioner.
Autentisering:
Autentisera dig med en användartoken. Se autentiseringssektionen nedan för ett exempel.
Prenumerera på ditt topic:
Använd en MQTT-klient för att prenumerera. Här är ett exempel med mosquitto, men vilken MQTT-klient som helst fungerar.

Exempel:

mosquitto_sub -h mqtt.yggio.net -p 8883  -u "<ditt-userID>" -P "<din-access-token>"  -t "yggio/output/v2/<ditt-userID>/#"

Skicka data (Som dataleverantör)

För att skicka data till Yggio via MQTT behöver du registrera autentiseringsuppgifter för enheten samt ett topic där enheten publicerar data.

Format för MQTT-topic:

yggio/generic/v2/[ditt-sub-topic]/[valfritt-sub-topic]

Topic måste reserveras i förväg. Se avsnittet om reserverade MQTT-topic nedan.
Payload måste vara i JSON-format.

Steg för att skicka data:

Skapa ett "Basic Credentials Set": Detta görs genom att skapa en uppsättning grundläggande autentiseringsuppgifter (basic credentials set) via Yggios REST API. Se denna guide för instruktioner.
Reservera ett MQTT-topic:
Detta topic identifierar datakällan (din enhet eller tjänst) i Yggio. Hur du reserverar ett MQTT-topic →
Publicera din data
Börja skicka data i JSON-format till ditt reserverade topic.

Exempel JSON payload:
```
  {
    "temperature": 23.5,
    "unit": "C"
  }
```
Varför det reserverade topic är viktigt Yggio använder detta topic för att koppla data till en specifik enhetsentitet. Topic sparas som ett hemligt fält och gör det möjligt att göra anspråk på enheten senare i Yggios användargränssnitt.

Autentisering

För att hämta en användartoken måste du göra en inloggningsförfrågan. Du hittar detaljerad information i vår Swagger-dokumentation.

Här är ett exempel på ett curl-kommando du kan modifiera och använda:

curl -X 'POST'   'https://YGGIO_DOMAIN/api/auth/local'   -H 'accept: application/json'   -H 'Content-Type: application/json'   -d '{
  "username": "DITT_ANVÄNDARNAMN",
  "password": "DITT_LÖSENORD"
}'

Vid lyckad inloggning får du ett svar som ser ut så här:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6..."
}

Denna token är avgörande för att få åtkomst till autentiserade slutpunkter och hämta data säkert. Se till att lagra den säkert och använda den i kommande förfrågningar.

basicCredentialsSet

I situationer där det inte är möjligt för klienten att uppdatera token under en prenumeration, kan du koppla kanalen till en "uppsättning grundläggande autentiseringsuppgifter". Nedan visas ett exempel på hur du skapar en sådan uppsättning samt ett fungerande mosquitto_sub-kommando.

curl -X 'POST' \
  'https://staging.yggio.net/api/basic-credentials-sets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer DITT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "Min_basicCredentialsSet",
  "password": "väldigt-hemligt-lösenord"
}'

Svar:

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

Använd _id i mosquitto_sub:

mosquitto_sub -h mqtt.staging.yggio.net -t "yggio/output/v2/123456789abcdef/#" -u Min_basicCredentialsSet -P väldigt-hemligt-lösenord

reservedMqttTopic

Exempel på hur man skapar ett reserverat MQTT-topic och använder det med mosquitto_pub:

curl -X 'POST' \
  'https://staging.yggio.net/api/reserved-mqtt-topics' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer DITT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "topic": "yggio/generic/v2/any/unique/topic/321",
  "basicCredentialsSetId": "123456789abcdefg"
}'

Svar:

{
  "_id": "abababababa1212121212",
  "topic": "yggio/generic/v2/any/unique/topic/321"
}

Publicera:

mosquitto_pub -h mqtt.staging.yggio.net -u "Min_basicCredentialsSet" -P "väldigt-hemligt-lösenord" -t "yggio/generic/v2/any/unique/topic/321" -m '{"health":"running"}'

Generiska enheter

För generiska enheter fungerar det reserverade MQTT-topic som identifierare för den skapade entiteten i Yggio. Användaren kan "claim:a" denna entitet i UI genom att ange secret-värdet under installation.

När den har blivit claim:ad ärver entiteten rättigheterna från basicCredentialsSet.

Exempel

Exempel 1 – Enkel enhet

// basicCredentialsSet
{
  _id: '123456789abcdefg'
  username: 'min-enhet',
  password: 'väldigt-hemligt-lösenord'
}

// reservedMqttTopic
{
  topic: 'yggio/generic/v2/any/unique/topic/321',
  basicCredentialsSetId: '123456789abcdefg'
}

Publiceringar:

mosquitto_pub -h mqtt.staging.yggio.net -u "min-enhet" -P "väldigt-hemligt-lösenord" -t "yggio/generic/v2/any/unique/topic/321" -m '{"health":"running"}'

mosquitto_pub -h mqtt.staging.yggio.net -u "min-enhet" -P "väldigt-hemligt-lösenord" -t "yggio/generic/v2/any/unique/topic/321/stats" -m '{"battery":100, "antennaStatus": "sending"}'

mosquitto_pub -h mqtt.staging.yggio.net -u "min-enhet" -P "väldigt-hemligt-lösenord" -t "yggio/generic/v2/any/unique/topic/321/temperature" -m '{"value":22}'

Alla ovanstående publiceringar kommer att resultera i uppdateringen eller skapandet av nedanstående entitet. Resultat:

{
  _id: 'abababababa1212121212',
  secret: 'yggio/generic/v2/any/unique/topic/321',
  health: "running",
  stats: { antennaStatus: "sending", battery: 100 },
  temperature: { value: 22 }
}

Exempel 2 – Gateway eller "moln" med sub-noder

// basicCredentialsSet
{
  _id: '123456789abcdefg',
  username: 'min-gateway',
  password: 'väldigt-hemligt-lösenord'
}

// reservedMqttTopics
[
  { topic: 'yggio/generic/v2/any/unique/gatewaytopic/4321', basicCredentialsSetId: '123456789abcdefg' },
  { topic: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/1', basicCredentialsSetId: '123456789abcdefg' },
  { topic: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/2', basicCredentialsSetId: '123456789abcdefg' }
]

Publiceringar:

mosquitto_pub -h mqtt.staging.yggio.net -u "min-gateway" -P "väldigt-hemligt-lösenord" -t "yggio/generic/v2/any/unique/gatewaytopic/4321" -m '{"health":"running"}'

mosquitto_pub -h mqtt.staging.yggio.net -u "min-gateway" -P "väldigt-hemligt-lösenord" -t "yggio/generic/v2/any/unique/gatewaytopic/4321/devices/1" -m '{"lightSwitch": "on"}'

mosquitto_pub -h mqtt.staging.yggio.net -u "min-gateway" -P "väldigt-hemligt-lösenord" -t "yggio/generic/v2/any/unique/gatewaytopic/4321/devices/2" -m '{"lightSwitch": "off"}'

Alla ovanstående publiceringar kommer att resultera i uppdateringen eller skapandet av nedanstående entiteter.

{
  _id: 'aaaaaaaaaaa111111111111'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321',
  health: "running",
}

{
  _id: 'bbbbbbbbbbbb22222222222'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/1',
  lightSwitch: "on",
}

{
  _id: 'cccccccccccc33333333333'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/2',
  lightSwitch: "off",
}

Värt att notera är att en publicering till t.ex. .../devices/1 skulle inte skapa en ny entitet. Istället skulle den uppdatera gatewayn i det här fallet. Detta beror på att det inte har funnits en "reservation" för det ämnet, dvs. inget reserveratMqttTopic existerar.

Så en publicering på detta viset...

mosquitto_pub -h mqtt.staging.yggio.net -u "my-gateway-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/gatewaytopic/4321/devices/3" -m '{"lightSwitch": "on"}'

...skulle uppdatera en enhet till...

{
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321',
  health: "running",
}

...to this...

{
  _id: 'aaaaaaaaaaa111111111111'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321',
  health: "running",
  devices: {
    3: {
      lightSwitch: "on"
    }
  }
}

Generellt MQTT-kommando

Downlink med Yggios interna MQTT-broker

{
    "name": "<Connector namn>",
    "basicCredentialsSetId": "<basicCredentialsSetId>",
    "integration": "Generic"
}

I denna JSON-konfiguration:

"name": Ange ett namn för din connector.
"basicCredentialsSetId": Ange ID:t för den uppsättning grundläggande autentiseringsuppgifter som ska användas.

Downlink med extern MQTT-broker

Alternativt, så kan du konfigurera connectorn att använda en extern MQTT-broker för downlink-kommunikation:

{
    "name": "<Connector namn>",
    "mqttServer": {
        "host": "mqtt.example.org",
        "port": <1883 eller 8883>,
        "protocol": "mqtt or mqtts",
        "username": "<Användarnamn>",
        "password": "<Lösenord>"
    },
    "downlink": {
        "topic": "<mqtt-topic>"
    },
    "integration": "Generic"
}

"name": Ange ett namn för din connector.
"mqttServer": Ange detaljerna för din externa MQTT-broker,
- Exempel: värd, port, protokoll, användarnamn och lösenord.
"downlink": Ange MQTT-topic där downlink-meddelanden kommer att skickas.
"integration": Ange integrationstypen, som i detta fall är "Generic".

Exempel: Skicka downlink via intern broker

För att skicka downlink kommandon till en connector via Yggios interna MQTT-broker, följ dessa steg:

Skapa en uppsättning grundläggande autentiseringsuppgifter (basic credentials set) med hjälp av Yggios REST API. input:

curl --location "https://$YGGIO_URL/api/basic-credentials-sets" \
--header "Authorization: Bearer $YGGIO_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "username": "MittAnvändarnamn",
    "password": "MittLösenord"
}'

output:

{
    "_id": "64d5f0fa0c5b9c88f70c6ff0",
    "username": "MittAnvändarnamn",
    "password": "MittLösenord"
}

Skapa en connector med hjälp av Yggios REST API. input:

curl --location "https://$YGGIO_URL/api/connectors" \
--header "Authorization: Bearer $YGGIO_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "name": "MinConnector",
    "basicCredentialsSetId": "64d5f0fa0c5b9c88f70c6ff0",
    "integration": "Generic"
}'

output:

{"_id":"64d5f1260c5b9c88f70c6ff5","name":"MinConnector","basicCredentialsSetId":"64d5f0fa0c5b9c88f70c6ff0","integration":"Generic"}

Prenumerera på topic yggio/push/v1/<BasicCredentialsSetId>/#

mosquitto_sub -v -h "mqtt.$YGGIO_URL" -u "MittAnvändarnamn" -P "MittLösenord" -t "yggio/push/v1/64d5f0fa0c5b9c88f70c6ff0/#"

Skicka kommando:

curl --location --request PUT "https://$YGGIO_URL/api/connectors/command" \
--header "Authorization: Bearer $YGGIO_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "command": "sendDownlink",
    "integrationName": "Generic",
    "connectorId": "64d5f1260c5b9c88f70c6ff5",
    "data": {
        "mqttTopic": "subTopic",
        "message": "mittMeddelande"
    }
}'

Utdata från kommandot:

yggio/push/v1/64d5f0fa0c5b9c88f70c6ff0/subTopic mittMeddelande

Glöm inte att ersätta $YGGIO_URL med den faktiska URL:en för din Yggio-server.

Axis-installation

Börja med att ansluta din Axis-kamera till ström och nätverk (ethernet).

Identifiera IPv4-adressen för den anslutna kameran och gå till https://[KAMERA-IP] från en dator som är ansluten till samma nätverk.

root-password

Logga in.

Gå till:

Enhetsvy (Device view)
Underhåll (Maintenance)

Följ instruktionerna för att uppdatera firmware. Yggio stödjer upp till version 10.8.x.

Axis-prenumeration till MQTT

Gå till vårt REST API via Swagger
Auktorisera dig via POST /auth/local
Ta token från svaret och klistra in det i Authorize
Scrolla ner till BasicCredentialsSets och gör ett POST /basic-credentials-sets
Spara användarnamn, lösenord och basicCredentialsSetId på en säker plats
Spara _id från svaret och använd det i nästa steg
Gå till POST /reserved-mqtt-topics, klistra in _id i basicCredentialsSetId
Använd yggio/generic/v2 följt av dina egna ämnen (topics), separerade med /
Se MQTT (data provider) för exempel

Axis-kamerans lokala webbgränssnitt

Enhetsvy (Device View)
MQTT
Värd (host): staging.yggio.net
Protokoll: MQTT över TCP
Port: 1883
Användarnamn från BasicCredentialsSets
Lösenord från BasicCredentialsSets
Spara
Anslut

Axis-händelser

Enhetsvy (Device View)
Händelser (Events)
MQTT-händelser
Use default condition prefix → AV (OFF)
Klistra in ämnet (topic) från föregående steg
Lägg till ett villkor och välj A3DPCCountingEvent
Spara

Axis-uppskattad beläggning

Beläggning (Occupancy)
Uppskatta beläggning → PÅ (ON)
Tillåt händelser → PÅ (ON)

Axis-räknare

Du kommer att se data som skickas från enheten här:
counter

Konfigurera enhet i Yggio

När ovanstående steg är genomförda och enheten har skickat sitt första meddelande till det reserverade MQTT-topic, kommer en enhet att skapas i Yggio.

Enhetens namn: MQTT - <det topic du valt>
Ange modellnamn: axis-p8815-2-3d-people-counter

Gå till fliken Data, där hittar du din peopleCounter-data.

Ta emot data (Som datakonsument)​

Format för MQTT-topic:​

För att ta emot all data kopplad till ditt ID kan du prenumerera på:​

Steg för att ta emot data:​

Skicka data (Som dataleverantör)​

Format för MQTT-topic:​

Steg för att skicka data:​

Autentisering​

basicCredentialsSet​

reservedMqttTopic​

Generiska enheter​

Exempel​

Exempel 1 – Enkel enhet​

Exempel 2 – Gateway eller "moln" med sub-noder​

Publiceringar:​

Generellt MQTT-kommando​

Downlink med Yggios interna MQTT-broker​

Downlink med extern MQTT-broker​

Exempel: Skicka downlink via intern broker​

Axis-installation​

Axis-prenumeration till MQTT​

Axis-kamerans lokala webbgränssnitt​

Axis-händelser​

Axis-uppskattad beläggning​

Axis-räknare​

Konfigurera enhet i Yggio​

Ta emot data (Som datakonsument)

Format för MQTT-topic:

För att ta emot all data kopplad till ditt ID kan du prenumerera på:

Steg för att ta emot data:

Skicka data (Som dataleverantör)

Format för MQTT-topic:

Steg för att skicka data:

Autentisering

basicCredentialsSet

reservedMqttTopic

Generiska enheter

Exempel

Exempel 1 – Enkel enhet

Exempel 2 – Gateway eller "moln" med sub-noder

Publiceringar:

Generellt MQTT-kommando

Downlink med Yggios interna MQTT-broker

Downlink med extern MQTT-broker

Exempel: Skicka downlink via intern broker

Axis-installation

Axis-prenumeration till MQTT

Axis-kamerans lokala webbgränssnitt

Axis-händelser

Axis-uppskattad beläggning

Axis-räknare

Konfigurera enhet i Yggio