La interfaz Sensors HAL, declarada en sensores.h , representa la interfaz entre el marco de trabajo de Android y el software específico del hardware. Una implementación de HAL debe definir cada función declarada en sensores.h. Las funciones principales son:
-
get_sensors_list: devuelve 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 HAL versión 1.0. Establece la frecuencia de muestreo para un sensor determinado. -
flush: descarga el FIFO del sensor especificado e informa un evento de descarga completa cuando se hace esto. -
poll: devuelve los eventos de sensor disponibles.
La implementación debe ser segura para subprocesos y permitir que estas funciones se llamen desde diferentes subprocesos.
La interfaz también define varios tipos utilizados por esas funciones. Los principales tipos son:
-
sensors_module_t -
sensors_poll_device_t -
sensor_t -
sensors_event_t
Además de las secciones a continuación, consulte sensores.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 implementados por el HAL. Consulte 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 los sensores se informarán a las aplicaciones. Por lo general, los sensores base aparecen primero, seguidos de los sensores compuestos.
Si varios sensores comparten el mismo tipo de sensor y 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 devuelve el número 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 identificador del sensor para activar/desactivar. El identificador de un sensor está definido por el campo handle de su estructura sensor_t .
enabled se establece en 1 para habilitar o en 0 para deshabilitar el sensor.
Los sensores de disparo único se desactivan automáticamente al recibir un evento, y aún deben aceptar que se desactiven a través de una llamada para activate(..., enabled=0) .
Los sensores que no son de activación nunca evitan que el SoC entre en modo de suspensión; es decir, la HAL no mantendrá un wake-lock parcial en nombre de las aplicaciones.
Los sensores de activación, cuando entregan eventos continuamente, pueden evitar que el SoC entre en modo de suspensión, pero si no es necesario 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 funciona y tiene éxito.
Si enabled es 0 y el sensor ya está desactivado, esta función no funciona y tiene éxito.
Esta función devuelve 0 en caso de éxito y un número de error negativo en caso contrario.
lote (sensor, banderas, período de muestreo, latencia máxima del informe)
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 causar la pérdida de ninguna medición del sensor: La transición de una frecuencia de muestreo a otra no puede causar la pérdida de eventos, ni la transición de una latencia de informe máxima alta a una baja. latencia máxima del informe.
sensor_handle es el identificador del sensor a configurar.
flags no se utiliza actualmente.
sampling_period_ns es el período de muestreo en el que debe ejecutarse el sensor, en nanosegundos. Consulte sampling_period_ns para obtener más detalles.
max_report_latency_ns es el tiempo máximo que se pueden retrasar los eventos antes de que se informen a través de HAL, en nanosegundos. Consulte el párrafo max_report_latency_ns para obtener más detalles.
Esta función devuelve 0 en caso de éxito y un número de error negativo en caso contrario.
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 está en desuso y nunca se llama. En su lugar, se llama a la función por batch para establecer el parámetro sampling_period_ns .
En HAL versión 1.0, se usó setDelay en lugar de lote para establecer sampling_period_ns .
ras (sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Agregue un evento de descarga completa al final del FIFO del hardware para el sensor especificado y descarga el FIFO; esos eventos se entregan como de costumbre (es decir, como si la latencia máxima de informes hubiera expirado) y se eliminan de FIFO.
El vaciado ocurre de forma asincrónica (es decir, esta función debe regresar de inmediato). Si la implementación utiliza un solo FIFO para varios sensores, ese FIFO se descarga y el evento de descarga completa se agrega 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, el flush aún debe tener éxito y enviar un evento de lavado completo para ese sensor. Esto se aplica a todos los sensores que no sean sensores de disparo único.
Cuando se llama al flush , incluso si ya hay un evento de lavado en el FIFO para ese sensor, se debe crear y agregar uno adicional al final del FIFO, y el FIFO se debe vaciar. El número de llamadas de flush debe ser igual al número de eventos de vaciado completo creados.
el flush no se aplica a los sensores de disparo único ; si sensor_handle se refiere a un sensor de un solo uso, flush debe devolver -EINVAL y no generar ningún evento de metadatos de descarga completa.
Esta función devuelve 0 en caso de éxito, -EINVAL si el sensor especificado es un sensor de un solo uso o no estaba habilitado, y un número de error negativo en caso contrario.
encuesta()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count);
Devuelve una matriz de datos del sensor completando el argumento data . Esta función debe bloquearse hasta que los eventos estén disponibles. Devolverá el número de eventos leídos en caso de éxito, o un número de error negativo en caso de error.
El número de eventos devueltos en data debe ser menor o igual que el argumento de count . Esta función nunca devolverá 0 (sin evento).
Secuencia de llamadas
Cuando el dispositivo arranca, se llama get_sensors_list .
Cuando se activa un sensor, se llamará a la función de batch con los parámetros solicitados, seguido de activate(..., enable=1) .
Tenga en cuenta que en la versión 1_0 de HAL, el orden era el opuesto: activate primero, seguido de set_delay .
Cuando las características solicitadas de un sensor están cambiando mientras está activado, se llama a la función por batch .
flush se puede llamar en cualquier momento, incluso en sensores no activados (en cuyo caso debe devolver -EINVAL )
Cuando un sensor se desactiva, se activate(..., enable=0) .
En paralelo a esas llamadas, la función de poll se llamará repetidamente para solicitar datos. Se puede llamar a la poll incluso cuando no hay sensores activados.
sensores_módulo_t
sensors_module_t es el tipo utilizado para crear el módulo de hardware de Android para los sensores. La implementación de HAL debe definir un objeto HAL_MODULE_INFO_SYM de este tipo para exponer la función get_sensors_list . Consulte la definición de sensores_module_t en sensores.h y la definición de sensors_module_t para hw_module_t más información.
sensores_encuesta_dispositivo_t / sensores_encuesta_dispositivo_1_t
sensors_poll_device_1_t contiene el resto de los métodos definidos anteriormente: activate , procesar por batch , flush y poll . Su campo common (de tipo hw_device_t ) define el número de versión de la HAL.
sensor_t
sensor_t representa un sensor de Android . Estos son algunos de sus campos importantes:
nombre: una cadena visible para el usuario que representa el sensor. Esta cadena suele contener el nombre de la pieza del sensor subyacente, el tipo de sensor y si se trata de un sensor de activación. Por ejemplo, "Acelerómetro LIS2HH12", "Giroscopio sin calibrar MAX21000", "Barómetro de activación BMP280", "Vector de rotación de juegos MPU6515"
identificador: el número entero utilizado para hacer referencia al sensor al registrarse en él o generar eventos a partir de él.
type: El tipo del sensor. Consulte la explicación del tipo de sensor en ¿Qué son los sensores de Android? para obtener más detalles, y consulte Tipos de sensores para conocer los tipos de sensores oficiales. Para tipos de sensores no oficiales, el type debe comenzar con SENSOR_TYPE_DEVICE_PRIVATE_BASE
stringType: el tipo del sensor como una cadena. Cuando el sensor tenga un tipo oficial, configúrelo 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 unicornio) definido por el equipo de Cool-product en Fictional-Company podría usar stringType=”com.fictional_company.cool_product.unicorn_detector” . El stringType se utiliza para identificar de forma única los tipos de sensores no oficiales. Consulte sensores.h para obtener más información sobre tipos y tipos de cadenas.
Permiso requerido: una cadena que representa el permiso que las aplicaciones deben poseer 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 permiso requiredPermission obligatorio. Todos los sensores que brindan información confidencial del usuario (como la frecuencia cardíaca) deben estar protegidos por un permiso.
banderas: Banderas para este sensor, que definen el modo de informe del sensor y si el sensor es un sensor de activación o no. Por ejemplo, un sensor de activación de un disparo tendrá flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . Los bits de la bandera que no se utilizan en la versión actual de HAL deben dejarse igual a 0.
maxRange: el valor máximo que el sensor puede informar, en la misma unidad que los valores informados. El sensor debe poder reportar valores sin saturarse dentro de [-maxRange; maxRange] . Tenga en cuenta que esto significa que el rango total del sensor en 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 "+/- 2g" informará maxRange = 2*9.81 = 2g .
resolución: La diferencia más pequeña en valor que el sensor puede medir. Por lo general, se calcula en función de maxRange y la cantidad de bits en la medición.
potencia: El costo de energía de habilitar el sensor, en miliamperios. Casi siempre es más que el consumo de energía informado en la hoja de datos del sensor subyacente. Consulte Sensores base != sensores físicos para obtener más detalles y consulte Proceso de 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 mientras se mueve es el que se informa en el campo de power .
minDelay: para sensores continuos, el período de muestreo, en microsegundos, correspondiente a la velocidad más rápida que admite el sensor. Consulte sampling_period_ns para obtener detalles sobre cómo se utiliza este valor. Tenga en cuenta que minDelay se expresa en microsegundos, mientras que sampling_period_ns se expresa en nanosegundos. Para sensores de modo de informe especial y de cambio, a menos que se especifique lo contrario, minDelay debe ser 0. Para sensores de una sola acción, debe ser -1.
maxDelay: para sensores continuos y de cambio, el período de muestreo, en microsegundos, correspondiente a la velocidad más lenta que admite el sensor. Consulte sampling_period_ns para obtener detalles sobre cómo se utiliza este valor. Tenga en cuenta que maxDelay se expresa en microsegundos, mientras que sampling_period_ns se expresa en nanosegundos. Para sensores especiales y de un solo disparo, maxDelay debe ser 0.
fifoReservedEventCount: el número de eventos reservados para este sensor en el FIFO del hardware. Si hay un FIFO dedicado para este sensor, entonces fifoReservedEventCount es el tamaño de este FIFO dedicado. Si el FIFO se comparte con otros sensores, fifoReservedEventCount es el tamaño de la parte del FIFO que está reservada para ese sensor. En la mayoría de los sistemas FIFO compartidos y en los sistemas que no tienen un FIFO de hardware, este valor es 0.
fifoMaxEventCount: el número máximo de eventos que se pueden almacenar en los FIFO para este sensor. Siempre es mayor o igual que fifoReservedEventCount . Este valor se usa para estimar qué tan rápido 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. Consulte Procesamiento por lotes para obtener más detalles.
Para los sensores con un tipo de sensor oficial, el marco sobrescribe algunos de los campos. Por ejemplo, los sensores de acelerómetro están obligados a tener un modo de informe continuo y los monitores de frecuencia cardíaca están obligados a estar protegidos por el permiso SENSOR_PERMISSION_BODY_SENSORS .
sensores_event_t
Los eventos de sensores generados por los sensores de Android y notificados a través de la función de encuesta son del type sensors_event_t . Aquí hay algunos campos importantes de sensors_event_t :
versión: debe tener el sizeof(struct sensors_event_t)
sensor: el identificador del sensor que generó el evento, tal como lo define sensor_t.handle .
type: El tipo de sensor del sensor que generó el evento, como lo define sensor_t.type .
timestamp: La marca de tiempo del evento en nanosegundos. Esta 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ó el evento. la timestamp de tiempo debe estar sincronizada con el reloj elapsedRealtimeNano y, en el caso de sensores continuos, la fluctuación debe ser pequeña. El filtrado de marcas de tiempo a veces es necesario para satisfacer los requisitos de CDD, ya que usar solo el tiempo de interrupción del SoC para configurar las marcas de tiempo provoca una fluctuación demasiado alta, y usar solo el tiempo del chip del sensor para configurar las marcas de tiempo puede provocar la desincronización del reloj elapsedRealtimeNano , ya que el el reloj del sensor se desvía.
datos y campos superpuestos: Los valores medidos por el sensor. El significado y las unidades de esos campos son específicos para cada tipo de sensor. Consulte sensores.h y la definición de los diferentes tipos de sensores para obtener una descripción de los campos de datos. Para algunos sensores, la precisión de las lecturas también se informa como parte de los datos, a través de un campo de status . Este campo solo se canaliza para esos tipos de sensores seleccionados y aparece en la capa SDK como un valor de precisión. Para esos sensores, el hecho de que el campo de estado debe establecerse se menciona en su definición de tipo de sensor .
Eventos completos de vaciado 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 devuelven junto con otros eventos del sensor a través de la encuesta. Poseen los siguientes campos:
versión: debe ser META_DATA_VERSION
tipo: debe ser SENSOR_TYPE_META_DATA
sensor, reservado y marca de tiempo : debe ser 0
meta_data.what: Contiene el tipo de metadatos para 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 del lavado de un sensor FIFO. Cuando meta_data.what=META_DATA_FLUSH_COMPLETE , meta_data.sensor debe establecerse en el identificador del sensor que se ha vaciado. Se generan cuando y solo cuando se solicita la flush en un sensor. Consulte la sección sobre la función de descarga para obtener más información.