MQTT

Yggio betreibt einen MQTT-Broker, der es einfach macht, Echtzeit-Datenströme zu veröffentlichen und zu abonnieren.

Daten empfangen (als Datenkonsument)

Wenn Sie Daten von Geräten empfangen möchten, müssen Sie ein Topic im MQTT-Broker von Yggio abonnieren.

MQTT-Topic-Format:

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

• [ID]: Ihr Identifikator – entweder eine User-ID, Client-App-ID oder eine Basic-Credentials-Set-ID.
• [iotnodeId]: Die eindeutige ID des IoT-Nodes, der die Daten sendet.

Um alle Daten Ihrer ID zu empfangen, können Sie Folgendes abonnieren:

yggio/output/v2/[ID]/#

Schritte zum Empfangen von Daten:

1. Einen Kanal einrichten:
   Erstellen Sie einen Kanal mit Ihrer User-ID oder Ihren Basic Credentials. Eine Anleitung finden Sie hier.

2. Ein Zugriffstoken erhalten:
   Authentifizieren Sie sich mit einem Benutzer-Zugriffstoken. Ein Beispiel finden Sie im Abschnitt Authentifizierung unten.

3. Ihr Topic abonnieren:
   Verwenden Sie einen MQTT-Client, um Ihr Topic zu abonnieren. Unten ist ein Beispiel mit mosquitto, aber jeder MQTT-Client funktioniert.

Beispiel:

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

---

Daten senden (als Datenanbieter)

Um Daten über MQTT an Yggio zu senden, registrieren Sie Ihre Gerätezugangsdaten und das Topic, auf dem Sie veröffentlichen werden.

MQTT-Topic-Format:

yggio/generic/v2/[your-sub-topic]/[optional-sub-topic]

• Das Topic muss im Voraus reserviert werden. Ein Beispiel finden Sie im Abschnitt Reserved MQTT Topic unten.

• Das Payload-Format muss JSON sein.

Schritte zum Senden von Daten:

1. Ein Basic Credentials Set erstellen
   Dies ermöglicht es Ihrem Gerät oder Dienst, sich beim Yggio-MQTT-Broker zu authentifizieren.
   So erstellen Sie eines →

2. Ein MQTT-Topic reservieren
   Dieses Topic identifiziert die Datenquelle (Ihr Gerät oder Ihren Dienst) in Yggio. So reservieren Sie ein Topic →

3. Ihre Daten veröffentlichen
   Beginnen Sie, JSON-formatierte Daten an Ihr reserviertes MQTT-Topic zu senden.

   Beispiel-JSON-Payload:

   {
     "temperature": 23.5,
     "unit": "C"
   }

4. Warum das reservierte Topic wichtig ist
   Yggio verwendet dieses Topic, um Daten mit einer bestimmten Geräteentität zu verknüpfen. Das Topic wird als geheimes Feld gespeichert, sodass die Entität später in der Yggio-UI beansprucht werden kann.

---

Authentifizierung

Um ein Benutzer-Zugriffstoken zu erhalten, müssen Sie eine Login-Anfrage stellen. Ausführliche Informationen finden Sie in unserer Swagger-Dokumentation. Unten ist ein Beispiel für einen curl-Befehl, den Sie anpassen und verwenden können:

curl -X 'POST' \
  'https://YGGIO_DOMAIN/api/auth/local' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
}'

Nach erfolgreicher Anmeldung erhalten Sie eine Antwort wie diese:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>"
}

Dieses Token ist entscheidend für den Zugriff auf authentifizierte Endpunkte und den sicheren Konsum von Daten. Speichern Sie es sicher und verwenden Sie es in nachfolgenden Anfragen.

---

basicCredentialsSet

In Szenarien, in denen es für den Client nicht möglich ist, das Token während des Abonnements zu erneuern, können Sie den Kanal mit einem „basic credentials set“ verbinden. Unten ist ein Beispiel, das zeigt, wie man ein Basic Credentials Set erstellt und einen funktionierenden mosquitto_sub-Befehl verwendet.

curl -X 'POST' \
  'https://staging.yggio.net/api/basic-credentials-sets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "My_basicCredentialsSet_Name",
  "password": "very-very-super-secret-password"
}'

Nach erfolgreicher Erstellung erhalten Sie eine Antwort wie diese:

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

Sie können dann die _id im mosquitto_sub-Befehl wie folgt verwenden:

mosquitto_sub -h mqtt.staging.yggio.net -t "yggio/output/v2/123456789abcdef/#" -u My_basicCredentialsSet_Name -P very-very-super-secret-password 

Dieser Ansatz ermöglicht sicheren und dauerhaften Zugriff auf Datenströme, ohne dass während des Abonnements ein Token erneuert werden muss.

---

reservedMqttTopic

Hier ist ein Beispiel, das zeigt, wie man ein reserviertes MQTT-Topic erstellt und mit einem mosquitto_pub-Befehl verwendet.

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

Nach erfolgreicher Erstellung erhalten Sie eine Antwort wie diese:

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

Sie können dann das topic im mosquitto_pub-Befehl wie unten gezeigt verwenden:

mosquitto_pub -h mqtt.staging.yggio.net -u "My_basicCredentialsSet_Name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/topic/321" -m '{"health":"running"}'

Dies ermöglicht es Ihnen, Daten mit den bereitgestellten Zugangsdaten sicher an das angegebene MQTT-Topic zu veröffentlichen.

---

Generische Geräte

Bei generischen Geräten dient das reservierte MQTT-Topic als Identifikator für die entsprechende, in Yggio erstellte Entität. Dieser Identifikator wird in entity.secret gespeichert. Nutzer haben die Möglichkeit, vor oder nach Beginn des Datenstroms die Entität in der Yggio-Benutzeroberfläche zu „beanspruchen“. Dies geschieht durch Eingabe des Secrets, das dem reservedMqttTopic.topic entspricht, während des Onboarding-Prozesses des Geräts.

Nach der Beanspruchung erbt die Entität die Zugriffsrechte, die mit dem für die Authentifizierung verwendeten basicCredentialsSet verbunden sind.

---

Beispiele

Unten finden Sie Beispiele für basicCredentialsSets, reservedMqttTopics und die daraus resultierenden gültigen MQTT-Veröffentlichungen.

Beispiel 1 – eine einfache Einheit

DB-Entitäten

// basicCredentialsSet
{
  _id: '123456789abcdefg'
  username: 'my-device-name',
  password: 'very-very-super-secret-password'
}

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

gültige Veröffentlichungen (mosquitto-Syntax)

mosquitto_pub -h mqtt.staging.yggio.net -u "my-device-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/topic/321" -m '{"health":"running"}'

mosquitto_pub -h mqtt.staging.yggio.net -u "my-device-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/topic/321/stats" -m '{"battery":100, "antennaStatus": "sending"}'

mosquitto_pub -h mqtt.staging.yggio.net -u "my-device-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/topic/321/temperature" -m '{"value":22}'

Alle drei obigen Veröffentlichungen führen zur Aktualisierung oder Erstellung des unten stehenden Iotnodes. Wichtig zu beachten: Eine Veröffentlichung an ein Sub-Topic erstellt keinen neuen Iotnode, sondern aktualisiert stattdessen den bestehenden mit den neuen Daten.

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

Beispiel 2 – Gateway oder „Cloud“ mit Sub-Nodes

// basicCredentialsSet
{
  _id: '123456789abcdefg'
  username: 'my-gateway-name',
  password: 'very-very-super-secret-password'
}

// reservedMqttTopic
[
  {
    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'
  }
]

gültige Veröffentlichungen (mosquitto-Syntax)

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" -m '{"health":"running"}'

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/1" -m '{"lightSwitch":on}'

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/2" -m '{"lightSwitch":off}'

Alle drei obigen Veröffentlichungen führen zur Aktualisierung oder Erstellung der unten stehenden Entitäten.

{
  _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",
}

Es sei erwähnt, dass eine Veröffentlichung an z. B. .../devices/3 in diesem Fall keine neue Entität erstellen, sondern stattdessen das Gateway aktualisieren würde. Das liegt daran, dass für dieses Topic keine „Reservierung“ vorgenommen wurde, d. h. es existiert kein reservedMqttTopic.

Eine Veröffentlichung wie diese...

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"}'

...würde die Entität von diesem...

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

...zu diesem aktualisieren...

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

Generisches MQTT-Kommando

Downlink über den internen MQTT-Broker von Yggio

Um den internen MQTT-Broker von Yggio für die Downlink-Kommunikation zu verwenden, können Sie Ihren Connector wie folgt konfigurieren:

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

In dieser JSON-Konfiguration:

• "name": Geben Sie einen Namen für Ihren Connector an.
• "basicCredentialsSetId": Geben Sie die ID des zu verwendenden Basic Credential Sets an.

Downlink über einen externen MQTT-Broker

Alternativ können Sie den Connector so konfigurieren, dass er einen externen MQTT-Broker für die Downlink-Kommunikation verwendet:

{
    "name": "<Connector name>",
    "mqttServer": {
        "host": "mqtt.example.org",
        "port": <1883 or 8883>,
        "protocol": "<mqtt or mqtts>",
        "username": "<Username>",
        "password": "<Password>"
    },
    "downlink": {
        "topic": "<mqtt-topic>"
    },
    "integration": "Generic"
}

• "name": Geben Sie einen Namen für Ihren Connector an.
• "mqttServer": Geben Sie die Details Ihres externen MQTT-Brokers an,
  • Beispiel: Host, Port, Protokoll, Benutzername und Passwort.
• "downlink": Legen Sie das MQTT-Topic fest, an das Downlink-Nachrichten gesendet werden.
• "integration": Geben Sie den Integrationstyp an, in diesem Fall „Generic“.

Beispiel: Einen Downlink über den internen Broker senden

Um ein Downlink-Kommando über den internen MQTT-Broker von Yggio zu senden, gehen Sie wie folgt vor:

• Erstellen Sie ein Basic Credential Set oder verwenden Sie ein bestehendes:

  Eingabe:

  curl --location "https://$YGGIO_URL/api/basic-credentials-sets" \
  --header "Authorization: Bearer $YGGIO_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
      "username": "MyUsername",
      "password": "MySecretPassword"
  }'

  Ausgabe:

  {"_id":"64d5f0fa0c5b9c88f70c6ff0","username":"MyUsername"}

• Erstellen Sie einen Connector:

  Eingabe:

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

  Ausgabe:

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

• Abonnieren Sie das Topic yggio/push/v1/<BasicCredentialsSetId>/#

  mosquitto_sub -v -h "mqtt.$YGGIO_URL" -u "MyUsername" -P "MySecretPassword" -t "yggio/push/v1/64d5f0fa0c5b9c88f70c6ff0/#"

• Senden Sie ein Kommando an den Connector:

  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": "myMessage"
          }
      }'

• Ausgabe des mosquitto_sub-Befehls:

  yggio/push/v1/64d5f0fa0c5b9c88f70c6ff0/subTopic myMessage

Achten Sie darauf, $YGGIO_URL durch die tatsächliche URL Ihres Yggio-Servers zu ersetzen.

Axis-Installation

Beginnen Sie damit, Ihre Axis-Kamera an eine Stromquelle und Ethernet anzuschließen.

Ermitteln Sie die IPv4-Adresse der angeschlossenen Kamera. Rufen Sie dann mit einem Computer im selben Netzwerk https://[CAMERA-IP] auf.

Melden Sie sich an.

Gehen Sie zu

1. Device view

2. Maintenance

Folgen Sie den Anweisungen, um die Firmware zu aktualisieren. Yggio unterstützt bis zu 10.8.x

Axis-Abonnement bei MQTT

Gehen Sie zu unserer REST-API Swagger

Autorisieren Sie sich bei POST /auth/local

Nehmen Sie das Token aus der Antwort und fügen Sie es bei Authorize ein.

Scrollen Sie zu BasicCredentialsSets und führen Sie ein POST /basic-credentials-sets aus.

Speichern Sie den gewünschten Benutzernamen, das Passwort und die basicCredentialsSetId an einem sicheren Ort!

Speichern Sie die _id aus der Antwort und verwenden Sie sie im nächsten Schritt.

Scrollen Sie zu POST /reserved-mqtt-topics, fügen Sie die _id aus dem vorherigen Schritt in basicCredentialsSetId ein und verwenden Sie yggio/generic/v2, gefolgt von Ihren eigenen Topics. Getrennt durch /. Siehe MQTT (Datenanbieter) für Beispiele.

Lokale Weboberfläche der Axis-Kamera

1. Device View

2. MQTT

3. staging.yggio.net als Host

4. MQTT über TCP

5. 1883 als Port

6. Benutzername aus BasicCredentialsSets

7. Passwort aus BasicCredentialsSets

8. Save

9. Connect

Axis-Ereignisse

1. Device View

2. Events

3. MQTT Events

4. Use default condition prefix -> OFF

5. Fügen Sie das Topic ein, das Sie in den vorherigen Schritten reserviert haben

6. Fügen Sie eine Bedingung hinzu und wählen Sie A3DPCCountingEvent

7. Save.

Axis-Belegungserkennung

1. Occupancy

2. Estimate occupancy -> ON

3. Allow Events -> ON

Axis-Zähler

Von hier aus sehen Sie die Daten, die vom Gerät kommen.

Gerät in Yggio konfigurieren

Nachdem die obigen Schritte abgeschlossen sind und das Gerät seine erste Nachricht an das reservierte MQTT-Topic gesendet hat, wird ein Gerät in Yggio erstellt.

Wenn das Gerät erstellt wird, lautet sein Name MQTT - <topic that you chose>.

Setzen Sie den Gerätemodellnamen auf -> axis-p8815-2-3d-people-counter.

Gehen Sie nun zu Data, und Sie finden dort Ihre peopleCounter-Daten.