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

bookmark_border Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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 geben HomeError aus. Wir empfehlen daher, einen do-catch-Block zu verwenden, um HomeError bei diesen Aufrufen abzufangen.

Prüfen Sie beim Verarbeiten 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

Rufen Sie mit einem Verweis auf das Home-Objekt devices() auf, um ein Query der verfügbaren Geräte abzurufen. Rufen Sie die Methode batched() von Query auf. Diese gibt bei jeder Änderung der Gerätemetadaten ein Set zurück, das den aktuellen Status des Zuhauses widerspiegelt. Oder rufen Sie Query.list() auf, um eine Übersicht der verfügbaren Geräte zu erhalten. Dies ist eine Hilfsmethode, die den batched()-Stream abonniert und den ersten ausgegebenen Wert zurückgibt. Query.stream() erstellt einen Stream, der neue Werte bei Änderungen an Gerätemetadaten wie Name, Raum oder Struktur ausgibt. Intern wird batched() verwendet und es werden nur die geänderten Eigenschaften ausgegeben.

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

Dort sind die Status für jedes Gerät verfügbar und unterstützte Befehle können an das Gerät gesendet werden.

Gerätetypen abrufen

Wenn Sie die mit einem Gerät verknüpften Gerätetypen abrufen möchten, lesen Sie die types-Eigenschaft des Geräts, die ein DeviceTypeController zurückgibt.

Rufen Sie 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 ein Empty Publisher zurückgegeben, das sofort abgeschlossen wird.

Wenn das Gerät einen bestimmten Gerätetyp unterstützt, können Sie ein Handle für diesen Typ abrufen, indem Sie get() aufrufen:

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 können Sie 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ätetyp-Trait abrufen

Gerätetypen sind der Einstiegspunkt zum Lesen von Attributen, da sie ein Gerät in seine funktionalen Teile zerlegen (z. B. Endpunkte in Matter).

Außerdem werden Attributkonflikte berücksichtigt, falls ein Gerät zwei Gerätetypen hat, die beide dasselbe Attribut haben. Wenn ein Gerät beispielsweise sowohl ein Lautsprecher als auch eine dimmbare Lampe ist, hat es zwei On/Off- und zwei Level Control-Traits.

Eine andere Art von Trait-Konflikt kann auftreten, wenn ein Gerät zwei Traits mit demselben Namen hat. onOff kann sich beispielsweise auf eine Instanz des Standard-Traits OnOff oder auf eine Instanz eines vom Hersteller definierten OnOff-Traits beziehen. Um Unklarheiten darüber zu vermeiden, welches Attribut gemeint ist, verweisen Sie auf ein Attribut über eine der beiden Attributsammlungen für jeden Gerätetyp.

Verwenden Sie für Standardmerkmale, die analogen Matter-Standardclustern entsprechen, matterTraits. Beispiel: So rufen Sie ein bestimmtes Attribut für den Gerätetyp „Dimmable Light“ 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-Merkmale 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 über die traits-Property darauf, stellen Sie aber den Paketnamen des Herstellers voran:

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

Hier sehen Sie ein Beispiel für die Prüfung des Attributs OnOff aus dem On/Off-Trait des Geräts:

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 von Geräten mit einem bestimmten Merkmal abrufen

Wenn Sie eine Liste von Geräten mit einem bestimmten Merkmal abrufen möchten, müssen Sie die Geräte, die Gerätetypen der einzelnen Geräte und die Merkmale der einzelnen Gerätetypen durchlaufen. So rufen Sie beispielsweise eine Liste der Geräte im Zuhause auf, die alle das Attribut „Ein/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 Traits findest du unter Trait-Index unter iOS.

Liste von Geräten mit ähnlichen Gerätetypen abrufen

So rufen Sie eine Liste der Geräte ab, die alle Lampen in einem Zuhause darstellen:

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

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

Eine vollständige Liste der Gerätetypen und ihrer Attribute, 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 Merkmal 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äteidentifizierung für Gerätehersteller

Wenn Sie Gerätehersteller sind und Cloud-to-cloud-Geräte entwickeln, können Sie Ihre Cloud-to-cloud-Geräte über das BasicInformation-Attribut identifizieren. Dazu können Sie diese Stringfelder in die SYNC-Antwort einfügen:

• 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 erstellt wird: "matterUniqueId": "matter-device-id",

Verwenden Sie beim Eingeben dieser String-Felder Ihre Matter-Anbieter- und Produkt-IDs, sofern 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.

Im Beispiel für die SYNC-Antwort wird die Verwendung dieser Felder gezeigt:

{
  "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-Dokumentation.SYNC

Geräte- und Attributmetadaten

Geräten und Attributen in den Home-APIs sind Metadaten zugeordnet, die bei der Verwaltung der Nutzerfreundlichkeit in einer App hilfreich sein können.

Jedes Merkmal in den Home APIs enthält die Property sourceConnectivity, die Informationen zum Onlinestatus und zur Lokalität (lokales oder Remote-Routing) eines Merkmals enthält.

Primären Typ eines Geräts abrufen

Einige Geräte können über die Home-APIs mehrere Gerätetypen präsentieren. Damit Nutzern in einer App die richtigen Optionen für ihre Geräte angezeigt werden, z. B. die Gerätesteuerung und vorgeschlagene automatisierte Abläufe, ist es hilfreich, zu prüfen, ob ein Gerätetyp der primäre Typ des Geräts 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 Attribut online ist

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

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

Einige Merkmale, in der Regel smart home-Merkmale von Google, 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 für ein Gerät prüfen

Die Verbindung für ein Gerät wird tatsächlich auf der Ebene des Gerätetyps 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-Standardmerkmale sind aufgrund des lokalen Routings möglicherweise weiterhin online, cloudbasierte Merkmale jedoch nicht.

Netzwerkrouting eines Attributs prüfen

Der Ort für ein Merkmal ist auch in den Home APIs verfügbar. Das dataSourceLocality gibt an, ob das Merkmal remote (über die Cloud), lokal (über einen lokalen Hub) oder Peer-to-Peer (direkt von Gerät zu Gerät, ohne Hub) weitergeleitet wird.

Der unbekannte Ortswert unspecified ist beispielsweise möglich, wenn eine App gestartet wird und noch keine Verbindung zu einem Hub oder Server für die Gerätekonnektivität hergestellt hat. Diese Geräte sind nicht erreichbar und Interaktionsanfragen von Befehlen oder Ereignissen schlagen fehl. Es liegt im Ermessen des Kunden, wie er mit solchen Geräten umgeht.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

Netzwerkrouting für ein Gerät prüfen

Wie die Konnektivität wird die Lokalität auf Geräteebene geprüft. Der zurückgegebene Status ist eine Kombination aus der Lokalität für alle Merkmale auf diesem Gerät.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

Der Status mixed kann in einem ähnlichen Szenario wie bei der partiallyOnline-Verbindung auftreten: Einige Attribute 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 die ursprüngliche HomeDevice-Struktur unverändert und die Änderung wird im zurückgegebenen aktualisierten HomeDevice-Objekt widergespiegelt.

Namen werden abgeschnitten, wenn sie das Limit von 60 Unicode-Codepunkten (Zeichen) überschreiten. Es werden keine Fehler ausgegeben. Entwickler sind dafür verantwortlich, lange Namen zu verarbeiten. Sie können beispielsweise entscheiden, ob sie Nutzer darüber informieren möchten, dass Namen gekürzt werden.

API-Liste

Nachdem eine Instanz von Home erstellt wurde, sind die folgenden Geräte-APIs darüber zugänglich:

Sobald Sie ein HomeDevice haben, können Sie über dieses auf die folgenden APIs zugreifen: