Descripción general de la API de Automation en Android

Las automatizaciones son una forma de automatizar tareas y la configuración de dispositivos en una casa. Las automatizaciones han estado disponibles en el ecosistema de Google Home como Rutinas en la Google Home app (GHA) y a través de automation script editor en Google Home for web.

Ahora, las automatizaciones en el ecosistema de Google Home están disponibles a través de las APIs de Home para Android. Usan los mismos conceptos básicos que se usan en GHA Rutinas y el script editor, pero con funciones y capacidades mejoradas que solo son posibles a través de las APIs de Home, incluidas las siguientes:

• Acceso a todos los atributos Matter estándar y smart home para un dispositivo, como se presenta en las APIs de Home
• Compatibilidad con flujos de ejecución secuenciales, paralelos y seleccionados

Las automatizaciones se escriben con Automation DSL, un lenguaje específico del dominio diseñado para crear automatizaciones en Kotlin.

Todos los atributos y tipos que deseas usar en tu app con las APIs de Device &Structure o Automation deben registrarse durante la inicialización. Consulta Cómo inicializar la casa en Android.

Orientación si el usuario revoca los permisos completos

Si el usuario revoca los permisos completos, todas las automatizaciones existentes dejarán de funcionar. Además, si el usuario revoca el acceso a dispositivos específicos, los activadores, las condiciones y las acciones asociadas con esos dispositivos dejarán de funcionar.

Cada vez que se inicie la app, asegúrate de que los permisos sigan vigentes. Si se revocaron, asegúrate de que se quiten todos los datos anteriores, incluidos los datos almacenados en caché en la aplicación.

Cuando se revoca el acceso a la estructura, se StructureAccessRevokedEvent entrega a tu backend de la nube. Consulta Otorgamientos de estructura para el flujo de trabajo de revocación de extremo a extremo de la nube del socio y la app para dispositivos móviles.

Exploración del desarrollador

La API de Automation es una parte de una exploración de desarrollo más grande. Se produce después de integrar las APIs de Structure y Device para garantizar que, cuando un usuario quiera usar una automatización, pueda hacerlo.

1. El desarrollador planifica su automatización y la define con Automation DSL.
2. El desarrollador incorpora la definición de automatización en una app para Android de Kotlin.
3. La app presenta automatizaciones a un usuario en función de la información sobre sus dispositivos, incluidos los atributos, los comandos y los eventos, recopilados con la API de Discovery o la API de Device.
   1. Con la API de Discovery, la app puede generar un borrador de automatización personalizado para los tipos de dispositivos y los atributos presentes en la estructura del usuario, con o sin la entrada del usuario.
   2. La API de Device puede proporcionar la mayor parte de la misma información que la API de Discovery, pero no está optimizada para casos de uso de automatización. Consulta Comparación entre la API de Device y la API de Discovery para obtener más detalles.
4. La app crea la automatización real que está vinculada a la estructura seleccionada.
5. La automatización ahora está disponible en la estructura del usuario y se puede ejecutar o borrar con los métodos de la API de Structure.

El usuario puede crear instancias nuevas de la automatización en cualquier momento, seleccionar una estructura diferente o, según la lógica de la app, quizás un conjunto diferente de dispositivos. Cada vez que lo hace, la app genera una instancia nueva de la automatización.

En la situación más básica, puedes sugerir a tus usuarios una automatización predefinida que realice una tarea relativamente básica. Como alternativa, puedes presentar un esqueleto de una automatización que el usuario personalice para satisfacer sus necesidades. También puedes escribir un editor de automatización abierto que permita al usuario crear automatizaciones complejas con todos los bloques de compilación disponibles en la API de Automation.

Sugerencias de automatización

Las APIs de Home pueden sugerir automatizaciones para un Structure en función de factores como los tipos de dispositivos presentes en el espacio.

Las sugerencias de automatización están representadas por la AutomationSuggestion clase.

La Structure interfaz abarca la HasSuggestions interfaz, que proporciona la suggestions() función, que muestra una colección de sugerencias de automatización.

Los métodos likeSuggestion() y dislikeSuggestion() están diseñados para conectarse a los controles de la IU thumb_up y thumb_down que el usuario puede presionar para proporcionar comentarios.

Un tercer método, clearSuggestionFeedback(), permite al usuario quitar sus comentarios para una automatización sugerida.

Los comentarios de los usuarios influyen en las sugerencias futuras.

En este ejemplo, se muestra cómo recuperar las sugerencias de automatización disponibles para un Structure, extraer un ID de sugerencia y registrar los comentarios de los usuarios con likeSuggestion(), clearSuggestionFeedback(), y dislikeSuggestion().

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch

class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {

  fun loadAndGiveFeedback() {
    viewModelScope.launch {
      // 1. Fetch suggestions from structure
      val suggestions = structure.suggestions()
      val firstSuggestion = suggestions.firstOrNull() ?: return@launch

      // Extract string suggestion ID
      val suggestionId: String = firstSuggestion.id.id

      // 2. Like the suggestion (thumbs up)
      val liked = structure.likeSuggestion(suggestionId)

      // 3. Clear previous feedback if the user toggled it off
      if (liked) {
        structure.clearSuggestionFeedback(suggestionId)
      }

      // 4. Dislike the suggestion (thumbs down)
      structure.dislikeSuggestion(suggestionId)
    }
  }
}

Parámetros de comando dinámicos

Los parámetros de comando dinámicos permiten a los desarrolladores crear parámetros de acción que se resuelven de forma dinámica en el tiempo de ejecución en lugar de depender estrictamente de valores estáticos y constantes. Esto permite dos capacidades principales:

• Referencias que pasan el valor de una propiedad de un activador (como una carga útil de evento) o un nodo de lector de estado, o de variables locales declaradas dentro del flujo de automatización
• Expresiones que capturan valores dinámicos de tiempo de ejecución (como una propiedad de evento o un valor de estado) y pasan el valor dinámico directamente a un parámetro de comando

Caso de uso

Vincula un interruptor giratorio físico que envía un evento de presión múltiple a una luz regulable. El recuento de clics es el valor dinámico que se pasa a un comando de paso LevelControl en el tiempo de ejecución.

Cómo funcionan los parámetros dinámicos

En Automation DSL en Android, los parámetros de comando aceptan Expression o Reference instancias directamente en lugar de valores constantes estáticos. El DSL los encapsula en Parameter definiciones cuando se construye la automatización.

Reglas de validación

Los parámetros de comando dinámicos siguen estas restricciones de validación:

• Se supone que los parámetros dinámicos son válidos estructuralmente durante la detección, ya que las APIs de Discovery solo evalúan las restricciones de valor concretas para los argumentos estáticos.
• Los nodos de referencia o expresión deben aparecer en sentido ascendente en el gráfico de automatización antes de que se haga referencia a ellos en una acción de comando descendente.

Usa parámetros de comando dinámicos en Android

Pasa expresiones dinámicas directamente a los parámetros de comando:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val keypressAutomation = automation {
  name = "Dynamic command parameters example"
  description = "Pass starter event field directly to command"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountExpr,
        )
      )
    }
  }
}

Como alternativa, asigna una expresión a una declaración de variable local y haz referencia a la variable más adelante en el flujo:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val myAutomationWithVariable = automation {
  name = "Dynamic command parameters with variables"
  description = "Declare a variable, assign value, and pass reference"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    val clickCountVar = variable<UInt>()
    clickCountVar.assign(clickCountExpr)

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountVar,
        )
      )
    }
  }
}

Restricciones de tipo

Asegúrate de que los tipos de variables y expresiones se alineen con la definición de tipo de esquema requerida Matter del parámetro de comando receptor (como UShort, UByte o UInt8).

Límites de recursos

Los siguientes límites se aplican a las automatizaciones en las APIs de Home: