Protocole API MODE DIY

Vous souhaitez contrôler votre appareil SONOFF via votre application ou votre plateforme domotique ? Le mode DIY est la solution !

Le mode DIY est conçu pour les utilisateurs et développeurs domotiques IoT souhaitant contrôler leur appareil SONOFF via une plateforme open source domotique existante ou un client HTTP local plutôt que via l'application eWeLink. En mode DIY, une fois connecté au réseau, l'appareil publie ses services et fonctionnalités conformément à la norme mDNS/DNS-SD. Avant de publier le service, l'appareil a activé le serveur HTTP sur le port déclaré par l'enregistrement DNS SRV. L'appareil expose ses fonctionnalités via une API RESTful basée sur HTTP. Les utilisateurs peuvent obtenir des informations sur l'appareil et le contrôler en envoyant une requête API HTTP.

Les appareils SONOFF ^[1] peuvent fonctionner en mode eWeLink ou en mode DIY. En mode eWeLink, l'appareil est connecté au cloud eWeLink et contrôlé par l'application eWeLink, tandis qu'en mode DIY, l'appareil publie son service de capacité et est contrôlé par une requête HTTP Post.

Les étapes pour entrer dans le mode DIY et se connecter à un réseau WiFi existant :

1. Entrer dans le mode d'appairage compatible (AP) en appuyant longuement sur le bouton d'appairage pendant 5 secondes après la mise sous tension
2. Connexion du point d'accès nommé ITEAD-XXXXXXXXXX avec le mot de passe par défaut 12345678 via un téléphone portable ou un PC
3. Visites du navigateur http://10.10.7.1/
4. Renseigner le SSID et le mot de passe du réseau WiFi existant
5. Accès réussi au mode DIY avec un réseau WiFi spécifique connecté.

Exemple pour une prise DIY à canal unique (BASICR3, RFR3, MINI/MINIR2, MINIR3) entrant en mode DIY :

1. Allumer;
2. Appuyez longuement sur le bouton pendant 5 secondes pour accéder au mode de couplage compatible (AP)
   Conseils d'utilisation : Si l'appareil a été couplé avec l'application eWeLink, il est nécessaire de réinitialiser l'appareil en appuyant longuement sur le bouton de couplage pendant 5 secondes, puis en appuyant encore 5 secondes pour accéder au mode de couplage compatible (AP)
3. L'indicateur LED clignotera en continu
4. À partir des paramètres WiFi du téléphone mobile ou du PC, un point d'accès de l'appareil nommé ITEAD-XXXXXXXXXX sera trouvé, connectez-le avec le mot de passe par défaut 12345678
5. Ouvrez le navigateur et accédez à http://10.10.7.1/
6. Ensuite, renseignez le SSID et le mot de passe Wi-Fi avec lesquels l'appareil se serait connecté
7. Réussi, maintenant l'appareil est en mode DIY.

Exemple pour un variateur DIY à canal unique (D1) entrant en mode DIY :

1. Allumer;
2. Appuyez longuement sur le bouton d'appairage de la télécommande RM433 pendant 5 secondes pour accéder au mode d'appairage compatible (AP)
   Conseils d'utilisation : Si l'appareil a été couplé avec l'application eWeLink, il est nécessaire de réinitialiser l'appareil en appuyant longuement sur le bouton de couplage de la télécommande RM433 pendant 5 secondes, puis en appuyant encore 5 secondes pour accéder au mode de couplage compatible (AP)
3. La lumière dimmable connectée à D1 clignotera en continu (passera rapidement de 100 % à 1 %, de 1 % à 100 %…)

Les étapes 4 à 7 sont les mêmes que dans l’exemple de la prise DIY à canal unique.

Exemple pour le compteur d'énergie intelligent (SPM-Main) qui entre en mode DIY :

1. Allumer;
2. Appuyez longuement sur le bouton du SPM-Main pendant 5 secondes pour accéder au mode de couplage Bluetooth.
   Conseils d'utilisation : si l'appareil a été couplé avec l'application eWeLink, il est nécessaire de réinitialiser l'appareil en appuyant longuement sur le bouton de couplage pendant 5 secondes pour accéder au mode de couplage Bluetooth.
3. L'indicateur LED clignotera rapidement.
4. Connectez SPM-Main à votre routeur à l'aide d'un câble Ethernet et l'une des méthodes suivantes est disponible pour vous connecter.
5. Tapez l'adresse IP de SPM-Main dans le navigateur de votre ordinateur et accédez-y.
6. Ensuite, entrez le SSID et le mot de passe WiFi.
7. Réussi. L'appareil est désormais en mode DIY.

Exemple pour l'ampoule LED intelligente (B02-BL-A60, B05-BL-A19, B05-BL-A60) qui entre en mode DIY :

1. Allumer;
2. Lorsque la lumière est allumée, appuyez 5 fois de suite sur l'interrupteur à un intervalle de 1 s (Arrêt-Marche-Arrêt-Marche-Arrêt-Marche-Arrêt-Marche-Arrêt-Marche).
3. Le « clignotement rapide » indique que l’appareil entre en mode de couplage compatible (AP).
4. À partir des paramètres WiFi du téléphone mobile ou du PC, un point d'accès de l'appareil nommé ITEAD-XXXXXXXXXX sera trouvé, connectez-le avec le mot de passe par défaut 12345678
5. Ouvrez le navigateur et accédez à http://10.10.7.1/
6. Ensuite, renseignez le SSID et le mot de passe Wi-Fi avec lesquels l'appareil se serait connecté
7. Réussi, maintenant l'appareil est en mode DIY.

Note:

• Les paramètres utilisateur seront nettoyés une fois le mode de fonctionnement modifié de l'un à l'autre.
• Le routeur ou le point d'accès WiFi doit fonctionner à 2,4 GHz et prendre en charge le service mDNS.
• Signification du clignotement des LED
  Clignotement rapide et unique – L’appareil ne se connecte pas au réseau WiFi ;
  Clignotement double rapide – L'appareil se connecte avec succès au WiFi et peut être découvert via mDNS et répondre à la demande du réseau LAN.
• Une fois l'appareil déjà en mode DIY, la page de configuration WiFi de http://10.10.7.1/ n'est pas accessible.
• Si un SSID ou un mot de passe WiFi incorrect a été saisi, l'appareil ne parviendra pas à se connecter à un réseau WiFi spécifique, avec un mécanisme de délai d'attente de 20 secondes, l'appareil arrêtera de se connecter au réseau WiFi, veuillez réessayer avec les étapes d'exemple de 1 à 7.
• La mise à niveau officielle du micrologiciel n'est disponible que dans l'application eWeLink.
• Le protocole v1.4 est accessible via https://github.com/itead/Sonoff_Devices_DIY_Tools

La découverte LAN en mode DIY implémente le protocole DNS multidiffusion IETF et le protocole de découverte de services basé sur DNS. ^{[2] – [8]}

L'appareil publie son propre service (c'est-à-dire la capacité de l'appareil) conformément au protocole de découverte standard mDNS/DNS-SD lorsque l'appareil est connecté au LAN (réseau local).

La définition des champs est la suivante :

Note d'enregistrement TXT :

1. L'enregistrement TXT doit contenir les chaînes ci-dessous :
   « txtvers = 1 », « id = [ID de l'appareil] », « type = [type d'appareil] », « apivers = [version de l'interface API de l'appareil] », « seq = [numéro de série de l'enregistrement TXT] », « data1 = [informations sur l'appareil] » ;
2. Chaînes facultatives :
   « data2 = [informations sur l'appareil] », « data3 = [informations sur l'appareil] », « data4 = [informations sur l'appareil] »
3. « seq =[numéro de séquence d'enregistrement TXT] » indique l'ordre de mise à jour des enregistrements TXT (ordre de mise à jour de l'état de l'appareil). Il est recommandé d'utiliser un entier positif incrémenté de 1 (réinitialisé à 1 au redémarrage de l'appareil) ;
4. Lorsque les informations sur l'appareil dépassent 249 octets, les 249 premiers octets doivent être stockés dans data1, et les octets restants sont divisés par 249, stockés dans data2, data3 et data4. Le format complet des informations sur l'appareil est un objet JSON.

Pour l'exemple d'enregistrement txt BASICR3, RFR3, MINI mDNS :
data1= {« switch » : « on », « startup » : « stay », « pulse » : « on », « pulseWidth » : 2000, « rssi » : -67, « fwVersion » : « 3.5.0 »}

Pour l'exemple d'enregistrement txt mDNS D1 (Dimmer) :
data1= {« switch » : « on », « mode » : 0, « brightness » : 50, « brightMin » : 0, « brightMax » : 255, « startup » : « on », « rssi » : -67, « fwVersion » : « 3.5.0 »}

Pour l'exemple d'enregistrement txt mDNS SPM-Main :
data1= {“subDevId”: “123456”,”commutateurs”: [{“commutateur”: “activé”,”prise”: 0},{“commutateur”: “activé”,”prise”: 1},{“commutateur”: “activé”,”prise”: 2},{“commutateur”: “activé”,”prise”: 3}]}

Pour l'exemple d'enregistrement txt mDNS MINIR3 :
data1= {« commutateurs » : [{« commutateur » : « activé », « prise » : 0},{« commutateur » : « désactivé », « prise » : 1},{« commutateur » : « désactivé », « prise » : 2},{« commutateur » : « désactivé », « prise » : 3}], « sledOnline » : « activé »}

Pour l'exemple d'enregistrement txt B02-BL-A60, B05-BL-A19, B05-BL-A60 :
data1= {« switch » : « off », « startup » : « off », « pulse » : « off », « pulseWidth » : 500, « ssid » : « eWeLink », « otaUnlock » : false, « fwVersion » : « 3.5.0 », « deviceid » : « 100000140e », « bssid » : « ec:17:2f:3d:15:e », « signalStrength » : -25}

Chaque fois que le contenu autre que la séquence change, comme le nom de l'instance de service est modifié, les informations sur l'appareil sont mises à jour, etc., l'appareil doit diffuser en multidiffusion l'enregistrement DNS correspondant (y compris la séquence incrémentée) conformément à la norme mDNS/DNS-SD.

Le processus de découverte doit suivre le protocole de découverte mDNS/DNS-SD pour découvrir l'appareil Sonoff DIY Mode avec le type de service « _ewelink._tcp » lorsque votre application ou client se connecte à Internet (Wi-Fi ou Ethernet) ;

Voici le processus de découverte :

1. Recherchez dans le réseau local tous les appareils avec le type de service _ewelink._tcp via l'enregistrement DNS PTR.
2. Obtenez le nom d'hôte et le port du service de l'appareil en analysant l'enregistrement DNS SRV de l'appareil. (Le port par défaut est 8081)
3. Obtenez l'adresse IP de l'appareil via l'enregistrement DNS A ou par d'autres moyens.
4. Obtenez les informations sur « l'ID de l'appareil », « le type de service », « la version de l'interface API de l'appareil » et « les informations sur l'appareil » en analysant l'enregistrement DNS TXT de l'appareil.

Note:

• Lorsque le « type d'appareil » du service de périphérique ne correspond pas au « type d'appareil » de votre application ou client, ou que la version de l'interface API du service de périphérique est supérieure à celle de votre application ou client, l'application ou le client ne doit pas analyser les « informations sur l'appareil » et appeler l'interface API de l'appareil, mais demander aux utilisateurs la raison spécifique pour laquelle l'appareil ne peut pas être contrôlé via le réseau local et suggérer de mettre à niveau l'application ou le client.

• L'application ou le client obtient l'adresse IP de l'appareil via l'enregistrement DNS A lorsque l'interface API de l'appareil est sur le point d'être appelée.

L'appareil doit ouvrir le serveur HTTP sur le port déclaré par l'enregistrement DNS SRV avant de publier ses services ; il publie ces fonctionnalités via une API RESTful basée sur HTTP. En raison de la sécurité du réseau local et de la puissance de calcul limitée de l'appareil, ce document recommande que l'appareil fournisse une interface HTTP plutôt qu'une interface HTTPS.

Le type d'appareil et la version de l'interface API de chaque produit sont indiqués ci-dessous :

URL : http://[ip]:[port]/[chemin]
Format de la valeur de retour : json
Méthode : HTTP post
La demande d'API RESTful fonctionne dans la méthode POST et le corps de demande au format JSON.

 { 
    "deviceid": "100000140e", 
    "data": { 
        "switch": "on" 
       }
}

La réponse de l'API RESTful fonctionne avec un code de réponse HTTP 200 OK et un corps de réponse au format JSON.

 { 
    "seq": 2, 
    "error": 0, 
    "data": { 
        "signalStrength": -67 
    } 
}

Note:

• En raison de la capacité de calcul de l'appareil, l'intervalle de temps de chaque requête HTTP ne doit pas être inférieur à 200 ms.
• Le port par défaut : 8081

Référence

[1] Les appareils SONOFF font référence à BASICR3 , RFR3 , MINI , D1 dans cette page
[2] Protocole DNS multidiffusion : IETF RFC 6762
[3] Protocole de découverte de services basé sur DNS : IETF RFC 6763
[4] Réseau sans configuration : Zeroconf
[5] Découverte et connectivité du réseau Apple Bonjour
[6] Découverte du service réseau Android
[7] Wikipédia Réseau à configuration zéro
[8] Comment Zeroconf se compare-t-il à Viiv/DLNA/DHWG/UPnP