Accéder aux appareils et aux métadonnées des appareils pour iOS

Les API d'appareils sont accessibles via les API Home pour iOS. Importez les packages suivants dans votre application :

import GoogleHomeSDK
import GoogleHomeTypes

Pour en savoir plus, consultez Modèle de données sur iOS.

Gestion des exceptions

Certaines méthodes des API Home génèrent une HomeError. Nous vous recommandons donc d'utiliser un bloc do-catch pour intercepter HomeError lors de ces appels.

Lorsque vous gérez HomeError, vérifiez ses champs code et message pour savoir ce qui s'est mal passé.

Toute erreur non gérée entraînera le plantage de votre application.

Pour en savoir plus, consultez Gestion des erreurs.

Pour obtenir un exemple, consultez Envoyer une commande à un appareil.

Exemples d'appels

Obtenir la liste des appareils

Avec une référence à l'objet Home, appelez devices() pour obtenir un Query d'appareils accessibles. Appelez la méthode batched() de Query, qui émet un ensemble reflétant l'état actuel de la maison à chaque modification des métadonnées de l'appareil. Vous pouvez également appeler Query.list() pour obtenir un aperçu des appareils disponibles. Il s'agit d'une méthode pratique qui s'abonne au flux batched() et renvoie la première valeur émise. Query.stream() génère un flux qui émet de nouvelles valeurs lors des modifications apportées aux métadonnées de l'appareil, telles que son nom, sa pièce ou sa structure. En interne, cela utilise batched() et n'émet que les propriétés modifiées.

// Get a list of all devices accessible to the user
let homeDevices = try await self.home.devices().list()

À partir de là, les états de chaque appareil sont accessibles et les commandes compatibles peuvent être envoyées à l'appareil.

Obtenir les types d'appareils

Pour obtenir les types d'appareils associés à un appareil, lisez la propriété types de l'appareil, qui renvoie un DeviceTypeController.

Appelez DeviceTypeController.subscribe(_:) pour vous abonner aux mises à jour d'un type d'appareil spécifique :

let devices = try await self.home.devices().list()
if let device = devices.first(where: { $0.id == myDeviceId }) {
  var receivedUpdate1 = false
  var receivedUpdate2 = false
  device.types.subscribe(OnOffLightDeviceType.self)
    .assertNoFailure()
    .sink { device in
      if !receivedUpdate1 {
        receivedUpdate1 = true
        Task {
          try await device.matterTraits.onOffTrait?.on()
        }
        return
      }
      if !receivedUpdate2 {
        receivedUpdate2 = true
        return
      }
      fatalError("Received unexpected update")
    }
}

Si l'appareil n'est pas compatible avec le type d'appareil spécifié, il renvoie un Empty Publisher qui se termine immédiatement.

Si l'appareil est compatible avec un type d'appareil spécifique, vous pouvez obtenir un handle pour ce type en appelant get() :

if let device = devices.first(where: { $0.id == myDeviceId }) {
  let deviceType = await device.types.get(OnOffLightDeviceType.self)
}

Si l'appareil n'est pas compatible avec le type spécifié, il renvoie nil.

Appelez DeviceTypeController.subscribeAll() pour obtenir un Publisher de DeviceTypeCollection. Cette classe vous permet de vérifier si l'appareil possède un type d'appareil particulier :

if let device = devices.first(where: { $0.id == myDeviceId }) {
  device.types.subscribeAll()
    .assertNoFailure()
    .sink { types in
      let lightDeviceType = types[OnOffLightDeviceType.self]
      let fanDeviceType = types[FanDeviceType.self]
    }
}

Obtenir une caractéristique de type d'appareil

Les types d'appareils sont le point d'entrée pour la lecture des caractéristiques, car ils décomposent un appareil en ses éléments fonctionnels (comme les points de terminaison dans Matter).

Ils tiennent également compte des collisions de caractéristiques dans le cas où un appareil comporte deux types d'appareils, qui peuvent tous deux avoir la même caractéristique. Par exemple, si un appareil est à la fois une enceinte et une ampoule à intensité variable, il possède deux caractéristiques On/Off et deux caractéristiques de contrôle du niveau.

Un autre type de collision de caractéristiques peut se produire lorsqu'un appareil possède deux caractéristiques portant le même nom. Par exemple, onOff peut faire référence à une instance du trait OnOff standard ou à une instance d'un trait OnOff défini par le fabricant. Pour éliminer toute ambiguïté potentielle quant à la caractéristique visée, faites référence à une caractéristique par le biais de l'une des deux collections de caractéristiques sur chaque type d'appareil.

Pour les traits standards, c'est-à-dire ceux qui sont analogues aux clusters standards Matter, utilisez matterTraits. Par exemple, pour obtenir un trait spécifique pour le type d'appareil "Lumière à intensité variable" :

if let dimmableLightDeviceType =
  await device.types.get(DimmableLightDeviceType.self)
{
  // Accessing standard trait on the type.
  let levelControlTrait =
    dimmableLightDeviceType.matterTraits.levelControlTrait.self
}

Pour les traits Google, utilisez googleTraits :

if let doorbellDeviceType = await device.types.get(GoogleDoorbellDeviceType.self) {
  // Accessing Google trait on the type.
  let doorbellPressTrait =
    doorbellDeviceType.googleTraits.doorbellPressTrait.self
}

Pour accéder à un trait spécifique à un fabricant, faites-y référence via la propriété traits, mais faites-la précéder du nom du package du fabricant :

let deviceType = await device1?.types.get(OnOffLightDeviceType.self)
// Accessing custom trait on the type.
if let spinnerTrait = deviceType?.traits[ExampleOrganization.SpinnerTrait.self] {
  let rpmVal = spinnerTrait.attributes.rpm
}

Lire l'état d'un appareil

Consultez cet exemple de vérification de l'attribut OnOff à partir du trait On/Off de l'appareil :

let lightDevices = devices.filter {
  $0.types.contains(OnOffLightDeviceType.self)
}
let light1 = lightDevices.first
let lightDeviceTypeOptional = await light1?.types.get(OnOffLightDeviceType.self)
if let onOffTrait = lightDeviceTypeOptional?.matterTraits.onOffTrait {
  let onOffVal = onOffTrait.attributes.onOff
}

Obtenir la liste des appareils dotés d'un trait spécifique

Pour obtenir la liste des appareils qui possèdent une caractéristique spécifique, vous devez parcourir les appareils, les types d'appareils de chacun d'eux et les caractéristiques de chaque type d'appareil. Par exemple, pour obtenir la liste des appareils de la maison qui possèdent tous le trait On/Off :

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
var allDevices = try await home.devices().list()
for device in allDevices {
  if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
    if deviceType.traits.contains(Matter.LevelControlTrait.self) {
      levelControlDevices.append(device)
    }
  }
}

Consultez Index des traits sur iOS pour obtenir la liste complète des traits disponibles dans les API Home.

Obtenir la liste des appareils ayant des types d'appareils similaires

Pour obtenir la liste des appareils qui représentent toutes les lumières d'une maison :

// Get a list of devices with similar device types (lights)
let lightDevices =
  try await self.home.devices().list().compactMap {
    $0.types.contains(DimmableLightDeviceType.self)
      || $0.types.contains(OnOffLightDeviceType.self)
      || $0.types.contains(ColorTemperatureLightDeviceType.self)
      || $0.types.contains(ExtendedColorLightDeviceType.self)
  }

Les API Home comportent plusieurs types d'appareils qui peuvent représenter un type d'appareil principal. Par exemple, il n'existe pas de type d'appareil "Lumière". En revanche, il existe quatre types d'appareils différents qui peuvent représenter une lumière, comme indiqué dans l'exemple précédent. Par conséquent, pour obtenir une vue complète d'un type d'appareil de niveau supérieur dans une maison, plusieurs types d'appareils doivent être inclus.

Consultez la page Types d'appareils compatibles sur iOS pour obtenir la liste complète des types d'appareils et de leurs caractéristiques disponibles dans les API Home.

Obtenir le nom du fournisseur, l'ID du fournisseur ou l'ID du produit pour un appareil

Le trait BasicInformationTrait inclut des informations telles que l'ID du fournisseur, l'ID du produit, le nom du produit et le numéro de série d'un appareil :

guard
  let vendorName =
    basicInfoTrait.attributes.vendorName
else {
  fatalError("Failed to get vendorName")
}
guard
  let vendorID =
    basicInfoTrait.attributes.vendorID
else {
  fatalError("Failed to get vendorID")
}
guard
  let productID =
    basicInfoTrait.attributes.productID
else {
  fatalError("Failed to get productID")
}

Identification des appareils cloud à cloud pour les fabricants d'appareils

Si vous êtes fabricant d'appareils Cloud-to-cloud et que vous souhaitez identifier vos appareils Cloud-to-cloud à l'aide du trait BasicInformation, vous pouvez inclure ces champs de chaîne dans leur réponse SYNC :

• L'ID fournisseur émis par la Connectivity Standards Alliance (CSA) : "matterOriginalVendorId": "0xfff1",

• Code produit qui identifie de manière unique un produit d'un fournisseur : "matterOriginalProductId": "0x1234",

• Identifiant unique de l'appareil, construit d'une manière spécifique au fabricant : "matterUniqueId": "matter-device-id",

Lorsque vous saisissez ces champs de chaîne, utilisez vos ID de fournisseur et de produit Matter si vous en avez. Si vous n'êtes pas membre de la CSA et que ces ID ne vous ont pas été attribués, vous pouvez laisser les champs matterOriginalVendorId et matterOriginalProductId vides et fournir matterUniqueId comme identifiant.

L'exemple de réponse SYNC montre l'utilisation de ces champs :

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting",
        ],
        "willReportState": true,
        "deviceInfo": { ... },
        "matterOriginalVendorId": "0xfff1",
        "matterOriginalProductId": "0x1234",
        "matterUniqueId": "matter-device-id",
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id",
          }
        ]
      }
    ]
  }
}

Pour en savoir plus, consultez la documentation Cloud-to-cloud SYNC.

Métadonnées de l'appareil et du trait

Les appareils et les caractéristiques des API Home sont associés à des métadonnées qui peuvent aider à gérer l'expérience utilisateur dans une application.

Chaque trait des API Home contient une propriété sourceConnectivity qui fournit des informations sur l'état en ligne et la localité (routage local ou à distance) d'un trait.

Obtenir le type principal d'un appareil

Certains appareils peuvent présenter plusieurs types d'appareils via les API Home. Pour s'assurer que les utilisateurs disposent des options appropriées dans une application (comme le contrôle des appareils et les automatisations suggérées) pour leurs appareils, il est utile de vérifier si un type d'appareil est le type principal de l'appareil.

if let deviceType =
  await device?.types.get(HumiditySensorDeviceType.self)
{
  if deviceType.metadata.isPrimaryType {
    print("Humidity Sensor is the primary type on this device.")
  } else {
    print("Humidity Sensor isn't the primary type on this device.")
  }
}

Vérifier si un trait est en ligne

Lisez la propriété connectivityState pour vérifier la connectivité d'un trait :

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

Certains traits, généralement les traits Google smart home, peuvent s'afficher hors connexion si l'appareil n'est pas connecté à Internet. En effet, ces caractéristiques sont basées sur le cloud et ne disposent pas de routage local.

Vérifier la connectivité d'un appareil

La connectivité d'un appareil est en fait vérifiée au niveau du type d'appareil, car certains appareils sont compatibles avec plusieurs types d'appareils. L'état renvoyé est une combinaison des états de connectivité de tous les traits de cet appareil.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

L'état partiallyOnline peut être observé en cas de types d'appareils mixtes lorsqu'il n'y a pas de connexion Internet. Les traits standards Matter peuvent toujours être en ligne en raison du routage local, mais les traits basés sur le cloud seront hors connexion.

Vérifier le routage réseau d'un trait

La localité d'un trait est également disponible dans les API Home. dataSourceLocality indique si le trait est routé à distance (via le cloud), localement (via un hub local) ou en peer-to-peer (directement d'appareil à appareil, sans hub).

La valeur de localité inconnue unspecified est possible, par exemple, lorsqu'une application démarre et n'a pas encore atteint un hub ou un serveur pour la connectivité de l'appareil. Ces appareils ne sont pas accessibles et les demandes d'interaction provenant de commandes ou d'événements échoueront. Il appartient au client de déterminer comment gérer ces appareils.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

Vérifier le routage réseau d'un appareil

Comme la connectivité, la localité est vérifiée au niveau du type d'appareil. L'état renvoyé est une combinaison de la localité pour tous les traits de cet appareil.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

L'état mixed peut être observé dans un scénario similaire à celui de la connectivité partiallyOnline : certains traits sont basés dans le cloud, tandis que d'autres sont locaux.

Modifier le nom d'un appareil

Appelez la méthode setName(_:) pour modifier le nom d'un appareil :

let updatedDevice = try await theDevice.setName("new device name")

Lorsque vous modifiez le nom d'un appareil, la structure HomeDevice d'origine reste la même et la modification est reflétée dans l'objet HomeDevice mis à jour renvoyé.

Liste des API

Une fois qu'une instance de Home est créée, les API d'appareil suivantes sont accessibles via celle-ci :

Une fois que vous disposez d'un HomeDevice, les API suivantes sont accessibles :