Présentation de l'API Automation sur Android

Les automatisations permettent d'automatiser les tâches et les paramètres des appareils dans une maison. Elles sont disponibles dans l'écosystème Google Home sous forme de routines dans le Google Home app (GHA) et via le automation script editor sur Google Home for web.

Désormais, les automatisations de l'écosystème Google Home sont disponibles via les API Home pour Android. Elles utilisent les mêmes concepts de base que les GHA routines et l'script editor, mais avec des fonctionnalités améliorées qui ne sont possibles que via les API Home, y compris :

• L'accès à tous les Matter standard et smart home traits pour un appareil, comme présenté dans les API Home.
• La prise en charge des flux d'exécution séquentiels, parallèles et de sélection.

Les automatisations sont écrites à l'aide d'Automation DSL, un langage spécifique au domaine conçu pour créer des automatisations en Kotlin.

Tous les traits et types que vous comptez utiliser dans votre application avec les API Device &Structure ou Automation doivent être enregistrés lors de l'initialisation. Consultez Initialiser la maison sur Android.

Conseils si l'utilisateur révoque les autorisations complètes

Si l'utilisateur révoque les autorisations complètes, toutes les automatisations existantes cesseront de fonctionner. De même, si l'utilisateur révoque l'accès à des appareils spécifiques, les déclencheurs, les conditions et les actions associés à ces appareils cesseront de fonctionner.

Chaque fois que l'application démarre, assurez-vous que les autorisations sont toujours en vigueur. Si elles ont été révoquées, assurez-vous que toutes les données précédentes sont supprimées, y compris celles mises en cache dans l'application.

Lorsque l'accès à la structure est révoqué, un StructureAccessRevokedEvent est envoyé à votre backend cloud. Consultez les autorisations de structure pour le workflow de révocation de bout en bout du cloud partenaire et de l'application mobile.

Parcours du développeur

L'API Automation fait partie d'un parcours de développement plus vaste. Elle intervient après l'intégration des API Structure et Device pour s'assurer que l'utilisateur peut utiliser une automatisation lorsqu'il le souhaite.

1. Le développeur planifie son automatisation et la définit à l'aide d'Automation DSL.
2. Le développeur intègre la définition de l'automatisation dans une application Android Kotlin.
3. L'application présente les automatisations à un utilisateur en fonction des informations sur ses appareils, y compris les traits, les attributs, les commandes et les événements, collectées à l'aide de l'API Discovery ou de l'API Device.
   1. Avec l'API Discovery, l'application peut générer une automatisation brouillon personnalisée en fonction des types d'appareils et des traits présents dans la structure de l'utilisateur, avec ou sans l'intervention de l'utilisateur.
   2. L'API Device peut fournir la plupart des mêmes informations que l'API Discovery, mais elle n'est pas optimisée pour les cas d'utilisation de l'automatisation. Pour en savoir plus, consultez Comparer l'API Device et l'API Discovery.
4. L'application crée l'automatisation réelle qui est associée à la structure sélectionnée.
5. L'automatisation est désormais disponible dans la structure de l'utilisateur et peut être exécutée ou supprimée à l'aide des méthodes de l'API Structure.

L'utilisateur peut créer de nouvelles instances de l'automatisation à tout moment, en sélectionnant une autre structure ou, selon la logique de l'application, peut-être un autre ensemble d'appareils. Chaque fois qu'il le fait, l'application génère une nouvelle instance de l'automatisation.

Dans le scénario le plus simple, vous pouvez suggérer à vos utilisateurs une automatisation prédéfinie qui effectue une tâche relativement simple. Vous pouvez également présenter un squelette d'automatisation que l'utilisateur personnalise en fonction de ses besoins. Vous pouvez aussi écrire un éditeur d'automatisation ouvert qui permet à l'utilisateur de créer des automatisations complexes à l'aide de tous les blocs de construction disponibles dans l'API Automation.

Suggestions d'automatisation

Les API Home peuvent suggérer des automatisations pour un Structure en fonction de facteurs tels que les types d'appareils présents dans l'espace.

Les suggestions d'automatisation sont représentées par la AutomationSuggestion classe.

L'Structure interface englobe l' HasSuggestions interface, qui fournit la suggestions() fonction, laquelle renvoie une collection de suggestions d'automatisation.

Les méthodes likeSuggestion() et dislikeSuggestion() sont destinées à être connectées aux commandes d'interface utilisateur thumb_up et thumb_down que l'utilisateur peut appuyer pour fournir des commentaires.

Une troisième méthode, clearSuggestionFeedback(), permet à l'utilisateur de supprimer ses commentaires pour une automatisation suggérée.

Les commentaires des utilisateurs influencent les suggestions futures.

Cet exemple montre comment récupérer les suggestions d'automatisation disponibles pour un Structure, extraire un ID de suggestion et enregistrer les commentaires de l'utilisateur à l'aide de likeSuggestion(), clearSuggestionFeedback(), et 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)
    }
  }
}

Paramètres de commande dynamiques

Les paramètres de commande dynamiques permettent aux développeurs de créer des paramètres d'action qui se résolvent dynamiquement au moment de l'exécution plutôt que de s'appuyer strictement sur des valeurs statiques et constantes. Cela permet deux fonctionnalités principales :

• Les références qui transmettent la valeur d'une propriété à partir d'un déclencheur (tel qu'une charge utile d'événement) ou d'un nœud de lecteur d'état, ou à partir de variables locales déclarées dans le flux d'automatisation.
• Les expressions qui capturent des valeurs dynamiques au moment de l'exécution (telles qu'une propriété d'événement ou une valeur d'état) et transmettent la valeur dynamique directement dans un paramètre de commande.

Cas d'utilisation

Associez un interrupteur rotatif physique qui envoie un événement multi-appui à une lumière à intensité variable. Le nombre de clics est la valeur dynamique transmise à une commande d'étape LevelControl au moment de l'exécution.

Fonctionnement des paramètres dynamiques

Dans Automation DSL sur Android, les paramètres de commande acceptent Expression ou Reference instances directement à la place des valeurs constantes statiques. Le DSL les encapsule dans des Parameter définitions lors de la construction de l'automatisation.

Règles de validation

Les paramètres de commande dynamiques suivent ces contraintes de validation :

• Les paramètres dynamiques sont supposés être structurellement valides lors de la détection, car les API de détection n'évaluent que les contraintes de valeur concrètes pour les arguments statiques.
• Les nœuds de référence ou d'expression doivent apparaître en amont dans le graphique d'automatisation avant d'être référencés dans une action de commande en aval.

Utiliser des paramètres de commande dynamiques sur Android

Transmettez des expressions dynamiques directement aux paramètres de commande :

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,
        )
      )
    }
  }
}

Vous pouvez également attribuer une expression à une déclaration de variable locale et référencer la variable ultérieurement dans le flux :

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,
        )
      )
    }
  }
}

Contraintes de type

Assurez-vous que les types de variables et d'expressions correspondent à la définition de type de schéma requise du paramètre de commande de réception Matter (par exemple, UShort, UByte ou UInt8).

Limites de ressources

Les limites suivantes s'appliquent aux automatisations dans les API Home :