Sterowanie urządzeniami w iOS

bookmark_border Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Ten przewodnik jest kontynuacją artykułu Dostęp do urządzeń i metadanych urządzeń na iOS i przedstawia dodatkowe przykłady kontroli nad urządzeniami i dostępu do nich.

Aby używać określonych typów urządzeń lub ich cech, takich jak Matter OnOffTraitużywane w wielu przykładach, należy je zaimportować:

import GoogleHomeSDK
import GoogleHomeTypes

Sprawdzanie, czy cecha obsługuje polecenie

Aby sprawdzić, czy polecenie jest obsługiwane na danym urządzeniu, użyj funkcji supports na poziomie cechy.

Aby na przykład sprawdzić, czy urządzenie obsługuje polecenie toggle atrybutu Włącz/Wyłącz:

// Check if the OnOff trait supports the toggle command.
if onOffTraitTest.supportsToggleCommand {
  print("onOffTrait supports toggle command")
} else {
  print("onOffTrait does not support stateful toggle command")
}

Wysyłanie polecenia do urządzenia

Wysyłanie polecenia jest podobne do odczytywania atrybutu stanu z cechy. Aby włączyć lub wyłączyć urządzenie, użyj polecenia OnOffTraitToggle, które w modelu danych ekosystemu Google Home jest zdefiniowane jako toggle(). Ta metoda zmienia wartość onOff na false, jeśli jest ona równa true, lub na true, jeśli jest równa false:

// Calling a command on a trait.
do {
  try await onOffTraitTest.toggle()
} catch let error as HomeError {
  // Code for handling the exception
}

W przypadku wykrycia problemu w przepływie wykonania polecenia mogą zwrócić wyjątek. Jako deweloper powinieneś używać bloku do-catch, aby odpowiednio obsługiwać te wyjątki, oraz wyświetlać użytkownikom szczegółowe informacje o przypadkach, w których błędy można naprawić. Nieprzetworzone wyjątki zatrzymają działanie aplikacji i mogą spowodować jej awarię.

Możesz też użyć poleceń off() lub on(), aby jednoznacznie ustawić stan:

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let error as HomeError {
  // Code for handling the exception
}

Po wysłaniu polecenia zmiany stanu możesz odczytać stan urządzenia, korzystając z opisu w sekcji Odczyt stanu urządzenia, aby obsłużyć go w aplikacji.

Wysyłanie polecenia z parametrami

Niektóre polecenia mogą używać parametrów takich jak te na stronie OnOffTrait lub LevelControlTrait:

// Turn off the light using the DyingLight effect.
do {
  try await onOffTraitTest.offWithEffect(
    effectIdentifier: Matter.OnOffTrait.EffectIdentifierEnum.dyingLight,
    effectVariant: 0
  )
} catch let error as HomeError {
  // Code for handling the exception
}

// Change the brightness of the light to 50%
do {
  try await levelControlTraitTest.moveToLevel(
    level: UInt8(127),
    transitionTime: 0,
    optionsMask: Matter.LevelControlTrait.OptionsBitmap(),
    optionsOverride: Matter.LevelControlTrait.OptionsBitmap()
  )
} catch let error as HomeError {
  // Code for handling the exception
}

Sprawdzanie, czy cecha obsługuje atrybut

Niektóre urządzenia mogą obsługiwać cechę Matter, ale nie konkretny atrybut. Na przykład urządzenie Cloud-to-cloud, które zostało zmapowane na Matter, może nie obsługiwać wszystkich atrybutów Matter. Aby obsłużyć takie przypadki, użyj właściwości isSupported na poziomie cechy, aby sprawdzić, czy atrybut jest obsługiwany na danym urządzeniu.

Aby na przykład sprawdzić, czy urządzenie obsługuje atrybut onOff cechy Włącz/wyłącz:

// Check if the OnOff trait supports the onOff attribute.
if onOffTrait.attributes.$onOff.isSupported {
  print("onOffTrait supports onOff state")
} else {
  print("onOffTrait is for a command only device!")
}

Niektóre atrybuty mogą być puste w specyfikacji Matter lub w schemacie Cloud-to-cloud smart home. W przypadku tych atrybutów możesz określić, czy zwrócona przez nie wartość nil jest spowodowana tym, że urządzenie nie przekazuje tej wartości, czy też wartość atrybutu to rzeczywiście nil. Aby to sprawdzić, użyj atrybutu isNullable zamiast atrybutu isSupported:

// Check if a nullable attribute is set or is not supported.
if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
  if let onOffTrait = deviceType.traits[Matter.OnOffTrait.self] {
    if onOffTrait.attributes.startUpOnOff == nil {
      if onOffTrait.attributes.$startUpOnOff.isSupported {
        print(
          "onOffTrait supports startUpOnOff and it is nil. Check the spec for the contextual meaning."
        )
      } else {
        print("onOffTrait does not support startUpOnOff!")
      }
    } else {
      print(
        "onOffTrait supports startUpOnOff and it is set to \(onOffTrait.attributes.startUpOnOff)"
      )
    }
  }
}

Aktualizowanie atrybutów cech

Jeśli chcesz zmienić wartość danego atrybutu, a żaden z poleceń atrybutu tego nie robi, atrybut może obsługiwać jawne ustawianie wartości.

Możliwość zmiany wartości atrybutu zależy od 2 czynników:

• Czy atrybut jest zapisywalny?
• Czy wartość atrybutu może się zmienić w efekcie ubocznym wysłania polecenia dotyczącego atrybutu?

Informacje te znajdziesz w dokumentacji referencyjnej dotyczącej cech i ich atrybutów.

Dlatego kombinacje właściwości, które określają, jak może się zmienić wartość atrybutu, to:

• Do odczytu i nie podlega innym poleceniom. Oznacza to, że wartość atrybutu się nie zmienia. Na przykład atrybut currentPosition elementu SwitchTrait.

• tylko do odczytu i ulegające wpływowi innych poleceń. Oznacza to, że wartość atrybutu może się zmienić tylko w wyniku wysłania polecenia. Na przykład atrybut currentLevel elementu LevelControlTrait jest dostępny tylko do odczytu, ale jego wartość może być modyfikowana przez polecenia takie jak moveToLevel.

• Możliwość zapisu i brak wpływu na inne polecenia. Oznacza to, że możesz bezpośrednio zmienić wartość atrybutu, używając funkcji update cechy, ale nie ma żadnych poleceń, które mogłyby wpłynąć na wartość atrybutu. Na przykład atrybut WrongCodeEntryLimit elementu DoorLockTrait.

• Do zapisu i modyfikowania przez inne polecenia. Oznacza to, że możesz bezpośrednio zmienić wartość atrybutu za pomocą funkcji update atrybutu, a wartość atrybutu może się zmienić w wyniku wysłania polecenia. Na przykład atrybut occupiedCoolingSetpoint obiektu ThermostatTrait można zapisać, ale też zaktualizować za pomocą polecenia setpointRaiseLower.

Przykład użycia funkcji update do zmiany wartości atrybutu

Ten przykład pokazuje, jak jawnie ustawić wartość atrybutu DoorLockTrait.wrongCodeEntryLimit.

Aby ustawić wartość atrybutu, wywołaj funkcję update atrybutu i przekaż jej funkcję aktualizacji, która ustawia nową wartość. Warto najpierw sprawdzić, czy cecha obsługuje atrybut.

Na przykład:

if doorLockTraitTest.attributes.$wrongCodeEntryLimit.isSupported {
  let _ = try await doorLockTraitTest.update {
    $0.setWrongCodeEntryLimit(3)
  }
}