O tipo de dispositivo campainha é implementado usando duas características:
PushAvStreamTransportTrait,
que processa o transporte de streams de áudio e vídeo usando protocolos baseados em push, e
WebRtcLiveViewTrait,
que oferece a capacidade de controlar transmissões ao vivo e o recurso TalkBack.
Sempre verifique se um dispositivo é compatível com atributos e comandos antes de usar qualquer recurso ou tentar atualizar atributos. Consulte Controlar dispositivos no iOS para mais informações.
| Tipo de dispositivo das APIs do Google Home | Características | App de exemplo do Swift | Caso de uso |
|---|---|---|---|
|
Campainha
Um dispositivo acionado por um botão do lado de fora de uma porta que emite um sinal audível e/ou visual, usado para chamar a atenção de uma pessoa que está do outro lado da porta. As campainhas podem ter transmissões ao vivo acessíveis, comunicação bidirecional ou eventos de detecção. |
Traços obrigatórios google PushAvStreamTransportTrait google WebRtcLiveViewTrait |
Campainha |
Receber informações básicas sobre um dispositivo
O traço BasicInformation
inclui informações como nome do fornecedor, ID do fornecedor, ID do produto,
nome do produto (inclui informações do modelo), versão do software
e o número de série de um dispositivo:
// [START get_device_information] let vendorName = basicInfoTrait.attributes.vendorName! let vendorID = basicInfoTrait.attributes.vendorID! let productID = basicInfoTrait.attributes.productID! let productName = basicInfoTrait.attributes.productName! let softwareVersion = basicInfoTrait.attributes.softwareVersion! let serialNumber = basicInfoTrait.attributes.serialNumber! // [END get_device_information]
Verificar a conectividade de um dispositivo
A conectividade de um dispositivo é verificada no nível do tipo de dispositivo, porque alguns dispositivos são compatíveis com vários tipos. O estado retornado é uma combinação dos estados de conectividade de todas as características do dispositivo.
let lightConnectivity = dimmableLightDeviceType.metadata.sourceConnectivity .connectivityState
Um estado de partiallyOnline pode ser observado no caso de tipos de dispositivos mistos quando não há conectividade com a Internet. As Matter características padrão ainda podem estar on-line devido ao roteamento local, mas as características baseadas na nuvem vão ficar off-line.
Iniciar uma transmissão ao vivo
Para iniciar uma transmissão ao vivo, envie a string do Session Description Protocol (SDP)
para o método
startLiveView(offerSdp:)
do traço
WebRtcLiveViewTrait, que retorna três valores:
- O SDP da sessão.
- A duração da sessão em segundos.
- O ID da sessão, que pode ser usado para estender ou encerrar a sessão.
public func sendOffer(offerSdp: String) async throws
-> (answerSdp: String, mediaSessionId: String, liveViewDuration: TimeInterval)
{
do {
// Sending StartLiveView command
let response = try await liveViewTrait.startLiveView(
offerSdp: offerSdp
)
// Received StartLiveView response
return (
answerSdp: response.answerSdp,
mediaSessionId: response.mediaSessionId,
liveViewDuration: TimeInterval(response.liveSessionDurationSeconds)
)
} catch {
// Failed to send StartLiveView command
throw error
}
}
Estender uma transmissão ao vivo
As transmissões ao vivo têm uma duração predefinida após a qual expiram. Para aumentar a duração de um stream ativo, envie uma solicitação de extensão usando o método extendLiveView(mediaSessionId:optionalArgsProvider:):
public func extendLiveView(mediaSessionId: String) async throws {
do {
// Extending live view
let extendedDuration = try await liveViewTrait.extendLiveView(mediaSessionId: mediaSessionId)
} catch {
// Failed to extend live view
throw error
}
}
Iniciar e interromper o TalkBack
Para iniciar o talkback, chame o método startTalkback(mediaSessionId:optionalArgsProvider:) da característica
WebRtcLiveViewTrait.
Para parar, use stopTalkback(mediaSessionId:).
public func toggleTwoWayTalk(isOn: Bool, mediaSessionId: String) async throws {
do {
if isOn {
try await liveViewTrait.startTalkback(mediaSessionId: mediaSessionId)
} else {
try await liveViewTrait.stopTalkback(mediaSessionId: mediaSessionId)
}
} catch {
throw HomeError.commandFailed("Failed to toggle twoWayTalk: \(error)")
}
}
Ativar e desativar a capacidade de gravação
Para ativar a capacidade de gravação da câmera, transmita
TransportStatusEnum.Active
ao método
PushAvStreamTransportTrait
da característica
setTransportStatus(transportStatus:optionalArgsProvider:). Para desativar a capacidade de gravação, transmita-a
TransportStatusEnum.Inactive.
No exemplo a seguir, agrupamos essas chamadas em uma única chamada que usa um
Boolean para ativar ou desativar a capacidade de gravação:
public func toggleIsRecording(isOn: Bool) {
self.uiState = .loading
guard let pushAvStreamTransportTrait else {
// PushAvStreamTransportTrait not found.
return
}
Task {
do {
try await pushAvStreamTransportTrait.setTransportStatus(
transportStatus: isOn ? .active : .inactive)
if isOn {
do {
self.player = try self.createWebRtcPlayer()
} catch {
// Failed to initialize WebRtcPlayer
self.uiState = .disconnected
return
}
await self.player?.initialize()
self.uiState = .live
} else {
self.player = nil
self.uiState = .off
}
} catch {
// Failed to toggle onOff
}
}
}
Ativar ou desativar a capacidade de gravação da câmera é o mesmo que ligar ou desligar o vídeo dela. Quando o vídeo de uma câmera está ativado, ela está gravando (para fins de eventos e clipes relacionados).
Quando a capacidade de gravação está desativada (o vídeo da câmera está desligado):
- A câmera ainda pode aparecer como on-line de acordo com o
connectivityStatedo tipo de dispositivo. - Não é possível acessar a transmissão ao vivo, e a câmera não detecta eventos na nuvem.
Verificar se a capacidade de gravação está ativada
Para determinar se a capacidade de gravação de uma câmera está ativada, verifique se há conexões ativas. O exemplo a seguir define duas funções para fazer isso:
public func isDeviceRecording() -> Bool {
guard let pushAvStreamTransportTrait else {
// PushAvStreamTransportTrait not found.
return false
}
guard
let hasActiveConnection =
pushAvStreamTransportTrait
.attributes
.currentConnections?
.contains(where: { $0.transportStatus == .active })
else {
return false
}
return hasActiveConnection
}
Configurações de bateria
Várias configurações de bateria podem ser controladas pelas APIs Home.
Definir a preferência de uso da bateria
Ao definir o equilíbrio energético, você configura a compensação entre a duração da bateria e o desempenho de um dispositivo. Você pode criar diferentes perfis de bateria, como "Estendido", "Equilibrado" e "Performance", e alternar entre eles.
Esse recurso é implementado atualizando o
atributo
currentEnergyBalance
da característica
EnergyPreference. O atributo aceita um índice inteiro que corresponde a um perfil específico definido na lista energyBalances do dispositivo (por exemplo, 0 para EXTENDED, 1 para BALANCED e 2 para PERFORMANCE).
Um valor null para currentEnergyBalance indica que o dispositivo está usando um
perfil personalizado. Este é um estado somente leitura.
A seguir, mostramos um exemplo de estrutura que o atributo currentEnergyBalance
vai usar, seguido pelo snippet de código real que usa o atributo.
// Example energyBalances list { "energy_balances": [ { "step": 0, "label": "EXTENDED" }, { "step": 50, "label": "BALANCED" }, { "step": 100, "label": "PERFORMANCE" } ] }
private func setBatteryUsage(to option: UInt8) async throws { _ = try await energyPreferenceTrait.update { $0.setCurrentEnergyBalance(option) } }
Ativar a Economia de bateria automática
Para configurar esse recurso, atualize o atributo
currentLowPowerModeSensitivity
da característica
EnergyPreference. Esse atributo usa um índice para selecionar um nível de sensibilidade, em que 0 geralmente representa Disabled e 1 representa Enabled ou Automatic.
private func setAutoBatterySaver(to value: Bool) async throws { _ = try await energyPreferenceTrait.update { $0.setCurrentLowPowerModeSensitivity(value ? 1 : 0) } }
Receber o estado de carregamento da bateria
Para saber o estado de carregamento atual do dispositivo (carregando, totalmente carregado ou não
carregando), use o atributo
batChargeState
da característica
PowerSource.
self.chargingState = powerSourceTrait.attributes.batChargeState var description: String switch self.chargingState { case .isCharging: description = "Charging" case .isAtFullCharge: description = "Full" case .isNotCharging: description = "Not Charging" default: description = "Unknown" }
Receber o nível da bateria
Para saber o nível atual da bateria, use o atributo
batChargeLevel
da característica
PowerSource. O nível é OK, Warning (baixo) ou Critical.
self.batteryLevel = powerSourceTrait.attributes.batChargeLevel var description: String switch self.batteryLevel { case .ok: description = "OK" case .warning: description = "Warning" case .critical: description = "Critical" default: description = "Unknown" }
Encontre a fonte de alimentação
Para determinar a fonte de energia que o dispositivo está usando, use os atributos BatPresent e wiredPresent da característica PowerSource.
if powerSourceTrait.attributes.wiredPresent ?? false { self.powerSourceType = .wired } else if powerSourceTrait.attributes.batPresent ?? false { self.powerSourceType = .battery } else { self.powerSourceType = nil }
Configurações de áudio
Várias configurações de áudio podem ser controladas pelas APIs Home.
Ativar ou desativar o microfone
Para ativar ou desativar o microfone do dispositivo, atualize o atributo
microphoneMuted
da característica CameraAvStreamManagementTrait usando a função
setMicrophoneMuted integrada:
// Turn the device's microphone on or off
func setMicrophone(on: Bool) async {
do {
_ = try await self.cameraAvStreamManagementTrait?.update {
$0.setMicrophoneMuted(!on)
}
} catch {
// Error
}
}
Ativar ou desativar a gravação de áudio
Para ativar ou desativar a gravação de áudio no dispositivo, atualize o atributo
recordingMicrophoneMuted
da característica CameraAvStreamManagementTrait usando a função
setRecordingMicrophoneMuted integrada:
// 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
}
}
Ajustar o volume do alto-falante
Para ajustar o volume do alto-falante do dispositivo, atualize o atributo
speakerVolumeLevel
da característica CameraAvStreamManagementTrait usando a função
setSpeakerVolumeLevel integrada:
// Adjust the camera speaker volume
func setSpeakerVolume(to value: UInt8) async {
do {
_ = try await cameraAvStreamManagementTrait.update {
$0.setSpeakerVolumeLevel(value)
}
} catch {
// Error
}
}
Outras configurações
Várias outras configurações podem ser controladas pelas APIs Home.
Ativar ou desativar a visão noturna
Para ativar ou desativar a visão noturna da câmera, use TriStateAutoEnum
para atualizar o atributo
nightVision
da característica CameraAvStreamManagementTrait usando a função
setNightVision integrada:
// Turn night vision on or off
func setNightVision(
to value: Google.CameraAvStreamManagementTrait.TriStateAutoEnum
) async {
do {
_ = try await cameraAvStreamManagementTrait.update {
$0.setNightVision(value)
}
} catch {
// Error
}
}
Mudar o brilho do LED de status
Para mudar o brilho do LED de status, use
ThreeLevelAutoEnum
para atualizar o atributo
statusLightBrightness
da característica CameraAvStreamManagementTrait usando a função
setStatusLightBrightness integrada:
// Set the LED brightness
func setStatusLightBrightness(
to value: Google.CameraAvStreamManagementTrait.ThreeLevelAutoEnum
) async {
do {
_ = try await cameraAvStreamManagementTrait.update {
$0.setStatusLightBrightness(value)
}
} catch {
// Error
}
}
Mudar a janela de visualização da câmera
A janela de visualização da câmera é a mesma do recurso de zoom e corte descrito no artigo de suporte Zoom e modo Enhance no vídeo da câmera Nest.
A janela de visualização é definida em um ViewportStruct que contém quatro valores, usados como coordenadas da janela. As coordenadas são definidas como:
(x1,y1) -- (x2,y1) | | (x1,y2) -- (x2,y2)
A determinação dos valores para ViewportStruct depende da interface do app e da implementação da câmera. Em um nível muito básico, para definir a janela de visualização do vídeo da câmera, atualize o atributo viewport da característica CameraAvStreamManagementTrait com um ViewportStruct, usando a função setViewport integrada.
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
}
}
}
Gerar um TransportOptionsStruct
Algumas configurações exigem modificações nas propriedades de um TransportOptionsStruct, que é transmitido para as opções de transporte de uma conexão de streaming. Para
Swift, essa struct precisa ser gerada antes de atualizar qualquer propriedade.
Use essa função auxiliar para gerar a struct a ser usada com as seguintes mudanças de configuração:
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
}
Ajustar a sensibilidade de ativação do dispositivo
A sensibilidade de ativação do dispositivo é usada para economizar bateria, diminuindo o alcance em que o dispositivo pode detectar atividade e aumentando o tempo para ativar após detectar essa atividade.
Nas APIs Home, isso pode ser definido usando a propriedade motionSensitivity do
triggerOptions no transportOptions do dispositivo. Essas opções são definidas
no traço PushAvStreamTransportTrait de cada dispositivo.
A sensibilidade de ativação só pode ser definida com os seguintes valores:
- 1 = Baixa
- 5 = Médio
- 10 = Alto
Para atualizar, encontre a configuração de transporte para fluxos de gravação ativos usando o comando findTransport e modifique a configuração com o novo valor de sensibilidade usando o comando modifyPushTransport.
O comando modifyPushTransport exige que o TransportOptionsStruct completo seja transmitido. Portanto, primeiro copie os valores da configuração atual. Consulte Gerar um TransportOptionsStruct para uma função auxiliar que faça isso.
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
}
}
Ajustar a duração máxima de eventos
A duração máxima de eventos é o tempo que a câmera vai gravar um clipe para um evento. Usando as APIs Home, isso pode ser configurado por dispositivo com os mesmos comprimentos que no Google Home app (GHA), em intervalos de segundos:
- 10 segundos
- 15 segundos
- 30 segundos
- 60 segundos (1 minuto)
- 120 segundos (2 minutos)
- 180 segundos (3 minutos)
Nas APIs Home, isso pode ser definido usando a propriedade motionTimeControl do
triggerOptions no transportOptions do dispositivo. Essas opções são definidas
no traço PushAvStreamTransportTrait de cada dispositivo.
Para atualizar, encontre a configuração de transporte para fluxos de gravação ativos usando o comando findTransport e modifique a configuração com o novo valor de duração do evento usando o comando modifyPushTransport.
O comando modifyPushTransport exige que o TransportOptionsStruct completo seja transmitido. Portanto, primeiro copie os valores da configuração atual. Consulte Gerar um TransportOptionsStruct para uma função auxiliar que faça isso.
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
}
}
Configurações da campainha
Várias configurações de toque da campainha podem ser controladas pelas APIs Home.
Mudar o som da campainha
Para mudar o som da campainha, primeiro acesse a lista de sons instalados no dispositivo usando o atributo installedChimeSounds da característica ChimeTrait:
doorbellChimeTrait.attributes.installedChimeSounds?.compactMap { chimeSound in
return chimeSound.chimeID, chimeSound.name
}
Em seguida, atualize o atributo
selectedChime
da característica ChimeTrait usando a função setSelectedChime
integrada:
func setDoorbellChime(chimeID: UInt8) async {
do {
_ = try await doorbellChimeTrait.update {
$0.setSelectedChime(chimeID)
}
} catch {
// Error
}
}
Usar uma campainha externa
A campainha pode ser configurada para usar um sino externo, como uma campainha mecânica instalada dentro de casa. Isso precisa ser configurado durante a instalação da campainha para evitar possíveis danos ao sino externo.
Para indicar o tipo de campainha externa instalada, use
ExternalChimeType
para atualizar o atributo
externalChime
da característica ChimeTrait usando a função
setExternalChime integrada:
// Indicate the external chime is mechanical
func setExternalChime(to value: Google.ChimeTrait.ExternalChimeType) async {
do {
_ = try await doorbellChimeTrait.update {
$0.setExternalChime(value)
}
} catch {
// Error
}
}
Mudar a duração da campainha externa
A duração, em segundos, que um toque externo toca pode ser configurada pelas APIs Home. Se o sino externo tiver suporte para uma duração de toque, o usuário poderá configurar isso.
O valor definido aqui depende das especificações do toque externo e da duração recomendada.
Para mudar a duração do toque externo, atualize o atributo
externalChimeDurationSeconds
do traço ChimeTrait usando a função
setExternalChimeDurationSeconds integrada:
// Change the external chime duration
func setExternalChimeDuration(to value: UInt16) async {
do {
_ = try await doorbellChimeTrait.update {
$0.setExternalChimeDuration(value)
}
} catch {
// Error
}
}
Ativar um tema de toque
Alguns campainhas podem ter toques disponíveis apenas para usuários por um tempo limitado. Por exemplo, toques específicos para feriados. Esses são os temas de toque.
Para saber quais temas de toque estão disponíveis para um usuário, crie um filtro de timebox
e use-o para filtrar os resultados do comando
getAvailableThemes
do traço
ChimeThemes. Isso retorna uma lista de temas disponíveis, incluindo os nomes deles.
O exemplo a seguir mostra como filtrar a lista.
Um tema é considerado ativo se o horário atual estiver dentro dos horários de início e término (os valores startTimeSeconds e endTimeSeconds, respectivamente). Se um horário de início não for definido, ele será considerado ativo desde o
início. Se um horário de término não for definido, ele vai continuar ativo
indefinidamente. Se os dois estiverem ausentes, o tema vai estar sempre ativo.
let chimeThemes = try await chimeThemeTrait.getAvailableThemes().themes
if !chimeThemes.isEmpty {
var chimeThemeSettings = []
for chimeTheme in chimeThemes {
let currentDateTime = UInt64(Date().timeIntervalSince1970)
// Only show chime themes that are active.
if chimeTheme.startTimeSeconds ?? 0 <= currentDateTime
&& chimeTheme.endTimeSeconds ?? UInt64.max >= currentDateTime
{
self.chimeThemeSettings.append(chimeTheme.name)
}
}
}
Depois de ter o nome do tema desejado, como Christmas, selecione-o usando a função setSelectedTimeboxedThemeName() no traço ChimeThemes ChimeThemes.
private func setChimeTheme(to value: String) async throws {
_ = try await chimeThemeTrait.update {
$0.setSelectedTimeboxedThemeName(value)
}
}```