Les API Home pour Android présentent tous les appareils de l'écosystème Google Home dans un modèle de données unifié. Ce modèle de données couvre tous les types d'appareils (de Google Nest ou de fabricants tiers), quelle que soit la technologie de maison connectée sous-jacente (comme Matter ou Cloud-to-cloud), et fournit une surface d'API commune pour créer des expériences utilisateur pour les développeurs smart home et d'applications mobiles.
Types d'appareil
Les types d'appareils présentés dans les API Home sont une unification des modèles de données Matter et Cloud-to-cloud. Certains sont directement dérivés de Matter, d'autres sont une extension des types d'appareils Matter et d'autres encore sont dérivés de Cloud-to-cloud.
Les types d'appareils contiennent des caractéristiques utilisées pour contrôler et gérer les appareils. Comme les types d'appareils, les caractéristiques sont dérivées des clusters Matter et des caractéristiques Cloud-to-cloud, et présentées dans un format commun semblable à celui des clusters Matter. Dans les API Home, les caractéristiques dérivées de Matter sont appelées traits, et non clusters.
Par conséquent, les types d'appareils et les caractéristiques des API Home sont destinés à être Matter-first. Un type d'appareil ou un trait Matter est prioritaire sur un analogue Cloud-to-cloud.
Pour obtenir la liste des types d'appareils et de leurs caractéristiques, consultez Types d'appareils compatibles sur Android.
Caractéristiques
Les versions Kotlin des traits sont générées pour être utilisées dans les API Home et contiennent des fonctionnalités supplémentaires spécifiques aux API Home (qui ne se trouvent pas dans Matter ou Cloud-to-cloud). Par exemple, chaque trait dispose de méthodes permettant de vérifier s'il est compatible avec un attribut ou une commande spécifique. Cela est utile pour déterminer si la lecture de l'état ou certaines actions peuvent être effectuées sur l'appareil d'un utilisateur, car tous les appareils d'un même type ne sont pas censés disposer des mêmes fonctionnalités.
Chaque trait est contenu dans son propre espace de noms et doit être importé individuellement pour être utilisé.
Par exemple, pour utiliser le trait On/Off Matter et le type d'appareil "On/Off Plug-in Unit", importez les packages suivants dans votre application :
import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice
Pour un type d'appareil Garage (de la maison connectée Google), incluez une combinaison de caractéristiques Matter et Google :
import com.google.home.google.LockUnlock
import com.google.home.matter.standard.DoorLock
import com.google.home.matter.standard.GoogleGarageDevice
Android Studio dispose d'une fonctionnalité de saisie semi-automatique et gère souvent les noms de packages complets pour vous lorsque vous ajoutez des lignes import aux fichiers sources de votre projet. Cependant, les noms de packages ne sont pas cohérents entre tous les types d'appareils et toutes les caractéristiques. Consultez la documentation de référence pour vérifier le nom de package correct pour chaque DeviceType ou Trait.
La plupart des caractéristiques sont compatibles avec les automatisations, et certaines ne sont disponibles que pour les automatisations. Pour en savoir plus, consultez Compatibilité des caractéristiques de l'API Automation sur Android.
Composition par type d'appareil
Les API Home sont compatibles avec la plupart des clusters d'applications Matter en tant que caractéristiques dans le modèle de données. Les clusters de configuration de bas niveau qui n'offrent pas d'utilité directe aux utilisateurs finaux, tels que Binding, ne sont pas exposés via les API Home.
Les caractéristiques dérivées des caractéristiques de maison connectée Cloud-to-cloud portent généralement le même nom dans Cloud-to-cloud et dans les API Home, comme dans l'exemple d'OpenClose. D'autres sont représentés comme des extensions de caractéristiques Matter, créées à l'aide d'extensions Matter spécifiques au fabricant. Ces caractéristiques comblent l'écart pour une caractéristique smart home dont les fonctionnalités sont réparties entre le SDK Matter et l'écosystème Google Home. Les types d'appareils Google*, qui proviennent de Cloud-to-cloud, mais n'ont pas encore d'équivalents Matter, en sont un exemple spécifique.
Les types d'appareils sont composés de caractéristiques provenant d'une ou des deux sources, Matter ou Cloud-to-cloud.
Par exemple, le type d'appareil Ventilateur est composé des deux et comporte trois traits :
- Le trait Matter
Identifyfournit toutes les fonctionnalités de MatterIdentify. - L'attribut
FanControlMatter fournit toutes les fonctionnalités de l'attribut MatterFanControl. - Le trait Google
ExtendedFanControlfournit toutes les fonctionnalités du trait Google smart homeFanSpeedqui ne sont pas couvertes par le traitFanControlMatter.
Ce type de composition de caractéristiques fournit un modèle flexible pour l'ensemble des fonctionnalités d'un type d'appareil, en faisant abstraction des modèles de données smart home sous-jacents.
Groupes d'appareils
Un groupe d'appareils représente un ensemble d'appareils défini par l'utilisateur au sein d'une même structure. Les groupes d'appareils sont représentés par l'entité DeviceGroup, qui est distincte de HomeDevice.
Pour en savoir plus sur les groupes d'appareils, consultez API Structure.