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 :
-
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 des rapports. -
setDelay
- Utilisé uniquement dans HAL version 1.0. Définit la fréquence d'échantillonnage pour un capteur donné. -
flush
- Vide le FIFO du capteur spécifié et signale un événement flush complete lorsque cela est fait. -
poll
- Renvoie les événements de capteur disponibles.
L'implémentation doit être thread-safe et permettre à ces fonctions d'être appelées à partir de différents threads.
L'interface définit également plusieurs types utilisés par ces fonctions. Les types principaux sont :
-
sensors_module_t
-
sensors_poll_device_t
-
sensor_t
-
sensors_event_t
En plus des sections ci-dessous, voir sensors.h pour plus d'informations sur ces types.
get_sensors_list(liste)
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. Voir sensor_t pour plus de détails sur la façon dont les capteurs sont définis.
L'ordre dans lequel les capteurs apparaissent dans la liste est l'ordre dans lequel les capteurs seront signalés aux applications. Habituellement, 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 celui renvoyé par getDefaultSensor(int sensorType, bool wakeUp)
.
Cette fonction renvoie le nombre de capteurs dans la liste.
activer (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 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 ou sur 0 pour désactiver le capteur.
Les capteurs monocoup se désactivent automatiquement lors de la réception d'un événement, et ils doivent encore accepter d'être désactivés via un appel à activate(..., enabled=0)
.
Les capteurs de non-réveil n'empêchent jamais le SoC de passer en mode veille ; c'est-à-dire que la couche HAL ne doit pas détenir de verrouillage de réveil partiel au nom des applications.
Les capteurs de réveil, lorsqu'ils délivrent des événements en continu, peuvent empêcher le SoC de passer en mode veille, mais si aucun événement ne doit être livré, le verrouillage de réveil partiel doit être libéré.
Si enabled
est 1 et que le capteur est déjà activé, cette fonction est un no-op et réussit.
Si enabled
est 0 et que le capteur est déjà désactivé, cette fonction est un no-op et réussit.
Cette fonction renvoie 0 en cas de succès et un numéro d'erreur négatif dans le cas contraire.
lot (capteur, drapeaux, période d'échantillonnage, latence maximale du rapport)
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, notamment la fréquence d'échantillonnage et la latence maximale des rapports . Cette fonction peut être appelée alors que le capteur est activé, auquel cas elle ne doit entraîner aucune perte des mesures du capteur : le passage d'un taux d'échantillonnage à l'autre ne peut pas entraîner de perte d'événements, pas plus que le passage d'une latence de rapport maximale élevée à une faible latence maximale des rapports.
sensor_handle
est le handle du capteur à configurer.
flags
est actuellement inutilisé.
sampling_period_ns
est la période d'échantillonnage à laquelle le capteur doit fonctionner, en nanosecondes. Voir sampling_period_ns pour plus de détails.
max_report_latency_ns
est le temps maximal pendant lequel les événements peuvent être retardés avant d'être signalés via HAL, en nanosecondes. Voir le paragraphe max_report_latency_ns pour plus de détails.
Cette fonction renvoie 0 en cas de succès 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. Au lieu de cela, la fonction batch
est appelée pour définir le paramètre sampling_period_ns
.
Dans HAL version 1.0, setDelay était utilisé à la place de batch pour définir sampling_period_ns .
rincer (capteur)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Ajouter un événement de vidage complet à la fin de la FIFO matérielle pour le capteur spécifié et vider la FIFO ; ces événements sont livrés comme d'habitude (c'est-à-dire comme si la latence de rapport maximale avait expiré) et supprimés de la FIFO.
Le vidage se produit de manière asynchrone (c'est-à-dire que cette fonction doit revenir immédiatement). Si l'implémentation utilise un seul FIFO pour plusieurs capteurs, ce FIFO est vidé et l'événement de vidage complet est ajouté uniquement pour le capteur spécifié.
Si le capteur spécifié n'a pas de FIFO (pas de mise en mémoire tampon possible), ou si le FIFO était vide au moment de l'appel, le flush
doit toujours réussir et envoyer un événement de vidage complet pour ce capteur. Ceci s'applique à tous les capteurs autres que les capteurs monocoup.
Lorsque le flush
est appelé, même si un événement de vidage est déjà dans la FIFO pour ce capteur, un événement supplémentaire doit être créé et ajouté à la fin de la FIFO, et la FIFO doit être vidée. Le nombre d'appels de flush
doit être égal au nombre d'événements de vidage complet créés.
flush
ne s'applique pas aux capteurs monocoup ; si sensor_handle
fait référence à un capteur unique, flush
doit renvoyer -EINVAL
et ne pas générer d'événement de métadonnées flush complete.
Cette fonction renvoie 0 en cas de succès, -EINVAL
si le capteur spécifié est un capteur monocoup ou n'a pas été activé, et un numéro d'erreur négatif dans le cas contraire.
sondage()
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. Il renverra le nombre d'événements lus en cas de succès, 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 retourner 0 (pas d'é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 HAL version 1_0, l'ordre était le contraire : 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 (auquel cas il doit renvoyer -EINVAL
)
Lorsqu'un capteur est désactivé, activate(..., enable=0)
sera appelé.
Parallèlement à ces appels, la fonction d' poll
sera appelée à plusieurs reprises pour demander des données. le poll
peut être appelé même lorsqu'aucun capteur n'est activé.
capteurs_module_t
sensors_module_t
est le type utilisé pour créer le module matériel Android pour les capteurs. L'implémentation de HAL doit définir un objet HAL_MODULE_INFO_SYM
de ce type pour exposer la fonction get_sensors_list . Voir la définition de sensors_module_t
dans Sensors.h et la définition de hw_module_t
pour plus d'informations.
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 de la HAL.
capteur_t
sensor_t
représente un capteur Android . Voici quelques-uns de ses domaines importants :
name : une chaîne visible par l'utilisateur qui représente le capteur. Cette chaîne contient souvent le nom de la partie du capteur sous-jacent, le type du capteur et s'il s'agit d'un capteur de réveil. Par exemple, "Accéléromètre LIS2HH12", "Gyroscope non calibré MAX21000", "Baromètre de réveil BMP280", "Vecteur de rotation de jeu MPU6515"
handle : L'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 : le type de capteur. Voir l'explication du type de capteur dans Que sont les capteurs Android ? pour plus de détails, et voir Types de capteurs pour les types de capteurs officiels. Pour les types de capteurs non officiels, type
doit commencer par SENSOR_TYPE_DEVICE_PRIVATE_BASE
stringType : le 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 a un type spécifique au fabricant, stringType
doit commencer par le nom de domaine inverse du fabricant. Par exemple, un capteur (disons un détecteur de licorne) défini par l'équipe Cool-product de Fictional-Company pourrait utiliser stringType=”com.fictional_company.cool_product.unicorn_detector”
. Le stringType
est utilisé pour identifier de manière unique les types de capteurs non officiels. Voir Sensors.h pour plus d'informations sur les types et les types de chaînes.
requiredPermission : une 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 ne nécessitent aucune autorisation pour accéder à ce capteur. Certains types de capteurs comme le moniteur de fréquence cardiaque 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 : drapeaux pour ce capteur, définissant le mode de rapport du capteur et indiquant si le capteur est un capteur de réveil ou non. Par exemple, un capteur de réveil ponctuel aura des flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP
. Les bits du drapeau qui ne sont pas utilisés dans la version actuelle de HAL doivent être laissés égaux à 0.
maxRange : La valeur maximale que le capteur peut rapporter, dans la même unité que les valeurs rapportées. Le capteur doit pouvoir rapporter 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 à chaque axe. Par exemple, un accéléromètre "+/- 2g" indiquera 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 dans la mesure.
power : Le coût énergétique de l'activation du capteur, en milliampères. C'est presque toujours plus que la consommation d'énergie indiquée dans la fiche technique du capteur sous-jacent. Voir Capteurs de base != capteurs physiques pour plus de détails et voir Processus de mesure de puissance pour plus de détails sur la façon de mesurer la consommation électrique d'un capteur. Si la consommation d'énergie du capteur dépend du déplacement de l'appareil, la consommation d'énergie pendant le déplacement est celle indiquée dans le champ d' power
.
minDelay : pour les capteurs continus, la période d'échantillonnage, en microsecondes, correspondant à la vitesse la plus rapide prise en charge par le capteur. Voir sampling_period_ns pour plus de détails sur la façon dont cette valeur est utilisée. Attention, minDelay
est exprimé en microsecondes alors que sampling_period_ns
est en nanosecondes. Pour les capteurs en cas de changement et en mode de rapport spécial, sauf indication contraire, minDelay
doit être égal à 0. Pour les capteurs ponctuels, il doit être égal à -1.
maxDelay : pour les capteurs continus et à changement, la période d'échantillonnage, en microsecondes, correspondant au taux le plus lent pris en charge par le capteur. Voir sampling_period_ns pour plus de détails sur la façon dont cette valeur est utilisée. Attention, maxDelay
est exprimé en microsecondes alors que sampling_period_ns
est en nanosecondes. Pour les capteurs spéciaux et ponctuels, maxDelay
doit être égal à 0.
fifoReservedEventCount : nombre d'événements réservés à ce capteur dans la FIFO matérielle. S'il existe une FIFO dédiée pour ce capteur, alors fifoReservedEventCount
est la taille de cette FIFO dédiée. Si la FIFO est partagée avec d'autres capteurs, fifoReservedEventCount
est la taille de la partie de la FIFO réservée à ce capteur. Sur la plupart des systèmes FIFO partagés et sur les systèmes qui n'ont pas de FIFO matériel, cette valeur est 0.
fifoMaxEventCount : nombre maximal d'événements pouvant être stockés dans les FIFO pour ce capteur. Il est toujours supérieur ou égal à fifoReservedEventCount
. Cette valeur est utilisée pour estimer la vitesse à laquelle le FIFO se remplira lors de l'enregistrement sur le capteur à une fréquence spécifique, en supposant qu'aucun autre capteur n'est activé. Sur les systèmes qui n'ont pas de FIFO matériel, fifoMaxEventCount
est 0. Voir Mise en lot pour plus de détails.
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 forcés d'avoir un mode de rapport continu et les moniteurs de fréquence cardiaque sont forcés d'être protégés par l'autorisation SENSOR_PERMISSION_BODY_SENSORS
.
capteurs_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 : le handle du capteur qui a généré l'événement, tel que défini par sensor_t.handle
.
type : Le type de capteur du capteur qui a généré l'événement, tel que défini par sensor_t.type
.
horodatage : horodatage de l'événement en nanosecondes. Il s'agit de l'heure à laquelle l'événement s'est produit (un pas a été franchi ou une mesure de l'accéléromètre a été effectuée), et non l'heure à laquelle l'événement a été signalé. l' timestamp
doit être synchronisé avec l'horloge elapsedRealtimeNano
et, dans le cas de capteurs continus, la gigue doit être faible. Le filtrage d'horodatage est parfois nécessaire pour satisfaire aux exigences CDD, car l'utilisation uniquement du temps d'interruption du SoC pour définir les horodatages provoque une gigue trop élevée, et l'utilisation uniquement du temps de la puce du capteur pour définir les horodatages peut entraîner une désynchronisation de l'horloge elapsedRealtimeNano
, car le l'horloge du capteur dérive.
données et champs qui se chevauchent : Les valeurs mesurées par le capteur. La signification et les unités de ces champs sont spécifiques à chaque type de capteur. Voir capteurs.h et la définition des différents types de capteurs pour une description des champs de données. Pour certains capteurs, la précision des lectures est également signalée dans le cadre des données, via un champ d' status
. Ce champ n'est transmis que pour les types de capteurs sélectionnés, apparaissant au niveau de la couche SDK sous la forme d'une 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 complets de vidage des métadonnées
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 par sondage. Ils possèdent les champs suivants :
version : Doit être META_DATA_VERSION
type : Doit être SENSOR_TYPE_META_DATA
capteur, réservé et horodatage : Doit être 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
.
Les événements META_DATA_FLUSH_COMPLETE
représentent l'achèvement du vidage d'une 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é. Ils sont générés quand et seulement quand la flush
d'eau est appelée sur un capteur. Voir la section sur la fonction de rinçage pour plus d'informations.