Jenis perangkat Bel Pintu diimplementasikan menggunakan dua trait:
PushAvStreamTransportTrait,
yang menangani transportasi streaming audio dan video menggunakan protokol berbasis push, dan
WebRtcLiveViewTrait,
yang memberikan kemampuan untuk mengontrol live stream dan talkback.
Selalu periksa dukungan atribut dan perintah untuk perangkat sebelum menggunakan fitur atau mencoba memperbarui atribut. Lihat Mengontrol perangkat di iOS untuk mengetahui informasi selengkapnya.
| Jenis Perangkat Home API | Sifat | Aplikasi Contoh Swift | Kasus Penggunaan |
|---|---|---|---|
Bel pintu
Perangkat yang diaktifkan oleh tombol di luar pintu yang menghasilkan sinyal yang dapat didengar dan/atau dilihat, yang digunakan untuk meminta perhatian orang yang berada di sisi lain pintu. Bel pintu mungkin memiliki fitur livestream yang dapat diakses, talkback dua arah, atau peristiwa deteksi. |
Ciri Wajib google PushAvStreamTransportTrait google WebRtcLiveViewTrait |
Bel pintu |
Memulai livestream
Untuk memulai livestream, kirim string Session Description Protocol (SDP) ke metode
startLiveView(offerSdp:)
trait
WebRtcLiveViewTrait, yang menampilkan tiga nilai:
- SDP untuk sesi.
- Durasi sesi dalam detik.
- ID sesi, yang dapat digunakan untuk memperpanjang atau menghentikan sesi.
public func sendOffer(offerSdp: String) async throws
-> (answerSdp: String, mediaSessionId: String, liveViewDuration: TimeInterval)
{
do {
Logger.info("Sending StartLiveView command...")
let response = try await liveViewTrait.startLiveView(
offerSdp: offerSdp
)
Logger.info("Received StartLiveView response: \(response)")
return (
answerSdp: response.answerSdp,
mediaSessionId: response.mediaSessionId,
liveViewDuration: TimeInterval(response.liveSessionDurationSeconds)
)
} catch {
Logger.error("Failed to send StartLiveView command: \(error)")
throw error
}
}
Memperpanjang livestream
Livestream memiliki durasi preset yang akan berakhir setelah durasi tersebut. Untuk memperpanjang durasi streaming aktif, kirim permintaan perpanjangan menggunakan metode
extendLiveView(mediaSessionId:optionalArgsProvider:):
public func extendLiveView(mediaSessionId: String) async throws {
do {
Logger.info("Extending live view...")
let extendedDuration = try await liveViewTrait.extendLiveView(mediaSessionId: mediaSessionId)
Logger.info("Extended live view for \(extendedDuration.liveSessionDurationSeconds) seconds.")
} catch {
Logger.error("Failed to extend live view: \(error)")
throw error
}
}
Memulai dan menghentikan TalkBack
Untuk memulai talkback, panggil metode startTalkback(mediaSessionId:optionalArgsProvider:) dari
WebRtcLiveViewTrait
trait.
Untuk berhenti, gunakan stopTalkback(mediaSessionId:).
public func toggleTwoWayTalk(isOn: Bool, mediaSessionId: String) async throws {
do {
Logger.info("Toggling twoWayTalk to \(isOn ? "ON" : "OFF")...")
if isOn {
try await liveViewTrait.startTalkback(mediaSessionId: mediaSessionId)
} else {
try await liveViewTrait.stopTalkback(mediaSessionId: mediaSessionId)
}
} catch {
throw HomeError.commandFailed("Failed to toggle twoWayTalk: \(error)")
}
}
Mengaktifkan dan menonaktifkan kemampuan perekaman
Untuk mengaktifkan kemampuan perekaman kamera, teruskan
TransportStatusEnum.Active
ke metode
setTransportStatus(transportStatus:optionalArgsProvider:)
trait
PushAvStreamTransportTrait. Untuk menonaktifkan kemampuan merekam, teruskan
TransportStatusEnum.Inactive.
Dalam contoh berikut, kita menggabungkan panggilan ini dalam satu panggilan yang menggunakan
Boolean untuk mengaktifkan/menonaktifkan kemampuan perekaman:
public func toggleIsRecording(isOn: Bool) {
self.uiState = .loading
guard let pushAvStreamTransportTrait else {
Logger.error("PushAvStreamTransportTrait not found.")
return
}
Task {
do {
try await pushAvStreamTransportTrait.setTransportStatus(
transportStatus: isOn ? .active : .inactive)
if isOn {
do {
self.player = try self.createWebRtcPlayer()
} catch {
Logger.error("Failed to initialize WebRtcPlayer: \(error)")
self.uiState = .disconnected
return
}
await self.player?.initialize()
self.uiState = .live
} else {
self.player = nil
self.uiState = .off
}
} catch {
Logger.error("Failed to toggle onOff: \(error)")
}
}
}
Mengaktifkan atau menonaktifkan kemampuan perekaman kamera sama dengan mengaktifkan atau menonaktifkan video kamera. Jika video kamera aktif, kamera akan merekam (untuk tujuan peristiwa dan klip terkait).
Jika kemampuan perekaman dinonaktifkan (video kamera nonaktif):
- Kamera masih dapat ditampilkan sebagai online sesuai dengan
connectivityStatejenis perangkat. - Livestream tidak dapat diakses, dan kamera tidak mendeteksi peristiwa cloud apa pun.
Periksa apakah kemampuan perekaman diaktifkan
Untuk menentukan apakah kemampuan perekaman kamera diaktifkan, periksa apakah ada koneksi yang aktif. Contoh berikut menentukan dua fungsi untuk melakukannya:
public func isDeviceRecording() -> Bool {
guard let pushAvStreamTransportTrait else {
Logger.error("PushAvStreamTransportTrait not found.")
return false
}
guard
let hasActiveConnection =
pushAvStreamTransportTrait
.attributes
.currentConnections?
.contains(where: { $0.transportStatus == .active })
else {
return false
}
return hasActiveConnection
}
Setelan audio
Berbagai setelan audio kamera dapat dikontrol melalui Home API.
Mengaktifkan atau menonaktifkan mikrofon
Untuk mengaktifkan atau menonaktifkan mikrofon perangkat, perbarui atribut
microphoneMuted
dari trait CameraAvStreamManagementTrait menggunakan fungsi
setMicrophoneMuted bawaan:
// Turn the device's microphone on or off
func setMicrophone(on: Bool) async {
do {
_ = try await self.cameraAvStreamManagementTrait?.update {
$0.setMicrophoneMuted(!on)
}
} catch {
// Error
}
}
Mengaktifkan atau menonaktifkan rekaman audio
Untuk mengaktifkan atau menonaktifkan perekaman audio untuk perangkat, perbarui atribut
recordingMicrophoneMuted
dari trait CameraAvStreamManagementTrait menggunakan fungsi
setRecordingMicrophoneMuted bawaan:
// Turn audio recording on or off for the device
func setAudioRecording(on: Bool) async {
do {
_ = try await self.cameraAvStreamManagementTrait?.update {
$0.setRecordingMicrophoneMuted(!on)
}
} catch {
// Error
}
}
Menyesuaikan volume speaker
Untuk menyesuaikan volume speaker perangkat, perbarui atribut
speakerVolumeLevel
dari trait CameraAvStreamManagementTrait menggunakan fungsi
setSpeakerVolumeLevel bawaan:
// Adjust the camera speaker volume
func setSpeakerVolume(to value: UInt8) async {
do {
_ = try await cameraAvStreamManagementTrait.update {
$0.setSpeakerVolumeLevel(value)
}
} catch {
// Error
}
}
Setelan lainnya
Berbagai setelan kamera lainnya dapat dikontrol melalui API Home.
Mengaktifkan atau menonaktifkan penglihatan malam
Untuk mengaktifkan atau menonaktifkan penglihatan malam untuk kamera, gunakan TriStateAutoEnum
untuk memperbarui
atribut nightVision
dari sifat CameraAvStreamManagementTrait menggunakan fungsi
setNightVision bawaan:
// Turn night vision on or off
func setNightVision(
to value: Google.CameraAvStreamManagementTrait.TriStateAutoEnum
) async {
do {
_ = try await cameraAvStreamManagementTrait.update {
$0.setNightVision(value)
}
} catch {
// Error
}
}
Mengubah kecerahan LED status
Untuk mengubah kecerahan LED status, gunakan
ThreeLevelAutoEnum
untuk memperbarui atribut
statusLightBrightness
dari trait CameraAvStreamManagementTrait menggunakan fungsi
setStatusLightBrightness bawaan:
// Set the LED brightness
func setStatusLightBrightness(
to value: Google.CameraAvStreamManagementTrait.ThreeLevelAutoEnum
) async {
do {
_ = try await cameraAvStreamManagementTrait.update {
$0.setStatusLightBrightness(value)
}
} catch {
// Error
}
}
Mengubah area pandang kamera
Viewport kamera sama dengan fitur Zoom dan Pangkas yang dijelaskan dalam artikel dukungan Memperbesar dan mengoptimalkan video kamera Nest.
Area tampilan ditentukan dalam ViewportStruct yang berisi empat nilai, yang
digunakan sebagai koordinat area tampilan. Koordinat didefinisikan sebagai:
(x1,y1) -- (x2,y1) | | (x1,y2) -- (x2,y2)
Penentuan nilai untuk ViewportStruct bergantung pada UI aplikasi dan implementasi kamera. Pada tingkat yang sangat mendasar, untuk menyetel area tampilan video
kamera, perbarui atribut
viewport
dari sifat CameraAvStreamManagementTrait dengan ViewportStruct, menggunakan
fungsi setViewport bawaan.
func setCrop(x1: UInt16, y1: UInt16, x2: UInt16, y2: UInt16) {
let viewport = Google.CameraAvStreamManagementTrait.ViewportStruct(
x1: x1,
y1: y1,
x2: x2,
y2: y2
)
Task {
do {
try await cameraAvStreamManagementTrait.update {
$0.setViewport(viewport)
}
} catch {
// Error
}
}
}
Membuat TransportOptionsStruct
Beberapa setelan memerlukan modifikasi pada properti di TransportOptionsStruct,
yang kemudian diteruskan ke opsi transportasi koneksi streaming. Untuk
Swift, struct ini harus dibuat sebelum memperbarui properti apa pun.
Gunakan fungsi bantuan ini untuk membuat struct yang akan digunakan dengan perubahan setelan berikut:
func getTransportOptions(
transportOptions: Google.PushAvStreamTransportTrait.TransportOptionsStruct,
wakeUpSensitivity: UInt8?,
maxEventLength: UInt32?
) async throws
-> Google.PushAvStreamTransportTrait.TransportOptionsStruct
{
var newMotionTimeControl:
Google.PushAvStreamTransportTrait.TransportMotionTriggerTimeControlStruct? = nil
if let maxEventLength {
guard let motionTimeControl = transportOptions.triggerOptions.motionTimeControl else {
throw HomeError.failedPrecondition(
// Error - cannot update max event length without motion time control
}
newMotionTimeControl =
Google.PushAvStreamTransportTrait.TransportMotionTriggerTimeControlStruct(
initialDuration: motionTimeControl.initialDuration,
augmentationDuration: motionTimeControl.augmentationDuration,
maxDuration: maxEventLength,
blindDuration: motionTimeControl.blindDuration
)
}
return Google.PushAvStreamTransportTrait.TransportOptionsStruct(
streamUsage: .recording,
videoStreamID: nil,
audioStreamID: nil,
tlsEndpointID: transportOptions.tlsEndpointID,
url: transportOptions.url,
triggerOptions: Google.PushAvStreamTransportTrait.TransportTriggerOptionsStruct(
triggerType: .motion,
motionZones: nil,
motionSensitivity: wakeUpSensitivity,
motionTimeControl: newMotionTimeControl,
maxPreRollLen: nil
),
ingestMethod: .cmafIngest,
containerOptions: Google.PushAvStreamTransportTrait.ContainerOptionsStruct(
containerType: .cmaf,
cmafContainerOptions: nil
),
expiryTime: nil
)
}
private func getRecordingConnection() async throws
-> Google.PushAvStreamTransportTrait.TransportConfigurationStruct?
{
guard let pushAvStreamTransportTrait else {
// Error - PushAvStreamTransport trait not available
return nil
}
let connections = try await pushAvStreamTransportTrait.findTransport().transportConfigurations
for connection in connections {
guard let transportOptions = connection.transportOptions,
transportOptions.streamUsage == .recording
else {
continue
}
return connection
}
return nil
}
Menyesuaikan sensitivitas aktivasi perangkat
Sensitivitas aktif perangkat digunakan untuk menghemat baterai dengan mengurangi rentang saat perangkat dapat mendeteksi aktivitas dan meningkatkan waktu untuk aktif setelah mendeteksi aktivitas tersebut.
Di Home API, ini dapat disetel menggunakan properti motionSensitivity dari
triggerOptions di transportOptions perangkat. Opsi ini ditentukan dalam trait PushAvStreamTransportTrait untuk setiap perangkat.
Sensitivitas aktivasi hanya dapat disetel ke nilai berikut:
- 1 = Rendah
- 5 = Sedang
- 10 = Tinggi
Proses pembaruan adalah dengan menemukan konfigurasi transportasi untuk aliran rekaman aktif menggunakan perintah
findTransport, lalu mengubah konfigurasi dengan nilai sensitivitas baru menggunakan perintah
modifyPushTransport.
Perintah modifyPushTransport memerlukan TransportOptionsStruct lengkap untuk
diteruskan, jadi Anda harus menyalin nilai yang ada dari konfigurasi saat ini
terlebih dahulu. Lihat Membuat TransportOptionsStruct untuk
fungsi bantuan guna melakukannya.
func setWakeUpSensitivity(to value: UInt8) async {
do {
let connection = try await getRecordingConnection()
guard let connection,
let transportOptions = connection.transportOptions
else {
// Error - Transport options not available
return
}
guard transportOptions.triggerOptions.motionSensitivity != nil else {
// Error - Motion sensitivity not available to be updated for this device
return
}
try await pushAvStreamTransportTrait.modifyPushTransport(
connectionID: connection.connectionID,
transportOptions: self.getTransportOptions(
transportOptions: transportOptions,
wakeUpSensitivity: value,
maxEventLength: nil
)
)
} catch {
// Error
}
}
Menyesuaikan durasi peristiwa maksimum
Durasi peristiwa maksimum adalah durasi waktu kamera akan merekam klip untuk suatu peristiwa. Melalui Home API, hal ini dapat dikonfigurasi, per perangkat, dengan panjang yang sama seperti melalui Google Home app (GHA), dalam interval detik:
- 10 detik
- 15 detik
- 30 detik
- 60 detik (1 menit)
- 120 detik (2 menit)
- 180 detik (3 menit)
Di Home API, ini dapat disetel menggunakan properti motionTimeControl dari
triggerOptions di transportOptions perangkat. Opsi ini ditentukan dalam trait PushAvStreamTransportTrait untuk setiap perangkat.
Proses pembaruan adalah menemukan konfigurasi transportasi untuk aliran rekaman aktif menggunakan perintah
findTransport, lalu mengubah konfigurasi dengan nilai panjang peristiwa baru menggunakan perintah
modifyPushTransport.
Perintah modifyPushTransport memerlukan TransportOptionsStruct lengkap untuk
diteruskan, jadi Anda harus menyalin nilai yang ada dari konfigurasi saat ini
terlebih dahulu. Lihat Membuat TransportOptionsStruct untuk
fungsi bantuan guna melakukannya.
func setMaxEventLength(to value: UInt32) async {
do {
let connection = try await getRecordingConnection()
guard let connection,
let transportOptions = connection.transportOptions
else {
// Error - Transport options not available
return
}
guard transportOptions.triggerOptions.motionTimeControl != nil else {
// Error - Motion time control not available to be updated for this device
return
}
try await pushAvStreamTransportTrait.modifyPushTransport(
connectionID: connection.connectionID,
transportOptions: self.getTransportOptions(
transportOptions: transportOptions,
wakeUpSensitivity: nil,
maxEventLength: value
)
)
} catch {
// Error
}
}
Setelan bel
Berbagai setelan bunyi bel pintu dapat dikontrol melalui Home API.
Mengubah suara bel
Untuk mengubah suara bel pintu, pertama-tama dapatkan daftar suara bel yang diinstal di perangkat, menggunakan atribut
installedChimeSounds
dari trait ChimeTrait:
doorbellChimeTrait.attributes.installedChimeSounds?.compactMap { chimeSound in
return chimeSound.chimeID, chimeSound.name
}
Kemudian, update atribut
selectedChime
dari trait ChimeTrait menggunakan fungsi setSelectedChime
bawaan:
func setDoorbellChime(chimeID: UInt8) async {
do {
_ = try await doorbellChimeTrait.update {
$0.setSelectedChime(chimeID)
}
} catch {
// Error
}
}
Menggunakan bel eksternal
Bel pintu dapat dikonfigurasi untuk menggunakan bel eksternal, seperti bel mekanis yang dipasang di dalam rumah. Setelan ini harus dikonfigurasi selama pemasangan bel pintu untuk menghindari potensi kerusakan pada bel eksternal.
Untuk menunjukkan jenis bel eksternal yang terpasang, gunakan
ExternalChimeType
untuk memperbarui atribut
externalChime
dari trait ChimeTrait menggunakan fungsi
setExternalChime bawaan:
// Indicate the external chime is mechanical
func setExternalChime(to value: Google.ChimeTrait.ExternalChimeType) async {
do {
_ = try await doorbellChimeTrait.update {
$0.setExternalChime(value)
}
} catch {
// Error
}
}
Mengubah durasi bel eksternal
Durasi dering bel eksternal, dalam detik, dapat dikonfigurasi melalui Home API. Jika bel eksternal mendukung durasi bel, pengguna mungkin ingin mengonfigurasi durasi ini.
Nilai yang ditetapkan di sini bergantung pada spesifikasi bel eksternal itu sendiri, dan durasi bel yang direkomendasikan.
Untuk mengubah durasi bunyi bel eksternal, perbarui atribut
externalChimeDurationSeconds
dari trait ChimeTrait menggunakan fungsi
setExternalChimeDurationSeconds bawaan:
// Change the external chime duration
func setExternalChimeDuration(to value: UInt16) async {
do {
_ = try await doorbellChimeTrait.update {
$0.setExternalChimeDuration(value)
}
} catch {
// Error
}
}