La interfaz Sensors HAL, declarada en sensors.h , representa la interfaz entre el marco de trabajo de Android y el software específico del hardware. Una implementación 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: se utiliza solo en HAL versión 1.0. Establece la frecuencia de muestreo para un sensor determinado. -
flush: limpia el FIFO del sensor especificado e informa un evento de descarga completa cuando se hace esto. -
poll: devuelve eventos de sensores 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 siguientes, 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 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 se informarán a las aplicaciones. Normalmente, 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 0 para deshabilitar el sensor.
Los sensores de un solo disparo se desactivan automáticamente al recibir un evento, y aún deben aceptar ser desactivados mediante una llamada para activate(..., enabled=0) .
Los sensores que no se activan nunca impiden que el SoC entre en modo de suspensión; es decir, HAL no mantendrá un bloqueo de activación parcial en nombre de las aplicaciones.
Los sensores de activación, cuando envían eventos de forma continua, pueden evitar que el SoC entre en modo de suspensión, pero si no es necesario enviar 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 . Esta función se puede llamar mientras el sensor está activado, en cuyo caso no debe causar que se pierda ninguna medición del sensor: la transición de una frecuencia de muestreo a otra no puede causar pérdida de eventos, ni tampoco 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 actualmente no se utiliza.
sampling_period_ns es el período de muestreo en el que debe funcionar 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 informarse 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, periodo 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 batch para establecer el parámetro sampling_period_ns .
En HAL versión 1.0, se usó setDelay en lugar de lote para configurar sampling_period_ns .
enjuague (sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Agregue un evento de descarga completa al final del FIFO de hardware para el sensor especificado y purgue el FIFO; esos eventos se entregan como de costumbre (es decir, como si la latencia máxima de informes hubiera expirado) y se eliminan del FIFO.
La descarga se produce de forma asincrónica (es decir, esta función debe regresar inmediatamente). Si la implementación utiliza un único FIFO para varios sensores, ese FIFO se vacía y el evento de descarga completa se agrega solo para el sensor especificado.
Si el sensor especificado no tiene FIFO (no es posible 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 descarga completa para ese sensor. Esto se aplica a todos los sensores excepto a los sensores de un solo disparo.
Cuando se llama a flush , incluso si ya hay un evento de descarga en el FIFO para ese sensor, se debe crear uno adicional y agregarlo al final del FIFO, y se debe vaciar el FIFO. La cantidad de llamadas flush debe ser igual a la cantidad de eventos de descarga completa creados.
flush no se aplica a los sensores de un solo disparo ; si sensor_handle se refiere a un sensor de un solo disparo, flush debe devolver -EINVAL y no generar ningún evento de metadatos completos de descarga.
Esta función devuelve 0 en caso de éxito, -EINVAL si el sensor especificado es un sensor de un solo disparo 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.
La cantidad de eventos devueltos en data debe ser menor o igual que el argumento 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 batch con los parámetros solicitados, seguido de activate(..., enable=1) .
Tenga en cuenta que en HAL versión 1_0, el orden era el opuesto: primero se llamó a activate , seguido de set_delay .
Cuando las características solicitadas de un sensor cambian mientras está activado, se llama a la función 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 llamará activate(..., enable=0) .
Paralelamente a esas llamadas, se llamará repetidamente a la función poll para solicitar datos. poll se puede llamar incluso cuando no hay sensores activados.
sensores_module_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 sensors_module_t en sensors.h y la definición de hw_module_t para obtener más información.
sensores_poll_device_t / sensores_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 de HAL.
sensor_t
sensor_t representa un sensor de Android . Éstos 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 es un sensor de activación. Por ejemplo, “Acelerómetro LIS2HH12”, “Giroscopio no calibrado MAX21000”, “Barómetro de despertador BMP280”, “Vector de rotación de juego MPU6515”
handle: El número entero utilizado para referirse al sensor al registrarse en él o generar eventos a partir de él.
tipo: 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 consulte 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: el tipo de sensor como cadena. Cuando el sensor tiene 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 (digamos 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 tipos de sensores no oficiales. Consulte sensores.h para obtener más información sobre tipos y tipos de cadenas.
requirePermission: 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 requiredPermission obligatorio obligatorio. Todos los sensores que proporcionen información sensible al usuario (como la frecuencia cardíaca) deben estar protegidos mediante un permiso.
flags: Banderas para este sensor, que definen el modo de informe del sensor y si el sensor es un sensor de despertador o no. Por ejemplo, un sensor de activación de un solo 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 HAL actual deben dejarse iguales a 0.
maxRange: el valor máximo que el sensor puede informar, en la misma unidad que los valores informados. El sensor debe poder informar 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 en 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 de valor que el sensor puede medir. Generalmente 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 miliAmps. Casi siempre es mayor 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 está en movimiento, el consumo de energía en movimiento es el que se informa en el campo 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 está en nanosegundos. Para sensores en modo de informe especial y en cambio, a menos que se especifique lo contrario, minDelay debe ser 0. Para sensores de un solo disparo, debe ser -1.
maxDelay: para sensores continuos y en 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 está 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 compartido y en sistemas que no tienen 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. Esto siempre es mayor o igual a fifoReservedEventCount . Este valor se utiliza 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 sistemas que no tienen un FIFO de hardware, fifoMaxEventCount es 0. Consulte Procesamiento por lotes para obtener más detalles.
Para sensores con un tipo de sensor oficial, el marco sobrescribe algunos de los campos. Por ejemplo, los sensores del 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 sensores de Android y reportados a través de la función de encuesta son de type sensors_event_t . A continuación se muestran algunos campos importantes de sensors_event_t :
versión: debe ser sizeof(struct sensors_event_t)
sensor: el identificador del sensor que generó el evento, según lo definido por sensor_t.handle .
tipo: el tipo de sensor que generó el evento, según lo definido por sensor_t.type .
marca de tiempo: 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. timestamp debe sincronizarse 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 causa una fluctuación demasiado alta, y usar solo el tiempo del chip del sensor para configurar las marcas de tiempo puede causar 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 de 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 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 se debe configurar el campo de estado se menciona en la definición del 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 de sensores mediante una 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 existe 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 se debe configurar en el identificador del sensor que se ha lavado. Se generan cuando y sólo cuando se solicita flush en un sensor. Consulte la sección sobre la función de descarga para obtener más información.