Auf Geräte und Gerätemetadaten für iOS zugreifen

Auf Geräte-APIs kann über die Home APIs für iOS zugegriffen werden. Importieren Sie die folgenden Pakete in Ihre App:

import GoogleHomeSDK
import GoogleHomeTypes

Weitere Informationen finden Sie unter Datenmodell unter iOS.

Fehlerbehandlung

Einige Methoden in den Home APIs werfen eine HomeError. Wir empfehlen daher, einen do-catch-Block zu verwenden, um HomeError bei diesen Aufrufen zu fangen.

Prüfen Sie bei der Verarbeitung von HomeError die Felder code und message, um herauszufinden, was schiefgelaufen ist.

Alle nicht behandelten Fehler führen zum Absturz Ihrer App.

Weitere Informationen finden Sie unter Fehlerbehandlung.

Ein Beispiel finden Sie unter Befehl an ein Gerät senden.

Beispielanrufe

Geräteliste abrufen

Rufe mit einer Referenz auf das Home-Objekt devices() auf, um eine Query mit barrierefreien Geräten zu erhalten. Rufen Sie die Methode batched() von Query auf. Dabei wird bei jeder Änderung der Gerätemetadaten ein Set ausgegeben, das den aktuellen Status des Zuhauses widerspiegelt. Alternativ können Sie Query.list() aufrufen, um einen Überblick über die verfügbaren Geräte zu erhalten. Dies ist eine praktische Methode, mit der du den batched()-Stream abonnierst und den ersten gesendeten Wert zurückgibst. Query.stream() erzeugt einen Stream, der bei Änderungen der Gerätemetadaten wie Name, Raum oder Gebäude neue Werte ausgibt. Intern wird batched() verwendet und nur die geänderten Properties werden gesendet.

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

Dort können die Status der einzelnen Geräte abgerufen und unterstützte Befehle an das Gerät gesendet werden.

Gerätetypen abrufen

Um die mit einem Gerät verknüpften Gerätetypen abzurufen, lesen Sie die Property types des Geräts. Sie gibt einen DeviceTypeController zurück.

Rufe DeviceTypeController.subscribe(_:) auf, um Updates für einen bestimmten Gerätetyp zu abonnieren:

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")
    }
}

Wenn das Gerät den angegebenen Gerätetyp nicht unterstützt, wird Empty Publisher zurückgegeben und die Anfrage wird sofort abgeschlossen.

Wenn das Gerät einen bestimmten Gerätetyp unterstützt, kannst du einen Handle für diesen Typ abrufen, indem du get() aufrufst:

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

Wenn das Gerät den angegebenen Typ nicht unterstützt, wird nil zurückgegeben.

Rufen Sie DeviceTypeController.subscribeAll() auf, um eine Publisher von DeviceTypeCollection zu erhalten. Mit dieser Klasse kannst du prüfen, ob das Gerät einen bestimmten Gerätetyp hat:

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]
    }
}

Gerätetypeigenschaft abrufen

Gerätetypen sind der Einstiegspunkt für das Lesen von Merkmalen, da sie ein Gerät in seine funktionalen Teile zerlegen (z. B. Endpunkte in Matter).

Außerdem werden Kollisionen von Merkmalen berücksichtigt, wenn ein Gerät zwei Gerätetypen hat, die beide dasselbe Merkmal haben. Wenn ein Gerät beispielsweise sowohl ein Lautsprecher als auch eine dimmbare Lampe ist, hat es zwei „An/Aus“- und zwei „Steuerung der Helligkeit“-Attribute.

Eine weitere Art von Merkmalsüberschneidung kann auftreten, wenn ein Gerät zwei Merkmale mit demselben Namen hat. onOff kann sich beispielsweise auf eine Instanz des standardmäßigen OnOff-Attributs oder auf eine Instanz eines vom Hersteller definierten OnOff-Attributs beziehen. Um mögliche Unklarheiten zu vermeiden, auf welches Merkmal sich ein Verweis bezieht, sollten Sie für jeden Gerätetyp einen Verweis über eine der beiden Merkmalssammlungen einfügen.

Verwenden Sie für Standardmerkmale, also solche, die den Matter-Standardclustern entsprechen, matterTraits. So rufen Sie beispielsweise ein bestimmtes Merkmal für den Gerätetyp „Dimmbares Licht“ ab:

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

Verwenden Sie für Google-Attribute googleTraits:

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

Wenn Sie auf ein herstellerspezifisches Merkmal zugreifen möchten, verweisen Sie darauf über die Property traits, fügen Sie aber davor den Paketnamen des Herstellers ein:

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
}

Gerätestatus lesen

In diesem Beispiel wird das OnOff-Attribut aus dem Attribut „An/Aus“ des Geräts geprüft:

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
}

Liste der Geräte mit einer bestimmten Eigenschaft abrufen

Wenn Sie eine Liste der Geräte mit einer bestimmten Eigenschaft abrufen möchten, müssen Sie die Geräte, die Gerätetypen der einzelnen Geräte und die Eigenschaften der einzelnen Gerätetypen durchgehen. So rufen Sie beispielsweise eine Liste der Geräte im Zuhause auf, die alle die Eigenschaft „An/Aus“ haben:

// 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)
    }
  }
}

Eine vollständige Liste der in den Home APIs verfügbaren Merkmale finden Sie im Merkmalindex für iOS.

Liste der Geräte mit ähnlichen Gerätetypen abrufen

So rufen Sie eine Liste der Geräte auf, die alle Lampen in einem Zuhause repräsentieren:

// 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)
  }

In den Smart-Home-APIs gibt es mehrere Gerätetypen, die einen Hauptgerätetyp darstellen könnten. Es gibt beispielsweise keinen Gerätetyp „Lampe“. Stattdessen gibt es vier verschiedene Gerätetypen, die eine Lampe darstellen könnten, wie im vorherigen Beispiel gezeigt. Um einen umfassenden Überblick über die Gerätetypen in einem Zuhause zu erhalten, müssen daher mehrere Gerätetypen berücksichtigt werden.

Eine vollständige Liste der Gerätetypen und ihrer Merkmale, die in den Home APIs verfügbar sind, finden Sie unter Unterstützte Gerätetypen unter iOS.

Anbietername, Anbieter-ID oder Produkt-ID für ein Gerät abrufen

Das Attribut BasicInformationTrait enthält Informationen wie die Anbieter-ID, die Produkt-ID, den Produktnamen und die Seriennummer eines Geräts:

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")
}

Cloud-zu-Cloud-Geräteidentifikation für Gerätehersteller

Wenn Sie ein Gerätehersteller sind und Cloud-to-cloud-Geräte herstellen, können Sie die folgenden Stringfelder in die SYNC-Antwort aufnehmen, um Ihre Cloud-to-cloud-Geräte über das BasicInformation-Attribut zu identifizieren:

• Von der Connectivity Standards Alliance (CSA) ausgestellte Anbieter-ID: "matterOriginalVendorId": "0xfff1",

• Eine Produktkennzeichnung, die ein Produkt eines Anbieters eindeutig identifiziert: "matterOriginalProductId": "0x1234",

• Eine eindeutige Kennung für das Gerät, die herstellerspezifisch aufgebaut ist: "matterUniqueId": "matter-device-id",

Verwenden Sie bei der Eingabe dieser Stringfelder Ihre Matter-Anbieter- und Produkt-IDs, falls vorhanden. Wenn Sie kein CSA-Mitglied sind und Ihnen diese IDs nicht zugewiesen wurden, können Sie die Felder matterOriginalVendorId und matterOriginalProductId leer lassen und matterUniqueId als Kennung angeben.

In der Beispiel-SYNC-Antwort wird die Verwendung dieser Felder veranschaulicht:

{
  "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",
          }
        ]
      }
    ]
  }
}

Weitere Informationen finden Sie in der Cloud-to-cloud SYNC-Dokumentation.

Geräte- und Merkmalsmetadaten

Geräten und Merkmalen in den Home APIs sind Metadaten zugeordnet, die die Nutzerfreundlichkeit in einer App verbessern können.

Jede Eigenschaft in den Home APIs enthält eine sourceConnectivity-Property mit Informationen zum Onlinestatus und zur Lokalität einer Eigenschaft (lokales oder Remote-Routing).

Primären Typ eines Geräts abrufen

Einige Geräte können über die Smart-Home-APIs mehrere Gerätetypen präsentieren. Damit Nutzern in einer App die richtigen Optionen für ihre Geräte angezeigt werden (z. B. Gerätesteuerung und vorgeschlagene Automatisierungen), ist es hilfreich zu prüfen, ob ein Gerätetyp der primäre Gerätetyp ist.

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.")
  }
}

Prüfen, ob ein Merkmal online ist

Lesen Sie das Attribut connectivityState, um die Konnektivität eines Merkmals zu prüfen:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

Einige Merkmale, in der Regel Google smart home-Merkmale, werden möglicherweise als offline angezeigt, wenn das Gerät keine Internetverbindung hat. Das liegt daran, dass diese Merkmale cloudbasiert sind und kein lokales Routing haben.

Verbindung eines Geräts prüfen

Die Konnektivität eines Geräts wird auf Gerätetypebene geprüft, da einige Geräte mehrere Gerätetypen unterstützen. Der zurückgegebene Status ist eine Kombination der Verbindungsstatus für alle Merkmale auf diesem Gerät.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

Der Status partiallyOnline kann bei gemischten Gerätetypen auftreten, wenn keine Internetverbindung besteht. Matter-Standardeigenschaften sind aufgrund des lokalen Routings möglicherweise weiterhin online, aber cloudbasierte Eigenschaften sind offline.

Netzwerk-Routing eines Merkmals prüfen

Die Region für ein Merkmal ist auch in den Home APIs verfügbar. Die dataSourceLocality gibt an, ob das Attribut per Remotezugriff (über die Cloud), lokal (über einen lokalen Hub) oder Peer-to-Peer (direkt von Gerät zu Gerät, kein Hub) weitergeleitet wird.

Der Wert „Unbekannter Ort“ unspecified ist beispielsweise möglich, wenn eine App gerade gestartet wird und noch keinen Hub oder Server für die Geräteverbindung erreicht hat. Diese Geräte sind nicht erreichbar und Interaktionsanfragen von Befehlen oder Ereignissen schlagen fehl. Der Kunde muss selbst entscheiden, wie er mit solchen Geräten umgeht.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

Netzwerk-Routing für ein Gerät prüfen

Wie bei der Konnektivität wird auch die Lokalität auf Gerätetypebene geprüft. Der zurückgegebene Status ist eine Kombination aus der Lokalität aller Merkmale auf diesem Gerät.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

Ein Status von mixed kann in einem ähnlichen Szenario wie bei einer partiallyOnline-Verbindung auftreten: Einige Merkmale sind cloudbasiert, andere lokal.

Name eines Geräts ändern

Rufen Sie die Methode setName(_:) auf, um den Namen eines Geräts zu ändern:

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

Wenn Sie den Namen eines Geräts ändern, bleibt das ursprüngliche HomeDevice-Objekt unverändert. Die Änderung wird im zurückgegebenen aktualisierten HomeDevice-Objekt berücksichtigt.

API-Liste

Sobald eine Instanz von Home erstellt wurde, können Sie über sie auf die folgenden Geräte-APIs zugreifen:

Sobald du eine HomeDevice hast, kannst du über sie auf die folgenden APIs zugreifen: