Entwickler- & API‑Anleitung

1. Erste Verwendung

1.1 Vorbereitung

Schritt 1. Bitte stellen Sie sicher, dass das Gateway eingeschaltet ist und ordnungsgemäß funktioniert.

Schritt 2. Stellen Sie sicher, dass das Gateway und der PC mit demselben LAN verbunden sind. Geben Sie dann die URL von CUBE in Ihren Browser ein.

Hinweis: Wenn Sie mehrere Gateways haben, können Sie die entsprechende IP-Adresse abrufen, um auf das angegebene Gateway auf die unten beschriebenen zwei Arten zuzugreifen.

1. Melden Sie sich bei Ihrem WLAN-Router an und prüfen Sie die IP-Adresse des Gateways im DHCP.

2. CUBE unterstützt die lokale Erkennung über mDNS.

1.2 Loslegen

• Rufen Sie die Schnittstelle [Access Token] auf und erhalten eine Fehlermeldung, die auffordert, auf < zu klickenFertig>. Beachten Sie, dass die Schnittstellenzugriffe nach dem Drücken nicht länger als 5 Minuten gültig sind.

// Anfrage
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// Antwort
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

• Klicken Sie auf <Fertig> und rufen Sie die Schnittstelle [Access Token] erneut auf. Die Antwort ist erfolgreich und das Token wurde erhalten.

// Anfrage
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// Antwort
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

• Token verifizieren. Rufen Sie die Schnittstelle [Get Device List] auf. Die Antwort ist erfolgreich und die Geräteliste wurde erhalten.

// Anfrage
curl --location --request GET 'http://<ip address>/open-api/V2/rest/devices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d'

// Antwort
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}

• Methode zum Erhalten des CUBE-Zugriffstokens: Nachdem die Schnittstelle [Access Token] aufgerufen wurde, fordert ein globales Popup auf der CUBE-Webkonsole den Benutzer auf, die Erfassung der Schnittstellenzugangsdaten zu bestätigen.

• Hinweis: Wenn Sie mehr als eine CUBE-Webkonsole-Seite geöffnet haben, erscheint das Bestätigungs-Popup auf mehreren Webkonsole-Seiten gleichzeitig, und die Popups der anderen Webkonsole-Seiten werden geschlossen, nachdem auf einer der Seiten die Bestätigung angeklickt wurde.

2. Kernkonzept

2.1 Adresse der Entwicklungs-Schnittstelle

Die Gateway-Web-API-Schnittstelle hat zwei Zugriffsarten (basierend auf IP oder Domainname), normalerweise ist der Root-Pfad /open-api/V2/rest/< specific function module >

// IP-Zugriff http:///open-api/V2/rest/bridge

// Domainnamen-Zugriff http:///open-api/V2/rest/bridge

2.2 Geräte-Anzeigekategorie & Fähigkeiten

• **Geräte-Anzeigekategorie (DisplayCategory). **Die Geräte-Anzeigekategorie wird verwendet, um spezifische Kategorien (des Geräts) zu identifizieren, wie z. B. switch, plug, light usw. Diese Informationen bestimmen die UI-Anzeigedarstellung des Geräts im Gateway.

• **Geräte-Fähigkeit. **Die Gerätefähigkeit wird verwendet, um die spezifischen Unterfunktionen des Geräts zu beschreiben. Zum Beispiel Leistungssteuerung, Helligkeitsregelung, Farbtemperaturregelung usw. Ein einzelnes Gerät kann 1 oder mehr Fähigkeiten unterstützen.

  • capability: Beschreibt den Namen der Fähigkeit, der weltweit eindeutig sein muss und vom Typ String ist. Mehrere englische Wörter sollten durch Bindestriche ("-") getrennt werden. Zum Beispiel: "thermostat-target-setpoint".

  • name: Beschreibt die Kategorie unterhalb der Fähigkeit, ebenfalls vom Typ String. Mehrere englische Wörter sollten durch Bindestriche ("-") getrennt werden. Zum Beispiel: "auto-mode", "manual-mode".

  • permission: Beschreibt die mit der Fähigkeit verbundenen Berechtigungen. Der Typ ist String, formatiert als 8421-Binärcode. Beispiele schließen ein:

    • Gerät steuerbar: "1000"

    • Gerät konfigurierbar: "0010"

    • Gerät steuerbar und konfigurierbar: "1010"

    • Gerät steuerbar und berichtsfähig: "1100"

Die Bedeutung jedes Bits, von rechts nach links, ist wie folgt: ⅰ. Bit 0: Erlaubt das Abfragen des Geräts ⅱ. Bit 1: Erlaubt das Konfigurieren des Geräts ⅲ. Bit 2: Erlaubt dem Gerät, Daten zu melden ⅳ. Bit 3: Erlaubt das Steuern des Geräts

const permission = {
  "update": "1000",
  "updated": "0100",
  "configure": "0010",
  "query": "0001",  
  "update-updated": "1100",
  "update-query": "1001",
  "update-updated-configure": "1110",
  "updated-configure":"0110",
  "update-updated-query":"1101"
}

settings: Beschreibt die Konfigurationselemente für die Fähigkeit, die vom Typ Objekt sind und eine Beschreibung jedes Konfigurationselements enthalten. ⅰ. key: Beschreibt den Namen des Konfigurationselements, der vom Typ String ist. Mehrere englische Wörter sollten in camelCase ausgedrückt werden. Zum Beispiel: "temperatureUnit". ⅱ. value: Beschreibt den Inhalt des Konfigurationselements. Die spezifischen Spezifikationen werden in der folgenden Tabelle detailliert beschrieben.

Attribut	Typ	Optional	Beschreibung
permission	string	N	Beschreibt die Berechtigungen für das Konfigurationselement.
Optionale Werte:

• Erlaubt die Änderung dieses Konfigurationselements: "10"

• Erlaubt das Anzeigen dieses Konfigurationselements: "01"

• Erlaubt sowohl das Ändern als auch das Anzeigen dieses Konfigurationselements: "11"

Bit-Erklärung:

1. Bit 0: Erlaubt das Anzeigen dieses Konfigurationselements

2. Bit 1: Erlaubt die Änderung dieses Konfigurationselements | | type | string | N | Beschreibt den Datentyp des Werts des Konfigurationselements. Optionale Werte:

• "enum"

• "numeric"

• "object"

• "boolean"

• "string"

Typ-spezifische Richtlinien:

1. Wenn **type = enum**:

   • Das value Feld (das den Wert des Konfigurationselements beschreibt) ist erforderlich, wenn permission Änderung erlaubt ("10" oder "11").

   • Das default (das den Standardwert des Konfigurationselements beschreibt) und values (die die auswählbaren Werte für das Konfigurationselement beschreiben) Felder optional sind.

2. Wenn **type = numeric**:

   • Das value Feld ist erforderlich, wenn permission Änderung erlaubt ("10" oder "11").

   • Die folgenden Felder sind optional:

     • min (beschreibt den Minimalwert des Konfigurationselements)

     • max (beschreibt den Maximalwert des Konfigurationselements)

     • step (beschreibt den Schrittwert für das Konfigurationselement)

     • precision (beschreibt die Genauigkeit)

     • unit (beschreibt die Einheit des Konfigurationselements)

     • default (beschreibt den Standardwert)

3. Wenn **type = object**:

   • Das value Feld ist erforderlich, wenn permission Änderung erlaubt ("10" oder "11").

   • Das default Feld ist optional.

4. Wenn **type = boolean**:

   • Das value Feld ist erforderlich, wenn permission Änderung erlaubt ("10" oder "11").

   • Das default Feld ist optional.

5. Wenn **type = string**:

   • Das value Feld ist erforderlich, wenn permission Änderung erlaubt ("10" oder "11").

   • Das default Feld ist optional. |

// type = enum
{
  "settings":{
    "temperatureUnit": {
      "type": "enum",
      "permission": "11", 
      "values": ["c", "f"], 
      "default": "c",
      "value": "f"
    }
  }
}
// type = numeric
{
  "settings": {
    "setpointRange": {
      "type": "numeric", 
      "permission": "01", 
      "min": 4, 
      "max": 35,
      "default": 20,
      "step": 0.5,
      "precision": 0.01
      "unit": "c"
    }
  }
}

// type = object
{
  "settings":{
    "weeklySchedule":{
      "type": "object",
      "permission": "11", 
      "value": {
        "maxEntryPerDay": 2, 
        "Monday": [
          {
            "startTimeInMinutes": 440, 
            "upperSetpoint": 36.5 
          },
          {
            "startTimeInMinutes": 900,
            "upperSetpoint": 26.5 
          }
        ]，
        "Tuesday": [...],
        "Wednesday": [...],
        "Thursday": [...],
        "Friday": [...],
        "Saturday": [...],
        "Sunday": [...],
      }
    }
  }
}

3.Web-API

Datentyp

Typ	Beschreibung
string	String-Datentyp. UTF8-kodiert.
number	Zahlendatentyp. Doppelpräzisions-64-Bit-Binärformat IEEE 754
int	Ganzzahldatentyp.
object	Objektdatentyp. JSON-konformes Objekt
string[]	Array von Strings
int[]	Array von Ganzzahlen
object[]	Array von Objekten
bool	Boolean
date	Zeitstring. String im ISO-Format (ISO 8601 Erweitertes Format): YYYY-MM-DDTHH:mm:ss.sssZ. Die Zeitzone ist immer UTC (Coordinated Universal Time), gekennzeichnet durch ein Suffix "Z".

Allgemeine Antwortergebnisse

Attribut	Typ	Optional	Beschreibung
error	int	N	Fehlercode:
0: Erfolg
400: Parameterfehler
401: Authentifizierung fehlgeschlagen
500: Serverausnahme
data	object	N	Antwort-Datenkörper
message	string	N	Antwortbeschreibung:
Wenn error gleich 0 ist, lautet der Inhalt success
Wenn error ungleich 0 ist, ist es ein nicht-leerer String und der Inhalt ist eine Fehlerbeschreibung.

Antwortbeispiel:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

{
  "error": 400,
  "data": {},
  "message": "invalid parameters"
}

Ressourcenliste

Typ	Beschreibung
Unterstützte Sounds	- alert1 (Alarmton 1)

• alert2 (Alarmton 2)

• alert3 (Alarmton 3)

• alert4 (Alarmton 4)

• alert5 (Alarmton 5)

• doorbell1 (Türklingelton 1)

• doorbell2 (Türklingelton 2)

• doorbell3 (Türklingelton 3)

• doorbell4 (Türklingelton 4)

• doorbell5 (Türklingelton 5)

• alarm1 (Alarmton 1)

• alarm2 (Alarmton 2)

• alarm3 (Alarmton 3)

• alarm4 (Alarmton 4)

• alarm5 (Alarmton 5) | | Unterstützte Deep | - bootComplete (Systemstart abgeschlossen)

• networkConnected (Netzwerk verbunden)

• networkDisconnected (Netzwerk getrennt)

• systemShutdown (Systemabschaltung) -deviceDiscovered (Gerät entdeckt)

• system Armed (System aktiviert)

• system Disarmed (System deaktiviert)

• factoryReset (Gerät zurücksetzen) |

3.1 Die Gateway-Funktion

a. Access Token

Ermöglicht Benutzern den Zugriff auf das Token.

• Hinweis: Das Token wird nach dem Zurücksetzen des Geräts gelöscht.

• Hinweis: Nach dem Erhalt des Tokens müssen Sie die Taste erneut drücken, um erfolgreich ein neues Token zu erhalten.

:::tips

• URL：/open-api/V2/rest/bridge/access_token

• Methode：GET

• Header：

  • Content-Type: application/json ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
app_name	string	Y	Beschreibung des Anwendungsnamens.

Erfolgreiche Datenantwort:

Attribut	Typ	Optional	Beschreibung
token	string	N	Das Zugriffs-Token der Schnittstelle. Es ist langfristig gültig, bitte speichern Sie es
app_name	string	Y	Beschreibung des Anwendungsnamens.

:::tips Bedingung: Benutzer löst die < command key > aus und ruft diese Schnittstelle innerhalb der gültigen Zeit auf. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

Fehlerhafte Datenantwort：leeres Objekt :::tips Bedingungen：Der Benutzer hat die < command key > nicht ausgelöst, oder die gültige Zeit ist abgelaufen. **Statuscode: ** 200 OK ::: Antwortbeispiel:

{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

b. Den Status des Gateways abrufen

Ermöglicht autorisierten Benutzern, den Status des Gateways über diese Schnittstelle abzurufen :::tips

• URL：/open-api/V2/rest/bridge/runtime

• Methode：GET

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter: keine Erfolgreiche Datenantwort:

Attribut	Typ	Optional	Beschreibung
ram_used	int	N	RAM-Nutzungsprozentsatz. [0-100]
cpu_used	int	N	CPU-Nutzungsprozentsatz. [0-100]
power_up_time	date	N	Die letzte Einschaltzeit
cpu_temp	int	N	CPU-Temperatur:
Einheit: Celsius
cpu_temp_unit	string	N	CPU-Temperatur-Einheit:
Optional
Werte:'c', 'f'
sd_card_used	int	Y	SD-Karten-Nutzung (Prozentsatz):
Bereich:[0-100] mit einer Dezimalstelle Genauigkeit
*Hinweis: Wenn die SD-Karte nicht eingesetzt oder nicht formatiert ist, ist der Wert leer.

:::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {
    "ram_used": 40,
    "cpu_used": 30,
    "power_up_time": "2022-10-12T02:58:09.989Z",
    "cpu_temp": 51,
    "cpu_temp_unit": "c",
    "sd_card_used" : "12"
  },
  "message": "success"
}

c. Gateway konfigurieren

Ermöglicht autorisierten Benutzern, das Gateway über diese Schnittstelle zu konfigurieren :::tips

• URL：/open-api/V2/rest/bridge/config

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
volume	int	Y	Systemlautstärke. [0-100]

Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

d. Gateway-Informationen abrufen

Ermöglicht autorisierten Benutzern, die Gateway-Informationen über diese Schnittstelle zu erhalten :::tips

• URL：/open-api/V2/rest/bridge

• Methode：GET

• Header：

  • Content-Type: application/json ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
ip	string	N	IP-Adresse
mac	string	N	MAC-Adresse
domain	string	Y	Gateway-Service-Domain
fw_version	string	N	Firmware-Version
name	string	N	Gerätename

Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Keine **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {
    "ip": "192.168.31.25",
    "mac": "00:0A:02:0B:03:0C",
    "domain": "ihost.local",
    "fw_version": "1.9.0",
    "name": "iHost"
  },
  "message": "success"
}

e. Gateway stummschalten

Ermöglicht autorisierten Benutzern, das Gateway über diese Schnittstelle stummzuschalten. :::tips

• URL：/open-api/v2/rest/bridge/mute

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Gateway lautlos schalten

Ermöglicht autorisierten Benutzern, das Gateway über diese Schnittstelle wieder laut zu schalten. :::tips

• URL：/open-api/v2/rest/bridge/unmute

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

g. Gateway-Alarm abbrechen

Ermöglicht autorisierten Benutzern, den Alarmtonzustand des Gateways über diese Schnittstelle zu deaktivieren. :::tips

• URL：/open-api/v2/rest/bridge/cancel_alarm

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.2 Hardware-Funktion

a. Gateway neu starten

Ermöglicht einem autorisierten Benutzer, das Gateway über diese Schnittstelle neu zu starten :::tips

• URL：/open-api/V2/rest/hardware/reboot

• Methode：POST

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter: keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK :::

{
  "error": 0,
  "data": {},
  "message": "success"
}

b. Lautsprechersteuerung

Ermöglicht autorisierten Benutzern, den Lautsprecher über diese Schnittstelle zu steuern :::tips

• URL：/open-api/V2/rest/hardware/speaker

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
type	string	N	Optionale Parameter: 1.play_sound (Ton abspielen) 2.play_beep (Piepston abspielen)
sound	SoundObject	Y (N wenn type play_sound ist.)	Der Sound.
beep	BeepObject	Y (N wenn type play_beep ist.)	Der Piepston

SoundObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Der Soundname. Die unterstützten Werte können in [Resource List - Supported sound] nachgeprüft werden
volume	int	N	Die Lautstärke des Sounds. [0-100]
countdown	int	N	Die Dauer, für die der Lautsprecher den Ton abspielt; er stoppt automatisch, wenn die Zeit abgelaufen ist. Einheit: Sekunde. [0,1799]

BeepObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Der Deep-Name. Die unterstützten Werte können in [Resource List - Supported deep] nachgeprüft werden
volume	int	N	Die Deep-Lautstärke. [0-100]

Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: ** 200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.3 Geräteverwaltungs-Funktion

a. Unterstützter Gerätetyp

Gerätetyp	Wert	iHost-Version
Steckdose	plug	≥ 2.1.0
Schalter	switch	≥ 2.1.0
Licht	light	≥ 2.1.0
Vorhang	curtain	≥ 2.1.0
Tür-/Fenstersensor	contactSensor	≥ 2.1.0
Bewegungssensor	motionSensor	≥ 2.1.0
Temperatursensor	temperatureSensor	≥ 2.1.0
Feuchtigkeitssensor	humiditySensor	≥ 2.1.0
Temperatur- und Feuchtigkeitssensor	temperatureAndHumiditySensor	≥ 2.1.0
Wasserleckdetektor	waterLeakDetector	≥ 2.1.0
Rauchmelder	smokeDetector	≥ 2.1.0
Drahtlose Taste	button	≥ 2.1.0
Kamera	camera	≥ 2.1.0
Allgemeiner Sensor	sensor	≥ 2.1.0
Allgemeiner Sensor	sensor	≥ 2.1.0
Deckenventilator mit Licht	fanLight	≥ 2.1.0
Klimaanlage	airConditioner	≥ 2.1.0
Ventilator	fan	≥ 2.1.0
Thermostat	thermostat	≥ 2.1.0

b. Unterstützte Gerätefunktionen

Netzschalter (power):

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "power", // Funktionsname
    "permission": "1100",  // ihost unterstützt die Konfiguration von Soft-Start/Stop nicht, daher kein configure-Feld
  }
]

Zustandsattribut:

{
  "powerState": "on", // Feld powerState zeigt den Ein/Aus-Zustand der Stromversorgung an. Erforderlich. **Typ:** string. "on" bedeutet eingeschaltet, "off" bedeutet ausgeschaltet, "toggle" bedeutet Umschalten.
}

Protokoll (Statusabfrage & Steuerbefehle):

Einschalten:

{
  "power": {
    "powerState": "on"
  }
}

Ausschalten:

{
  "power": {
    "powerState": "off"
  }
}

Kanalumschaltung (toggle):

Beispiel für Funktionsdeklaration:

Einzelkomponenten-Beispiel:

[
  {
    "capability": "toggle", // Funktionsname
    "permission": "1100",  // Berechtigung
    "name": "1", // Komponentenname, **Typ:** String. Optionale Werte: "1" (Kanal 1), "2" (Kanal 2), "3" (Kanal 3), "4" (Kanal 4) oder andere Werte mit Groß-/Kleinbuchstaben und Zahlen
  }
]

Beispiel für mehrere Komponenten:

[
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "1"
  },
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "2"
  }
]

Zustandsattribut:

{
  "toggleState": "on", // Feld toggleState zeigt den Umschaltzustand des Attributs {name} von {device_id} an. Erforderlich. **Typ:** String. "on" bedeutet aktiviert, "off" bedeutet deaktiviert, "toggle" bedeutet Umschalten.
}

Protokoll (Statusabfrage & Steuerbefehle):

Umschaltformat:

{
  [capability]: {
    [toggle-name]: {
      [toggleState]: [value]
    }
  }
}
Komponente 1 an, Komponente 2 aus:
{
  "toggle": {
    "1": {
      "toggleState": "on"
    },
    "2": {
      "toggleState": "off"
    }
  }
}

Kanal-Sekundenbetrieb (toggle-inching):

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "toggle-inching", // Funktionsname
    "permission": "0010",  // Berechtigung
    "settings": {
      "toggleInchingSetting": {
        "permission": "11",
        "type": "object",
        "value": {
          "supported": {
            "1": { // Komponentenname
              "enable": true, // Ob die Inching-Funktion aktiviert ist. **Typ:** Boolean. Erforderlich.
              "inchingSwitch": "off", // Inching-Schalter-Einstellung. **Typ:** String. Erforderlich. "off" (aus), "on" (an)
              "delay": 1000, // Inching-Verzögerungszeit in Millisekunden. **Typ:** Integer. Erforderlich.
              "min_delay": 500, // Minimale Verzögerungszeit
              "max_delay": 100000 // Maximale Verzögerungszeit
            },
            "2": { // Komponentenname
              "enable": true, // Ob die Inching-Funktion aktiviert ist. **Typ:** Boolean. Erforderlich.
              "inchingSwitch": "off", // Inching-Schalter-Einstellung. **Typ:** String. Erforderlich. "off" (aus), "on" (an)
              "delay": 1000, // Inching-Verzögerungszeit in Millisekunden. **Typ:** Integer. Erforderlich.
              "min_delay": 500, // Minimale Verzögerungszeit
              "max_delay": 100000 // Maximale Verzögerungszeit
            },
            "3": { // Komponentenname
              "enable": true, // Ob die Inching-Funktion aktiviert ist. **Typ:** Boolean. Erforderlich.
              "inchingSwitch": "off", // Inching-Schalter-Einstellung. **Typ:** String. Erforderlich. "off" (aus), "on" (an)
              "delay": 1000, // Inching-Verzögerungszeit in Millisekunden. **Typ:** Integer. Erforderlich.
              "min_delay": 500, // Minimale Verzögerungszeit
              "max_delay": 100000 // Maximale Verzögerungszeit
            },
            "4": { // Komponentenname
              "enable": true, // Ob die Inching-Funktion aktiviert ist. **Typ:** Boolean. Erforderlich.
              "inchingSwitch": "off", // Inching-Schalter-Einstellung. **Typ:** String. Erforderlich. "off" (aus), "on" (an)
              "delay": 1000, // Inching-Verzögerungszeit in Millisekunden. **Typ:** Integer. Erforderlich.
              "min_delay": 500, // Minimale Verzögerungszeit
              "max_delay": 100000 // Maximale Verzögerungszeit
            }
          }
        }
      }
    }
  }
]

Zustandsattribut

Keine

Protokoll (Statusabfrage & Steuerbefehle)

Keine

Helligkeitsanpassung (brightness):

Beispiel für Funktionsdeklaration:

{
  "capability": "brightness", // Funktionsname
  "permission": "1100"  // Berechtigung
}

Zustandsattribut:

{
  "brightness": 100, // Feld brightness gibt die Helligkeitsprozentzahl an. Wähle zwischen brightness oder brightnessDelta. **Typ:** Number. Bereich: 0-100.
}

Protokoll (Statusabfrage & Steuerbefehle):

Setze Helligkeit auf 80%. (0 ist am dunkelsten und 100 am hellsten.)

json
复制代码
{
  "brightness": {
    "brightness": 80
  }
}

Farbtemperaturanpassung (color-temperature):

Beispiel für Funktionsdeklaration:

{
  "capability": "color-temperature", // Funktionsname
  "permission": "1100"  // Berechtigung
}

Zustandsattribut:

{
  "colorTemperature": 100, // Feld colorTemperature gibt die Prozentzahl der Farbtemperatur an. Wähle zwischen colorTemperature oder colorTemperatureDelta. **Typ:** Number. Bereich: 0-100. 0 bedeutet warmes Licht, 50 bedeutet neutrales Licht, 100 bedeutet kühles Licht.
}

Protokoll (Statusabfrage & Steuerbefehle):

Farbtemperatur auf 50% einstellen:

json
 
{
  "color-temperature": {
    "colorTemperature": 50
  }
}

Farbregelung (color-rgb):

Beispiel für Funktionsdeklaration:

{
  "capability": "color-rgb", // Funktionsname
  "permission": "1100"  // Berechtigung
}

Zustandsattribut:

{
  "red": 255, // Feld red repräsentiert die rote Farbe im RGB-Farbraum. Erforderlich. **Typ:** Number. Bereich: 0-255.
  "green": 0, // Feld green repräsentiert die grüne Farbe im RGB-Farbraum. Erforderlich. **Typ:** Number. Bereich: 0-255.
  "blue": 255 // Feld blue repräsentiert die blaue Farbe im RGB-Farbraum. Erforderlich. **Typ:** Number. Bereich: 0-255.
}

Protokoll (Statusabfrage & Steuerbefehle):

Farbe auf Violett einstellen:

{
  "color-rgb": {
    "red": 255,
    "green": 0,
    "blue": 255
  }
}

Prozentuale Anpassung (percentage):

Beispiel für Funktionsdeklaration:

{
  "capability": "percentage",
  "permission": "1100",
  "settings": { // Optional
    "percentageRange": {
      "permission": "01",
      "type": "numeric",
      "min": 0,
      "max": 100,
      "step": 5
    }
  }
}

Zustandsattribut:

{
  "percentage": 100, // Feld percentage gibt einen Prozentwert an. Wähle zwischen percentage oder percentageDelta. **Typ:** Number. Bereich: 0-100.
}

Protokoll (Statusabfrage & Steuerbefehle):

Auf 40% einstellen:

{
  "percentage": {
    "percentage": 40
  }
}

Motorsteuerung (motor-control):

Beispiel für Funktionsdeklaration:

{
  "capability": "motor-control",
  "permission": "1100"
}

Zustandsattribut:

json
 
{
  "motorControl": "stop", // Feld motorControl zeigt den Zustand des Motors an. Erforderlich. **Typ:** String. Mögliche Werte: "open" (öffnen), "close" (schließen), "stop" (stopp), "lock" (verriegeln).
}

Protokoll (Statusabfrage & Steuerbefehle):

Motor öffnen:

{
  "motor-control": {
    "motorControl": "open"
  }
}

Motorumkehr (motor-reverse):

Beispiel für Funktionsdeklaration:

{
  "capability": "motor-reverse",
  "permission": "1100"
}

Zustandsattribut:

{
  "motorReverse": true, // Feld motorReverse zeigt die Drehrichtungseinstellung des Motors an. Erforderlich. **Typ:** Boolean. true bedeutet vorwärts, false bedeutet rückwärts.
}

Protokoll (Statusabfrage & Steuerbefehle):

Motor auf Vorwärts einstellen:

{
  "motor-reverse": {
    "motorReverse": true
  }
}

Motorkalibrierung (motor-clb)

Beispiel für Funktionsdeklaration:

{
  "capability": "motor-clb",
  "permission": "0100"
}

Attribute (Zustand):

{
  "motorClb": "calibration" // Feld motorClb zeigt den Kalibrierungsstatus des Motors an. Erforderlich. **Typ:** String. "normal" bedeutet Normalmodus (kalibriert), "calibration" bedeutet laufende Kalibrierung.
}

Protokoll (Statusmeldung):

Melden, dass Motor kalibriert wird:

{
  "motor-clb": {
    "motorClb": "calibration"
  }
}

Einschaltzustand beim Start (startup)

Beispiel für Funktionsdeklaration:

{
  "capability": "startup",
  "permission": "1100"
}

Attribute (Zustand):

{
  "startup": "on" // Stromzustand beim Start. **Typ:** String. Erforderlich. Optionale Werte: "on" (eingeschaltet), "stay" (eingeschaltet belassen), "off" (ausgeschaltet), "toggle" (Zustand umkehren).
}

Protokoll (Statusabfrage & Steuerbefehle):

Stromzustand auf immer eingeschaltet setzen:

{
  "startup": {
    "startup": "on"
  }
}

---

Aufweckaktivierung (identify)

Beispiel für Funktionsdeklaration:

{
  "capability": "identify",
  "permission": "0100"
}

Attribute (Zustand):

{
  "identify": true // Zeigt an, ob das Gerät aktiv Erkennungsresultate meldet oder aktiviert ist.
}

Protokoll (Statusmeldung & Steuerbefehle):

Aufweckaktivierungszeit einstellen:

{
  "identify": {
    "countdown": 180 // Feld countdown gibt die Countdown-Zeit an. Erforderlich. **Typ:** Number. Einheit: Sekunden.
  }
}

Aktivierungsstatus melden:

{
  "identify": {
    "identify": true // Zeigt an, ob das Gerät aktiv Erkennungsresultate meldet oder aktiviert ist.
  }
}

Echtzeit-Leistungsverbrauchsstatistik-Schalter (power-consumption)

Beispiel für Funktionsdeklaration:

{
  "capability": "power-consumption",
  "permission": "1101",
  "settings": {
    "resolution": {
      "permission": "01",
      "type": "numeric",
      "value": 3600
    },
    "timeZoneOffset": {
      "permission": "01",
      "type": "numeric",
      "min": -12,
      "max": 14,
      "value": 0
    }
  }
}

Attribute (Zustand):

Echtzeitstatistiken starten/beenden:

{
  "rlSummarize": true, // Echtzeitstatistiken starten/beenden. **Typ:** Boolean. Erforderlich.
  "timeRange": { // Zusammengefasster Zeitraum. Erforderlich.
    "start": "2020-07-05T08:00:00Z", // Startzeit der Verbrauchsstatistik. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Endzeit der Verbrauchsstatistik. **Typ:** String. Erforderlich.
  }
}

Leistungsverbrauch nach Zeitraum abfragen:

{
  "type": "summarize", // Art der Statistik. **Typ:** String. Erforderlich. Optionale Werte: "rlSummarize" (Echtzeit-Zusammenfassung), "summarize" (aktuelle Zusammenfassung).
  "timeRange": { // Zusammengefasster Zeitraum. Erforderlich, wenn type = "summarize".
    "start": "2020-07-05T08:00:00Z", // Startzeit der Verbrauchsstatistik. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Endzeit der Verbrauchsstatistik. **Typ:** String. Optional. Wenn weggelassen, bedeutet dies die aktuelle Zeit.
  }
}

Mit Statistikergebnis für den Zeitraum antworten:

json
 
{
  "type": "summarize", // Art der Statistik. **Typ:** String. Erforderlich. Optionale Werte: "rlSummarize" (Echtzeit-Zusammenfassung), "summarize" (aktuelle Zusammenfassung).
  "rlSummarize": 50.0, // Gesamtverbrauch. **Typ:** Number. Einheit: 0,01 kWh. Optional.
  "electricityIntervals": [ // Mehrere Statistikaufzeichnungen, aufgeteilt entsprechend configuration.resolution. Optional. Nicht vorhanden, wenn type = "rlSummarize".
    {
      "usage": 26.5, // Verbrauch. **Typ:** Number. Einheit: 0,01 kWh. Erforderlich.
      "start": "2020-07-05T08:00:00Z", // Startzeit. **Typ:** Datum. Erforderlich.
      "end": "2020-07-05T09:00:00Z" // Endzeit. **Typ:** Datum. Erforderlich. Wenn das Intervall zwischen end und start kleiner als resolution ist, gelten alle gemeldeten Datensätze als ungültig.
    },
    {
      "usage": 26.5, // Verbrauch. **Typ:** Number. Einheit: 0,01 kWh. Erforderlich.
      "start": "2020-07-05T09:00:00Z", // Startzeit. **Typ:** Datum. Erforderlich.
      "end": "2020-07-05T10:00:00Z" // Endzeit. **Typ:** Datum. Erforderlich. Wenn das Intervall zwischen end und start kleiner als resolution ist, gelten alle gemeldeten Datensätze als ungültig.
    }
  ]
}

Protokoll (Statusmeldung & Steuerbefehle):

Echtzeitstatistiken starten:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}

Echtzeitstatistiken beenden:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Historischen Energieverbrauch abrufen:

json
 
{
  "power-consumption": {
    "type": "summarize",
    "timeRange": {
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z"
    }
  }
}

Echtzeit-Energieverbrauch abrufen:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "type": "rlSummarize"
    }
  }
}

Erkennungsmodus für Temperatur und Luftfeuchtigkeit (thermostat-mode-detect)

Beispiel für Funktionsdeklaration:

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "temperature", // Typ der Temperaturkontrollerkennung. **Typ:** String. Erforderlich. Optionale Werte: "humidity" (Feuchtigkeitsdetektion), "temperature" (Temperaturdetektion).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Unterstützte Erkennungseinstellungen. Erforderlich.
          {
            "name": "lowerSetpoint", // Der erkannte Wert sollte über diesem Sollwert liegen. Mindestens eines von lowerSetpoint oder upperSetpoint ist erforderlich.
            "value": { // Erkennungsbereich. Optional. Angeben, wenn Voreinstellungen bestehen.
              "value": 68.0, // Temperaturwert. **Typ:** Number. Erforderlich.
              "scale": "f" // Temperatureinheit. Erforderlich, wenn name=temperature. Optionale Werte: "c" (Celsius), "f" (Fahrenheit).
            }
          },
          {
            "name": "upperSetpoint", // Der erkannte Wert sollte unter diesem Sollwert liegen. Mindestens eines von lowerSetpoint oder upperSetpoint ist erforderlich.
            "value": { // Erkennungsbereich. Optional. Angeben, wenn Voreinstellungen bestehen.
              "value": 68.0, // Temperaturwert. **Typ:** Number. Erforderlich.
              "scale": "f" // Temperatureinheit. Erforderlich, wenn name=temperature. Optionale Werte: "c" (Celsius), "f" (Fahrenheit).
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "humidity", // Typ der Temperaturkontrollerkennung. **Typ:** String. Erforderlich. Optionale Werte: "humidity" (Feuchtigkeitsdetektion), "temperature" (Temperaturdetektion).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Unterstützte Erkennungseinstellungen. Erforderlich.
          {
            "name": "lowerSetpoint", // Der erkannte Wert sollte über diesem Sollwert liegen. Mindestens eines von lowerSetpoint oder upperSetpoint ist erforderlich.
            "value": { // Erkennungsbereich. Optional. Angeben, wenn Voreinstellungen bestehen.
              "value": 68.0, // Feuchtigkeitswert. **Typ:** Number. Erforderlich
            }
          },
          {
            "name": "upperSetpoint", // Der erkannte Wert sollte unter diesem Sollwert liegen. Mindestens eines von lowerSetpoint oder upperSetpoint ist erforderlich.
            "value": { // Erkennungsbereich. Optional. Angeben, wenn Voreinstellungen bestehen.
              "value": 68.0, // Feuchtigkeitswert. **Typ:** Number. Erforderlich
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

Attribute (Zustand):

{
  "mode": "COMFORT" // Mode-ID. Optional. Unterstützte Werte: "COMFORT" (Komfortmodus), "COLD" (Kaltmodus), "HOT" (Heißmodus), "DRY" (Trockenmodus), "WET" (Feuchtmodus).
}

Protokoll (Statusabfrage & Steuerbefehle):

Format:

{
    [capability] :{
        [mode name] :{
            "mode": [value]
        }
    }
}

Beispiel:

{
  "thermostat-mode-detect": {
    "humidity": {
      "mode": "COMFORT"
    }
  }
}

Thermostatmodus (thermostat-mode)

Beispiel für Funktionsdeklaration:

{
  "capability": "thermostat",
  "permission": "1100",
  "name": "thermostat-mode",
  "settings": {
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "MANUAL",
        "AUTO",
        "ECO"
      ]
    }
  }
}

Attribute (Zustand):

{
  "thermostatMode": "MANUAL" // Betriebsmodus des Thermostats. **Typ:** String. Optionale Werte: "MANUAL", "AUTO", "ECO".
}

Protokoll (Statusabfrage & Steuerbefehle):

{
   "thermostat": {
    "thermostat-mode": {
      "thermostatMode": "MANUAL"
    }
  }
}

Adaptive Wiederherstellungsstatus des Thermostats (thermostat/adaptive-recovery-status)

Beispiel für Funktionsdeklaration:

{
  "capability": "thermostat",
  "permission": "0100",
  "name": "adaptive-recovery-status" // Adaptiver Wiederherstellungsstatus des Thermostats
}

Attribute (Zustand):

{
  "adaptiveRecoveryStatus": "HEATING" // Adaptiver Wiederherstellungsstatus des Thermostats. **Typ:** String. Optionale Werte: "HEATING", "INACTIVE".
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "thermostat": {
    "adaptive-recovery-status": {
      "adaptiveRecoveryStatus": "HEATING"
    }
  }
}

Thermostat Zieltemperatur-Einstellung (thermostat-target-setpoint)

Beispiel für Funktionsdeklaration:

[[
  {
    "capability": "thermostat-target-setpoint",
    "name": "manual-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "eco-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "auto-mode",
    "permission": "0110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      },
      "weeklySchedule":{
        "type": "object",
        "permission": "11",
        "value": {
          "maxEntryPerDay": 2,
          "Monday": [
          {
            "startTimeInMinutes": 440, // Startzeit in Minuten. **Typ:** int. Z.B. 7:20 = 440 Minuten.
            "upperSetpoint": 36.5, // Maximale Zieltemperatur. **Typ:** number.
            "lowerSetpoint": 20 // Minimale Zieltemperatur. **Typ:** number.
          },
          {
            "startTimeInMinutes": 900, // Startzeit in Minuten. Z.B. 15:00 = 900 Minuten.
            "upperSetpoint": 26.5, // Maximale Zieltemperatur. **Typ:** number.
            "lowerSetpoint": 21 // Minimale Zieltemperatur. **Typ:** number.
          }
        ],
          "Tuesday": [...
          ],
          "Wednesday": [...
          ],
          "Thursday": [...
          ],
          "Friday": [...
          ],
          "Saturday": [...
          ],
          "Sunday": [...
          ],
        }
      }
    }
  }
]

Attribute (Zustand):

{
  "targetSetpoint": 30 // Zieltemperatur für den angegebenen Modus. **Typ:** number, in der durch temperatureUnit angegebenen Einheit.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "thermostat-target-setpoint": {
    "manual-mode": {
        "targetSetpoint": 30 
    },
    "auto-mode": {
        "targetSetpoint": 30 
    }
  }
}

Sensorerkennung (detect)

Beispiel für Funktionsdeklaration:

{
  "capability": "detect",
  "permission": "0110",
  "settings": { // Optional
    "detectInterval": {
      "permission": "11",
      "type": "numeric",
      "value": 300
    },
    "detectSensitivity": {
      "permission": "11",
      "type": "numeric",
      "value": 1000
    }
  }
}

Attribute (Zustand):

{
  "detected": true // Erkennungsergebnis. **Typ:** Boolean. `true` bedeutet erkannt, `false` bedeutet nicht erkannt.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
    "detect": {
        "detected": true
    }
}

Temperaturerkennung (temperature)

Beispiel für Funktionsdeklaration:

{
  "capability": "temperature",
  "permission": "0110",
  "settings": { // Optional
    "temperatureCalibration": { // Optionale Temperaturkalibrierung
      "type": "numeric",
      "permission": "11",
      "min": -7, // Minimaler Wert
      "max": 7, // Maximaler Wert
      "step": 0.2, // Temperaturanpassungsschritt, Einheit wie temperatureUnit
      "value": 5.2 // Aktueller Kalibrierungswert. **Typ:** number.
    },
    "temperatureUnit": { // Optionale Temperatureinheit
      "type": "enum",
      "permission": "11",
      "value": "c",
      "values": [
        "c",
        "f"
      ]
    },
    "temperatureRange": { // Optionaler Temperatur-Erkennungsbereich
      "type": "numeric",
      "permission": "01",
      "min": -40,
      "max": 80
    }
  }
}

Attribute (Zustand):

json
复制代码
{
  "temperature": 26.5 // Aktuelle Temperatur. **Typ:** Number, in Celsius.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "temperature": {
    "temperature": 20
  }
}

Feuchtigkeitserkennung (humidity)

Beispiel für Funktionsdeklaration:

{
  "capability": "humidity",
  "permission": "0100",
  "settings": { // Optionaler Feuchtigkeits-Erkennungsbereich.
    "humidityRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 100
    }
  }
}

Attribute (Zustand):

{
  "humidity": 50 // Aktuelle relative Luftfeuchtigkeit (Prozent). **Typ:** Number, Bereich 0-100.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
    "humidity": {
        "humidity": 20
    }
}

Batterieerkennung (battery)

Beispiel für Funktionsdeklaration:

{
  "capability": "battery",
  "permission": "0100"
}

Attribute (Zustand):

{
  "battery": 95 // Verbleibender Batteriestand in Prozent. **Typ:** Number, Bereich -1 bis 100. Hinweis: -1 bedeutet unbekannter Batteriestand.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "battery": {
    "battery": 40
  }
}

Einzeltastenerkennung (press)

Beispiel für Funktionsdeklaration:

{
  "capability": "press",
  "permission": "1100",
  "settings": { // Optional
    "actions": { // Tastenaktionen, optional.
      "type": "enum",
      "permission": "01",
      "values": [ // Optionale Tastenaktionen. Standardwerte sind "singlePress", "doublePress", "longPress". Konfigurierte Aktionen ersetzen die Standardwerte.
      ]
    }
  }
}

Attribute (Zustand):

{
  "press": "singlePress" // Tastendrucktyp. **Typ:** String. Standardwerte: "singlePress" (einfacher/kurzer Druck), "doublePress" (Doppeldruck), "longPress" (Langer Druck).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "press": {
    "press": "singlePress"
  }
}

Mehrfachtastenerkennung (multi-press)

Beispiel für Funktionsdeklaration:

{
  "capability": "multi-press",
  "permission": "0100",
  "name": "1", // Name des multi-press-Attributs. **Typ:** String. Es sind nur alphanumerische Zeichen erlaubt.
  "settings": { // Optional
    "actions": { // Tastenaktionen, optional.
      "type": "enum",
      "permission": "01",
      "values": [ // Optionale Tastenaktionen. Standardwerte sind "singlePress", "doublePress", "longPress". Konfigurierte Aktionen ersetzen die Standardwerte.
      ]
    }
  }
}

Attribute (Zustand):

{
  "press": "singlePress" // Tastendrucktyp. **Typ:** String. Standardwerte: "singlePress" (einfacher/kurzer Druck), "doublePress" (Doppeldruck), "longPress" (Langer Druck).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
    [capability] :{
        [multi-press-name]：{
            press:[value]
        }
    }
}

beispiel:
{
  "multi-press": {
    "1": {
      "press": "singlePress"
    },
    "2": {
      "press": "doublePress"
    }
  }
}

Signalstärke-Erkennung (rssi)

Beispiel für Funktionsdeklaration:

{
  "capability": "rssi",
  "permission": "0100"
}

Attribute (Zustand):

{
  "rssi": -65 // Drahtlose Signalstärke (Received Signal Strength Indicator). **Typ:** Number, Einheit dBm, negative Ganzzahlen.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "rssi": {
    "rssi": -65
  }
}

Manipulationsalarm (tamper-alert)

Beispiel für Funktionsdeklaration:

{
  "capability": "tamper-alert",
  "permission": "0100"
}

Attribute (Zustand):

{
  "tamper": "clear" // Manipulationsstatus. **Typ:** String. Mögliche Werte: "clear" (nicht manipuliert), "detected" (manipuliert).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "tamper-alert": {
    "tamper": "clear" // Manipulationsstatus. **Typ:** String. Mögliche Werte: "clear" (nicht manipuliert), "detected" (manipuliert).
  }
}

Beleuchtungsstärkeerkennung (illumination-level)

Beispiel für Funktionsdeklaration:

{
  "capability": "illumination-level",
  "permission": "0100"
}

Attribute (Zustand):

{
  "level": "brighter" // Helligkeitspegel. **Typ:** String. Mögliche Werte: "brighter" (heller), "darker" (dunkler).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "illumination-level": {
    "level": "brighter"
  }
}

Spannungserkennung (voltage)

Beispiel für Funktionsdeklaration:

{
  "capability": "voltage",
  "permission": "0100"
}

Attribute (Zustand):

{
  "voltage": 50 // Aktueller Spannungswert, in 0,01V-Einheiten. **Typ:** Number, nicht-negative Werte.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "voltage": {
    "voltage": 50
  }
}

Stromstärke-Erkennung (electric-current)

Beispiel für Funktionsdeklaration:

{
  "capability": "electric-current",
  "permission": "0100"
}

Attribute (Zustand):

{
  "electric-current": 50 // Aktueller Stromwert, in 0,01A-Einheiten. **Typ:** Number, nicht-negative Ganzzahlen.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "electric-current": {
    "electric-current": 50
  }
}

Leistungserkennung (electric-power)

Beispiel für Funktionsdeklaration:

{
  "capability": "electric-power",
  "permission": "0100"
}

Attribute (Zustand):

{
  "electric-power": 50 // Aktueller Leistungswert, in 0,01W-Einheiten. **Typ:** Number, nicht-negative Ganzzahlen.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "electric-power": {
    "electric-power": 50
  }
}

Fehlererkennung (fault)

Beispiel für Funktionsdeklaration:

{
  "capability": "fault",
  "permission": "0100"
}

Attribute (Zustand):

{
  "fault": "none" // Fehlerstatus. **Typ:** String. Mögliche Werte: "none" (kein Fehler), "detected" (Fehler erkannt).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "fault": {
    "fault": "none"
  }
}

Schwellwertunterbrecher (threshold-breaker)

Beispiel für Funktionsdeklaration:

{
  "capability": "threshold-breaker",
  "permission": "0010",
  "settings": {
    "supportedSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "supported": [
          {
            "name": "lowerPower", // Niedriger Leistungs-Schwellenwert-Unterbrecher
            "value": {
              "value": 50, // Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 3500 // Maximaler Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "upperPower", // Hoher Leistungs-Schwellenwert-Unterbrecher
            "value": {
              "value": 50, // Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 3500 // Maximaler Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "lowerElectricCurrent", // Niedriger Strom-Schwellenwert-Unterbrecher
            "value": {
              "value": 50, // Erkennungstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 1500 // Maximaler Erkennungstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "upperElectricCurrent", // Hoher Strom-Schwellenwert-Unterbrecher
            "value": {
              "value": 50, // Erkennungstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 1500 // Maximaler Erkennungstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "lowerVoltage", // Niedriger Spannungs-Schwellenwert-Unterbrecher
            "value": {
              "value": 50, // Erkennungs-Spannungswert, in 0,01V-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungs-Spannungswert, in 0,01V-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 24000 // Maximaler Erkennungs-Spannungswert, in 0,01V-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "upperVoltage", // Hoher Spannungs-Schwellenwert-Unterbrecher
            "value": {
              "value": 50, // Erkennungs-Spannungswert, in 0,01V-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungs-Spannungswert, in 0,01V-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 24000 // Maximaler Erkennungs-Spannungswert, in 0,01V-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          }
        ]
      }
    }
  }
}

Attribute (Zustand)

• Keine

Protokoll (Statusabfrage & Steuerbefehle)

• Keine

Inch-Funktion (inching)

Beispiel für Funktionsdeklaration:

{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // Einstellung zum Aktivieren der Inch-Funktion
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Einstellung der Inch-Aktion
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Einstellung der Inchtime
      "type": "numeric",
      "permission": "11",
      "min": 500,
      "max": 100000,
      "value": 1000,
      "unit": "ms"
    }
  }
}

Attribute (Zustand):

• Keine

Protokoll (Statusabfrage & Steuerbefehle):

• Keine

Kamera-Stream (camera-stream)

Beispiel für Funktionsdeklaration:

{
  "capability": "camera-stream",
  "permission": "0010",
  "settings": {
    "streamSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "username": "String", // Zugangsaccount. **Typ:** String. Erforderlich.
        "password": "String", // Zugangspasswort. **Typ:** String. Erforderlich.
        "streamUrl": "rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01", // Stream-URL. **Typ:** String. Erforderlich.
        "videoCodec": "", // Videocodec. **Typ:** String. Erforderlich. Optionale Parameter sind zu definieren.
        "resolution": { // Videoauflösung. Erforderlich.
          "width": 1080, // Breite. **Typ:** Number. Erforderlich.
          "height": 720 // Höhe. **Typ:** Number. Erforderlich.
        },
        "keyFrameInterval": 5, // Keyframe-Intervall. **Typ:** String. Erforderlich.
        "audioCodec": "G711", // Audiocodec. **Typ:** String. Erforderlich. Optionale Parameter sind zu definieren.
        "samplingRate": 50, // Audioabtastrate in Hz. **Typ:** Number. Erforderlich. Optionale Parameter sind zu definieren.
        "dataRate": 50 // Datenrate. **Typ:** Number. Erforderlich. Einheit: kb/s.
      }
    }
  }
}

Attribute (Zustand):

• Keine

Protokoll (Statusabfrage & Steuerbefehle):

• Keine

Modussteuerung (mode)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "mode",
    "name": "fanLevel",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["low", "medium", "high"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben die Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "thermostatMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["auto", "manual"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben die Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "airConditionerMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["cool", "heat", "auto", "fan", "dry"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben die Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "fanMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["normal", "sleep", "child"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben die Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "horizontalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben die Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "verticalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben die Standardwerte.
      }
    }
  }
]

Attribute (Zustand):

{
  "modeValue": "low" // Moduswert. **Typ:** String. Erforderlich. Siehe unterstützte Voreinstellungen.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "mode": {
    "fanLevel": {
      "modeValue": "low"
    }
  }
}

Kohlendioxid-Erkennung (co2)

Beispiel für Funktionsdeklaration:

{
  "capability": "co2",
  "permission": "0100",
  "settings": {
    "co2Range": {
      "type": "numeric",
      "permission": "01",
      "min": 400,
      "max": 10000
    }
  }
}

Attribute (Zustand):

{
  "co2": 111 // Kohlendioxidkonzentration. **Typ:** Integer. Einheit: ppm.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "co2": {
    "co2": 500
  }
}

Beleuchtungsstärkeerkennung (illumination)

Beispiel für Funktionsdeklaration:

{
  "capability": "illumination",
  "permission": "0100",
  "settings": {
    "illuminationRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 160000
    }
  }
}

Attribute (Zustand):

{
  "illumination": 11 // Beleuchtungsstärke. **Typ:** Integer. Einheit: lux.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "illumination": {
    "illumination": 50
  }
}

Raucherkennung (smoke)

Beispiel für Funktionsdeklaration:

{
  "capability": "smoke",
  "permission": "0100"
}

Attribute (Zustand):

{
  "smoke": true // Erkennungsergebnis. **Typ:** Boolean. `true` bedeutet erkannt, `false` bedeutet nicht erkannt.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "smoke": {
    "smoke": true
  }
}

Türmagnet Öffnen/Schließen Erkennung (Kontakt)

Beispiel für Funktionsdeklaration:

{
  "capability": "contact",
  "permission": "0100"
}

Attribute (Zustand):

{
  "contact": true // Erkennungsergebnis. **Typ:** Boolean. `true` bedeutet Erkennung, `false` bedeutet keine Erkennung.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "contact": {
    "contact": true
  }
}

Bewegungserkennung (motion)

Beispiel für Funktionsdeklaration:

{
  "capability": "motion",
  "permission": "0110",
  "settings": {
    "motionInterval": {
      "type": "numeric",
      "permission": "11",
      "value": 300
    },
    "motionSensitivity": {
      "type": "numeric",
      "permission": "11",
      "value": 1000
    }
  }
}

Attribute (Zustand):

{
  "motion": true // Erkennungsergebnis. **Typ:** Boolean. `true` bedeutet Erkennung, `false` bedeutet keine Erkennung.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "motion": {
    "motion": true
  }
}

Wasserleck-Erkennung (water-leak)

Beispiel für Funktionsdeklaration:

{
  "capability": "water-leak",
  "permission": "0100"
}

Attribute (Zustand):

{
  "waterLeak": true // Feld `waterLeak` zeigt das aktuelle Erkennungsergebnis an. **Typ:** Boolean. `true` bedeutet Erkennung, `false` bedeutet keine Erkennung.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "water-leak": {
    "waterLeak": true
  }
}

Fenstererkennungsschalter (window-detection)

Beispiel für Funktionsdeklaration:

{
  "capability": "window-detection",
  "permission": "1100"
}

Attribute (Zustand):

{
  "powerState": "on" // Feld `powerState` zeigt den Stromzustand an. **Typ:** String. `on` bedeutet Strom an, `off` bedeutet Strom aus.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "window-detection": {
    "powerState": "on"
  }
}

Kindersicherungsschalter (child-lock)

Beispiel für Funktionsdeklaration:

{
  "capability": "child-lock",
  "permission": "1100"
}

Attribute (Zustand):

{
  "powerState": "on" // Feld `powerState` zeigt den Stromzustand an. **Typ:** String. `on` bedeutet Strom an, `off` bedeutet Strom aus.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "child-lock": {
    "powerState": "on"
  }
}

Anti-Direktstoß-Schalter (anti-direct-blow)

Beispiel für Funktionsdeklaration:

{
  "capability": "anti-direct-blow",
  "permission": "1100"
}

Attribute (Zustand):

{
  "powerState": "on" // Feld `powerState` zeigt den Stromzustand an. **Typ:** String. `on` bedeutet Strom an, `off` bedeutet Strom aus.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "anti-direct-blow": {
    "powerState": "on"
  }
}

Horizontaler Schwenkschalter (horizontal-swing)

Beispiel für Funktionsdeklaration:

{
  "capability": "horizontal-swing",
  "permission": "1100"
}

Attribute (Zustand):

{
  "powerState": "on" // Feld `powerState` zeigt den Stromzustand an. **Typ:** String. `on` bedeutet Strom an, `off` bedeutet Strom aus.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "horizontal-swing": {
    "powerState": "on"
  }
}

Vertikaler Schwenkschalter (vertical-swing)

Beispiel für Funktionsdeklaration:

{
  "capability": "vertical-swing",
  "permission": "1100"
}

Attribute (Zustand):

{
  "powerState": "on" // Feld `powerState` zeigt den Stromzustand an. **Typ:** String. `on` bedeutet Strom an, `off` bedeutet Strom aus.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "vertical-swing": {
    "powerState": "on"
  }
}

ECO-Modus-Schalter (eco)

Beispiel für Funktionsdeklaration:

{
  "capability": "eco",
  "permission": "1100"
}

Attribute (Zustand):

{
  "powerState": "on" // Feld `powerState` zeigt den Stromzustand an. **Typ:** String. `on` bedeutet Strom an, `off` bedeutet Strom aus.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "eco": {
    "powerState": "on"
  }
}

Einschaltverhalten umschalten (toggle-startup)

Beispiel für Funktionsdeklaration:

{
  "capability": "toggle-startup",
  "permission": "1100",
  "name": "1" // Feld `name` gibt den Attributnamen für `toggle-startup` an. **Typ:** String. Es sind nur Buchstaben und Zahlen erlaubt.
}

Attribute (Zustand):

{
  "startup": "on" // **Typ:** String. Optionen: `on` (Einschalten), `stay` (Eingeschaltet bleiben), `off` (Ausschalten).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "toggle-startup": {
    "1": {
      "startup": "on"
    },
    "2": {
      "startup": "off"
    }
  }
}

Erkennung halten (detect-hold)

Beispiel für Funktionsdeklaration:

{
  "capability": "detect-hold",
  "permission": "0100",
  "settings": {
    "detectHoldEnable": { // Einstellung zum Aktivieren der Erkennungs-Haltefunktion
      "permission": "01",
      "type": "boolean",
      "value": false
    },
    "detectHoldSwitch": { // Einstellung für die Erkennungs-Halteaktion
      "type": "enum",
      "permission": "01",
      "value": "on",
      "values": ["on", "off"]
    },
    "detectHoldTime": { // Einstellung der Erkennungs-Haltezeit
      "type": "numeric",
      "permission": "01",
      "min": 1,
      "max": 359,
      "value": 5,
      "unit": "minute"
    }
  }
}

Attribute (Zustand):

{
  "detectHold": "on" // Feld `detectHold` zeigt den Zustand der Erkennungs-Haltefunktion an. **Typ:** String. `on` bedeutet Erkennungs-Halt aktiv, `off` bedeutet Erkennungs-Halt inaktiv.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "detect-hold": {
    "detectHold": "on"
  }
}

Umschalten Identifizieren/Aktivieren (toggle-identify)

Beispiel für Funktionsdeklaration:

{
  "capability": "toggle-identify",
  "permission": "1100", // Hinweis: Diese Fähigkeit wird in der aktuellen Version (V1.13.7) auf ihost nicht für Berichte verwendet.
  "name": "1" // Komponentenname. **Typ:** String. Optionale Werte: "1" (Kanal 1), "2" (Kanal 2), "3" (Kanal 3), "4" (Kanal 4).
}

Attribute (Zustand):

{
  "identify": true, // Zeigt an, dass das Gerät aktiv Identifikation oder Aktivierung gemeldet hat.
  "countdown": 180 // Feld `countdown` zeigt die Aktivierungsdauer an. **Typ:** Number. Einheit: Sekunden.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "toggle-identify": {
    "1": {
      "countdown": 180 // Gerät für 180 Sekunden aktivieren.
    }
  }
}

// Gerät meldet Selbstaktivierung
{
  "toggle-identify": {
    "1": {
      "identify": true
    }
  }
}

Umschalten Spannungs-Erkennung (toggle-voltage)

Beispiel für Funktionsdeklaration:

{
  "capability": "toggle-voltage",
  "permission": "1100"
}

Attribute (Zustand):

{
  "voltage": 230 // Feld `voltage` zeigt die gemessene Spannung an. **Typ:** Number. Einheit: Volt.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "toggle-voltage": {
    "voltage": 230
  }
}

Unterkomponenten-Stromerkennung (toggle-electric-current)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "toggle-electric-current",
    "permission": "0100",
    "name": "1" // Komponentenname. **Typ:** String. Optionale Werte: "1" (Kanal 1), "2" (Kanal 2), "3" (Kanal 3), "4" (Kanal 4).
  }
]

Attribute (Zustand):

{
  "electricCurrent": 50 // Feld `electricCurrent` repräsentiert den Stromwert. **Einheit:** 0.01 A. **Typ:** Integer. Wert muss größer oder gleich 0 sein.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "toggle-electric-current": {
    "1": {
      "electricCurrent": 50
    }
  }
}

Unterkomponenten-Leistungserkennung (toggle-electric-power)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "toggle-electric-power",
    "permission": "0100",
    "name": "1" // Komponentenname. **Typ:** String. Optionale Werte: "1" (Kanal 1), "2" (Kanal 2), "3" (Kanal 3), "4" (Kanal 4).
  }
]

Attribute (Zustand):

{
  "electricPower": 50, // Feld `electricPower` repräsentiert den aktuellen Leistungswert. **Einheit:** 0.01 W. **Typ:** Integer. Wert muss größer oder gleich 0 sein.
  "reactivePower": 50, // Feld `reactivePower` repräsentiert den aktuellen Blindleistungswert. **Einheit:** 0.01 W. **Typ:** Integer. Optional.
  "activePower": 50, // Feld `activePower` repräsentiert den aktuellen Wirkleistungswert. **Einheit:** 0.01 W. **Typ:** Integer. Optional.
  "apparentPower": 50 // Feld `apparentPower` repräsentiert den aktuellen Scheinleistungswert. **Einheit:** 0.01 W. **Typ:** Integer. Optional.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "toggle-electric-power": {
    "1": {
      "electricPower": 50,
      "reactivePower": 50,
      "activePower": 50,
      "apparentPower": 50
    }
  }
}

Unterkomponenten-Energieverbrauchsstatistik (toggle-power-consumption)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "toggle-power-consumption",
    "permission": "1101",
    "name": "1", // Komponentenname. **Typ:** String. Optionale Werte: "1" (Kanal 1), "2" (Kanal 2), "3" (Kanal 3), "4" (Kanal 4).
    "settings": {
      "resolution": {
        "permission": "01",
        "type": "numeric",
        "value": 3600
      },
      "timeZoneOffset": {
        "permission": "01",
        "type": "numeric",
        "min": -12,
        "max": 14,
        "value": 0
      }
    }
  }
]

Attribute (Zustand):

Echtzeitstatistiken starten/beenden:

{
  "rlSummarize": true, // Starten oder Stoppen der Echtzeitstatistik. **Typ:** Boolean. Erforderlich.
  "timeRange": { // Zusammenfassungszeitraum. Erforderlich.
    "start": "2020-07-05T08:00:00Z", // Startzeit des Energieverbrauchs. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Endzeit des Energieverbrauchs. **Typ:** String. Erforderlich.
  }
}

Leistungsverbrauch nach Zeitraum abfragen:

{
  "type": "summarize", // Zusammenfassungstyp. **Typ:** String. Erforderlich. Optionen: "rlSummarize" (Echtzeit-Zusammenfassung), "summarize" (Aktuelle Zusammenfassung).
  "timeRange": { // Zusammenfassungszeitraum, erforderlich wenn Typ "summarize" ist.
    "start": "2020-07-05T08:00:00Z", // Startzeit des Energieverbrauchs. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Endzeit des Energieverbrauchs. **Typ:** String. Optional. Wenn nicht angegeben, wird die aktuelle Zeit verwendet.
  }
}

Antwort für Energieverbrauch innerhalb des Zeitbereichs:

{
  "type": "summarize", // Zusammenfassungstyp. **Typ:** String. Erforderlich.
  "rlSummarize": 50.0, // Gesamter Energieverbrauch. **Einheit:** 0.01 kWh. **Typ:** Number. Optional.
  "electricityIntervals": [ // In mehrere Datensätze aufgeteilt durch `configuration.resolution`. Optional. Nicht vorhanden wenn Typ "rlSummarize" ist.
    {
      "usage": 26.5, // Energieverbrauch. **Einheit:** 0.01 kWh. **Typ:** Number. Erforderlich.
      "start": "2020-07-05T08:00:00Z", // Startzeit. **Typ:** String. Erforderlich.
      "end": "2020-07-05T09:00:00Z" // Endzeit. **Typ:** String. Erforderlich. Datensätze mit kürzeren Intervallen als die Auflösung gelten als ungültig.
    },
    {
      "usage": 26.5, // Energieverbrauch. **Einheit:** 0.01 kWh. **Typ:** Number. Erforderlich.
      "start": "2020-07-05T09:00:00Z", // Startzeit. **Typ:** String. Erforderlich.
      "end": "2020-07-05T10:00:00Z" // Endzeit. **Typ:** String. Erforderlich. Datensätze mit kürzeren Intervallen als die Auflösung gelten als ungültig.
    }
  ]
}

Protokoll (Statusabfrage & Steuerbefehle):

Echtzeitstatistiken starten:

{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}

Echtzeitstatistiken beenden:

{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Historischen Energieverbrauch abrufen:

{
  "toggle-power-consumption": {
    "1": {
      "type": "summarize",
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Echtzeit-Energieverbrauch abrufen:

{
  "toggle-power-consumption": {
    "1": {
      "type": "rlSummarize"
    }
  }
}

Linkqualitätsindikator (lqi)

Beispiel für Funktionsdeklaration:

{
  "capability": "lqi",
  "permission": "0100"
}

Attribute (Zustand):

{
  "lqi": 60 // Feld `lqi` repräsentiert den Linkqualitätsindikator. **Typ:** Number. Wertebereich: 0 bis 255.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "lqi": {
    "lqi": 60
  }
}

Funktionale Konfiguration (configuration)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "configuration",
    "permission": "1100"
  }
]

Attribute (Zustand):

{
  "deviceConfiguration": { // Gerätespezifische funktionale Konfiguration
    "defaultResolution": 300, // Standardauflösung für das Lesen von Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
    "maxResolution": 86400, // Maximale Auflösung für das Lesen von Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
    "minResolution": 60 // Minimale Auflösung für das Lesen von Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
  }
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "configuration": {
    "deviceConfiguration": { // Gerätespezifische funktionale Konfiguration
      "defaultResolution": 300, // Standardauflösung für das Lesen von Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
      "maxResolution": 86400, // Maximale Auflösung für das Lesen von Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
      "minResolution": 60 // Minimale Auflösung für das Lesen von Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
    }
  }
}

System (system)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "system",
    "permission": "1000"
  }
]

Attribute (Zustand):

{
  "restart": true // Neustartgerät-Befehl. **Typ:** Boolean. Erforderlich. Wert muss `true` sein.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "system": { // Fähigkeitbezogene Konfiguration. Optional.
    "restart": true
  }
}

Feuchtigkeit (moisture)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "moisture",
    "permission": "0100"
  }
]

Attribute (Zustand):

{
  "moisture": 55.5 // Feld `moisture` repräsentiert den Feuchtigkeits-Sättigungsprozentsatz. **Typ:** Number. Erforderlich. Bereich: 0 bis 100.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "moisture": {
    "moisture": 55.5
  }
}

Barometrischer Druck (barometric-pressure)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "barometric-pressure",
    "permission": "0100",
    "settings": {
      "barometricPressureRange": {
        "type": "numeric",
        "permission": "01",
        "min": 540, // Minimaler Wert. **Typ:** Integer. Erforderlich. Muss kleiner als `max` sein.
        "max": 1100 // Maximaler Wert. **Typ:** Integer. Erforderlich. Muss größer als `min` sein.
      }
    }
  }
]

Attribute (Zustand):

{
  "barometricPressure": 50 // Barometrischer Druckwert. **Typ:** Integer. Erforderlich. **Einheit:** hPa.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "barometric-pressure": {
    "barometricPressure": 50
  }
}

Windgeschwindigkeit (wind-speed)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "wind-speed",
    "permission": "0100",
    "settings": {
      "windSpeedRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Minimaler Wert. **Typ:** Number. Erforderlich. Muss kleiner als `max` sein.
        "max": 50 // Maximaler Wert. **Typ:** Number. Erforderlich. Muss größer als `min` sein.
      }
    }
  }
]

Attribute (Zustand):

{
  "windSpeed": 50 // Windgeschwindigkeitswert. **Typ:** Number. Erforderlich. **Einheit:** m/s (Meter pro Sekunde).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "wind-speed": {
    "windSpeed": 50
  }
}

Windrichtung (wind-direction)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "wind-direction",
    "permission": "0100"
  }
]

Attribute (Zustand):

{
  "windDirection": 10 // Windrichtung. **Typ:** Integer. Erforderlich. **Einheit:** Grad. Bereich: 0 bis 360 Grad (im Uhrzeigersinn).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "wind-direction": {
    "windDirection": 10
  }
}

Niederschlag (rainfall)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "rainfall",
    "permission": "0100",
    "settings": {
      "rainfallRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Minimaler Wert. **Typ:** Number. Erforderlich. Muss kleiner als `max` sein.
        "max": 450 // Maximaler Wert. **Typ:** Number. Erforderlich. Muss größer als `min` sein.
      }
    }
  }
]

Attribute (Zustand):

{
  "rainfall": 11.11 // Niederschlagswert. **Typ:** Number. Erforderlich. **Einheit:** mm/h (Millimeter pro Stunde).
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "rainfall": {
    "rainfall": 11.11
  }
}

Ultraviolett-Index (ultraviolet-index)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "ultraviolet-index",
    "permission": "0100",
    "settings": {
      "ultravioletIndexRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Minimaler Wert. **Typ:** Number. Erforderlich. Muss kleiner als `max` sein.
        "max": 16 // Maximaler Wert. **Typ:** Number. Erforderlich. Muss größer als `min` sein.
      }
    }
  }
]

Attribute (Zustand):

{
  "ultravioletIndex": 11.1 // Ultraviolettindex. **Typ:** Number. Erforderlich.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "ultraviolet-index": {
    "ultravioletIndex": 11.1
  }
}

Elektrische Leitfähigkeit (electrical-conductivity)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "electrical-conductivity",
    "permission": "0100",
    "settings": {
      "electricalConductivityRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Minimaler Wert. **Typ:** Number. Erforderlich. Muss kleiner als `max` sein.
        "max": 23 // Maximaler Wert. **Typ:** Number. Erforderlich. Muss größer als `min` sein.
      }
    }
  }
]

Attribute (Zustand):

{
  "electricalConductivity": 11.11 // Elektrische Leitfähigkeitswert. **Typ:** Number. Erforderlich. **Einheit:** dS/m.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "electrical-conductivity": {
    "electricalConductivity": 11.11
  }
}

Sendestärke (transmit-power)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "transmit-power",
    "permission": "1100"
  }
]

Attribute (Zustand):

{
  "transmitPower": 9 // Sendeleistung des Geräts. **Typ:** Integer. Erforderlich. **Einheit:** dBm.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "transmit-power": {
    "transmitPower": 9
  }
}

PM2.5-Erkennung (pm25)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "pm25",
    "permission": "0100"
  }
]

Attribute (Zustand):

{
  "pm25": 10 // PM2.5-Konzentration in der Luft. **Typ:** Number. Erforderlich. **Einheit:** µg/m³.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "pm25": {
    "pm25": 10
  }
}

VOC-Index (voc-index)

Beispiel für Funktionsdeklaration:

{
  "capability": "voc-index",
  "permission": "0100"
}

Attribute (Zustand):

{
  "vocIndex": 10 // VOC-Index, der das Niveau der Schadgasbelastung widerspiegelt. **Typ:** Number. Erforderlich. **Einheit:** µg/m³.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "voc-index": {
    "vocIndex": 10
  }
}

Erdgas-Erkennung (gas)

Beispiel für Funktionsdeklaration:

{
  "capability": "gas",
  "permission": "0100"
}

Attribute (Zustand):

{
  "gas": true // Gibt an, ob eine Erdgasleckage erkannt wurde. **Typ:** Boolean. Erforderlich.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "gas": {
    "gas": true
  }
}

Bewässerungsarbeitsstatus (irrigation/work-status)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "irrigation",
    "permission": "0101",
    "name": "work-status",
    "settings": {
      "volumeUnit": {
        "type": "enum",
        "permission": "01",
        "values": ["L"],
        "value": "L"
      }
    }
  }
]

Attribute (Zustand):

{
  "realTimeVolume": 20, // Echtzeit-Bewässerungsvolumen. **Typ:** Number. Optional. **Einheit:** L.
  "start": "2020-07-05T08:00:00Z", // Bewässerungsstartzeit. **Typ:** Datum. Optional.
  "end": "2020-07-05T09:00:00Z", // Bewässerungsendzeit. **Typ:** Datum. Optional.
  "dailyVolume": 20 // Tägliches Bewässerungsvolumen. **Typ:** Number. Optional. **Einheit:** L.
}

Protokoll (Statusabfrage & Steuerbefehle):

Berichterstattung des Arbeitsstatus:

{
  "irrigation": {
    "work-status": {
      "realTimeVolume": 20,
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z",
      "dailyVolume": 20
    }  
  }
}

Abfrage des Arbeitsstatus:

{
  "irrigation": {
    "type": "oneDay", // Aggregationstyp. **Typ:** String. Erforderlich. Optionen: "oneDay", "30Days", "180Days".
    "timeRange": { // Zeitraum für die Aggregation. **Typ:** Objekt. Erforderlich.
      "start": "2020-07-05T08:00:00Z", // Startzeit für die Aggregation der Bewässerungsdaten. **Typ:** String. Erforderlich.
      "end": "2020-07-05T09:00:00Z" // Endzeit für die Aggregation der Bewässerungsdaten. **Typ:** String. Optional. Wenn weggelassen, wird die aktuelle Zeit verwendet.
    }
  }
}

Ergebnis der Arbeitsstatus-Abfrage:

{
  "irrigation": {
    "type": "oneDay", // Aggregationstyp. **Typ:** String. Erforderlich.
    "irrigationIntervals": [
      {
        "volume": 6500, // Bewässerungsvolumen. **Typ:** Number. Erforderlich. **Einheit:** L.
        "duration": 30, // Bewässerungsdauer. **Typ:** Number. Erforderlich. **Einheit:** Minuten.
        "start": "2020-07-05T08:00:00Z", // Startzeit. **Typ:** String. Erforderlich.
        "end": "2020-07-05T09:00:00Z" // Endzeit. **Typ:** String. Erforderlich.
      },
      {
        "volume": 6500, // Bewässerungsvolumen. **Typ:** Number. Erforderlich. **Einheit:** L.
        "duration": 30, // Bewässerungsdauer. **Typ:** Number. Erforderlich. **Einheit:** Minuten.
        "start": "2020-07-05T08:00:00Z", // Startzeit. **Typ:** String. Erforderlich.
        "end": "2020-07-05T09:00:00Z" // Endzeit. **Typ:** String. Erforderlich.
      }
    ]
  }
}

Bewässerungsarbeitsmodus (irrigation/work-mode)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "irrigation",
    "permission": "0100",
    "name": "work-mode",
    "settings": {
      "supportedModes": {
        "type": "enum",
        "permission": "01",
        "values": [
          "MANUAL", // Manueller Modus
          "TIMER", // Einmalige Zeitplanung
          "CYCLE-TIMER", // Wiederholte Zeitplanung
          "VOLUME", // Einmaliges Volumen
          "CYCLE-VOLUME" // Wiederholtes Volumen
        ]
      }
    }
  }
]

Attribute (Zustand):

{
  "workMode": "MANUAL" // Bewässerungsarbeitsmodus. **Typ:** String. Optional. Werte sollten aus `settings.supportedModes` stammen.
}

Protokoll (Statusabfrage & Steuerbefehle):

{
  "irrigation": {
    "work-mode": "MANUAL"
  }
}

Automatischer Bewässerungscontroller (irrigation/auto-controller)

Beispiel für Funktionsdeklaration:

[
  {
    "capability": "irrigation",
    "permission": "1100",
    "name": "auto-controller",
    "settings": {
      "volumeRange": { // Volumenbereich
        "type": "enum",
        "permission": "01",
        "min": 0,
        "max": 6500,
        "unit": "L"
      },
      "timeRange": { // Zeitbereich
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 86400,
        "unit": "second"
      },
      "cycleCountRange": { // Zyklusanzahlbereich
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 100,
        "step": 1
      }
    }
  }
]

Attribute (Zustand):

Einmal- oder wiederholte Zeitplanung:

{
  "type": "time", // Bewässerungsmodus. **Typ:** String. Erforderlich. Optionen: "volume", "time".
  "action": {
    "perDuration": 60, // Dauer pro Bewässerungszyklus. **Typ:** Number. Erforderlich.
    "intervalDuration": 20, // Intervall zwischen Bewässerungszyklen. **Typ:** Number. Erforderlich.
    "count": 3 // Anzahl der Bewässerungszyklen. **Typ:** Number. Erforderlich.
  }
}

Einmaliges oder wiederholtes Volumen:

{
  "type": "volume", // Bewässerungsmodus. **Typ:** String. Erforderlich. Optionen: "volume", "time".
  "action": {
    "perConsumedVolume": 60, // Volumenverbrauch pro Bewässerungszyklus. **Typ:** Number. Erforderlich.
    "intervalDuration": 20, // Intervall zwischen Bewässerungszyklen. **Typ:** Number. Erforderlich.
    "count": 3 // Anzahl der Bewässerungszyklen. **Typ:** Number. Erforderlich.
  }
}

Protokoll (Statusabfrage & Steuerbefehle):

Einmal- oder wiederholte Zeitplanung:

{
  "irrigation": {
    "auto-controller": {
      "type": "time", // Bewässerungsmodus. **Typ:** String. Erforderlich.
      "action": {
        "perDuration": 60, // Dauer pro Bewässerungszyklus. **Typ:** Number. Erforderlich.
        "intervalDuration": 20, // Intervall zwischen Zyklen. **Typ:** Number. Erforderlich.
        "count": 3 // Anzahl der Zyklen. **Typ:** Number. Erforderlich.
      }
    }
  }
}

Einmaliges oder wiederholtes Volumen:

{
  "irrigation": {
    "auto-controller": {
      "type": "volume", // Bewässerungsmodus. **Typ:** String. Erforderlich.
      "action": {
        "perConsumedVolume": 60, // Volumenverbrauch pro Zyklus. **Typ:** Number. Erforderlich.
        "intervalDuration": 20, // Intervall zwischen Zyklen. **Typ:** Number. Erforderlich.
        "count": 3 // Anzahl der Zyklen. **Typ:** Number. Erforderlich.
      }
    }
  }
}

Unterstützte Voreingestellte Modi

**Modusnamen **	**Optionale Werte **
fanLevel (Lüfterstufe)	"low"
"medium"
"high"
thermostatMode (Thermostatmodus)	"auto"
"manual"
airConditionerMode >= 1.11.0 (Klimaanlagenmodus)	"cool"
"heat"
"auto"
"fan"
"dry"
fanMode >= 1.11.0 (Lüftermodus)	"normal"
"sleep"
"child"
horizontalAngle >= 1.11.0 (Horizontaler Winkel)	"30"
"60"
"90"
"120"
"180"
"360"
verticalAngle >= 1.11.0 (Vertikaler Winkel)	"30"
"60"
"90"
"120"
"180"
"360"

c. Beschreibung der Tags

• Der spezielle Schlüssel toggle wird verwendet, um den Namen der Toggle-Unterkomponente festzulegen.

{
    "toggle": {
        '1': 'Kanal1',
        '2': 'Kanal2',
        '3': 'Kanal3',
        '4': 'Kanal4',
    },
}

• Der spezielle Schlüssel temperature_unit wird verwendet, um die Temperatureinheit festzulegen.

{
    "temperature_unit":'c' // c-Celsius; f-Fahrenheit
}

d. Spezielle Fehlercodes und Beschreibung

Fehlercode	Beschreibung	iHost-Version
110000	Das Untergerät/Gruppe, das der id entspricht, existiert nicht	≥2.1.0
110001	Das Gateway befindet sich im Zustand, Zigbee-Geräte zu entdecken	≥2.1.0
110002	Geräte in einer Gruppe haben keine gemeinsame Fähigkeit	≥2.1.0
110003	Falsche Anzahl von Geräten	≥2.1.0
110004	Falsche Anzahl von Gruppen	≥2.1.0
110005	Gerät offline	≥2.1.0
110006	Aktualisierung des Gerätestatus fehlgeschlagen	≥2.1.0
110007	Aktualisierung des Gruppenstatus fehlgeschlagen	≥2.1.0
110008	Die maximale Anzahl von Gruppen wurde erreicht. Erstellen Sie bis zu 50 Gruppen	≥2.1.0
110009	Die IP-Adresse des Kamerageräts ist falsch	≥2.1.0
110010	Zugriffsautorisierungsfehler des Kamerageräts	≥2.1.0
110011	Stream-Adresse des Kamerageräts fehlerhaft	≥2.1.0
110012	Videoencoding des Kamerageräts wird nicht unterstützt	≥2.1.0
110013	Gerät existiert bereits	≥2.1.0
110014	Kamera unterstützt keinen Offline-Betrieb	≥2.1.0
110015	Das Kontopasswort stimmt nicht mit dem Kontopasswort in der RTSP-Stream-Adresse überein	≥2.1.0
110016	Das Gateway befindet sich im Zustand, ONVIF-Kameras zu entdecken	≥2.1.0
110017	Überschreitung der maximalen Anzahl hinzugefügter Kameras	≥2.1.0
110018	Der Pfad der ESP-Kamera ist falsch	≥2.1.0
110019	Fehler beim Zugriff auf die Service-Adresse des Drittanbietergeräts	≥2.1.0

e. Suche nach Untergerät

Ermöglichen Sie autorisierten Benutzern, die Gateway-Suche nach Untergeräten über diese Schnittstelle zu aktivieren oder zu deaktivieren

• 💡Hinweis: Unterstützt derzeit nur die Suche nach Zigbee-Untergeräten.

• 💡Hinweis: Zigbee-Untergeräte werden nach der Suche automatisch hinzugefügt. Die Schnittstelle "Untergeräte manuell hinzufügen" muss nicht verwendet werden :::tips

• URL：/open-api/V2/rest/devices/discovery

• Methode: PUT

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
aktivieren	boolean	N	true (Pairing starten); false (Pairing pausieren)
type	string	N	Suchtyp: Zigbee

Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: ** 200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Untergerät manuell hinzufügen

Erlauben Sie autorisierten Benutzern, ein einzelnes Untergerät über diese Schnittstelle hinzuzufügen.

• Hinweis: Derzeit werden nur RTSP-Kamera und ESP32-Kamera unterstützt :::tips

• URL：/open-api/V2/rest/devices

• Methode：POST

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
name	string	N	Name des Untergeräts
display_category	string	N	Gerätetyp. Unterstützt nur Kamera。
capabilities	CapabilityObject[]	N	Fähigkeitsliste. Wenn display_category = camera, enthalten die Fähigkeiten nur camera-stream-Fähigkeiten.
protocal	string	N	Geräteprotokoll. RTSP; ESP32-CAM
manufacturer	string	N	Hersteller.
model	string	N	Gerätemodell
firmware_version	string	N	Firmware-Version des Geräts

CapabilityObject

Attribut	Typ	Optional	Beschreibung
capability	string	N	Name der Fähigkeit. Unterstützt nur "camera-stream"
permission	string	N	Geräteberechtigung. Unterstützt nur Lesen.
configuration	CameraStreamConfigurationObject	Y	Kamera-Stream-Konfiguration.

SettingsObject

Attribut	Typ	Optional	Beschreibung
streamSetting	StreamSettingObject	N	Streamdienst-Konfiguration

StreamSettingObject

Attribut	Typ	Optional	Beschreibung
type	string	N	Streamdienst-Konfiguration
permission	string	N	Fähigkeitsberechtigung. Unterstützt nur "11" (änderbar).
value	StreamSettingValueObject	N	Spezifische Konfigurationswerte

StreamSettingValueObject

Attribut	Typ	Optional	Beschreibung
stream_url	string	N	Stream-URL-Format
Format:<schema>://<hostname>:<port>/<username>:<password>@<service_path>
Beispiel:rtsp://admin:[email protected]:554/streaming/channel01
Schema-Optionen:
rtsp (Real-Time Streaming Protocol)
http (Hypertext Transfer Protocol) — Für ESP32-CAM-Geräte
*Hinweis: Einige Kameras benötigen möglicherweise keinen Benutzernamen oder kein Passwort. In solchen Fällen können Sie <username> und <password> Felder aus der URL weglassen.

Erfolgreiche Datenantwort:

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts

:::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {
    "serial_number": "serial_number"
  },
  "message": "success"
}

Fehlerhafte Datenantwort: leeres Objekt :::tips Bedingung：

1. Fehler beim Zugriff auf den Kamera-Stream (Formatfehler, Autorisierungsfehler, Netzwerkfehler usw.)

2. Gerät existiert bereits

3. Wenn das Hinzufügen eines einzelnen Geräts fehlschlägt, wird zurückgegeben, dass alle Geräte nicht hinzugefügt wurden.

Statuscode: 200 OK Fehlercode： ● 110009 Fehlerhafte Kamera-IP-Adresse ● 110010 Kamerazugriffsautorisierungsfehler ● 110011 Fehlerhafte Kamera-Stream-Adresse ● 110012 Das Kamera-Videoencoding wird nicht unterstützt ● 110013 Gerät existiert bereits ::: Antwortbeispiel:

{
  "error": 110009,
  "data": {},
  "message": "Kamera-IP-Zugriff fehlgeschlagen" 
}

g. Liste der Untergeräte abrufen

Ermöglichen Sie autorisierten Benutzern, die Liste der Gateway-Untergeräte über diese Schnittstelle abzurufen. :::tips

• URL：/open-api/V2/rest/devices

• Methode: GET

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter: keine Erfolgreiche Datenantwort:

Attribut	Typ	Optional	Beschreibung
device_list	ResponseDeviceObject[]	N	Geräteliste

ResponseDeviceObject

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	"N" wenn ein Drittanbietergerät verbunden ist, sonst "Y"	Eindeutige Seriennummer des Drittanbietergeräts
service_address	string	"N" wenn ein Drittanbietergerät verbunden ist, sonst "Y"	Service-Adresse des Drittanbieters
name	string	N	Gerätename, wenn er nicht umbenannt wurde, wird er vom Frontend gemäß den Standardanzeigeregeln angezeigt.
manufacturer	string	N	Hersteller
model	string	N	Gerätemodell
firmware_version	string	N	Firmware-Version. Kann eine leere Zeichenkette sein.
hostname	string	Y	Hostname des Geräts
mac_address	string	Y	MAC-Adresse des Geräts
app_name	string	Y	Der Name der Anwendung, zu der es gehört. Wenn app_name beim Abrufen des Open-Interface-Zertifikats ausgefüllt wurde, werden alle nachfolgenden Geräte, die über das Zertifikat verbunden werden, in dieses Feld geschrieben.
display_category	string	N	Gerätekategorie
capabilities	CapabilityObject[]	N	Gerätefähigkeiten
protocol	string	"N" wenn ein Drittanbietergerät verbunden ist, sonst "Y"	Geräteprotokoll: zigbee, onvif, rtsp, esp32-cam
state	object	Y	Gerätezustandsobjekt. Für Zustandsbeispiele verschiedener Fähigkeiten prüfen Sie bitte 【Unterstützte Gerätefähigkeiten】
Tags	object	Y	JSON-Format Schlüssel-Wert, benutzerdefinierte Geräteinformationen. Die Funktion ist wie folgt:- Wird zum Speichern von Gerätekanälen verwendet- Wird zum Speichern von Temperatureinheiten verwendet- Benutzerdefinierte Informationen für andere Drittanbietergeräte
online	boolean	N	Online-Status: True für onlineFalse ist offline
Subnetz	boolean	Y	Ob es sich im selben Subnetz wie das Gateway befindet

CapabilityObject 💡Hinweis: Bitte prüfen Sie die Beispiele unterstützter Gerätefähigkeiten unter [Supported Device Capabilities].

Attribut	Typ	Optional	Beschreibung
capability	string	N	Fähigkeitsname. Details siehe [Supported Device Capabilities]
permission	string	N	Berechtigung der Fähigkeit. Mögliche Werte sind "read" (lesbar), "write" (schreibbar), "readWrite" (lesbar und schreibbar).
configuration	object	Y	Konfigurationsinformationen der Fähigkeit. Derzeit wird camera-stream verwendet, siehe [Supported Device Capabilities]
name	string	Y	Das Namensfeld in toggle. Die Sub-Channel-Nummer, die zur Identifizierung von Mehrkanalgeräten verwendet wird. Wenn name beispielsweise 1 ist, bedeutet dies Kanal 1.

:::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data":{
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "Mein Gerät",
        "manufacturer": "SONOFF",
        "model": "BASICZBR3",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          },
          {
            "capability": "rssi",
            "permission": "read"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ],
  }
  "message": "success"
}

h. Aktualisieren angegebener Geräteinformationen oder -zustand

Ermöglicht autorisierten Benutzern, die Basisinformationen von Untergeräten zu ändern und über diese Schnittstelle Steuerbefehle auszugeben. :::tips

• URL：/open-api/V2/rest/devices/{serial_number}

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
name	string	Y	Gerätename
Tags	object	Y	JSON-Format Schlüssel-Wert, benutzerdefinierte Geräteinformationen.
state	object	Y	Gerätezustandsobjekt. Für Zustandsbeispiele verschiedener Fähigkeiten prüfen Sie bitte [Support Device Capabilities]
configuration	object	Y	Konfigurationsinformationen der Fähigkeit, derzeit kann nur die Kamera_stream-Fähigkeit geändert werden.

Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK Fehlercode:

• 110000 Das Untergerät/die Gruppe, die der id entspricht, existiert nicht ::: Antwortbeispiel:

{
  "error": 0,
  "data":{
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "我的设备",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  },
  "message": "success"
}

i. Untergerät löschen

Ermöglicht autorisierten Benutzern, Untergeräte über diese Schnittstelle zu löschen. :::tips

• URL：/open-api/V2/rest/devices/{serial_number}

• Methode：DELETE

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
name	string	Y	Gerätename.
Tags	object	Y	Schlüssel-Wert-Paare im JSON-Format, die verwendet werden, um Gerätenamen von Kanälen und andere Informationen über Untergeräte zu speichern.
state	object	Y	Gerätestatus ändern; für spezifische Protokolldetails siehe "Supported Device Capabilities."
capabilities	CapabilityObject []	Y	Konfigurationsinformationen der Fähigkeit; alle Fähigkeiten, die das Einstellen von Konfigurationen unterstützen, können geändert werden. Beachten Sie, dass Berechtigungen nicht geändert werden können.

Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK Fehlercodes:

• 110000: Das Untergerät/die Gruppe, die der ID entspricht, existiert nicht.

• 110006: Aktualisierung des Gerätezustands fehlgeschlagen.

• 110019: Zugriff auf den Dienstadresse des Drittanbietergeräts fehlgeschlagen.

• 110024: Aktualisierung der Gerätekonfiguration fehlgeschlagen. ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // Gerät einschalten
  await axios({
    url: `http://<domain name or ip address>/open-api/v2/rest/devices/${serial_number}`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      state: {
        power: {
          powerState: 'on'
        }
      }
    }
  });
})()

j. Untergerät löschen

Ermöglicht autorisierten Benutzern, Untergeräte über diese Schnittstelle zu löschen. :::tips

• URL：/open-api/v2/rest/devices/{serial_number}

• Methode：DELETE

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

k. Gerätestatus abfragen

Ermöglicht autorisierten Benutzern, den Gerätestatus über diese Schnittstelle abzufragen. :::tips

• URL：/open-api/v2/rest/devices/:serial_number/query-state/{capability}

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
query_state	object	N	Gerätestatus abfragen; für spezifische Protokolldetails siehe "Supported Device Capabilities."

import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // Gerät einschalten
  await axios({
    url: `http://<domain name or ip address>/open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      "query_state":{
        "power-consumption":{
          "type": "summarize", // Art der Statistik, erforderlich
          "timeRange": { // Zeitbereich für die Zusammenfassung, erforderlich, wenn type="summarize"
            "start": "2020-07-05T08:00:00Z", // Startzeit für Stromverbrauchsstatistiken
            "end": "2020-07-05T09:00:00Z" // Endzeit für Stromverbrauchsstatistiken; wenn weggelassen, Standard ist die aktuelle Zeit
          }
        }
      }
    });
})()

Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.4 Sicherheitsverwaltung

a. Sicherheitsliste abrufen

Ermöglicht autorisierten Benutzern, Gateway-Einstellungen über diese Schnittstelle zu ändern. :::tips

• URL：/open-api/v2/rest/security

• Methode：GET

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort:

Attribut	Typ	Optional	Beschreibung
security_list	ResponseSecurityObject[]	N	Antwort Geräteliste

ResponseDeviceObject

Attribut	Typ	Optional	Beschreibung
sid	int	N	Sicherheits-ID
name	string	N	Sicherheitsname
aktivieren	bool	N	Ob aktiviert

• true Aktiviert

• false Deaktiviert |

:::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {
    "security_list":[
      {
        "sid": 1,
        "name": "Home Mode",
        "enable": true
      }
    ]
  },
  "message": "success"
}

b. Angegebene Sicherheitsmodus aktivieren

Ermöglicht autorisierten Benutzern, einen angegebenen Sicherheitsmodus über diese Schnittstelle zu aktivieren. :::tips

• URL：/open-api/v2/rest/security/{security_id}/enable

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

c. Angegebenen Sicherheitsmodus deaktivieren

Ermöglicht autorisierten Benutzern, einen angegebenen Sicherheitsmodus über diese Schnittstelle zu deaktivieren. :::tips

• URL：/open-api/v2/rest/security/{security_id}/disable

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

d. Ein-Klick-Sicherheits-Einrichtung aktivieren

Ermöglicht autorisierten Benutzern, den Ein-Klick-Sicherheitsmodus über diese Schnittstelle zu aktivieren. :::tips

• URL：/open-api/v2/rest/security/enable

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

e. Sicherheit deaktivieren

Ermöglicht autorisierten Benutzern, die Sicherheit über diese Schnittstelle zu deaktivieren. :::tips

• URL：/open-api/v2/rest/security/disable

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

{
  "error": 0,
  "data": {},
  "message": "success"
}

4. Zugriff für Drittanbietergeräte

4.1 Zugriffsanleitung

Gerätezugang

1.0.jpg

Zugriff für Drittanbieter-Gateway

2.0.jpg

Zugriffsschritte

1. Bestimmen Sie die Klassifizierung des Geräts im Gateway. Details siehe [Supported Device Type].

2. Bestimmen Sie die Fähigkeiten, auf die das Gerät zugreifen kann. Details siehe [Supported Device Capabilities].

3. Rufen Sie die Schnittstelle [Discovery Request] auf, um das Gerät zum Gateway hinzuzufügen.

   1. Hinweis: Sie müssen die Dienstadresse bereitstellen, um die vom Gateway ausgestellten Anweisungen zu empfangen; diese wird verwendet, um die vom Gateway ausgestellten Geräte-Steuerbefehle zu empfangen.

4. Wenn sich der Status des Drittanbietergeräts ändert, müssen Sie die Schnittstelle [Device States Change Report] aufrufen, um den neuesten Status zurück an das Gateway zu senden.

5. Nach dem Hinzufügen erscheint das Drittanbietergerät in der Geräteliste und verfügt über die meisten Funktionen des Gateways (wie andere Nicht-Drittanbietergeräte). Die gängigen offenen Schnittstellen im Zusammenhang mit dem Gerät können normal verwendet werden.

• Wählen Sie die passende Gerätekategorie. Die Klassifizierung beeinflusst das endgültige Anzeigeergebnis der UI nach der Verbindung des Geräts mit dem Gateway.

• Wählen Sie die richtige Gerätefähigkeit. Die Fähigkeitsliste bestimmt das Protokoll für den Gerätezustand.

Programmschritt

a. Gerätezugang

3.0.jpg

b. Drittanbieter-Gateway-Zugang

4.0.jpg

4.2 Zugriffsbeispiel

Schalter, Steckdose

Drittanbietergeräte synchronisieren

// Anfrage
URL：/open-api/v2/rest/thirdparty/event
Methode：POST
Header：
  Content-Type: application/json
  Autorization: Bearer  <token>
Body:
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission": "1100"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "Firmware-Version",
          "service_address": "http://192.168.31.14/webhook"
      	}
      ]
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "third_serial_number": "third_serial_number",
        "serial_number": "Seriennummer"
      }
    ]
  }
}

Gerätestatus melden

URL：/open-api/V2/rest/thirdparty/event
Methode：POST
Header：
  Content-Type: application/json
  Autorization: Bearer  <token>
Body:

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {}
}

Offline/Online melden

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {}
}

Empfangen der Anweisungen zur Gateway-Gerätesteuerung

URL：<service address>
Methode：POST
Header：
  Content-Type: application/json
B

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "endpoint": {
      "third_serial_number": "third_serial_number",
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {}
}

Gerät abfragen

URL：/open-api/V2/rest/devices
Methode：GET
Header：
  Content-Type: application/json
  Autorization: Bearer  <token>
Body: Keine

{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "Seriennummer",
        "third_serial_number": "third_serial_number",
        "name": "my plug",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "Firmware-Version",
        "display_category": "plug",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  },
  "message": "success"
}

4.3 Web-API

Drittanbieter-Anfrage-Gateway-Schnittstelle

Anfrageformat

Ermöglicht autorisierten Benutzern, Ereignisanfragen über diese Schnittstelle an das Gateway zu senden. :::tips

• URL：/open-api/V2/rest/thirdparty/event

• Methode：POST

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
event	EventObject	N	Strukturinformationen des Anfrage-Ereignisobjekts

EventObject

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
endpoint	EndpointObject	Y	Strukturinformationen des Anfrage-EndpunktsHinweis: Dieses Feld ist leer, wenn eine neue Geräteliste synchronisiert wird.
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Anfrage-Name. optionale Parameter: DiscoveryRequest: Synchronisiere neue Geräte DeviceStatesChangeReport: Gerätezustands-Updatebericht DeviceOnlineChangeReport: Bericht zum Online-Status des Geräts
message_id	string	N	Anfrage-Nachrichten-ID, UUID_V4
version	string	N	Angeforderte Protokollversionsnummer. Derzeit fest auf 1

EndpointObject

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	N	Eindeutige Seriennummer des Drittanbietergeräts
Tags	object	Y	JSON-Format Schlüssel-Wert, benutzerdefinierte Geräteinformationen. [Geräteverwaltungsfunktion] - [Beschreibung der Tags]

PayloadObject Je nach unterschiedlichem header.name unterschiedliche Anfragestruktur.

Antwortformat

:::tips **Statuscode: **200 OK Antwortparameter: :::

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Antwort-Headers
payload	PayloadObject	N	Strukturinformationen der Antwort-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Name des Antwort-Headers. optionale Parameter:Response: Erfolgreiche Antwort ErrorResponse: Fehlerantwort
message_id	string	N	Nachrichten-ID des Antwort-Headers, UUID_V4. Übergeben Sie hier die message_id des Anfrage-Headers *Wenn der Anforderungsparameter message_id fehlt, ist dieses Feld bei der Antwort ein leerer String.
version	string	N	- Anforderungsprotokollversionsnummer. Derzeit fest auf 1.

Erfolgreiche Antwort--PayloadObject ：

Je nach Anfragetyp ist die Antwortstruktur unterschiedlich. Details finden Sie in der jeweiligen Anfragedokumentation.

Fehlerantwort--PayloadObject：

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertypen:

• INVALID_PARAMETERS: Parameterfehler

• AUTH_FAILURE: Autorisierungsfehler

• INTERNAL_ERROR: Interner Dienstfehler | | description | string | N | Fehlerbeschreibung |

DiscoveryRequest Synchronisiere eine neue Geräteliste

• Hinweis: Nachdem das Gerät mit dem Gateway synchronisiert wurde, ist es standardmäßig online, also online=true. Nachfolgende Online-Änderungen hängen vollständig von der Synchronisierung mit dem Drittanbieter über die Schnittstelle DeviceOnlineChangeReport ab.

Anfrageparameter: EndpointObject**：**Keine PayloadObject：

Attribut	Typ	Optional	Beschreibung
endpoints	EndpointObject[]	N	Geräteliste

EndpointObject:

Attribut	Typ	Optional	Beschreibung
third_serial_number	string	N	Eindeutige Seriennummer des Drittanbietergeräts
name	string	N	Gerätename
display_category	string	N	Gerätekategorie. Siehe [Supported Device Type] für Details. *Drittanbietergeräte unterstützen derzeit nicht das Hinzufügen von Kameras.
capabilities	CapabilityObject[]	N	Fähigkeitsliste
state	object	N	Anfangszustandsinformationen
manufacturer	string	N	Hersteller
model	string	N	Gerätemodell
Tags	object	Y	JSON-Format Schlüssel-Wert, benutzerdefinierte Geräteinformationen:Wird verwendet, um Gerätekanäle zu speichernWird verwendet, um Temperatureinheiten zu speichernAndere benutzerdefinierte Drittanbieter-Daten
firmware_version	string	N	Firmware-Version
service_address	string	N	Dienstadresse. Zum Beispiel http://192.168.31.14/service_address

Beispiel für Anfrage:

{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "Firmware-Version",
          "service_address": "http://192.168.31.14/service_address"
        }
      ]
    }
  }
}

Antwortparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
endpoints	EndpointObject[]	N	Geräteliste

EndpointObject:

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	N	Eindeutige Seriennummer des Drittanbietergeräts

Beispiel für eine korrekte Antwort:

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "serial_number": "Seriennummer",
        "third_serial_number": "third_serial_number"
      }
    ]
  }
}

Beispiel für eine Fehlerantwort:

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "webhook darf nicht leer sein" 
  }
}

DeviceStatesChangeReport Gerätezustandsänderungsbericht

• Hinweis: Wiederholte Zustandsberichte können fälschlicherweise Szenen auslösen.

Anfrageparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
state	object	N	Gerätezustand, Details siehe [Supported device cabilities]

Beispiel für Anfrage:

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Antwortparameter: PayloadObject: Leeres Objekt Beispiel einer erfolgreichen Antwort:

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {}
}

DeviceOnlineChangeReport Bericht zum Online-Status des Geräts

• Hinweis: Wiederholte Zustandsberichte können fälschlicherweise Szenen auslösen.

Anfrageparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
online	boolean	N	Geräteonline-Status true: Online
false: Offline

Beispiel für Anfrage:

{
  "event": {
    "header": {
      "name": "DeviceOnlineChangeReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

Antwortparameter: PayloadObject: Leeres Objekt Beispiel einer erfolgreichen Antwort:

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {}
}

DeviceInformationUpdatedReport Geräteinformationsaktualisierungsbericht

• Hinweis: Aktualisierungen können bestehende Szenen oder Sicherheitsfunktionen beeinflussen.

Anfrageparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
capabilities

| CapabilityObject[]

| N

| Fähigkeitsliste. Details finden Sie im Abschnitt Unterstützte Gerätefähigkeiten. **Hinweis: **Dieser Parameter aktualisiert nur das value von dem Einstellung Schlüssel innerhalb des CapabilityObject, und Aktualisierungen sind nur zulässig, wenn das permission für den Einstellung Schlüssel ist 11 oder 01. Für die spezifische Strukturdefinition des Einstellung in CapabilityObjectverweisen Sie auf die detaillierte Beschreibung in Abschnitt 2.3 Gerätekategorien & Gerätefähigkeiten. | | tags

| object

| Y

| JSON-Format Schlüssel-Wert, benutzerdefinierte Geräteinformationen.

• Kann verwendet werden, um Gerätekanäle zu speichern

• Kann verwendet werden, um Temperatureinheiten zu speichern

• Andere benutzerdefinierte Drittanbieter-Daten |

Beispiel für Anfrage:

{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "detect",
          "permission": "0110",
          "settings":{
            "detectInterval":{
              "permission": "11",
              "type": "numeric",
              "value": 300,
            },
            "detectSensitivity":{
              "permission": "11",
              "type": "numeric",
              "value": 1000,
            }
          }
        }
      ]
    }
  }
}

Antwortparameter: PayloadObject: Leeres Objekt Beispiel einer erfolgreichen Antwort:

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "2"
  },
  "payload": {}
}

Gateway sendet die Anweisungs-Schnittstelle über die Geräte-Dienstadresse

• Hinweis:

1. Die Drittparteien müssen innerhalb von 3 s auf die Anfrage des Gateways antworten. Andernfalls wird das Gateway die Befehlsverarbeitung als abgelaufen einstufen.

2. Wenn der Drittanbieterservice offline ist, setzt das Gateway das Gerät in einen Offline-Zustand, und der Drittanbieterservice muss den Gerätestatus (DeviceStatesChangeReport) oder den Online-Status (DeviceOnlineChangeReport) melden, bevor er wieder online geht.

Anfrageformat

Das Gateway sendet Anweisungen über die Geräte-Dienstadressen-Schnittstelle an den Drittanbieter. :::tips

• URL：

• Methode：POST

• Header：

  • Content-Type: application/json ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
directive	DirectiveObject	N	Strukturinformationen des Directive-Objekts

DirectiveObject

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
endpoint	EndpointObject	N	Strukturinformationen des Anfrage-Endpunkts
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Anfrage-Name. Optionale Parameter:UpdateDeviceStates: Gerätezustände aktualisieren
message_id	string	N	Anfrage-Nachrichten-ID, UUID_V4
version	string	N	Angeforderte Protokollversionsnummer. Derzeit fest auf 1.

EndpointObject

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	N	Eindeutige Seriennummer des Drittanbietergeräts
Tags	object	N	JSON-Format Schlüssel-Wert, benutzerdefinierte Geräteinformationen. [Geräteverwaltungsfunktion] - [Beschreibung der Tags]

PayloadObject: Je nach unterschiedlichem header.name, gibt es für jeden eine spezifische Anfragestruktur.

Beispiel für Anfrage:

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Antwortformat

:::tips **HTTP-Statuscode: **200 OK HTTP-Antwortattribute： :::

Attribut	Typ	Optional	Beschreibung
event	EventObject	N	Strukturinformationen des Antwort-Ereignisses

EventObject

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Name des Antwort-Headers. Optionale Parameter: UpdateDeviceStatesResponse: Antwort auf Gerätezustandsaktualisierung ErrorResponse: Fehlerantwort
message_id	string	N	Nachrichten-ID des Antwort-Headers, UUID_V4. Übergeben Sie hier die message_id des Anfrage-Headers
version	string	N	Angeforderte Protokollversionsnummer. Derzeit fest auf 1.

Erfolgreiche Antwort--PayloadObject：

Je nach Anfragetyp ist die Antwortstruktur unterschiedlich. Details finden Sie in der jeweiligen Anfragedokumentation.

Fehlerantwort--PayloadObject：

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertypen:

• ENDPOINT_UNREACHABLE: Gerät ist nicht erreichbar oder offline

• ENDPOINT_LOW_POWER: Gerät befindet sich im Energiesparmodus und kann nicht gesteuert werden

• INVALID_DIRECTIVE: Abnormale Anweisung vom Gateway

• NO_SUCH_ENDPOINT: Gerät existiert nicht

• NOT_SUPPORTED_IN_CURRENT_MODE: Der aktuelle Modus unterstützt die Operation nicht

• INTERNAL_ERROR: Interner Dienstfehler

• REMOTE_KEY_CODE_NOT_LEARNED: Fernbedienungstasten-Code nicht gelernt |

:::tips Bedingungen: Die Anfrageparameter sind legal. **Statuscode: **200 OK Antwortparameter: :::

{
  "event": {
    "header": {
      "name": "UpdateDeviceStatesResponse",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {}
  }
}

{
  "event": {
    "header": {
      "name": "ErrorResponse",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE"
    }
  }
}

UpdateDeviceStates

Anfrageparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
state	object	N	Gerätezustand, Details siehe [Supported device cabilities].

Beispiel für Anfrage:

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

Antwortparameter: PayloadObject：Leeres Objekt Beispiel einer erfolgreichen Antwort

{
  "header": {
    "name": "Response",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {}
}

QueryDeviceStates

Anfrageparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
state	object	N	Gerätezustand, Details siehe [Supported device cabilities].

Beispiel für Anfrage:

{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "timeRange": {
            "start": "2020-07-05T08:00:00Z", // Startzeit für Stromverbrauchsstatistiken, erforderlich.
            "end": "2020-07-05T09:00:00Z"   // Endzeit für Stromverbrauchsstatistiken, erforderlich.
          }
        }
      }
    }
  }
}

Antwortparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
state	object	N	Gerätezustand, Details siehe [Supported device cabilities].

Antwortbeispiel:

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // In mehrere Datensätze unterteilt basierend auf configuration.resolution
            {
              "usage": 26.5, // Stromverbrauchswert, erforderlich. Typ: number.
              "start": "2020-07-05T08:00:00Z", // Startzeit, erforderlich. Typ: date.
              "end": "2020-07-05T09:00:00Z"    // Endzeit, erforderlich. Typ: date. Wenn das Intervall zwischen End und Start kleiner als resolution ist, gelten alle gemeldeten Datensätze als ungültig.
            },
            {
              "usage": 26.5, // Stromverbrauchswert, erforderlich. Typ: number.
              "start": "2020-07-05T09:00:00Z", // Startzeit, erforderlich. Typ: date.
              "end": "2020-07-05T10:00:00Z"    // Endzeit, erforderlich. Typ: date. Wenn das Intervall zwischen End und Start kleiner als resolution ist, gelten alle gemeldeten Datensätze als ungültig.
            }
          ]
        }
      }
    }
  }
}

ConfigureDeviceCapabilities

Anfrageparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
capabilities	CapabilityObject[]	N	Fähigkeitsliste. Details siehe Abschnitt Unterstützte Gerätefähigkeiten. Beachten Sie, dass das Feld permission nicht geändert werden kann; beim Synchronisieren denselben Wert übergeben.

Beispiel für Anfrage:

{
  "directive": {
    "header": {
      "name": "ConfigureDeviceCapabilities",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "thermostat-mode-detect",
          "permission": "0110",
          "name": "temperature", // Art der Temperaturregelungs-Erkennung, erforderlich. Optionale Werte: humidity (Feuchterkennung), temperature (Temperaturerkennung)
          "settings": {
            "setpointRange": {
              "permission": "11",
              "type": "object",
              "value": {
                "supported": [ // Unterstützte Erkennungseinstellungen, erforderlich.
                  {
                    "name": "lowerSetpoint", // Minimaler Wert, den die Erkennung einhalten soll. Entweder lowerSetpoint oder upperSetpoint muss angegeben werden.
                    "value": { // Erkennungsbereich, optional. Ausfüllen, wenn Voreinstellungen vorhanden sind.
                      "value": 68.0, // Temperatur- oder Feuchtigkeitswert, erforderlich.
                      "scale": "f" // Temperatureinheit, erforderlich, wenn name=temperature. Optionen: c (Celsius), f (Fahrenheit)
                    }
                  },
                  {
                    "name": "upperSetpoint", // Maximaler Wert, den die Erkennung einhalten soll. Entweder lowerSetpoint oder upperSetpoint muss angegeben werden.
                    "value": { // Erkennungsbereich, optional. Ausfüllen, wenn Voreinstellungen vorhanden sind.
                      "value": 68.0, // Temperatur- oder Feuchtigkeitswert, erforderlich.
                      "scale": "f" // Temperatureinheit, erforderlich, wenn name=temperature. Optionen: c (Celsius), f (Fahrenheit)
                    }
                  }
                ]
              }
            },
            "supportedModes": {
              "type": "enum",
              "permission": "01",
              "values": [
                "COMFORT",
                "COLD",
                "HOT"
              ]
            }
          }
        }
      ]
    }
  }
}

Antwortparameter: PayloadObject：Leeres Objekt Beispiel einer erfolgreichen Antwort

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "2"
    },
    "payload": {}
  }
}

5. Server-sent Events

MDN EventSource-Schnittstellenbeschreibung：https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

5.1 Anweisung

Das Gateway unterstützt das Pushen von Nachrichten an den Client mittels SSE (Server-sent events). Der Client kann SSE-Nachrichten nach Erhalt der Zugangsdaten überwachen und den Inhalt der Push-Nachrichten gemäß dem Ereignisbenachrichtigungsprotokoll der Entwicklungs-Schnittstelle nach Empfang der Nachrichten vom Gateway parsen. Es ist zu beachten, dass das Gateway derzeit das HTTP1.1-Protokoll verwendet, sodass auf der Browserseite eine maximale Verbindungsanzahl von nicht mehr als 6 besteht (Spezifische Hinweise finden Sie in der MDN EventSource-Schnittstellenbeschreibung.)

5.2 Allgemeines Format

:::tips

• URL：/open-api/V2/sse/bridge

• Methode：GET ::: Anfrageparameter:

Name	Typ	Optional	Beschreibung
access_token	string	N	Access-Token

Hinweis: Beim Anfordern einer SSE-Verbindung prüft das Gateway das access_token, und es wird ein Authentifizierungsfehler zurückgegeben, wenn es ungültig ist. { "error": 401, "data": {}, "message": "invalid access_token"}

## Zum Beispiel: Modulname: device Version: 1,v2,v3 Nachrichtentyp: addDevice

Beispiel:

const evtSource = new EventSource("http://<domain name or ip address>/open-api/v2/sse/bridge?access_token=xxxxxx");

evtSource.addEventListener('device#v2#addDevice',function (event) {
  try {
    const data = JSON.parse(event.data);
    console.log('data', data);
  } catch (error) {
    console.error(`parse error`,error);
  }
}

5.3 Gerätemodul

a. Gerät hinzufügen-Ereignis

:::tips Modulname：device Version：v2 Nachrichtentyp：addDevice event.data Parameter： :::

Name	Typ	Optional	Beschreibung
payload	ResponseDeviceObjectObject - Schnittstelle identisch mit Get Device List	N	Geräteinformationen

Beispiel:

// event.data
{
  "payload": {
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "MeinGerät",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  }
}

b. Ereignis: Gerätezustand aktualisieren

:::tips Modulname：device Version：v2 Nachrichtentyp：updateDeviceState event.data Parameter： :::

Name	Typ	Optional	Beschreibung
endpoint	EndpointObject	N	Geräteinformationen
payload	object。 Struktur identisch mit dem Gerätezustand	N	Gerätestatusdaten

EndpointObject:

Parameter	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	Y	Die eindeutige Seriennummer des Drittanbietergeräts. Für über offene Schnittstellen verbundene Geräte ist dieses Feld erforderlich.

Beispiel:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}

c. Ereignis: Geräteinformationen aktualisieren

:::tips Modulname：device Version：v2 Nachrichtentyp：updateDeviceInfo event.data Parameter： :::

Name	Typ	Optional	Beschreibung
endpoint	EndpointObject	N	Geräteinformationen
payload	DeviceChangeObject	N	Daten der Geräteänderung

EndpointObject:

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	Y	Die eindeutige Seriennummer des Drittanbietergeräts. Für über offene Schnittstellen verbundene Geräte ist dieses Feld erforderlich.

DeviceChangeObject

Name	Typ	Optional	Beschreibung
name	string	N	Gerätename
capabilities	CapabilityObject []	Y	Liste der Gerätefähigkeiten.
Tags	object	Y	Tagsobject | Nullable | JSON-Format Schlüssel-Wert-Paare für benutzerdefinierte Geräteinformationen.

• Kann verwendet werden, um Gerätekanäle zu speichern.

• Kann verwendet werden, um Temperatureinheiten zu speichern.

• Für andere benutzerdefinierte Drittanbieter-Daten. |

Beispiel:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "name": "device name",
    "capabilities": [
      {
        "capability": "thermostat-mode-detect",
        "permission": "0110",
        "name": "temperature", // Art der Temperaturregelungs-Erkennung, erforderlich. Optionale Werte: humidity (Feuchterkennung), temperature (Temperaturerkennung)
        "settings": {
          "setpointRange": {
            "permission": "11",
            "type": "object",
            "value": {
              "supported": [ // Unterstützte Erkennungseinstellungen, erforderlich.
                {
                  "name": "lowerSetpoint", // Minimaler Wert, den die Erkennung einhalten soll. Entweder lowerSetpoint oder upperSetpoint muss angegeben werden.
                  "value": { // Erkennungsbereich, optional. Ausfüllen, wenn Voreinstellungen vorhanden sind.
                    "value": 68.0, // Temperatur- oder Feuchtigkeitswert, erforderlich.
                    "scale": "f" // Temperatureinheit, erforderlich, wenn name=temperature. Optionen: c (Celsius), f (Fahrenheit)
                  }
                },
                {
                  "name": "upperSetpoint", // Maximaler Wert, den die Erkennung einhalten soll. Entweder lowerSetpoint oder upperSetpoint muss angegeben werden.
                  "value": { // Erkennungsbereich, optional. Ausfüllen, wenn Voreinstellungen vorhanden sind.
                    "value": 68.0, // Temperatur- oder Feuchtigkeitswert, erforderlich.
                    "scale": "f" // Temperatureinheit, erforderlich, wenn name=temperature. Optionen: c (Celsius), f (Fahrenheit)
                  }
                }
              ]
            }
          },
          "supportedModes": {
            "type": "enum",
            "permission": "01",
            "values": [
              "COMFORT",
              "COLD",
              "HOT"
            ]
          }
        }
      }
    ]
  }
}

d. Ereignis: Gerät löschen

:::tips Modulname：device Version：v2 Nachrichtentyp：deleteDevice event.data Parameter： :::

** Name **	** Typ **	** Optional**	** Beschreibung **
endpoint	EndpointObject	N	Geräteinformationen

EndpointObject:

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	Y	Die eindeutige Seriennummer des Drittanbietergeräts. Für über offene Schnittstellen verbundene Geräte ist dieses Feld erforderlich.

Beispiel:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  }
}

e. Ereignis: Geräte-Online-Status aktualisieren

:::tips Modulname：device Version：v2 Nachrichtentyp：updateDeviceOnline event.data Parameter： :::

Name	Typ	Optional	Beschreibung
endpoint	EndpointObject	N	Geräteinformationen
payload	DeviceChangeObject	N	Daten der Geräteänderung

EndpointObject:

Attribut	Typ	Optional	Beschreibung
serial_number	string	N	Eindeutige Seriennummer des Geräts
third_serial_number	string	Y	Die eindeutige Seriennummer des Drittanbietergeräts. Für über offene Schnittstellen verbundene Geräte ist dieses Feld erforderlich.

DeviceChangeObject

Name	Typ	Optional	Beschreibung
online	boolean	N	Geräte-Online-Status

Beispiel:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "online": false
  }
}

5.4 Gateway-Modul

a. Sicherheitsstatus-Aktualisierungsereignis

:::tips Modulname：device Version：v2 Nachrichtentyp：updateDeviceOnline event.data Parameter： :::

Attribut	Typ	Optional	Beschreibung
payload	SecurityStateObject	N	Geräteinformationen

SecurityStateObject

Attribut	Typ	Optional	Beschreibung
alarm_state	string	N

• arming | Bewaffnet

• disarming | Entwaffnet |

Beispiel:

// event.data
{
  "payload": {
    "alarm_state": "alarming"
  }
}

5.5 Sicherheitsmodul

a. Arm-State-Aktualisierungsereignis

:::tips Modulname：device Version：v2 Nachrichtentyp：updateDeviceOnline event.data Parameter： :::

Attribut	Typ	Optional	Beschreibung
payload	ArmStateObject	N	Arm- und Disarm-Informationen

ArmStateObject：

Attribut	Typ	Optional	Beschreibung
arm_state	string	N

• arming | Bewaffnet

• disarming | Deaktiviert | | detail | DetailObject | N | Arm-/Disarm-Details |

DetailObject：

Attribut	Typ	Optional	Beschreibung
sid	int	N	Sicherheitsmodus-ID
name	string	N	Sicherheitsname

Beispiel

// event.data
{
  "payload": {
    "arm_state": "arming",
    "detail": {
      "sid": 1,
      "name": "Home Mode"
    }
  }
}

6. TTS (Text-to-Speech) Engine-Funktion

6.1 Anleitung

Schlüsselrolle

• TTS-Dienstanbieter: Der TTS-Engine-Dienstanbieter ist verantwortlich für die Registrierung der TTS-Engine am Gateway und die Bereitstellung von TTS-Diensten

• Gateway-Server：iHost

• Gateway Open API Client

6.1.1 Registrierung des TTS-Engine-Dienstes

1. 【TTS-Dienstanbieter】Ruft die Schnittstelle auf, um die TTS-Engine am Gateway zu registrieren.

2. 【Gateway-Server】Nach erfolgreicher Registrierung speichert das Gateway die Basisinformationen der TTS-Engine (einschließlich der Dienstadresse server_address, und die anschließende Kommunikation zwischen dem Gateway und dem TTS-Dienstanbieter erfolgt über die Adresse server_address) und vergibt die TTS-Engine-Service-ID innerhalb des Gateways.

image.png

6.1.2 Abrufen der Liste synthetisierter Audios

1. 【Gateway Open API Client】Ruft die Schnittstelle auf, um die Liste der registrierten TTS-Engine-Dienste zu erhalten. Sie können die aktuelle Liste der registrierten TTS-Engines abrufen (einschließlich der vom Gateway zugewiesenen TTS-Engine-ID).

2. 【Gateway Open API Client】Ruft die Schnittstelle auf, um die Liste der Audios einer angegebenen TTS-Engine zu erhalten. Das Gateway sendet synchron eine Anforderung zur Audiolistenabfrage an den angegebenen TTS-Dienstanbieter und gibt das Ergebnis zurück.

image.png

6.1.3 Sprachsynthese durch Angabe einer Sprach-Engine

1. 【Gateway Open API Client】Ruft die Schnittstelle auf, um die Liste der registrierten TTS-Engine-Dienste zu erhalten. Sie können die aktuelle Liste der registrierten TTS-Engines abrufen (einschließlich der vom Gateway zugewiesenen TTS-Engine-ID).

2. 【Gateway Open API Client】Ruft die Schnittstelle auf, um die Liste der Audios einer angegebenen TTS-Engine zu erhalten. Das Gateway sendet synchron eine Anforderung zur Audiolistenabfrage an den angegebenen TTS-Dienstanbieter und gibt das Ergebnis zurück.

image.png

6.1.4 Audio synthetisieren und TTS-Sprachwiedergabe.

1. 【Gateway Open API Client】Ruft die Schnittstelle auf, um die Liste der registrierten TTS-Engine-Dienste zu erhalten. Sie können die aktuelle Liste der registrierten TTS-Engines abrufen (einschließlich der vom Gateway zugewiesenen TTS-Engine-ID).

2. 【Gateway Open API Client】Ruft die Schnittstelle auf, um die Liste der Audios einer angegebenen TTS-Engine zu erhalten. Das Gateway sendet synchron eine Anforderung zur Audiolistenabfrage an den angegebenen TTS-Dienstanbieter und gibt das Ergebnis zurück. (einschließlich der TTS-Audiodatei-Adresse)

3. 【Gateway Open API Client】Notiert die TTS-Audiodatei-Adresse aus dem zuvor zurückgegebenen Ergebnis, ruft die Schnittstelle zum Abspielen der Audiodatei auf und spielt sie über das Gateway ab.

6.2 TTS-Engine-Modul

6.2.1 Gateway Offene Fähigkeiten

a. Abrufen der Liste der registrierten TTS-Engine-Dienste

:::tips

• URL：/open-api/V2/rest/tts/engines

• Methode：GET

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter: keine Korrekte Datenantwort:

Attribut	Typ	Optional	Beschreibung
engines	EngineObject []	N	Liste der registrierten TTS-Engines

EngineObject Struktur

Attribut	Typ	Optional	Beschreibung
id	string	N	Vom Gateway zugewiesene Engine-ID
name	string	N	Name des TS-Engine-Dienstes

:::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK Antwortbeispiel:： :::

{
  "error": 0,
  "data": {
    "engines": [
      {
        "id": "engine id",
        "name": "engine name"
      }
    ]
  },
  "message": "success"
}

b. Abrufen der Liste der Audios einer angegebenen TTS-Engine

:::tips

• URL：/open-api/V2/rest/tts/engine/{id}/audio-list

• Methode：GET

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter: keine Korrekte Datenantwort:

Attribut	Typ	Optional	Beschreibung
audio_list	AudioObject []	N	Audioliste

AudioObject Struktur

Attribut	Typ	Optional	Beschreibung
url	string	N	URL der Audiodatei, zum Beispiel:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Beschriftung der Audiodatei

:::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK **Fehlercode: **

• 190000 Die Engine funktioniert abnormal

Antwortbeispiel:： :::

{
  "error": 0,
  "data": {
    "audio_list": [
      {
        "url": "tts audio address", // zum Beispiel: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "tts audio label"
      }
    ]
  },
  "message": "success"
}

c. Sprachsynthese mit der angegebenen TTS-Engine ausführen

:::tips

• URL：/open-api/V2/rest/tts/engine/{id}/synthesize

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter:

Attribut	Typ	Optional	Beschreibung
text	string	N	Text, der zur Synthese des Audios verwendet wird
label	string	Y	Beschriftung der Audiodatei
language	string	Y	Transparentes Feld. Optionaler Sprachcode für die Syntheseanforderung. Die konkrete Liste der unterstützten Sprachcodes wird vom TTS-Engine-Dienstanbieter bereitgestellt. Beachten Sie, dass der TTS-Engine-Dienst die Standardsprache für die Sprachsynthese unterstützen muss, was bedeutet, dass wenn die Sprache nicht übergeben wird, die Standardsprache der Engine für die Synthese verwendet wird.
options	object	Y	Transparentes Feld. Wird verwendet, um die für die Synthese erforderlichen Konfigurationsparameter an den TTS-Engine-Dienst zu übergeben.

Korrekte Datenantwort:

Attribut	Typ	Optional	Beschreibung
audio	AudioObject	N	Audioliste

AudioObject Struktur

Attribut	Typ	Optional	Beschreibung
url	string	N	URL der Audiodatei, zum Beispiel:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Beschriftung der Audiodatei

:::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK **Fehlercode: **

• 190000 Die Engine funktioniert abnormal

Antwortbeispiel:： :::

{
  "error": 0,
  "data": {
    "audio": {
        "url": "tts audio address" // zum Beispiel, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "tts audio label"
    }
  },
  "message": "success"
}

6.2.2 Kommunikation zwischen Gateway und TTS-Dienst

a. Registrierung des TTS-Engine-Dienstes

Anfrage vom TTS-Dienstanbieter an das Gateway senden

:::tips

• URL：/open-api/V2/rest/thirdparty/event

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter:

Attribut	Typ	Optional	Beschreibung
event	EventObject	N	Strukturinformationen des Request Event Object

EventObject

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Request-Name. Optionaler Parameter.

• RegisterTTSEngine | | message_id | string | N | Request-Nachrichten-ID, UUID_V4 | | version | string | N | Versionsnummer des Anforderungsprotokolls. Derzeit fest auf 1 |

PayloadObject

Attribut	Typ	Optional	Beschreibung
service_address	string	N	Dienstadresse. Zum Beispiel, http:///
name	string	N	Dienstname

Anfragebeispiel:

{
  "event": {
    "header": {
      "name": "RegisterTTSEngine",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {
        "service_address": "service_address",
        "name": "tts service name"
    }
  }
}

**Korrekte Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Antwort-Header-Name. Optionaler Parameter:

• Antwort (Erfolgreiche Antwort)

• ErrorResponse (Fehlerantwort) | | message_id | string | N | Response-Header-Nachrichten-ID, UUID_V4. Eingehende Anforderungsnachricht hier: header.message_id | | version | string | N | Versionsnummer des Anforderungsprotokolls. Derzeit fest auf 1 |

PayloadObject

Attribut	Typ	Optional	Beschreibung
engine_id	string	N	Vom Gateway zugewiesene Engine-ID

:::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK Antwortbeispiel:： ::: Korrektes Antwortbeispiel：

{
    "header": {
      "name": "Response",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {
      "engine_id": "engine id"
    }
  }

**Abnorme Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertyp

• INVALID_PARAMETERS (Parameterfehler)

• AUTH_FAILURE (Authentifizierungsfehler)

• INTERNAL_ERROR (Interner Dienstfehler) | | description | string | N | Fehlerbeschreibung |

Fehlerantwortbeispiel：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address darf nicht leer sein" 
  }
}

b. Befehl zur Synchronisierung der Audioliste

Sendet vom Gateway einen Befehl an den TTS-Dienstanbieter.

:::tips

• URL：<service address>

• Methode：POST

• Header：

  • Content-Type: application/json ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
directive	DirectiveObject	N	Strukturinformationen des Anweisungsobjekts

DirectiveObject

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Request-Name. Optionaler Parameter:

• SyncTTSAudioList | | message_id | string | N | Request-Nachrichten-ID, UUID_V4 | | version | string | N | Versionsnummer des Anforderungsprotokolls. Derzeit fest auf 1 |

Anfragebeispiel:

{
  "directive": {
    "header": {
      "name": "SyncTTSAudioList",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {}
  }
}

**Korrekte Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Antwort-Header-Name. Optionaler Parameter:

• Antwort (Erfolgreiche Antwort)

• ErrorResponse (Fehlerantwort) | | message_id | string | N | Response-Header-Nachrichten-ID, UUID_V4. Eingehende Anforderungsnachricht hier: header.message_id | | version | string | N | Versionsnummer des Anforderungsprotokolls. Derzeit fest auf 1 |

PayloadObject:

Attribut	Typ	Optional	Beschreibung
audio_list	AudioObject []	N	TTS-Audioliste

AudioObject Struktur

Attribut	Typ	Optional	Beschreibung
url	string	N	URL der Audiodatei, zum Beispiel:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Beschriftung der Audiodatei

:::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK Antwortbeispiel:： ::: Korrektes Antwortbeispiel：

{
    "header": {
      "name": "Response",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {
      "audio_list": [
        {
            "url": "tts audio url",
            "label": "tts audio label"
        }
      ]
    }
}

**Abnorme Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertyp

• INVALID_PARAMETERS (Parameterfehler)

• AUTH_FAILURE (Authentifizierungsfehler)

• INTERNAL_ERROR (Interner Dienstfehler) | | description | string | N | Fehlerbeschreibung |

Fehlerantwortbeispiel：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address darf nicht leer sein" 
  }
}

c. Sprachsynthesebefehl

Sendet vom Gateway einen Befehl an den TTS-Dienstanbieter.

:::tips

• URL：<service address>

• Methode：POST

• Header：

  • Content-Type: application/json ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
directive	DirectiveObject	N	Strukturinformationen des Anweisungsobjekts

DirectiveObject

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Request-Name. Optionaler Parameter:

• SynthesizeSpeech | | message_id | string | N | Request-Nachrichten-ID: UUID_V4 | | version | string | N | Versionsnummer des Anforderungsprotokolls. Derzeit fest auf 1 |

PayloadObject

Attribut	Typ	Optional	Beschreibung
text	string	N	Text, der zur Synthese des Audios verwendet wird
label	string	Y	Beschriftung der Audiodatei
language	string	Y	Transparentes Feld. Optionaler Sprachcode für die Syntheseanforderung. Die konkrete Liste der unterstützten Sprachcodes wird vom TTS-Engine-Dienstanbieter bereitgestellt. Beachten Sie, dass der TTS-Engine-Dienst die Standardsprache für die Sprachsynthese unterstützen muss, was bedeutet, dass wenn die Sprache nicht übergeben wird, die Standardsprache der Engine für die Synthese verwendet wird.
options	object	Y	Transparentes Feld. Wird verwendet, um die für die Synthese erforderlichen Konfigurationsparameter an den TTS-Engine-Dienst zu übergeben.

Anfragebeispiel:

{
    "directive": {
        "header": {
            "name": "SynthesizeSpeech",
            "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
            "version": "1"
        },
        "payload": {
            "text": "Eingabetext zur Synthese.",
            "label": "tts audio label"
        }
    }
}

**Korrekte Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
header	HeaderObject	N	Strukturinformationen des Anfrage-Headers
payload	PayloadObject	N	Strukturinformationen der Anfrage-Payload

HeaderObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Antwort-Header-Name. Optionaler Parameter:

• Antwort (Erfolgreiche Antwort)

• ErrorResponse (Fehlerantwort) | | message_id | string | N | Response-Header-Nachrichten-ID, UUID_V4. Eingehende Anforderungsnachricht hier: header.message_id | | version | string | N | Versionsnummer des Anforderungsprotokolls. Derzeit fest auf 1 |

PayloadObject

Attribut	Typ	Optional	Beschreibung
audio	AudioObject	N	TTS-Audio

AudioObject Struktur

Attribut	Typ	Optional	Beschreibung
url	string	N	URL der Audiodatei, zum Beispiel:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Beschriftung der Audiodatei

:::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK Antwortbeispiel:： ::: Korrektes Antwortbeispiel：

{
    "header": {
      "name": "Response",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
      "version": "1"
    },
    "payload": {
      "audio": {
        "url": "tts audio url",
        "label": "tts audio label"
      }
    }
}

**Abnorme Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertyp

• INVALID_PARAMETERS (Parameterfehler)

• AUTH_FAILURE (Authentifizierungsfehler)

• INTERNAL_ERROR (Interner Dienstfehler) | | description | string | N | Fehlerbeschreibung |

Fehlerantwortbeispiel：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Eindeutiger Bezeichner, vorzugsweise eine Version-4-UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address darf nicht leer sein" 
  }
}

7. Multimedia-Modul

7.1 Abspielen einer Audiodatei

:::tips

• URL：/open-api/V2/rest/media/audio-player

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter:

Attribut	Typ	Optional	Beschreibung
audio_url	string	N	Audio-URL-Adresse

Korrekte Datenantwort: :::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. **Statuscode: **200 OK Antwortbeispiel:： :::

{
  "error": 0,
  "data": {},
  "message": "success"
}

8. Benutzerdefinierte UI-Karte

Benutzerdefinierte UI-Karten ermöglichen es Ihnen, beliebige Inhalte innerhalb der Karte anzuzeigen. Dieser Inhalt kann eine Webseite, ein Bild oder jeder Dienst mit einer UI sein. Sie müssen lediglich die URL des Inhalts angeben, den Sie anzeigen möchten. Die UI-Karte passt automatisch Breite und Höhe an, und der Inhalt wird in einem iFrame gerendert.

8.1 Anleitung

Schlüsselrolle

• UI-Dienstanbieter: Der Anbieter, der für die Erstellung benutzerdefinierter UI-Karten auf dem Gateway verantwortlich ist.

• Gateway-Server: Der Gateway-Server (iHost).

• Gateway Open API Client: Der Open API-Client für das Gateway.

8.1.1 Erstellen einer benutzerdefinierten UI-Karte

• [UI-Dienstanbieter]: Ruft die API auf, um eine benutzerdefinierte UI-Karte auf dem Gateway zu erstellen.

• [Gateway-Server]: Nach erfolgreicher Registrierung speichert das Gateway die Basisinformationen der UI-Karte (einschließlich Größenkonfiguration und Kartenressourcen-URL) und weist eine interne UI-Karten-ID innerhalb des Gateways zu.

image.png

8.1.2 Abrufen der UI-Kartenliste

• [UI-Dienstanbieter]: Ruft die API auf, um die Liste der UI-Karten abzurufen.

• [Gateway-Server]: Gibt die auf dem Gateway gespeicherte Liste der UI-Karten zurück, einschließlich benutzerdefinierter UI-Karten, die nicht vom Aufrufer erstellt wurden.

image.png

8.1.3 Ändern der Konfiguration einer angegebenen UI-Karte

• [UI-Dienstanbieter]: Ruft die API auf, um die Konfiguration einer angegebenen UI-Karte zu ändern, z. B. die Größenkonfiguration und die Ressourcen-URL.

• [Gateway-Server]: Nach erfolgreicher Änderung speichert das Gateway die aktualisierten UI-Karteninformationen, einschließlich der neuen Größenkonfiguration und Ressourcen-URL.

image.png

8.1.4 Löschen einer benutzerdefinierten UI-Karte

1. [UI-Dienstanbieter]: Ruft die API auf, um eine angegebene benutzerdefinierte UI-Karte zu löschen.

2. [Gateway-Server]: Das Gateway entfernt alle Informationen, die sich auf die angegebene UI-Karte beziehen.

image.png

8.2 Modul für benutzerdefinierte UI-Karten

8.2.1 Erstellen einer benutzerdefinierten UI-Karte

Der UI-Dienstanbieter sendet eine Anfrage an das Gateway, um eine benutzerdefinierte UI-Karte zu erstellen.

:::tips

• URL：/open-api/v2/rest/ui/cards

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter:

Attribut	Typ	Optional	Beschreibung
label	string	Y	Kartenbezeichnung: Wird verwendet, um die Karte zu beschreiben. Es ist das Alias der Karte.
cast_settings	CastSettingsObject	Y	Cast-Karteneinstellungen: Konfigurationseinstellungen für Cast-Karten.
web_settings	WebSettingsObject	N	Web-Karteneinstellungen: Konfigurationseinstellungen für Web-Karten.

CastSettingsObject:

Attribut	Typ	Optional	Beschreibung
dimensions	DimensionObject []	N	Größenkonfiguration: Muss mindestens eine Konfiguration enthalten.
default	string	N	Standardangabe: Die Standardgrößenspezifikation wird verwendet, mit optionalen Parametern: 2x2

WebSettingsObject:

Attribut	Typ	Optional	Beschreibung
dimensions	DimensionObject []	N	Größenkonfiguration: Muss mindestens eine Konfiguration enthalten.
drawer_component	DrawerObject	Y	Anzeigeeinstellungen der Drawer-Komponente.
default	string	N	Standardspezifikation:

• 1x1

• 2x1 |

DimensionObject:

Attribut	Typ	Optional	Beschreibung
src	string	N	Ressourcen-URL: Zum Beispiel: http://example.html
size	string	N	Größenspezifikationen:
CastSettingsObject optionale Parameter:

• 2×2

WebSettingsObject optionale Parameter:

• 1x1

• 2x1 |

DrawerObject:

Attribut	Typ	Optional	Beschreibung
src	string	N	Ressourcen-URL: Zum Beispiel: http://example.html

Erfolgreiche Datenantwort:

Attribut	Typ	Optional	Beschreibung
id	string	N	Eindeutige UI-Karten-ID

:::tips Bedingungen: Die Anfrageparameter sind gültig und die Benutzer-Identitätsprüfung wurde bestanden. **Statuscode: ** 200 OK ::: Anfragebeispiel：

{
  "label": "ewelink cube card",
  "cast_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×2"
      }
    ],
    "default": "2×2"
  },
  "web_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×1"
      },
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "1×1"
      }
    ],
    "drawer_component": {
      "src": "https://ewelink.cc/ewelink-cube/"
    },
    "default": "2×1"
  }
}

Antwortbeispiel:

{
  "error": 0,
  "data": {
    "id": "72cc5a4a-f486-4287-857f-b482d7818b16"
  },
  "message": "success"
}

8.2.2 Abrufen der UI-Kartenliste

:::tips

• URL：/open-api/v2/rest/ui/cards

• Methode：GET

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter: Keine Antwortparameter:

Attribut	Typ	Optional	Beschreibung
data	CardObject[]	N	UI-Kartenliste

CardObjec Objekt:

Attribut	Typ	Optional	Beschreibung
id	string	N	Karten-ID: Eine eindeutige Kennung für die Karte.
label	string	Y	Kartenbezeichnung: Wird verwendet, um die Karte zu beschreiben. Sie dient als Alias oder Name der Karte.
cast_settings	CastSettingsObject	Y	Kartenbezeichnung: Wird verwendet, um die Karte zu beschreiben. Es ist das Alias der Karte.
web_settings	WebSettingsObject	N	Cast-Karteneinstellungen: Konfigurationseinstellungen für Cast-Karten.
app_name	string	Y	Web-Karteneinstellungen: Konfigurationseinstellungen für Web-Karten.

CastSettingsObject:

Attribut	Typ	Optional	Beschreibung
dimensions	DimensionObject []	N	Größenkonfiguration: Muss mindestens eine Konfiguration enthalten.
default	string	N	Standardspezifikation:
Optionaler Parameter: 2x2
used	string	N	Aktuelle Spezifikation:
Optionaler Parameter: 2x2

WebSettingsObject:

Attribut	Typ	Optional	Beschreibung
dimensions	DimensionObject []	N	Größenkonfiguration: Muss mindestens eine Konfiguration enthalten.
drawer_component	DrawerObject	Y	Anzeigeeinstellungen der Drawer-Komponente.
default	string	N	Standardspezifikation:
Optionaler Parameter:

• 1x1

• 2x1 | | used | string | N | Aktuelle Spezifikation: Optionaler Parameter:

• 1x1

• 2x1 |

DimensionObject:

Attribut	Typ	Optional	Beschreibung
src	string	N	Ressourcen-URL: Zum Beispiel: http://example.html
size	string	N	Größenspezifikationen:
Optionaler Parameter:

• 1x1

• 2x1

Hinweis: Derzeit unterstützen Cast-Karten nur die 2x2-Spezifikation. Die 2x2-Spezifikation wird nicht wirksam sein. |

DrawerObject:

Attribut	Typ	Optional	Beschreibung
src	string	N	Ressourcen-URL: Zum Beispiel: http://example.html

Antwortbeispiel:

{
  "error": 0,
  "data": [
    {
      "id": "72cc5a4a-f486-4287-857f-b482d7818b16",
      "label": "ewelink cube card",
      "cast_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×2"
          }
        ],
        "default": "2×2",
        "used": "2×2"
      },
      "web_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×1"
          },
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "1×1"
          }
        ],
        "drawer_component": {
          "src": "https://ewelink.cc/ewelink-cube/"
        },
        "default": "2×1",
        "used": "2×1"
      },
      "appName": "ewelink-cube"
    }
  ],
  "message": "success"
}

8.2.3 Ändern der Konfiguration einer angegebenen UI-Karte

Autorisierte Benutzer dürfen die Konfiguration einer bestehenden UI-Karte über diese Schnittstelle ändern. Anbieter benutzerdefinierter Karten können nur UI-Karten ändern, die sie erstellt haben.

:::tips

• URL：/open-api/v2/rest/ui/cards/{id}

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter:

Attribut	Typ	Optional	Beschreibung
label	string	Y	Wird verwendet, um die Karte zu beschreiben. Es ist das Alias der Karte.
cast_settings	CastSettingsObject	Y	Cast-Karteneinstellungen
web_settings	WebSettingsObject	Y	Web-Karteneinstellungen

CastSettingsObject:

Attribut	Typ	Optional	Beschreibung
used	string	Y, Entweder used oder src muss angegeben werden, aber mindestens einer dieser Parameter ist erforderlich.	Aktuelle Spezifikation:
Optionaler Parameter:

• 2x2

| | src | string | Y, Entweder used oder src muss angegeben werden, aber mindestens einer dieser Parameter ist erforderlich. | Ressourcen-URL: http://example.html |

WebSettingsObject:

Attribut	Typ	Optional	Beschreibung
used	string	Y, Entweder used oder src muss angegeben werden, aber mindestens einer dieser Parameter ist erforderlich.	Aktuelle Spezifikation:
Optionaler Parameter:

• 1x1

• 2x1 | | src | string | Y, Entweder used oder src muss angegeben werden, aber mindestens einer dieser Parameter ist erforderlich. | Ressourcen-URL: http://example.html |

Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. Die zu ändernde UI-Karte muss von dem Anbieter benutzerdefinierter UI-Karten erstellt worden sein, der die Schnittstelle aufruft. **Statuscode: ** 200 OK Fehlercode:

• 406: Keine Berechtigung zum Zugriff auf diese Ressource ::: **Antwortbeispiel: **

{
  "error": 0,
  "data": {},
  "message": "success"
}

**Anfragebeispiel: **

{
  "cast_settings": {
    "used": "2×2"
  },
  "web_settings": {
    "used": "1×1"
  }
}

8.2.4 Löschen einer benutzerdefinierten UI-Karte

Autorisierte Benutzer dürfen eine bestehende UI-Karte mit dieser Schnittstelle löschen. Anbieter benutzerdefinierter Karten können nur UI-Karten löschen, die sie erstellt haben.

:::tips

• URL：/open-api/v2/rest/ui/cards/{id}

• Methode：DELETE

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anforderungsparameter: Keine Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anforderungsparameter sind gültig und die Benutzeridentitätsprüfung ist bestanden. Die zu ändernde UI-Karte muss von dem Anbieter benutzerdefinierter UI-Karten erstellt worden sein, der die Schnittstelle aufruft. **Statuscode: ** 200 OK Fehlercode:

• 406: Keine Berechtigung zum Zugriff auf diese Ressource. ::: **Antwortbeispiel: **

{
  "error": 0,
  "data": {},
  "message": "success"
}