Contrôler les appareils externes

Dans Android 11 et versions ultérieures, la fonctionnalité de commandes en accès rapide des appareils permet à l'utilisateur d'afficher et de contrôler rapidement des appareils externes tels que des lumières, des thermostats et des appareils photo à partir d'une affordance de l'utilisateur dans trois interactions à partir d'un lanceur d'applications par défaut. L'OEM de l'appareil choisit le lanceur d'applications qu'il utilise. Les agrégateurs d'appareils (par exemple, Google Home) et les applications de fournisseurs tiers peuvent fournir des appareils à afficher dans cet espace. Cette page vous explique comment afficher les commandes de l'appareil dans cet espace et les associer à votre application de contrôle.

Pour ajouter cette prise en charge, créez et déclarez un ControlsProviderService. Créez les commandes compatibles avec votre application en fonction de types de commandes prédéfinis, puis créez des éditeurs pour ces commandes.

Interface utilisateur

Les appareils sont affichés sous Commandes des appareils sous forme de modèles de widgets. Cinq widgets de contrôle d'appareil sont disponibles, comme illustré dans la figure suivante:

Appuyez de manière prolongée sur un widget pour accéder à l'application et mieux le contrôler. Vous pouvez personnaliser l'icône et la couleur de chaque widget, mais pour une expérience utilisateur optimale, utilisez l'icône et la couleur par défaut si elles correspondent à l'appareil.

Créer le service

Cette section explique comment créer le ControlsProviderService. Ce service indique à l'interface utilisateur du système Android que votre application contient des commandes de contrôle des appareils qui doivent apparaître dans la zone Commandes de l'appareil de l'interface utilisateur Android.

L'API ControlsProviderService suppose que vous connaissez les flux réactifs, comme défini dans le projet GitHub "Flux réactifs" et mis en œuvre dans les interfaces de flux Java 9. L'API repose sur les concepts suivants:

• Éditeur:votre application est l'éditeur.
• Abonné:l'UI du système correspond à l'abonné et peut demander un certain nombre de commandes à l'éditeur.
• Abonnement:la période pendant laquelle l'éditeur peut envoyer des mises à jour à l'UI du système. L'éditeur ou l'abonné peut fermer cette fenêtre.

Déclarer le service

Votre application doit déclarer un service, tel que MyCustomControlService, dans son fichier manifeste.

Le service doit inclure un filtre d'intent pour ControlsProviderService. Ce filtre permet aux applications de contribuer aux commandes de l'UI du système.

Vous avez également besoin d'un label qui s'affiche dans les commandes de l'UI du système.

L'exemple suivant montre comment déclarer un service:

<service
    android:name="MyCustomControlService"
    android:label="My Custom Controls"
    android:permission="android.permission.BIND_CONTROLS"
    android:exported="true"
    >
    <intent-filter>
      <action android:name="android.service.controls.ControlsProviderService" />
    </intent-filter>
</service>

Ensuite, créez un fichier Kotlin nommé MyCustomControlService.kt et étendez-le ControlsProviderService():

    class MyCustomControlService : ControlsProviderService() {
        ...
    }
    

    public class MyCustomJavaControlService extends ControlsProviderService {
        ...
    }
    

Sélectionnez le type de commande approprié

L'API fournit des méthodes de compilateur pour créer les commandes. Pour remplir le compilateur, déterminez l'appareil que vous souhaitez contrôler et la manière dont l'utilisateur interagit avec lui. Procédez comme suit :

1. Sélectionnez le type d'appareil représenté par la commande. La classe DeviceTypes est une énumération de tous les appareils compatibles. Le type permet de déterminer les icônes et les couleurs de l'appareil dans l'interface utilisateur.
2. Déterminez le nom visible par l'utilisateur, l'emplacement de l'appareil (par exemple, la cuisine) et d'autres éléments textuels d'UI associés à la commande.
3. Choisissez le meilleur modèle pour faciliter l'interaction des utilisateurs. Les commandes se voient attribuer un ControlTemplate à partir de l'application. Ce modèle présente directement l'état de contrôle à l'utilisateur, ainsi que les modes de saisie disponibles, à savoir ControlAction. Le tableau suivant présente certains des modèles disponibles et les actions compatibles:

Avec ces informations, vous pouvez créer la commande:

• Utilisez la classe de compilateur Control.StatelessBuilder lorsque l'état de la commande est inconnu.
• Utilisez la classe de compilateur Control.StatefulBuilder lorsque l'état de la commande est connu.

Par exemple, pour contrôler une ampoule connectée et un thermostat, ajoutez les constantes suivantes à votre MyCustomControlService:

    private const val LIGHT_ID = 1234
    private const val LIGHT_TITLE = "My fancy light"
    private const val LIGHT_TYPE = DeviceTypes.TYPE_LIGHT
    private const val THERMOSTAT_ID = 5678
    private const val THERMOSTAT_TITLE = "My fancy thermostat"
    private const val THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT
 
    class MyCustomControlService : ControlsProviderService() {
      ...
    }
    

    public class MyCustomJavaControlService extends ControlsProviderService {
 
    private final int LIGHT_ID = 1337;
    private final String LIGHT_TITLE = "My fancy light";
    private final int LIGHT_TYPE = DeviceTypes.TYPE_LIGHT;
    private final int THERMOSTAT_ID = 1338;
    private final String THERMOSTAT_TITLE = "My fancy thermostat";
    private final int THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT;
 
    ...
    }
    

Créer des éditeurs pour les commandes

Une fois la commande créée, elle a besoin d'un éditeur. L'éditeur informe l'UI du système de l'existence de la commande. La classe ControlsProviderService comporte deux méthodes d'éditeur que vous devez remplacer dans le code de votre application:

• createPublisherForAllAvailable(): crée un Publisher pour toutes les commandes disponibles dans votre application. Utilisez Control.StatelessBuilder() afin de créer des objets Control pour cet éditeur.
• createPublisherFor(): crée un Publisher pour une liste de commandes données, identifiées par leurs identifiants de chaîne. Utilisez Control.StatefulBuilder pour créer ces objets Control, car l'éditeur doit attribuer un état à chaque commande.

Créer l'éditeur

Lorsque votre application publie des commandes pour la première fois dans l'UI du système, elle ne connaît pas l'état de chaque commande. L'obtention de l'état peut être une opération chronophage impliquant de nombreux sauts dans le réseau du fournisseur d'appareils. Utilisez la méthode createPublisherForAllAvailable() pour annoncer les contrôles disponibles au système. Cette méthode utilise la classe de compilateur Control.StatelessBuilder, car l'état de chaque commande est inconnu.

Une fois les commandes affichées dans l'interface utilisateur Android , l'utilisateur peut sélectionner des commandes favorites.

Pour utiliser des coroutines Kotlin afin de créer un ControlsProviderService, ajoutez une dépendance à votre build.gradle:

dependencies {
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4"
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4")
}

Une fois vos fichiers Gradle synchronisés, ajoutez l'extrait suivant à votre fichier Service pour implémenter createPublisherForAllAvailable():

    class MyCustomControlService : ControlsProviderService() {
 
      override fun createPublisherForAllAvailable(): Flow.Publisher =
          flowPublish {
              send(createStatelessControl(LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE))
              send(createStatelessControl(THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE))
          }
 
      private fun createStatelessControl(id: Int, title: String, type: Int): Control {
          val intent = Intent(this, MainActivity::class.java)
              .putExtra(EXTRA_MESSAGE, title)
              .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
          val action = PendingIntent.getActivity(
              this,
              id,
              intent,
              PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
          )
 
          return Control.StatelessBuilder(id.toString(), action)
              .setTitle(title)
              .setDeviceType(type)
              .build()
      }
 
          override fun createPublisherFor(controlIds: List): Flow.Publisher {
           TODO()
        }
 
        override fun performControlAction(
            controlId: String,
            action: ControlAction,
            consumer: Consumer
        ) {
            TODO()
        }
    }
    

    public class MyCustomJavaControlService extends ControlsProviderService {
 
        private final int LIGHT_ID = 1337;
        private final String LIGHT_TITLE = "My fancy light";
        private final int LIGHT_TYPE = DeviceTypes.TYPE_LIGHT;
        private final int THERMOSTAT_ID = 1338;
        private final String THERMOSTAT_TITLE = "My fancy thermostat";
        private final int THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT;
 
        private boolean toggleState = false;
        private float rangeState = 18f;
        private final Map> controlFlows = new HashMap<>();
 
        @NonNull
        @Override
        public Flow.Publisher createPublisherForAllAvailable() {
            List controls = new ArrayList<>();
            controls.add(createStatelessControl(LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE));
            controls.add(createStatelessControl(THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE));
            return FlowAdapters.toFlowPublisher(Flowable.fromIterable(controls));
        }
 
        @NonNull
        @Override
        public Flow.Publisher createPublisherFor(@NonNull List controlIds) {
            ReplayProcessor updatePublisher = ReplayProcessor.create();
 
            controlIds.forEach(control -> {
                controlFlows.put(control, updatePublisher);
                updatePublisher.onNext(createLight());
                updatePublisher.onNext(createThermostat());
            });
 
            return FlowAdapters.toFlowPublisher(updatePublisher);
        }
    }
    

Balayez le menu système vers le bas et repérez le bouton Commandes de l'appareil, illustré dans la figure 4:

En appuyant sur Commandes de l'appareil, vous accédez à un deuxième écran dans lequel vous pouvez sélectionner votre application. Une fois que vous avez sélectionné votre application, l'extrait précédent crée un menu système personnalisé affichant vos nouvelles commandes, comme illustré dans la figure 5:

Implémentez maintenant la méthode createPublisherFor() en ajoutant les éléments suivants à votre Service:

    private val job = SupervisorJob()
    private val scope = CoroutineScope(Dispatchers.IO + job)
    private val controlFlows = mutableMapOf>()
 
    private var toggleState = false
    private var rangeState = 18f
 
    override fun createPublisherFor(controlIds: List): Flow.Publisher {
        val flow = MutableSharedFlow(replay = 2, extraBufferCapacity = 2)
 
        controlIds.forEach { controlFlows[it] = flow }
 
        scope.launch {
            delay(1000) // Retrieving the toggle state.
            flow.tryEmit(createLight())
 
            delay(1000) // Retrieving the range state.
            flow.tryEmit(createThermostat())
 
        }
        return flow.asPublisher()
    }
 
    private fun createLight() = createStatefulControl(
        LIGHT_ID,
        LIGHT_TITLE,
        LIGHT_TYPE,
        toggleState,
        ToggleTemplate(
            LIGHT_ID.toString(),
            ControlButton(
                toggleState,
                toggleState.toString().uppercase(Locale.getDefault())
            )
        )
    )
 
    private fun createThermostat() = createStatefulControl(
        THERMOSTAT_ID,
        THERMOSTAT_TITLE,
        THERMOSTAT_TYPE,
        rangeState,
        RangeTemplate(
            THERMOSTAT_ID.toString(),
            15f,
            25f,
            rangeState,
            0.1f,
            "%1.1f"
        )
    )
 
    private fun  createStatefulControl(id: Int, title: String, type: Int, state: T, template: ControlTemplate): Control {
        val intent = Intent(this, MainActivity::class.java)
            .putExtra(EXTRA_MESSAGE, "$title $state")
            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        val action = PendingIntent.getActivity(
            this,
            id,
            intent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )
 
        return Control.StatefulBuilder(id.toString(), action)
            .setTitle(title)
            .setDeviceType(type)
            .setStatus(Control.STATUS_OK)
            .setControlTemplate(template)
            .build()
    }
 
    override fun onDestroy() {
        super.onDestroy()
        job.cancel()
    }
 
    

    @NonNull
    @Override
    public Flow.Publisher createPublisherFor(@NonNull List controlIds) {
        ReplayProcessor updatePublisher = ReplayProcessor.create();
 
        controlIds.forEach(control -> {
            controlFlows.put(control, updatePublisher);
            updatePublisher.onNext(createLight());
            updatePublisher.onNext(createThermostat());
        });
 
        return FlowAdapters.toFlowPublisher(updatePublisher);
    }
 
    private Control createStatelessControl(int id, String title, int type) {
        Intent intent = new Intent(this, MainActivity.class)
                .putExtra(EXTRA_MESSAGE, title)
                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        PendingIntent action = PendingIntent.getActivity(
                this,
                id,
                intent,
                PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
        );
 
        return new Control.StatelessBuilder(id + "", action)
                .setTitle(title)
                .setDeviceType(type)
                .build();
    }
 
    private Control createLight() {
        return createStatefulControl(
                LIGHT_ID,
                LIGHT_TITLE,
                LIGHT_TYPE,
                toggleState,
                new ToggleTemplate(
                        LIGHT_ID + "",
                        new ControlButton(
                                toggleState,
                                String.valueOf(toggleState).toUpperCase(Locale.getDefault())
                        )
                )
        );
    }
 
    private Control createThermostat() {
        return createStatefulControl(
                THERMOSTAT_ID,
                THERMOSTAT_TITLE,
                THERMOSTAT_TYPE,
                rangeState,
                new RangeTemplate(
                        THERMOSTAT_ID + "",
                        15f,
                        25f,
                        rangeState,
                        0.1f,
                        "%1.1f"
                )
        );
    }
 
    private  Control createStatefulControl(int id, String title, int type, T state, ControlTemplate template) {
        Intent intent = new Intent(this, MainActivity.class)
                .putExtra(EXTRA_MESSAGE, "$title $state")
                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        PendingIntent action = PendingIntent.getActivity(
                this,
                id,
                intent,
                PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
        );
 
        return new Control.StatefulBuilder(id + "", action)
                .setTitle(title)
                .setDeviceType(type)
                .setStatus(Control.STATUS_OK)
                .setControlTemplate(template)
                .build();
    }
    

Dans cet exemple, la méthode createPublisherFor() contient une fausse implémentation de ce que votre application doit faire: communiquer avec votre appareil pour récupérer son état et émettre cet état au système.

La méthode createPublisherFor() utilise des coroutines et des flux Kotlin pour satisfaire l'API Reactive Streams requise en procédant comme suit:

1. Crée un Flow.
2. Attend une seconde.
3. Crée et émet l'état de l'ampoule connectée.
4. Attend encore une seconde.
5. Crée et émet l'état du thermostat.

Gérer les actions

La méthode performControlAction() signale quand l'utilisateur interagit avec une commande publiée. Le type d'ControlAction envoyé détermine l'action. Effectuez l'action appropriée pour la commande donnée, puis mettez à jour l'état de l'appareil dans l'UI Android.

Pour terminer l'exemple, ajoutez ce qui suit à votre Service:

    override fun performControlAction(
        controlId: String,
        action: ControlAction,
        consumer: Consumer
    ) {
        controlFlows[controlId]?.let { flow ->
            when (controlId) {
                LIGHT_ID.toString() -> {
                    consumer.accept(ControlAction.RESPONSE_OK)
                    if (action is BooleanAction) toggleState = action.newState
                    flow.tryEmit(createLight())
                }
                THERMOSTAT_ID.toString() -> {
                    consumer.accept(ControlAction.RESPONSE_OK)
                    if (action is FloatAction) rangeState = action.newValue
                    flow.tryEmit(createThermostat())
                }
                else -> consumer.accept(ControlAction.RESPONSE_FAIL)
            }
        } ?: consumer.accept(ControlAction.RESPONSE_FAIL)
    }
    

    @Override
    public void performControlAction(@NonNull String controlId, @NonNull ControlAction action, @NonNull Consumer consumer) {
        ReplayProcessor processor = controlFlows.get(controlId);
        if (processor == null) return;
 
        if (controlId.equals(LIGHT_ID + "")) {
            consumer.accept(ControlAction.RESPONSE_OK);
            if (action instanceof BooleanAction) toggleState = ((BooleanAction) action).getNewState();
            processor.onNext(createLight());
        }
        if (controlId.equals(THERMOSTAT_ID + "")) {
            consumer.accept(ControlAction.RESPONSE_OK);
            if (action instanceof FloatAction) rangeState = ((FloatAction) action).getNewValue()
            processor.onNext(createThermostat());
        }
    }
    

Exécutez l'application, accédez au menu Commandes de l'appareil, puis affichez les commandes d'éclairage et de thermostat.