Descripción general de la API de Automation en Android

Las automatizaciones son una forma de automatizar tareas y parámetros de configuración de dispositivos en una casa. Las automatizaciones están disponibles en el ecosistema de Google Home como rutinas en la Google Home app (GHA) y a través de la 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 las rutinas de GHA y la 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 estándar de Matter y smart home de un dispositivo, como se presentan en las APIs de Home.
• Compatibilidad con flujos de ejecución secuenciales, paralelos y de selección.

Las automatizaciones se escriben con el DSL de automatización, un lenguaje específico de dominio diseñado para crear automatizaciones en Kotlin.

Todos los rasgos y tipos que quieras usar en tu app con las APIs de Device and Structure o Automation deben registrarse durante la inicialización. Consulta Inicializa 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 asociados a esos dispositivos dejarán de funcionar.

Cada vez que se inicie la app, asegúrate de verificar 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 entrega un StructureAccessRevokedEvent a tu backend de la nube. Consulta Permisos de estructura para conocer el flujo de trabajo de revocación de extremo a extremo de la app para dispositivos móviles y la nube del socio.

Exploración del desarrollador

La API de Automation es una parte de un recorrido de desarrollo más amplio. 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 el DSL de Automation.
2. El desarrollador incorpora la definición de automatización en una app para Android en Kotlin.
3. La app presenta automatizaciones a un usuario según la información sobre sus dispositivos, incluidos los rasgos, 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 según 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 Compara la API de Device y la API de Discovery para obtener más detalles.
4. La app crea la automatización real que se vincula a la estructura seleccionada.
5. La automatización ya 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, seleccionando una estructura diferente o, según la lógica de la app, tal vez un conjunto diferente de dispositivos. Cada vez que lo hacen, la app genera una instancia nueva de la automatización.

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

Sugerencias de automatización

   Implementado en la app de ejemplo para Android   

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

Las sugerencias de automatización se representan con la clase AutomationSuggestion.

La interfaz Structure abarca la interfaz HasSuggestions, que proporciona la función suggestions(), que devuelve 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 que el usuario quite sus comentarios sobre 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 que los desarrolladores creen parámetros de acción que se resuelvan de forma dinámica durante el tiempo de ejecución, en lugar de depender estrictamente de valores estáticos y constantes. Esto habilita dos funciones principales:

• Referencias que pasan el valor de una propiedad desde un activador (como una carga útil de evento) o un nodo de lector de estado, o desde variables locales declaradas dentro del flujo de automatización.
• Son expresiones que capturan valores dinámicos del entorno 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íe 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 entorno de ejecución.

Cómo funcionan los parámetros dinámicos

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

Reglas de validación

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

• Se supone que los parámetros dinámicos son estructuralmente válidos durante el descubrimiento, ya que las APIs de descubrimiento solo evalúan las restricciones de valores concretos para los argumentos estáticos.
• Los nodos de referencia o expresión deben aparecer antes en el gráfico de automatización para que se pueda hacer referencia a ellos en una acción de comando posterior.

Usa parámetros de comandos 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 Matter requerida del parámetro de comando receptor (como UShort, UByte o UInt8).

Límites de recursos

Se aplican los siguientes límites a las automatizaciones en las APIs de Home: