Commands

Über unsere REST-API können Sie Kommandos an Ihre Geräte senden, wie z. B. das Einreihen von LoRa-Downlinks und das Ein-/Ausschließen von Z-Wave-Geräten. Diese Dokumentation soll unsere Swagger-Dokumentation ergänzen, die URL lautet staging.yggio.net/api/iotnodes/command.

Wie ein Kommando funktioniert

Ein Kommando ist eine Nachricht, die Yggio an die Integration weitergibt, zu der ein Gerät gehört. Yggio spricht nicht selbst mit dem Gerät: es übergibt das Kommando dem Netzwerkserver oder der Herstellercloud, die es zustellt. Daraus folgen zwei Dinge. Was ein Kommando kann, hängt von der Integration ab und nicht von Yggio, und ein angenommenes Kommando ist eingereiht und nicht zugestellt.

Jedes Kommando ist dieselbe Anfrage, PUT /api/iotnodes/command, mit denselben vier Feldern:

{
  "command": "loraAppServerQueueDownlink",
  "integrationName": "ChirpStack",
  "iotnodeId": "5d2c6561ecb9a30aa5fc3e41",
  "data": {}
}

Feld
command	Erforderlich. Welches Kommando ausgeführt wird
iotnodeId	Das Gerät, für das es gilt
integrationName	An welche Integration gesendet wird. Optional, wenn das Gerät bereits zu einer gehört
data	Die eigene Payload des Kommandos. Ihre Form hängt vom Kommando ab

integrationName und der eigene Connector des Geräts benennen beide das Ziel. Eines von beiden ist erforderlich, und integrationName gewinnt, wenn beide angegeben sind.

Die Kommandonamen und die data, die jedes erwartet, unterscheiden sich je Integration, weshalb die Abschnitte unten nach Integration und nicht nach Kommando geordnet sind. Unter Iotnodes in der Swagger UI lässt sich derselbe Endpunkt interaktiv aufrufen.

Ein Kommando zu senden erfordert Write-Zugriff auf das Gerät und die Ressource Device in Ihrer Rolle.

LoRa

Downlink

Downlinks können generell folgendermaßen verwendet werden:

1. Einen Downlink einreihen – wenn das Gerät (je nach Klasse) einen Downlink empfangen soll, verschwindet er aus der Warteschlange

2. Die Warteschlange abrufen – damit Sie als Nutzer sehen können, was sich aktuell in der Warteschlange befindet

3. Die Warteschlange leeren – entfernt alle eingereihten Downlinks aus der Warteschlange

Die Verwendung dieser drei Kommandos unterscheidet sich von Integration zu Integration.

ChirpStack-Downlink

Ein Element einreihen

Methode: PUT

Body:

{
  "command":"loraAppServerQueueDownlink", //string, use as is
  "integrationName":"ChirpStack", //string, use as is
  "iotnodeId":"5d2c6561ecb9a30aa5fc3e41", //string, yggioId of the device
  "data": {
    "confirmed": false, //bool, we're currently not using confirmed,
    "reference": "I sent this to configure blabla", //string, reference to the payload in plain text
    "fPort": "5", //string, port
    "data": "1111" //string, hex, payload to be sent to the device
  }
}

Die Warteschlange abrufen

Methode: PUT

Body:

{
  "command": "loraAppServerGetDeviceQueue", //string, use as is
  "integrationName": "ChirpStack", //string, use as is
  "iotnodeId": "5d2c6561ecb9a30aa5fc3e41", //string, yggioId of the device
}

Die Warteschlange leeren

Methode: PUT

Body:

{
  "command": "loraAppServerFlushQueue", //string, use as is
  "integrationName": "ChirpStack", //string, use as is
  "iotnodeId": "5d2c6561ecb9a30aa5fc3e41", //string, yggioId of the device
}

Netmore-Downlink

Ein Element einreihen

Methode: PUT

Body:

{
  "command": "apiCall", //string, use as is
  "iotnodeId": "60a3b1fd26b01f00074aa625", //string, yggioId of the device
  "data": {
    "callName": "sendDownlink", //string, use as is
    "callData": {
      "devEui": "70B3D52C00019041", //string, devEui of the iotnode
      "payload":{
        "fPort": "2", //string, port
        "payloadHex": "aaaaa" //string, hex, payload to be sent to the device
      }
    }
  }
}

Die Warteschlange abrufen

Methode: PUT

Body:

{
  "command": "apiCall", //string, use as is
  "iotnodeId": "60a3b1fd26b01f00074aa625", //string, yggioId of the device
  "data":{
    "callName": "getDownlinks", //string, use as is
    "callData": {
      "devEui": "70B3D52C00019041" //string, devEui of the iotnode
    }
  }
}

Die Warteschlange leeren

Methode: PUT

Body:

{
  "command": "apiCall", //string, use as is
  "iotnodeId": "60a3b1fd26b01f00074aa625", //string, yggioId of the device
  "data": {
    "callName": "clearDownlinks", //string, use as is
    "callData": {
      "devEui": "70B3D52C00019041" //string, devEui of the iotnode
    }
  }
}

Kommandoschaltflächen

Erstellen Sie eine Schaltfläche, die bei Betätigung eine Regel auslöst

1. Wählen Sie eine Voreinstellung in der Dropdown-Liste, oder wählen Sie „Custom“, um einen eigenen Text einzugeben
2. Gehen Sie zur Regelmaschine und dort zu Rules
3. Die mit der Schaltfläche verbundene Regel hat folgendes Format: device-name.button-name, z. B. Basement-light.On
4. Fügen Sie der Regel eine Aktion hinzu und klicken Sie auf Save. Es ist nicht nötig, eine Auslösebedingung hinzuzufügen, da die Regel die Schaltfläche bereits als Auslösebedingung verwendet.