Entwickler- & API-Anleitung

1. Erste Nutzung

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 Ihrem Browser ein.

Hinweis: Wenn Sie mehrere Gateways haben, können Sie die entsprechende IP-Adresse abrufen, um auf das angegebene Gateway auf die folgenden zwei Weisen 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 Erste Schritte

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

// 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 [Access Token]-Schnittstelle erneut auf. Die Antwort ist erfolgreich und das Token wird 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 [Get Device List]-Schnittstelle auf. Die Antwort ist erfolgreich und die Geräteliste wird 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": "Gerätename",
        "manufacturer": "Herstellername",
        "model": "Modellname",
        "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 Abrufen des CUBE-Zugriffstokens: Nachdem die [Access Token]-Schnittstelle aufgerufen wurde, fordert das globale Popup-Feld der CUBE-Webkonsole den Benutzer auf, die Erteilung der Schnittstellenaufruf-Anmeldeinformationen zu bestätigen.

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

2. Kernkonzept

2.1 Adresse der Entwicklungs-Schnittstelle

Die Web-API-Schnittstelle des Gateways hat zwei Zugriffsmethoden (basierend auf IP oder Domänennamen), normalerweise ist der Stamm-Pfad /open-api/V2/rest/< specific function module >

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

// Domain-Name-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 (Geräte-)spezifische Kategorien zu identifizieren, wie z. B. switch, plug, light usw. Diese Informationen bestimmen die UI-Anzeige des Geräts im Gateway.

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

  • capability: Beschreibt den Fähigkeitsnamen, der global eindeutig sein muss und vom Typ String ist. Mehrere englische Wörter sollten mit Bindestrichen ("-") getrennt werden. Zum Beispiel: "thermostat-target-setpoint".

  • name: Beschreibt die Kategorie unter der Fähigkeit, ebenfalls vom Typ String. Mehrere englische Wörter sollten mit Bindestrichen ("-") 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 sind:

    • Gerät steuerbar: "1000"

    • Gerät konfigurierbar: "0010"

    • Gerät steuerbar und konfigurierbar: "1010"

    • Gerät steuerbar und meldungsfä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 sind in der Tabelle unten aufgeführt.

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

• Erlaube die Änderung dieses Konfigurationselements: "10"

• Erlaube das Anzeigen dieses Konfigurationselements: "01"

• Erlaube sowohl Änderung als auch Anzeige dieses Konfigurationselements: "11"

Bit-Erklärung:

1. Bit 0: Erlaubt das Anzeigen dieses Konfigurationselements

2. Bit 1: Erlaubt die Änderung dieses Konfigurationselements | | Typ | string | N | Beschreibt den Datentyp des Wertes 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. Doppeltgenaue 64-Bit-Binärform im IEEE-754-Format
int	Ganzzahliger Datentyp.
object	Objektdatentyp. JSON-kompatibles Objekt
string[]	Array von Strings
int[]	Array von Ganzzahlen
object[]	Array von Objekten
bool	Boolesch
date	Zeitzeichenfolge. Zeichenfolge im ISO-Format (ISO 8601 Extended Format): YYYY-MM-DDTHH:mm:ss.sssZ. Die Zeitzone ist immer UTC (Coordinated Universal Time), gekennzeichnet durch ein Suffix "Z".

Allgemeine Antwort-Ergebnisse

Attribut	Typ	Optional	Beschreibung
error	int	N	Fehlercode:
0: Erfolg
400: Parameterfehler
401: Authentifizierung fehlgeschlagen
500: Server-Ausnahme
data	object	N	Antwort-Datenkörper
message	string	N	Antwortbeschreibung:
Wenn error gleich 0 ist, ist der Inhalt success
Wenn error ungleich 0 ist, ist es eine nicht-leere Zeichenfolge, 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 Töne	- 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 (System heruntergefahren) -deviceDiscovered (Gerät entdeckt)

• system Armed (System scharfgeschaltet aktiviert)

• system Disarmed (System scharfgeschaltet 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 einem Gerätezurücksetzen gelöscht.

• Hinweis: Nachdem Sie das Token erhalten haben, 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 Schnittstellenzugriffs-Token. Es ist langfristig gültig, bitte speichern Sie es
app_name	string	Y	Beschreibung des Anwendungsnamens.

:::tips Bedingung: Benutzer löst die < Befehlstaste > aus und greift innerhalb der gültigen Zeit auf diese Schnittstelle zu. **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 < Befehlstaste > 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 zu erhalten :::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-Auslastungsprozent. [0-100]
cpu_used	int	N	CPU-Auslastungsprozentsatz. [0-100]
power_up_time	date	N	Die letzte Einschaltdauer
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-Auslastung (Prozentsatz):
Bereich:[0-100] mit einer Nachkommastelle Präzision
*Hinweis: Wenn die SD-Karte nicht eingesetzt oder nicht formatiert ist, ist der Wert leer.

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitä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 einstellen

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 legal und die Benutzeridentitä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-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 legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

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

f. Gateway Stummschaltung aufheben

Ermöglicht autorisierten Benutzern, die Stummschaltung des Gateways über diese Schnittstelle aufzuheben. :::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 legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

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

g. Gateway-Alarm abbrechen

Ermöglicht autorisierten Benutzern, den Alarmtonstatus am Gateway ü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 legal und die Benutzeridentitä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 legal und die Benutzeridentitä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 (Piepton abspielen)
sound	SoundObject	Y (N, falls type play_sound ist.)	Der Ton.
beep	BeepObject	Y (N, falls type play_beep ist.)	Der Piepton

SoundObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Der Tonname. Die unterstützten Werte können in [Ressourcenliste - Unterstützte Töne] überprüft werden
volume	int	N	Die Lautstärke des Tons. [0-100]
countdown	int	N	Die Dauer, für die der Lautsprecher den Ton abspielt; nach Ablauf der Zeit wird die Wiedergabe automatisch gestoppt. Einheit: Sekunde. [0,1799]

BeepObject

Attribut	Typ	Optional	Beschreibung
name	string	N	Der Deep-Name. Die unterstützten Werte können in [Ressourcenliste - Unterstützte Deep] überprüft werden
volume	int	N	Die Deep-Lautstärke. [0-100]

Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: ** 200 OK ::: Antwortbeispiel:

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

3.3 Geräteverwaltungsfunktion

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
Wassermelder	waterLeakDetector	≥ 2.1.0
Rauchmelder	smokeDetector	≥ 2.1.0
Drahtloser Knopf	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 Fähigkeitsdeklaration:

[
  {
    "capability": "power", // Name der Fähigkeit
    "permission": "1100",  // ihost unterstützt keine Konfiguration von Soft-Start/Stop, daher kein configure-Feld
  }
]

Statusattribut:

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

Protokoll (Statusabfrage & Steuerungsbefehle):

Einschalten:

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

Ausschalten:

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

Kanalumschalter (toggle):

Beispiel für Fähigkeitsdeklaration:

Einzelkomponenten-Beispiel:

[
  {
    "capability": "toggle", // Name der Fähigkeit
    "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ß- und Kleinbuchstaben und Zahlen
  }
]

Beispiel für mehrere Komponenten:

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

Statusattribut:

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

Protokoll (Statusabfrage & Steuerungsbefehle):

Umschaltformat:

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

Kanal-Impuls (toggle-inching):

Beispiel für Fähigkeitsdeklaration:

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

Statusattribut

Keine

Protokoll (Statusabfrage & Steuerungsbefehle)

Keine

Helligkeitsregelung (brightness):

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "brightness", // Name der Fähigkeit
  "permission": "1100"  // Berechtigung
}

Statusattribut:

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

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

Farbtemperaturregelung (color-temperature):

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "color-temperature", // Name der Fähigkeit
  "permission": "1100"  // Berechtigung
}

Statusattribut:

{
  "colorTemperature": 100, // Feld colorTemperature gibt den Farbtemperaturprozentsatz an. Wähle zwischen colorTemperature oder colorTemperatureDelta. **Typ:** Number. Bereich: 0-100. 0 steht für warmes Licht, 50 für neutrales Licht, 100 für kühles Licht.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

Farbtemperatur auf 50 % einstellen:

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

Farbregelung (color-rgb):

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "color-rgb", // Name der Fähigkeit
  "permission": "1100"  // Berechtigung
}

Statusattribut:

{
  "red": 255, // Feld red repräsentiert den Rotwert im RGB-Farbraum. Erforderlich. **Typ:** Number. Bereich: 0-255.
  "green": 0, // Feld green repräsentiert den Grünwert im RGB-Farbraum. Erforderlich. **Typ:** Number. Bereich: 0-255.
  "blue": 255 // Feld blue repräsentiert den Blauwert im RGB-Farbraum. Erforderlich. **Typ:** Number. Bereich: 0-255.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

Farbe auf Lila setzen:

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

Prozentuale Einstellung (percentage):

Beispiel für Fähigkeitsdeklaration:

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

Statusattribut:

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

Protokoll (Statusabfrage & Steuerungsbefehle):

Auf 40 % einstellen:

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

Motorsteuerung (motor-control):

Beispiel für Fähigkeitsdeklaration:

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

Statusattribut:

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

Protokoll (Statusabfrage & Steuerungsbefehle):

Motor öffnen:

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

Motordrehrichtungsumkehr (motor-reverse):

Beispiel für Fähigkeitsdeklaration:

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

Statusattribut:

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

Protokoll (Statusabfrage & Steuerungsbefehle):

Motor auf Vorwärts einstellen:

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

Motorkalibrierung (motor-clb)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusmeldung):

Melde, dass der Motor kalibriert wird:

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

Einschaltzustand beim Start (startup)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

Stromzustand auf Immer An setzen:

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

---

Weckaktivierung (identify)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusmeldung & Steuerungsbefehle):

Weckaktivierungszeit einstellen:

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

Aktivierungsstatus melden:

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

Echtzeit-Leistungsstatistik-Schalter (power-consumption)

Beispiel für Fähigkeitsdeklaration:

{
  "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 (Status):

Echtzeitstatistik starten/stoppen:

{
  "rlSummarize": true, // Start/Stop der Echtzeitstatistik. **Typ:** Boolean. Erforderlich.
  "timeRange": { // Zusammengefasster Zeitraum. Erforderlich.
    "start": "2020-07-05T08:00:00Z", // Beginn der Stromverbrauchsstatistik. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Ende der Stromverbrauchsstatistik. **Typ:** String. Erforderlich.
  }
}

Stromverbrauch nach Zeitraum abfragen:

{
  "type": "summarize", // Typ 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", // Beginn der Stromverbrauchsstatistik. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Ende der Stromverbrauchsstatistik. **Typ:** String. Optional. Wenn weggelassen, entspricht dies der aktuellen Zeit.
  }
}

Mit Ergebnis der Statistik innerhalb des Zeitraums antworten:

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

Protokoll (Statusmeldung & Steuerungsbefehle):

Echtzeitstatistik starten:

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

Echtzeitstatistik stoppen:

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

Historischen Stromverbrauch abrufen:

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

Echtzeit-Stromverbrauch abrufen:

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

Temperatur- und Feuchtigkeitsmodus-Erkennung (thermostat-mode-detect)

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "temperature", // Art der Temperatur-/Feuchtigkeits-Erkennung. **Typ:** String. Erforderlich. Optionale Werte: "humidity" (Feuchtigkeitserkennung), "temperature" (Temperaturerkennung).
  "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 existieren.
              "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 existieren.
              "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", // Art der Temperatur-/Feuchtigkeits-Erkennung. **Typ:** String. Erforderlich. Optionale Werte: "humidity" (Feuchtigkeitserkennung), "temperature" (Temperaturerkennung).
  "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 existieren.
              "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 existieren.
              "value": 68.0, // Feuchtigkeitswert. **Typ:** Number. Erforderlich
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

Attribute (Status):

{
  "mode": "COMFORT" // Mode-ID. Optional. Unterstützte Werte: "COMFORT" (Komfortmodus), "COLD" (Kältemodus), "HOT" (Heizmodus), "DRY" (Trockenmodus), "WET" (Feuchtmodus).
}

Protokoll (Statusabfrage & Steuerungsbefehle):

Format:

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

Beispiel:

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

Thermostatmodus (thermostat-mode)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

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

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Einstellung der Zieltemperatur des Thermostatmodus (thermostat-target-setpoint)

Beispiel für Fähigkeitsdeklaration:

[[
  {
    "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 (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Sensordetektion (detect)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Temperaturerkennung (temperature)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Feuchterkennung (humidity)

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "humidity",
  "permission": "0100",
  "settings": { // Optionaler Bereich für Feuchterkennung.
    "humidityRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 100
    }
  }
}

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Batteriestatus (battery)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Einzeltastenerkennung (press)

Beispiel für Fähigkeitsdeklaration:

{
  "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 (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Mehrfachtastenerkennung (multi-press)

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "multi-press",
  "permission": "0100",
  "name": "1", // Name des multi-press-Attributs. **Typ:** String. 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 (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

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

Signalstärke-Erkennung (rssi)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Manipulationsalarm (tamper-alert)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Beleuchtungsstärke-Erkennung (illumination-level)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Spannungserkennung (voltage)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Stromstärke-Erkennung (electric-current)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Leistungserkennung (electric-power)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Fehlererkennung (fault)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Schwellwert-Übertreter (threshold-breaker)

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "threshold-breaker",
  "permission": "0010",
  "settings": {
    "supportedSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "supported": [
          {
            "name": "lowerPower", // Niedriger Leistungs-Schwellenwert-Übertreter
            "value": {
              "value": 50, // Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimale Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 3500 // Maximale Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "upperPower", // Hoher Leistungs-Schwellenwert-Übertreter
            "value": {
              "value": 50, // Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimale Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 3500 // Maximale Erkennungsleistungswert, in 0,01W-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "lowerElectricCurrent", // Niedriger Strom-Schwellenwert-Übertreter
            "value": {
              "value": 50, // Erkennungsstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungsstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 1500 // Maximaler Erkennungsstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "upperElectricCurrent", // Hoher Strom-Schwellenwert-Übertreter
            "value": {
              "value": 50, // Erkennungsstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "min_range": 10, // Minimaler Erkennungsstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
              "max_range": 1500 // Maximaler Erkennungsstromwert, in 0,01A-Einheiten. **Typ:** Integer. Bereich: >=0.
            }
          },
          {
            "name": "lowerVoltage", // Niedriger Spannungs-Schwellenwert-Übertreter
            "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-Übertreter
            "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 (Status)

• Keine

Protokoll (Statusabfrage & Steuerungsbefehle)

• Keine

Impulsfunktion (inching)

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // Einstellung zur Aktivierung der Impulsfunktion
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Einstellung der Impulsaktion
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Einstellung der Impulszeit
      "type": "numeric",
      "permission": "11",
      "min": 500,
      "max": 100000,
      "value": 1000,
      "unit": "ms"
    }
  }
}

Attribute (Status):

• Keine

Protokoll (Statusabfrage & Steuerungsbefehle):

• Keine

Kamerastream (camera-stream)

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "camera-stream",
  "permission": "0010",
  "settings": {
    "streamSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "username": "String", // Zugriffsaccount. **Typ:** String. Erforderlich.
        "password": "String", // Zugriffspasswort. **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, // Key-Frame-Abstand. **Typ:** String. Erforderlich.
        "audioCodec": "G711", // Audiocodec. **Typ:** String. Erforderlich. Optionale Parameter sind zu definieren.
        "samplingRate": 50, // Audio-Abtastrate in Hz. **Typ:** Number. Erforderlich. Optionale Parameter sind zu definieren.
        "dataRate": 50 // Bitrate. **Typ:** Number. Erforderlich. Einheit: kb/s.
      }
    }
  }
}

Attribute (Status):

• Keine

Protokoll (Statusabfrage & Steuerungsbefehle):

• Keine

Modussteuerung (mode)

Beispiel für Fähigkeitsdeklaration:

[
  {
    "capability": "mode",
    "name": "fanLevel",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["low", "medium", "high"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "thermostatMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["auto", "manual"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "airConditionerMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["cool", "heat", "auto", "fan", "dry"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben Standardwerte.
      }
    }
  },
  {
    "capability": "mode",
    "name": "fanMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["normal", "sleep", "child"] // Benutzerdefinierte Moduswerte. Konfigurierte Werte überschreiben 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 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 Standardwerte.
      }
    }
  }
]

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Kohlendioxid-Erkennung (co2)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Beleuchtungsstärke-Erkennung (illumination)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Raucherkennung (smoke)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

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

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Bewegungserkennung (motion)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Wasserleck-Erkennung (water-leak)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Fenstererkennungs-Schalter (window-detection)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "powerState": "on" // Feld `powerState` gibt den Stromzustand an. **Typ:** String. `on` bedeutet eingeschaltet, `off` bedeutet ausgeschaltet.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Kindersicherungsschalter (child-lock)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "powerState": "on" // Feld `powerState` gibt den Stromzustand an. **Typ:** String. `on` bedeutet eingeschaltet, `off` bedeutet ausgeschaltet.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

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

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "powerState": "on" // Feld `powerState` gibt den Stromzustand an. **Typ:** String. `on` bedeutet eingeschaltet, `off` bedeutet ausgeschaltet.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Horizontaler Schwenkschalter (horizontal-swing)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "powerState": "on" // Feld `powerState` gibt den Stromzustand an. **Typ:** String. `on` bedeutet eingeschaltet, `off` bedeutet ausgeschaltet.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Vertikaler Schwenkschalter (vertical-swing)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "powerState": "on" // Feld `powerState` gibt den Stromzustand an. **Typ:** String. `on` bedeutet eingeschaltet, `off` bedeutet ausgeschaltet.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

ECO-Modus-Schalter (eco)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "powerState": "on" // Feld `powerState` gibt den Stromzustand an. **Typ:** String. `on` bedeutet eingeschaltet, `off` bedeutet ausgeschaltet.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Umschalten beim Start (toggle-startup)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Erkennungs-Halten (detect-hold)

Beispiel für Fähigkeitsdeklaration:

{
  "capability": "detect-hold",
  "permission": "0100",
  "settings": {
    "detectHoldEnable": { // Einstellung zum Aktivieren des Erkennungs-Haltens
      "permission": "01",
      "type": "boolean",
      "value": false
    },
    "detectHoldSwitch": { // Einstellung der Aktion für Erkennungs-Halten
      "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 (Status):

{
  "detectHold": "on" // Feld `detectHold` gibt den Status des Erkennungs-Haltens an. **Typ:** String. `on` bedeutet Erkennungs-Halten ist aktiv, `off` bedeutet inaktiv.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Umschalten Identifizieren/Aktivieren (toggle-identify)

Beispiel für Fähigkeitsdeklaration:

{
  "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 (Status):

{
  "identify": true, // Zeigt an, dass das Gerät eine aktive Identifikations- oder Aktivierungsmeldung gesendet hat.
  "countdown": 180 // Feld `countdown` gibt die Aktivierungsdauer an. **Typ:** Number. Einheit: Sekunden.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

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

Umschalten Spannungserkennung (toggle-voltage)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Unterkomponenten-Stromerkennung (toggle-electric-current)

Beispiel für Fähigkeitsdeklaration:

[
  {
    "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 (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Unterkomponenten-Leistungserkennung (toggle-electric-power)

Beispiel für Fähigkeitsdeklaration:

[
  {
    "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 (Status):

{
  "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 die aktuelle Blindleistung. **Einheit:** 0.01 W. **Typ:** Integer. Optional.
  "activePower": 50, // Feld `activePower` repräsentiert die aktuelle Wirkleistung. **Einheit:** 0.01 W. **Typ:** Integer. Optional.
  "apparentPower": 50 // Feld `apparentPower` repräsentiert die Scheinleistung. **Einheit:** 0.01 W. **Typ:** Integer. Optional.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Unterkomponenten Energieverbrauchsstatistik (toggle-power-consumption)

Beispiel für Fähigkeitsdeklaration:

[
  {
    "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 (Status):

Echtzeitstatistik starten/stoppen:

{
  "rlSummarize": true, // Start oder Stopp der Echtzeitstatistik. **Typ:** Boolean. Erforderlich.
  "timeRange": { // Zusammenfassender Zeitbereich. Erforderlich.
    "start": "2020-07-05T08:00:00Z", // Startzeit der Energieverwendung. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Endzeit der Energieverwendung. **Typ:** String. Erforderlich.
  }
}

Stromverbrauch nach Zeitraum abfragen:

{
  "type": "summarize", // Zusammenfassungstyp. **Typ:** String. Erforderlich. Optionen: "rlSummarize" (Echtzeit-Zusammenfassung), "summarize" (Aktuelle Zusammenfassung).
  "timeRange": { // Zusammenfassender Zeitbereich, erforderlich wenn Typ "summarize" ist.
    "start": "2020-07-05T08:00:00Z", // Startzeit der Energieverwendung. **Typ:** String. Erforderlich.
    "end": "2020-07-05T09:00:00Z" // Endzeit der Energieverwendung. **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": [ // Aufgeteilt nach `configuration.resolution` in mehrere Einträge. 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. Einträge 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. Einträge mit kürzeren Intervallen als die Auflösung gelten als ungültig.
    }
  ]
}

Protokoll (Statusabfrage & Steuerungsbefehle):

Echtzeitstatistik starten:

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

Echtzeitstatistik stoppen:

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

Historischen Stromverbrauch abrufen:

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

Echtzeit-Stromverbrauch abrufen:

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

Verbindungsqualitätsindikator (lqi)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Funktionale Konfiguration (configuration)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "deviceConfiguration": { // Gerätebezogene Funktionskonfiguration
    "defaultResolution": 300, // Standardauflösung zum Lesen der Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
    "maxResolution": 86400, // Maximale Auflösung zum Lesen der Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
    "minResolution": 60 // Minimale Auflösung zum Lesen der Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
  }
}

Protokoll (Statusabfrage & Steuerungsbefehle):

{
  "configuration": {
    "deviceConfiguration": { // Gerätebezogene Funktionskonfiguration
      "defaultResolution": 300, // Standardauflösung zum Lesen der Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
      "maxResolution": 86400, // Maximale Auflösung zum Lesen der Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
      "minResolution": 60 // Minimale Auflösung zum Lesen der Feuchtigkeits-Sättigungsdaten. **Typ:** Integer. **Einheit:** Sekunden. Erforderlich.
    }
  }
}

System (system)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "restart": true // Neustart-Befehl für das Gerät. **Typ:** Boolean. Erforderlich. Wert muss `true` sein.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Feuchtigkeit (moisture)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Luftdruck (barometric-pressure)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Windgeschwindigkeit (wind-speed)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Windrichtung (wind-direction)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Niederschlag (rainfall)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

UV-Index (ultraviolet-index)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "ultravioletIndex": 11.1 // UV-Index. **Typ:** Number. Erforderlich.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Elektrische Leitfähigkeit (electrical-conductivity)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "electricalConductivity": 11.11 // Wert der elektrischen Leitfähigkeit. **Typ:** Number. Erforderlich. **Einheit:** dS/m.
}

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Sendeleistung (transmit-power)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

PM2,5-Erkennung (pm25)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

VOC-Index (voc-index)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Erdgas-Erkennung (gas)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Bewässerungsarbeitsstatus (irrigation/work-status)

Beispiel für Fähigkeitsdeklaration:

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

Attribute (Status):

{
  "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 & Steuerungsbefehle):

Berichterstattung zum 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": { // Zeitbereich für die Aggregation. **Typ:** Objekt. Erforderlich.
      "start": "2020-07-05T08:00:00Z", // Startzeit für die Aggregation von Bewässerungsdaten. **Typ:** String. Erforderlich.
      "end": "2020-07-05T09:00:00Z" // Endzeit für die Aggregation von Bewässerungsdaten. **Typ:** String. Optional. Wenn ausgelassen, 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 Fähigkeitsdeklaration:

[
  {
    "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 (Status):

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

Protokoll (Statusabfrage & Steuerungsbefehle):

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

Automatischer Bewässerungsregler (irrigation/auto-controller)

Beispiel für Fähigkeitsdeklaration:

[
  {
    "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 (Status):

Einmalige 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, // Verbrachtes Volumen 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 & Steuerungsbefehle):

Einmalige 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, // Verbrachtes Volumen 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/die Gruppe, die der id entspricht, existiert nicht	≥2.1.0
110001	Das Gateway befindet sich im Zustand des Entdeckens von Zigbee-Geräten	≥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 fehlerhaft	≥2.1.0
110010	Zugriffsautorisierungsfehler des Kamerageräts	≥2.1.0
110011	Stream-Adresse des Kamerageräts fehlerhaft	≥2.1.0
110012	Video-Codierung der Kamera 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 des Entdeckens von ONVIF-Kameras	≥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	Zugriff auf die Service-Adresse des Drittanbietergeräts fehlgeschlagen	≥2.1.0

e. Suche nach Untergeräten

Ermöglicht 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 "Manuell Untergeräte 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 (Paarung starten); false (Paarung pausieren)
type	string	N	Suchtyp: Zigbee

Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: ** 200 OK ::: Antwortbeispiel:

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

f. Manuelles Hinzufügen des Untergeräts

Ermöglicht 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 capabilities 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	Geräte-Firmware-Version

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	Konfiguration des Stream-Dienstes

StreamSettingObject

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

StreamSettingValueObject

Attribut	Typ	Optional	Beschreibung
stream_url	string	N	Format der Stream-URL
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 das <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 legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

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

Fehlschlag-Datenantwort: leeres Objekt :::tips Bedingung：

1. Fehler beim Zugriff auf die Kamera-Stream-Adresse (Formatfehler, Autorisierungsfehler, Netzwerk-Ausnahme usw.)

2. Gerät existiert bereits

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

Statuscode: 200 OK Fehlercode： ● 110009 Kamera-IP-Adresse fehlerhaft ● 110010 Kamerazugriffs-Autorisierungsfehler ● 110011 Kamera-Stream-Adresse fehlerhaft ● 110012 Die Kamera-Video-Codierung 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öglicht autorisierten Benutzern, die Liste der Gateway-Untergeräte über diese Schnittstelle zu erhalten. :::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 angeschlossen ist, ansonsten "Y"	Eindeutige Seriennummer des Drittanbietergeräts
service_address	string	"N" wenn ein Drittanbietergerät angeschlossen ist, ansonsten "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 ein leerer String sein.
hostname	string	Y	Geräte-Hostname
mac_address	string	Y	MAC-Adresse des Geräts
app_name	string	Y	Der Name der Anwendung, zu der es gehört. Wenn bei der Erlangung des Open-Interface-Zertifikats app_name ausgefüllt wurde, werden alle nachfolgenden über das Zertifikat verbundenen Geräte in dieses Feld geschrieben.
display_category	string	N	Gerätekategorie
capabilities	CapabilityObject[]	N	Gerätefähigkeiten
protocol	string	"N" wenn ein Drittanbietergerät angeschlossen ist, ansonsten "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 verwendet, um Gerätekanäle zu speichern - Wird verwendet, um Temperatureinheiten zu speichern - Benutzerdefinierte Informationen für andere Drittanbietergeräte
online	boolean	N	Online-Status: True für online False ist offline
Subnetz	boolean	Y	Ob es sich im gleichen 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	Name der Fähigkeit. Für 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 zur Identifizierung von Mehrkanalgeräten verwendete Unterkanalnummer. Wenn z. B. name 1 ist, bedeutet dies Kanal 1.

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitä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 bestimmter Geräteinformationen oder -zustände

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 für Fähigkeiten, derzeit unterstützt nur die Fähigkeit camera_stream Änderungen.

Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung wurde 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

  • Autorisierung: 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 für Fähigkeiten; alle Fähigkeiten, die das Setzen 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 wurde bestanden. **Statuscode: **200 OK Fehlercodes:

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

• 110006: Aktualisierung des Gerätestatus fehlgeschlagen.

• 110019: Zugriff auf die Drittanbieterdienstadresse 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

  • Autorisierung: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

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

k. Gerätezustand abfragen

Ermöglicht autorisierten Benutzern, den Gerätezustand ü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ätezustand 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 Statistiken, erforderlich
          "timeRange": { // Zeitbereich für die Zusammenfassung, erforderlich wenn type="summarize"
            "start": "2020-07-05T08:00:00Z", // Startzeit für Leistungsverbrauchsstatistiken
            "end": "2020-07-05T09:00:00Z" // Endzeit für Leistungsverbrauchsstatistiken; wenn ausgelassen, Standard ist die aktuelle Zeit
          }
        }
      }
    });
})()

Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitä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

  • Autorisierung: 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 legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

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

b. Bestimmten Sicherheitsmodus aktivieren

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

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

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Autorisierung: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

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

c. Bestimmten Sicherheitsmodus deaktivieren

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

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

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Autorisierung: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitä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-Sicherheits-Einrichtungsmodus über diese Schnittstelle zu aktivieren. :::tips

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

• Methode：PUT

• Header：

  • Content-Type: application/json

  • Autorisierung: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitä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

  • Autorisierung: Bearer ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: leeres Objekt {} :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: **200 OK ::: Antwortbeispiel:

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

4. Zugriff von Drittanbietergeräten

4.1 Zugriffsanleitung

Gerätezugriff

Zugriff für Drittanbieter-Gateway

Zugriffsschritte

1. Bestimmen Sie die Klassifizierung des Geräts im Gateway. Die Details finden Sie bitte unter [Supported Device Type].

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

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

   1. Achtung: Sie müssen die Serviceadresse bereitstellen, um die vom Gateway ausgestellten Anweisungen zu empfangen. Diese Adresse wird verwendet, um die vom Gateway ausgestellten Geräte-Steueranweisungen 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 an das Gateway zurückzusenden.

5. Nach dem Hinzufügen erscheint das Drittanbietergerät in der Geräteliste mit den 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, nachdem das Gerät mit dem Gateway verbunden ist.

• Wählen Sie die richtige Gerätegröße. Die Fähigkeitsliste bestimmt den Zustand des Gerätestatusprotokolls.

Programmvorgang

a. Gerätezugriff

b. Drittanbieter-Gateway-Zugriff

4.2 Zugriffsbeispiel

Schalter, Steckdose

Synchronisieren von Drittanbietergeräten

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

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

Gerätezustand melden

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

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

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

Offline/Online melden

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

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

Empfangen der Anweisungen zur Gateway-Gerätesteuerung

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

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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 UUID Version 4",
    "version": "1"
  },
  "payload": {}
}

Gerät abfragen

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

{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "serial number",
        "third_serial_number": "third_serial_number",
        "name": "meine Steckdose",
        "manufacturer": "Herstellername",
        "model": "Modellname",
        "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-Endpunkts Hinweis: 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	Anforderungsname. Optionale Parameter: DiscoveryRequest: Synchronisieren neuer Geräte DeviceStatesChangeReport: Bericht über Gerätestatusaktualisierungen DeviceOnlineChangeReport: Bericht über Online-Status des Geräts
message_id	string	N	Anfrage-Nachrichten-ID, UUID_V4
version	string	N	Angeforderte Protokollversionsnummer. Derzeit auf 1 festgelegt

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] - [Tags-Beschreibung]

PayloadObject Je nach unterschiedlichem header.name gibt es unterschiedliche Anfragestrukturen.

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. Hier die im Anfrage-Header message_id übergebene ID einfügen *Wenn die Anfrage keinen message_id-Parameter enthält, ist dieses Feld bei der Antwort eine leere Zeichenkette.
version	string	N	- Angeforderte Protokollversionsnummer. Derzeit auf 1 festgelegt.

Erfolgreiche Antwort--PayloadObject ：

Je nach Anforderungstyp unterscheidet sich die Antwortstruktur. Details finden Sie in der jeweiligen Anforderungsdokumentation.

Fehlerantwort--PayloadObject：

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertypen:

• INVALID_PARAMETERS: Parameterfehler

• AUTH_FAILURE: Autorisierungsfehler

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

DiscoveryRequest Synchronisiert eine neue Geräteliste

• Hinweis: Nachdem das Gerät mit dem Gateway synchronisiert wurde, ist es standardmäßig online, d. h. online=true. Nachfolgende Online-Änderungen hängen vollständig von der Synchronisierung mit dem Drittanbieter über die DeviceOnlineChangeReport-Schnittstelle 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. Details siehe [Supported Device Type]. *Drittanbietergeräte unterstützen derzeit das Hinzufügen von Kameras nicht.
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 speichern Wird verwendet, um Temperatureinheiten zu speichern Andere benutzerdefinierte Drittanbieterdaten
firmware_version	string	N	Firmware-Version
service_address	string	N	Serviceadresse. Zum Beispiel http://192.168.31.14/service_address

Beispiel einer Anfrage:

{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "meine Steckdose",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "Herstellername",
          "model": "Modellname",
          "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 einer korrekten Antwort:

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

Beispiel einer Fehlerantwort:

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

DeviceStatesChangeReport Bericht über Änderungen des Gerätezustands

• Hinweis: Wiederholte Statusberichte können fälschlicherweise zu einer Auslösung einer zugehörigen Szene führen.

Anfrageparameter: PayloadObject：

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

Beispiel einer Anfrage:

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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 UUID Version 4",
    "version": "1"
  },
  "payload": {}
}

DeviceOnlineChangeReport Bericht über den Online-Status des Geräts

• Hinweis: Wiederholte Statusberichte können fälschlicherweise zu einer Auslösung einer zugehörigen Szene führen.

Anfrageparameter: PayloadObject：

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

Beispiel einer Anfrage:

{
  "event": {
    "header": {
      "name": "DeviceOnlineChangeReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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 UUID Version 4",
    "version": "1"
  },
  "payload": {}
}

DeviceInformationUpdatedReport Bericht über aktualisierte Geräteinformationen

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

Anfrageparameter: PayloadObject：

Attribut	Typ	Optional	Beschreibung
capabilities

| CapabilityObject[]

| N

| Fähigkeitenliste. 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 erlaubt, wenn das permission für den Einstellung Schlüssel ist 11 oder 01. Für die spezifische Strukturdefinition des Einstellung in CapabilityObjectsiehe die detaillierte Beschreibung in Abschnitt 2.3 Geräteanzeigekategorien & 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 einer Anfrage:

{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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 UUID Version 4",
    "version": "2"
  },
  "payload": {}
}

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

• Hinweis:

1. Die Drittanbieter müssen innerhalb von 3s auf die Anforderung des Gateways antworten. Andernfalls beurteilt das Gateway die Befehlsverarbeitung als zeitüberschritten.

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

Anfrageformat

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

• URL：

• Methode：POST

• Header：

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

Attribut	Typ	Optional	Beschreibung
directive	DirectiveObject	N	Strukturinformationen des Direktivenobjekts

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	Anforderungsname. Optionale Parameter: UpdateDeviceStates: Gerätezustände aktualisieren
message_id	string	N	Anfrage-Nachrichten-ID, UUID_V4
version	string	N	Angeforderte Protokollversionsnummer. Derzeit auf 1 festgelegt.

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] - [Tags-Beschreibung]

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

Beispiel einer Anfrage:

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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. Optionaler Parameter: UpdateDeviceStatesResponse: Antwort auf Gerätezustandsaktualisierung ErrorResponse: Fehlerantwort
message_id	string	N	Nachrichten-ID des Antwort-Headers, UUID_V4. Hier die im Anfrage-Header message_id übergebene ID einfügen
version	string	N	Angeforderte Protokollversionsnummer. Derzeit auf 1 festgelegt.

Erfolgreiche Antwort--PayloadObject：

Je nach Anforderungstyp unterscheidet sich die Antwortstruktur. Details finden Sie in der jeweiligen Anforderungsdokumentation.

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: Ungewöhnliche Direktive 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: Fernbedienungs-Tastencode nicht gelernt |

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

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

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

UpdateDeviceStates

Anfrageparameter: PayloadObject：

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

Beispiel einer Anfrage:

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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 UUID Version 4",
    "version": "1"
  },
  "payload": {}
}

QueryDeviceStates

Anfrageparameter: PayloadObject：

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

Beispiel einer Anfrage:

{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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 Leistungsverbrauchsstatistiken, erforderlich.
            "end": "2020-07-05T09:00:00Z"   // Endzeit für Leistungsverbrauchsstatistiken, erforderlich.
          }
        }
      }
    }
  }
}

Antwortparameter: PayloadObject：

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

Beispielantwort:

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // In mehrere Datensätze unterteilt basierend auf configuration.resolution
            {
              "usage": 26.5, // Leistungsverbrauchswert, erforderlich. Typ: number.
              "start": "2020-07-05T08:00:00Z", // Startzeit, erforderlich. Typ: Datum.
              "end": "2020-07-05T09:00:00Z"    // Endzeit, erforderlich. Typ: Datum. Wenn das Intervall zwischen end und start kleiner als resolution ist, gelten alle gemeldeten Datensätze als ungültig.
            },
            {
              "usage": 26.5, // Leistungsverbrauchswert, erforderlich. Typ: number.
              "start": "2020-07-05T09:00:00Z", // Startzeit, erforderlich. Typ: Datum.
              "end": "2020-07-05T10:00:00Z"    // Endzeit, erforderlich. Typ: Datum. 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 finden Sie im Abschnitt unterstützte Gerätefähigkeiten. Beachten Sie, dass das Feld permission nicht geändert werden kann; beim Synchronisieren denselben Wert übergeben.

Beispiel einer Anfrage:

{
  "directive": {
    "header": {
      "name": "ConfigureDeviceCapabilities",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "thermostat-mode-detect",
          "permission": "0110",
          "name": "temperature", // Art der Temperaturkontrolldetektion, erforderlich. Optionale Werte: humidity (Feuchtigkeitsmessung), temperature (Temperaturmessung)
          "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 voreingestellte Bedingungen 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 voreingestellte Bedingungen 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 UUID Version 4",
      "version": "2"
    },
    "payload": {}
  }
}

5. Server-sent Events

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

5.1 Anleitung

Das Gateway unterstützt das Pushen von Nachrichten an den Client mittels SSE (Server-sent events). Der Client kann SSE-Nachrichten überwachen, nachdem er die Zugangsdaten erhalten hat, und den Inhalt der Push-Nachrichten entsprechend dem Entwicklungsinterface-Ereignisbenachrichtigungsprotokoll parsen, nachdem Nachrichten vom Gateway empfangen wurden. Es ist zu beachten, dass das Gateway derzeit das HTTP1.1-Protokoll verwendet, sodass im Browser maximal nicht mehr als 6 Verbindungen für SSE erlaubt sind (spezifische Hinweise finden Sie in der MDN EventSource-Schnittstellenbeschreibung).

5.2 Gemeinsames 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 gibt einen Authentifizierungsfehler zurück, 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. Ereignis Gerät hinzufügen

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

Name	Typ	Optional	Beschreibung
payload	ResponseDeviceObjectObject - Schnittstelle identisch mit der 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	Objekt。 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 Geräte, die über offene Schnittstellen verbunden sind, 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äteinfo aktualisieren

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

Name	Typ	Optional	Beschreibung
endpoint	EndpointObject	N	Geräteinformationen
payload	DeviceChangeObject	N	Geräteänderungsdaten

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 Geräte, die über offene Schnittstellen verbunden sind, 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": "Gerätename",
    "capabilities": [
      {
        "capability": "thermostat-mode-detect",
        "permission": "0110",
        "name": "temperature", // Art der Temperaturkontrolldetektion, erforderlich. Optionale Werte: humidity (Feuchtigkeitsmessung), temperature (Temperaturmessung)
        "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 voreingestellte Bedingungen 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 voreingestellte Bedingungen 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 Geräte, die über offene Schnittstellen verbunden sind, ist dieses Feld erforderlich.

Beispiel:

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

e. Ereignis Geräte-Online aktualisieren

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

Name	Typ	Optional	Beschreibung
endpoint	EndpointObject	N	Geräteinformationen
payload	DeviceChangeObject	N	Geräteänderungsdaten

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 Geräte, die über offene Schnittstellen verbunden sind, 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. Ereignis Sicherheitsstatus-Aktualisierung

:::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. Ereignis Armzustand-Aktualisierung

:::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 | Entwaffnet | | 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 Anbieter des TTS-Dienst-Engines 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 weist innerhalb des Gateways eine TTS-Engine-Service-ID zu.

6.1.2 Abrufen der Liste der synthetisierten Audiodateien

1. 【Gateway Open API Client】Ruft die Schnittstelle auf, um die Liste der registrierten TTS-Engine-Dienste zu erhalten. Sie können die aktuell 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 Audiodateien einer angegebenen TTS-Engine zu erhalten. Das Gateway sendet eine synchrone Audio-Listen-Anweisung an den angegebenen TTS-Dienstanbieter und gibt das Ergebnis zurück.

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 aktuell 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 Audiodateien einer angegebenen TTS-Engine zu erhalten. Das Gateway sendet eine synchrone Audio-Listen-Anweisung an den angegebenen TTS-Dienstanbieter und gibt das Ergebnis zurück.

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 aktuell 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 Audiodateien einer angegebenen TTS-Engine zu erhalten. Das Gateway sendet eine synchrone Audio-Listen-Anweisung an den angegebenen TTS-Dienstanbieter und gibt das Ergebnis zurück. (einschließlich der TTS-Audiodatei-Adresse)

3. 【Gateway Open API Client】Speichert die TTS-Audiodatei-Adresse aus dem in den vorherigen Schritten zurückgegebenen Ergebnis, ruft die Schnittstelle zum Abspielen der Audiodatei auf und spielt diese über das Gateway ab.

6.2 TTS-Engine-Modul

6.2.1 Gateway-öffentliche Funktionen

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 ::: Anfrageparameter: 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 TTS-Engine-Dienstes

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. **Statuscode: **200 OK Antwortbeispiel:： :::

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

b. Liste der Audiodateien einer angegebenen TTS-Engine abrufen

:::tips

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

• Methode：GET

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: 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	Bezeichnung der Audiodatei

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. **Statuscode: **200 OK **Fehlercode: **

• 190000 Die Engine läuft nicht normal

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 durchführen

:::tips

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

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
text	string	N	Text, der zur Synthese des Audios verwendet wird
label	string	Y	Bezeichnung der Audiodatei
language	string	Y	Transparentes Feld. Optionaler Sprachcode für die Syntheseanforderung. Die genaue 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. Das bedeutet, dass bei Nichtübermittlung der Sprache 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	Bezeichnung der Audiodatei

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. **Statuscode: **200 OK **Fehlercode: **

• 190000 Die Engine läuft nicht normal

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

Anforderung an das Gateway senden durch den TTS-Dienstanbieter

:::tips

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

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
event	EventObject	N	Strukturinformation des Request-Event-Objekts

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	Anfragename. Optionaler Parameter.

• RegisterTTSEngine | | message_id | string | N | Anfrage-Nachrichten-ID, UUID_V4 | | version | string | N | Versionsnummer des Anfrageprotokolls. Derzeit fest auf 1 gesetzt |

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 UUID Version 4",
      "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	Name des Antwort-Headers. Optionaler Parameter:

• Antwort (Erfolgreiche Antwort)

• ErrorResponse (Fehlerantwort) | | message_id | string | N | Antwort-Header Nachrichten-ID, UUID_V4. Eingehende Anfrage-Nachricht hier: header.message_id | | version | string | N | Versionsnummer des Anfrageprotokolls. Derzeit fest auf 1 gesetzt |

PayloadObject

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

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. **Statuscode: **200 OK Antwortbeispiel:： ::: Korrektes Antwortbeispiel：

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

**Abnormale Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertyp

• INVALID_PARAMETERS (Parameterfehler)

• AUTH_FAILURE (Authentifizierungsfehler)

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

Fehlerantwort-Beispiel：

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

b. Synchronisieren des Audiolisten-Befehls

Befehl an den TTS-Dienstanbieter senden durch das Gateway.

:::tips

• URL：<service address>

• Methode：POST

• Header：

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

Attribut	Typ	Optional	Beschreibung
directive	DirectiveObject	N	Strukturinformation des Instruktionsobjekts

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	Anfragename. Optionaler Parameter:

• SyncTTSAudioList | | message_id | string | N | Anfrage-Nachrichten-ID, UUID_V4 | | version | string | N | Versionsnummer des Anfrageprotokolls. Derzeit fest auf 1 gesetzt |

Anfragebeispiel:

{
  "directive": {
    "header": {
      "name": "SyncTTSAudioList",
      "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4",
      "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	Name des Antwort-Headers. Optionaler Parameter:

• Antwort (Erfolgreiche Antwort)

• ErrorResponse (Fehlerantwort) | | message_id | string | N | Antwort-Header Nachrichten-ID, UUID_V4. Eingehende Anfrage-Nachricht hier: header.message_id | | version | string | N | Versionsnummer des Anfrageprotokolls. Derzeit fest auf 1 gesetzt |

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	Bezeichnung der Audiodatei

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. **Statuscode: **200 OK Antwortbeispiel:： ::: Korrektes Antwortbeispiel：

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

**Abnormale Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertyp

• INVALID_PARAMETERS (Parameterfehler)

• AUTH_FAILURE (Authentifizierungsfehler)

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

Fehlerantwort-Beispiel：

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

c. Sprachsynthese-Befehl

Befehl an den TTS-Dienstanbieter senden durch das Gateway.

:::tips

• URL：<service address>

• Methode：POST

• Header：

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

Attribut	Typ	Optional	Beschreibung
directive	DirectiveObject	N	Strukturinformation des Instruktionsobjekts

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	Anfragename. Optionaler Parameter:

• SynthesizeSpeech | | message_id | string | N | Anfrage-Nachrichten-ID: UUID_V4 | | version | string | N | Versionsnummer des Anfrageprotokolls. Derzeit fest auf 1 gesetzt |

PayloadObject

Attribut	Typ	Optional	Beschreibung
text	string	N	Text, der zur Synthese des Audios verwendet wird
label	string	Y	Bezeichnung der Audiodatei
language	string	Y	Transparentes Feld. Optionaler Sprachcode für die Syntheseanforderung. Die genaue 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. Das bedeutet, dass bei Nichtübermittlung der Sprache 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 UUID Version 4",
            "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	Name des Antwort-Headers. Optionaler Parameter:

• Antwort (Erfolgreiche Antwort)

• ErrorResponse (Fehlerantwort) | | message_id | string | N | Antwort-Header Nachrichten-ID, UUID_V4. Eingehende Anfrage-Nachricht hier: header.message_id | | version | string | N | Versionsnummer des Anfrageprotokolls. Derzeit fest auf 1 gesetzt |

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	Bezeichnung der Audiodatei

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. **Statuscode: **200 OK Antwortbeispiel:： ::: Korrektes Antwortbeispiel：

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

**Abnormale Antwortparameter: **

Attribut	Typ	Optional	Beschreibung
type	string	N	Fehlertyp

• INVALID_PARAMETERS (Parameterfehler)

• AUTH_FAILURE (Authentifizierungsfehler)

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

Fehlerantwort-Beispiel：

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

7. Multimedia-Modul

7.1 Audiodatei abspielen

:::tips

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

• Methode：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter:

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

Korrekte Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. **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 anzuzeigenden Inhalts angeben. Die UI-Karte passt automatisch ihre Breite und Höhe an, und der Inhalt wird mithilfe eines 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 Kartenresource-URL) und weist eine interne UI-Karten-ID innerhalb des Gateways zu.

8.1.2 Abrufen der UI-Karten-Liste

• [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.

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 Resource-URL.

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

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 im Zusammenhang mit der angegebenen UI-Karte.

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 ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
label	string	Y	Kartenbezeichnung: Wird verwendet, um die Karte zu beschreiben. Sie ist das Alias der Karte.
cast_settings	CastSettingsObject	Y	Einstellungen für Cast-Karten: Konfigurationsoptionen für Cast-Karten.
web_settings	WebSettingsObject	N	Einstellungen für Web-Karten: Konfigurationsoptionen 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 ID der UI-Karte

:::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentitätsprüfung wurde bestanden. **Statuscode: ** 200 OK ::: 请求示例：

{
  "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-Karten-Liste

:::tips

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

• Methode：GET

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Anfrageparameter: Keine Antwortparameter:

Attribut	Typ	Optional	Beschreibung
data	CardObject[]	N	Liste der UI-Karten

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. Sie ist das Alias der Karte.
web_settings	WebSettingsObject	N	Einstellungen für Cast-Karten: Konfigurationsoptionen für Cast-Karten.
app_name	string	Y	Einstellungen für Web-Karten: Konfigurationsoptionen 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 Spezifikation 2x2. Die 2x2-Spezifikation wird nicht wirksam. |

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 vorhandenen 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 ::: Anfrageparameter:

Attribut	Typ	Optional	Beschreibung
label	string	Y	Wird verwendet, um die Karte zu beschreiben. Sie ist das Alias der Karte.
cast_settings	CastSettingsObject	Y	Einstellungen für Cast-Karten
web_settings	WebSettingsObject	Y	Einstellungen für Web-Karten

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 Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. Die zu ändernde UI-Karte muss vom Anbieter der benutzerdefinierten UI-Karte erstellt worden sein, der die Schnittstelle aufruft. **Statuscode: ** 200 OK Fehlercode:

• 406: Keine Berechtigung für den 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 vorhandene 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 ::: Anfrageparameter: Keine Erfolgreiche Datenantwort: :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. Die zu ändernde UI-Karte muss vom Anbieter der benutzerdefinierten UI-Karte erstellt worden sein, der die Schnittstelle aufruft. **Statuscode: ** 200 OK Fehlercode:

• 406: Keine Berechtigung für den Zugriff auf diese Ressource. ::: **Antwortbeispiel: **

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