HAL de sensores 1.0

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.