Documentation du plugin SmartThings pour Jeedom

Le plugin permet de récupérer les emplacements, pièces et commandes de tous les appareils qui sont enregistrés et actifs sur son compte SmartThings.
SmartThings permet l’interconnexion avec d’autres plateformes (eWeLink, Harmony, Arlo…) et permet donc indirectement d’interfacer différents protocoles domotiques (Zigbee, Z-wave, Wi-Fi…)
Il récupère les informations des appareils depuis le cloud SmartThings, aucune communication directe vers l’appareil n’est réalisée.

Appareils compatibles

Tous les appareils affichés dans l’application SmartThings.
Les commandes générées et leurs traductions peuvent ne pas être complètes pour l’instant. Pensez à fournir les infos brutes au développeur pour implémenter correctement chaque appareil.
Même sur les appareils déjà parfaitement implémentés, il y a régulièrement des mises à jour de SmartThings pour inclure de nouvelles commandes/info… et donc n’hésitez pas à remonter cela.
Actuellement voilà la liste des appareils testés et configurés ou en cours d’amélioration :

• Lave-linge (Samsung OCF Washer)
• Sèche-linge (Samsung OCF Dryer)
• Réfrigérateur avec dongle (Samsung OCF Refrigerator)
• TV (Samsung OCF TV)
• Four (Samsung OCF Oven)
• Plaque de cuisson (oic.d.cooktop)
• Climatiseur (Samsung Floor A/C et Samsung OCF Air Conditioner)
• Lampe Bulb (c2c-rgbw-color-bulb)
• Thermostat Netatmo (c2c-thermostat-bridge-1 et c2c-thermostat-heating-1)
• Aspirateur robot (Samsung OCF Robot Vacuum)
• SmartTag (SmartTag-Tag(BLE)) (partiellement fonctionnel : pas de connexion à SmartThings Find) Sujet de discussion : https://community.jeedom.com/t/discussions-smarttag-et-smarttag/63972
• Caméra et sonnette vidéo (Arlo Video Doorbell testé)
• Harmony
• SmartThings Hub
• Mobile presence (localisation de son téléphone)
• Volet (Meroos)
• Store (IKEA)
• Prise (Samsung OCF Smart Plug, SmartPlug)
• Localisation

Commandes générées

Commandes info

Les commandes info sont générées principalement en fonction des informations fournies par SmartThings sur cet appareil. Si la valeur est nulle, la commande n’est pas créée (la valeur ne remonte pas de l’appareil).
Le type et sous-type de la commande dépend, lui, de la documentation de SmartThings (capabilities) qui sont téléchargés en dur dans le plugin lors de la mise à jour du plugin. Cette documentation est disponible ici, elle est modifiée et corrigée par mes soins pour les besoins du plugin.

• Une commande info Santé est créée lors de la synchronisation.
  Elle remonte l’état de l’appareil (EN LIGNE, HORS LIGNE).

• Une commande infos Dernières notifications est créées lors de notifications sur l’appareil. Il faut activer les notifications dans la configuration du plugin.

Les autres commandes info dépendent de l’appareil.

Commandes action

Les commandes actions sont, elles, générées premièrement en fonction des commandes info précédemment créées, puis en fonction de la documentation de SmartThings (capabilities).
Il se peut qu’il y ait une dérive dans la documentation de SmartThings (par ex : numéro de chaîne qui apparaît en string au lieu de numeric). Pensez à me remonter ces dérives.

• Une commande action Rafraîchir les infos est créée lors de la synchronisation.
  Elle permet de lancer, en dehors du cron, manuellement une récupération des infos de l’appareil.

• À ne pas confondre avec la commande Actualiser qui permet à SmartThings de forcer une demande d’informations directement à l’appareil. (certaines TV ne remontent les infos que lorsque SmartThings envoie cette commande à intervalle régulier)

• La commande Exécuter une commande de sous-type message permet d’envoyer à SmartThings une commande brute ou un groupe de commande brute. En plus des commande classique déjà générées dans le plugin.
  Par exemple, pour une climatisation, il est possible de couper le son :

[
  "mode/vs/0",
  {
    "x.com.samsung.da.options":
      [
        "Volume_Mute"
      ]
  }
]

De changer la direction de ventilation :

[
  "airflow/vs/0",
  {
	"x.com.samsung.da.direction":
	  "Left_And_Right"
  }
] 

Etc… tout dépend de votre appareil et ce que vous voulez faire, et si la commande à envoyer est accessible.

En laissant la souris sur un équipement de la page générale du plugin, on peut rapidement voir les informations (nom, type, catégorie, santé…)

Modification d’une commande

Depuis la page des commandes de l’équipement, on peut voir et modifier les informations servant à SmartThings en cliquant sur le bouton orange.

Cette page s’ouvre et indique des champs différents en fonction du type de commande.
En vert, tout bas de page, il y a les informations venant de SmartThings sur cette commande. (minimum, maximum, valeur possibles…)
En rouge, quand les capabilities ne sont pas sur votre Jeedom.

Commande notification

Depuis la dernière beta de février 2022, la commande notification remonte désormais la liste, ligne par ligne, de chaque notification de l’appareil au lieu d’écraser la précédente notification et de n’afficher que la dernière notification en date. Afin de ne pas rater de notifications double/triple lors du rafraichissement des info. Les scénarios utilisant l’ancienne commande ne sont donc plus fonctionnels.
J’ai mis en place une configuration dans la modification de la commande comme ceci :

Attention à ne pas mélanger avec l’Action sur valeur gérée par le core et disponible dans la configuration de la commande

Il est possible de déclencher un scénario, une variable, une commande action.
Les tags #notif# et #dateNotif# sont créés automatiquement, inutile d’ajouter un nouveau tag.
Ils contiennent la date (#dateNotif#) et le texte (#notif#).

Il est possible de sélectionner le texte qui va déclencher l’action (par défaut: Cycle Terminé), pour faire déclencher plusieurs textes, insérez || entre chaque groupe de mots dans le champ prévu.
Si vous voulez ne déclencher l’action qu’en « lisant » les premières lignes de la valeur de la commande, entrez un nombre entier.

Page Configuration du plugin

La première configuration du plugin est documentée ici.

Les options avancées permettent de mettre à jour les capabilities en cas de modification, ajout, suppression.
Suite à la mise à jour, il faudra soit recharger la configuration ou synchroniser soit supprimer l’équipement puis synchroniser, pour que les changement soient pris en compte. Ce sera indiqué dans le changelog.

Générer l’ensemble des options permet d’avoir la liste complète des commandes de SmartThings (select).
La liste fournie par certains appareils ne coïncide pas avec la réalité de commande supportées.
Ça permet donc d’ajouter des commandes compatibles. Mais toutes ne sont pas forcément fonctionnelles du coup.
Exemple : une TV dit supporter uniquement HDMI1, alors que le port HDMI2 existe sur la TV.

• Générer l’ensemble des options des commandes listes via SmartThings : Pour les commandes action de sous-type Liste (select) uniquement. En cochant la case, la valeurs des listes de ces commandes sont complétées uniquement par les informations génériques SmartThings et non par les informations fournies par votre appareil. Intéressant dans le cas où votre appareil fournit une liste (ex: HDMI1, HDMI2), mais peut accepter d’autres choix fournis par SmartThings (ex: DisplayPort, Tuner…). Bémol : les nouveaux choix de la liste ne sont pas forcément tous reconnus. Par défaut : décoché.
• Affecter une pièce SmartThings à une pièce Jeedom : Si coché et que les pièces sont associées dans l’équipement de type Location (Emplacement), chaque nouvel appareil ajouté par Synchronisation se verra affecter la pièce Jeedom associée à la pièce SmartThings.
• Ajouter les commandes Historique : Affiche le bouton Historique et récupère les informations de l’API history pour créer une commande par équipement si il y a une historique pour cet appareil.
• Ajouter les commandes Notifications : Affiche le bouton Notifications et récupère les informations de l’API notification pour créer une commande par équipement s’il y a une notification pour cet appareil.
• Activer la météo, prévision et qualité de l’air : Récupère les informations de l’API services pour créer les commandes de météo, prévision et qualité de l’air dans l’équipement Location associé. Obligation d’avoir un équipement Location.

Équipement

Chaque appareil peut fournir des informations sur chacun de ses modules s’il en a plusieurs.
Un four à deux cavités fournit les informations de chaque cavité et des informations globales.
Un réfrigérateur-congélateur peut fournir les informations de la partie réfrigérateur, de la partie congélateur et des informations globales.

Voici l’exemple d’un congélateur :

Il est possible de modifier le nom de l’appareil, sa pièce et son emplacement SmartThings ou de le supprimer de SmartThings directement sans passer par l’application. (si suppression de SmartThings OK, suppression de Jeedom également).

• Le bouton Recréer les commandes permet de recréer les commandes infos/actions de l’appareil (en recréant toutes ses commandes ou en n’ajoutant que les manquantes). Cette option ne permet pas de créer les commandes action Rafraîchir les infos ou Santé (uniquement synchronisation).

• Le bouton Infos brutes affiche l’arbre de l’appareil dans SmartThings. C’est à partir de ces informations que les commandes info/action sont créées et que les informations remontent dans Jeedom. En cas de problème avec une commande, ou pour l’ajout ou la modification d’une commande, pensez à copier cet arbre.

• Le bouton Synchroniser les infos permet de récupérer les informations de base de l’appareil (type, catégorie) qui sont affichées dans le volet de droite.

Page Santé

La page santé remonte tous les équipements : leurs type, santé, statut, dernière communication, depuis… et date de création.

Page Historique

Cette page est accessible depuis la page des équipements et depuis chaque équipement (filtré à l’équipement en question).
Elle remonte les 50 derniers historiques de SmartThings avec la commande associée, la valeur et la date de l’évènement.
Les traductions en français peuvent être folkloriques, elles proviennent de SmartThings.

Page Notifications

Cette page est accessible depuis la page des équipements et depuis chaque équipement (filtré à l’équipement en question).
Elle remonte toutes les notifications envoyées à l’App SmartThings.
Celles générées depuis la commande action de l’équipement Location seront elles aussi listées ici.

Dashboard

Depuis la page de l’équipement, on peut choisir le Widget équipement à afficher sur le dashboard.
Celui du core Jeedom ou celui de l’appareil, s’il existe.
Actuellement, il y en a pour le lave-linge, le sèche-linge, la télévision, le réfrigérateur, le four et les climatiseurs.

Ces widgets sont séparés en 2 pages permettant d’afficher de manière ordonnées les informations et actions.
Si les informations sont disponibles, le widget les affichera.
Il est possible, depuis la page des commandes de décocher Afficher sur la commande qu’on ne souhaite pas afficher.

Le couleurs s’adaptent en fonction du thême Jeedom (dark, legacy).

Les widgets sont redimensionnables (3 tailles possibles) :

Lave-linge

Sèche-linge

A l’instar du lave-linge, le sèche-linge fournit les mêmes informations et donc affichera les mêmes types d’informations. Je vous mets les informations qui divergent :

Réfrigérateur

Télévision

Four

Pour chacune des cavités, ici 3, le widget permet de sélectionner la cavité et de visualiser ses informations et actions.

Climatiseur

Le logo dépend du type de climatiseur.

Aspirateur

Plaque de cuisson

Hub

Caméra (sonnette vidéo)

Volet

Store

Le store, lui, sur la même base de widget que le volet, se sert de la commande info « Niveau d’obscurité » shadeLevel pour indiquer le statut du store.

Le curseur sur la gauche indique la valeur actuelle et permet de modifier l’ouverture du store.
Un clic sur le volet le fermera s’il est proche de la fermeture, l’ouvrira s’il est proche de l’ouverture. Cette commande dépend de la valeur min et max attribuée à la commande.

Les boutons monter, pause et descendre ne dépendent pas de la commande info/action « Niveau dobscurité » et, du coup, montera jusqu’à la position 100% et descendra jusqu’à la position 0%.
Attention : dans le cas où vous avez une position minimale fixée dans la commande « Niveau dobscurité » (exemple : à 32%), le volet descendra jusqu’à 0% tout de même.
Vous pouvez remplacer la commande « Fermer » close en renseignant ces infos dans la modale Modification de commande :

Cela aura pour but de ne plus descendre à 0% pour fermer, mais à la valeur minimale fixée (ici 32%).

Présence mobile

Prise

Localisation

5 blocs sont disponibles sur ce widget :

• La météo :
  • Ensoleillement
  • Température
  • Humidité
  • Vitesse des vents
  • Altitude des nuages
  • Indice UV
  • Visibilité
  • Direction du vent
  • Heure de lever et coucher de soleil
• La prévision :
  • Précipitations (dans 1h, 6h et 24h)
  • Neige (dans 1h, 6h et 24h)
  • Température (dans les 24 prochaines heures)
• La qualité de l’air :
  • Indice de qualité de l’air
  • Niveau d’ozone
  • Niveau de dioxyde de soufre
  • Niveau de dioxyde d’azote
  • Indice de particule en suspension de moins de 10 microns
  • Indice de particule en suspension de moins de 25 microns
  • Niveau de monoxyde de carbone
• Les notifications :
  • Commande pour envoyer une notification
  • Liste des dernières notifications sur cette localisation
• Les infos de l’équipement :
  • Identique aux autres widgets
  • Carte de la localisation GPS

Info binaire

Un widget de commande info binaire est disponible pour reprendre cette image.
Dans les paramètres optionnels, il faut indiquer :

• la catégorie : #category# : Samsung OCF Oven. Il s’agit en fait du type de l’équipement.
• la hauteur (peut être optionnel) : #height# : 90 par défaut.
• la largeur (peut être optionnel) : #width# : 90 par défaut.