La interfaz de la HAL de sensores, declarada en sensors.h, representa la interfaz entre el framework de Android y las software específico de hardware. Una implementación de HAL debe definir cada función declarada en sensors.h. Las funciones principales son las siguientes:
get_sensors_list
: Muestra la lista de todos los sensores.activate
: Inicia o detiene un sensor.batch
: Establece los parámetros de un sensor, como la frecuencia de muestreo y el valor máximo. la latencia de informes.setDelay
: Solo se usa en la versión 1.0 de HAL. Fija la frecuencia de muestreo de un sensor dado.flush
: Limpia el FIFO del sensor especificado e informa un vaciado completo. cuando esto esté listo.poll
: Muestra los eventos de sensores disponibles.
La implementación debe ser segura para subprocesos y permitir que se llame a estas funciones desde diferentes subprocesos.
La interfaz también define varios tipos que usan esas funciones. Los tipos principales son los siguientes:
sensors_module_t
sensors_poll_device_t
sensor_t
sensors_event_t
Además de las secciones a continuación, consulta sensors.h para obtener más información sobre esos tipos.
get_sensors_list(lista)
int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list);
Proporciona la lista de sensores que implementa el sistema HAL. Consulta sensor_t para obtener detalles sobre cómo se definen los sensores.
El orden en que aparecen los sensores en la lista es el orden en que se informarán a las aplicaciones. Por lo general, los sensores base aparecen y, luego, los sensores compuestos.
Si varios sensores comparten el mismo tipo de sensor y la misma propiedad de activación, el primero de la lista se denomina sensor "predeterminado". Es el que devuelve
getDefaultSensor(int sensorType, bool wakeUp)
Esta función muestra la cantidad de sensores en la lista.
activate(sensor, true/false)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Activa o desactiva un sensor.
sensor_handle
es el controlador del sensor que se activa o desactiva. El identificador de un sensor se define mediante el campo handle
de su estructura sensor_t.
enabled
se establece en 1 para habilitar el sensor o en 0 para inhabilitarlo.
Los sensores únicos se desactivan automáticamente cuando reciben un evento y aún deben aceptar que se desactiven mediante una llamada a activate(...,
enabled=0)
.
Los sensores que no activan nunca impiden que el SoC entre en modo suspendido, es decir, el HAL no debe mantener un bloqueo de activación parcial en nombre de las aplicaciones.
Los sensores de activación, cuando se entregan eventos de forma continua, pueden evitar que el SoC en modo de suspensión, pero si no es necesario entregar ningún evento, la se debe liberar el bloqueo de activación.
Si enabled
es 1 y el sensor ya está activado, esta función es no-op.
y tenga éxito.
Si enabled
es 0 y el sensor ya está desactivado, esta función es no-op
y tenga éxito.
Esta función muestra 0 en caso de éxito y, de lo contrario, un número de error negativo.
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);
Establece los parámetros de un sensor, incluida la frecuencia de muestreo y la latencia máxima del informe. Se puede llamar a esta función mientras el sensor está activado, en en este caso, no debe hacer que se pierdan las mediciones de los sensores: de una tasa de muestreo a la otra no puede causar la pérdida de eventos, ni transición de una latencia del informe máxima alta a un informe máximo bajo latencia.
sensor_handle
es el controlador del sensor que se configurará.
flags
no está en uso en este momento.
sampling_period_ns
es el período de muestreo en el que el sensor
debería ejecutarse en nanosegundos. Consulta sampling_period_ns para obtener más detalles.
max_report_latency_ns
es el tiempo máximo durante el cual se pueden ejecutar los eventos
se retrasa antes de informarse a través de la HAL, en nanosegundos. Consulta max_report_Latency_ns
párrafo para obtener más detalles.
Esta función muestra 0 en caso de éxito y, de lo contrario, un número de error negativo.
setDelay(sensor, sampling period)
int (*setDelay)( struct sensors_poll_device_t *dev, int sensor_handle, int64_t sampling_period_ns);
Después de la versión 1.0 de HAL, esta función es obsoleta y nunca se llama.
En su lugar, se llama a la función batch
para establecer la
Parámetro sampling_period_ns
.
En la versión 1.0 de la HAL, se usó setDelay en lugar de lote para configurar sample_period_ns.
flush(sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Agrega un evento de limpieza completa al final de la lista FIFO de hardware del sensor especificado y borra la lista FIFO. esos eventos se entregan como de costumbre (es decir, como si hubiera caducado la latencia máxima de informes) y se quitan de la lista FIFO.
La limpieza ocurre de forma asíncrona (es decir, esta función debe mostrarse de inmediato). Si la implementación usa un solo FIFO para varios sensores, se borra ese FIFO y se agrega el evento de limpieza completa solo para el sensor especificado.
Si el sensor especificado no tiene FIFO (no es posible el almacenamiento en búfer) o si el FIFO estaba vacío en el momento de la llamada, flush
aún debe tener éxito y enviar un evento de limpieza completa para ese sensor. Esto se aplica a todos los sensores que no sean
que los sensores de un solo golpe.
Cuando se llama a flush
, incluso si ya hay un evento de limpieza en la FIFO de ese sensor, se debe crear uno adicional y agregarlo al final de la FIFO, y se debe limpiar la FIFO. La cantidad de llamadas a flush
debe ser igual a la cantidad de eventos de limpieza completos creados.
flush
no se aplica a los sensores únicos. Si sensor_handle
hace referencia a un sensor único, flush
debe mostrar -EINVAL
y no generar ningún evento de metadatos completos.
Esta función muestra 0 si se realiza correctamente, -EINVAL
si el sensor especificado es un sensor único o no se habilitó, y un número de error negativo en caso contrario.
poll()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count);
Devuelve un array de datos del sensor completando el argumento data
. Esta función
se deben bloquear hasta que los eventos estén disponibles. Devolverá la cantidad de eventos leídos si se realiza correctamente o un número de error negativo en caso de que se produzca un error.
La cantidad de eventos que se muestran en data
debe ser menor o igual que
el argumento count
. Esta función nunca debe devolver 0 (ningún evento).
Secuencia de llamadas
Cuando se inicia el dispositivo, se llama a get_sensors_list
.
Cuando se activa un sensor, se llamará a la función batch
con el
los parámetros solicitados, seguidos de activate(..., enable=1)
.
Ten en cuenta que, en la versión 1_0 de HAL, el orden era el opuesto: se llamaba a activate
.
primero y, luego, set_delay
.
Cuando las características solicitadas de un sensor cambian mientras está
activado, se llama a la función batch
.
Se puede llamar a flush
en cualquier momento, incluso con sensores no activados (en cuyo caso
debe mostrar -EINVAL
).
Cuando se desactive un sensor, se llamará a activate(..., enable=0)
.
En paralelo a esas llamadas, se llamará repetidamente a la función poll
para
solicitar datos. Se puede llamar a poll
incluso cuando no hay sensores activados.
sensors_module_t
sensors_module_t
es el tipo que se usa para crear el hardware de Android.
para los sensores. La implementación del sistema HAL debe definir un objeto HAL_MODULE_INFO_SYM
de este tipo para exponer la función get_sensors_list. Consulta la
definición de sensors_module_t
en sensors.h y la definición de hw_module_t
para obtener más información.
sensores_poll_device_t / sensor_poll_device_1_t
sensors_poll_device_1_t
contiene el resto de los métodos definidos anteriormente: activate
, batch
, flush
y poll
. Su campo common
(de tipo hw_device_t) define el número de versión del sistema HAL.
sensor_t
sensor_t
representa un sensor de Android. Estos son algunos de sus campos importantes:
name: Es una cadena visible para el usuario que representa el sensor. A menudo, esta cadena contiene el nombre de la pieza del sensor subyacente, el tipo del sensor y si es un sensor de activación. Por ejemplo, “Acelerómetro LIS2HH12”, "Giroscopio no calibrado MAX21000", "Barómetro BMP280 Wake-up", "Juego MPU6515 Vector de rotación”.
handle: Es el número entero que se usa para hacer referencia al sensor cuando se registra en él. generar eventos a partir de ella.
type: Es el tipo de sensor. Consulta la explicación de los sensores
escribe ¿Qué son los sensores de Android? para obtener más información y consulta Tipos de sensores para conocer los tipos de sensores oficiales. Para tipos de sensores no oficiales, type
debe comenzar con SENSOR_TYPE_DEVICE_PRIVATE_BASE
.
stringType: Es el tipo del sensor como una cadena. Cuando el valor
sensor tiene un tipo oficial, establecido en SENSOR_STRING_TYPE_*
. Cuándo
el sensor tiene un tipo específico de fabricante, stringType
debe
comenzar con el nombre de dominio inverso del fabricante. Por ejemplo, un sensor (por ejemplo, un detector de unicornios) definido por el equipo de Producto-genial en Fictional-Company podría usar stringType=”com.fictional_company.cool_product.unicorn_detector”
.
stringType
se usa para identificar de forma única los tipos de sensores no oficiales. Consulta sensors.h para obtener más información sobre los tipos y los tipos de cadenas.
requiredPermission: Es una cadena que representa el permiso que deben tener las aplicaciones para ver el sensor, registrarse en él y recibir sus datos. Una cadena vacía significa que las aplicaciones no requieren ningún permiso para
acceder a este sensor. Algunos tipos de sensores, como el monitor de frecuencia cardíaca, tienen un
requiredPermission
obligatorio. Todos los sensores que proporcionen información sensible del usuario (como la frecuencia cardíaca) deben estar protegidos por un permiso.
flags: Marcas para este sensor, que definen el modo de informe del sensor y si
si el sensor es un sensor de activación o no. Por ejemplo, un sensor de activación único
tendrá flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP
. Los bits de
la marca que no se usa en la versión actual del HAL debe ser igual a 0.
maxRange: Es el valor máximo que puede informar el sensor, en la misma unidad que los valores informados. El sensor debe poder informar valores sin saturar
en [-maxRange; maxRange]
. Ten en cuenta que esto significa que el rango total de
en el sentido genérico es 2*maxRange
. Cuando el sensor informa valores en varios ejes, el rango se aplica a cada eje. Por ejemplo, un acelerómetro de “+/- 2g” registrará maxRange = 2*9.81 = 2g
.
resolution: Es la diferencia de valor más pequeña que puede medir el sensor.
Por lo general, se calcula en función de maxRange
y la cantidad de bits en la medición.
power: El costo de potencia de habilitar el sensor, en miliA
Esto casi siempre es mayor que el consumo de energía que se informa en la hoja de datos del sensor subyacente. Consulta Sensores base != físico
sensores para obtener más información y consulta Medición de energía
para obtener detalles sobre cómo medir el consumo de energía de un sensor.
Si el consumo de energía del sensor depende de si el dispositivo se está moviendo, el consumo de energía durante el movimiento es el que se informa en el campo power
.
minDelay: para sensores continuos, el período de muestreo, en
microsegundos, que corresponden a la velocidad más rápida que admite el sensor. Consulta sample_period_ns
detalles sobre cómo se usa este valor. Ten en cuenta que minDelay
se expresa en microsegundos, mientras que sampling_period_ns
se expresa en nanosegundos. Para los sensores del modo de informe especial y en caso de cambio, a menos que
de lo contrario, minDelay
debe ser 0. Para los sensores únicos, debe ser -1.
maxDelay: para sensores continuos y de cambio, la capacidad de
tiempo en microsegundos, que corresponde a la velocidad más lenta a la que
admite. Consulta sample_period_ns
detalles sobre cómo se usa este valor. Ten en cuenta que maxDelay
se expresa en microsegundos, mientras que sampling_period_ns
se expresa en nanosegundos. Para los sensores especiales y únicos, maxDelay
debe ser 0.
fifoReservedEventCount: Es la cantidad de eventos reservados para este sensor en la FIFO de hardware. Si hay una FIFO dedicada para este sensor, entonces
fifoReservedEventCount
es el tamaño de esta FIFO dedicada. Si el FIFO es
compartido con otros sensores, fifoReservedEventCount
es el tamaño de la parte de
el FIFO reservado
para ese sensor. En la mayoría de los sistemas FIFO compartidos y en
que no tienen un FIFO de hardware, este valor es 0.
fifoMaxEventCount: Es la cantidad máxima de eventos que se pueden almacenar en los FIFO de este sensor. Siempre es mayor o igual que fifoReservedEventCount
. Este valor se usa para estimar la rapidez con la que se llenará el FIFO cuando se registre en el sensor a una velocidad específica, suponiendo que no se activen otros sensores. En los sistemas que no tienen
FIFO de hardware, fifoMaxEventCount
es 0. Consulta Ejecución por lotes para obtener más detalles.
En el caso de los sensores con un tipo de sensor oficial, el framework reemplaza algunos de los campos. Por ejemplo, los sensores de acelerómetro deben tener un modo de generación de informes continuo, y los monitores de frecuencia cardíaca deben estar protegidos por el permiso SENSOR_PERMISSION_BODY_SENSORS
.
evento_sensores
Los eventos de sensor que generan los sensores de Android y que se informan a través de la función de poll son de type sensors_event_t
. Estos son algunos ejemplos
campos importantes de sensors_event_t
:
version: Debe ser sizeof(struct sensors_event_t)
.
sensor: El controlador del sensor que generó el evento, según lo define
sensor_t.handle
type: El tipo de sensor del sensor que generó el evento, según lo definido por
sensor_t.type
timestamp: Es la marca de tiempo del evento en nanosegundos. Este es el momento en el que
evento específico (se realizó un paso o se realizó una medición con un acelerómetro),
no la hora en que se informó el evento. timestamp
debe sincronizarse con el
elapsedRealtimeNano
y, en el caso de los sensores continuos, el Jitter
debe ser pequeño. A veces, el filtrado de marcas de tiempo es necesario para satisfacer los requisitos del CDD, ya que usar solo el tiempo de interrupción del SoC para establecer las marcas de tiempo causa un jitter demasiado alto y usar solo el tiempo del chip del sensor para establecer las marcas de tiempo puede causar una desincronización del reloj elapsedRealtimeNano
, ya que el reloj del sensor se desplaza.
datos y campos superpuestos: Son los valores que mide la
sensor. El significado y las unidades de esos campos son específicos para cada sensor
el tipo de letra. Consulta sensors.h y la definición de los diferentes tipos de sensores para obtener una descripción de
campos de datos. En el caso de algunos sensores, la exactitud de las lecturas también se informa como parte de los datos, a través de un campo status
. Este campo solo se pasa para esos tipos de sensores seleccionados y aparece en la capa del SDK como un valor de precisión. Para esos sensores, el hecho de que el campo de estado se deba establecer
se menciona en su tipo de sensor
definición.
Eventos completos de limpieza de metadatos
Los eventos de metadatos tienen el mismo tipo que los eventos de sensor normales: sensors_event_meta_data_t = sensors_event_t
. Se muestran junto con otros eventos del sensor a través de la sondeo. Tienen los siguientes campos:
version: Debe ser META_DATA_VERSION
type: Debe ser SENSOR_TYPE_META_DATA
.
sensor, reserved y timestamp: Deben ser 0.
meta_data.what: Contiene el tipo de metadatos de este evento. Actualmente hay un
único tipo de metadatos válido: META_DATA_FLUSH_COMPLETE
.
Los eventos META_DATA_FLUSH_COMPLETE
representan la finalización de la limpieza de un FIFO de sensor. Cuando meta_data.what=META_DATA_FLUSH_COMPLETE
, meta_data.sensor
debe fijarse en la manija del sensor que se purgó. Se generan cuando y solo cuando se llama a flush
en un sensor. Consulta la sección sobre
la función flush para obtener más información.