Cette page a été traduite par l'API Cloud Translation.

Capteurs HAL 1.0

L'interface HAL des capteurs, déclarée dans sensors.h, représente l'interface entre le framework Android et le logiciel spécifique au matériel. Une implémentation HAL doit définir chaque fonction déclarée dans sensors.h. Les fonctions principales sont les suivantes:

get_sensors_list : renvoie la liste de tous les capteurs.
activate : démarre ou arrête un capteur.
batch : définit les paramètres d'un capteur, tels que la fréquence d'échantillonnage et la latence de signalement maximale.
setDelay : utilisé uniquement dans la version 1.0 de HAL. Définit la fréquence d'échantillonnage pour un capteur donné.
flush : vide la file d'attente FIFO du capteur spécifié et signale un événement de vidage terminé une fois cette opération effectuée.
poll : renvoie les événements de capteur disponibles.

L'implémentation doit être thread-safe et permettre l'appel de ces fonctions à partir de différents threads.

L'interface définit également plusieurs types utilisés par ces fonctions. Voici les principaux types:

sensors_module_t
sensors_poll_device_t
sensor_t
sensors_event_t

En plus des sections ci-dessous, consultez sensors.h pour en savoir plus sur ces types.

get_sensors_list(list)

int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t
  const** list);

Fournit la liste des capteurs implémentés par le HAL. Pour en savoir plus sur la définition des capteurs, consultez sensor_t.

L'ordre dans lequel les capteurs apparaissent dans la liste correspond à l'ordre dans lequel ils seront signalés aux applications. En général, les capteurs de base apparaissent en premier, suivis des capteurs composites.

Si plusieurs capteurs partagent le même type de capteur et la même propriété de réveil, le premier de la liste est appelé capteur "par défaut". C'est celle renvoyée par getDefaultSensor(int sensorType, bool wakeUp).

Cette fonction renvoie le nombre de capteurs dans la liste.

active(capteur, vrai/faux)

int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int
  enabled);

Active ou désactive un capteur.

sensor_handle est la poignée du capteur à activer/désactiver. La poignée d'un capteur est définie par le champ handle de sa structure sensor_t.

enabled est défini sur 1 pour activer ou sur 0 pour désactiver le capteur.

Les capteurs à usage unique se désactivent automatiquement à la réception d'un événement. Ils doivent toutefois accepter d'être désactivés via un appel à activate(..., enabled=0).

Les capteurs non réveillés n'empêchent jamais le SoC de passer en mode suspension. Autrement dit, le HAL ne doit pas maintenir un wake-lock partiel au nom des applications.

Lorsqu'ils diffusent des événements en continu, les capteurs de wakeup peuvent empêcher le SoC de passer en mode suspendu. Toutefois, si aucun événement n'est nécessaire, le wakelock partiel doit être libéré.

Si enabled est défini sur 1 et que le capteur est déjà activé, cette fonction est une opération sans effet et réussit.

Si enabled est défini sur 0 et que le capteur est déjà désactivé, cette fonction est une opération no-op et aboutit.

Cette fonction renvoie 0 en cas de réussite et un numéro d'erreur négatif dans le cas contraire.

batch(sensor, flags, sampling period, maximum report latency)

int (*batch)(
     struct sensors_poll_device_1* dev,
     int sensor_handle,
     int flags,
     int64_t sampling_period_ns,
     int64_t max_report_latency_ns);

Définit les paramètres d'un capteur, y compris la fréquence d'échantillonnage et la latence maximale des rapports. Cette fonction peut être appelée lorsque le capteur est activé. Dans ce cas, elle ne doit pas entraîner de pertes des mesures du capteur: le passage d'un taux d'échantillonnage à l'autre ne peut pas entraîner de perte d'événements, ni passer d'une latence de rapport maximale élevée à une latence de rapport maximale faible.

sensor_handle est la poignée du capteur à configurer.

flags n'est actuellement pas utilisé.

sampling_period_ns est la période d'échantillonnage pendant laquelle le capteur doit s'exécuter, en nanosecondes. Pour en savoir plus, consultez sampling_period_ns.

max_report_latency_ns est la durée maximale pendant laquelle les événements peuvent être retardés avant d'être signalés via le HAL, en nanosecondes. Pour en savoir plus, reportez-vous au paragraphe max_report_Latency_ns.

Cette fonction renvoie 0 en cas de réussite et un numéro d'erreur négatif dans le cas contraire.

setDelay(capteur, période d'échantillonnage)

int (*setDelay)(
     struct sensors_poll_device_t *dev,
     int sensor_handle,
     int64_t sampling_period_ns);

Après la version 1.0 de HAL, cette fonction est obsolète et n'est jamais appelée. À la place, la fonction batch est appelée pour définir le paramètre sampling_period_ns.

Dans la version 1.0 de HAL, setDelay était utilisé au lieu de batch pour définir sampling_period_ns.

flush(capteur)

int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

Ajoutez un événement de vidage complet à la fin de la file d'attente FIFO matérielle pour le capteur spécifié et videz la file d'attente FIFO. Ces événements sont diffusés comme d'habitude (c'est-à-dire comme si la latence de création de rapports maximale avait expiré) et supprimés de la file d'attente FIFO.

Le vidage se produit de manière asynchrone (c'est-à-dire que cette fonction doit renvoyer immédiatement un résultat). Si l'implémentation utilise un seul FIFO pour plusieurs capteurs, ce FIFO est effacé et l'événement d'effacement complet n'est ajouté que pour le capteur spécifié.

Si le capteur spécifié ne comporte pas de FIFO (aucune mise en tampon n'est possible) ou si le FIFO était vide au moment de l'appel, flush doit toujours réussir et envoyer un événement de vidage terminé pour ce capteur. Ce principe s'applique à tous les capteurs autres que les capteurs uniques.

Lorsque flush est appelé, même si un événement de vidage est déjà dans la file d'attente FIFO de ce capteur, un événement supplémentaire doit être créé et ajouté à la fin de la file d'attente FIFO, et la file d'attente FIFO doit être vidangée. Le nombre d'appels flush doit être égal au nombre d'événements de vidage complet créés.

flush ne s'applique pas aux capteurs de type one-shot. Si sensor_handle fait référence à un capteur one-shot, flush doit renvoyer -EINVAL et ne générer aucun événement de vidage complet des métadonnées.

Cette fonction renvoie 0 en cas de réussite, -EINVAL si le capteur spécifié est un capteur unique ou n'était pas activé, et un nombre d'erreur négatif dans le cas contraire.

poll()

int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
  count);

Renvoie un tableau de données de capteurs en remplissant l'argument data. Cette fonction doit se bloquer jusqu'à ce que des événements soient disponibles. Il renvoie le nombre d'événements lus en cas de réussite ou un numéro d'erreur négatif en cas d'erreur.

Le nombre d'événements renvoyés dans data doit être inférieur ou égal à l'argument count. Cette fonction ne doit jamais renvoyer 0 (aucun événement).

Séquence d'appels

Lorsque l'appareil démarre, get_sensors_list est appelé.

Lorsqu'un capteur est activé, la fonction batch est appelée avec les paramètres demandés, suivis de activate(..., enable=1).

Notez que dans la version 1_0 de HAL, l'ordre était inverse: activate était appelé en premier, suivi de set_delay.

Lorsque les caractéristiques demandées d'un capteur changent lorsqu'il est activé, la fonction batch est appelée.

flush peut être appelé à tout moment, même sur des capteurs non activés (auquel cas elle doit renvoyer -EINVAL).

Lorsqu'un capteur est désactivé, activate(..., enable=0) est appelé.

Parallèlement à ces appels, la fonction poll est appelée à plusieurs reprises pour demander des données. poll peut être appelé même si aucun capteur n'est activé.

sensors_module_t

sensors_module_t est le type utilisé pour créer le module matériel Android pour les capteurs. L'implémentation du HAL doit définir un objet HAL_MODULE_INFO_SYM de ce type pour exposer la fonction get_sensors_list. Pour en savoir plus, consultez la définition de sensors_module_t dans sensors.h et la définition de hw_module_t.

capteurs_poll_device_t / capteurs_poll_device_1_t

sensors_poll_device_1_t contient le reste des méthodes définies ci-dessus : activate, batch, flush et poll. Son champ common (de type hw_device_t) définit le numéro de version du HAL.

capteur_t

sensor_t représente un capteur Android. Voici quelques-uns de ses champs importants:

name:chaîne visible par l'utilisateur qui représente le capteur. Cette chaîne contient souvent le nom de la pièce du capteur sous-jacent, le type du capteur et s'il s'agit d'un capteur de réveil. Exemples : "Accéléromètre LIS2HH12", "Gyroscope non calibré MAX21000", "Baromètre de réveil BMP280", "Vecteur de rotation du jeu MPU6515"

handle:entier utilisé pour faire référence au capteur lors de son enregistrement ou de la génération d'événements à partir de celui-ci.

type:type du capteur. Pour en savoir plus, consultez la description du type de capteur dans la section Qu'est-ce qu'un capteur Android ? et Types de capteurs pour connaître les types de capteurs officiels. Pour les types de capteurs non officiels, type doit commencer par SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType:type du capteur sous forme de chaîne. Lorsque le capteur a un type officiel, définissez-le sur SENSOR_STRING_TYPE_*. Lorsque le capteur possède un type spécifique au fabricant, stringType doit commencer par le nom de domaine inversé du fabricant. Par exemple, un capteur (par exemple, un détecteur d'unicornes) défini par l'équipe Cool-product de Fictional-Company peut utiliser stringType=”com.fictional_company.cool_product.unicorn_detector”. Le stringType permet d'identifier de manière unique les types de capteurs non officiels. Consultez sensors.h pour plus d'informations sur les types et les types de chaînes.

requiredPermission:chaîne représentant l'autorisation dont les applications doivent disposer pour voir le capteur, s'y enregistrer et recevoir ses données. Une chaîne vide signifie que les applications n'ont pas besoin d'autorisation pour accéder à ce capteur. Certains types de capteurs, comme le cardiofréquencemètre, comportent un requiredPermission obligatoire. Tous les capteurs fournissant des informations utilisateur sensibles (telles que la fréquence cardiaque) doivent être protégés par une autorisation.

flags (indicateurs) : indicateurs associés à ce capteur, définissant son mode de signalement et s'il s'agit d'un capteur d'activation ou non. Par exemple, un capteur de réveil ponctuel aura flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP. Les bits de l'indicateur qui ne sont pas utilisés dans la version actuelle du HAL doivent être laissés égaux à 0.

maxRange:valeur maximale que le capteur peut indiquer, dans la même unité que les valeurs signalées. Le capteur doit pouvoir signaler des valeurs sans saturer dans [-maxRange; maxRange]. Notez que cela signifie que la portée totale du capteur au sens générique est 2*maxRange. Lorsque le capteur indique des valeurs sur plusieurs axes, la plage s'applique à chaque axe. Par exemple, un accéléromètre "+/- 2 g" indique maxRange = 2*9.81 = 2g.

résolution:la plus petite différence de valeur que le capteur peut mesurer. Généralement calculé en fonction de maxRange et du nombre de bits de la mesure.

power:coût énergétique de l'activation du capteur, en milliampères. Cette valeur est presque toujours supérieure à la consommation d'énergie indiquée dans la fiche technique du capteur sous-jacent. Pour en savoir plus, consultez Capteurs de base != capteurs physiques et Procédure de mesure de la consommation d'énergie pour savoir comment mesurer la consommation d'énergie d'un capteur. Si la consommation d'énergie du capteur dépend de la mobilité de l'appareil, la consommation d'énergie en mouvement est celle indiquée dans le champ power.

minDelay:pour les capteurs continus, période d'échantillonnage, en microsecondes, correspondant au débit le plus rapide compatible avec le capteur. Pour en savoir plus sur l'utilisation de cette valeur, consultez sampling_period_ns. Notez que minDelay est exprimé en microsecondes, tandis que sampling_period_ns est exprimé en nanosecondes. Pour les capteurs en cas de modification et les capteurs en mode de création de rapports spéciaux, sauf indication contraire, minDelay doit être défini sur 0. Pour les capteurs ponctuels, la valeur doit être -1.

maxDelay:pour les capteurs continus et à changement, période d'échantillonnage, en microsecondes, correspondant au débit le plus lent compatible avec le capteur. Pour en savoir plus sur l'utilisation de cette valeur, consultez sampling_period_ns. Notez que maxDelay est exprimé en microsecondes, tandis que sampling_period_ns est exprimé en nanosecondes. Pour les capteurs spéciaux et à usage unique, maxDelay doit être défini sur 0.

fifoReservedEventCount:nombre d'événements réservés à ce capteur dans la file d'attente FIFO matérielle. Si un FIFO dédié est disponible pour ce capteur, fifoReservedEventCount correspond à la taille de ce FIFO dédié. Si la file d'attente FIFO est partagée avec d'autres capteurs, fifoReservedEventCount correspond à la taille de la partie de la file d'attente FIFO réservée à ce capteur. Sur la plupart des systèmes FIFO partagés et sur les systèmes qui ne disposent pas d'un FIFO matériel, cette valeur est 0.

fifoMaxEventCount:nombre maximal d'événements pouvant être stockés dans les FIFO de ce capteur. Cette valeur est toujours supérieure ou égale à fifoReservedEventCount. Cette valeur permet d'estimer la rapidité avec laquelle la file d'attente FIFO se remplit lors de l'enregistrement auprès du capteur à un débit spécifique, en supposant qu'aucun autre capteur n'est activé. Sur les systèmes qui ne disposent pas d'une file d'attente FIFO matérielle, fifoMaxEventCount est défini sur 0. Pour en savoir plus, consultez Grouper les tâches.

Pour les capteurs disposant d'un type de capteur officiel, certains champs sont écrasés par le framework. Par exemple, les capteurs de l'accéléromètre doivent obligatoirement avoir un mode de création de rapports continu, et les moniteurs de fréquence cardiaque doivent obligatoirement être protégés par l'autorisation SENSOR_PERMISSION_BODY_SENSORS.

sensors_event_t

Les événements générés par les capteurs Android et signalés via la fonction poll sont de type type sensors_event_t. Voici quelques champs importants de sensors_event_t:

version:doit être sizeof(struct sensors_event_t)

sensor:poignée du capteur qui a généré l'événement, comme défini par sensor_t.handle.

type:type du capteur ayant généré l'événement, tel que défini par sensor_t.type.

timestamp:horodatage de l'événement en nanosecondes. Il s'agit de l'heure à laquelle l'événement s'est produit (un pas a été effectué ou une mesure de l'accéléromètre a été effectuée), et non de l'heure à laquelle l'événement a été signalé. timestamp doit être synchronisé avec la horloge elapsedRealtimeNano. Dans le cas des capteurs continus, le jitter doit être faible. Le filtrage des codes temporels est parfois nécessaire pour répondre aux exigences de la CDD, car n'utiliser que le temps d'interruption du SoC pour définir les codes temporels entraîne un jitter trop élevé, et n'utiliser que le temps de la puce du capteur pour définir les codes temporels peut entraîner une désynchronisation par rapport à l'horloge elapsedRealtimeNano, car l'horloge du capteur dérive.

Données et champs qui se chevauchent:valeurs mesurées par le capteur. La signification et les unités de ces champs sont spécifiques à chaque type de capteur. Pour obtenir une description des champs de données, consultez sensors.h et la définition des différents types de capteurs. Pour certains capteurs, la précision des mesures est également indiquée dans les données, via un champ status. Ce champ n'est transmis que pour certains types de capteurs, et apparaît au niveau de la couche du SDK en tant que valeur de précision. Pour ces capteurs, le fait que le champ d'état doit être défini est mentionné dans la définition de leur type de capteur.

Événements de vidage des métadonnées terminés

Les événements de métadonnées ont le même type que les événements de capteur normaux : sensors_event_meta_data_t = sensors_event_t. Ils sont renvoyés avec d'autres événements de capteur via l'interrogation. Elles contiennent les champs suivants:

version:doit être META_DATA_VERSION

type:doit être SENSOR_TYPE_META_DATA

sensor, reserved et timestamp: doit être égal à 0

meta_data.what:contient le type de métadonnées de cet événement. Il n'existe actuellement qu'un seul type de métadonnées valide: META_DATA_FLUSH_COMPLETE.

Les événements META_DATA_FLUSH_COMPLETE représentent la fin du vidage d'un FIFO de capteur. Lorsque meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor doit être défini sur la poignée du capteur qui a été effacé. Elles sont générées lorsque et seulement lorsque flush est appelé sur un capteur. Pour en savoir plus, consultez la section sur la fonction flush.