# 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 klicken**Fertig**>. Beachten Sie, dass nach dem Drücken der Schnittstellenzugriff nicht länger als 5 Minuten gültig ist. ```json // Anfrage curl --location --request GET 'http:///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. ```json // Anfrage curl --location --request GET 'http:///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. ```json // Anfrage curl --location --request GET 'http:///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 ```javascript 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. | ```javascript // 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](https://en.wikipedia.org/wiki/Double-precision_floating-point_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**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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 ::: ```json { "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**: ```json { "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://:@:/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:`://:/:@` | | | | | Beispiel:`rtsp://admin:123456@192.168.10.115: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 `` und `` 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" } ``` ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // Gerät einschalten await axios({ url: `http:///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**: ```json { "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." | ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // Gerät einschalten await axios({ url: `http:///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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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 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 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： 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   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 | 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 `CapabilityObject`siehe 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: ```json { "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: ```json { "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: ```json { "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:** ```json { "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: ```json { "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 ```json { "event": { "header": { "name": "Response", "message_id": "Eindeutiger Bezeichner, vorzugsweise eine UUID Version 4", "version": "2" }, "payload": {} } } ``` ## 5. Server-sent Events > MDN EventSource-Schnittstellenbeschreibung： ### 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: ```javascript const evtSource = new EventSource("http:///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: ```json // 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: ```json // 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 | **Tags**`object` \| 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: ```json // 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: ```json // 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: ```json // 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: ```json // 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 ```json // 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:**： ::: ```json { "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: | | | | | | | 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:**： ::: ```json { "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: | | | | | | | 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:**： ::: ```json { "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: ```json { "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： ```json { "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： ```json { "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**：`` * **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: ```json { "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: | | | | | | | label | string | Y | Bezeichnung der Audiodatei | :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. \*\*Statuscode: \*\*`200 OK` **Antwortbeispiel:**： ::: Korrektes Antwortbeispiel： ```json { "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： ```json { "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**：`` * **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: ```json { "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: | | | | | | | label | string | Y | Bezeichnung der Audiodatei | :::tips Bedingungen: Die Anfrageparameter sind legal und die Benutzeridentität wurde verifiziert. \*\*Statuscode: \*\*`200 OK` **Antwortbeispiel:**： ::: Korrektes Antwortbeispiel： ```json { "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： ```json { "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:**： ::: ```json { "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: | | 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: | 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` ::: 请求示例： ```json { "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: ```json { "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: | | 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: | Antwortbeispiel: ```json { "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: | 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: | 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: \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` \*\*Anfragebeispiel: \*\* ```json { "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: \*\* ```json { "error": 0, "data": {}, "message": "success" } ```