Guida al dispositivo campanello per Android

Il tipo di dispositivo Campanello viene implementato utilizzando due tratti: PushAvStreamTransport, che gestisce il trasporto di stream audio e video utilizzando protocolli basati su push e WebRtcLiveView, che offre la possibilità di controllare le live streaming e la funzionalità TalkBack.

Prima di utilizzare qualsiasi funzionalità o tentare di aggiornare gli attributi, controlla sempre il supporto di attributi e comandi per un dispositivo. Per ulteriori informazioni, consulta Controllare i dispositivi su Android.

Visualizzare le informazioni di base su un dispositivo

La caratteristica BasicInformation include informazioni quali nome del fornitore, ID fornitore, ID prodotto, nome del prodotto (incluse le informazioni sul modello), versione software e numero di serie di un dispositivo:

// Get device basic information. All general information traits are on the RootNodeDevice type.
    device.type(RootNodeDevice).first().standardTraits.basicInformation?.let { basicInformation ->
        println("vendorName ${basicInformation.vendorName}")
        println("vendorId ${basicInformation.vendorId}")
        println("productId ${basicInformation.productId}")
        println("productName ${basicInformation.productName}")
        println("softwareVersion ${basicInformation.softwareVersion}")
        println("serialNumber ${basicInformation.serialNumber}")
    }

Controllare la connettività di un dispositivo

La connettività di un dispositivo viene effettivamente controllata a livello di tipo di dispositivo perché alcuni dispositivi supportano più tipi di dispositivi. Lo stato restituito è una combinazione degli stati di connettività per tutte le caratteristiche del dispositivo.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

In caso di tipi di dispositivi misti, quando non è presente una connettività a internet, potrebbe essere osservato uno stato di PARTIALLY_ONLINE. Le caratteristiche standard di Matter potrebbero essere ancora online a causa del routing locale, ma le caratteristiche basate sul cloud saranno offline.

Avviare un live streaming

Per avviare un live streaming, invia la stringa Session Description Protocol (SDP) al metodo WebRtcLiveView dell'attributo startLiveView(), che restituisce un WebRtcLiveViewTrait.StartLiveViewCommand.Response contenente tre valori:

• L'SDP per la sessione.
• La durata della sessione in secondi.
• L'ID sessione, che può essere utilizzato per estendere o terminare la sessione.

suspend fun getWebRtcLiveViewTrait(cameraDevice: HomeDevice) {
 return cameraDevice.type(GoogleDoorbellDevice).trait(WebRtcLiveView).first {
    it?.metadata?.sourceConnectivity?.connectivityState == ConnectivityState.ONLINE
  }

}

// Start the live view
suspend fun startCameraStream(trait: WebRtcLiveView, offerSdp: String) {
  val response = trait.startLiveView(offerSdp)
  // Response contains three fields (see below)
  return response
}
  ...

// This is used to manage the WebRTC connection
val peerConnection: RTCPeerConnection = ...

   ...

val startResponse = startCameraStream(sdp)
val answerSdp = startResponse?.answerSdp
val sessionDuration = startResponse?.liveSessionDurationSeconds
val mediaSessionId = startResponse?.mediaSessionId

peerConnection.setRemoteDescription(SessionDescription.Type.ANSWER,
                                    answerSdp)

Estendere un live streaming

I live streaming hanno una durata preimpostata dopo la quale scadono. Per estendere la durata di uno stream attivo, invia una richiesta di estensione utilizzando il metodo WebRtcLiveView.extendLiveView():

// Assuming camera stream has just been started
suspend fun scheduleExtension(trait: WebRtcLiveView, mediaSessionId: String, liveSessionDurationSeconds: UShort ) {
  delay(liveSessionDurationSeconds - BUFFER_SECONDS * 1000)
  val response = trait.extendLiveView(mediaSessionId)
  // returns how long the session will be live for
  return response.liveSessionDurationSeconds
}

Avviare e interrompere TalkBack

Per avviare TalkBack, chiama il metodo startTalkback() del tratto WebRtcLiveView. Per interrompere, utilizza stopTalkback().

// Make sure camera stream is on
suspend fun setTalkback(isOn: Boolean, trait: WebRtcLiveView, mediaSessionId: String) {
  if(isOn) {
    trait.startTalkback(mediaSessionId)
  } else {
    trait.stopTalkback(mediaSessionId)
  }
}

Attivare e disattivare la funzionalità di registrazione

Per attivare la funzionalità di registrazione della videocamera, passa TransportStatusEnum.Active al metodo PushAvStreamTransport dell'attributo setTransportStatus(). Per disattivare la funzionalità di registrazione, passa TransportStatusEnum.Inactive. Nel seguente esempio, racchiudiamo queste chiamate in una singola chiamata che utilizza un Boolean per attivare/disattivare la funzionalità di registrazione:

// Start or stop recording for all connections.
suspend fun setCameraRecording(trait: PushAvStreamTransport, isOn: Boolean) {
  if(isOn) {
    trait.setTransportStatus(TransportStatusEnum.Active)
  } else {
    trait.setTransportStatus(TransportStatusEnum.Inactive)
  }
}

L'attivazione o la disattivazione della funzionalità di registrazione della videocamera equivale ad accendere o spegnere il video della videocamera. Quando il video di una videocamera è attivo, la videocamera registra (ai fini degli eventi e dei clip correlati).

Quando la funzionalità di registrazione è disattivata (il video della videocamera è spento):

• La videocamera può comunque essere visualizzata come online in base all'connectivityState del tipo di dispositivo.
• Non è possibile accedere al live streaming e la videocamera non rileva eventi sul cloud.

Controllare se la funzionalità di registrazione è attiva

Per determinare se la funzionalità di registrazione di una videocamera è attiva, controlla se sono attive connessioni. L'esempio seguente definisce due funzioni per farlo:

// Get the on/off state
suspend fun onOffState(pushAvStreamTransport: PushAvStreamTransport) {
  return pushAvStreamTransport
    .currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

// Check if the camera's recording capability is enabled
fun PushAvStreamTransport.recordModeActive(): Boolean {
  return currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

Un altro modo per verificare è utilizzare la funzione findTransport() con un predicato:

// Fetch the current connections
suspend fun queryRecordModeState(trait: PushAvStreamTransport) {
  return trait.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

Impostazioni della batteria

È possibile controllare varie impostazioni della batteria tramite le API Home.

Impostare la preferenza di utilizzo della batteria

L'impostazione del bilanciamento energetico consente di configurare il compromesso tra durata della batteria e prestazioni di un dispositivo. Puoi creare diversi profili batteria, ad esempio "Esteso", "Bilanciato" e "Prestazioni", e passare da uno all'altro.

Questa funzionalità viene implementata aggiornando l'attributo currentEnergyBalance del tratto EnergyPreference. L'attributo accetta un indice intero che corrisponde a un profilo specifico definito nell'elenco energyBalances del dispositivo (ad esempio, 0 per EXTENDED, 1 per BALANCED e 2 per PERFORMANCE).

Un valore null per currentEnergyBalance indica che il dispositivo utilizza un profilo personalizzato. Questo è uno stato di sola lettura.

Di seguito è riportato un esempio di struttura che verrà utilizzata dall'attributo currentEnergyBalance, seguito dallo snippet di codice effettivo che utilizza l'attributo.

// Example energyBalances list
energy_balances: [
  {
    step: 0,
    label: "EXTENDED"
  },
  {
    step: 50,
    label: "BALANCED"
  },
  {
    step: 100,
    label: "PERFORMANCE"
  }
]

// The index parameter must be within the UByte range (0-255).
suspend fun setEnergyBalance(trait: EnergyPreference, index: Int) {
  trait.update { setCurrentEnergyBalance(index.toUByte()) }
}

// Setting the battery usage to more recording ie performance
setEnergyBalance(energyPreference, 2)

Attivare il risparmio energetico automatico

Per configurare questa funzionalità, aggiorna l'attributo currentLowPowerModeSensitivity del tratto EnergyPreference. Questo attributo utilizza un indice per selezionare un livello di sensibilità, dove 0 in genere rappresenta Disabled e 1 rappresenta Enabled o Automatic.

suspend fun setAutomaticBatterySaver(enable: Boolean, trait: EnergyPreference) {
  // 0 is Disabled, 1 is Enabled
  val value = if (enable) 1.toUByte() else 0.toUByte()
  trait.update { setCurrentLowPowerModeSensitivity(value) }
}

Ottenere lo stato di ricarica della batteria

Per ottenere lo stato di ricarica attuale del dispositivo (in carica, completamente carico o non in carica), utilizza l'attributo batChargeState del tratto PowerSource.

// Get the battery charging state
val batteryChargeState = powerSource.batChargeState

when (batteryChargeState) {
    PowerSourceTrait.BatChargeStateEnum.IsCharging -> "Charging"
    PowerSourceTrait.BatChargeStateEnum.IsAtFullCharge -> "Full"
    PowerSourceTrait.BatChargeStateEnum.IsNotCharging -> "Not Charging"
    else -> "Unknown"
}

Ottenere il livello della batteria

Per ottenere il livello attuale della batteria, utilizza l'attributo batChargeLevel del tratto PowerSource. Il livello è OK, Warning (basso) o Critical.

// Get the battery charge level
val batteryLevel = powerSourceTrait.batChargeLevel

when (batteryLevel) {
    PowerSourceTrait.BatChargeLevelEnum.OK -> "OK"
    PowerSourceTrait.BatChargeLevelEnum.Warning -> "Warning"
    PowerSourceTrait.BatChargeLevelEnum.Critical -> "Critical"
    else -> "Unknown"
}

Recuperare la fonte di alimentazione

Per determinare la fonte di alimentazione utilizzata dal dispositivo, utilizza gli attributi BatPresent e wiredPresent del tratto PowerSource.

  val trait: PowerSource
  val isWired = trait.wiredPresent
  val hasBattery = trait.batPresent

Impostazioni audio

È possibile controllare varie impostazioni audio tramite le API Home.

Attivare o disattivare il microfono

Per attivare o disattivare il microfono del dispositivo, aggiorna l'attributo microphoneMuted del tratto CameraAvStreamManagement utilizzando la funzione Kotlin setMicrophoneMuted integrata:

// Turn the device's microphone on or off
suspend fun turnOffMicrophone(disableMicrophone: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setMicrophoneMuted(disableMicrophone) }
}

Attivare o disattivare la registrazione audio

Per attivare o disattivare la registrazione audio per il dispositivo, aggiorna l'attributo recordingMicrophoneMuted del tratto CameraAvStreamManagement utilizzando la funzione setRecordingMicrophoneMuted Kotlin integrata:

// Turn audio recording on or off for the device
suspend fun turnOffAudioRecording(disableAudioRecording: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setRecordingMicrophoneMuted(disableAudioRecording) }
}

Regolare il volume dello speaker

Per regolare il volume dello speaker del dispositivo, aggiorna l'attributo speakerVolumeLevel del tratto CameraAvStreamManagement utilizzando la funzione setSpeakerVolumeLevel Kotlin integrata:

// Adjust the camera speaker volume
suspend fun adjustSpeakerVolume(volume: Int, trait: CameraAvStreamManagement) {
  trait.update { setSpeakerVolumeLevel(volume.toUbyte()) }
}

Altre impostazioni

Varie altre impostazioni possono essere controllate tramite le API Home.

Attivare o disattivare la visione notturna

Per attivare o disattivare la visione notturna per la videocamera, utilizza TriStateAutoEnum per aggiornare l'attributo nightVision del tratto CameraAvStreamManagement utilizzando la funzione Kotlin setNightVision integrata:

// Turn night vision on
cameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.On)
}

// Turn night vision off
CameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.Off)
}

Modificare la luminosità del LED di stato

Per modificare la luminosità del LED di stato, utilizza ThreeLevelAutoEnum per aggiornare l'attributo statusLightBrightness del tratto CameraAvStreamManagement utilizzando la funzione Kotlin setStatusLightBrightness integrata:

// Set the LED brightness to high
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.High)
}

// Set the LED brightness to low
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.Low)
}

Modificare il viewport della videocamera

La finestra della videocamera è la stessa della funzionalità Zoom e ritaglio descritta nell'articolo del Centro assistenza Aumentare lo zoom e migliorare i video della videocamera Nest.

La finestra viene definita in un ViewportStruct che contiene quattro valori, che vengono utilizzati come coordinate della finestra. Le coordinate sono definite come:

(x1,y1) -- (x2,y1)
   |          |
(x1,y2) -- (x2,y2)

La determinazione dei valori per ViewportStruct dipende dall'interfaccia utente di un'app e dall'implementazione della fotocamera. A un livello molto base, per impostare la visualizzazione del video della videocamera, aggiorna l'attributo viewport del tratto CameraAvStreamManagement con un ViewportStruct, utilizzando la funzione Kotlin setViewport integrata:

cameraAvStreamManagement
  .update { setViewport(
    CameraAvStreamManagementTrait.ViewportStruct(
      x1 = horizontalRange.rangeStart.roundToInt().toUShort(),
      x2 = horizontalRange.rangeEnd.roundToInt().toUShort(),
      y1 = verticalRange.rangeStart.roundToInt().toUShort(),
      y2 = verticalRange.rangeEnd.roundToInt().toUShort(),
    )
) }

Regolare la sensibilità alla riattivazione del dispositivo

La sensibilità di riattivazione del dispositivo viene utilizzata per risparmiare batteria diminuendo il raggio in cui il dispositivo può rilevare l'attività e aumentando il tempo di riattivazione dopo aver rilevato l'attività.

Nelle API Home, questa impostazione può essere configurata utilizzando la proprietà motionSensitivity di triggerOptions in transportOptions del dispositivo. Queste opzioni sono definite nell'attributo PushAvStreamTransport per ogni dispositivo.

La sensibilità al risveglio può essere impostata solo sui seguenti valori:

• 1 = Basso
• 5 = Media
• 10 = Alto

La procedura di aggiornamento consiste nel trovare la configurazione di trasporto per i flussi di registrazione attivi utilizzando il comando findTransport, quindi modificare la configurazione con il nuovo valore di sensibilità utilizzando il comando modifyPushTransport:

// Create a struct with the new wake-up sensitivity
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionSensitivity =
        OptionalValue.present(wakeUpSensitivity.toUByte())
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

Regolare la durata massima degli eventi

La durata massima degli eventi è il periodo di tempo per cui la videocamera registrerà un clip per un evento. Tramite le API Home, questa impostazione può essere configurata, per dispositivo, con le stesse durate che si ottengono tramite GHA, a intervalli di secondi:

• 10 secondi
• 15 secondi
• 30 secondi
• 60 secondi (1 minuto)
• 120 secondi (2 minuti)
• 180 secondi (3 minuti)

Nelle API Home, questa impostazione può essere configurata utilizzando la proprietà motionTimeControl di triggerOptions in transportOptions del dispositivo. Queste opzioni sono definite nell'attributo PushAvStreamTransport per ogni dispositivo.

La procedura di aggiornamento consiste nel trovare la configurazione di trasporto per i flussi di registrazione attivi utilizzando il comando findTransport, quindi modificare la configurazione con il nuovo valore della durata dell'evento utilizzando il comando modifyPushTransport:

// Create a struct with the new max event length
// where maxDuration is the length in seconds
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionTimeControl =
        OptionalValue.present(
          TransportMotionTriggerTimeControlStruct(maxDuration = it.toUInt())
        )
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

Impostazioni del cicalino

È possibile controllare varie impostazioni del suono del campanello tramite le API Home.

Modificare il suono del cicalino

Per modificare il suono della suoneria del campanello, recupera prima l'elenco dei suoni della suoneria installati sul dispositivo utilizzando l'attributo installedChimeSounds del tratto Chime:

// Get a list of chimes and identify the currently selected one
private val doorbellChimeTraitFlow: Flow =
    device.traitFromType(Chime, GoogleDoorbellDevice)
val chimeSounds = doorbellChimeTraitFlow.first().installedChimeSounds ?: emptyList()

Quindi, aggiorna l'attributo selectedChime del tratto Chime utilizzando la funzione Kotlin setSelectedChime integrata:

// Set the chime using the chimeId from the installed list
chimeSounds.firstOrNull { it.name == name }?.let { setSelectedChime(it.chimeId) }

Utilizzare un cicalino esterno

Il campanello può essere configurato per utilizzare un cicalino esterno, ad esempio una campana meccanica installata all'interno della casa. Questa impostazione deve essere configurata durante l'installazione del campanello per evitare potenziali danni al cicalino esterno.

Per indicare il tipo di cicalino esterno installato, utilizza ExternalChimeType per aggiornare l'attributo externalChime del tratto Chime utilizzando la funzione setExternalChime Kotlin integrata:

// Indicate the external chime is mechanical
chime.update {
  setExternalChime(ChimeTrait.ExternalChimeType.Mechanical)
}

Modificare la durata del suono del cicalino esterno

La durata, in secondi, del suono di un campanello esterno può essere configurata tramite le API Home. Se il suono esterno supporta una durata, un utente potrebbe volerla configurare.

Il valore impostato qui dipende dalle specifiche del cicalino esterno e dalla durata consigliata del suono.

Per modificare la durata del suono di avviso esterno, aggiorna l'attributo externalChimeDurationSeconds del tratto Chime utilizzando la funzione setExternalChimeDurationSeconds Kotlin integrata:

// Change the external chime duration
chime.update {
  setExternalChimeDurationSeconds(newDuration.toUShort())
}

Attivare un tema per il suono di notifica

Alcuni campanelli potrebbero avere suonerie disponibili solo per un periodo di tempo limitato. Ad esempio, suoni specifici per le festività. Questi si chiamano temi di notifica.

Per vedere quali temi di suono sono disponibili per un utente, crea un filtro timebox e utilizzalo per filtrare i risultati del comando getAvailableThemes() dall'attributo ChimeThemes. Viene restituito un elenco di temi disponibili, inclusi i nomi dei temi.

Il seguente esempio mostra come filtrare l'elenco. Un tema è considerato attivo se l'ora corrente rientra nell'intervallo tra l'ora di inizio e l'ora di fine (rispettivamente i valori startTimeSeconds e endTimeSeconds). Se non è impostata un'ora di inizio, viene considerata attiva dall'inizio dei tempi. Se non viene impostata un'ora di fine, la regola rimane attiva a tempo indeterminato. Se mancano entrambi, il tema è sempre attivo.

// Get themes from the ChimeThemes trait
fun List<ChimeThemesTrait.ThemeStruct>.filterTimeboxedThemes():
    List<ChimeThemesTrait.ThemeStruct> {
  val now = timeSource.instant().epochSecond.toULong()
  return filter { chimeStruct: ChimeThemesTrait.ThemeStruct ->
    val startTime: ULong = chimeStruct.startTimeSeconds.getOrNull() ?: 0UL
    val endTime: ULong = chimeStruct.endTimeSeconds.getOrNull() ?: MAX_VALUE
    startTime <= now && now <= endTime
  }
}

val availableThemes =
  doorbellChimeThemesTraitFlow
    .first()
    .getAvailableThemes()
    .themes
    .filterTimeboxedThemes()

Una volta ottenuto il nome del tema che vuoi, ad esempio Christmas, puoi selezionarlo utilizzando la funzione setSelectedTimeboxedThemeName() nell'attributo ChimeThemes:

// Select a theme using the ChimeThemes trait
val themeToSelect = "Christmas"
if (themeToSelect in availableThemeNames) {
  doorbellChimeThemesTraitFlow.first().setSelectedTimeboxedThemeName(themeToSelect)
}