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 maximale de génération de rapports.setDelay: utilisé uniquement dans la version 1.0 de HAL. Définit la fréquence d'échantillonnage d'un capteur donné.flush: vide le 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 d'appeler ces fonctions à partir de différents threads.
L'interface définit également plusieurs types utilisés par ces fonctions. Les principaux types sont les suivants :
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 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 les capteurs seront signalés aux applications. En règle générale, 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 descripteur du capteur à activer/désactiver. Le descripteur d'un capteur est défini par le handle champ de sa structure sensor_t.
enabled est défini sur 1 pour activer le capteur ou sur 0 pour le désactiver.
Les capteurs à usage unique se désactivent automatiquement lors de la réception d'un événement,
et ils doivent toujours accepter d'être désactivés via 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 verrouillage partiel au nom des applications.
Les capteurs de réveil, lorsqu'ils diffusent des événements en continu, peuvent empêcher le SoC de passer en mode veille, mais si aucun événement n'a besoin d'être diffusé, le verrouillage 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 sans effet
et réussit.
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 de génération de rapports. Cette fonction peut être appelée lorsque le capteur est activé. Dans ce cas, elle ne doit pas entraîner la perte de mesures du capteur : le passage d'une fréquence d'échantillonnage à une autre ne peut pas entraîner la perte d'événements, ni le passage d'une latence maximale de génération de rapports élevée à une latence maximale de génération de rapports faible.
sensor_handle est le descripteur du capteur à configurer.
flags n'est actuellement pas utilisé.
sampling_period_ns est la période d'échantillonnage à laquelle le capteur
doit s'exécuter, en nanosecondes. Pour en savoir plus, consultez sampling_period_ns for
more details.
max_report_latency_ns est le délai maximal avant que les événements ne soient
signalés via le HAL, en nanosecondes. Pour en savoir plus, consultez le 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(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.
À la place, la fonction batch est appelée pour définir le
sampling_period_ns paramètre.
Dans la version 1.0 de HAL, setDelay était utilisé à la place de batch pour définir sampling_period_ns.
flush(sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Ajoute un événement de vidage terminé à la fin du FIFO matériel pour le capteur spécifié et vide le FIFO. Ces événements sont diffusés comme d'habitude (c'est-à-dire comme si la latence maximale de génération de rapports avait expiré) et supprimés du FIFO.
Le vidage s'effectue 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 toujours réussir et
envoyer un événement de vidage terminé pour ce capteur. Cela s'applique à tous les capteurs autres
que les capteurs à usage unique.
Lorsque flush est appelé, même si un événement de vidage est déjà présent 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 terminé créés.
flush ne s'applique pas aux capteurs à usage unique
. Si sensor_handle fait référence à un capteur à usage unique,
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 à usage unique ou n'a pas été activé, et un numéro 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 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 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 batch fonction 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 inverse : 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 batch fonction est appelée.
flush peut être appelé à tout moment, même sur des capteurs non activés (dans ce cas
il doit renvoyer -EINVAL)
Lorsqu'un capteur est désactivé, activate(..., enable=0) est appelé.
Parallèlement à ces appels, la poll fonction est appelée à plusieurs reprises pour
demander des données. poll peut être appelé même lorsqu'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.
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 du 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 son enregistrement ou de la génération d'événements à partir de celui-ci.
type : type de capteur. Pour en savoir plus, consultez l'explication du type de capteur
dans Que sont les capteurs Android ? et les types de capteurs officiels dans Types de capteurs. Pour les types de capteurs non officiels, type doit commencer par SENSOR_TYPE_DEVICE_PRIVATE_BASE.
stringType : type de capteur sous forme de chaîne. Lorsque le
capteur est d'un type officiel, définissez la valeur sur SENSOR_STRING_TYPE_*. Lorsque
le capteur est d'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 de licornes) 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. 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, ont un
obligatoire requiredPermission. Tous les capteurs fournissant des informations utilisateur sensibles (telles que la fréquence cardiaque) doivent être protégés par une
autorisation.
flags : indicateurs de ce capteur, définissant son mode de génération de rapports et indiquant s'il s'agit d'un capteur de réveil ou non. Par exemple, un capteur de réveil à usage unique
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 de HAL doivent être laissés égaux à 0.
maxRange : valeur maximale que le capteur peut signaler, dans la même unité que les
valeurs signalées. Le capteur doit être en mesure de signaler des valeurs sans saturation
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 à chaque axe. Par exemple, un accéléromètre "+/- 2g"
signalera maxRange = 2*9.81 = 2g.
resolution : plus petite différence de valeur que le capteur peut mesurer.
Généralement calculée 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.
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 Processus 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 du déplacement de l'appareil, la
consommation d'énergie en déplacement est celle indiquée dans le power
champ.
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 pour
plus de détails. Notez que minDelay est
exprimé en microsecondes, tandis que sampling_period_ns est en
nanosecondes. Pour les capteurs de mode de génération de rapports spéciaux et de changement, sauf
indication contraire, minDelay doit être défini sur 0. Pour les capteurs à usage unique, il
doit être défini sur -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 pour
plus de détails. Notez que maxDelay est
exprimé en microsecondes, tandis que sampling_period_ns est en
nanosecondes. Pour les capteurs spéciaux et à usage unique, maxDelay doit être
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, alors
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 de FIFO matériel, cette valeur est égale à 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. Elle permet d'estimer la vitesse à laquelle le FIFO sera plein 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 de
FIFO matériel, fifoMaxEventCount est défini sur 0. Pour en savoir plus, consultez la section Traitement par lot.
Pour les capteurs d'un type officiel, certains champs sont écrasés
par le framework. Par exemple, les capteurs d'accéléromètre
sont obligatoirement en mode de génération de rapports continu, et les moniteurs de fréquence cardiaque sont
obligatoirement 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 via la fonction d’interrogation sont de type sensors_event_t. Voici quelques champs importants de sensors_event_t :
version : doit être sizeof(struct sensors_event_t)
sensor : descripteur du capteur qui a généré l'événement, tel que défini par
sensor_t.handle.
type : type de capteur du capteur qui a 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é effectuée ou une mesure d'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'
elapsedRealtimeNano horloge, et dans le cas des capteurs continus, la gigue
doit être faible. Le filtrage de l'horodatage est parfois nécessaire pour répondre aux exigences du CDD
car l'utilisation uniquement de l'heure d'interruption du SoC pour définir les horodatages
entraîne une gigue trop élevée, et l'utilisation uniquement de l'heure de la puce du capteur pour définir les
horodatages peut entraîner une désynchronisation de l'
elapsedRealtimeNano horloge, car l'horloge du capteur dérive.
data and overlapping fields : 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 signalé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 leur définition de type de capteur.
Événements de vidage terminé des métadonnées
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. Ils possèdent les champs suivants :
version : doit être META_DATA_VERSION
type : doit être SENSOR_TYPE_META_DATA
sensor, reserved, and timestamp : doit être défini sur 0
meta_data.what : contient le type de métadonnées pour cet événement. Il existe actuellement un
seul type de métadonnées valide : META_DATA_FLUSH_COMPLETE.
META_DATA_FLUSH_COMPLETE événements 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 descripteur du capteur qui a été vidé. Ils sont
générés uniquement lorsque flush est appelé sur un capteur. Pour en savoir plus, consultez la section sur
la fonction de vidage.