1. Einführung
Was sind die Home-APIs?
Die Google Home APIs bieten eine Reihe von Bibliotheken, mit denen Entwickler das Google Home-Ökosystem nutzen können. Mit den Home-APIs können Entwickler Apps erstellen, mit denen Smart-Home-Geräte nahtlos in Betrieb genommen und gesteuert werden können.
In diesem Video wird die mobile App, die Sie erstellen werden, kurz vorgestellt. Sehen Sie sich das Video an, während Sie das Codelab durcharbeiten.
Komponenten der Smart-Home-APIs
Die Home APIs bestehen aus:
- Device API und Structure API: Interaktion mit dem Zuhause eines Nutzers. Apps können diese APIs verwenden, um Informationen zu Geräten, Räumen und Gebäuden zu lesen (z. B. die aktuelle Thermostattemperatur) und Geräte zu steuern (z. B. den Thermostatsollwert zu ändern).
- Commissioning API: Neue Matter-Geräte lassen sich mit minimalem Aufwand in der Fabric in Betrieb nehmen (einrichten).
- Automatisierungen-API: Automatisierungen erstellen, löschen und abfragen, die im Zuhause eines Nutzers ausgeführt werden.
Vorbereitung
- Die neueste stabile Version von Xcode.
- Ein Google-Konto mit mindestens einem Gebäude im Zuhause.
- Ein iOS-Gerät mit iOS 16.4 oder höher, das mit dem Testkonto eingerichtet ist.
- Eine Apple-ID, die im Apple Developer Program registriert ist, um das Bereitstellungsprofil zu generieren.
- Ein Google-Hub, der die Home APIs unterstützt.
Lerninhalte
- So erstellen Sie eine iOS-App mit den Home APIs unter Berücksichtigung von Best Practices.
- Verwendung der Geräte- und Gebäude-APIs zur Darstellung und Steuerung eines Smart Homes.
- So fügen Sie Geräte mit der Commissioning API dem Google Home-Ökosystem hinzu.
- So erstellen Sie mit der Automatisierungen-API eine einfache Automatisierung.
2. Zuhause einrichten
Geräte vorbereiten
Der Google Home Playground bietet eine Vielzahl von vorgefertigten emulierten Smart-Home-Geräten und wird empfohlen, um das volle Potenzial der Home-APIs zu erkunden, insbesondere wenn Sie nur wenige Geräte in Ihrem Zuhause haben.
Folge der Anleitung, um dich in Google Home Playground anzumelden und die Kontoverknüpfung in der Google Home App abzuschließen. Danach solltest du die Geräte auf dem Tab „Geräte“ in der Google Home App sehen können.
3. Einrichtung
Code der Beispiel-App abrufen
Klonen Sie zuerst den Quellcode von GitHub:
git clone https://github.com/google-home/google-home-api-sample-app-ios.git
Das Beispielverzeichnis enthält für dieses Codelab zwei Branches: start und finished.
start: Der Startcode für dieses Projekt, in dem Sie Änderungen vornehmen, um das Codelab abzuschließen.finished: Der vollständige Code für dieses Codelab, der zum Überprüfen Ihrer Arbeit verwendet wird.
„Start“-Code ansehen
Wechseln Sie zu Beginn dieses Codelabs zum start-Branch Ihres geklonten Repositorys:
git checkout start
Dieser Branch enthält den Startcode für das Projekt. Sie werden diesen Code im Laufe des Codelabs ändern, um die vollständige Funktionalität zu implementieren. Die Codelab-Beispiel-App bietet eine grundlegende Struktur, die in Swift für die Interaktion mit dem Home APIs iOS SDK erstellt wurde. Sehen wir uns die wichtigsten Komponenten im start-Projekt an:
Main Entry (GoogleHomeAPISampleIOSApp): Dies ist der Haupteinstiegspunkt der App und befindet sich inGoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift. Es konfiguriert und initialisiert das SDK und richtet die primäre Benutzeroberfläche ein.Core Views (View/):MainView.swift: Die Stammansicht nach dem Start mit dem Haupt-NavigationView. Sie ist für die Auswahl des aktiven Google Home-Zuhause und die Anzeige des entsprechendenStructureViewzuständig.StructureView.swift: Hier werden die Inhalte für die aktuell ausgewählte Struktur angezeigt. Über Tabs können Sie zwischen einem Raster mit Geräten und der Liste Automatisierungen wechseln. Außerdem gibt es Menüs zum Hinzufügen von Räumen oder Geräten.DeviceView.swift: Stellt die interaktive Kachel für ein einzelnes Gerät imStructureView-Raster dar.AutomationsView.swift: Zeigt die Liste der vorhandenen Automatisierungen für die Struktur an und bietet die Möglichkeit, Automatisierungsdetails zu erstellen oder aufzurufen.
ViewModels (ViewModel/): Diese Klassen verwalten den Status und die Logik für die Ansichten.AccountViewModel.swift: Verarbeitet die Verbindung zumHome-Objekt und verwaltet den Authentifizierungsstatus.MainViewModel.swift: Verwaltet die Liste der verfügbarenStructure-Objekte und verfolgt die ausgewählte Struktur.StructureViewModel.swift: Verwaltet die Anzeige von Räumen undDeviceControl-Objekten in der ausgewählten Struktur.AutomationList.swift,AutomationViewModel.swiftusw.: Verarbeitet das Abrufen, Anzeigen, Erstellen und Verwalten von automatisierten Abläufen.
Device Controls (ViewModel/Device/):DeviceControl.swift: Eine Basisklasse zur Darstellung steuerbarer Geräte in der Benutzeroberfläche.- Spezifische Unterklassen (
LightControl.swift,FanControl.swift,OnOffPlugInUnitControl.swiftusw.): Implementieren Sie die UI-Logik, die Gerätesteuerung und die Statuszuordnung für verschiedene Gerätetypen basierend auf ihren Attributen. DeviceControlFactory.swift: Verantwortlich für das Erstellen der entsprechendenDeviceControl-Unterklasse für ein bestimmtesHomeDevice.
Commissioning (Commissioning/):CommissioningManager.swift: Enthält die Logik für die Verwaltung des Ablaufs zur Inbetriebnahme von Matter-Geräten.
Utilities & UX (Utils/, UX/, Storage/): Enthält Hilfscode für UI-Elemente (Farben, Dimensionen), Fehlerbehandlung, Datenspeicherung (SelectedStructureStorage.swift) und andere Dienstprogramme.
In diesem Codelab finden Sie Kommentare wie TODO oder auskommentierte Codeblöcke und Warnungen im start-Projekt. Diese Markierungen kennzeichnen die Abschnitte, in denen Sie Code hinzufügen oder auskommentieren müssen, um die erforderliche Funktionalität zu implementieren.
Apple-Bereitstellungskonfigurationsdateien erstellen
Folgen Sie der Anleitung zum Erstellen von Apple-Bereitstellungskonfigurationsdateien, um App Attest zu konfigurieren. Nach der Einrichtung kann die App nur auf einem echten Gerät und nicht in einem Simulator bereitgestellt werden.
Authentifizierung einrichten
Um die OAuth-Client-ID zu erhalten und die Home APIs zu aktivieren, müssen Sie sich zuerst in Google Cloud anmelden und entweder ein neues Projekt erstellen oder ein vorhandenes auswählen. Folge dann der Anleitung, um die OAuth-Client-ID zu generieren, die Home APIs zu aktivieren und dein Konto der Zulassungsliste hinzuzufügen.
SDK einrichten
Rufen Sie das Home APIs iOS SDK ab und konfigurieren Sie es anhand der Einrichtungsanleitung unter SDK einrichten. Denken Sie daran, HOME_API_TODO_ADD_APP_GROUP durch Ihre eigene App-Gruppe zu ersetzen.
Projekt erstellen und ausführen
Nachdem Sie das Projekt mit dem start-Branch erstellt und ausgeführt haben, sollte ein TODO-Dialogfeld und ein Bildschirm mit der Meldung „Anmeldung erforderlich“ angezeigt werden. Die Interaktion mit den Home APIs wird in den folgenden Abschnitten implementiert.
Hinweis: Suchen Sie im Projekt nach dem Text, der im Dialogfeld angezeigt wird, um den Code zu finden, der geändert werden muss. Suchen Sie beispielsweise nach „TODO: initialize Home“.
4. Initialisierung
Home initialisieren
Bevor Sie eine der Home APIs für iOS verwenden können, müssen Sie Home in Ihrer App initialisieren. Home ist der Einstiegspunkt der obersten Ebene für das SDK und bietet Zugriff auf alle Entitäten in der Struktur des Nutzers. Wenn Sie alle Entitäten eines bestimmten Typs anfordern, gibt die API ein Query-Objekt zurück, mit dem Sie auswählen können, wie die Ergebnisse empfangen werden sollen. Entferne in GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift den Kommentar und die Benachrichtigung in connect(), um die Initialisierung des Zuhauses zu implementieren.
/// TODO: initialize Home
/// Remove comments to initialize Home and handling permission.
private func connect() {
Task {
do {
self.home = try await Home.connect()
} catch {
Logger().error("Auth error: \(error).")
}
}
}
Berechtigung zur Verwendung der Home-APIs
Der Einwilligungsbildschirm wird angezeigt, wenn Sie die App ausführen. Wählen Sie die Google Home-Struktur und das Konto aus, das auf der Zulassungsliste Ihres Google Cloud-Projekts steht.
5. Geräte und Strukturen
Räume und Geräte abrufen
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Benachrichtigung in getRoomsAndDevices(), um die Räume und Geräte in der ausgewählten Struktur mit home.rooms() bzw. home.devices() abzurufen.
/// TODO: get rooms and devices
/// Remove comments to get the rooms and devices from home entry
private func getRoomsAndDevices(){
self.home.rooms().batched()
.combineLatest(self.home.devices().batched())
.receive(on: DispatchQueue.main)
.catch { error in
Logger().error("Failed to load rooms and devices: \(error)")
return Just((Set<Room>(), Set<HomeDevice>()))
}
.map { [weak self] rooms, devices in
guard let self = self else { return [] }
self.hasLoaded = true
return self.process(rooms: rooms, devices: devices)
}
/// receive from .map and .assign() to publisher entries
.assign(to: &self.$entries)
}
Die Funktion process() sorgt zuerst dafür, dass sich die Geräte im selben Raum befinden, bevor sie als HomeDevices über DeviceControl und DeviceControlFactory interagieren.
Hinweis: Wenn Ihr Gerät nicht in der DeviceControlFactory aufgeführt ist, wird es als „Nicht unterstützt“ angezeigt. Weitere Informationen zu unterstützten Geräten finden Sie auf der Seite Unterstützte Gerätetypen unter iOS.
Mit einem Gerät interagieren
Der Stecker outlet1 ist anfangs inaktiv, wenn Sie auf die Geräte tippen oder wischen. Wenn Sie die Interaktion mit dem Gerät aktivieren möchten, suchen Sie nach GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift und entfernen Sie den Kommentar und die Benachrichtigung in der Funktion primaryAction().
/// TODO: primary action of OnOffPlug
/// Toggles the plug; usually provided as the `action` callback on a Button.
public override func primaryAction() {
self.updateTileInfo(isBusy: true)
Task { @MainActor [weak self] in
guard
let self = self,
let onOffPluginUnitDeviceType = self.onOffPluginUnitDeviceType,
let onOffTrait = onOffPluginUnitDeviceType.matterTraits.onOffTrait
else { return }
do {
try await onOffTrait.toggle()
} catch {
Logger().error("Failed to to toggle OnOffPluginUnit on/off trait: \(error)")
self.updateTileInfo(isBusy: false)
}
}
}
Die Funktion primaryAction() in der Klasse OnOffPlugInUnitControl schaltet den Ein/Aus-Status eines Smart-Plug oder eines beliebigen Geräts um, das durch OnOffPluginUnitDeviceType dargestellt wird.
Weitere Beispiele für die Gerätesteuerung finden Sie unter GoogleHomeAPISampleIOS/ViewModel/Device.
Neuen Raum erstellen
Mit der Structure API können Räume erstellt und gelöscht sowie Geräte zwischen Räumen übertragen werden.
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Benachrichtigung in addRoom().
/// TODO: add room
/// Add a new room in a given structure.
func addRoom(name: String, structure: Structure) {
Task {
do {
// The view will be updated with the values from the devices publisher.
_ = try await structure.createRoom(name: name)
} catch {
Logger().error("Failed to create room: \(error)")
}
}
}
Wenn Sie einen neuen Raum mit structure.createRoom() erstellen möchten, gehen Sie links oben zum Pluszeichen + > „Raum hinzufügen“. Geben Sie den Namen des neuen Chatrooms ein und klicken Sie auf „Chatroom erstellen“. Der neue Raum wird nach einigen Sekunden angezeigt.
Gerät in einen anderen Raum verschieben
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Benachrichtigung in moveDevice().
/// TODO: move device
/// Move a device into a different room.
func moveDevice(device deviceID: String, to roomID: String, structure: Structure) {
Task {
do {
_ = try await structure.move(device: deviceID, to: roomID)
} catch {
Logger().error("Failed to move to room: \(error)")
}
}
}
Wenn du das Gerät mit structure.move() umstellen möchtest, halte es gedrückt, wähle „In einen anderen Raum verschieben“ aus und wähle den neuen Raum aus.
Leeren Raum löschen
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Benachrichtigung in removeRoom().
/// TODO: delete room
/// Delete an empty room in a given structure.
func removeRoom(id: String, structure: Structure) {
Task {
do {
// The view will be updated with the values from the devices publisher.
_ = try await structure.deleteRoom(id: id)
} catch {
Logger().error("Failed to remove room: \(error)")
}
}
}
Wenn Sie einen leeren Raum mit structure.deleteRoom() löschen möchten, klicken Sie rechts neben dem Namen des Raums auf das Papierkorbsymbol und bestätigen Sie die Aktion. Es können nur leere Räume gelöscht werden.
Hinweis: Wenn Sie das Gerät zurückbewegen, wird ein leerer Raum erstellt.
6. Inbetriebnahme
Hinweis: Für diesen Abschnitt sind ein Google-Hub und ein Matter-Gerät erforderlich. Achte darauf, dass der Google Nest Hub in deinem Zuhause online und erreichbar ist. Wenn Sie kein Matter-Gerät haben, können Sie stattdessen die App Matter Virtual Device verwenden.
Matter-Gerät hinzufügen
Mit der Commissioning API kann deine App dem Zuhause und dem Google-Konto des Nutzers neue Matter-Geräte hinzufügen. So können Nutzer die Einrichtung direkt in Ihrer App vornehmen.
Entfernen Sie in GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift den Kommentar und die Benachrichtigung in addMatterDevice().
/// TODO: add Matter Device
/// Starts the Matter device commissioning flow to add the device to the user's home.
/// - Parameters:
/// - structure: The structure to add the device to.
/// - add3PFabricFirst: Whether to add the device to a third party fabric first.
public func addMatterDevice(to structure: Structure, add3PFabricFirst: Bool) {
self.isCommissioning = true
/// pass if it's 1p or 3p commissioning
let userDefaults = UserDefaults(
suiteName: CommissioningManager.appGroup)
userDefaults?.set(
add3PFabricFirst, forKey: CommissioningUserDefaultsKeys.shouldPerform3PFabricCommissioning)
Task {
do {
try await structure.prepareForMatterCommissioning()
} catch {
Logger().error("Failed to prepare for Matter Commissioning: \(error).")
self.isCommissioning = false
return
}
// Prepare the Matter request by providing the ecosystem name and home to be added to.
let topology = MatterAddDeviceRequest.Topology(
ecosystemName: "Google Home",
homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
)
let request = MatterAddDeviceRequest(topology: topology)
do {
Logger().info("Starting MatterAddDeviceRequest.")
try await request.perform()
Logger().info("Completed MatterAddDeviceRequest.")
let commissionedDeviceIDs = try structure.completeMatterCommissioning()
Logger().info("Commissioned device IDs: \(commissionedDeviceIDs).")
} catch let error {
structure.cancelMatterCommissioning()
Logger().error("Failed to complete MatterAddDeviceRequest: \(error).")
}
self.isCommissioning = false
}
}
Wenn du einen neuen Raum mit structure.prepareForMatterCommissioning() erstellen möchtest, wähle links oben das „+“-Symbol > Gerät zu Google Fabric hinzufügen aus. Dazu wird MatterAddDeviceRequest verwendet, um das Matter-Gerät in deinem Raum hinzuzufügen. Nachdem Sie den Raum und den Gerätenamen ausgewählt haben, wird das Gerät auf dem Bildschirm „Geräte“ angezeigt.
7. Automatisierung
Alle Automatisierungen im Gebäude ansehen
Tippen Sie in der unteren Navigationsleiste auf Automatisierte Abläufe. Darin werden alle Automatisierungen in Ihrer Struktur mit structure.listAutomations() aufgeführt.
Hinweis: Wenn Sie noch keine Smart-Home-Automatisierungen eingerichtet haben, wird die Meldung „Füge eine Automatisierung hinzu, um loszulegen“ angezeigt.
Automatisierung erstellen
Nachdem Sie sich mit den Geräte- und Struktur-APIs und dem Hinzufügen eines neuen Geräts vertraut gemacht haben, ist es an der Zeit, eine neue Automatisierung mit der Automation API zu erstellen.
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift den Kommentar, die Benachrichtigung und den leeren automatisierten Ablauf in lightAutomation().
/// TODO: create automation
/// - Parameter devices: devices in current selected structure
/// - Returns: the automation object to be created
/// This automation will turn off the light after 5 seconds.
public func lightAutomation(devices: Set<HomeDevice>) async throws -> any DraftAutomation {
let light = devices.first { $0.name == "light2" }
guard let light else {
Logger().error("Unable to find light device with name light2")
throw HomeError.notFound("No devices support OnOffLightDeviceType")
}
return automation(
name: "Turn off light after 5 seconds",
description:
"""
Turns off light2 after it has been on for 5 seconds.
"""
) {
let onOffStarter = starter(light, OnOffLightDeviceType.self, OnOffTrait.self)
onOffStarter
condition {
onOffStarter.onOff.equals(true)
}
delay(for: Duration.seconds(5))
action(light, OnOffLightDeviceType.self) {
OnOffTrait.off()
}
}
}
Wenn Sie eine Automatisierung erstellen möchten, die das Licht fünf Sekunden nach dem Einschalten ausschaltet, rufen Sie die Automatisierungsansicht auf und klicken Sie auf die Schaltfläche + Hinzufügen. Wähle dann Licht nach 5 Sekunden ausschalten aus. Die Automatisierungsdetails, einschließlich starter, condition und action, werden angezeigt. Klicken Sie auf Speichern, um die Automatisierung durch structure.createAutomation() zu erstellen.
Hinweis: Welche Automatisierungen verfügbar sind, hängt von den Geräten in deinem Zuhause ab. Wenn keine verfügbaren Automatisierungen angezeigt werden, benenne dein Lichtgerät in „light2“ um.
Kehren Sie zum Tab „Geräte“ zurück und schalten Sie die Lampe mit dem Namen „light2“ ein. Es schaltet sich nach fünf Sekunden automatisch aus.
Eine Automatisierung besteht aus folgenden Komponenten:
- Auslöser:Das ist ein Ereignis, das die Automatisierung auslöst. In diesem Beispiel würde die Automatisierung starten, sobald sich
OnOffTraitändert. - Bedingung:Hier wird geprüft, ob das Startergerät bestimmte Anforderungen erfüllt. In diesem Fall wird die Automatisierung ausgeführt, wenn das Licht eingeschaltet ist.
- Aktion:Das ist die Automatisierung, die ausgeführt werden soll, aber nur, wenn der Starter die Anforderungen erfüllt. Wenn die Bedingungen erfüllt sind, wird das Licht ausgeschaltet.
Weitere Beispiele findest du auf der Seite Beispielautomatisierungen.
Automatisierung löschen
Die Methode structure.deleteAutomation() wird aufgerufen, wenn Sie auf einer vorhandenen Automatisierung nach links wischen und auf das Papierkorbsymbol tippen, um sie aus Ihrer Struktur zu entfernen.
8. Glückwunsch
Glückwunsch! Sie haben mithilfe der Home APIs für iOS eine einfache Smart-Home-App erstellt.
Erreicht:
- Initialisierung: Sie haben Ihre App über
Home.connect()mit dem Google Home-Ökosystem verbunden. - Berechtigungen: Hier werden die Nutzerauthentifizierung und ‑autorisierung für den Zugriff auf Smart-Home-Daten verwaltet.
- Geräte und Strukturen: Mit
home.rooms()undhome.devices()abgerufene und angezeigte Räume und Geräte. - Gerätesteuerung: Implementierte Geräteinteraktion, z. B. das Umschalten des Status eines
OnOffPluginUnitDeviceTypedurch Aufrufen von Befehlen für seine Eigenschaften. - Verwaltung der Struktur: Es wurden Funktionen zum Erstellen neuer Räume (
structure.createRoom()), zum Verschieben von Geräten zwischen Räumen (structure.move()) und zum Löschen leerer Räume (structure.deleteRoom()) hinzugefügt. - Inbetriebnahme: Der Inbetriebnahmeablauf des SDK wurde integriert, um neue Matter-Geräte (
MatterAddDeviceRequest) hinzuzufügen. - Automatisierung: Wir haben uns angesehen, wie Automatisierungen in einer Struktur aufgelistet, erstellt (
structure.createAutomation()) und gelöscht (structure.deleteAutomation()) werden.
Sie haben jetzt ein grundlegendes Verständnis dafür, wie Sie die Home-APIs nutzen können, um umfassende Smart-Home-Steuerungsfunktionen auf iOS zu entwickeln.
Nächste Schritte:
- Steuern Sie andere Gerätetypen, die in der Beispiel-App enthalten sind (z. B. Lampen, Ventilatoren und Jalousien).
- Hier finden Sie weitere Informationen zu den verschiedenen Merkmalen und Befehlen, die für verschiedene Geräte verfügbar sind.
- Experimentieren Sie mit komplexeren automatisierten Abläufen, indem Sie verschiedene Auslöser, Bedingungen und Aktionen verwenden.
- Weitere erweiterte Funktionen und Details finden Sie in der Dokumentation zu Home-APIs.
Gut gemacht!