> For the complete documentation index, see [llms.txt](https://cube.ewelink.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cube.ewelink.cc/cube-os-fr/ressources/guide-du-developpeur-et-de-lapi.md). # Guide du développeur et de l’API ## 1. Commencer à utiliser ### 1.1 Préparation Étape 1. Veuillez vous assurer que la passerelle est alimentée et fonctionne correctement. Étape 2. Assurez-vous que la passerelle et le PC sont connectés au même réseau local. Ensuite, saisissez l'URL de CUBE dans votre navigateur. Remarque : Si vous avez plusieurs passerelles, vous pouvez obtenir l'adresse IP correspondante pour accéder à la passerelle spécifiée de deux manières ci-dessous. 1. Connectez-vous à votre routeur sans fil et vérifiez l'adresse IP de la passerelle dans le DHCP. 2. CUBE prend en charge la découverte locale via mDNS. ### 1.2 Démarrage * Appelez l'interface \[Access Token], et obtenez une réponse d'erreur, invitant à cliquer <**Terminé**>. Notez qu'après l'appui, l'accès à l'interface est valable pendant au plus 5 minutes. ```json // Requête curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Réponse { "error": 401, "data": {}, "message": "link button not pressed" } ``` * Cliquez sur <**Terminé**> et appelez à nouveau l'interface \[Access Token]. La réponse est réussie et le token est obtenu. ```json // Requête curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Réponse { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` * Vérifiez le token. Appelez l'interface \[Get Device List]. La réponse est réussie et la liste des appareils est obtenue. ```json // Requête curl --location --request GET 'http:///open-api/V2/rest/devices' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d' // Réponse { "error": 0, "data": { "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "nom de l'appareil", "manufacturer": "nom du fabricant", "model": "nom du modèle", "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" } ``` * Méthode d'obtention du token d'accès CUBE : après l'appel de l'interface \[Access Token], une fenêtre contextuelle globale de la console Web CUBE invite l'utilisateur à confirmer l'acquisition des identifiants d'appel de l'interface. * Remarque : Si vous ouvrez plus d'une page de console Web CUBE, la fenêtre de confirmation apparaîtra sur plusieurs pages de console web en même temps, et la fenêtre contextuelle des autres pages sera fermée après avoir cliqué sur la confirmation sur l'une des pages de la console web. ## 2. Concept central ### 2.1 Adresse de l'interface de développement L'API Web de la passerelle a deux méthodes d'accès (basées sur l'IP ou le nom de domaine), généralement le chemin racine est /open-api/V2/rest/\ // Accès IP http\:///open-api/V2/rest/bridge // Accès par nom de domaine http\:///open-api/V2/rest/bridge ### 2.2 Catégorie d'affichage de l'appareil & Capacités * \*\*Catégorie d'affichage de l'appareil (DisplayCategory). \*\*La catégorie d'affichage de l'appareil sert à identifier des catégories spécifiques (d'appareil), telles que switch, plug, light, etc. **Cette information déterminera l'effet d'affichage de l'interface utilisateur de l'appareil dans la passerelle**. * \*\*Capacité de l'appareil. \*\*La capacité de l'appareil sert à décrire les sous-fonctions spécifiques de l'appareil. Par exemple le contrôle d'alimentation, le contrôle de luminosité, le contrôle de la température de couleur, etc. **Un seul appareil peut prendre en charge 1 ou plusieurs capacités**. * **capability :** Décrit le nom de la capacité, qui doit être mondialement unique et de type chaîne. Plusieurs mots anglais doivent être séparés par des tirets ("-"). Par exemple : `"thermostat-target-setpoint"`. * **name :** Décrit la catégorie sous la capacité, également de type chaîne. Plusieurs mots anglais doivent être séparés par des tirets ("-"). Par exemple : `"auto-mode"`, `"manual-mode"`. * **permission :** Décrit les permissions associées à la capacité. Le type est chaîne, formaté en code binaire 8421. Exemples incluent : * Appareil contrôlable : `"1000"` * Appareil configurable : `"0010"` * Appareil contrôlable et configurable : `"1010"` * Appareil contrôlable et reportable : `"1100"` La signification de chaque bit, de droite à gauche, est la suivante : ⅰ. Bit 0 : Permet d'interroger l'appareil ⅱ. Bit 1 : Permet de configurer l'appareil ⅲ. Bit 2 : Permet à l'appareil de rapporter des données ⅳ. Bit 3 : Permet de contrôler l'appareil ```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 :** Décrit les éléments de configuration pour la capacité, qui sont de type objet et incluent une description de chaque élément de configuration. ⅰ. **key :** Décrit le nom de l'élément de configuration, qui est de type chaîne. Plusieurs mots anglais doivent être exprimés en camelCase. Par exemple : `"temperatureUnit"`. ⅱ. **value :** Décrit le contenu de l'élément de configuration. Les spécifications détaillées se trouvent dans le tableau ci-dessous. | Attribut | Type | Optionnel | Description | | -------------------------- | ------ | --------- | ------------------------------------------------------- | | permission | string | N | Décrit les permissions pour l'élément de configuration. | | **Valeurs optionnelles :** | | | | * Permet la modification de cet élément de configuration : `"10"` * Permet la consultation de cet élément de configuration : `"01"` * Permet à la fois la modification et la consultation de cet élément de configuration : `"11"` **Explication des bits :** 1. **Bit 0 :** Permet la consultation de cet élément de configuration 2. **Bit 1 :** Permet la modification de cet élément de configuration | | type | string | N | Décrit le type de données de la valeur de l'élément de configuration. **Valeurs optionnelles :** * `"enum"` * `"numeric"` * `"object"` * `"boolean"` * `"string"` **Directives spécifiques au type :** 1. **Lorsque `**type = enum**`:** * Le `champ valeur` (décrivant la valeur de l'élément de configuration) est requis si `permission` permet la modification (`"10"` ou `"11"`). * Le `défaut` (décrivant la valeur par défaut de l'élément de configuration) et `valeurs` (décrivant les valeurs sélectionnables pour l'élément de configuration) les champs sont optionnels. 2. **Lorsque `**type = numeric**`:** * Le `champ valeur` le champ est requis si `permission` permet la modification (`"10"` ou `"11"`). * Les champs suivants sont optionnels : * `min` (décrivant la valeur minimale de l'élément de configuration) * `max` (décrivant la valeur maximale de l'élément de configuration) * `step` (décrivant la valeur d'incrément pour l'élément de configuration) * `precision` (décrivant la précision) * `unit` (décrivant l'unité de l'élément de configuration) * `défaut` (décrivant la valeur par défaut) 3. **Lorsque `**type = object**`:** * Le `champ valeur` le champ est requis si `permission` permet la modification (`"10"` ou `"11"`). * Le `défaut` le champ est optionnel. 4. **Lorsque `**type = boolean**`:** * Le `champ valeur` le champ est requis si `permission` permet la modification (`"10"` ou `"11"`). * Le `défaut` le champ est optionnel. 5. **Lorsque `**type = string**`:** * Le `champ valeur` le champ est requis si `permission` permet la modification (`"10"` ou `"11"`). * Le `défaut` le champ est optionnel. | ```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. API Web ### Type de données | Type | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | string | Type de données chaîne. Encodé en UTF8. | | nombre | Type de données nombre. [format binaire IEEE 754 double précision 64 bits](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | | int | Type de données entier. | | objet | Type de données objet. Objet conforme à JSON | | string\[] | Tableau de chaînes | | int\[] | Tableau d'entiers | | object\[] | Tableau d'objets | | bool | Booléen | | date | Chaîne temporelle. Chaîne au format ISO (format étendu ISO 8601) : YYYY-MM-DDTHH:mm:ss.sssZ. Le fuseau horaire est toujours UTC (Temps universel coordonné), identifié par un suffixe "Z". | ### Résultats génériques de la réponse | Attribut | Type | Optionnel | Description | | ----------------------------------------------------------------------------------------------------------- | ------ | --------- | ------------------------------- | | error | int | N | Code d'erreur : | | 0 : Succès | | | | | 400 : Erreur de paramètre | | | | | 401 : Échec de l'authentification | | | | | 500 : Exception serveur | | | | | data | objet | N | Corps des données de la réponse | | message | string | N | Description de la réponse : | | Lorsque error est égal à 0, le contenu est success | | | | | Lorsque error n'est pas égal à 0, c'est une chaîne non vide, et le contenu est une description de l'erreur. | | | | **Exemple de réponse**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` ```json { "error": 400, "data": {}, "message": "invalid parameters" } ``` ### Liste des ressources | Type | Description | | ------------------- | ------------------------- | | Sons pris en charge | - alert1 (Son d'alarme 1) | * alert2 (Son d'alarme 2) * alert3 (Son d'alarme 3) * alert4 (Son d'alarme 4) * alert5 (Son d'alarme 5) * doorbell1 (Son de sonnette 1) * doorbell2 (Son de sonnette 2) * doorbell3 (Son de sonnette 3) * doorbell4 (Son de sonnette 4) * doorbell5 (Son de sonnette 5) * alarm1 (Son d'alarme 1) * alarm2 (Son d'alarme 2) * alarm3 (Son d'alarme 3) * alarm4 (Son d'alarme 4) * alarm5 (Son d'alarme 5) | | Deep pris en charge | - bootComplete (Démarrage du système terminé) * networkConnected (Réseau connecté) * networkDisconnected (Réseau déconnecté) * systemShutdown (Extinction du système) -deviceDiscovered (Découvrir l'appareil) * system Armed (Système armé activé) * system Disarmed (Système armé désactivé) * factoryReset (Réinitialiser l'appareil) | ### 3.1 La fonction de la passerelle #### a. Jeton d'accès Permet aux utilisateurs d'obtenir un jeton d'accès. * Remarque : Le token sera effacé après la réinitialisation de l'appareil. * Remarque : Après l'obtention du token, vous devez appuyer à nouveau sur le bouton pour obtenir avec succès un nouveau token. :::astuces * **URL**：`/open-api/V2/rest/bridge/access_token` * **Méthode**：`GET` * **En-tête**： * Content-Type: application/json ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ------------------------------------ | | app\_name | string | Y | Description du nom de l'application. | Réponse de données réussie : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------------------------------------------------------------------------- | | token | string | N | Le jeton d'accès de l'interface. Il est valable longtemps, veuillez le sauvegarder | | app\_name | string | Y | Description du nom de l'application. | :::astuces **Condition**: L'utilisateur déclenche la < touche de commande > et accède à cette interface dans la durée de validité. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` Réponse de données en cas d'échec：Objet vide :::astuces **Conditions**：L'utilisateur n'a pas déclenché la < touche de commande >, ou la durée de validité a expiré. \*\*Code d'état : \*\* `200 OK` ::: **Exemple de réponse**: ```json { "error": 401, "data": {}, "message": "link button not pressed" } ``` #### b. Obtenir l'état de la passerelle Permet aux utilisateurs autorisés d'obtenir l'état de la passerelle via cette interface :::astuces * **URL**：`/open-api/V2/rest/bridge/runtime` * **Méthode**：`GET` * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : aucun Réponse de données réussie : | **Attribut** | **Type** | **Optionnel** | **Description** | | ---------------------------------------------------------------------------------------- | -------- | ------------- | -------------------------------------------- | | ram\_used | int | N | Pourcentage d'utilisation de la RAM.\[0-100] | | cpu\_used | int | N | Pourcentage d'utilisation du CPU. \[0-100] | | power\_up\_time | date | N | Dernière heure de mise sous tension | | cpu\_temp | int | N | Température du CPU : | | Unité : Celsius | | | | | cpu\_temp\_unit | string | N | Unité de température du CPU : | | Optionnel | | | | | valeurs :`'c'`, `'f'` | | | | | sd\_card\_used | int | Y | Utilisation de la carte SD (pourcentage) : | | Plage :`[0-100]` avec une décimale de précision | | | | | \*Remarque : Si la carte SD n'est pas insérée ou n'est pas formatée, la valeur est vide. | | | | :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```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. Configurer la passerelle Permet aux utilisateurs autorisés de configurer la passerelle via cette interface :::astuces * **URL**：`/open-api/V2/rest/bridge/config` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ------------------------ | | volume | int | Y | Volume système. \[0-100] | Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Obtenir les informations de la passerelle Permet aux utilisateurs autorisés d'obtenir les informations de la passerelle via cette interface :::astuces * **URL**：`/open-api/V2/rest/bridge` * **Méthode**：`GET` * **En-tête**： * Content-Type: application/json ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ----------------------------------- | | ip | string | N | adresse ip | | mac | string | N | adresse mac | | domain | string | Y | Domaine de service de la passerelle | | fw\_version | string | N | Version du firmware | | name | string | N | Nom de l'appareil | Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Aucun \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```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. Mise en sourdine de la passerelle Permet aux utilisateurs autorisés de mettre la passerelle en sourdine via cette interface. :::astuces * **URL**：`/open-api/v2/rest/bridge/mute` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : aucun Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### f. Désactiver le mode silencieux de la passerelle Permet aux utilisateurs autorisés de désactiver le mode silencieux de la passerelle via cette interface.\ :::astuces * **URL**：`/open-api/v2/rest/bridge/unmute` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : aucun Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### g. Annuler l'alarme de la passerelle Permet aux utilisateurs autorisés de désactiver l'état du son d'alarme sur la passerelle via cette interface. :::astuces * **URL**：`/open-api/v2/rest/bridge/cancel_alarm` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : aucun Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.2 Fonction matérielle #### a. Redémarrer la passerelle Permet à l'utilisateur autorisé de redémarrer la passerelle via cette interface :::astuces * **URL**：`/open-api/V2/rest/hardware/reboot` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : aucun Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: ```json { "error": 0, "data": {}, "message": "success" } ``` #### b. Contrôle du haut-parleur Permet aux utilisateurs autorisés de contrôler le haut-parleur via cette interface :::astuces * **URL**：`/open-api/V2/rest/hardware/speaker` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------- | ------------------------------ | -------------------------------------------------------------------------------- | | type | string | N | Paramètres optionnels : 1.play\_sound (jouer le son) 2.play\_beep (jouer le bip) | | sound | SoundObject | Y (N si type est play\_sound.) | Le son. | | beep | BeepObject | Y (N si type est play\_beep.) | Le bip | SoundObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Le nom du son. Les valeurs prises en charge peuvent être consultées dans \[Resource List - Supported sound] | | volume | int | N | Le volume du son. \[0-100] | | countdown | int | N | La durée pendant laquelle le haut-parleur joue le son, et il s'arrêtera automatiquement à la fin du temps imparti. Unité : seconde. \[0,1799] | BeepObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Le nom de l'événement (deep). Les valeurs prises en charge peuvent être consultées dans \[Resource List - Supported deep] | | volume | int | N | Le volume de l'événement (deep). \[0-100] | Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\* `200 OK` ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.3 Fonction de gestion des appareils #### a. Type d'appareil pris en charge | **Type d'appareil** | **Valeur** | Version iHost | | ------------------------------------ | ---------------------------- | ------------- | | Prise (Plug) | plug | ≥ 2.1.0 | | Interrupteur | switch | ≥ 2.1.0 | | Lumière | light | ≥ 2.1.0 | | Rideau | curtain | ≥ 2.1.0 | | Capteur porte/fenêtre | contactSensor | ≥ 2.1.0 | | Capteur de mouvement | motionSensor | ≥ 2.1.0 | | Capteur de température | temperatureSensor | ≥ 2.1.0 | | Capteur d'humidité | humiditySensor | ≥ 2.1.0 | | Capteur de température et d'humidité | temperatureAndHumiditySensor | ≥ 2.1.0 | | Détecteur de fuite d'eau | waterLeakDetector | ≥ 2.1.0 | | Détecteur de fumée | smokeDetector | ≥ 2.1.0 | | Bouton sans fil | button | ≥ 2.1.0 | | Caméra | camera | ≥ 2.1.0 | | Capteur général | sensor | ≥ 2.1.0 | | Capteur général | sensor | ≥ 2.1.0 | | Plafonnier ventilateur (Fanlight) | fanLight | ≥ 2.1.0 | | Climatiseur | airConditioner | ≥ 2.1.0 | | Ventilateur | fan | ≥ 2.1.0 | | Thermostat | thermostat | ≥ 2.1.0 | #### b. Capacités de l'appareil prises en charge **Interrupteur d'alimentation (power) :** **Exemple de déclaration de capacité :** ``` [ { "capability": "power", // Nom de la capacité "permission": "1100", // ihost ne prend pas en charge la configuration du démarrage/arrêt progressif, donc pas de champ configure } ] ``` **Attribut d'état :** ``` { "powerState": "on", // Le champ powerState indique l'état d'alimentation on/off. Requis. **Type :** chaîne. "on" indique alimentation activée, "off" indique alimentation désactivée, "toggle" indique basculement. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** **Allumer :** ``` { "power": { "powerState": "on" } } ``` **Éteindre :** ``` { "power": { "powerState": "off" } } ``` **Commutation de canal (toggle) :** **Exemple de déclaration de capacité :** Exemple de composant unique : ``` [ { "capability": "toggle", // Nom de la capacité "permission": "1100", // Permission "name": "1", // Nom du composant, **Type :** Chaîne. Valeurs optionnelles : "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4), ou d'autres valeurs contenant des lettres majuscules/minuscules et des chiffres } ] ``` Exemple de composants multiples : ``` [ { "capability": "toggle", "permission": "1100", "name": "1" }, { "capability": "toggle", "permission": "1100", "name": "2" } ] ``` **Attribut d'état :** ``` { "toggleState": "on", // Le champ toggleState indique l'état de basculement de l'attribut {name} de {device_id}. Requis. **Type :** Chaîne. "on" indique activé, "off" indique désactivé, "toggle" indique basculement. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Format de basculement : ``` { [capability]: { [toggle-name]: { [toggleState]: [value] } } } Composant 1 Activé, Composant 2 Désactivé : { "toggle": { "1": { "toggleState": "on" }, "2": { "toggleState": "off" } } } ``` **Inching de canal (toggle-inching) :** **Exemple de déclaration de capacité :** ``` [ { "capability": "toggle-inching", // Nom de la capacité "permission": "0010", // Permission "settings": { "toggleInchingSetting": { "permission": "11", "type": "object", "value": { "supported": { "1": { // Nom du composant "enable": true, // Si la fonction inching est activée. **Type :** Booléen. Requis. "inchingSwitch": "off", // Réglage de l'interrupteur d'inching. **Type :** Chaîne. Requis. "off" (alimentation off), "on" (alimentation on) "delay": 1000, // Temps de délai pour l'inching en millisecondes. **Type :** Entier. Requis. "min_delay": 500, // Temps de délai minimum "max_delay": 100000 // Temps de délai maximum }, "2": { // Nom du composant "enable": true, // Si la fonction inching est activée. **Type :** Booléen. Requis. "inchingSwitch": "off", // Réglage de l'interrupteur d'inching. **Type :** Chaîne. Requis. "off" (alimentation off), "on" (alimentation on) "delay": 1000, // Temps de délai pour l'inching en millisecondes. **Type :** Entier. Requis. "min_delay": 500, // Temps de délai minimum "max_delay": 100000 // Temps de délai maximum }, "3": { // Nom du composant "enable": true, // Si la fonction inching est activée. **Type :** Booléen. Requis. "inchingSwitch": "off", // Réglage de l'interrupteur d'inching. **Type :** Chaîne. Requis. "off" (alimentation off), "on" (alimentation on) "delay": 1000, // Temps de délai pour l'inching en millisecondes. **Type :** Entier. Requis. "min_delay": 500, // Temps de délai minimum "max_delay": 100000 // Temps de délai maximum }, "4": { // Nom du composant "enable": true, // Si la fonction inching est activée. **Type :** Booléen. Requis. "inchingSwitch": "off", // Réglage de l'interrupteur d'inching. **Type :** Chaîne. Requis. "off" (alimentation off), "on" (alimentation on) "delay": 1000, // Temps de délai pour l'inching en millisecondes. **Type :** Entier. Requis. "min_delay": 500, // Temps de délai minimum "max_delay": 100000 // Temps de délai maximum } } } } } } ] ``` **Attribut d'état** Aucun **Protocole (Interroger l'état et instructions de contrôle)** Aucun **Réglage de la luminosité (brightness) :** **Exemple de déclaration de capacité :** ``` { "capability": "brightness", // Nom de la capacité "permission": "1100" // Permission } ``` **Attribut d'état :** ``` { "brightness": 100, // Le champ brightness indique le pourcentage de luminosité. Choisir entre brightness ou brightnessDelta. **Type :** Nombre. Plage : 0-100. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Régler la luminosité à 80 %. (0 est le plus sombre et 100 le plus lumineux.) ``` json copier le code { "brightness": { "brightness": 80 } } ``` **Réglage de la température de couleur (color-temperature) :** **Exemple de déclaration de capacité :** ``` { "capability": "color-temperature", // Nom de la capacité "permission": "1100" // Permission } ``` **Attribut d'état :** ``` { "colorTemperature": 100, // Le champ colorTemperature indique le pourcentage de température de couleur. Choisir entre colorTemperature ou colorTemperatureDelta. **Type :** Nombre. Plage : 0-100. 0 indique une lumière chaude, 50 une lumière neutre, 100 une lumière froide. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Ajuster la température de couleur à 50 % : ``` json { "color-temperature": { "colorTemperature": 50 } } ``` **Réglage de la couleur (color-rgb) :** **Exemple de déclaration de capacité :** ``` { "capability": "color-rgb", // Nom de la capacité "permission": "1100" // Permission } ``` **Attribut d'état :** ``` { "red": 255, // Le champ red représente la composante rouge dans l'espace colorimétrique RGB. Requis. **Type :** Nombre. Plage : 0-255. "green": 0, // Le champ green représente la composante verte dans l'espace colorimétrique RGB. Requis. **Type :** Nombre. Plage : 0-255. "blue": 255 // Le champ blue représente la composante bleue dans l'espace colorimétrique RGB. Requis. **Type :** Nombre. Plage : 0-255. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Régler la couleur sur Violet : ``` { "color-rgb": { "red": 255, "green": 0, "blue": 255 } } ``` **Réglage en pourcentage (percentage) :** **Exemple de déclaration de capacité :** ``` { "capability": "percentage", "permission": "1100", "settings": { // Optionnel "percentageRange": { "permission": "01", "type": "numeric", "min": 0, "max": 100, "step": 5 } } } ``` **Attribut d'état :** ``` { "percentage": 100, // Le champ percentage indique une valeur en pourcentage. Choisir entre percentage ou percentageDelta. **Type :** Nombre. Plage : 0-100. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Ajuster à 40 % : ``` { "percentage": { "percentage": 40 } } ``` **Contrôle du moteur (motor-control) :** **Exemple de déclaration de capacité :** ``` { "capability": "motor-control", "permission": "1100" } ``` **Attribut d'état :** ``` json { "motorControl": "stop", // Le champ motorControl indique l'état du moteur. Requis. **Type :** Chaîne. Valeurs possibles : "open" (ouvrir), "close" (fermer), "stop" (arrêter), "lock" (verrouiller). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Ouvrir le moteur : ``` { "motor-control": { "motorControl": "open" } } ``` **Inversion du moteur (motor-reverse) :** **Exemple de déclaration de capacité :** ``` { "capability": "motor-reverse", "permission": "1100" } ``` **Attribut d'état :** ``` { "motorReverse": true, // Le champ motorReverse indique le réglage de la direction du moteur. Requis. **Type :** Booléen. true indique avant, false indique arrière. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Définir le moteur en avant : ``` { "motor-reverse": { "motorReverse": true } } ``` **Calibration du moteur (motor-clb)** **Exemple de déclaration de capacité :** ``` { "capability": "motor-clb", "permission": "0100" } ``` **Attributs (État) :** ``` { "motorClb": "calibration" // Le champ motorClb indique l'état de calibration du moteur. Requis. **Type :** Chaîne. "normal" indique mode normal (calibré), "calibration" indique calibration en cours. } ``` **Protocole (Rapport d'état) :** Signaler que le moteur est en cours de calibration : ``` { "motor-clb": { "motorClb": "calibration" } } ``` **État d'alimentation au démarrage (startup)** **Exemple de déclaration de capacité :** ``` { "capability": "startup", "permission": "1100" } ``` **Attributs (État) :** ``` { "startup": "on" // État d'alimentation au démarrage. **Type :** Chaîne. Requis. Valeurs optionnelles : "on" (alimentation activée), "stay" (maintenir l'alimentation), "off" (alimentation désactivée), "toggle" (inverser l'état d'alimentation). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Définir l'état d'alimentation sur Toujours activé : ``` { "startup": { "startup": "on" } } ``` *** **Activation de réveil (identify)** **Exemple de déclaration de capacité :** ``` { "capability": "identify", "permission": "0100" } ``` **Attributs (État) :** ``` { "identify": true // Indique si l'appareil signale activement les résultats de reconnaissance ou est activé. } ``` **Protocole (Rapport d'état et instructions de contrôle) :** Définir le temps d'activation de réveil : ``` { "identify": { "countdown": 180 // Le champ countdown indique le temps de compte à rebours. Requis. **Type :** Nombre. Unité : secondes. } } ``` Signaler l'état d'activation : ``` { "identify": { "identify": true // Indique si l'appareil signale activement les résultats de reconnaissance ou est activé. } } ``` **Commutation des statistiques de consommation électrique en temps réel (power-consumption)** **Exemple de déclaration de capacité :** ``` { "capability": "power-consumption", "permission": "1101", "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ``` **Attributs (État) :** Démarrer/Arrêter les statistiques en temps réel : ``` { "rlSummarize": true, // Démarrer/arrêter les statistiques en temps réel. **Type :** Booléen. Requis. "timeRange": { // Période de temps résumée. Requis. "start": "2020-07-05T08:00:00Z", // Heure de début des statistiques de consommation. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin des statistiques de consommation. **Type :** Chaîne. Requis. } } ``` Interroger la consommation d'énergie par plage horaire : ``` { "type": "summarize", // Type de statistiques. **Type :** Chaîne. Requis. Valeurs optionnelles : "rlSummarize" (résumé en temps réel), "summarize" (résumé courant). "timeRange": { // Période de temps résumée. Requis si type = "summarize". "start": "2020-07-05T08:00:00Z", // Heure de début des statistiques de consommation. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin des statistiques de consommation. **Type :** Chaîne. Optionnel. Si omis, indique l'heure actuelle. } } ``` Répondre avec le résultat des statistiques dans la plage horaire : ``` json { "type": "summarize", // Type de statistiques. **Type :** Chaîne. Requis. Valeurs optionnelles : "rlSummarize" (résumé en temps réel), "summarize" (résumé courant). "rlSummarize": 50.0, // Consommation totale d'énergie. **Type :** Nombre. Unité : 0,01 kWh. Optionnel. "electricityIntervals": [ // Plusieurs enregistrements de statistiques divisés selon configuration.resolution. Optionnel. Non présent lorsque type = "rlSummarize". { "usage": 26.5, // Consommation d'énergie. **Type :** Nombre. Unité : 0,01 kWh. Requis. "start": "2020-07-05T08:00:00Z", // Heure de début. **Type :** Date. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin. **Type :** Date. Requis. Si l'intervalle entre end et start est inférieur à resolution, tous les enregistrements signalés sont considérés comme invalides. }, { "usage": 26.5, // Consommation d'énergie. **Type :** Nombre. Unité : 0,01 kWh. Requis. "start": "2020-07-05T09:00:00Z", // Heure de début. **Type :** Date. Requis. "end": "2020-07-05T10:00:00Z" // Heure de fin. **Type :** Date. Requis. Si l'intervalle entre end et start est inférieur à resolution, tous les enregistrements signalés sont considérés comme invalides. } ] } ``` **Protocole (Rapport d'état et instructions de contrôle) :** Démarrer les statistiques en temps réel : ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Arrêter les statistiques en temps réel : ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obtenir la consommation d'énergie historique : ``` json { "power-consumption": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } ``` Obtenir la consommation d'énergie en temps réel : ``` json { "power-consumption": { "powerConsumption": { "type": "rlSummarize" } } } ``` **Détection du mode Température et Humidité (thermostat-mode-detect)** **Exemple de déclaration de capacité :** ``` { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Type de détection du contrôle de température. **Type :** Chaîne. Requis. Valeurs optionnelles : "humidity" (détection d'humidité), "temperature" (détection de température). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Paramètres de détection pris en charge. Requis. { "name": "lowerSetpoint", // La valeur détectée doit être au-dessus de ce point de consigne. Au moins un de lowerSetpoint ou upperSetpoint est requis. "value": { // Plage de détection. Optionnel. Spécifier s'il existe des conditions prédéfinies. "value": 68.0, // Valeur de température. **Type :** Nombre. Requis. "scale": "f" // Unité de température. Requise lorsque name=temperature. Valeurs optionnelles : "c" (Celsius), "f" (Fahrenheit). } }, { "name": "upperSetpoint", // La valeur détectée doit être en dessous de ce point de consigne. Au moins un de lowerSetpoint ou upperSetpoint est requis. "value": { // Plage de détection. Optionnel. Spécifier s'il existe des conditions prédéfinies. "value": 68.0, // Valeur de température. **Type :** Nombre. Requis. "scale": "f" // Unité de température. Requise lorsque name=temperature. Valeurs optionnelles : "c" (Celsius), "f" (Fahrenheit). } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } { "capability": "thermostat-mode-detect", "permission": "0110", "name": "humidity", // Type de détection du contrôle de température. **Type :** Chaîne. Requis. Valeurs optionnelles : "humidity" (détection d'humidité), "temperature" (détection de température). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Paramètres de détection pris en charge. Requis. { "name": "lowerSetpoint", // La valeur détectée doit être au-dessus de ce point de consigne. Au moins un de lowerSetpoint ou upperSetpoint est requis. "value": { // Plage de détection. Optionnel. Spécifier s'il existe des conditions prédéfinies. "value": 68.0, // Valeur d'humidité. **Type :** Nombre. Requis } }, { "name": "upperSetpoint", // La valeur détectée doit être en dessous de ce point de consigne. Au moins un de lowerSetpoint ou upperSetpoint est requis. "value": { // Plage de détection. Optionnel. Spécifier s'il existe des conditions prédéfinies. "value": 68.0, // Valeur d'humidité. **Type :** Nombre. Requis } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ``` **Attributs (État) :** ``` { "mode": "COMFORT" // ID du mode. Optionnel. Valeurs prises en charge : "COMFORT" (Mode Confort), "COLD" (Mode Froid), "HOT" (Mode Chaud), "DRY" (Mode Sec), "WET" (Mode Humide). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Format : ``` { [capability] :{ [mode name] :{ "mode": [value] } } } ``` Exemple : ``` { "thermostat-mode-detect": { "humidity": { "mode": "COMFORT" } } } ``` **Mode du thermostat (thermostat-mode)** **Exemple de déclaration de capacité :** ``` { "capability": "thermostat", "permission": "1100", "name": "thermostat-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", "AUTO", "ECO" ] } } } ``` **Attributs (État) :** ``` { "thermostatMode": "MANUAL" // Mode de fonctionnement du thermostat. **Type :** Chaîne. Valeurs optionnelles : "MANUAL", "AUTO", "ECO". } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "thermostat": { "thermostat-mode": { "thermostatMode": "MANUAL" } } } ``` **État de récupération adaptative du thermostat (thermostat/adaptive-recovery-status)** **Exemple de déclaration de capacité :** ``` { "capability": "thermostat", "permission": "0100", "name": "adaptive-recovery-status" // État de récupération adaptative du thermostat } ``` **Attributs (État) :** ``` { "adaptiveRecoveryStatus": "HEATING" // État de récupération adaptative du thermostat. **Type :** Chaîne. Valeurs optionnelles : "HEATING", "INACTIVE". } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "thermostat": { "adaptive-recovery-status": { "adaptiveRecoveryStatus": "HEATING" } } } ``` **Réglage de la température cible du mode thermostat (thermostat-target-setpoint)** **Exemple de déclaration de capacité :** ``` [[ { "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, // Heure de début en minutes. **Type :** int. Ex. : 7:20 = 440 minutes. "upperSetpoint": 36.5, // Température cible maximale. **Type :** nombre. "lowerSetpoint": 20 // Température cible minimale. **Type :** nombre. }, { "startTimeInMinutes": 900, // Heure de début en minutes. Ex. : 15:00 = 900 minutes. "upperSetpoint": 26.5, // Température cible maximale. **Type :** nombre. "lowerSetpoint": 21 // Température cible minimale. **Type :** nombre. } ], "Tuesday": [... ], "Wednesday": [... ], "Thursday": [... ], "Friday": [... ], "Saturday": [... ], "Sunday": [... ], } } } } ] ``` **Attributs (État) :** ``` { "targetSetpoint": 30 // Température cible pour le mode spécifié. **Type :** nombre, dans l'unité spécifiée par temperatureUnit. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "thermostat-target-setpoint": { "manual-mode": { "targetSetpoint": 30 }, "auto-mode": { "targetSetpoint": 30 } } } ``` **Détection de capteur (detect)** **Exemple de déclaration de capacité :** ``` { "capability": "detect", "permission": "0110", "settings": { // Optionnel "detectInterval": { "permission": "11", "type": "numeric", "value": 300 }, "detectSensitivity": { "permission": "11", "type": "numeric", "value": 1000 } } } ``` **Attributs (État) :** ``` { "detected": true // Résultat de détection. **Type :** Booléen. `true` indique détection, `false` indique absence de détection. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "detect": { "detected": true } } ``` **Détection de température (temperature)** **Exemple de déclaration de capacité :** ``` { "capability": "temperature", "permission": "0110", "settings": { // Optionnel "temperatureCalibration": { // Calibration de température optionnelle "type": "numeric", "permission": "11", "min": -7, // Valeur minimale "max": 7, // Valeur maximale "step": 0.2, // Pas d'ajustement de la température, unité identique à temperatureUnit "value": 5.2 // Valeur actuelle de calibration de la température. **Type :** nombre. }, "temperatureUnit": { // Unité de température optionnelle "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange": { // Plage de détection de température optionnelle "type": "numeric", "permission": "01", "min": -40, "max": 80 } } } ``` **Attributs (État) :** ``` json copier le code { "temperature": 26.5 // Température actuelle. **Type :** Nombre, en Celsius. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "temperature": { "temperature": 20 } } ``` **Détection d'humidité (humidity)** **Exemple de déclaration de capacité :** ``` { "capability": "humidity", "permission": "0100", "settings": { // Plage de détection d'humidité optionnelle. "humidityRange": { "type": "numeric", "permission": "01", "min": 0, "max": 100 } } } ``` **Attributs (État) :** ``` { "humidity": 50 // Humidité relative actuelle (pourcentage). **Type :** Nombre, plage 0-100. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "humidity": { "humidity": 20 } } ``` **Détection de batterie (battery)** **Exemple de déclaration de capacité :** ``` { "capability": "battery", "permission": "0100" } ``` **Attributs (État) :** ``` { "battery": 95 // Pourcentage de batterie restant. **Type :** Nombre, plage -1 à 100. Remarque : -1 indique niveau de batterie inconnu. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "battery": { "battery": 40 } } ``` **Détection d'un bouton simple (press)** **Exemple de déclaration de capacité :** ``` { "capability": "press", "permission": "1100", "settings": { // Optionnel "actions": { // Actions du bouton, optionnel. "type": "enum", "permission": "01", "values": [ // Actions du bouton optionnelles. Valeurs par défaut : "singlePress", "doublePress", "longPress". Les actions configurées remplacent les valeurs par défaut. ] } } } ``` **Attributs (État) :** ``` { "press": "singlePress" // Type d'appui sur le bouton. **Type :** Chaîne. Valeurs standard : "singlePress" (appui simple ou court), "doublePress" (double appui), "longPress" (appui long). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "press": { "press": "singlePress" } } ``` **Détection multi-boutons (multi-press)** **Exemple de déclaration de capacité :** ``` { "capability": "multi-press", "permission": "0100", "name": "1", // Nom de l'attribut multi-press. **Type :** Chaîne. Caractères alphanumériques uniquement autorisés. "settings": { // Optionnel "actions": { // Actions du bouton, optionnel. "type": "enum", "permission": "01", "values": [ // Actions du bouton optionnelles. Valeurs par défaut : "singlePress", "doublePress", "longPress". Les actions configurées remplacent les valeurs par défaut. ] } } } ``` **Attributs (État) :** ``` { "press": "singlePress" // Type d'appui sur le bouton. **Type :** Chaîne. Valeurs standard : "singlePress" (appui simple ou court), "doublePress" (double appui), "longPress" (appui long). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { [capability] :{ [multi-press-name]：{ press:[value] } } } exemple : { "multi-press": { "1": { "press": "singlePress" }, "2": { "press": "doublePress" } } } ``` **Détection de la puissance du signal (rssi)** **Exemple de déclaration de capacité :** ``` { "capability": "rssi", "permission": "0100" } ``` **Attributs (État) :** ``` { "rssi": -65 // Puissance du signal sans fil (Received Signal Strength Indicator). **Type :** Nombre, unité dBm, valeurs entières négatives. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "rssi": { "rssi": -65 } } ``` **Détection de sabotage (tamper-alert)** **Exemple de déclaration de capacité :** ``` { "capability": "tamper-alert", "permission": "0100" } ``` **Attributs (État) :** ``` { "tamper": "clear" // État de sabotage. **Type :** Chaîne. Valeurs possibles : "clear" (pas de sabotage), "detected" (sabotage détecté). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "tamper-alert": { "tamper": "clear" // État de sabotage. **Type :** Chaîne. Valeurs possibles : "clear" (pas de sabotage), "detected" (sabotage détecté). } } ``` **Détection du niveau d'illumination (illumination-level)** **Exemple de déclaration de capacité :** ``` { "capability": "illumination-level", "permission": "0100" } ``` **Attributs (État) :** ``` { "level": "brighter" // Niveau de luminosité. **Type :** Chaîne. Valeurs possibles : "brighter" (plus lumineux), "darker" (plus sombre). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "illumination-level": { "level": "brighter" } } ``` **Détection de tension (voltage)** **Exemple de déclaration de capacité :** ``` { "capability": "voltage", "permission": "0100" } ``` **Attributs (État) :** ``` { "voltage": 50 // Valeur de tension actuelle, en unités de 0,01 V. **Type :** Nombre, valeurs non négatives. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "voltage": { "voltage": 50 } } ``` **Détection du courant électrique (electric-current)** **Exemple de déclaration de capacité :** ``` { "capability": "electric-current", "permission": "0100" } ``` **Attributs (État) :** ``` { "electric-current": 50 // Valeur du courant actuel, en unités de 0,01 A. **Type :** Nombre, valeurs entières non négatives. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "electric-current": { "electric-current": 50 } } ``` **Détection de la puissance électrique (electric-power)** **Exemple de déclaration de capacité :** ``` { "capability": "electric-power", "permission": "0100" } ``` **Attributs (État) :** ``` { "electric-power": 50 // Valeur de puissance actuelle, en unités de 0,01 W. **Type :** Nombre, valeurs entières non négatives. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "electric-power": { "electric-power": 50 } } ``` **Détection de défaut (fault)** **Exemple de déclaration de capacité :** ``` { "capability": "fault", "permission": "0100" } ``` **Attributs (État) :** ``` { "fault": "none" // État de défaut. **Type :** Chaîne. Valeurs possibles : "none" (pas de défaut), "detected" (défaut détecté). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "fault": { "fault": "none" } } ``` **Seuil déclencheur (threshold-breaker)** **Exemple de déclaration de capacité :** ``` { "capability": "threshold-breaker", "permission": "0010", "settings": { "supportedSetting": { "type": "object", "permission": "11", "value": { "supported": [ { "name": "lowerPower", // Seuil de basse puissance déclencheur "value": { "value": 50, // Valeur de puissance détectée, en unités de 0,01 W. **Type :** Entier. Plage : >=0. "min_range": 10, // Valeur minimale de détection de puissance, en unités de 0,01 W. **Type :** Entier. Plage : >=0. "max_range": 3500 // Valeur maximale de détection de puissance, en unités de 0,01 W. **Type :** Entier. Plage : >=0. } }, { "name": "upperPower", // Seuil de haute puissance déclencheur "value": { "value": 50, // Valeur de puissance détectée, en unités de 0,01 W. **Type :** Entier. Plage : >=0. "min_range": 10, // Valeur minimale de détection de puissance, en unités de 0,01 W. **Type :** Entier. Plage : >=0. "max_range": 3500 // Valeur maximale de détection de puissance, en unités de 0,01 W. **Type :** Entier. Plage : >=0. } }, { "name": "lowerElectricCurrent", // Seuil de courant faible déclencheur "value": { "value": 50, // Valeur de courant détectée, en unités de 0,01 A. **Type :** Entier. Plage : >=0. "min_range": 10, // Valeur minimale de détection de courant, en unités de 0,01 A. **Type :** Entier. Plage : >=0. "max_range": 1500 // Valeur maximale de détection de courant, en unités de 0,01 A. **Type :** Entier. Plage : >=0. } }, { "name": "upperElectricCurrent", // Seuil de courant élevé déclencheur "value": { "value": 50, // Valeur de courant détectée, en unités de 0,01 A. **Type :** Entier. Plage : >=0. "min_range": 10, // Valeur minimale de détection de courant, en unités de 0,01 A. **Type :** Entier. Plage : >=0. "max_range": 1500 // Valeur maximale de détection de courant, en unités de 0,01 A. **Type :** Entier. Plage : >=0. } }, { "name": "lowerVoltage", // Seuil de basse tension déclencheur "value": { "value": 50, // Valeur de tension détectée, en unités de 0,01 V. **Type :** Entier. Plage : >=0. "min_range": 10, // Valeur minimale de détection de tension, en unités de 0,01 V. **Type :** Entier. Plage : >=0. "max_range": 24000 // Valeur maximale de détection de tension, en unités de 0,01 V. **Type :** Entier. Plage : >=0. } }, { "name": "upperVoltage", // Seuil de haute tension déclencheur "value": { "value": 50, // Valeur de tension détectée, en unités de 0,01 V. **Type :** Entier. Plage : >=0. "min_range": 10, // Valeur minimale de détection de tension, en unités de 0,01 V. **Type :** Entier. Plage : >=0. "max_range": 24000 // Valeur maximale de détection de tension, en unités de 0,01 V. **Type :** Entier. Plage : >=0. } } ] } } } } ``` **Attributs (État)** * Aucun **Protocole (Interroger l'état et instructions de contrôle)** * Aucun **Fonction Inch (inching)** **Exemple de déclaration de capacité :** ``` { "capability": "inching", "permission": "0010", "settings": { "inchingEnable": { // Réglage d'activation de la fonction inch "permission": "11", "type": "boolean", "value": false }, "inchingSwitch": { // Réglage de l'action inch "type": "enum", "permission": "11", "value": "on", "values": ["on", "off"] }, "inchingDelay": { // Réglage du temps d'inch "type": "numeric", "permission": "11", "min": 500, "max": 100000, "value": 1000, "unit": "ms" } } } ``` **Attributs (État) :** * Aucun **Protocole (Interroger l'état et instructions de contrôle) :** * Aucun **Flux de caméra (camera-stream)** **Exemple de déclaration de capacité :** ``` { "capability": "camera-stream", "permission": "0010", "settings": { "streamSetting": { "type": "object", "permission": "11", "value": { "username": "String", // Compte d'accès. **Type :** Chaîne. Requis. "password": "String", // Mot de passe d'accès. **Type :** Chaîne. Requis. "streamUrl": "rtsp://:@:/streaming/channel01", // URL du flux. **Type :** Chaîne. Requis. "videoCodec": "", // Codec vidéo. **Type :** Chaîne. Requis. Paramètres optionnels à définir. "resolution": { // Résolution vidéo. Requise. "width": 1080, // Largeur. **Type :** Nombre. Requis. "height": 720 // Hauteur. **Type :** Nombre. Requis. }, "keyFrameInterval": 5, // Intervalle de key frame. **Type :** Chaîne. Requis. "audioCodec": "G711", // Codec audio. **Type :** Chaîne. Requis. Paramètres optionnels à définir. "samplingRate": 50, // Fréquence d'échantillonnage audio, en Hz. **Type :** Nombre. Requis. Paramètres optionnels à définir. "dataRate": 50 // Débit binaire. **Type :** Nombre. Requis. Unité : kb/s. } } } } ``` **Attributs (État) :** * Aucun **Protocole (Interroger l'état et instructions de contrôle) :** * Aucun **Contrôle de mode (mode)** **Exemple de déclaration de capacité :** ``` [ { "capability": "mode", "name": "fanLevel", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["low", "medium", "high"] // Valeurs de mode personnalisées. Les valeurs configurées remplacent les valeurs par défaut. } } }, { "capability": "mode", "name": "thermostatMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["auto", "manual"] // Valeurs de mode personnalisées. Les valeurs configurées remplacent les valeurs par défaut. } } }, { "capability": "mode", "name": "airConditionerMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["cool", "heat", "auto", "fan", "dry"] // Valeurs de mode personnalisées. Les valeurs configurées remplacent les valeurs par défaut. } } }, { "capability": "mode", "name": "fanMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["normal", "sleep", "child"] // Valeurs de mode personnalisées. Les valeurs configurées remplacent les valeurs par défaut. } } }, { "capability": "mode", "name": "horizontalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valeurs de mode personnalisées. Les valeurs configurées remplacent les valeurs par défaut. } } }, { "capability": "mode", "name": "verticalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valeurs de mode personnalisées. Les valeurs configurées remplacent les valeurs par défaut. } } } ] ``` **Attributs (État) :** ``` { "modeValue": "low" // Valeur de mode. **Type :** Chaîne. Requise. Se référer aux modes prédéfinis pris en charge. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "mode": { "fanLevel": { "modeValue": "low" } } } ``` **Détection de dioxyde de carbone (co2)** **Exemple de déclaration de capacité :** ``` { "capability": "co2", "permission": "0100", "settings": { "co2Range": { "type": "numeric", "permission": "01", "min": 400, "max": 10000 } } } ``` **Attributs (État) :** ``` { "co2": 111 // Concentration de dioxyde de carbone. **Type :** Entier. Unité : ppm. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "co2": { "co2": 500 } } ``` **Détection d'illumination (illumination)** **Exemple de déclaration de capacité :** ``` { "capability": "illumination", "permission": "0100", "settings": { "illuminationRange": { "type": "numeric", "permission": "01", "min": 0, "max": 160000 } } } ``` **Attributs (État) :** ``` { "illumination": 11 // Niveau d'illumination. **Type :** Entier. Unité : lux. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "illumination": { "illumination": 50 } } ``` **Détection de fumée (smoke)** **Exemple de déclaration de capacité :** ``` { "capability": "smoke", "permission": "0100" } ``` **Attributs (État) :** ``` { "smoke": true // Résultat de détection. **Type :** Booléen. `true` indique détection, `false` indique absence de détection. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "smoke": { "smoke": true } } ``` **Détection d'ouverture/fermeture par aimant de porte (contact)** **Exemple de déclaration de capacité :** ``` { "capability": "contact", "permission": "0100" } ``` **Attributs (État) :** ``` { "contact": true // Résultat de détection. **Type :** Booléen. `true` indique détection, `false` indique aucune détection. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "contact": { "contact": true } } ``` **Détection de mouvement (motion)** **Exemple de déclaration de capacité :** ``` { "capability": "motion", "permission": "0110", "settings": { "motionInterval": { "type": "numeric", "permission": "11", "value": 300 }, "motionSensitivity": { "type": "numeric", "permission": "11", "value": 1000 } } } ``` **Attributs (État) :** ``` { "motion": true // Résultat de détection. **Type :** Booléen. `true` indique détection, `false` indique aucune détection. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "motion": { "motion": true } } ``` **Détection de fuite d'eau (water-leak)** **Exemple de déclaration de capacité :** ``` { "capability": "water-leak", "permission": "0100" } ``` **Attributs (État) :** ``` { "waterLeak": true // Le champ `waterLeak` indique le résultat de détection actuel. **Type :** Booléen. `true` indique détection, `false` indique aucune détection. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "water-leak": { "waterLeak": true } } ``` **Interrupteur de détection de fenêtre (window-detection)** **Exemple de déclaration de capacité :** ``` { "capability": "window-detection", "permission": "1100" } ``` **Attributs (État) :** ``` { "powerState": "on" // Le champ `powerState` indique l'état d'alimentation. **Type :** Chaîne. `on` indique que l'alimentation est activée, `off` indique qu'elle est désactivée. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "window-detection": { "powerState": "on" } } ``` **Verrouillage enfant (child-lock)** **Exemple de déclaration de capacité :** ``` { "capability": "child-lock", "permission": "1100" } ``` **Attributs (État) :** ``` { "powerState": "on" // Le champ `powerState` indique l'état d'alimentation. **Type :** Chaîne. `on` indique que l'alimentation est activée, `off` indique qu'elle est désactivée. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "child-lock": { "powerState": "on" } } ``` **Anti-coup direct (anti-direct-blow)** **Exemple de déclaration de capacité :** ``` { "capability": "anti-direct-blow", "permission": "1100" } ``` **Attributs (État) :** ``` { "powerState": "on" // Le champ `powerState` indique l'état d'alimentation. **Type :** Chaîne. `on` indique que l'alimentation est activée, `off` indique qu'elle est désactivée. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "anti-direct-blow": { "powerState": "on" } } ``` **Balancement horizontal (horizontal-swing)** **Exemple de déclaration de capacité :** ``` { "capability": "horizontal-swing", "permission": "1100" } ``` **Attributs (État) :** ``` { "powerState": "on" // Le champ `powerState` indique l'état d'alimentation. **Type :** Chaîne. `on` indique que l'alimentation est activée, `off` indique qu'elle est désactivée. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "horizontal-swing": { "powerState": "on" } } ``` **Balancement vertical (vertical-swing)** **Exemple de déclaration de capacité :** ``` { "capability": "vertical-swing", "permission": "1100" } ``` **Attributs (État) :** ``` { "powerState": "on" // Le champ `powerState` indique l'état d'alimentation. **Type :** Chaîne. `on` indique que l'alimentation est activée, `off` indique qu'elle est désactivée. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "vertical-swing": { "powerState": "on" } } ``` **Mode ÉCO (eco)** **Exemple de déclaration de capacité :** ``` { "capability": "eco", "permission": "1100" } ``` **Attributs (État) :** ``` { "powerState": "on" // Le champ `powerState` indique l'état d'alimentation. **Type :** Chaîne. `on` indique que l'alimentation est activée, `off` indique qu'elle est désactivée. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "eco": { "powerState": "on" } } ``` **Basculer au démarrage (toggle-startup)** **Exemple de déclaration de capacité :** ``` { "capability": "toggle-startup", "permission": "1100", "name": "1" // Le champ `name` spécifie le nom de l'attribut pour `toggle-startup`. **Type :** Chaîne. Seules les lettres et les chiffres sont autorisés. } ``` **Attributs (État) :** ``` { "startup": "on" // **Type :** Chaîne. Options : `on` (alimentation activée), `stay` (maintien de l'alimentation), `off` (alimentation désactivée). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "toggle-startup": { "1": { "startup": "on" }, "2": { "startup": "off" } } } ``` **Détection de maintien (detect-hold)** **Exemple de déclaration de capacité :** ``` { "capability": "detect-hold", "permission": "0100", "settings": { "detectHoldEnable": { // Paramètre d'activation de la détection de maintien "permission": "01", "type": "boolean", "value": false }, "detectHoldSwitch": { // Paramètre d'action de la détection de maintien "type": "enum", "permission": "01", "value": "on", "values": ["on", "off"] }, "detectHoldTime": { // Paramètre du temps de détection de maintien "type": "numeric", "permission": "01", "min": 1, "max": 359, "value": 5, "unit": "minute" } } } ``` **Attributs (État) :** ``` { "detectHold": "on" // Le champ `detectHold` indique l'état du maintien de détection. **Type :** Chaîne. `on` signifie que le maintien de détection est actif, `off` signifie qu'il est inactif. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "detect-hold": { "detectHold": "on" } } ``` **Basculer Identifier/Activer (toggle-identify)** **Exemple de déclaration de capacité :** ``` { "capability": "toggle-identify", "permission": "1100", // Remarque : Cette capacité n'est pas utilisée pour le reporting dans la version actuelle (V1.13.7) sur ihost. "name": "1" // Nom du composant. **Type :** Chaîne. Valeurs optionnelles : "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ``` **Attributs (État) :** ``` { "identify": true, // Indique que le dispositif a signalé activement une identification ou une activation. "countdown": 180 // Le champ `countdown` indique la durée d'activation. **Type :** Nombre. Unité : secondes. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "toggle-identify": { "1": { "countdown": 180 // Active l'appareil pendant 180 secondes. } } } // L'appareil signale une auto-activation { "toggle-identify": { "1": { "identify": true } } } ``` **Basculer Détection de Tension (toggle-voltage)** **Exemple de déclaration de capacité :** ``` { "capability": "toggle-voltage", "permission": "1100" } ``` **Attributs (État) :** ``` { "voltage": 230 // Le champ `voltage` indique la tension détectée. **Type :** Nombre. Unité : Volts. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "toggle-voltage": { "voltage": 230 } } ``` **Détection de courant électrique du sous-composant (toggle-electric-current)** **Exemple de déclaration de capacité :** ``` [ { "capability": "toggle-electric-current", "permission": "0100", "name": "1" // Nom du composant. **Type :** Chaîne. Valeurs optionnelles : "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ] ``` **Attributs (État) :** ``` { "electricCurrent": 50 // Le champ `electricCurrent` représente la valeur du courant. **Unité :** 0.01 A. **Type :** Entier. La valeur doit être supérieure ou égale à 0. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "toggle-electric-current": { "1": { "electricCurrent": 50 } } } ``` **Détection de puissance du sous-composant (toggle-electric-power)** **Exemple de déclaration de capacité :** ``` [ { "capability": "toggle-electric-power", "permission": "0100", "name": "1" // Nom du composant. **Type :** Chaîne. Valeurs optionnelles : "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ] ``` **Attributs (État) :** ``` { "electricPower": 50, // Le champ `electricPower` représente la valeur de puissance actuelle. **Unité :** 0.01 W. **Type :** Entier. La valeur doit être supérieure ou égale à 0. "reactivePower": 50, // Le champ `reactivePower` représente la valeur de puissance réactive actuelle. **Unité :** 0.01 W. **Type :** Entier. Optionnel. "activePower": 50, // Le champ `activePower` représente la valeur de puissance active actuelle. **Unité :** 0.01 W. **Type :** Entier. Optionnel. "apparentPower": 50 // Le champ `apparentPower` représente la valeur de puissance apparente actuelle. **Unité :** 0.01 W. **Type :** Entier. Optionnel. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "toggle-electric-power": { "1": { "electricPower": 50, "reactivePower": 50, "activePower": 50, "apparentPower": 50 } } } ``` **Statistiques de consommation d'énergie du sous-composant (toggle-power-consumption)** **Exemple de déclaration de capacité :** ``` [ { "capability": "toggle-power-consumption", "permission": "1101", "name": "1", // Nom du composant. **Type :** Chaîne. Valeurs optionnelles : "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ] ``` **Attributs (État) :** Démarrer/Arrêter les statistiques en temps réel : ``` { "rlSummarize": true, // Démarrer ou arrêter les statistiques en temps réel. **Type :** Booléen. Requis. "timeRange": { // Plage temporelle du résumé. Requis. "start": "2020-07-05T08:00:00Z", // Heure de début de la consommation d'énergie. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin de la consommation d'énergie. **Type :** Chaîne. Requis. } } ``` Interroger la consommation d'énergie par plage horaire : ``` { "type": "summarize", // Type de résumé. **Type :** Chaîne. Requis. Options : "rlSummarize" (Résumé en temps réel), "summarize" (Résumé courant). "timeRange": { // Plage temporelle du résumé, requise lorsque le type est "summarize". "start": "2020-07-05T08:00:00Z", // Heure de début de la consommation d'énergie. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin de la consommation d'énergie. **Type :** Chaîne. Optionnel. Si non fourni, la valeur par défaut est l'heure actuelle. } } ``` Réponse pour la consommation d'énergie dans la plage temporelle : ``` { "type": "summarize", // Type de résumé. **Type :** Chaîne. Requis. "rlSummarize": 50.0, // Consommation d'énergie totale. **Unité :** 0.01 kWh. **Type :** Nombre. Optionnel. "electricityIntervals": [ // Divisé par `configuration.resolution` en plusieurs enregistrements. Optionnel. Non présent lorsque le type est "rlSummarize". { "usage": 26.5, // Consommation d'énergie. **Unité :** 0.01 kWh. **Type :** Nombre. Requis. "start": "2020-07-05T08:00:00Z", // Heure de début. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin. **Type :** Chaîne. Requis. Les enregistrements dont les intervalles sont plus courts que la résolution sont considérés comme invalides. }, { "usage": 26.5, // Consommation d'énergie. **Unité :** 0.01 kWh. **Type :** Nombre. Requis. "start": "2020-07-05T09:00:00Z", // Heure de début. **Type :** Chaîne. Requis. "end": "2020-07-05T10:00:00Z" // Heure de fin. **Type :** Chaîne. Requis. Les enregistrements dont les intervalles sont plus courts que la résolution sont considérés comme invalides. } ] } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Démarrer les statistiques en temps réel : ``` { "toggle-power-consumption": { "1": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Arrêter les statistiques en temps réel : ``` { "toggle-power-consumption": { "1": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obtenir la consommation d'énergie historique : ``` { "toggle-power-consumption": { "1": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obtenir la consommation d'énergie en temps réel : ``` { "toggle-power-consumption": { "1": { "type": "rlSummarize" } } } ``` **Indicateur de qualité de lien (lqi)** **Exemple de déclaration de capacité :** ``` { "capability": "lqi", "permission": "0100" } ``` **Attributs (État) :** ``` { "lqi": 60 // Le champ `lqi` représente l'indicateur de qualité de lien. **Type :** Nombre. Plage de valeurs : 0 à 255. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "lqi": { "lqi": 60 } } ``` **Configuration fonctionnelle (configuration)** **Exemple de déclaration de capacité :** ``` [ { "capability": "configuration", "permission": "1100" } ] ``` **Attributs (État) :** ``` { "deviceConfiguration": { // Configuration fonctionnelle liée à l'appareil "defaultResolution": 300, // Résolution par défaut pour la lecture des données de saturation d'humidité. **Type :** Entier. **Unité :** Secondes. Requis. "maxResolution": 86400, // Résolution maximale pour la lecture des données de saturation d'humidité. **Type :** Entier. **Unité :** Secondes. Requis. "minResolution": 60 // Résolution minimale pour la lecture des données de saturation d'humidité. **Type :** Entier. **Unité :** Secondes. Requis. } } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "configuration": { "deviceConfiguration": { // Configuration fonctionnelle liée à l'appareil "defaultResolution": 300, // Résolution par défaut pour la lecture des données de saturation d'humidité. **Type :** Entier. **Unité :** Secondes. Requis. "maxResolution": 86400, // Résolution maximale pour la lecture des données de saturation d'humidité. **Type :** Entier. **Unité :** Secondes. Requis. "minResolution": 60 // Résolution minimale pour la lecture des données de saturation d'humidité. **Type :** Entier. **Unité :** Secondes. Requis. } } } ``` **Système (system)** **Exemple de déclaration de capacité :** ``` [ { "capability": "system", "permission": "1000" } ] ``` **Attributs (État) :** ``` { "restart": true // Commande de redémarrage de l'appareil. **Type :** Booléen. Requis. La valeur doit être `true`. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "system": { // Configuration liée à la capacité. Optionnelle. "restart": true } } ``` **Humidité (moisture)** **Exemple de déclaration de capacité :** ``` [ { "capability": "moisture", "permission": "0100" } ] ``` **Attributs (État) :** ``` { "moisture": 55.5 // Le champ `moisture` représente le pourcentage de saturation d'humidité. **Type :** Nombre. Requis. Plage : 0 à 100. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "moisture": { "moisture": 55.5 } } ``` **Pression barométrique (barometric-pressure)** **Exemple de déclaration de capacité :** ``` [ { "capability": "barometric-pressure", "permission": "0100", "settings": { "barometricPressureRange": { "type": "numeric", "permission": "01", "min": 540, // Valeur minimale. **Type :** Entier. Requis. Doit être inférieure à `max`. "max": 1100 // Valeur maximale. **Type :** Entier. Requis. Doit être supérieure à `min`. } } } ] ``` **Attributs (État) :** ``` { "barometricPressure": 50 // Valeur de la pression barométrique. **Type :** Entier. Requis. **Unité :** hPa. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "barometric-pressure": { "barometricPressure": 50 } } ``` **Vitesse du vent (wind-speed)** **Exemple de déclaration de capacité :** ``` [ { "capability": "wind-speed", "permission": "0100", "settings": { "windSpeedRange": { "type": "numeric", "permission": "01", "min": 0, // Valeur minimale. **Type :** Nombre. Requis. Doit être inférieure à `max`. "max": 50 // Valeur maximale. **Type :** Nombre. Requis. Doit être supérieure à `min`. } } } ] ``` **Attributs (État) :** ``` { "windSpeed": 50 // Valeur de la vitesse du vent. **Type :** Nombre. Requis. **Unité :** m/s (mètres par seconde). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "wind-speed": { "windSpeed": 50 } } ``` **Direction du vent (wind-direction)** **Exemple de déclaration de capacité :** ``` [ { "capability": "wind-direction", "permission": "0100" } ] ``` **Attributs (État) :** ``` { "windDirection": 10 // Direction du vent. **Type :** Entier. Requis. **Unité :** Degrés. Plage : 0 à 360 degrés (sens horaire). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "wind-direction": { "windDirection": 10 } } ``` **Pluviométrie (rainfall)** **Exemple de déclaration de capacité :** ``` [ { "capability": "rainfall", "permission": "0100", "settings": { "rainfallRange": { "type": "numeric", "permission": "01", "min": 0, // Valeur minimale. **Type :** Nombre. Requis. Doit être inférieure à `max`. "max": 450 // Valeur maximale. **Type :** Nombre. Requis. Doit être supérieure à `min`. } } } ] ``` **Attributs (État) :** ``` { "rainfall": 11.11 // Valeur de la pluviométrie. **Type :** Nombre. Requis. **Unité :** mm/h (millimètres par heure). } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "rainfall": { "rainfall": 11.11 } } ``` **Indice UV (ultraviolet-index)** **Exemple de déclaration de capacité :** ``` [ { "capability": "ultraviolet-index", "permission": "0100", "settings": { "ultravioletIndexRange": { "type": "numeric", "permission": "01", "min": 0, // Valeur minimale. **Type :** Nombre. Requis. Doit être inférieure à `max`. "max": 16 // Valeur maximale. **Type :** Nombre. Requis. Doit être supérieure à `min`. } } } ] ``` **Attributs (État) :** ``` { "ultravioletIndex": 11.1 // Indice ultraviolet. **Type :** Nombre. Requis. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "ultraviolet-index": { "ultravioletIndex": 11.1 } } ``` **Conductivité électrique (electrical-conductivity)** **Exemple de déclaration de capacité :** ``` [ { "capability": "electrical-conductivity", "permission": "0100", "settings": { "electricalConductivityRange": { "type": "numeric", "permission": "01", "min": 0, // Valeur minimale. **Type :** Nombre. Requis. Doit être inférieure à `max`. "max": 23 // Valeur maximale. **Type :** Nombre. Requis. Doit être supérieure à `min`. } } } ] ``` **Attributs (État) :** ``` { "electricalConductivity": 11.11 // Valeur de la conductivité électrique. **Type :** Nombre. Requis. **Unité :** dS/m. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "electrical-conductivity": { "electricalConductivity": 11.11 } } ``` **Puissance d'émission (transmit-power)** **Exemple de déclaration de capacité :** ``` [ { "capability": "transmit-power", "permission": "1100" } ] ``` **Attributs (État) :** ``` { "transmitPower": 9 // Valeur de puissance d'émission de l'appareil. **Type :** Entier. Requis. **Unité :** dBm. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "transmit-power": { "transmitPower": 9 } } ``` **Détection PM2.5 (pm25)** **Exemple de déclaration de capacité :** ``` [ { "capability": "pm25", "permission": "0100" } ] ``` **Attributs (État) :** ``` { "pm25": 10 // Concentration de PM2.5 dans l'air. **Type :** Nombre. Requis. **Unité :** µg/m³. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "pm25": { "pm25": 10 } } ``` **Indice COV (voc-index)** **Exemple de déclaration de capacité :** ``` { "capability": "voc-index", "permission": "0100" } ``` **Attributs (État) :** ``` { "vocIndex": 10 // Indice VOC reflétant le niveau de pollution par des gaz nocifs. **Type :** Nombre. Requis. **Unité :** µg/m³. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "voc-index": { "vocIndex": 10 } } ``` **Détection de gaz naturel (gas)** **Exemple de déclaration de capacité :** ``` { "capability": "gas", "permission": "0100" } ``` **Attributs (État) :** ``` { "gas": true // Indique si une fuite de gaz naturel est détectée. **Type :** Booléen. Requis. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "gas": { "gas": true } } ``` **Statut de travail d'irrigation (irrigation/work-status)** **Exemple de déclaration de capacité :** ``` [ { "capability": "irrigation", "permission": "0101", "name": "work-status", "settings": { "volumeUnit": { "type": "enum", "permission": "01", "values": ["L"], "value": "L" } } } ] ``` **Attributs (État) :** ``` { "realTimeVolume": 20, // Volume d'irrigation en temps réel. **Type :** Nombre. Optionnel. **Unité :** L. "start": "2020-07-05T08:00:00Z", // Heure de début de l'irrigation. **Type :** Date. Optionnel. "end": "2020-07-05T09:00:00Z", // Heure de fin de l'irrigation. **Type :** Date. Optionnel. "dailyVolume": 20 // Volume d'irrigation quotidien. **Type :** Nombre. Optionnel. **Unité :** L. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Rapport de l'état de travail : ``` { "irrigation": { "work-status": { "realTimeVolume": 20, "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z", "dailyVolume": 20 } } } ``` Requête d'état de travail : ``` { "irrigation": { "type": "oneDay", // Type d'agrégation. **Type :** Chaîne. Requis. Options : "oneDay", "30Days", "180Days". "timeRange": { // Plage temporelle pour l'agrégation. **Type :** Objet. Requis. "start": "2020-07-05T08:00:00Z", // Heure de début pour l'agrégation des données d'irrigation. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin pour l'agrégation des données d'irrigation. **Type :** Chaîne. Optionnel. Si omis, l'heure actuelle est utilisée. } } } ``` Résultat de la requête d'état de travail : ``` { "irrigation": { "type": "oneDay", // Type d'agrégation. **Type :** Chaîne. Requis. "irrigationIntervals": [ { "volume": 6500, // Volume d'irrigation. **Type :** Nombre. Requis. **Unité :** L. "duration": 30, // Durée d'irrigation. **Type :** Nombre. Requis. **Unité :** minutes. "start": "2020-07-05T08:00:00Z", // Heure de début. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin. **Type :** Chaîne. Requis. }, { "volume": 6500, // Volume d'irrigation. **Type :** Nombre. Requis. **Unité :** L. "duration": 30, // Durée d'irrigation. **Type :** Nombre. Requis. **Unité :** minutes. "start": "2020-07-05T08:00:00Z", // Heure de début. **Type :** Chaîne. Requis. "end": "2020-07-05T09:00:00Z" // Heure de fin. **Type :** Chaîne. Requis. } ] } } ``` **Mode de travail d'irrigation (irrigation/work-mode)** **Exemple de déclaration de capacité :** ``` [ { "capability": "irrigation", "permission": "0100", "name": "work-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", // Mode manuel "TIMER", // Programmation à heure unique "CYCLE-TIMER", // Programmation répétée "VOLUME", // Volume à heure unique "CYCLE-VOLUME" // Volume répété ] } } } ] ``` **Attributs (État) :** ``` { "workMode": "MANUAL" // Mode de travail d'irrigation. **Type :** Chaîne. Optionnel. Les valeurs doivent provenir de `settings.supportedModes`. } ``` **Protocole (Interroger l'état et instructions de contrôle) :** ``` { "irrigation": { "work-mode": "MANUAL" } } ``` **Contrôleur d'irrigation automatique (irrigation/auto-controller)** **Exemple de déclaration de capacité :** ``` [ { "capability": "irrigation", "permission": "1100", "name": "auto-controller", "settings": { "volumeRange": { // Plage de volume "type": "enum", "permission": "01", "min": 0, "max": 6500, "unit": "L" }, "timeRange": { // Plage temporelle "type": "enum", "permission": "01", "min": 1, "max": 86400, "unit": "second" }, "cycleCountRange": { // Plage du nombre de cycles "type": "enum", "permission": "01", "min": 1, "max": 100, "step": 1 } } } ] ``` **Attributs (État) :** Programmation à heure unique ou répétée : ``` { "type": "time", // Mode d'irrigation. **Type :** Chaîne. Requis. Options : "volume", "time". "action": { "perDuration": 60, // Durée par cycle d'irrigation. **Type :** Nombre. Requis. "intervalDuration": 20, // Intervalle entre les cycles d'irrigation. **Type :** Nombre. Requis. "count": 3 // Nombre de cycles d'irrigation. **Type :** Nombre. Requis. } } ``` Volume à heure unique ou répété : ``` { "type": "volume", // Mode d'irrigation. **Type :** Chaîne. Requis. Options : "volume", "time". "action": { "perConsumedVolume": 60, // Volume consommé par cycle d'irrigation. **Type :** Nombre. Requis. "intervalDuration": 20, // Intervalle entre les cycles d'irrigation. **Type :** Nombre. Requis. "count": 3 // Nombre de cycles d'irrigation. **Type :** Nombre. Requis. } } ``` **Protocole (Interroger l'état et instructions de contrôle) :** Programmation à heure unique ou répétée : ``` { "irrigation": { "auto-controller": { "type": "time", // Mode d'irrigation. **Type :** Chaîne. Requis. "action": { "perDuration": 60, // Durée par cycle d'irrigation. **Type :** Nombre. Requis. "intervalDuration": 20, // Intervalle entre les cycles. **Type :** Nombre. Requis. "count": 3 // Nombre de cycles. **Type :** Nombre. Requis. } } } } ``` Volume à heure unique ou répété : ``` { "irrigation": { "auto-controller": { "type": "volume", // Mode d'irrigation. **Type :** Chaîne. Requis. "action": { "perConsumedVolume": 60, // Volume consommé par cycle. **Type :** Nombre. Requis. "intervalDuration": 20, // Intervalle entre les cycles. **Type :** Nombre. Requis. "count": 3 // Nombre de cycles. **Type :** Nombre. Requis. } } } } ``` **Modes prédéfinis pris en charge** | \*\*Noms des modes \*\* | \*\*Valeurs optionnelles \*\* | | ----------------------------------------------- | ----------------------------- | | fanLevel (niveau du ventilateur) | "low" | | "medium" | | | "high" | | | thermostatMode (mode thermostat) | "auto" | | "manual" | | | airConditionerMode >= 1.11.0 (mode climatiseur) | "cool" | | "heat" | | | "auto" | | | "fan" | | | "dry" | | | fanMode >= 1.11.0 (mode ventilateur) | "normal" | | "sleep" | | | "child" | | | horizontalAngle >= 1.11.0 (angle horizontal) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | | verticalAngle >= 1.11.0 (angle vertical) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | #### c. Description des balises * La clé spéciale toggle est utilisée pour définir le nom du sous-composant toggle. ``` { "toggle": { '1': 'Chanel1', '2': 'Chanel2', '3': 'Chanel3', '4': 'Chanel4', }, } ``` * La clé spéciale temperature\_unit est utilisée pour définir l'unité de température. ``` { "temperature_unit":'c' // c-Celsius; f-Fahrenheit } ``` #### d. Code d'erreur spécial et description | **Code d'erreur** | **Description** | Version iHost | | ----------------- | ---------------------------------------------------------------------------- | ------------- | | 110000 | Le sous-appareil/groupe correspondant à l'id n'existe pas | ≥2.1.0 | | 110001 | La passerelle est en train de découvrir des appareils zigbee | ≥2.1.0 | | 110002 | Les appareils d'un groupe n'ont pas de capacité commune | ≥2.1.0 | | 110003 | Nombre incorrect d'appareils | ≥2.1.0 | | 110004 | Nombre incorrect de groupes | ≥2.1.0 | | 110005 | Appareil hors ligne | ≥2.1.0 | | 110006 | Échec de la mise à jour du statut de l'appareil | ≥2.1.0 | | 110007 | Échec de la mise à jour du statut du groupe | ≥2.1.0 | | 110008 | Le nombre maximal de groupes a été atteint. Créez jusqu'à 50 groupes | ≥2.1.0 | | 110009 | L'adresse IP de l'appareil caméra est incorrecte | ≥2.1.0 | | 110010 | Erreur d'autorisation d'accès à l'appareil caméra | ≥2.1.0 | | 110011 | Erreur d'adresse de flux de l'appareil caméra | ≥2.1.0 | | 110012 | L'encodage vidéo de l'appareil caméra n'est pas pris en charge | ≥2.1.0 | | 110013 | L'appareil existe déjà | ≥2.1.0 | | 110014 | La caméra ne prend pas en charge le fonctionnement hors ligne | ≥2.1.0 | | 110015 | Le mot de passe du compte est incompatible avec le mot de passe du flux RTSP | ≥2.1.0 | | 110016 | La passerelle est en train de découvrir des caméras onvif | ≥2.1.0 | | 110017 | Nombre maximal de caméras ajoutées dépassé | ≥2.1.0 | | 110018 | Le chemin de la caméra ESP est incorrect | ≥2.1.0 | | 110019 | Échec d'accès à l'adresse de service de l'appareil tiers | ≥2.1.0 | #### e. Recherche de sous-appareil Permettre aux utilisateurs autorisés d'activer ou de désactiver la recherche de sous-appareils par la passerelle via cette interface * 💡Remarque : Prend actuellement en charge uniquement la recherche de sous-appareils Zigbee. * 💡Remarque : Les sous-appareils Zigbee seront ajoutés automatiquement après la recherche. Il n'est pas nécessaire d'utiliser l'interface "Ajouter manuellement des sous-appareils" :::tips * **URL**：/open-api/V2/rest/devices/discovery * **Méthode**: PUT * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------------------------------------------------------- | | enable | boolean | N | true (Démarrer l'appairage); false (Mettre en pause l'appairage) | | type | string | N | Type de recherche : Zigbee | Réponse de données réussie : Objet vide {} :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\* `200 OK` ::: **Exemple de réponse**: ``` { "error": 0, "data": {}, "message": "success" } ``` #### f. Ajouter manuellement le sous-appareil Permettre aux utilisateurs autorisés d'ajouter un **unique** sous-appareil via cette interface. * Remarque : Seules les caméras RTSP et ESP32 Camera sont prises en charge pour le moment :::tips * **URL**：/open-api/V2/rest/devices * **Méthode**：POST * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ----------------- | ------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nom du sous-appareil | | display\_category | string | N | Type d'appareil. Prend en charge uniquement la caméra。 | | capabilities | CapabilityObject\[] | N | Liste des capacités. Lorsque display\_category = camera, les capacités n'incluent que les capacités de camera-stream. | | protocal | string | N | Protocole de l'appareil. RTSP; ESP32-CAM | | manufacturer | string | N | Fabricant. | | model | string | N | Modèle de l'appareil | | firmware\_version | string | N | Version du firmware de l'appareil | CapabilityObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------- | ------------------------------- | ------------- | ---------------------------------------------------------------- | | capability | string | N | Nom de la capacité. Prend en charge uniquement "camera-stream" | | permission | string | N | Permission de l'appareil. Prend en charge uniquement la lecture. | | configuration | CameraStreamConfigurationObject | Y | Configuration du flux de la caméra. | SettingsObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------- | ------------------- | ------------- | -------------------------------- | | streamSetting | StreamSettingObject | N | Configuration du service de flux | StreamSettingObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------------------ | ------------- | -------------------------------------------------------------------- | | type | string | N | Configuration du service de flux | | permission | string | N | Permission de la capacité. Ne prend en charge que "11" (modifiable). | | champ valeur | StreamSettingValueObject | N | Valeurs de configuration spécifiques | StreamSettingValueObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | ----------------------- | | stream\_url | string | N | Format de l'URL de flux | | Format :`://:/:@` | | | | | Exemple :`rtsp://admin:123456@192.168.10.115:554/streaming/channel01` | | | | | Options de schéma : | | | | | `rtsp` (Real-Time Streaming Protocol) | | | | | `http` (Hypertext Transfer Protocol) — Pour les appareils ESP32-CAM | | | | | \*Remarque : Certaines caméras peuvent ne pas nécessiter de nom d'utilisateur ou de mot de passe. Dans ce cas, vous pouvez omettre le `` et `` champs de l'URL. | | | | Réponse de données réussie : | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------- | -------- | ------------- | ------------------------------------ | | serial\_number | string | N | Numéro de série unique de l'appareil | :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ``` { "error": 0, "data": { "serial_number": "serial_number" }, "message": "success" } ``` Réponse de données en cas d'échec : Objet vide :::tips **Condition**： 1. Erreur d'accès à l'adresse de flux de la caméra (erreur de format, échec d'autorisation, exception réseau, etc.) 2. L'appareil existe déjà 3. Si un seul appareil échoue à l'ajout, retourne que tous les appareils ont échoué à l'ajout. **Code d'état**: 200 OK **Code d'erreur**： ● 110009 Erreur d'adresse IP de la caméra ● 110010 Erreur d'autorisation d'accès à la caméra ● 110011 Erreur d'adresse de flux de la caméra ● 110012 L'encodage vidéo de la caméra n'est pas pris en charge ● 110013 L'appareil existe déjà ::: **Exemple de réponse**: ``` { "error": 110009, "data": {}, "message": "échec d'accès ip de la caméra" } ``` #### g. Obtenir la liste des sous-appareils Permettre aux utilisateurs autorisés d'obtenir la liste des sous-appareils de la passerelle via cette interface. :::tips * **URL**：/open-api/V2/rest/devices * **Méthode**: GET * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : aucun Réponse de données réussie : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------------------- | ------------- | ----------------- | | device\_list | ResponseDeviceObject\[] | N | Liste d'appareils | ResponseDeviceObject | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | ------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | "N" lorsqu'un appareil tiers est connecté, sinon "Y" | Numéro de série unique de l'appareil tiers | | service\_address | string | "N" lorsqu'un appareil tiers est connecté, sinon "Y" | Adresse de service du tiers | | name | string | N | Nom de l'appareil, s'il n'est pas renommé, sera affiché par le front-end selon les règles d'affichage par défaut. | | manufacturer | string | N | Fabricant | | model | string | N | Modèle de l'appareil | | firmware\_version | string | N | Version du firmware. Peut être une chaîne vide. | | hostname | string | Y | Nom d'hôte de l'appareil | | mac\_address | string | Y | Adresse MAC de l'appareil | | app\_name | string | Y | Le nom de l'application à laquelle il appartient. Si app\_name est renseigné lors de l'obtention du certificat d'interface ouverte, alors tous les appareils ultérieurs connectés via le certificat seront écrits dans ce champ. | | display\_category | string | N | Catégorie de l'appareil | | capabilities | CapabilityObject\[] | N | Capacités de l'appareil | | protocol | string | "N" lorsqu'un appareil tiers est connecté, sinon "Y" | Protocole de l'appareil : zigbee, onvif, rtsp, esp32-cam | | state | objet | Y | Objet d'état de l'appareil. Pour des exemples d'état pour différentes capacités, veuillez consulter 【Support Device Capabilities】 | | tags | objet | Y | Paires clé-valeur au format JSON, informations personnalisées de l'appareil. Les fonctions sont les suivantes : - Utilisé pour stocker les canaux de l'appareil - Utilisé pour stocker les unités de température - Informations personnalisées pour d'autres appareils tiers | | en ligne | boolean | N | État en ligne : True pour en ligne False pour hors ligne | | sous-réseau | boolean | Y | S'il est dans le même sous-réseau que la passerelle | CapabilityObject 💡Remarque : Veuillez consulter les Exemples de capacités d'appareil prises en charge pour \[Supported Device Capabilities]. | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | capability | string | N | Nom de la capacité. Pour plus de détails, consultez \[Supported Device Capabilities] | | permission | string | N | Permission de la capacité. Les valeurs possibles sont "read" (lecteur), "write" (écrivain), "readWrite" (lecture et écriture). | | configuration | objet | Y | Informations de configuration de la capacité. Actuellement utilisé pour camera-stream, consultez \[Supported Device Capabilities] | | name | string | Y | Le champ name dans toggle. Le numéro de sous-canal utilisé pour identifier les appareils multi-canaux. Par exemple, si name est 1, cela signifie le canal 1. | :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ``` { "error": 0, "data":{ "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "Mon appareil", "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. Mettre à jour les informations ou l'état spécifié de l'appareil Permet aux utilisateurs autorisés de modifier les informations de base du sous-appareil et d'émettre des commandes de contrôle via cette interface. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Méthode**：PUT * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Nom de l'appareil | | tags | objet | Y | Paires clé-valeur au format JSON, informations personnalisées de l'appareil. | | state | objet | Y | Objet d'état de l'appareil. Pour des exemples d'état pour différentes capacités, veuillez consulter \[Support Device Capabilities] | | configuration | objet | Y | Informations de configuration de la capacité, actuellement seule la capacité camera\_stream prend en charge la modification. | Réponse de données réussie : :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK **Code d'erreur**: * 110000 Le sous-appareil/groupe correspondant à l'id n'existe pas ::: **Exemple de réponse**: ``` { "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. Supprimer le sous-appareil Permet aux utilisateurs autorisés de supprimer des sous-appareils via cette interface. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Méthode**：DELETE * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Nom de l'appareil. | | tags | objet | Y | Paires clé-valeur au format JSON utilisées pour stocker les noms des canaux de l'appareil et d'autres informations sur les sous-appareils. | | state | objet | Y | Modifier l'état de l'appareil ; pour des détails sur le protocole, référez-vous à "Supported Device Capabilities." | | capabilities | CapabilityObject \[] | Y | Informations de configuration de la capacité ; toutes les capacités qui prennent en charge la configuration peuvent être modifiées. Notez que les permissions ne peuvent pas être changées. | Réponse de données réussie : :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK **Codes d'erreur :** * 110000 : Le sous-appareil/groupe correspondant à l'ID n'existe pas. * 110006 : Échec de la mise à jour de l'état de l'appareil. * 110019 : Échec d'accès à l'adresse du service de l'appareil tiers. * 110024 : Échec de la mise à jour de la configuration de l'appareil. ::: **Exemple de réponse**: ``` { "error": 0, "data": {}, "message": "success" } ``` ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // allumer l'appareil 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. Supprimer le sous-appareil Permet aux utilisateurs autorisés de supprimer des sous-appareils via cette interface.\ :::tips * **URL**：`/open-api/v2/rest/devices/{serial_number}` * **Méthode**：`DELETE` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : Aucun Réponse de données réussie : :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### k. Interroger l'état de l'appareil Permet aux utilisateurs autorisés d'interroger l'état de l'appareil via cette interface.\ :::tips * **URL**：`/open-api/v2/rest/devices/:serial_number/query-state/{capability}` * **Méthode**：POST * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | | query\_state | objet | N | Interroger l'état de l'appareil ; pour des détails sur le protocole, référez-vous à "Supported Device Capabilities." | ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // allumer l'appareil 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", // Type de statistiques, requis "timeRange": { // Plage temporelle pour la synthèse, requis lorsque type="summarize" "start": "2020-07-05T08:00:00Z", // Heure de début pour les statistiques de consommation d'énergie "end": "2020-07-05T09:00:00Z" // Heure de fin pour les statistiques de consommation d'énergie ; si omis, la valeur par défaut est l'heure actuelle } } } }); })() ``` Réponse de données réussie : :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.4 Gestion de la sécurité #### a. Obtenir la liste de sécurité Permet aux utilisateurs autorisés de modifier les paramètres de la passerelle via cette interface. :::tips * **URL**：`/open-api/v2/rest/security` * **Méthode**：`GET` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : Aucun Réponse de données réussie : | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------- | ------------------------- | ------------- | ------------------------------ | | security\_list | ResponseSecurityObject\[] | N | Liste des appareils en réponse | ResponseDeviceObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ------------------ | | sid | int | N | id de sécurité | | name | string | N | Nom de la sécurité | | enable | bool | N | Activé ou non | * true Activé * false Désactivé | :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": { "security_list":[ { "sid": 1, "name": "Mode Maison", "enable": true } ] }, "message": "success" } ``` #### b. Activer le mode de sécurité spécifié Permet aux utilisateurs autorisés d'activer un mode de sécurité spécifié via cette interface.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/enable` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : Aucun Réponse de données réussie : Objet vide {} :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### c. Désactiver le mode de sécurité spécifié Permet aux utilisateurs autorisés de désactiver un mode de sécurité spécifié via cette interface.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/disable` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : Aucun Réponse de données réussie : Objet vide {} :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Activation en un clic de la configuration de sécurité Permet aux utilisateurs autorisés d'activer le mode de configuration de sécurité en un clic via cette interface.\ :::tips * **URL**：`/open-api/v2/rest/security/enable` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : Aucun Réponse de données réussie : Objet vide {} :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### e. Désactiver la sécurité Permet aux utilisateurs autorisés de désactiver la sécurité via cette interface.\ :::tips * **URL**：`/open-api/v2/rest/security/disable` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Authorization: Bearer ::: Paramètres de la requête : Aucun Réponse de données réussie : Objet vide {} :::tips **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*200 OK ::: **Exemple de réponse**: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 4. Accès aux appareils tiers ### 4.1 Instructions d'accès #### Accès aux appareils
#### Accès de la passerelle tierce
#### Étapes d'accès 1. Déterminez la classification de l'appareil dans la passerelle. Pour plus de détails, veuillez consulter \[Supported Device Type]. 2. Déterminez les capacités auxquelles l'appareil peut accéder. Pour plus de détails, veuillez consulter \[Supported Device Capabilities]. 3. Appelez l'interface \[Discovery Request] pour ajouter l'appareil à la passerelle. 1. *Attention : Vous devez fournir l'adresse de service pour recevoir les instructions émises par la passerelle, utilisée pour recevoir les instructions de contrôle d'appareil émises par la passerelle*. 4. Si l'état de l'appareil tiers change, vous devez appeler l'interface \[Device States Change Report] pour renvoyer le dernier état à la passerelle. 5. Après l'ajout, l'appareil tiers apparaîtra dans la liste d'appareils, avec la plupart des fonctions de la passerelle (autres appareils non tiers). Les interfaces ouvertes courantes liées à l'appareil peuvent être utilisées normalement. * Sélectionnez la catégorie d'appareil appropriée. La classification affectera le résultat d'affichage final de l'interface utilisateur après que l'appareil est connecté à la passerelle. * Choisissez la capacité d'appareil correcte. La liste des capacités déterminera l'état du protocole d'état de l'appareil. #### Processus du programme **a. Accès de l'appareil**
**b. Accès de la passerelle tierce**
### 4.2 Exemple d'accès #### Interrupteur, Prise **Synchroniser les appareils tiers** ``` // Requête URL：/open-api/v2/rest/thirdparty/event Méthode：POST En-tête： Content-Type: application/json Autorization: Bearer Corps : { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "ma prise", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "1100" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "nom du fabricant", "model": "nom du modèle", "firmware_version": "version du firmware", "service_address": "http://192.168.31.14/webhook" } ] } } } ``` ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number", "serial_number": "numéro de série" } ] } } ``` **Signaler l'état de l'appareil** ``` URL：/open-api/V2/rest/thirdparty/event Méthode：POST En-tête： Content-Type: application/json Autorization: Bearer Corps : { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } ``` **Signaler hors ligne/en ligne** ``` {  "event": {    "header": {      "name": "DeviceStatesChangeReport",      "message_id": "Identifiant unique, de préférence un UUID v4",      "version": "1"   },    "endpoint": {      "serial_number": "serial_number"   },    "payload": {       "online": true   } } } ``` ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } ``` **Recevoir les instructions concernant le contrôle de l'appareil par la passerelle** ``` URL： Méthode：POST En-tête：  Content-Type: application/json B {  "directive": {    "header": {      "name": "UpdateDeviceStates",      "message_id": "Identifiant unique, de préférence un UUID v4",      "version": "1"   },    "endpoint": {      "third_serial_number": "third_serial_number",      "serial_number": "serial_number"   },    "payload": {       "state": : {         "power": {           "powerState": "on"         }       }   } } } ``` ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } ``` **Interroger l'appareil** ``` URL：/open-api/V2/rest/devices Méthode：GET En-tête：  Content-Type: application/json  Autorization: Bearer   Corps : Aucun ``` ``` { "error": 0, "data": { "device_list": [ { "serial_number": "numéro de série", "third_serial_number": "third_serial_number", "name": "ma prise", "manufacturer": "nom du fabricant", "model": "nom du modèle", "firmware_version": "version du firmware", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] }, "message": "success" } ``` ### 4.3 API Web #### Interface de passerelle de requête tierce **Format de la requête** Permet aux utilisateurs autorisés d'envoyer des requêtes d'événement à la passerelle via cette interface. :::tips * **URL**：/open-api/V2/rest/thirdparty/event * **Méthode**：POST * **En-tête**： * Content-Type: application/json * Autorization: Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------- | ------------- | ---------------------------------------------- | | event | EventObject | N | Structure de l'objet d'événement de la requête | EventObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | | header | HeaderObject | N | Structure de l'en-tête de la requête | | endpoint | EndpointObject | Y | Structure de l'endpoint de la requête Remarque : Ce champ est vide lors de la synchronisation d'une nouvelle liste d'appareils. | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nom de la requête. paramètre optionnel : DiscoveryRequest : Synchroniser de nouveaux appareils DeviceStatesChangeReport : Rapport de mise à jour de l'état de l'appareil DeviceOnlineChangeReport : Rapport d'état en ligne de l'appareil | | message\_id | string | N | ID du message de la requête, UUID\_V4 | | version | string | N | Numéro de version du protocole de la requête. Actuellement fixé à 1 | EndpointObject | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | N | Numéro de série unique de l'appareil tiers | | tags | objet | Y | Paires clé-valeur au format JSON, informations personnalisées de l'appareil. \[Fonction de gestion des appareils] - \[Description des tags] | PayloadObject Selon le header.name différent, la structure de la requête est différente. **Format de la réponse** :::tips \*\*Code d'état : \*\*200 OK **Paramètres de la réponse :** ::: | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la réponse | | payload | PayloadObject | N | Structure de la charge utile de la réponse | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nom de l'en-tête de la réponse. paramètres optionnels : Response : Réponse réussie ErrorResponse : Réponse d'erreur | | message\_id | string | N | ID du message de l'en-tête de la réponse, UUID\_V4. Transmettre ici header.message\_id du message de la requête \*Si le paramètre message\_id manque dans la requête, ce champ sera une chaîne vide dans la réponse. | | version | string | N | - Numéro de version du protocole de la requête. Actuellement fixé à 1. | > Réponse réussie--PayloadObject ： Selon le type de requête, la structure de la réponse est différente. Pour plus de détails, veuillez consulter le document d'instruction de la requête spécifique. > Réponse d'échec--PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------- | | type | string | N | Types d'erreur : | * INVALID\_PARAMETERS : Erreur de paramètres * AUTH\_FAILURE : Erreur d'autorisation * INTERNAL\_ERROR : Erreur interne du service | | description | string | N | Description de l'erreur | **DiscoveryRequest Synchroniser une nouvelle liste d'appareils** * Remarque : Après la synchronisation de l'appareil vers la passerelle, il est en ligne par défaut, c'est-à-dire online=true. Les changements ultérieurs d'état en ligne dépendent entièrement de la synchronisation avec la tierce partie via l'interface DeviceOnlineChangeReport. **Paramètres de la requête :** EndpointObject\*\*：\*\*Aucun PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------------- | ------------- | ----------------- | | endpoints | EndpointObject\[] | N | Liste d'appareils | EndpointObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | ------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | third\_serial\_number | string | N | Numéro de série unique de l'appareil tiers | | name | string | N | Nom de l'appareil | | display\_category | string | N | Catégorie de l'appareil. Voir \[Supported Device Type] pour les détails. \*Les appareils tiers ne prennent pas en charge l'ajout de caméras pour le moment. | | capabilities | CapabilityObject\[] | N | Liste des capacités | | state | objet | N | Informations d'état initial | | manufacturer | string | N | Fabricant | | model | string | N | Modèle de l'appareil | | tags | objet | Y | Paires clé-valeur au format JSON, informations personnalisées de l'appareil : Utilisées pour stocker les canaux de l'appareil Utilisées pour stocker les unités de température Autres données personnalisées tiers | | firmware\_version | string | N | Version du firmware | | service\_address | string | N | Adresse de service. Par exemple | Exemple de requête : ``` { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "ma prise", "display_category": "plug", "capabilities": [ { "capability": "power", "permission" "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "nom du fabricant", "model": "nom du modèle", "firmware_version": "version du firmware", "service_address": "http://192.168.31.14/service_address" } ] } } } ``` **Paramètres de la réponse :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------------- | ------------- | ----------------- | | endpoints | EndpointObject\[] | N | Liste d'appareils | EndpointObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | -------- | ------------- | ------------------------------------------ | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | N | Numéro de série unique de l'appareil tiers | Exemple d'une réponse correcte : ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "endpoints": [ { "serial_number": "numéro de série", "third_serial_number": "third_serial_number" } ] } } ``` Exemple d'une réponse d'erreur : ``` { "header": { "name": "ErrorResponse", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "webhook cannot be empty" } } ``` **DeviceStatesChangeReport Rapport de changement d'état de l'appareil** * Remarque : Des rapports d'état répétés peuvent déclencher faussement une scène associée. **Paramètres de la requête :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------------------------------------------------------------------- | | state | objet | N | État de l'appareil, voir \[Supported device cabilities] pour plus de détails | Exemple de requête : ``` { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Paramètres de la réponse :** PayloadObject : Objet vide Exemple d'une réponse réussie : ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } ``` **DeviceOnlineChangeReport Rapport d'état en ligne de l'appareil** * Remarque : Des rapports d'état répétés peuvent déclencher faussement une scène associée. **Paramètres de la requête :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------------ | -------- | ------------- | ------------------------------------------- | | en ligne | boolean | N | État en ligne de l'appareil true : En ligne | | false : Hors ligne | | | | Exemple de requête : ``` { "event": { "header": { "name": "DeviceOnlineChangeReport", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": true } } } ``` **Paramètres de la réponse :** PayloadObject : Objet vide Exemple d'une réponse réussie : ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } ``` **DeviceInformationUpdatedReport Rapport de mise à jour des informations de l'appareil** * Remarque : La mise à jour peut affecter les scènes existantes ou les fonctions de sécurité. **Paramètres de la requête :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------- | | capabilities | | | | \| CapabilityObject\[] \| N \| Liste des capacités. Les détails peuvent être consultés dans la section capacités d'appareil prises en charge. \*\*Remarque : \*\*Ce paramètre ne mettra à jour que le `champ valeur` du `paramètre` clé au sein du `CapabilityObject`, et les mises à jour sont autorisées uniquement si le `permission` pour la `paramètre` clé est `11` ou `01`. Pour la définition de structure spécifique du `paramètre` dans `CapabilityObject`, se référer à la description détaillée à la section 2.3 Catégories d'affichage des appareils & Capacités des appareils. | | tags \| object \| Y \| Paires clé-valeur au format JSON, informations personnalisées de l'appareil. * Peut être utilisé pour stocker les canaux de l'appareil * Peut être utilisé pour stocker les unités de température * Autres données personnalisées tierces | Exemple de requête : ```json { "event": { "header": { "name": "DeviceInformationUpdatedReport", "message_id": "Identifiant unique, de préférence un UUID v4", "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, } } } ] } } } ``` **esponse parameters:** PayloadObject : Objet vide Exemple d'une réponse réussie : ```json { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "payload": {} } ``` #### La passerelle envoie l'interface d'instruction via l'adresse de service de l'appareil * Remarque : 1. Les tiers doivent répondre à la demande de la passerelle dans les 3 s. Sinon, la passerelle jugera que le traitement de la commande a expiré. 2. Si le service tiers est hors ligne, la passerelle définira l'appareil en état hors ligne, et le service tiers doit signaler l'état de l'appareil (DeviceStatesChangeReport) ou l'état en ligne (DeviceOnlineChangeReport) avant de revenir en état en ligne. **Format de la requête** La passerelle envoie des instructions au tiers via l'interface d'adresse de service de l'appareil. :::tips * **URL**： * **Méthode**：POST * **En-tête**： * Content-Type: application/json ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | --------------- | ------------- | ------------------------------ | | directive | DirectiveObject | N | Structure de l'objet directive | DirectiveObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | endpoint | EndpointObject | N | Structure de l'endpoint de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ----------------------------------------------------------------------------------------------------- | | name | string | N | Nom de la requête. Paramètres optionnels : UpdateDeviceStates : Mettre à jour les états des appareils | | message\_id | string | N | ID du message de la requête, UUID\_V4 | | version | string | N | Numéro de version du protocole de la requête. Actuellement fixé à 1. | EndpointObject | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | N | Numéro de série unique de l'appareil tiers | | tags | objet | N | Paires clé-valeur au format JSON, informations personnalisées de l'appareil. \[Fonction de gestion des appareils] - \[Description des tags] | PayloadObject : Selon différents `header.name`, il existe une structure de requête spécifique pour chacun. Exemple de requête : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", "tags": {} }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Format de la réponse** :::tips \*\*Code de statut HTTP : \*\*200 OK **Attribut de réponse HTTP：** ::: | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------- | ------------- | ----------------------------------- | | event | EventObject | N | Structure de l'événement de réponse | EventObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | N | Nom de l'en-tête de la réponse. Paramètre optionnel : UpdateDeviceStatesResponse : Réponse de mise à jour de l'état des appareils ErrorResponse : Réponse d'erreur | | message\_id | string | N | ID du message de l'en-tête de la réponse, UUID\_V4. Transmettre ici header.message\_id du message de la requête | | version | string | N | Numéro de version du protocole de la requête. Actuellement fixé à 1. | > Réponse réussie--PayloadObject： Selon le type de requête, la structure de la réponse est différente. Pour plus de détails, veuillez consulter le document d'instruction de la requête spécifique. > Réponse d'échec--PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ------------------- | | type | string | N | **Types d'erreur**: | * **ENDPOINT\_UNREACHABLE**: Le dispositif est inaccessible ou hors ligne * **ENDPOINT\_LOW\_POWER**: Le dispositif est en mode basse consommation et ne peut pas être contrôlé * **INVALID\_DIRECTIVE**: Directive anormale de la part de la passerelle * **NO\_SUCH\_ENDPOINT**: Le dispositif n'existe pas * **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**: Le mode actuel ne prend pas en charge l'opération * **INTERNAL\_ERROR**: Erreur interne du service * **REMOTE\_KEY\_CODE\_NOT\_LEARNED**: Code de touche de la télécommande non appris | :::astuces **Conditions**: Les paramètres de la requête sont légaux. \*\*Code d'état : \*\*200 OK **Paramètres de la réponse :** ::: ``` { "event": { "header": { "name": "UpdateDeviceStatesResponse", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } } ``` ``` { "event": { "header": { "name": "ErrorResponse", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "type": "ENDPOINT_UNREACHABLE" } } } ``` **UpdateDeviceStates** **Paramètres de la requête :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ----------------------------------------------------------------------------- | | state | objet | N | État de l'appareil, voir \[Supported device cabilities] pour plus de détails. | Exemple de requête : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": : { "power": { "powerState": "on" } } } } } ``` **Paramètres de la réponse :** PayloadObject：Objet vide Exemple de réponse réussie ``` { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } ``` **QueryDeviceStates** **Paramètres de la requête :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ----------------------------------------------------------------------------- | | state | objet | N | État de l'appareil, voir \[Supported device cabilities] pour plus de détails. | Exemple de requête : ```json { "directive": { "header": { "name": "QueryDeviceStates", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "state": { "power-consumption": { "timeRange": { "start": "2020-07-05T08:00:00Z", // Heure de début pour les statistiques de consommation d'énergie, requis. "end": "2020-07-05T09:00:00Z" // Heure de fin pour les statistiques de consommation d'énergie, requis. } } } } } } ``` **Paramètres de la réponse :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ----------------------------------------------------------------------------- | | state | objet | N | État de l'appareil, voir \[Supported device cabilities] pour plus de détails. | **Exemple de réponse :** ```json { "event": { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "payload": { "state": { "power-consumption": { "electricityIntervals": [ // Divisé en plusieurs enregistrements en fonction de configuration.resolution { "usage": 26.5, // Valeur de consommation d'énergie, requis. Type : number. "start": "2020-07-05T08:00:00Z", // Heure de début, requis. Type : date. "end": "2020-07-05T09:00:00Z" // Heure de fin, requis. Type : date. Si l'intervalle entre end et start est inférieur à resolution, tous les enregistrements signalés sont considérés invalides. }, { "usage": 26.5, // Valeur de consommation d'énergie, requis. Type : number. "start": "2020-07-05T09:00:00Z", // Heure de début, requis. Type : date. "end": "2020-07-05T10:00:00Z" // Heure de fin, requis. Type : date. Si l'intervalle entre end et start est inférieur à resolution, tous les enregistrements signalés sont considérés invalides. } ] } } } } } ``` **ConfigureDeviceCapabilities** **Paramètres de la requête :** PayloadObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | capabilities | CapabilityObject\[] | N | Liste des capacités. Les détails peuvent être consultés dans la section capacités d'appareil prises en charge. Remarque, le champ permission ne peut pas être modifié, transmettre la même valeur lors de la synchronisation. | Exemple de requête : ```json { "directive": { "header": { "name": "ConfigureDeviceCapabilities", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Type de détection de contrôle de la température, requis. Valeurs optionnelles : humidity (détection d'humidité), temperature (détection de température) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Paramètres de détection pris en charge, requis. { "name": "lowerSetpoint", // Valeur minimale que la détection doit maintenir. Soit lowerSetpoint soit upperSetpoint doit être fourni. "value": { // Plage de détection, optionnelle. Remplir s'il y a des conditions prédéfinies. "value": 68.0, // Valeur de température ou d'humidité, requis. "scale": "f" // Unité de température, requise si name=temperature. Options : c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valeur maximale que la détection doit maintenir. Soit lowerSetpoint soit upperSetpoint doit être fourni. "value": { // Plage de détection, optionnelle. Remplir s'il y a des conditions prédéfinies. "value": 68.0, // Valeur de température ou d'humidité, requis. "scale": "f" // Unité de température, requise si name=temperature. Options : c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } } ``` **Paramètres de la réponse :** PayloadObject：Objet vide Exemple de réponse réussie ```json { "event": { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "2" }, "payload": {} } } ``` ## 5. Événements envoyés par le serveur > Description de l'interface MDN EventSource： ### 5.1 Instruction La passerelle prend en charge l'envoi de messages au client via SSE (Server-sent events). Le client peut surveiller les messages SSE après avoir obtenu les informations d'accès et peut analyser le contenu des messages poussés selon le protocole de notification d'événement de l'interface de développement après réception des messages poussés par la passerelle. Il convient de noter que la passerelle utilise actuellement le protocole HTTP1.1, donc SSE côté navigateur sera limité à un maximum de 6 connexions (Les instructions spécifiques se trouvent dans la description de l'interface MDN EventSource.) ### 5.2 Format commun :::astuces * **URL**：/open-api/V2/sse/bridge * **Méthode**：`GET` ::: Paramètres de la requête : | Nom | Type | Optionnel | Description | | ------------- | ------ | --------- | ------------- | | access\_token | string | N | Jeton d'accès | Remarque : Lors de la demande d'une connexion SSE, la passerelle vérifiera l'access\_token, et renverra une erreur d'échec d'authentification s'il est invalide. { "error": 401, "data": {}, "message": "invalid access\_token"} > \## Par exemple : Nom du module : device Version : 1,v2,v3 Type de message : addDevice Exemple : ```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 Module Appareil #### a. Événement Ajouter l'appareil :::tips Nom du module：device Version：v2 Type de message：addDevice event.data paramètres： ::: | Nom | Type | Optionnel | Description | | ------- | ----------------------------------------------------------------------------------------- | --------- | --------------------------- | | payload | ResponseDeviceObjectObject - Interface identique à celle d'Obtenir la liste des appareils | N | informations sur l'appareil | Exemple : ```json // event.data { "payload": { "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "Monappareil", "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. Événement de mise à jour de l'état de l'appareil :::tips Nom du module：device Version：v2 Type de message：updateDeviceState event.data paramètres： ::: | Nom | Type | Optionnel | Description | | -------- | ------------------------------------------------- | --------- | ---------------------------- | | endpoint | EndpointObject | N | Informations sur l'appareil | | payload | objet。 Structure identique à l'état de l'appareil | N | Données d'état de l'appareil | EndpointObject : | Paramètre | Type | Optionnel | Description | | --------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | Y | Le numéro de série unique de l'appareil tiers. Pour les appareils connectés via des interfaces ouvertes, ce champ est requis. | Exemple : ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "power": { "powerState": "on" }, "brightness": { "brightness": 100 } } } ``` #### c. Événement de mise à jour des informations de l'appareil :::tips Nom du module：device Version：v2 Type de message：updateDeviceInfo event.data paramètres： ::: | Nom | Type | Optionnel | Description | | -------- | ------------------ | --------- | -------------------------------- | | endpoint | EndpointObject | N | Informations sur l'appareil | | payload | DeviceChangeObject | N | Données de changement d'appareil | EndpointObject : | Attribut | Type | Optionnel | Description | | --------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | Y | Le numéro de série unique de l'appareil tiers. Pour les appareils connectés via des interfaces ouvertes, ce champ est requis. | DeviceChangeObject | Nom | Type | Optionnel | Description | | ------------ | -------------------- | --------- | --------------------------------------------------------------------------------------------------------- | | name | string | N | Nom de l'appareil | | capabilities | CapabilityObject \[] | Y | Liste des capacités de l'appareil. | | tags | objet | Y | **tags**`objet` \| Nullable \| Paires clé-valeur JSON pour les informations personnalisées de l'appareil. | * Peut être utilisé pour stocker les canaux de l'appareil. * Peut être utilisé pour stocker les unités de température. * Pour d'autres données personnalisées tierces. | Exemple : ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "name": "nom de l'appareil", "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Type de détection de contrôle de la température, requis. Valeurs optionnelles : humidity (détection d'humidité), temperature (détection de température) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Paramètres de détection pris en charge, requis. { "name": "lowerSetpoint", // Valeur minimale que la détection doit maintenir. Soit lowerSetpoint soit upperSetpoint doit être fourni. "value": { // Plage de détection, optionnelle. Remplir s'il y a des conditions prédéfinies. "value": 68.0, // Valeur de température ou d'humidité, requis. "scale": "f" // Unité de température, requise si name=temperature. Options : c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valeur maximale que la détection doit maintenir. Soit lowerSetpoint soit upperSetpoint doit être fourni. "value": { // Plage de détection, optionnelle. Remplir s'il y a des conditions prédéfinies. "value": 68.0, // Valeur de température ou d'humidité, requis. "scale": "f" // Unité de température, requise si name=temperature. Options : c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } ``` #### d. Événement Supprimer l'appareil :::tips Nom du module：device Version：v2 Type de message：deleteDevice event.data paramètres： ::: | \*\* Nom \*\* | \*\* Type \*\* | \*\* Optionnel\*\* | \*\* Description \*\* | | ------------- | -------------- | ------------------ | --------------------------- | | endpoint | EndpointObject | N | Informations sur l'appareil | EndpointObject : | Attribut | Type | Optionnel | Description | | --------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | Y | Le numéro de série unique de l'appareil tiers. Pour les appareils connectés via des interfaces ouvertes, ce champ est requis. | Exemple : ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" } } ``` #### e. Événement de mise à jour de l'état en ligne de l'appareil :::tips Nom du module：device Version：v2 Type de message：updateDeviceOnline event.data paramètres： ::: | Nom | Type | Optionnel | Description | | -------- | ------------------ | --------- | -------------------------------- | | endpoint | EndpointObject | N | Informations sur l'appareil | | payload | DeviceChangeObject | N | Données de changement d'appareil | EndpointObject : | Attribut | Type | Optionnel | Description | | --------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numéro de série unique de l'appareil | | third\_serial\_number | string | Y | Le numéro de série unique de l'appareil tiers. Pour les appareils connectés via des interfaces ouvertes, ce champ est requis. | DeviceChangeObject | Nom | Type | Optionnel | Description | | -------- | ------- | --------- | --------------------------- | | en ligne | boolean | N | État en ligne de l'appareil | Exemple : ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": false } } ``` ### 5.4 Module Passerelle #### a. Événement de mise à jour de l'état de sécurité :::tips Nom du module：device Version：v2 Type de message：updateDeviceOnline event.data paramètres： ::: | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------------- | ------------- | --------------------------- | | payload | SecurityStateObject | N | Informations sur l'appareil | SecurityStateObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------- | | etat\_alarme | string | N | | * `armement` | Armé * `désarmement` | Désarmé | Exemple : ```json // event.data { "payload": { "alarm_state": "alarming" } } ``` ### 5.5 Module Sécurité #### a. Événement de mise à jour de l'état d'armement :::tips Nom du module：device Version：v2 Type de message：updateDeviceOnline event.data paramètres： ::: | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------------- | ------------- | ----------------------------------------- | | payload | ArmStateObject | N | informations d'armement et de désarmement | ArmStateObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------- | -------- | ------------- | --------------- | | etat\_armement | string | N | | * `armement` | Armé * `désarmement` | Désarmé | | détail | DetailObject | N | Détails d'armement/désarmement | DetailObject： | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------------- | | sid | int | N | id du mode de sécurité | | name | string | N | Nom de la sécurité | Exemple ```json // event.data { "payload": { "arm_state": "arming", "detail": { "sid": 1, "name": "Home Mode" } } } ``` ## 6. TTS (**Moteur de synthèse vocale (Text-to-Speech)** ### 6.1 Instructions #### Rôle clé * Fournisseur de service TTS : Le fournisseur du service moteur TTS est responsable de l'enregistrement du moteur TTS sur la passerelle et de la fourniture des services TTS * Serveur de passerelle：iHost * Client Open API de la passerelle #### 6.1.1 Enregistrement du service du moteur TTS 1. 【Fournisseur de service TTS】Appeler l'interface pour enregistrer le moteur TTS sur la passerelle. 2. 【Serveur de passerelle】Après un enregistrement réussi, la passerelle stockera les informations de base du moteur TTS (y compris l'adresse du service server\_address, et les communications ultérieures entre la passerelle et le fournisseur de service TTS se feront via l'adresse server\_address), et attribuera l'ID du service du moteur TTS au sein de la passerelle.
#### 6.1.2 Obtenir la liste des audios synthétisés 1. 【Client Open API de la passerelle】Appeler l'interface pour obtenir la liste des services de moteur TTS enregistrés. Vous pouvez obtenir la liste actuelle des moteurs TTS enregistrés (y compris l'ID du moteur TTS attribué par la passerelle). 2. 【Client Open API de la passerelle】Appeler l'interface pour obtenir la liste des audios d'un moteur TTS spécifié. La passerelle émettra une instruction synchrone de liste audio au fournisseur de service TTS spécifié et renverra le résultat.
#### 6.1.3 Synthèse vocale en spécifiant un moteur vocal 1. 【Client Open API de la passerelle】Appeler l'interface pour obtenir la liste des services de moteur TTS enregistrés. Vous pouvez obtenir la liste actuelle des moteurs TTS enregistrés (y compris l'ID du moteur TTS attribué par la passerelle). 2. 【Client Open API de la passerelle】Appeler l'interface pour obtenir la liste des audios d'un moteur TTS spécifié. La passerelle émettra une instruction synchrone de liste audio au fournisseur de service TTS spécifié et renverra le résultat.
#### 6.1.4 Synthétiser l'audio et lire la parole TTS. 1. 【Client Open API de la passerelle】Appeler l'interface pour obtenir la liste des services de moteur TTS enregistrés. Vous pouvez obtenir la liste actuelle des moteurs TTS enregistrés (y compris l'ID du moteur TTS attribué par la passerelle). 2. 【Client Open API de la passerelle】Appeler l'interface pour obtenir la liste des audios d'un moteur TTS spécifié. La passerelle émettra une instruction synchrone de liste audio au fournisseur de service TTS spécifié et renverra le résultat. (y compris l'adresse du fichier audio TTS) 3. 【Client Open API de la passerelle】Enregistrer l'adresse du fichier audio TTS à partir du résultat renvoyé à l'étape précédente, appeler l'interface de lecture du fichier audio et le lire via la passerelle. ### 6.2 Module du moteur TTS #### 6.2.1 Capacité ouverte de la passerelle **a. Obtenir la liste des services de moteurs TTS enregistrés** :::astuces * **URL**：`/open-api/V2/rest/tts/engines` * **Méthode**：`GET` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : aucun Réponse de données correcte : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ---------------- | ------------- | --------------------------------- | | engines | EngineObject \[] | N | Liste des moteurs TTS enregistrés | Structure de EngineObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------------------------------- | | id | string | N | ID du moteur attribué par la passerelle | | name | string | N | Nom du service du moteur TS | :::astuce Conditions : Les paramètres de requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*`200 OK` **Exemple de réponse :**： ::: ```json { "error": 0, "data": { "engines": [ { "id": "engine id", "name": "engine name" } ] }, "message": "success" } ``` **b. Obtenir la liste des audios d'un moteur TTS spécifié** :::astuces * **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list` * **Méthode**：`GET` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : aucun Réponse de données correcte : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | --------------- | ------------- | --------------- | | audio\_list | AudioObject \[] | N | Liste audio | Structure de AudioObject | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------------------------------------------------- | -------- | ------------- | ----------------------------------- | | url | string | N | URL du fichier audio, par exemple : | | | | | | | label | string | Y | Étiquette du fichier audio | :::astuce Conditions : Les paramètres de requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*`200 OK` \*\*Code d'erreur : \*\* * 190000 Le moteur fonctionne de manière anormale **Exemple de réponse :**： ::: ```json { "error": 0, "data": { "audio_list": [ { "url": "adresse audio tts", // par exemple : https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "étiquette audio tts" } ] }, "message": "success" } ``` **c. Effectuer la synthèse vocale en utilisant le moteur TTS spécifié** :::astuces * **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Texte utilisé pour synthétiser l'audio | | label | string | Y | Étiquette du fichier audio | | language | string | Y | Champ transparent. Code de langue optionnel pour la requête de synthèse vocale. La liste spécifique des codes de langue pris en charge est fournie par le fournisseur du service moteur TTS. Notez que le service du moteur TTS doit prendre en charge une langue par défaut pour la synthèse vocale, ce qui signifie que si la langue n'est pas transmise, la langue par défaut du moteur sera utilisée pour la synthèse. | | options | objet | Y | Champ transparent. Il est utilisé pour transmettre les paramètres de configuration requis pour la synthèse au service du moteur TTS. | Réponse de données correcte : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------- | ------------- | --------------- | | audio | AudioObject | N | Liste audio | Structure de AudioObject | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------------------------------------------------- | -------- | ------------- | ----------------------------------- | | url | string | N | URL du fichier audio, par exemple : | | | | | | | label | string | Y | Étiquette du fichier audio | :::astuce Conditions : Les paramètres de requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*`200 OK` \*\*Code d'erreur : \*\* * 190000 Le moteur fonctionne de manière anormale **Exemple de réponse :**： ::: ```json { "error": 0, "data": { "audio": { "url": "adresse audio tts" // par exemple, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "étiquette audio tts" } }, "message": "success" } ``` #### 6.2.2 Communication entre la passerelle et le service TTS **a. Enregistrement du service du moteur TTS** > Envoyer une requête à la passerelle par le fournisseur de service TTS :::astuces * **URL**：`/open-api/V2/rest/thirdparty/event` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------- | ------------- | --------------------------------------------------------------- | | event | EventObject | N | Structure des informations de l'objet d'événement de la requête | EventObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------------------------------- | | name | string | N | Nom de la requête. Paramètre optionnel. | * RegisterTTSEngine | | message\_id | string | N | ID du message de requête, UUID\_V4 | | version | string | N | Numéro de version du protocole de requête. Actuellement fixé à 1 | PayloadObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ---------------- | -------- | ------------- | ------------------------------------------ | | service\_address | string | N | Adresse du service. Par exemple, http\:/// | | name | string | N | Nom du service | Exemple de requête : ```json { "event": { "header": { "name": "RegisterTTSEngine", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "service_address": "service_address", "name": "nom du service tts" } } } ``` \*\*Paramètres de réponse corrects : \*\* | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | -------------------------------------------------- | | name | string | N | Nom de l'en-tête de réponse. Paramètre optionnel : | * Réponse (Réponse réussie) * ErrorResponse (Réponse d'erreur) | | message\_id | string | N | ID du message d'en-tête de réponse, UUID\_V4. Requête entrante ici : header.message\_id | | version | string | N | Numéro de version du protocole de requête. Actuellement fixé à 1 | PayloadObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------------------------------- | | engine\_id | string | N | ID du moteur attribué par la passerelle | :::astuce Conditions : Les paramètres de requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*`200 OK` **Exemple de réponse :**： ::: Exemple de réponse correcte ： ```json { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "engine_id": "engine id" } } ``` \*\*Paramètres de réponse anormaux : \*\* | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------- | | type | string | N | Type d'erreur | * INVALID\_PARAMETERS (Erreur de paramètres) * AUTH\_FAILURE (Échec d'authentification) * INTERNAL\_ERROR (Erreur interne du service) | | description | string | N | Description de l'erreur | Exemple de réponse d'erreur ： ```json { "header": { "name": "ErrorResponse", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address ne peut pas être vide" } } ``` **b. Commande de synchronisation de la liste audio** > Envoyer une commande au fournisseur de service TTS par la passerelle. :::astuces * **URL**：`` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | --------------- | ------------- | ------------------------------------------------------ | | directive | DirectiveObject | N | Informations sur la structure de l'objet d'instruction | DirectiveObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------------------------------- | | name | string | N | Nom de la requête. Paramètre optionnel : | * SyncTTSAudioList | | message\_id | string | N | ID du message de requête, UUID\_V4 | | version | string | N | Numéro de version du protocole de requête. Actuellement fixé à 1 | Exemple de requête : ```json { "directive": { "header": { "name": "SyncTTSAudioList", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": {} } } ``` \*\*Paramètres de réponse corrects : \*\* | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | -------------------------------------------------- | | name | string | N | Nom de l'en-tête de réponse. Paramètre optionnel : | * Réponse (Réponse réussie) * ErrorResponse (Réponse d'erreur) | | message\_id | string | N | ID du message d'en-tête de réponse, UUID\_V4. Requête entrante ici : header.message\_id | | version | string | N | Numéro de version du protocole de requête. Actuellement fixé à 1 | PayloadObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | --------------- | ------------- | --------------- | | audio\_list | AudioObject \[] | N | Liste audio TTS | Structure de AudioObject | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------------------------------------------------- | -------- | ------------- | ----------------------------------- | | url | string | N | URL du fichier audio, par exemple : | | | | | | | label | string | Y | Étiquette du fichier audio | :::astuce Conditions : Les paramètres de requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*`200 OK` **Exemple de réponse :**： ::: Exemple de réponse correcte ： ```json { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "audio_list": [ { "url": "url audio tts", "label": "étiquette audio tts" } ] } } ``` \*\*Paramètres de réponse anormaux : \*\* | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------- | | type | string | N | Type d'erreur | * INVALID\_PARAMETERS (Erreur de paramètres) * AUTH\_FAILURE (Échec d'authentification) * INTERNAL\_ERROR (Erreur interne du service) | | description | string | N | Description de l'erreur | Exemple de réponse d'erreur ： ```json { "header": { "name": "ErrorResponse", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address ne peut pas être vide" } } ``` **c. Commande de synthèse vocale** > Envoyer une commande au fournisseur de service TTS par la passerelle. :::astuces * **URL**：`` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | --------------- | ------------- | ------------------------------------------------------ | | directive | DirectiveObject | N | Informations sur la structure de l'objet d'instruction | DirectiveObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------------------------------- | | name | string | N | Nom de la requête. Paramètre optionnel : | * SynthesizeSpeech | | message\_id | string | N | ID du message de requête : UUID\_V4 | | version | string | N | Numéro de version du protocole de requête. Actuellement fixé à 1 | PayloadObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Texte utilisé pour synthétiser l'audio | | label | string | Y | Étiquette du fichier audio | | language | string | Y | Champ transparent. Code de langue optionnel pour la requête de synthèse vocale. La liste spécifique des codes de langue pris en charge est fournie par le fournisseur du service moteur TTS. Notez que le service du moteur TTS doit prendre en charge une langue par défaut pour la synthèse vocale, ce qui signifie que si la langue n'est pas transmise, la langue par défaut du moteur sera utilisée pour la synthèse. | | options | objet | Y | Champ transparent. Il est utilisé pour transmettre les paramètres de configuration requis pour la synthèse au service du moteur TTS. | Exemple de requête : ```json { "directive": { "header": { "name": "SynthesizeSpeech", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "text": "Texte d'entrée à synthétiser.", "label": "étiquette audio tts" } } } ``` \*\*Paramètres de réponse corrects : \*\* | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------------------------------ | | header | HeaderObject | N | Structure de l'en-tête de la requête | | payload | PayloadObject | N | Structure de la charge utile de la requête | HeaderObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | -------------------------------------------------- | | name | string | N | Nom de l'en-tête de réponse. Paramètre optionnel : | * Réponse (Réponse réussie) * ErrorResponse (Réponse d'erreur) | | message\_id | string | N | ID du message d'en-tête de réponse, UUID\_V4. Requête entrante ici : header.message\_id | | version | string | N | Numéro de version du protocole de requête. Actuellement fixé à 1 | PayloadObject | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ----------- | ------------- | --------------- | | audio | AudioObject | N | Audio TTS | Structure de AudioObject | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------------------------------------------------- | -------- | ------------- | ----------------------------------- | | url | string | N | URL du fichier audio, par exemple : | | | | | | | label | string | Y | Étiquette du fichier audio | :::astuce Conditions : Les paramètres de requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*`200 OK` **Exemple de réponse :**： ::: Exemple de réponse correcte ： ```json { "header": { "name": "Response", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "audio": { "url": "url audio tts", "label": "étiquette audio tts" } } } ``` \*\*Paramètres de réponse anormaux : \*\* | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------- | | type | string | N | Type d'erreur | * INVALID\_PARAMETERS (Erreur de paramètres) * AUTH\_FAILURE (Échec d'authentification) * INTERNAL\_ERROR (Erreur interne du service) | | description | string | N | Description de l'erreur | Exemple de réponse d'erreur ： ```json { "header": { "name": "ErrorResponse", "message_id": "Identifiant unique, de préférence un UUID v4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address ne peut pas être vide" } } ``` ## 7. Module multimédia ### 7.1 Lire un fichier audio :::astuces * **URL**：`/open-api/V2/rest/media/audio-player` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ---------------------- | | audio\_url | string | N | Adresse URL de l'audio | Réponse de données correcte : :::astuce Conditions : Les paramètres de requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\*`200 OK` **Exemple de réponse :**： ::: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 8. Carte d'interface utilisateur personnalisée Les cartes UI personnalisées vous permettent d'afficher tout contenu souhaité à l'intérieur de la carte. Ce contenu peut être une page web, une image ou tout service disposant d'une interface utilisateur. Il suffit de fournir l'URL du contenu que vous souhaitez afficher. La carte UI adaptera automatiquement sa largeur et sa hauteur, et le contenu sera rendu à l'aide d'une iFrame. ### 8.1 Instructions #### Rôle clé * **Fournisseur de service UI** : Le fournisseur responsable de la création des cartes UI personnalisées sur la passerelle. * **Serveur de passerelle** : Le serveur de passerelle (iHost). * **Client Open API de la passerelle** : Le client Open API pour la passerelle. #### 8.1.1 Création d'une carte UI personnalisée * **\[Fournisseur de service UI]** : Appelle l'API pour créer une carte UI personnalisée sur la passerelle. * **\[Serveur de passerelle]** : Après un enregistrement réussi, la passerelle stocke les informations de base de la carte UI (y compris la configuration de taille et l'URL de la ressource de la carte) et attribue un ID interne de carte UI au sein de la passerelle.
#### 8.1.2 Récupération de la liste des cartes UI * **\[Fournisseur de service UI]** : Appelle l'API pour récupérer la liste des cartes UI. * **\[Serveur de passerelle]** : Renvoie la liste des cartes UI stockées sur la passerelle, y compris les cartes UI personnalisées non créées par l'appelant.
#### 8.1.3 Modification de la configuration d'une carte UI spécifiée * **\[Fournisseur de service UI]** : Appelle l'API pour modifier la configuration d'une carte UI spécifiée, telle que la configuration de taille et l'URL de la ressource. * **\[Serveur de passerelle]** : Après une modification réussie, la passerelle stocke les informations mises à jour de la carte UI, y compris la nouvelle configuration de taille et l'URL de la ressource.
#### 8.1.4 Suppression d'une carte UI personnalisée 1. **\[Fournisseur de service UI]** : Appelle l'API pour supprimer une carte UI personnalisée spécifiée. 2. **\[Serveur de passerelle]** : La passerelle supprimera toutes les informations liées à la carte UI spécifiée.
### 8.2 Module de carte UI personnalisée #### 8.2.1 Création d'une carte UI personnalisée > Le fournisseur de service UI envoie une requête à la passerelle pour créer une carte UI personnalisée. :::astuces * **URL**：`/open-api/v2/rest/ui/cards` * **Méthode**：`POST` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------- | ------------------ | ------------- | ---------------------------------------------------------------------------------- | | label | string | Y | Étiquette de la carte : Utilisée pour décrire la carte. C'est l'alias de la carte. | | cast\_settings | CastSettingsObject | Y | Paramètres de la carte Cast : Paramètres de configuration pour les cartes Cast. | | web\_settings | WebSettingsObject | N | Paramètres de la carte Web : Paramètres de configuration pour les cartes Web. | CastSettingsObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configuration de taille : Doit inclure au moins une configuration. | | défaut | string | N | Spécification par défaut : La spécification de taille par défaut est utilisée, avec des paramètres optionnels : 2x2 | WebSettingsObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | ----------------- | ------------------- | ------------- | ------------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Configuration de taille : Doit inclure au moins une configuration. | | drawer\_component | DrawerObject | Y | Paramètres d'affichage du composant tiroir. | | défaut | string | N | Spécification par défaut : | * 1x1 * 2x1 | DimensionObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------------------------------- | -------- | ------------- | --------------------------------------------------------- | | src | string | N | URL de la ressource : Par exemple : | | size | string | N | Spécifications de taille : | | Paramètres optionnels de CastSettingsObject : | | | | * 2×2 Paramètres optionnels de WebSettingsObject : * 1x1 * 2x1 | DrawerObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------------------------------------------------- | | src | string | N | URL de la ressource : Par exemple : | Réponse de données réussie : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | ------------------------ | | id | string | N | ID unique de la carte UI | :::astuces **Conditions**: Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. \*\*Code d'état : \*\* `200 OK` ::: Exemple de requête： ```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" } } ``` Exemple de réponse : ```json { "error": 0, "data": { "id": "72cc5a4a-f486-4287-857f-b482d7818b16" }, "message": "success" } ``` #### 8.2.2 Récupérer la liste des cartes UI :::astuces * **URL**：`/open-api/v2/rest/ui/cards` * **Méthode**：`GET` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : Aucun Paramètres de réponse : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | ------------- | ------------- | ------------------- | | data | CardObject\[] | N | Liste des cartes UI | Objet CardObjec : | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------- | ------------------ | ------------- | -------------------------------------------------------------------------------------------------- | | id | string | N | ID de la carte : Un identifiant unique pour la carte. | | label | string | Y | Étiquette de la carte : Utilisée pour décrire la carte. Elle sert d'alias ou de nom pour la carte. | | cast\_settings | CastSettingsObject | Y | Étiquette de la carte : Utilisée pour décrire la carte. C'est l'alias de la carte. | | web\_settings | WebSettingsObject | N | Paramètres de la carte Cast : Paramètres de configuration pour les cartes Cast. | | app\_name | string | Y | Paramètres de la carte Web : Paramètres de configuration pour les cartes Web. | CastSettingsObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------------------- | ------------------- | ------------- | ------------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Configuration de taille : Doit inclure au moins une configuration. | | défaut | string | N | Spécification par défaut : | | Paramètre optionnel : 2x2 | | | | | utilisé | string | N | Spécification actuelle : | | Paramètre optionnel : 2x2 | | | | WebSettingsObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | ------------------- | ------------- | ------------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Configuration de taille : Doit inclure au moins une configuration. | | drawer\_component | DrawerObject | Y | Paramètres d'affichage du composant tiroir. | | défaut | string | N | Spécification par défaut : | | Paramètre optionnel : | | | | * 1x1 * 2x1 | | utilisé | string | N | Spécification actuelle : Paramètre optionnel : * 1x1 * 2x1 | DimensionObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | -------- | ------------- | --------------------------------------------------------- | | src | string | N | URL de la ressource : Par exemple : | | size | string | N | Spécifications de taille : | | Paramètre optionnel : | | | | * 1x1 * 2x1 **Remarque** : Actuellement, les cartes Cast ne prennent en charge que la spécification 2x2. La spécification 2x2 ne sera pas effective. | DrawerObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | ------------ | -------- | ------------- | --------------------------------------------------------- | | src | string | N | URL de la ressource : Par exemple : | Exemple de réponse : ```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 Modifier la configuration d'une carte UI spécifiée > Les utilisateurs autorisés sont autorisés à modifier la configuration d'une carte UI existante via cette interface. Les fournisseurs de services de cartes personnalisées ne peuvent modifier que les cartes UI qu'ils ont créées. :::astuces * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Méthode**：`PUT` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : | **Attribut** | **Type** | **Optionnel** | **Description** | | -------------- | ------------------ | ------------- | --------------------------------------------------------- | | label | string | Y | Utilisé pour décrire la carte. C'est l'alias de la carte. | | cast\_settings | CastSettingsObject | Y | Paramètres de la carte Cast | | web\_settings | WebSettingsObject | Y | Paramètres de la carte Web | CastSettingsObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------ | ------------------------ | | utilisé | string | Y, L'un ou l'autre `utilisé` ou `src` doit être fourni, mais au moins un de ces paramètres est requis. | Spécification actuelle : | | Paramètre optionnel : | | | | * 2x2 \| | src | string | Y, L'un ou l'autre `utilisé` ou `src` doit être fourni, mais au moins un de ces paramètres est requis. | URL de la ressource : | WebSettingsObject : | **Attribut** | **Type** | **Optionnel** | **Description** | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------ | ------------------------ | | utilisé | string | Y, L'un ou l'autre `utilisé` ou `src` doit être fourni, mais au moins un de ces paramètres est requis. | Spécification actuelle : | | Paramètre optionnel : | | | | * 1x1 * 2x1 | | src | string | Y, L'un ou l'autre `utilisé` ou `src` doit être fourni, mais au moins un de ces paramètres est requis. | URL de la ressource : | Réponse de données réussie : :::tips **Conditions** : Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. La carte UI modifiée doit avoir été créée par le fournisseur de carte UI personnalisée appelant l'interface. \*\*Code d'état : \*\* `200 OK` **Code d'erreur :** * **406** : Pas d'autorisation pour accéder à cette ressource ::: \*\*Exemple de réponse : \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` \*\*Exemple de requête : \*\* ```json { "cast_settings": { "used": "2×2" }, "web_settings": { "used": "1×1" } } ``` #### 8.2.4 Supprimer une carte UI personnalisée > Les utilisateurs autorisés sont autorisés à supprimer une carte UI existante en utilisant cette interface. Les fournisseurs de cartes personnalisées ne peuvent supprimer que les cartes UI qu'ils ont créées. :::astuces * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Méthode**：`DELETE` * **En-tête**： * Content-Type: application/json * Autorisation : Bearer ::: Paramètres de la requête : Aucun Réponse de données réussie : :::astuce **Conditions** : Les paramètres de la requête sont légaux et la vérification d'identité de l'utilisateur est passée. La carte UI modifiée doit avoir été créée par le fournisseur de carte UI personnalisée appelant l'interface. \*\*Code d'état : \*\* `200 OK` **Code d'erreur :** * **406** : Pas d'autorisation pour accéder à cette ressource. ::: \*\*Exemple de réponse : \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cube.ewelink.cc/cube-os-fr/ressources/guide-du-developpeur-et-de-lapi.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.