L'interface Sensors HAL, 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 FIFO du capteur spécifié et signale un événement de vidage terminé lorsque cette opération est effectuée.poll: renvoie les événements de capteur disponibles.
L'implémentation doit être thread-safe et permettre d'appeler 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_tsensors_poll_device_tsensor_tsensors_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 la 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". Il s'agit de celui renvoyé par getDefaultSensor(int sensorType, bool wakeUp).
Cette fonction renvoie le nombre de capteurs dans la liste.
activate(sensor, true/false)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Active ou désactive un capteur.
sensor_handle est le handle du capteur à activer/désactiver. Le handle d'un capteur est défini par le champ handle de sa structure sensor_t.
enabled est défini sur 1 pour activer le capteur ou sur 0 pour le désactiver.
Les capteurs à déclenchement unique se désactivent automatiquement lorsqu'ils reçoivent un événement, et ils doivent toujours accepter d'être désactivés par un appel à activate(...,
enabled=0).
Les capteurs sans réveil n'empêchent jamais le SoC de passer en mode veille. Autrement dit, le HAL ne doit pas conserver de wakelock partiel au nom des applications.
Lorsque les capteurs de réveil diffusent des événements en continu, ils peuvent empêcher le SoC de passer en mode veille. Toutefois, si aucun événement n'a besoin d'être diffusé, le verrouillage partiel de réveil 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 sans effet et réussit.
Cette fonction renvoie 0 en cas de réussite et un nombre 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é, auquel cas elle ne doit entraîner la perte d'aucune mesure du capteur : le passage d'une fréquence d'échantillonnage à une autre ne peut pas entraîner la perte d'événements, pas plus que le passage d'une latence de rapport maximale élevée à une latence de rapport maximale faible.
sensor_handle est le handle du capteur à configurer.
flags n'est pas utilisé pour le moment.
sampling_period_ns correspond à la période d'échantillonnage à laquelle le capteur doit fonctionner, en nanosecondes. Pour en savoir plus, consultez sampling_period_ns.
max_report_latency_ns correspond au délai maximal (en nanosecondes) avant que les événements ne soient signalés via la HAL. Pour en savoir plus, consultez le paragraphe max_report_latency_ns.
Cette fonction renvoie 0 en cas de réussite et un nombre d'erreur négatif dans le cas contraire.
setDelay(sensor, sampling period)
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.
Au lieu de cela, 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(sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Ajoutez un événement de vidage complet à la fin du FIFO matériel pour le capteur spécifié et videz le FIFO. Ces événements sont distribués comme d'habitude (c'est-à-dire comme si la latence de rapport maximale avait expiré) et supprimés du 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 vidé et l'événement de vidage terminé n'est ajouté que pour le capteur spécifié.
Si le capteur spécifié n'a pas de FIFO (aucune mise en mémoire tampon possible) ou si le FIFO était vide au moment de l'appel, flush doit quand même réussir et envoyer un événement de vidage terminé pour ce capteur. Cela s'applique à tous les capteurs, à l'exception des capteurs ponctuels.
Lorsque flush est appelé, même si un événement de vidage est déjà dans le FIFO pour ce capteur, un événement supplémentaire doit être créé et ajouté à la fin du FIFO, et le FIFO doit être vidé. 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 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 métadonnées de vidage terminé.
Cette fonction renvoie 0 en cas de réussite, -EINVAL si le capteur spécifié est un capteur unique ou n'a pas été activé, et un nombre d'erreur négatif dans les autres cas.
poll()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
count);Renvoie un tableau de données de capteur en remplissant l'argument data. Cette fonction doit bloquer jusqu'à ce que des événements soient disponibles. Elle renvoie le nombre d'événements lus en cas de réussite ou un nombre 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, suivie de activate(..., enable=1).
Notez que dans la version 1.0 de HAL, l'ordre était inversé : activate était appelé en premier, suivi de set_delay.
Lorsque les caractéristiques demandées d'un capteur changent alors qu'il est activé, la fonction batch est appelée.
flush peut être appelé à tout moment, même sur des capteurs non activés (dans ce cas, il doit renvoyer -EINVAL).
Lorsque le capteur est désactivé, activate(..., enable=0) est appelé.
Parallèlement à ces appels, la fonction poll sera 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 de la 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.
sensors_poll_device_t / sensors_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 de la HAL.
sensor_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 de capteur et indique s'il s'agit d'un capteur de réveil. Par exemple, "LIS2HH12 Accelerometer", "MAX21000 Uncalibrated Gyroscope", "BMP280 Wake-up Barometer", "MPU6515 Game Rotation Vector"
handle : entier utilisé pour faire référence au capteur lors de l'enregistrement ou de la génération d'événements à partir de celui-ci.
type : type du capteur. Pour en savoir plus sur les types de capteurs, consultez Que sont les capteurs 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 (disons un détecteur de licornes) défini par l'équipe Cool-product de Fictional-Company peut utiliser stringType=”com.fictional_company.cool_product.unicorn_detector”.
stringType permet d'identifier de manière unique les types de capteurs non officiels. Pour en savoir plus sur les types et les types de chaînes, consultez sensors.h.
requiredPermission : chaîne représentant l'autorisation que les applications doivent posséder pour voir le capteur, s'y enregistrer et recevoir ses données. Une chaîne vide signifie que les applications n'ont besoin d'aucune 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 (comme la fréquence cardiaque) doivent être protégés par une autorisation.
flags : indicateurs de ce capteur, définissant son mode de signalement et indiquant s'il s'agit d'un capteur de réveil 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 HAL actuelle doivent être laissés à 0.
maxRange : valeur maximale que le capteur peut signaler, dans la même unité que les valeurs signalées. Le capteur doit être capable de signaler des valeurs sans saturer dans [-maxRange; maxRange]. Notez que cela signifie que la plage totale du capteur au sens générique est 2*maxRange. Lorsque le capteur signale des valeurs sur plusieurs axes, la plage s'applique à chacun d'eux. Par exemple, un accéléromètre "+/- 2 g" signalera maxRange = 2*9.81 = 2g.
Résolution : plus petite différence de valeur que le capteur peut mesurer.
Généralement calculé en fonction de maxRange et du nombre de bits dans la mesure.
power : coût énergétique de l'activation du capteur, en milliampères.
Il est presque toujours supérieur à 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 Processus de mesure de la puissance pour savoir comment mesurer la consommation d'énergie d'un capteur.
Si la consommation d'énergie du capteur dépend du fait que l'appareil est en mouvement ou non, 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 à la fréquence la plus rapide prise en charge par 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 mode de rapport "on-change" et spécial, 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 de changement, période d'échantillonnage, en microsecondes, correspondant à la fréquence la plus lente prise en charge par 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 ponctuels, maxDelay doit être défini sur 0.
fifoReservedEventCount : nombre d'événements réservés à ce capteur dans le FIFO matériel. S'il existe un FIFO dédié à ce capteur, fifoReservedEventCount correspond à la taille de ce FIFO dédié. Si le FIFO est partagé avec d'autres capteurs, fifoReservedEventCount correspond à la taille de la partie du 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 définie sur 0.
fifoMaxEventCount : nombre maximal d'événements pouvant être stockés dans les FIFO pour ce capteur. Cette valeur est toujours supérieure ou égale à fifoReservedEventCount. Cette valeur permet d'estimer la vitesse à laquelle la FIFO se remplira lors de l'enregistrement du capteur à une fréquence spécifique, en supposant qu'aucun autre capteur n'est activé. Sur les systèmes qui ne disposent pas d'un FIFO matériel, fifoMaxEventCount est défini sur 0. Pour en savoir plus, consultez Traitement par lot.
Pour les capteurs avec un type de capteur officiel, certains champs sont écrasés par le framework. Par exemple, les capteurs d'accéléromètre sont obligatoirement en mode de rapport 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 de capteur générés par les capteurs Android et signalés par 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 : identifiant du capteur qui a généré l'événement, tel que défini par sensor_t.handle.
type : type de 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 (une étape a été franchie 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 l'horloge elapsedRealtimeNano. Dans le cas de capteurs continus, la gigue doit être faible. Le filtrage des codes temporels est parfois nécessaire pour répondre aux exigences du CDD. En effet, l'utilisation de l'heure d'interruption du SoC uniquement pour définir les codes temporels entraîne une gigue trop élevée, et l'utilisation de l'heure du capteur uniquement pour définir les codes temporels peut entraîner une désynchronisation de 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 lectures 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 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 sont du 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 : doivent être définis sur 0
meta_data.what : contient le type de métadonnées pour 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 le handle du capteur qui a été vidé. Elles ne sont générées que lorsque flush est appelé sur un capteur. Pour en savoir plus, consultez la section sur la fonction flush.