Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Dostęp do urządzeń i metadanych urządzeń w iOS

Do interfejsów API urządzeń można uzyskać dostęp za pomocą interfejsów Home API na iOS. Zaimportuj do aplikacji te pakiety:

import GoogleHomeSDK
import GoogleHomeTypes

Więcej informacji znajdziesz w artykule Model danych na iOS.

Obsługa błędów

Niektóre metody w interfejsach Home API zgłaszają wyjątek HomeError, dlatego zalecamy używanie bloku do-catch do przechwytywania wyjątku HomeError w przypadku tych wywołań.

Podczas obsługi HomeError sprawdź pola code i message, aby dowiedzieć się, co poszło nie tak.

Wszelkie nieobsłużone błędy spowodują awarię aplikacji.

Więcej informacji znajdziesz w sekcji Obsługa błędów.

Przykład znajdziesz w sekcji Wysyłanie polecenia do urządzenia.

Przykładowe wywołania

Pobieranie listy urządzeń

Odwołując się do obiektu Home, wywołaj devices(), aby uzyskać Query dostępnych urządzeń. Wywołaj metodę Query's batched(), która emituje zbiór odzwierciedlający bieżący stan domu przy każdej zmianie metadanych urządzenia. Możesz też zadzwonić pod numer Query.list(), aby uzyskać przegląd dostępnych urządzeń. Jest to wygodna metoda, która subskrybuje strumień batched() i zwraca pierwszą wyemitowaną wartość. Query.stream() tworzy strumień, który emituje nowe wartości w przypadku zmian metadanych urządzenia, takich jak jego nazwa, pomieszczenie lub struktura. Wewnętrznie używa funkcji batched() i emituje tylko zmienione właściwości.

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

Możesz tam sprawdzić stan każdego urządzenia i wysyłać do nich polecenia.

W wersji 1.8 interfejsów Home API możesz ustawić, aby interfejs API reprezentował każde urządzenie wieloczęściowe jako jedno urządzenie. W tym celu ustaw parametr enableMultipartDevices metody devices() na true. Więcej informacji znajdziesz w artykule Urządzenia wieloczęściowe na iOS.

Pobieranie typów urządzenia

Aby uzyskać typy urządzeń powiązane z urządzeniem, odczytaj właściwość types urządzenia, która zwraca DeviceTypeController.

Zadzwoń pod numer DeviceTypeController.subscribe(_:), aby subskrybować aktualizacje dotyczące określonego typu urządzenia:

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

Jeśli urządzenie nie obsługuje określonego typu, zwraca natychmiast ukończony Empty Publisher.

Jeśli urządzenie obsługuje określony typ, możesz uzyskać do niego dostęp, wywołując funkcję get():

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

Jeśli urządzenie nie obsługuje określonego typu, zwraca wartość nil.

Zadzwoń pod numer DeviceTypeController.subscribeAll(), aby otrzymać Publisher w wysokości DeviceTypeCollection. Ta klasa umożliwia sprawdzenie, czy urządzenie ma określony typ:

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

Pobieranie cechy typu urządzenia

Typy urządzeń to punkt wejścia do odczytywania cech, ponieważ dzielą urządzenie na jego funkcjonalne części (np. punkty końcowe w Matter).

Uwzględniają one też kolizje cech w przypadku, gdy urządzenie ma 2 typy, z których oba mogą mieć tę samą cechę. Jeśli np. urządzenie jest zarówno głośnikiem, jak i ściemnianym oświetleniem, będzie miało 2 cechy włączania/wyłączania i 2 cechy sterowania poziomem.

Inny rodzaj kolizji cech może wystąpić, gdy urządzenie ma 2 cechy o tej samej nazwie. Na przykład onOff może odnosić się do instancji standardowego atrybutu OnOff lub do instancji atrybutu OnOff zdefiniowanego przez producenta. Aby wyeliminować wszelkie potencjalne niejasności co do tego, która cecha jest zamierzona, odwołuj się do cechy za pomocą jednej z dwóch kolekcji cech na każdym typie urządzenia.

W przypadku cech standardowych, czyli tych, które są analogiczne doMatter klastrów standardowych, użyj matterTraits. Na przykład, aby uzyskać konkretną cechę dla typu urządzenia Dimmable Light:

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

W przypadku atrybutów Google użyj googleTraits:

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

Aby uzyskać dostęp do cechy specyficznej dla producenta, odwołaj się do niej za pomocą właściwości traits, ale poprzedź ją nazwą pakietu producenta:

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
}

Odczytywanie stanu urządzenia

Spójrz na ten przykład sprawdzania atrybutu OnOff z cechy Włączanie/wyłączanie urządzenia:

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
}

Pobieranie listy urządzeń o określonej cesze

Aby uzyskać listę urządzeń o określonej cesze, musisz przejść przez urządzenia, typy urządzeń każdego urządzenia i cechy każdego typu urządzenia. Aby na przykład uzyskać listę urządzeń w domu, które mają cechę Włączanie/wyłączanie:

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
let 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)
    }
  }
}

Pełną listę cech dostępnych w interfejsach Home API znajdziesz w artykule Indeks cech w iOS.

Pobieranie listy urządzeń o podobnych typach

Aby uzyskać listę urządzeń reprezentujących wszystkie światła w domu:

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

W interfejsach Home API jest wiele typów urządzeń, które mogą reprezentować podstawowy typ urządzenia. Na przykład nie ma typu urządzenia „Światło”. Zamiast tego istnieją 4 różne typy urządzeń, które mogą reprezentować światło, jak pokazano w przykładzie powyżej. Aby uzyskać pełny obraz urządzeń wyższego poziomu w domu, należy uwzględnić wiele typów urządzeń.

Pełną listę typów urządzeń i ich cech dostępnych w interfejsach Home API znajdziesz w sekcji Obsługiwane typy urządzeń w iOS.

Pobieranie nazwy dostawcy, identyfikatora dostawcy lub identyfikatora produktu dla urządzenia

Cechy BasicInformationTrait zawierają informacje takie jak identyfikator dostawcy, identyfikator produktu, nazwa produktu i numer seryjny urządzenia:

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

Identyfikacja urządzeń w chmurze dla producentów urządzeń

Jeśli jesteś producentem urządzeń i tworzysz Cloud-to-cloud urządzenia, aby zidentyfikować swoje Cloud-to-cloud urządzenia za pomocą cechy BasicInformation, możesz uwzględnić te pola tekstowe w odpowiedzi SYNC:

Connectivity Standards Alliance (Alliance)Wydany identyfikator dostawcy:"matterOriginalVendorId": "0xfff1",
Identyfikator produktu, który jednoznacznie identyfikuje produkt sprzedawcy:"matterOriginalProductId": "0x1234",
unikalny identyfikator urządzenia, który jest tworzony w sposób określony przez producenta:"matterUniqueId": "matter-device-id",

Podczas wpisywania tych pól tekstowych używaj Matter identyfikatorów dostawcy i produktu, jeśli je masz. Jeśli nie jesteś członkiem Alliance i nie masz przypisanych tych identyfikatorów, możesz pozostawić pola matterOriginalVendorId i matterOriginalProductId puste i podać matterUniqueId jako identyfikator.

W przykładowej odpowiedzi SYNC widać użycie tych pól:

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

Więcej informacji znajdziesz w Cloud-to-cloud SYNC dokumentacji.

Metadane urządzenia i cech

Urządzenia i cechy w interfejsach Home API mają powiązane z nimi metadane, które mogą ułatwiać zarządzanie wygodą użytkowników w aplikacji.

Każda cecha w interfejsach Home API zawiera właściwość sourceConnectivity z informacjami o stanie online i lokalizacji cechy (routing lokalny lub zdalny).

Pobieranie głównego typu urządzenia

Niektóre urządzenia mogą udostępniać wiele typów urządzeń za pomocą interfejsów Home API. Aby mieć pewność, że użytkownicy widzą w aplikacji odpowiednie opcje (np. sterowanie urządzeniem i sugerowane automatyzacje) dla swoich urządzeń, warto sprawdzić, czy typ urządzenia jest jego typem podstawowym.

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

Sprawdzanie, czy cecha jest dostępna online

Odczytaj właściwość connectivityState, aby sprawdzić łączność cechy:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

Niektóre cechy, zwykle cechy Google smart home, mogą być wyświetlane offline, jeśli urządzenie nie ma połączenia z internetem. Wynika to z faktu, że te cechy są oparte na chmurze i nie mają lokalnego routingu.

Sprawdzanie połączenia urządzenia

Połączenie urządzenia jest sprawdzane na poziomie typu urządzenia, ponieważ niektóre urządzenia obsługują wiele typów. Zwracany stan jest kombinacją stanów łączności wszystkich cech na tym urządzeniu.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

Stan partiallyOnline może wystąpić w przypadku różnych typów urządzeń, gdy nie ma połączenia z internetem. Matter standardowe cechy mogą być nadal dostępne online ze względu na routing lokalny, ale cechy oparte na chmurze będą niedostępne.

Uzyskiwanie adresu IP urządzenia

Aby znaleźć adres IP urządzenia, użyj atrybutu networkInterfaces elementu GeneralDiagnosticsTrait. Adresy są zwracane jako obiekty Data, które możesz sformatować w standardowe ciągi IPv4 lub IPv6 za pomocą struktury Network:

func getIpAddresses(trait: Matter.GeneralDiagnosticsTrait) -> [String] {
  let interfaces = trait.attributes.networkInterfaces ?? []
  var ipAddresses: [String] = []

  for interface in interfaces {
    for data in interface.iPv4Addresses {
      if let ipv4 = IPv4Address(data) {
        ipAddresses.append(String(describing: ipv4))
      }
    }
    for data in interface.iPv6Addresses {
      if let ipv6 = IPv6Address(data) {
        ipAddresses.append(String(describing: ipv6))
      }
    }
  }

  return ipAddresses
}

Sprawdzanie routingu sieciowego cechy

Lokalizacja cechy jest też dostępna w interfejsach Home API. Ikona dataSourceLocality wskazuje, czy cecha jest przekazywana zdalnie (przez chmurę), lokalnie (przez lokalny hub) czy w trybie peer-to-peer (bezpośrednio z urządzenia na urządzenie, bez huba).

Nieznana wartość lokalizacji unspecified może wystąpić na przykład podczas uruchamiania aplikacji, która nie nawiązała jeszcze połączenia z hubem lub serwerem. Te urządzenia są niedostępne i nie będą reagować na żądania interakcji z poleceń lub zdarzeń. To klient decyduje, jak obsługiwać takie urządzenia.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

Sprawdzanie routingu sieciowego urządzenia

Podobnie jak łączność, lokalizacja jest sprawdzana na poziomie typu urządzenia. Zwracany stan jest kombinacją lokalizacji wszystkich cech na tym urządzeniu.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

Stan mixed może wystąpić w podobnym scenariuszu jak stan partiallyOnline: niektóre cechy są oparte na chmurze, a inne są lokalne.

Zmienianie nazwy urządzenia

Wywołaj metodę setName(_:) , aby zmienić nazwę urządzenia:

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

Podczas zmiany nazwy urządzenia oryginalna struktura HomeDevice pozostaje bez zmian, a zmiana jest odzwierciedlana w zwracanym zaktualizowanym obiekcie HomeDevice.

Nazwy zostaną obcięte, jeśli przekroczą limit 60 punktów kodowych Unicode (znaków), i nie zostaną zgłoszone żadne błędy. Deweloperzy odpowiadają za obsługę długich nazw i mogą na przykład zdecydować, czy chcą informować użytkowników o tym, że nazwy zostaną skrócone.

Sprawdzanie członkostwa urządzenia w grupie

Urządzenie fizyczne może należeć do co najmniej 1 grupy urządzeń. Aby sprawdzić, do których grup należy urządzenie, sprawdź cechę GroupMembership na urządzeniu:

let trait = try await device.traits.get(Google.GroupMembershipTrait.self)
for groupId in trait.groupObjectIDs {
  print("Device belongs to group: \(groupId)")
}