Guide développeur et API

1. Commencer à utiliser

1.1 Préparation

Étape 1. Veuillez vous assurer que la passerelle est sous tension et fonctionne correctement.

Étape 2. Assurez-vous que la passerelle et le PC sont connectés au même LAN. 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 avoir appuyé, l'accès à l'interface est valide 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": "bouton de liaison non appuyé" 
}

• Cliquez <Terminé> et appelez à nouveau l'interface [Access Token]. La réponse réussit 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": "succès"
}

• 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": "succès"
}

• Méthode d'obtention du token d'accès CUBE : Après avoir appelé l'interface [Access Token], une boîte de dialogue contextuelle globale de la page console Web CUBE invite l'utilisateur à confirmer l'obtention des informations d'identification d'appel de l'interface.

• Remarque : Si vous ouvrez plus d'une page de console Web CUBE, la boîte de confirmation contextuelle apparaîtra sur plusieurs pages de console Web simultanément, et la boîte contextuelle des autres pages sera fermée après avoir cliqué sur la confirmation sur l'une des pages.

2. Concept principal

2.1 Adresse de l'interface de développement

L'interface Web API de la passerelle dispose de 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 fonctionnel 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 est utilisée pour identifier des catégories spécifiques (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 est utilisée pour décrire les sous-fonctions spécifiques de l'appareil. Par exemple le contrôle de l'alimentation, le contrôle de la 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 globalement unique et de type chaîne. Plusieurs mots en anglais doivent être séparés par des traits d'union ("-"). Par exemple : "thermostat-target-setpoint".

  • name : Décrit la catégorie sous la capacité, également de type chaîne. Plusieurs mots en anglais doivent être séparés par des traits d'union ("-"). Par exemple : "auto-mode", "manual-mode".

  • permission : Décrit les autorisations associées à la capacité. Le type est string, formaté en code binaire 8421. Des exemples incluent :

    • Appareil contrôlable : "1000"

    • Appareil configurable : "0010"

    • Appareil contrôlable et configurable : "1010"

    • Appareil contrôlable et rapportable : "1100"

La signification de chaque bit, de droite à gauche, est la suivante : ⅰ. Bit 0 : Autorise la requête de l'appareil ⅱ. Bit 1 : Autorise la configuration de l'appareil ⅲ. Bit 2 : Autorise l'appareil à rapporter des données ⅳ. Bit 3 : Autorise le contrôle de 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 en 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 sont énoncées dans le tableau ci-dessous.

Attribut	Type	Optionnel	Description
permission	string	N	Décrit les autorisations pour l'élément de configuration.
Valeurs optionnelles :

• Autoriser la modification de cet élément de configuration : "10"

• Autoriser la visualisation de cet élément de configuration : "01"

• Autoriser à la fois la modification et la visualisation de cet élément de configuration : "11"

Explication des bits :

1. Bit 0 : Autorise la visualisation de cet élément de configuration

2. Bit 1 : Autorise 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 (décrivant la valeur de l'élément de configuration) est requis si permission autorise la modification ("10" ou "11").

   • Le défaut (décrivant la valeur par défaut de l'élément de configuration) et values (décrivant les valeurs sélectionnables pour l'élément de configuration) les champs sont optionnels.

2. Lorsque **type = numeric**:

   • Le champ le champ est requis si permission autorise 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 de pas 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 le champ est requis si permission autorise la modification ("10" ou "11").

   • Le défaut le champ est optionnel.

4. Lorsque **type = boolean**:

   • Le champ le champ est requis si permission autorise la modification ("10" ou "11").

   • Le défaut le champ est optionnel.

5. Lorsque **type = string**:

   • Le champ le champ est requis si permission autorise 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ée

Type	Description
string	Type de données string. Encodé en UTF8.
number	Type de données nombre. format binaire IEEE 754 double précision 64 bits
int	Type de données entier.
object	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 réponse

Attribut	Type	Optionnel	Description
error	int	N	Code d'erreur :
0 : Succès
400 : Erreur de paramètre
401 : Échec d'authentification
500 : Exception serveur
data	object	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": "succès"
}

{
  "error": 400,
  "data": {},
  "message": "paramètres invalides"
}

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) | | Prise en charge des deep | - bootComplete (Démarrage du système terminé)

• networkConnected (Réseau connecté)

• networkDisconnected (Réseau déconnecté)

• systemShutdown (Arrêt 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'accéder au token.

• Remarque : Le token sera effacé après la réinitialisation de l'appareil.

• Remarque : Après avoir obtenu le 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 token d'accès de l'interface. Il est valide pendant 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 le délai de validité. **Code d'état : **200 OK ::: Exemple de réponse:

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

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 le délai de validité a expiré. **Code d'état : ** 200 OK ::: Exemple de réponse:

{
  "error": 401,
  "data": {},
  "message": "bouton de liaison non appuyé" 
}

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 CPU :
Optionnel
valeurs :'c', 'f'
sd_card_used	int	Y	Utilisation de la carte SD (pourcentage) :
Plage :[0-100] avec une précision d'une décimale
*Remarque : Si la carte SD n'est pas insérée ou non formatée, la valeur est vide.

:::astuces Conditions : Les paramètres de la requête sont légaux et la vérification de l'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": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

d. Obtenir les infos de la passerelle

Permet aux utilisateurs autorisés d'obtenir les infos 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": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

f. Réactiver le son de la passerelle

Permet aux utilisateurs autorisés de réactiver le son 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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

g. Annuler l'alarme de la passerelle

Permet aux utilisateurs autorisés de désactiver l'état sonore 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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK :::

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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 une fois le temps écoulé. Unité : seconde. [0,1799]

BeepObject

Attribut	Type	Optionnel	Description
name	string	N	Le nom du deep. Les valeurs prises en charge peuvent être consultées dans [Resource List - Supported deep]
volume	int	N	Le volume du 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 de l'identité de l'utilisateur est passée. **Code d'état : ** 200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

3.3 Fonction de gestion des appareils

a. Types d'appareils pris en charge

Type d'appareil	Valeur	Version iHost
Prise	plug	≥ 2.1.0
Interrupteur	switch	≥ 2.1.0
Lumière	light	≥ 2.1.0
Rideau	curtain	≥ 2.1.0
Capteur de 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
Ventilateur avec lumière	fanLight	≥ 2.1.0
Climatiseur	airConditioner	≥ 2.1.0
Ventilateur	fan	≥ 2.1.0
Thermostat	thermostat	≥ 2.1.0

b. Capacités prises en charge par l'appareil

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 marche/arrêt. Requis. **Type :** string. "on" indique marche, "off" indique arrêt, "toggle" indique basculement.
}

Protocole (Requête d'état & instructions de contrôle) :

Allumer :

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

Éteindre :

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

Commutateur 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 :** String. 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 du basculement de l'attribut {name} de {device_id}. Requis. **Type :** String. "on" signifie activé, "off" signifie désactivé, "toggle" signifie basculer.
}

Protocole (Requête d'état & instructions de contrôle) :

Format du 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, // Indique si la fonction inching est activée. **Type :** Boolean. Requis.
              "inchingSwitch": "off", // Réglage de l'interrupteur inching. **Type :** String. Requis. "off" (arrêt), "on" (marche)
              "delay": 1000, // Temps de temporisation inching en millisecondes. **Type :** Integer. Requis.
              "min_delay": 500, // Temps de temporisation minimum
              "max_delay": 100000 // Temps de temporisation maximum
            },
            "2": { // Nom du composant
              "enable": true, // Indique si la fonction inching est activée. **Type :** Boolean. Requis.
              "inchingSwitch": "off", // Réglage de l'interrupteur inching. **Type :** String. Requis. "off" (arrêt), "on" (marche)
              "delay": 1000, // Temps de temporisation inching en millisecondes. **Type :** Integer. Requis.
              "min_delay": 500, // Temps de temporisation minimum
              "max_delay": 100000 // Temps de temporisation maximum
            },
            "3": { // Nom du composant
              "enable": true, // Indique si la fonction inching est activée. **Type :** Boolean. Requis.
              "inchingSwitch": "off", // Réglage de l'interrupteur inching. **Type :** String. Requis. "off" (arrêt), "on" (marche)
              "delay": 1000, // Temps de temporisation inching en millisecondes. **Type :** Integer. Requis.
              "min_delay": 500, // Temps de temporisation minimum
              "max_delay": 100000 // Temps de temporisation maximum
            },
            "4": { // Nom du composant
              "enable": true, // Indique si la fonction inching est activée. **Type :** Boolean. Requis.
              "inchingSwitch": "off", // Réglage de l'interrupteur inching. **Type :** String. Requis. "off" (arrêt), "on" (marche)
              "delay": 1000, // Temps de temporisation inching en millisecondes. **Type :** Integer. Requis.
              "min_delay": 500, // Temps de temporisation minimum
              "max_delay": 100000 // Temps de temporisation maximum
            }
          }
        }
      }
    }
  }
]

Attribut d'état

Aucun

Protocole (Requête d'état & 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 :** Number. Plage : 0-100.
}

Protocole (Requête d'état & instructions de contrôle) :

Définir la luminosité à 80 %. (0 est le plus sombre et 100 le plus lumineux.)

json
复制代码
{
  "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 :** Number. Plage : 0-100. 0 indique lumière chaude, 50 indique lumière neutre, 100 indique lumière froide.
}

Protocole (Requête d'état & 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 couleur RGB. Requis. **Type :** Number. Plage : 0-255.
  "green": 0, // Le champ green représente la composante verte dans l'espace couleur RGB. Requis. **Type :** Number. Plage : 0-255.
  "blue": 255 // Le champ blue représente la composante bleue dans l'espace couleur RGB. Requis. **Type :** Number. Plage : 0-255.
}

Protocole (Requête d'état & instructions de contrôle) :

Définir 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 :** Number. Plage : 0-100.
}

Protocole (Requête d'état & 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 :** String. Valeurs possibles : "open" (ouvert), "close" (fermé), "stop" (arrêt), "lock" (verrouiller).
}

Protocole (Requête d'état & 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 :** Boolean. true indique avant, false indique arrière.
}

Protocole (Requête d'état & 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 le statut de calibration du moteur. Requis. **Type :** String. "normal" indique mode normal (calibré), "calibration" indique calibration en cours.
}

Protocole (Rapport d'état) :

Rapporter 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 :** String. Requis. Valeurs optionnelles : "on" (allumé), "stay" (maintenir l'alimentation), "off" (éteint), "toggle" (inverser l'état d'alimentation).
}

Protocole (Requête d'état & instructions de contrôle) :

Définir l'état d'alimentation sur Toujours Allumé :

{
  "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 rapporte activement les résultats de reconnaissance ou est activé.
}

Protocole (Rapport d'état & instructions de contrôle) :

Définir le temps d'activation de réveil :

{
  "identify": {
    "countdown": 180 // Le champ countdown indique le temps de décompte. Requis. **Type :** Number. Unité : secondes.
  }
}

Rapporter l'état d'activation :

{
  "identify": {
    "identify": true // Indique si l'appareil rapporte activement les résultats de reconnaissance ou est activé.
  }
}

Interrupteur de 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 :** Boolean. Requis.
  "timeRange": { // Plage de temps résumée. Requise.
    "start": "2020-07-05T08:00:00Z", // Heure de début des statistiques de consommation d'énergie. **Type :** String. Requis.
    "end": "2020-07-05T09:00:00Z" // Heure de fin des statistiques de consommation d'énergie. **Type :** String. Requis.
  }
}

Interroger la consommation d'énergie par plage horaire :

{
  "type": "summarize", // Type de statistiques. **Type :** String. Requis. Valeurs optionnelles : "rlSummarize" (résumé en temps réel), "summarize" (résumé courant).
  "timeRange": { // Plage de temps résumée. Requise si type = "summarize".
    "start": "2020-07-05T08:00:00Z", // Heure de début des statistiques de consommation d'énergie. **Type :** String. Requis.
    "end": "2020-07-05T09:00:00Z" // Heure de fin des statistiques de consommation d'énergie. **Type :** String. Optionnel. Si omis, indique l'heure actuelle.
  }
}

Répondre avec le résultat des statistiques dans la plage de temps :

json
 
{
  "type": "summarize", // Type de statistiques. **Type :** String. Requis. Valeurs optionnelles : "rlSummarize" (résumé en temps réel), "summarize" (résumé courant).
  "rlSummarize": 50.0, // Consommation d'énergie totale. **Type :** Number. Unité : 0.01 kWh. Optionnel.
  "electricityIntervals": [ // Plusieurs enregistrements statistiques divisés selon configuration.resolution. Optionnel. Non présent quand type = "rlSummarize".
    {
      "usage": 26.5, // Consommation d'énergie. **Type :** Number. 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 rapportés sont considérés invalides.
    },
    {
      "usage": 26.5, // Consommation d'énergie. **Type :** Number. 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 rapportés sont considérés invalides.
    }
  ]
}

Protocole (Rapport d'état & 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 de contrôle de température. **Type :** String. 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 l'un de lowerSetpoint ou upperSetpoint est requis.
            "value": { // Plage de détection. Optionnel. Spécifier si des conditions prédéfinies existent.
              "value": 68.0, // Valeur de température. **Type :** Number. Requis.
              "scale": "f" // Unité de température. Requis quand 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 l'un de lowerSetpoint ou upperSetpoint est requis.
            "value": { // Plage de détection. Optionnel. Spécifier si des conditions prédéfinies existent.
              "value": 68.0, // Valeur de température. **Type :** Number. Requis.
              "scale": "f" // Unité de température. Requis quand 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 de contrôle de température. **Type :** String. 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 l'un de lowerSetpoint ou upperSetpoint est requis.
            "value": { // Plage de détection. Optionnel. Spécifier si des conditions prédéfinies existent.
              "value": 68.0, // Valeur d'humidité. **Type :** Number. Requis
            }
          },
          {
            "name": "upperSetpoint", // La valeur détectée doit être en dessous de ce point de consigne. Au moins l'un de lowerSetpoint ou upperSetpoint est requis.
            "value": { // Plage de détection. Optionnel. Spécifier si des conditions prédéfinies existent.
              "value": 68.0, // Valeur d'humidité. **Type :** Number. 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 (Requête d'état & instructions de contrôle) :

Format :

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

Exemple :

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

Mode 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 :** String. Valeurs optionnelles : "MANUAL", "AUTO", "ECO".
}

Protocole (Requête d'état & instructions de contrôle) :

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

Statut 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" // Statut de récupération adaptative du thermostat
}

Attributs (État) :

{
  "adaptiveRecoveryStatus": "HEATING" // Statut de récupération adaptative du thermostat. **Type :** String. Valeurs optionnelles : "HEATING", "INACTIVE".
}

Protocole (Requête d'état & 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 :** number.
            "lowerSetpoint": 20 // Température cible minimale. **Type :** number.
          },
          {
            "startTimeInMinutes": 900, // Heure de début en minutes. Ex. : 15:00 = 900 minutes.
            "upperSetpoint": 26.5, // Température cible maximale. **Type :** number.
            "lowerSetpoint": 21 // Température cible minimale. **Type :** number.
          }
        ],
          "Tuesday": [...
          ],
          "Wednesday": [...
          ],
          "Thursday": [...
          ],
          "Friday": [...
          ],
          "Saturday": [...
          ],
          "Sunday": [...
          ],
        }
      }
    }
  }
]

Attributs (État) :

{
  "targetSetpoint": 30 // Température cible pour le mode spécifié. **Type :** number, dans l'unité spécifiée par temperatureUnit.
}

Protocole (Requête d'état & 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 la détection. **Type :** Boolean. `true` indique détection, `false` indique absence de détection.
}

Protocole (Requête d'état & 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 température. **Type :** number.
    },
    "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
复制代码
{
  "temperature": 26.5 // Température actuelle. **Type :** Number, en Celsius.
}

Protocole (Requête d'état & 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 :** Number, plage 0-100.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection de la batterie (battery)

Exemple de déclaration de capacité :

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

Attributs (État) :

{
  "battery": 95 // Pourcentage de batterie restant. **Type :** Number, plage -1 à 100. Remarque : -1 indique niveau de batterie inconnu.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection d'un bouton unique (press)

Exemple de déclaration de capacité :

{
  "capability": "press",
  "permission": "1100",
  "settings": { // Optionnel
    "actions": { // Actions du bouton, optionnel.
      "type": "enum",
      "permission": "01",
      "values": [ // Actions de 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 :** String. Valeurs standard : "singlePress" (appui simple ou court), "doublePress" (double appui), "longPress" (appui long).
}

Protocole (Requête d'état & 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 :** String. Seuls les caractères alphanumériques sont autorisés.
  "settings": { // Optionnel
    "actions": { // Actions du bouton, optionnel.
      "type": "enum",
      "permission": "01",
      "values": [ // Actions de 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 :** String. Valeurs standard : "singlePress" (appui simple ou court), "doublePress" (double appui), "longPress" (appui long).
}

Protocole (Requête d'état & 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 :** Number, unité dBm, valeurs entières négatives.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection d'effraction (tamper-alert)

Exemple de déclaration de capacité :

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

Attributs (État) :

{
  "tamper": "clear" // État d'effraction. **Type :** String. Valeurs possibles : "clear" (pas d'effraction), "detected" (effraction détectée).
}

Protocole (Requête d'état & instructions de contrôle) :

{
  "tamper-alert": {
    "tamper": "clear" // État d'effraction. **Type :** String. Valeurs possibles : "clear" (pas d'effraction), "detected" (effraction détectée).
  }
}

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 :** String. Valeurs possibles : "brighter" (plus lumineux), "darker" (plus sombre).
}

Protocole (Requête d'état & 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.01V. **Type :** Number, valeurs non négatives.
}

Protocole (Requête d'état & 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 de courant actuelle, en unités de 0.01A. **Type :** Number, valeurs entières non négatives.
}

Protocole (Requête d'état & 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.01W. **Type :** Number, valeurs entières non négatives.
}

Protocole (Requête d'état & 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 :** String. Valeurs possibles : "none" (pas de défaut), "detected" (défaut détecté).
}

Protocole (Requête d'état & instructions de contrôle) :

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

Rupture de seuil (threshold-breaker)

Exemple de déclaration de capacité :

{
  "capability": "threshold-breaker",
  "permission": "0010",
  "settings": {
    "supportedSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "supported": [
          {
            "name": "lowerPower", // Rupture de seuil de faible puissance
            "value": {
              "value": 50, // Valeur de puissance détectée, en unités de 0.01W. **Type :** Integer. Plage : >=0.
              "min_range": 10, // Valeur minimale de détection de puissance, en unités de 0.01W. **Type :** Integer. Plage : >=0.
              "max_range": 3500 // Valeur maximale de détection de puissance, en unités de 0.01W. **Type :** Integer. Plage : >=0.
            }
          },
          {
            "name": "upperPower", // Rupture de seuil de haute puissance
            "value": {
              "value": 50, // Valeur de puissance détectée, en unités de 0.01W. **Type :** Integer. Plage : >=0.
              "min_range": 10, // Valeur minimale de détection de puissance, en unités de 0.01W. **Type :** Integer. Plage : >=0.
              "max_range": 3500 // Valeur maximale de détection de puissance, en unités de 0.01W. **Type :** Integer. Plage : >=0.
            }
          },
          {
            "name": "lowerElectricCurrent", // Rupture de seuil de faible courant
            "value": {
              "value": 50, // Valeur de courant détectée, en unités de 0.01A. **Type :** Integer. Plage : >=0.
              "min_range": 10, // Valeur minimale de détection de courant, en unités de 0.01A. **Type :** Integer. Plage : >=0.
              "max_range": 1500 // Valeur maximale de détection de courant, en unités de 0.01A. **Type :** Integer. Plage : >=0.
            }
          },
          {
            "name": "upperElectricCurrent", // Rupture de seuil de courant élevé
            "value": {
              "value": 50, // Valeur de courant détectée, en unités de 0.01A. **Type :** Integer. Plage : >=0.
              "min_range": 10, // Valeur minimale de détection de courant, en unités de 0.01A. **Type :** Integer. Plage : >=0.
              "max_range": 1500 // Valeur maximale de détection de courant, en unités de 0.01A. **Type :** Integer. Plage : >=0.
            }
          },
          {
            "name": "lowerVoltage", // Rupture de seuil de basse tension
            "value": {
              "value": 50, // Valeur de tension détectée, en unités de 0.01V. **Type :** Integer. Plage : >=0.
              "min_range": 10, // Valeur minimale de détection de tension, en unités de 0.01V. **Type :** Integer. Plage : >=0.
              "max_range": 24000 // Valeur maximale de détection de tension, en unités de 0.01V. **Type :** Integer. Plage : >=0.
            }
          },
          {
            "name": "upperVoltage", // Rupture de seuil de haute tension
            "value": {
              "value": 50, // Valeur de tension détectée, en unités de 0.01V. **Type :** Integer. Plage : >=0.
              "min_range": 10, // Valeur minimale de détection de tension, en unités de 0.01V. **Type :** Integer. Plage : >=0.
              "max_range": 24000 // Valeur maximale de détection de tension, en unités de 0.01V. **Type :** Integer. Plage : >=0.
            }
          }
        ]
      }
    }
  }
}

Attributs (État)

• Aucun

Protocole (Requête d'état & instructions de contrôle)

• Aucun

Fonction Inch (inching)

Exemple de déclaration de capacité :

{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // Paramètre d'activation de la fonction inch
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Paramètre d'action inch
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Paramètre du temps d'inch
      "type": "numeric",
      "permission": "11",
      "min": 500,
      "max": 100000,
      "value": 1000,
      "unit": "ms"
    }
  }
}

Attributs (État) :

• Aucun

Protocole (Requête d'état & 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 :** String. Requis.
        "password": "String", // Mot de passe d'accès. **Type :** String. Requis.
        "streamUrl": "rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01", // URL du flux. **Type :** String. Requis.
        "videoCodec": "", // Codec vidéo. **Type :** String. Requis. Paramètres optionnels à définir.
        "resolution": { // Résolution vidéo. Requise.
          "width": 1080, // Largeur. **Type :** Number. Requis.
          "height": 720 // Hauteur. **Type :** Number. Requis.
        },
        "keyFrameInterval": 5, // Intervalle d'images clés. **Type :** String. Requis.
        "audioCodec": "G711", // Codec audio. **Type :** String. Requis. Paramètres optionnels à définir.
        "samplingRate": 50, // Fréquence d'échantillonnage audio, en Hz. **Type :** Number. Requis. Paramètres optionnels à définir.
        "dataRate": 50 // Débit binaire. **Type :** Number. Requis. Unité : kb/s.
      }
    }
  }
}

Attributs (État) :

• Aucun

Protocole (Requête d'état & 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 :** String. Requise. Se référer aux modes préréglés pris en charge.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection du 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 :** Integer. Unité : ppm.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection de l'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 :** Integer. Unité : lux.
}

Protocole (Requête d'état & 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 la détection. **Type :** Boolean. `true` indique détection, `false` indique absence de détection.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection ouverture/fermeture aimant de porte (contact)

Exemple de déclaration de capacité :

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

Attributs (État) :

{
  "contact": true // Résultat de la détection. **Type :** Boolean. `true` indique une détection, `false` indique aucune détection.
}

Protocole (Requête d'état & 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 la détection. **Type :** Boolean. `true` indique une détection, `false` indique aucune détection.
}

Protocole (Requête d'état & 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 actuel de la détection. **Type :** Boolean. `true` indique une détection, `false` indique aucune détection.
}

Protocole (Requête d'état & 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 :** String. `on` indique que l'alimentation est activée, `off` indique que l'alimentation est désactivée.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Verrouillage pour enfants (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 :** String. `on` indique que l'alimentation est activée, `off` indique que l'alimentation est désactivée.
}

Protocole (Requête d'état & 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 :** String. `on` indique que l'alimentation est activée, `off` indique que l'alimentation est désactivée.
}

Protocole (Requête d'état & 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 :** String. `on` indique que l'alimentation est activée, `off` indique que l'alimentation est désactivée.
}

Protocole (Requête d'état & 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 :** String. `on` indique que l'alimentation est activée, `off` indique que l'alimentation est désactivée.
}

Protocole (Requête d'état & 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 :** String. `on` indique que l'alimentation est activée, `off` indique que l'alimentation est désactivée.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Basculer démarrage (toggle-startup)

Exemple de déclaration de capacité :

{
  "capability": "toggle-startup",
  "permission": "1100",
  "name": "1" // Le champ `name` spécifie le nom d'attribut pour `toggle-startup`. **Type :** String. Seules les lettres et les chiffres sont autorisés.
}

Attributs (État) :

{
  "startup": "on" // **Type :** String. Options : `on` (mise sous tension), `stay` (maintien de l'alimentation), `off` (mise hors tension).
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection 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 de durée de la 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 :** String. `on` signifie que le maintien de détection est actif, `off` signifie qu'il est inactif.
}

Protocole (Requête d'état & 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 :** String. Valeurs optionnelles : "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4).
}

Attributs (État) :

{
  "identify": true, // Indique que l'appareil a signalé activement une identification ou activation.
  "countdown": 180 // Le champ `countdown` indique la durée d'activation. **Type :** Number. Unité : secondes.
}

Protocole (Requête d'état & instructions de contrôle) :

{
  "toggle-identify": {
    "1": {
      "countdown": 180 // Activer l'appareil pendant 180 secondes.
    }
  }
}

// L'appareil rapporte 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 :** Number. Unité : Volts.
}

Protocole (Requête d'état & instructions de contrôle) :

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

Détection du 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 :** String. 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 :** Integer. La valeur doit être supérieure ou égale à 0.
}

Protocole (Requête d'état & 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 :** String. 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 :** Integer. 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 :** Integer. Optionnel.
  "activePower": 50, // Le champ `activePower` représente la valeur de puissance active actuelle. **Unité :** 0.01 W. **Type :** Integer. Optionnel.
  "apparentPower": 50 // Le champ `apparentPower` représente la valeur de puissance apparente actuelle. **Unité :** 0.01 W. **Type :** Integer. Optionnel.
}

Protocole (Requête d'état & 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 :** String. 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 :** Boolean. Requis.
  "timeRange": { // Plage temporelle du résumé. Requis.
    "start": "2020-07-05T08:00:00Z", // Heure de début de la consommation d'énergie. **Type :** String. Requis.
    "end": "2020-07-05T09:00:00Z" // Heure de fin de la consommation d'énergie. **Type :** String. Requis.
  }
}

Interroger la consommation d'énergie par plage horaire :

{
  "type": "summarize", // Type de résumé. **Type :** String. 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 :** String. Requis.
    "end": "2020-07-05T09:00:00Z" // Heure de fin de la consommation d'énergie. **Type :** String. Optionnel. Si non fourni, prend par défaut l'heure courante.
  }
}

Réponse pour la consommation d'énergie dans une plage temporelle :

{
  "type": "summarize", // Type de résumé. **Type :** String. Requis.
  "rlSummarize": 50.0, // Consommation d'énergie totale. **Unité :** 0.01 kWh. **Type :** Number. 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 :** Number. Requis.
      "start": "2020-07-05T08:00:00Z", // Heure de début. **Type :** String. Requis.
      "end": "2020-07-05T09:00:00Z" // Heure de fin. **Type :** String. Requis. Les enregistrements avec des intervalles plus courts que la résolution sont considérés comme invalides.
    },
    {
      "usage": 26.5, // Consommation d'énergie. **Unité :** 0.01 kWh. **Type :** Number. Requis.
      "start": "2020-07-05T09:00:00Z", // Heure de début. **Type :** String. Requis.
      "end": "2020-07-05T10:00:00Z" // Heure de fin. **Type :** String. Requis. Les enregistrements avec des intervalles plus courts que la résolution sont considérés comme invalides.
    }
  ]
}

Protocole (Requête d'état & 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 liaison (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 liaison. **Type :** Number. Plage de valeurs : 0 à 255.
}

Protocole (Requête d'état & 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 :** Integer. **Unité :** Secondes. Requis.
    "maxResolution": 86400, // Résolution maximale pour la lecture des données de saturation d'humidité. **Type :** Integer. **Unité :** Secondes. Requis.
    "minResolution": 60 // Résolution minimale pour la lecture des données de saturation d'humidité. **Type :** Integer. **Unité :** Secondes. Requis.
  }
}

Protocole (Requête d'état & 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 :** Integer. **Unité :** Secondes. Requis.
      "maxResolution": 86400, // Résolution maximale pour la lecture des données de saturation d'humidité. **Type :** Integer. **Unité :** Secondes. Requis.
      "minResolution": 60 // Résolution minimale pour la lecture des données de saturation d'humidité. **Type :** Integer. **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 :** Boolean. Requis. La valeur doit être `true`.
}

Protocole (Requête d'état & instructions de contrôle) :

{
  "system": { // Configuration liée à la capacité. Optionnel.
    "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 en humidité. **Type :** Number. Requis. Plage : 0 à 100.
}

Protocole (Requête d'état & 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 :** Integer. Requis. Doit être inférieure à `max`.
        "max": 1100 // Valeur maximale. **Type :** Integer. Requis. Doit être supérieure à `min`.
      }
    }
  }
]

Attributs (État) :

{
  "barometricPressure": 50 // Valeur de la pression barométrique. **Type :** Integer. Requis. **Unité :** hPa.
}

Protocole (Requête d'état & 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 :** Number. Requis. Doit être inférieure à `max`.
        "max": 50 // Valeur maximale. **Type :** Number. Requis. Doit être supérieure à `min`.
      }
    }
  }
]

Attributs (État) :

{
  "windSpeed": 50 // Valeur de la vitesse du vent. **Type :** Number. Requis. **Unité :** m/s (mètres par seconde).
}

Protocole (Requête d'état & 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 :** Integer. Requis. **Unité :** Degrés. Plage : 0 à 360 degrés (sens horaire).
}

Protocole (Requête d'état & instructions de contrôle) :

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

Précipitations (rainfall)

Exemple de déclaration de capacité :

[
  {
    "capability": "rainfall",
    "permission": "0100",
    "settings": {
      "rainfallRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Valeur minimale. **Type :** Number. Requis. Doit être inférieure à `max`.
        "max": 450 // Valeur maximale. **Type :** Number. Requis. Doit être supérieure à `min`.
      }
    }
  }
]

Attributs (État) :

{
  "rainfall": 11.11 // Valeur des précipitations. **Type :** Number. Requis. **Unité :** mm/h (millimètres par heure).
}

Protocole (Requête d'état & 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 :** Number. Requis. Doit être inférieure à `max`.
        "max": 16 // Valeur maximale. **Type :** Number. Requis. Doit être supérieure à `min`.
      }
    }
  }
]

Attributs (État) :

{
  "ultravioletIndex": 11.1 // Indice ultraviolet. **Type :** Number. Requis.
}

Protocole (Requête d'état & 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 :** Number. Requis. Doit être inférieure à `max`.
        "max": 23 // Valeur maximale. **Type :** Number. Requis. Doit être supérieure à `min`.
      }
    }
  }
]

Attributs (État) :

{
  "electricalConductivity": 11.11 // Valeur de la conductivité électrique. **Type :** Number. Requis. **Unité :** dS/m.
}

Protocole (Requête d'état & 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 la puissance d'émission de l'appareil. **Type :** Integer. Requis. **Unité :** dBm.
}

Protocole (Requête d'état & 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 PM2.5 dans l'air. **Type :** Number. Requis. **Unité :** µg/m³.
}

Protocole (Requête d'état & 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 :** Number. Requis. **Unité :** µg/m³.
}

Protocole (Requête d'état & 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 :** Boolean. Requis.
}

Protocole (Requête d'état & 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 :** Number. Optionnel. **Unité :** L.
  "start": "2020-07-05T08:00:00Z", // Heure de début d'irrigation. **Type :** Date. Optionnel.
  "end": "2020-07-05T09:00:00Z", // Heure de fin d'irrigation. **Type :** Date. Optionnel.
  "dailyVolume": 20 // Volume d'irrigation quotidien. **Type :** Number. Optionnel. **Unité :** L.
}

Protocole (Requête d'état & instructions de contrôle) :

Rapport de statut de travail :

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

Requête de statut de travail :

{
  "irrigation": {
    "type": "oneDay", // Type d'agrégation. **Type :** String. Requis. Options : "oneDay", "30Days", "180Days".
    "timeRange": { // Plage temporelle pour l'agrégation. **Type :** Object. Requis.
      "start": "2020-07-05T08:00:00Z", // Heure de début pour l'agrégation des données d'irrigation. **Type :** String. Requis.
      "end": "2020-07-05T09:00:00Z" // Heure de fin pour l'agrégation des données d'irrigation. **Type :** String. Optionnel. Si omis, l'heure courante est utilisée.
    }
  }
}

Résultat de la requête de statut de travail :

{
  "irrigation": {
    "type": "oneDay", // Type d'agrégation. **Type :** String. Requis.
    "irrigationIntervals": [
      {
        "volume": 6500, // Volume d'irrigation. **Type :** Number. Requis. **Unité :** L.
        "duration": 30, // Durée d'irrigation. **Type :** Number. Requis. **Unité :** minutes.
        "start": "2020-07-05T08:00:00Z", // Heure de début. **Type :** String. Requis.
        "end": "2020-07-05T09:00:00Z" // Heure de fin. **Type :** String. Requis.
      },
      {
        "volume": 6500, // Volume d'irrigation. **Type :** Number. Requis. **Unité :** L.
        "duration": 30, // Durée d'irrigation. **Type :** Number. Requis. **Unité :** minutes.
        "start": "2020-07-05T08:00:00Z", // Heure de début. **Type :** String. Requis.
        "end": "2020-07-05T09:00:00Z" // Heure de fin. **Type :** String. 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", // Planification ponctuelle
          "CYCLE-TIMER", // Planification répétée
          "VOLUME", // Volume ponctuel
          "CYCLE-VOLUME" // Volume répété
        ]
      }
    }
  }
]

Attributs (État) :

{
  "workMode": "MANUAL" // Mode de travail d'irrigation. **Type :** String. Optionnel. Les valeurs doivent provenir de `settings.supportedModes`.
}

Protocole (Requête d'état & 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) :

Planification ponctuelle ou répétée :

{
  "type": "time", // Mode d'irrigation. **Type :** String. Requis. Options : "volume", "time".
  "action": {
    "perDuration": 60, // Durée par cycle d'irrigation. **Type :** Number. Requis.
    "intervalDuration": 20, // Intervalle entre les cycles d'irrigation. **Type :** Number. Requis.
    "count": 3 // Nombre de cycles d'irrigation. **Type :** Number. Requis.
  }
}

Volume ponctuel ou répété :

{
  "type": "volume", // Mode d'irrigation. **Type :** String. Requis. Options : "volume", "time".
  "action": {
    "perConsumedVolume": 60, // Volume consommé par cycle d'irrigation. **Type :** Number. Requis.
    "intervalDuration": 20, // Intervalle entre les cycles d'irrigation. **Type :** Number. Requis.
    "count": 3 // Nombre de cycles d'irrigation. **Type :** Number. Requis.
  }
}

Protocole (Requête d'état & instructions de contrôle) :

Planification ponctuelle ou répétée :

{
  "irrigation": {
    "auto-controller": {
      "type": "time", // Mode d'irrigation. **Type :** String. Requis.
      "action": {
        "perDuration": 60, // Durée par cycle d'irrigation. **Type :** Number. Requis.
        "intervalDuration": 20, // Intervalle entre les cycles. **Type :** Number. Requis.
        "count": 3 // Nombre de cycles. **Type :** Number. Requis.
      }
    }
  }
}

Volume ponctuel ou répété :

{
  "irrigation": {
    "auto-controller": {
      "type": "volume", // Mode d'irrigation. **Type :** String. Requis.
      "action": {
        "perConsumedVolume": 60, // Volume consommé par cycle. **Type :** Number. Requis.
        "intervalDuration": 20, // Intervalle entre les cycles. **Type :** Number. Requis.
        "count": 3 // Nombre de cycles. **Type :** Number. 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': 'Canal1',
        '2': 'Canal2',
        '3': 'Canal3',
        '4': 'Canal4',
    },
}

• 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 état de découverte 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 maximum 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 de l'appareil caméra	≥2.1.0
110011	Erreur d'adresse de flux de l'appareil caméra	≥2.1.0
110012	Le codage 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 incohérent avec le mot de passe du compte dans l'adresse de flux RTSP	≥2.1.0
110016	La passerelle est en état de découverte 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 erroné	≥2.1.0
110019	Échec d'accès à l'adresse de service du périphérique 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 : Ne prend en charge que la recherche de sous-appareils Zigbee pour le moment.

• 💡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 de l'identité de l'utilisateur est passée. **Code d'état : ** 200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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 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 caméra.

SettingsObject

Attribut	Type	Optionnel	Description
streamSetting	StreamSettingObject	N	Configuration du service de streaming

StreamSettingObject

Attribut	Type	Optionnel	Description
type	string	N	Configuration du service de streaming
permission	string	N	Autorisation de capacité. Prend en charge uniquement "11" (modifiable).
champ	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:[email protected]: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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {
    "serial_number": "serial_number"
  },
  "message": "succès"
}

Réponse de données 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 l'ajout d'un seul appareil échoue, renvoie que tous les appareils n'ont pas pu être ajoutés.

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 Le codage 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 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 des 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 du service 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 rempli lors de l'obtention du certificat d'interface ouverte, alors tous les appareils ultérieurs connectés via le certificat seront inscrits dans ce champ.
display_category	string	N	Catégorie d'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
état	object	Y	Objet d'état de l'appareil. Pour des exemples d'état des différentes fonctionnalités, veuillez consulter 【Fonctionnalités d'appareils prises en charge】
étiquettes	object	Y	Paires clé-valeur au format JSON, informations personnalisées sur l'appareil. La fonction est la suivante : - 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 se trouve dans le même sous-réseau que la passerelle

CapabilityObject 💡Remarque : Veuillez vérifier les Exemples de fonctionnalités d'appareils prises en charge pour [Fonctionnalités d'appareils prises en charge].

Attribut	Type	Optionnel	Description
capability	string	N	Nom de la capacité. Pour plus de détails, consultez [Fonctionnalités d'appareils prises en charge]
permission	string	N	Autorisation de la capacité. Valeurs possibles : "read" (lecture), "write" (écriture), "readWrite" (lecture et écriture).
configuration	object	Y	Informations de configuration de la capacité. Actuellement utilisé pour camera-stream, consultez [Fonctionnalités d'appareils prises en charge]
name	string	Y	Le champ name dans toggle. Le numéro de sous-canal utilisé pour identifier les appareils multicanaux. 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 de l'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": "succès"
}

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
étiquettes	object	Y	Paires clé-valeur au format JSON, informations personnalisées sur l'appareil.
état	object	Y	Objet d'état de l'appareil. Pour des exemples d'état des différentes fonctionnalités, veuillez consulter [Fonctionnalités d'appareils prises en charge]
configuration	object	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": "succès"
}

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.
étiquettes	object	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.
état	object	Y	Modifier l'état de l'appareil ; pour les détails du protocole, se référer à "Fonctionnalités d'appareils prises en charge."
capabilities	CapabilityObject []	Y	Informations de configuration de la capacité ; toutes les capacités qui prennent en charge la définition de configurations peuvent être modifiées. Notez que les permissions ne peuvent pas être modifié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": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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	object	N	Interroger l'état de l'appareil ; pour les détails du protocole, se référer à "Fonctionnalités d'appareils prises en charge."

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, requise 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, par défaut 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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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 d'appareils répondant

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 de l'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": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

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 de l'identité de l'utilisateur est passée. **Code d'état : **200 OK ::: Exemple de réponse:

{
  "error": 0,
  "data": {},
  "message": "succès"
}

4. Appareil tiers Accès

4.1 Instructions d'accès

Accès de l'appareil

1.0.jpg

Accès de passerelle tiers

2.0.jpg

Étapes d'accès

1. Déterminer la classification de l'appareil dans la passerelle. Les détails sont disponibles dans [Types d'appareils pris en charge].

2. Déterminer les fonctionnalités auxquelles l'appareil peut accéder. Les détails sont disponibles dans [Fonctionnalités d'appareils prises en charge].

3. Appeler 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 des appareils é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 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 la connexion de l'appareil à la passerelle.

• Choisissez la bonne fonctionnalité d'appareil. La liste des fonctionnalités déterminera l'état du protocole d'état de l'appareil.

Processus du programme

a. Accès de l'appareil

3.0.jpg

b. Accès de la passerelle tiers

4.0.jpg

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 version 4",
      "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 version 4",
    "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 version 4",
      "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 version 4",
    "version": "1"
  },
  "payload": {}
}

Signaler hors ligne/en ligne

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Identifiant unique, de préférence un UUID version 4",
    "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 version 4",
      "version": "1"
    },
    "endpoint": {
      "third_serial_number": "third_serial_number",
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Identifiant unique, de préférence un UUID version 4",
    "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": "succès"
}

4.3 API Web

Interface de passerelle de requête tierce

Format de 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	Informations sur la structure de l'objet d'événement de la requête

EventObject

Attribut	Type	Optionnel	Description
header	HeaderObject	N	Informations sur la structure de l'en-tête de la requête
endpoint	EndpointObject	Y	Informations sur la 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	Informations sur la structure du payload 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 de message de la requête, UUID_V4
version	string	N	Numéro de version du protocole de la requête. Actuellement fixe à 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
étiquettes	object	Y	Paires clé-valeur au format JSON, informations personnalisées sur 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 réponse

:::tips **Code d'état : **200 OK Paramètres de la réponse : :::

Attribut	Type	Optionnel	Description
header	HeaderObject	N	Informations sur la structure de l'en-tête de réponse
payload	PayloadObject	N	Informations sur la structure du payload de réponse

HeaderObject

Attribut	Type	Optionnel	Description
name	string	N	Nom de l'en-tête de réponse. paramètres optionnels : Response : Réponse réussie ErrorResponse : Réponse d'erreur
message_id	string	N	ID de message de l'en-tête de réponse, UUID_V4. Renvoyer ici l'header.message_id du message de requête *Si le paramètre message_id de la requête est absent, ce champ sera une chaîne vide lors de la réponse.
version	string	N	- Numéro de version du protocole de la requête. Actuellement fixe à 1.

Réponse réussie--PayloadObject ：

Selon le type de requête, la structure de réponse est différente. Pour plus de détails, veuillez vous référer au document d'instructions 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ètre

• AUTH_FAILURE : Erreur d'autorisation

• INTERNAL_ERROR : Erreur de service interne | | 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 en ligne ultérieurs 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 d'appareil. Voir [Types d'appareils pris en charge] 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
état	object	N	Informations d'état initial
manufacturer	string	N	Fabricant
model	string	N	Modèle de l'appareil
étiquettes	object	Y	Paires clé-valeur au format JSON, informations personnalisées sur l'appareil : Utilisé pour stocker les canaux de l'appareil Utilisé pour stocker les unités de température Autres données personnalisées tierces
firmware_version	string	N	Version du firmware
service_address	string	N	Adresse de service. Tel que 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 version 4",
      "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 des 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 version 4",
    "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 version 4",
    "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
état	object	N	État de l'appareil, Voir [Fonctionnalités d'appareils prises en charge] pour plus de détails

Exemple de requête :

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "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 version 4",
    "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 version 4",
      "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 version 4",
    "version": "1"
  },
  "payload": {}
}

DeviceInformationUpdatedReport Rapport de mise à jour des informations de l'appareil

• Remarque : La mise à jour peut affecter les scènes ou fonctions de sécurité existantes.

Paramètres de la requête : PayloadObject：

Attribut	Type	Optionnel	Description
capabilities

| CapabilityObject[]

| N

| Liste des capacités. Les détails se trouvent dans la section des fonctionnalités d'appareils prises en charge. **Remarque : **Ce paramètre ne mettra à jour que le champ de la réglage clé dans le CapabilityObject, et les mises à jour sont autorisées uniquement si le permission pour la réglage clé est 11 ou 01. Pour la définition structurelle spécifique du réglage dans CapabilityObjectréférez-vous à la description détaillée dans la section 2.3 Catégories d'affichage des appareils et fonctionnalités des appareils. | | tags

| object

| Y

| Paires clé-valeur au format JSON, informations personnalisées sur 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 version 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "detect",
          "permission": "0110",
          "settings":{
            "detectInterval":{
              "permission": "11",
              "type": "numeric",
              "value": 300,
            },
            "detectSensitivity":{
              "permission": "11",
              "type": "numeric",
              "value": 1000,
            }
          }
        }
      ]
    }
  }
}

Paramètres de 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 version 4",
    "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 requête de la passerelle sous 3s. Sinon, la passerelle considérera le traitement de la commande comme expiré.

2. Si le service tiers est hors ligne, la passerelle mettra 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 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	Informations sur la structure de l'objet directive

DirectiveObject

Attribut	Type	Optionnel	Description
header	HeaderObject	N	Informations sur la structure de l'en-tête de la requête
endpoint	EndpointObject	N	Informations sur la structure de l'endpoint de la requête
payload	PayloadObject	N	Informations sur la structure du payload 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 de l'appareil
message_id	string	N	ID de message de la requête, UUID_V4
version	string	N	Numéro de version du protocole de la requête. Actuellement fixe à 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
étiquettes	object	N	Paires clé-valeur au format JSON, informations personnalisées sur 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 version 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Format de réponse

:::tips **Code d'état HTTP : **200 OK Attribut de réponse HTTP： :::

Attribut	Type	Optionnel	Description
event	EventObject	N	Informations sur la structure de l'événement de réponse

EventObject

Attribut	Type	Optionnel	Description
header	HeaderObject	N	Informations sur la structure de l'en-tête de la requête
payload	PayloadObject	N	Informations sur la structure du payload de la requête

HeaderObject

Attribut	Type	Optionnel	Description
name	string	N	Nom de l'en-tête de réponse. Paramètre optionnel : UpdateDeviceStatesResponse : Réponse de mise à jour des états de l'appareil ErrorResponse : Réponse d'erreur
message_id	string	N	ID de message de l'en-tête de réponse, UUID_V4. Renvoyer ici l'header.message_id du message de requête
version	string	N	Numéro de version du protocole de la requête. Actuellement fixe à 1.

Réponse réussie--PayloadObject：

Selon le type de requête, la structure de réponse est différente. Pour plus de détails, veuillez vous référer au document d'instructions de la requête spécifique.

Réponse d'échec--PayloadObject：

Attribut	Type	Optionnel	Description
type	string	N	Types d'erreur:

• ENDPOINT_UNREACHABLE: L'appareil est injoignable ou hors ligne

• ENDPOINT_LOW_POWER: L'appareil est en mode basse consommation et ne peut pas être contrôlé

• INVALID_DIRECTIVE: Directive anormale de la passerelle

• NO_SUCH_ENDPOINT: L'appareil n'existe pas

• NOT_SUPPORTED_IN_CURRENT_MODE: Le mode actuel ne prend pas en charge l'opération

• INTERNAL_ERROR: Erreur de service interne

• REMOTE_KEY_CODE_NOT_LEARNED: Code de touche de 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 version 4",
      "version": "1"
    },
    "payload": {}
  }
}

{
  "event": {
    "header": {
      "name": "ErrorResponse",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "1"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE"
    }
  }
}

UpdateDeviceStates

Paramètres de la requête : PayloadObject：

Attribut	Type	Optionnel	Description
état	object	N	État de l'appareil, Voir [Fonctionnalités d'appareils prises en charge] pour plus de détails.

Exemple de requête :

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "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 version 4",
    "version": "1"
  },
  "payload": {}
}

QueryDeviceStates

Paramètres de la requête : PayloadObject：

Attribut	Type	Optionnel	Description
état	object	N	État de l'appareil, Voir [Fonctionnalités d'appareils prises en charge] pour plus de détails.

Exemple de requête :

{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "timeRange": {
            "start": "2020-07-05T08:00:00Z", // Heure de début pour les statistiques de consommation d'énergie, requise.
            "end": "2020-07-05T09:00:00Z"   // Heure de fin pour les statistiques de consommation d'énergie, requise.
          }
        }
      }
    }
  }
}

Paramètres de la réponse : PayloadObject：

Attribut	Type	Optionnel	Description
état	object	N	État de l'appareil, Voir [Fonctionnalités d'appareils prises en charge] pour plus de détails.

Exemple de réponse :

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // Divisé en plusieurs enregistrements selon configuration.resolution
            {
              "usage": 26.5, // Valeur de consommation d'énergie, requise. Type : number.
              "start": "2020-07-05T08:00:00Z", // Heure de début, requise. Type : date.
              "end": "2020-07-05T09:00:00Z"    // Heure de fin, requise. Type : date. 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, // Valeur de consommation d'énergie, requise. Type : number.
              "start": "2020-07-05T09:00:00Z", // Heure de début, requise. Type : date.
              "end": "2020-07-05T10:00:00Z"    // Heure de fin, requise. Type : date. Si l'intervalle entre end et start est inférieur à resolution, tous les enregistrements signalés sont considérés comme 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 fonctionnalités d'appareils prises en charge. Notez que le champ permission ne peut pas être modifié, fournir 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 version 4",
      "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 existe des conditions prédéfinies.
                      "value": 68.0, // Valeur de température ou d'humidité, requise.
                      "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 existe des conditions prédéfinies.
                      "value": 68.0, // Valeur de température ou d'humidité, requise.
                      "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 version 4",
      "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 le push de messages vers le client en utilisant SSE (Server-sent events). Le client peut surveiller les messages SSE après obtention des identifiants d'accès et peut analyser le contenu des messages push selon le protocole de notification d'événements 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 aura une limite maximale de connexions ne dépassant pas 6 (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 elle renverra une erreur d'échec d'authentification si le token 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 d'ajout d'appareil

:::tips Nom du module：device Version：v2 Type de message：addDevice paramètres event.data： :::

Nom	Type	Optionnel	Description
payload	ResponseDeviceObjectObject - Interface identique à celle de Obtenir la liste d'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 paramètres event.data： :::

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 paramètres event.data： :::

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.
étiquettes	object	Y	étiquettesobject | 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 existe des conditions prédéfinies.
                    "value": 68.0, // Valeur de température ou d'humidité, requise.
                    "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 existe des conditions prédéfinies.
                    "value": 68.0, // Valeur de température ou d'humidité, requise.
                    "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 de suppression d'appareil

:::tips Nom du module：device Version：v2 Type de message：deleteDevice paramètres event.data： :::

** 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 paramètres event.data： :::

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 paramètres event.data： :::

Attribut	Type	Optionnel	Description
payload	SecurityStateObject	N	Informations sur l'appareil

SecurityStateObject

Attribut	Type	Optionnel	Description
alarm_state	string	N

• arming | Armé

• disarming | 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 paramètres event.data： :::

Attribut	Type	Optionnel	Description
payload	ArmStateObject	N	informations d'armement et de désarmement

ArmStateObject：

Attribut	Type	Optionnel	Description
arm_state	string	N

• arming | Armé

• disarming | 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 (Synthèse vocale) Fonction du moteur

6.1 Instruction

Rôle clé

• Fournisseur de service TTS : Le fournisseur du moteur de service TTS est responsable de l'enregistrement du moteur TTS sur la passerelle et de la fourniture des services TTS

• Serveur de la 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 la 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 la communication ultérieure entre la passerelle et le fournisseur de service TTS se fera via l'adresse server_address), et allouera l'ID de service du moteur TTS au sein de la passerelle.

image.png

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

image.png

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

image.png

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 alloué 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és ouvertes de la passerelle

a. Obtenir la liste des services de moteur TTS enregistrés

:::astuces

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

• Méthode：GET

• En-tête：

  • Content-Type: application/json

  • Authorization: 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 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": {
    "engines": [
      {
        "id": "engine id",
        "name": "engine name"
      }
    ]
  },
  "message": "succès"
}

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

  • Authorization: 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	Libellé du fichier audio

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

• 190000 Le moteur fonctionne anormalement

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": "libellé audio tts"
      }
    ]
  },
  "message": "succès"
}

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

  • Authorization: Bearer ::: Paramètres de la requête :

Attribut	Type	Optionnel	Description
text	string	N	Texte utilisé pour synthétiser l'audio
label	string	Y	Libellé 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 de 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 fournie, la langue par défaut du moteur sera utilisée pour la synthèse.
options	object	Y	Champ transparent. Il est utilisé pour transmettre les paramètres de configuration requis pour la synthèse au service de 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	Libellé du fichier audio

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

• 190000 Le moteur fonctionne anormalement

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": "libellé audio tts"
    }
  },
  "message": "succès"
}

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

  • Authorization: Bearer ::: Paramètres de la requête :

Attribut	Type	Optionnel	Description
event	EventObject	N	Structure des informations de l'objet d'événement de requête

EventObject

Attribut	Type	Optionnel	Description
header	HeaderObject	N	Informations sur la structure de l'en-tête de la requête
payload	PayloadObject	N	Informations sur la structure du payload 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 la requête, UUID_V4 | | version | string | N | Numéro de version du protocole de la 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 version 4",
      "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	Informations sur la structure de l'en-tête de la requête
payload	PayloadObject	N	Informations sur la structure du payload 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 de l'en-tête de réponse, UUID_V4. Message de la requête entrante ici : header.message_id | | version | string | N | Numéro de version du protocole de la 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 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 :： ::: Exemple de réponse correcte :：

{
    "header": {
      "name": "Response",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "1"
    },
    "payload": {
      "engine_id": "engine id"
    }
  }

**Paramètres de réponse anormale : **

Attribut	Type	Optionnel	Description
type	string	N	Type d'erreur

• INVALID_PARAMETERS (Erreur de paramètres)

• AUTH_FAILURE (Échec de l'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 version 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address ne peut pas être vide" 
  }
}

b. Commande de synchronisation de la liste audio

Envoyer la commande au fournisseur de service TTS depuis 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	Informations sur la structure de l'en-tête de la requête
payload	PayloadObject	N	Informations sur la structure du payload 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 la requête, UUID_V4 | | version | string | N | Numéro de version du protocole de la requête. Actuellement fixé à 1 |

Exemple de requête :

{
  "directive": {
    "header": {
      "name": "SyncTTSAudioList",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "1"
    },
    "payload": {}
  }
}

**Paramètres de réponse corrects : **

Attribut	Type	Optionnel	Description
header	HeaderObject	N	Informations sur la structure de l'en-tête de la requête
payload	PayloadObject	N	Informations sur la structure du payload 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 de l'en-tête de réponse, UUID_V4. Message de la requête entrante ici : header.message_id | | version | string | N | Numéro de version du protocole de la 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	Libellé du fichier audio

:::astuce 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 :： ::: Exemple de réponse correcte :：

{
    "header": {
      "name": "Response",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "1"
    },
    "payload": {
      "audio_list": [
        {
            "url": "url audio tts",
            "label": "libellé audio tts"
        }
      ]
    }
}

**Paramètres de réponse anormale : **

Attribut	Type	Optionnel	Description
type	string	N	Type d'erreur

• INVALID_PARAMETERS (Erreur de paramètres)

• AUTH_FAILURE (Échec de l'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 version 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address ne peut pas être vide" 
  }
}

c. Commande de synthèse vocale

Envoyer la commande au fournisseur de service TTS depuis 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	Informations sur la structure de l'en-tête de la requête
payload	PayloadObject	N	Informations sur la structure du payload 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 la requête : UUID_V4 | | version | string | N | Numéro de version du protocole de la requête. Actuellement fixé à 1 |

PayloadObject

Attribut	Type	Optionnel	Description
text	string	N	Texte utilisé pour synthétiser l'audio
label	string	Y	Libellé 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 de 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 fournie, la langue par défaut du moteur sera utilisée pour la synthèse.
options	object	Y	Champ transparent. Il est utilisé pour transmettre les paramètres de configuration requis pour la synthèse au service de moteur TTS.

Exemple de requête :

{
    "directive": {
        "header": {
            "name": "SynthesizeSpeech",
            "message_id": "Identifiant unique, de préférence un UUID version 4",
            "version": "1"
        },
        "payload": {
            "text": "Texte d'entrée à synthétiser.",
            "label": "libellé audio tts"
        }
    }
}

**Paramètres de réponse corrects : **

Attribut	Type	Optionnel	Description
header	HeaderObject	N	Informations sur la structure de l'en-tête de la requête
payload	PayloadObject	N	Informations sur la structure du payload 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 de l'en-tête de réponse, UUID_V4. Message de la requête entrante ici : header.message_id | | version | string | N | Numéro de version du protocole de la 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	Libellé du fichier audio

:::astuce 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 :： ::: Exemple de réponse correcte :：

{
    "header": {
      "name": "Response",
      "message_id": "Identifiant unique, de préférence un UUID version 4",
      "version": "1"
    },
    "payload": {
      "audio": {
        "url": "url audio tts",
        "label": "libellé audio tts"
      }
    }
}

**Paramètres de réponse anormale : **

Attribut	Type	Optionnel	Description
type	string	N	Type d'erreur

• INVALID_PARAMETERS (Erreur de paramètres)

• AUTH_FAILURE (Échec de l'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 version 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address ne peut pas être vide" 
  }
}

7. Module multimédia

7.1 Lecture d'un fichier audio

:::astuces

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

• Méthode：POST

• En-tête：

  • Content-Type: application/json

  • Authorization: Bearer ::: Paramètres de la requête :

Attribut	Type	Optionnel	Description
audio_url	string	N	Adresse URL audio

Réponse de données correcte : :::astuce 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": "succès"
}

8. Carte UI personnalisée

Les cartes UI personnalisées vous permettent d'afficher n'importe quel contenu souhaité dans la carte. Ce contenu peut être une page Web, une image ou tout service avec une interface utilisateur. Vous devez simplement 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 Instruction

Rôle clé

• Fournisseur de service UI: Le fournisseur responsable de la création des cartes UI personnalisées sur la passerelle.

• Serveur de la passerelle: Le serveur de la 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 la passerelle]: Lors d'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.

image.png

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

image.png

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 la passerelle]: Après 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.

image.png

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 la passerelle]: La passerelle supprimera toutes les informations liées à la carte UI spécifiée.

image.png

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

  • Authorization: Bearer ::: Paramètres de la requête :

Attribut	Type	Optionnel	Description
label	string	Y	Libellé de la carte : Utilisé 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 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 de l'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": "succès"
}

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

  • Authorization: Bearer ::: Paramètres de la requête : Aucun Paramètres de réponse :

Attribut	Type	Optionnel	Description
data	CardObject[]	N	Liste des cartes UI

CardObjec Objet :

Attribut	Type	Optionnel	Description
id	string	N	ID de la carte : Un identifiant unique pour la carte.
label	string	Y	Libellé de la carte : Utilisé pour décrire la carte. Il sert d'alias ou de nom pour la carte.
cast_settings	CastSettingsObject	Y	Libellé de la carte : Utilisé 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 | | used | 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": "succès"
}

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

  • Authorization: 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": "succès"
}

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

  • Authorization: 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": "succès"
}