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.

// Requête
curl --location --request GET 'http://<adresse ip>/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.

// Requête
curl --location --request GET 'http://<adresse ip>/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.

// Requête
curl --location --request GET 'http://<adresse ip>/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/<module de fonction spécifique>

// 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

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

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

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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 :::

{
  "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:

{
  "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://<username>:<password>@<hostname>:<port>/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 :<schema>://<hostname>:<port>/<username>:<password>@<service_path>
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 <username> et <password> 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"
}

import axios from 'axios';

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

(async function main() {
  // allumer l'appareil
  await axios({
    url: `http://<nom de domaine ou adresse ip>/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:

{
  "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."

import axios from 'axios';

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

(async function main() {
  // allumer l'appareil
  await axios({
    url: `http://<nom de domaine ou adresse ip>/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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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  <token>
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  <token>
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：<adresse de service>
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  <token>
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 http://192.168.31.14/service_address

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 :

{
  "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 :

{
  "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 :

{
  "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 :

{
  "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 :

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

{
  "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：https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

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 :

const evtSource = new EventSource("http://<nom de domaine ou adresse ip>/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 :

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

// 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	tagsobjet | 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 :

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

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

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

// 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

// 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 :： :::

{
  "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 :
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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 :： :::

{
  "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 :
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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 :： :::

{
  "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 :

{
  "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 ：

{
    "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 ：

{
  "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：<adresse du service>

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

{
  "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 :
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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 ：

{
    "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 ：

{
  "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：<adresse du service>

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

{
    "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 :
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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 ：

{
    "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 ：

{
  "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 :： :::

{
  "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 : http://example.html
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 : http://example.html

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：

{
  "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 :

{
  "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 : http://example.html
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 : http://example.html

Exemple de réponse :

{
  "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 : http://example.html |

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 : http://example.html |

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

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

**Exemple de requête : **

{
  "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 : **

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