Français
Piloter une serrure à distance : quelques pièges à connaître entre le logiciel et la porte
Entre l'ordre que votre logiciel envoie à une serrure et le pêne qui bouge, où l'ordre peut-il se perdre, et que faut-il vérifier par soi-même ?
En apparence, une API de serrure connectée s'apparente à une API web : une adresse, une requête, une réponse. Mais il existe une différence de fond. L'API web fait passer ses informations d'un logiciel à un autre. L'API de serrure connectée, elle, franchit carrément une frontière : elle sort du logiciel pour atteindre le monde physique.
À l'autre bout d'un service web se trouve généralement une base de données, qui répond tout de suite à propos d'un état qui est le sien propre. À la différence, une API de serrure connectée agit sur un objet mécanique, qui fonctionne sur piles, qui sommeille la plupart du temps, qui dépend d'une connexion Wi-Fi qu'il ne maîtrise pas lui-même et qui tourne sur un firmware dont vous ne contrôlez pas toujours les évolutions.
L'API vous permet bien de lui transmettre un ordre, mais contrairement à une interaction logicielle de bout en bout, la bonne transmission de cet ordre ne permet pas de conclure à sa bonne exécution. Pour cela, vous devez aussi examiner l'appareil et vérifier son état. Dans certains cas, même, il peut arriver que les possibilités d'observation à votre disposition se trouvent assez limitées.
Nous présenterons ici à titre d'exemple quelques pièges typiques qu'il faut apprendre à connaître : une réponse qui confirme la réception de l'ordre et non son exécution, un état qui date du dernier message reçu, un même mot qui désigne une opération différente d'une marque à l'autre, et un appareil qui change sans prévenir.
Ce que l'on décrit ici, c'est ce qu'affrontent tous les développeurs qui s'adressent directement à l'API d'un fabricant. Les deux premiers pièges tiennent à la physique et ne disparaissent jamais, quel que soit l'intermédiaire. Les deux autres tiennent aux fabricants, et c'est ce que votre couche logicielle doit s'efforcer d'absorber : dans un autre article, nous expliquons comment Seam s'y prend pour corriger ou atténuer ces défauts.
L'API répond dès que l'ordre est accepté, mais le pêne bouge après
Dans un service web, une réponse positive signifie en général que l'opération a eu lieu, parce que le serveur exécute l'opération avant de répondre. Dans le cas d'une API d'appareil connecté, cette réponse annonce souvent seulement que l'ordre a été reçu par le serveur qui le relaie.
Nous l'expliquons dans notre documentation (Seam, action attempts) : « Les appareils existent dans le monde physique. Le monde physique est intrinsèquement asynchrone ». Si nous avions une réponse instantanée, cela « impliquerait l'achèvement instantané d'un processus physique de longue durée ». En bref, un paradoxe. Voilà pourquoi l'ordre de déplacer un ne renvoie pas un résultat, mais une « tentative d'action » : c'est une réponse qui confirme la prise en charge de l'ordre, mais qui ne dit pas encore s'il a été exécuté, et qu'il faut revenir consulter.
Toute intégration à une API d'appareil connecté se heurte à ce problème, quelle que soit la plateforme. Dans le cas des serrures, entre l'ordre et le pêne, il y a six maillons : votre serveur, le cloud du fabricant, un ou un installé chez le client, une liaison radio, le firmware de la serrure, et enfin le moteur qui entraîne le pêne. La réponse est renvoyée à partir du deuxième maillon. Le pêne se trouve au sixième, peut-être coincé contre une gâche mal alignée, ou piégé par un autre incident technique.

Une intégration naïve d'API afficherait « déverrouillé » sur l'écran de l'application dès l'instant où aurait été reçue la réponse du deuxième maillon. Mais dans un tel cas, l'utilisateur risquerait bien d'arriver devant la porte et de la trouver encore verrouillée. On chercherait le bug inutilement, puisque rien n'aurait véritablement échoué : l'appli aura simplement affirmé une chose que l'API n'avait jamais signifiée.
Pour savoir si le pêne a bougé, il faut encore lire l'état de la serrure. Cette lecture, elle aussi, possède quelques limites.
L'état qu'on lit n'est pas forcément celui de l'appareil, mais le dernier qu'il a remonté
Il s'ensuit un autre point important à comprendre : quand on interroge l'API d'un fabricant pour connaître l'état d'une serrure, ce n'est en général pas à la serrure elle-même que l'on pose la question. On demande en fait au service cloud de nous communiquer la dernière nouvelle qu'il a reçue de l'objet, ce qui n'est pas exactement la même chose.
La documentation de SmartThings est d'ailleurs assez illustrative sur ce point.
Elle distingue trois états de santé pour un appareil, et non deux. Un
appareil inscrit au contrôle de santé possède un intervalle de vérification,
fixé à son installation. Tant
qu'il donne signe de vie dans cet intervalle, il est considéré ONLINE, ce qui
signifie, selon SmartThings, qu'on peut « attendre de l'appareil qu'il réponde
à une commande ». S'il reste silencieux plus longtemps, l'appareil passe à
l'état UNHEALTHY, « un état intermédiaire, qui indique que l'appareil est
peut-être hors ligne ». Cet état est celui que la plateforme attribue à « une
latence réseau élevée, une pile faible, ou un événement de sabotage sur un
appareil de sécurité ». La plateforme tente alors de le joindre ; si elle n'y
parvient pas, l'appareil est finalement déclaré OFFLINE. Combien de temps
dure tout cela ? La documentation ne donne aucun
chiffre : l'intervalle dépend de l'appareil, et l'opérateur qui cherche à lire
cet état, le plus souvent, ne connaît pas la durée de cet intervalle
(SmartThings, device
health).
L'état intermédiaire est le plus honnête des trois, à vrai dire. Il ne dit pas que l'appareil est en panne, ce qui n'est peut-être pas le cas ; il dit simplement qu'à l'heure actuelle, il n'est pas possible de connaître avec certitude son état. La plateforme préfère avouer cette incertitude, plutôt que de trancher. Une intégration qui réduirait l'état d'un appareil à un booléen prendrait le risque de remonter régulièrement de fausses affirmations.
La documentation SmartThings illustre autrement encore ce problème : « quand un hub passe hors ligne, tous les appareils reliés à ce hub sont eux aussi marqués OFFLINE ». Il suffit qu'un boîtier soit débranché dans un couloir pour que des dizaines d'appareils changent d'état d'un coup, alors qu'aucun d'entre eux n'a pourtant bougé. Affirmer qu'ils seraient eux-mêmes inactifs conduirait le technicien à se précipiter pour les changer ou remplacer leurs piles. Inutilement.
Les marques du marché ont plusieurs manières de définir ce qu'on appelle « programmer un code »
Deux serrures connectées dont les brochures affirment qu'elles acceptent des codes d'accès n'accepteront pas forcément les mêmes codes. Parmi les trente-quatre commandes que la spécification Matter définit pour une serrure, seules deux sont obligatoires : verrouiller et déverrouiller. Tout ce qui concerne les codes, les horaires et les utilisateurs relève de fonctions que chaque appareil déclare ou ne déclare pas, à son bon vouloir. Les noms des appareils eux-mêmes ne suivent aucune règle commune : chaque numéro de modèle obéit à la grammaire de l'entreprise qui l'a écrit.
« Programmer un code » n'est donc pas une opération, mais une famille d'opérations dont les règles changent selon la marque : nombre de chiffres, chiffres autorisés ou positionnement autorisé pour certains chiffres, nombre d'emplacements de stockage des codes, possibilité de relire le code ou uniquement de vérifier qu'il existe, plage horaire gérée par la serrure ou à gérer dans votre logiciel, ou encore quelle procédure intervient quand tous les emplacements sont déjà pris. L'API peut accepter un ordre et la serrure le refuser, selon une logique qui varie avec chaque marque ou encore selon le fournisseur cloud utilisé. Là encore, attendez-vous à ce que la réponse de l'API n'en dise rien. On présuppose qu'on opère à l'intérieur d'un système et de ses règles, que vous êtes censé connaître. Tout est toujours fait comme si vous ne travailliez qu'avec une seule marque. Rien n'est conçu pour vous permettre de passer facilement d'un système à un autre.
L'API de Seam sert précisément à résoudre ce problème. Dans un autre article, nous révélons quelques-uns des casse-têtes que ces différences peuvent générer, et comment, chez Seam, nous construisons toutes sortes de parades pour les absorber.
Le matériel, l'API et le firmware changent, chacun à son rythme
L'intégration directe d'une API de serrures connectées vous amène à faire reposer votre code sur une pile technique qui appartient à une autre entreprise que la vôtre. Ce n'est pas votre produit, et il continue d'évoluer, à un rythme que vous ne commandez pas et sans que vous puissiez figer son fonctionnement. En branchant votre logiciel sur l'API d'un fabricant, vous intégrez une couche instable au cœur même de votre logiciel.
Les appareils connectés eux-mêmes sont installés souvent dans des bâtiments qu'on ne voit pas, et sont mis à jour à un rythme qu'on ne vous communique pas toujours. Le terrain est miné et il ne cesse de bouger.
Le matériel peut même changer sans que son nom soit modifié. Une même serrure figure ainsi dans deux dossiers de certification à quatre ans d'écart, avec une version matérielle et une génération de radio différentes, tandis qu'un même nom commercial peut désigner deux appareils différents au même moment, sur deux continents. Votre liste de compatibilité, elle, contient le nom, mais elle ne vous dit pas lequel des deux appareils le client a acheté.
L'API peut changer elle aussi, et même annoncé par le fabricant, un changement
oblige à reprendre l'intégration. Quand Allegion a remplacé sa passerelle GWE
par la GWE2, le nouveau modèle a reçu son propre identifiant, gwe2 : un
caractère de plus, et tout logiciel qui avait écrit gwe en dur, par exemple
dans l'adresse où il va chercher le firmware de la passerelle, doit être
repris (Allegion, guide d'intégration Gateway
IP).
Allegion demande d'ailleurs à ses clients de vérifier auprès de leur
fournisseur de logiciel que le nouveau modèle est pris en charge (Schlage,
ressources
ENGAGE).
La correction est minime. Encore faut-il lire les guides que publie chacun de
ses fabricants et rester en alerte au moindre de ces changements.
Enfin pour ne rien gâcher, vous découvrirez aussi que, quand l'API est servie par le boîtier chez le client, ce qu'elle sait faire dépend de la version du firmware qui tourne dans ce boîtier, et parfois de celle de la serrure qui lui est reliée. Une fonction ajoutée dans une version n'existe pas dans celles d'avant, et votre logiciel doit en tenir compte avant de supposer ce que l'appareil accepte.
Les versions s'accumulent aussi : le document qui décrit l'API d'un même bridge a connu quatorze versions de 2017 à 2024, et chacune a ajouté sans retirer. Un fabricant qui introduit un jeton d'authentification haché garde l'ancien jeton en clair, parce que les logiciels écrits contre ce jeton ne sont pas les siens et qu'il ne peut pas les mettre à jour. À raison. Du coup, votre code se retrouve à devoir savoir accepter les deux, indéfiniment (le cas concret est détaillé dans notre article sur les versions d'API).
Le parc que vous prenez en charge ne correspond pas simplement aux produits d'aujourd'hui. Vous intégrez de facto tout ce que le marché a vendu depuis le moment où vous avez commencé.
| Un service web ordinaire | Une API d'appareil | |
|---|---|---|
| Une réponse 2xx signifie | En général, que l'opération est terminée | L'ordre a été reçu |
| Lire l'état donne | La valeur actuelle | La dernière nouvelle reçue par le cloud, à une date inconnue |
| L'appareil est | Disponible ou indisponible | Disponible, indisponible, ou personne ne sait |
| La panne à prévoir | Délai d'attente dépassé, données invalides | Pile à plat, pêne coincé, boîtier débranché |
| Un fabricant propose | Une API | Souvent une API cloud, une API locale et une radio |
| Deux appareils de même fonction | Se comportent de la même façon | Diffèrent par leurs limites, leurs emplacements, leurs formats et le sens des mots |
| Le contrat change | Quand vous changez de version | Quand le fabricant le décide, ou quand un boîtier se met à jour |
La colonne de droite n'est pas une liste de griefs : c'est la liste des hypothèses à retirer du code. Chaque ligne a coûté une semaine à quelqu'un.
Aucun de ces pièges n'est un défaut des API en elles-mêmes. Celles-ci tiennent leur promesse initiale : transmettre un ordre, et renvoyer les informations dont dispose le cloud. La véritable difficulté est précisément renvoyée à vous, sur la partie où ces API ne vous font aucune promesse : que l'ordre soit arrivé jusqu'au pêne, que l'état lu soit bien celui de l'appareil en ce moment, que le mot « code » veuille dire la même chose chez telle autre marque, et que l'appareil soit encore celui qui était installé le mois dernier. Face à chacun de ces pièges, le logiciel qui commande doit développer des stratégies d'observation et faire lui-même les vérifications que l'API ne fait pas.
Vous l'aurez compris : quand on s'adresse directement à chaque fabricant, ce travail est à faire une fois par fabricant, puis à refaire chaque fois que l'un d'eux change quelque chose. C'est donc un vaste mille-feuille applicatif dont il s'agit d'assurer la maintenance, avec des surprises intempestives incessantes. Ce qu'une plateforme construit au-dessus de ces API pour l'absorber, et ce qu'elle peut ou non corriger, est un sujet que nous abordons ici.