La interfaz de la HAL de sensores, declarada en sensors.h, representa la interfaz entre el framework de Android y el 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 la latencia máxima de informes.setDelay: Solo se usa en la versión 1.0 de HAL. Establece la frecuencia de muestreo de un sensor determinado.flush: Vacía el FIFO del sensor especificado e informa un evento de vaciado completo cuando esto se hace.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_tsensors_poll_device_tsensor_tsensors_event_t
Además de las secciones que se indican a continuación, consulta sensors.h para obtener más información sobre esos tipos.
get_sensors_list(list)
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 el que aparecen los sensores en la lista es el orden en el que se informarán a las aplicaciones. Por lo general, los sensores de base aparecen primero, seguidos de 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 muestra getDefaultSensor(int sensorType, bool wakeUp).
Esta función muestra la cantidad de sensores en la lista.
activar(sensor, verdadero/falso)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Activa o desactiva un sensor.
sensor_handle es el control del sensor para activarlo o desactivarlo. 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 desactivarse 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.
Cuando los sensores de activación envían eventos de forma continua, pueden evitar que el SoC entre en modo suspendido, pero si no se debe entregar ningún evento, se debe liberar el bloqueo de activación parcial.
Si enabled es 1 y el sensor ya está activado, esta función no realiza ninguna acción y se realiza correctamente.
Si enabled es 0 y el sensor ya está desactivado, esta función es no-op y se ejecuta correctamente.
Esta función muestra 0 si se realiza correctamente y un número de error negativo en caso contrario.
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 cuyo caso no debe provocar la pérdida de ninguna medición del sensor: la transición de una tasa de muestreo a la otra no puede provocar la pérdida de eventos, ni tampoco la transición de una latencia máxima de informe alta a una latencia máxima de informe baja.
sensor_handle es el identificador 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 se debe ejecutar el sensor, en nanosegundos. Consulta sampling_period_ns para obtener más detalles.
max_report_latency_ns es el tiempo máximo en el que se pueden retrasar los eventos antes de que se informen a través del HAL, en nanosegundos. Consulta el párrafo max_report_latency_ns 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, período de muestreo)
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 dejó de estar disponible y nunca se la llama.
En su lugar, se llama a la función batch para establecer el parámetro sampling_period_ns.
En la versión 1.0 de HAL, se usó setDelay en lugar de lote para establecer sampling_period_ns.
vaciar(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 se realiza de forma asíncrona (es decir, esta función debe mostrarse de inmediato). Si la implementación usa un solo FIFO para varios sensores, ese FIFO se limpia y el evento de vaciado completo solo se agrega para el sensor especificado.
Si el sensor especificado no tiene FIFO (no se puede almacenar 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, excepto a los sensores únicos.
Cuando se llama a flush, incluso si ya hay un evento de limpieza en la fila FIFO de ese sensor, se debe crear uno adicional y agregarlo al final de la fila FIFO, y se debe limpiar la fila FIFO. La cantidad de llamadas a flush debe ser igual a la cantidad de eventos de limpieza completos creados.
flush no se aplica a sensores de un solo intento; si sensor_handle hace referencia a un sensor único, flush debe mostrar -EINVAL y no generar ningún evento de metadatos de limpieza completa.
Esta función muestra 0 si la operación es exitosa, -EINVAL si el sensor especificado es un sensor único o no estaba habilitado, y, en caso contrario, muestra un número de error negativo.
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 debe bloquearse 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 muestra en data debe ser menor o igual que el argumento count. Esta función nunca debe mostrar 0 (sin eventos).
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 los parámetros solicitados, seguida de activate(..., enable=1).
Ten en cuenta que, en la versión 1_0 de HAL, el orden era el opuesto: primero se llamaba a activate y, luego, a 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 en sensores no activados (en cuyo caso debe mostrar -EINVAL).
Cuando se desactive un sensor, se llamará a activate(..., enable=0).
De forma simultánea a esas llamadas, se llamará a la función poll de forma reiterada 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 módulo de 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.
sensors_poll_device_t / sensors_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 de sensor y si es un sensor de activación. Por ejemplo, "LIS2HH12 Accelerometer", "MAX21000 Uncalibrated Gyroscope", "BMP280 Wake-up Barometer", "MPU6515 Game Rotation Vector"
control: Es el número entero que se usa para hacer referencia al sensor cuando te registras en él o generas eventos a partir de él.
type: Es el tipo de sensor. Consulta la explicación del tipo de sensor en ¿Qué son los sensores de Android? para obtener más detalles y Tipos de sensores para ver los tipos de sensores oficiales. Para tipos de sensores no oficiales, type debe comenzar con SENSOR_TYPE_DEVICE_PRIVATE_BASE.
stringType: el tipo de sensor como una cadena Cuando el sensor tenga un tipo oficial, configúralo en SENSOR_STRING_TYPE_*. Cuando el sensor tiene un tipo específico del 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”.
El stringType se usa para identificar de forma exclusiva los tipos de sensores no oficiales. Consulta sensors.h para obtener más información sobre tipos y 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 proporcionan información
sensible del usuario (como la frecuencia cardíaca) deben estar protegidos por un
permiso.
flags: Son marcas para este sensor que definen el modo de generación de informes del sensor y si 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 usan en la versión actual de HAL deben dejarse iguales 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 saturarse dentro de [-maxRange; maxRange]. Ten en cuenta que esto significa que el rango total del sensor en el sentido genérico es 2*maxRange. Cuando el sensor informa valores sobre varios ejes, el rango se aplica a cada eje. Por ejemplo, un acelerómetro de "+/- 2 g" informará 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: Es el costo de energía de habilitar el sensor, expresado en miliamps.
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 = sensores físicos para obtener más detalles y consulta Proceso de medición de energía para obtener información 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 los sensores continuos, es el período de muestreo, en microsegundos, que corresponde a la tasa más rápida que admite el sensor. Consulta sampling_period_ns para obtener 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 de modo de generación de informes especiales y de cambio, a menos que se especifique lo contrario, minDelay debe ser 0. Para los sensores de un solo intento, debe ser -1.
maxDelay: Para los sensores continuos y de cambio, es el período de muestreo, en microsegundos, que corresponde a la velocidad más lenta que admite el sensor. Consulta sampling_period_ns para obtener 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 sensores especiales y de un solo intento, maxDelay debe ser 0.
fifoReservedEventCount: La cantidad de eventos reservados para este sensor en el FIFO de hardware. Si hay una FIFO dedicada para este sensor, entonces fifoReservedEventCount es el tamaño de esta FIFO dedicada. Si la FIFO se comparte con otros sensores, fifoReservedEventCount es el tamaño de la parte de la FIFO que se reserva para ese sensor. En la mayoría de los sistemas de FIFO compartido y en los sistemas 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 un 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.
sensors_event_t
Los eventos del sensor que generan los sensores de Android y que se informan a través de la función poll son de type sensors_event_t. Estos son algunos campos importantes de sensors_event_t:
version: Debe ser sizeof(struct sensors_event_t).
sensor: Es el identificador del sensor que generó el evento, como lo define sensor_t.handle.
type: El tipo de sensor del sensor que generó el evento, como lo define sensor_t.type.
timestamp: Es la marca de tiempo del evento en nanosegundos. Es la hora en que ocurrió el evento (se dio un paso o se realizó una medición del acelerómetro), no la hora en que se informó. timestamp debe estar sincronizado con el reloj 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 el sensor. El significado y las unidades de esos campos son específicos de cada tipo de sensor. Consulta sensors.h y la definición de los diferentes tipos de sensores para obtener una descripción de los 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. En el caso de esos sensores, el hecho de que se debe configurar el campo de estado se menciona en su definición de tipo de sensor.
Eventos de limpieza de metadatos completos
Los eventos de metadatos tienen el mismo tipo que los eventos de sensores 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, solo hay un 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 se debe establecer en el identificador del sensor que se borró. Se generan solo cuando se llama a flush en un sensor. Consulta la sección sobre la función flush para obtener más información.