A interface Sensors HAL, declarada emsens.h , representa a interface entre a estrutura Android e o software específico de hardware. Uma implementação HAL deve definir cada função declarada em sensores.h. As principais funções são:
-
get_sensors_list– Retorna a lista de todos os sensores. -
activate- Inicia ou para um sensor. -
batch- Define os parâmetros de um sensor, como frequência de amostragem e latência máxima de relatório. -
setDelay- Usado apenas no HAL versão 1.0. Define a frequência de amostragem para um determinado sensor. -
flush– libera o FIFO do sensor especificado e relata um evento de flush completo quando isso é feito. -
poll- Retorna eventos de sensor disponíveis.
A implementação deve ser thread-safe e permitir que essas funções sejam chamadas de diferentes threads.
A interface também define vários tipos usados por essas funções. Os principais tipos são:
-
sensors_module_t -
sensors_poll_device_t -
sensor_t -
sensors_event_t
Além das seções abaixo, consultesensores.h para obter mais informações sobre esses tipos.
get_sensors_list(lista)
int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list);
Fornece a lista de sensores implementados pelo HAL. Consulte sensor_t para obter detalhes sobre como os sensores são definidos.
A ordem em que os sensores aparecem na lista é a ordem em que os sensores serão reportados às aplicações. Normalmente, os sensores básicos aparecem primeiro, seguidos pelos sensores compostos.
Se vários sensores compartilharem o mesmo tipo de sensor e propriedade de ativação, o primeiro da lista será chamado de sensor “padrão”. É aquele retornado por getDefaultSensor(int sensorType, bool wakeUp) .
Esta função retorna o número de sensores na lista.
ativar(sensor, verdadeiro/falso)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Ativa ou desativa um sensor.
sensor_handle é o identificador do sensor para ativar/desativar. O identificador de um sensor é definido pelo campo handle de sua estrutura sensor_t .
enabled é definido como 1 para ativar ou 0 para desativar o sensor.
Os sensores one-shot se desativam automaticamente ao receber um evento, e ainda devem aceitar ser desativados por meio de uma chamada para activate(..., enabled=0) .
Sensores não ativados nunca impedem que o SoC entre no modo de suspensão; isto é, o HAL não deverá realizar um wake-lock parcial em nome das aplicações.
Os sensores de ativação, ao entregar eventos continuamente, podem impedir que o SoC entre no modo de suspensão, mas se nenhum evento precisar ser entregue, o wake-lock parcial deverá ser liberado.
Se enabled for 1 e o sensor já estiver ativado, esta função é autônoma e é bem-sucedida.
Se enabled for 0 e o sensor já estiver desativado, esta função é autônoma e é bem-sucedida.
Esta função retorna 0 em caso de sucesso e um número de erro negativo caso contrário.
lote (sensor, sinalizadores, período de amostragem, latência máxima do relatório)
int (*batch)(
struct sensors_poll_device_1* dev,
int sensor_handle,
int flags,
int64_t sampling_period_ns,
int64_t max_report_latency_ns);
Define os parâmetros de um sensor, incluindo frequência de amostragem e latência máxima do relatório . Esta função pode ser chamada enquanto o sensor está ativado, caso em que não deve causar a perda de nenhuma medição do sensor: A transição de uma taxa de amostragem para outra não pode causar perda de eventos, nem a transição de uma latência de relatório máxima alta para uma baixa. latência máxima do relatório.
sensor_handle é o identificador do sensor a ser configurado.
flags não está sendo usado no momento.
sampling_period_ns é o período de amostragem em que o sensor deve funcionar, em nanossegundos. Consulte sampling_period_ns para obter mais detalhes.
max_report_latency_ns é o tempo máximo pelo qual os eventos podem ser atrasados antes de serem relatados por meio do HAL, em nanossegundos. Consulte o parágrafo max_report_latency_ns para obter mais detalhes.
Esta função retorna 0 em caso de sucesso e um número de erro negativo caso contrário.
setDelay(sensor, período de amostragem)
int (*setDelay)(
struct sensors_poll_device_t *dev,
int sensor_handle,
int64_t sampling_period_ns);
Após a versão 1.0 do HAL, esta função está obsoleta e nunca é chamada. Em vez disso, a função batch é chamada para definir o parâmetro sampling_period_ns .
Na versão 1.0 do HAL, setDelay foi usado em vez de batch para definir sampling_period_ns .
descarga (sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Adicione um evento flush complete ao final do FIFO de hardware para o sensor especificado e libere o FIFO; esses eventos são entregues normalmente (ou seja: como se a latência máxima de relatório tivesse expirado) e removidos do FIFO.
A liberação acontece de forma assíncrona (ou seja: esta função deve retornar imediatamente). Se a implementação usar um único FIFO para vários sensores, esse FIFO será liberado e o evento flush complete será adicionado apenas para o sensor especificado.
Se o sensor especificado não tiver FIFO (sem buffer possível), ou se o FIFO estiver vazio no momento da chamada, flush ainda deverá ser bem-sucedida e enviar um evento de liberação completa para esse sensor. Isto se aplica a todos os sensores, exceto sensores de disparo único.
Quando flush é chamado, mesmo que um evento de flush já esteja no FIFO desse sensor, um evento adicional deve ser criado e adicionado ao final do FIFO, e o FIFO deve ser liberado. O número de chamadas flush deve ser igual ao número de eventos de conclusão de liberação criados.
flush não se aplica a sensores únicos ; se sensor_handle se referir a um sensor único, flush deverá retornar -EINVAL e não gerar nenhum evento de metadados completo de flush.
Esta função retorna 0 em caso de sucesso, -EINVAL se o sensor especificado for um sensor único ou não estiver habilitado e um número de erro negativo caso contrário.
enquete()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count);
Retorna uma matriz de dados do sensor preenchendo o argumento data . Esta função deve ser bloqueada até que os eventos estejam disponíveis. Ele retornará o número de eventos lidos em caso de sucesso ou um número de erro negativo em caso de erro.
O número de eventos retornados nos data deve ser menor ou igual ao argumento count . Esta função nunca deve retornar 0 (nenhum evento).
Sequência de chamadas
Quando o dispositivo é inicializado, get_sensors_list é chamado.
Quando um sensor é ativado, a função batch será chamada com os parâmetros solicitados, seguida por activate(..., enable=1) .
Observe que na versão HAL 1_0, a ordem era oposta: activate foi chamado primeiro, seguido por set_delay .
Quando as características solicitadas de um sensor mudam enquanto ele está ativado, a função batch é chamada.
flush pode ser chamado a qualquer momento, mesmo em sensores não ativados (nesse caso deve retornar -EINVAL )
Quando um sensor é desativado, activate(..., enable=0) será chamado.
Paralelamente a essas chamadas, a função poll será chamada repetidamente para solicitar dados. poll pode ser chamada mesmo quando nenhum sensor está ativado.
sensores_módulo_t
sensors_module_t é o tipo usado para criar o módulo de hardware Android para os sensores. A implementação do HAL deve definir um objeto HAL_MODULE_INFO_SYM deste tipo para expor a função get_sensors_list . Consulte a definição sensors_module_t emsensores.h e a definição de hw_module_t para obter mais informações.
sensores_poll_device_t / sensores_poll_device_1_t
sensors_poll_device_1_t contém o restante dos métodos definidos acima: activate , batch , flush e poll . Seu campo common (do tipo hw_device_t ) define o número da versão do HAL.
sensor_t
sensor_t representa um sensor Android . Aqui estão alguns de seus campos importantes:
nome: uma string visível ao usuário que representa o sensor. Essa string geralmente contém o nome da peça do sensor subjacente, o tipo do sensor e se é um sensor de despertar. Por exemplo, “Acelerômetro LIS2HH12”, “Giroscópio não calibrado MAX21000”, “Barômetro de despertar BMP280”, “Vetor de rotação de jogo MPU6515”
identificador: O inteiro usado para se referir ao sensor ao registrá-lo ou gerar eventos a partir dele.
tipo: O tipo do sensor. Veja a explicação do tipo de sensor em O que são sensores Android? para obter mais detalhes e consulte Tipos de sensores para tipos de sensores oficiais. Para tipos de sensores não oficiais, type deve começar com SENSOR_TYPE_DEVICE_PRIVATE_BASE
stringType: o tipo do sensor como uma string. Quando o sensor tiver um tipo oficial, configure como SENSOR_STRING_TYPE_* . Quando o sensor possui um tipo específico do fabricante, stringType deve começar com o nome de domínio reverso do fabricante. Por exemplo, um sensor (digamos, um detector de unicórnio) definido pela equipe Cool-product da Fictional-Company poderia usar stringType=”com.fictional_company.cool_product.unicorn_detector” . O stringType é usado para identificar exclusivamente tipos de sensores não oficiais. Consultesensores.h para obter mais informações sobre tipos e tipos de string.
requirePermission: Uma string que representa a permissão que os aplicativos devem possuir para ver o sensor, registrar-se nele e receber seus dados. Uma string vazia significa que os aplicativos não exigem permissão para acessar esse sensor. Alguns tipos de sensores, como o monitor de frequência cardíaca, têm uma requiredPermission obrigatória. Todos os sensores que fornecem informações confidenciais do usuário (como frequência cardíaca) devem ser protegidos por uma permissão.
sinalizadores: sinalizadores para este sensor, definindo o modo de relatório do sensor e se o sensor é um sensor de despertar ou não. Por exemplo, um sensor de ativação única terá flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . Os bits do flag que não são usados na versão atual do HAL devem ser deixados iguais a 0.
maxRange: O valor máximo que o sensor pode reportar, na mesma unidade dos valores reportados. O sensor deve ser capaz de reportar valores sem saturar dentro de [-maxRange; maxRange] . Observe que isso significa que o alcance total do sensor no sentido genérico é 2*maxRange . Quando o sensor reporta valores em vários eixos, o intervalo se aplica a cada eixo. Por exemplo, um acelerômetro “+/- 2g” reportará maxRange = 2*9.81 = 2g .
resolução: A menor diferença no valor que o sensor pode medir. Geralmente calculado com base em maxRange e no número de bits na medição.
potência: O custo de energia para ativar o sensor, em miliamperes. Isso é quase sempre maior que o consumo de energia relatado na folha de dados do sensor subjacente. Consulte Sensores básicos != sensores físicos para obter mais detalhes e consulte Processo de medição de energia para obter detalhes sobre como medir o consumo de energia de um sensor. Se o consumo de energia do sensor depende do dispositivo estar em movimento, o consumo de energia durante o movimento é aquele relatado no campo power .
minDelay: Para sensores contínuos, o período de amostragem, em microssegundos, correspondente à taxa mais rápida que o sensor suporta. Consulte sampling_period_ns para obter detalhes sobre como esse valor é usado. Tenha em atenção que minDelay é expresso em microssegundos enquanto sampling_period_ns é expresso em nanossegundos. Para sensores on-change e modo de relatório especial, salvo especificação em contrário, minDelay deve ser 0. Para sensores one-shot, deve ser -1.
maxDelay: Para sensores contínuos e em mudança, o período de amostragem, em microssegundos, correspondente à taxa mais lenta que o sensor suporta. Consulte sampling_period_ns para obter detalhes sobre como esse valor é usado. Tenha em atenção que maxDelay é expresso em microssegundos, enquanto sampling_period_ns é expresso em nanossegundos. Para sensores especiais e de disparo único, maxDelay deve ser 0.
fifoReservedEventCount: O número de eventos reservados para este sensor no FIFO de hardware. Se houver um FIFO dedicado para este sensor, então fifoReservedEventCount será o tamanho deste FIFO dedicado. Se o FIFO for compartilhado com outros sensores, fifoReservedEventCount será o tamanho da parte do FIFO reservada para esse sensor. Na maioria dos sistemas FIFO compartilhados e em sistemas que não possuem um FIFO de hardware, esse valor é 0.
fifoMaxEventCount: O número máximo de eventos que podem ser armazenados nos FIFOs deste sensor. É sempre maior ou igual a fifoReservedEventCount . Este valor é usado para estimar a rapidez com que o FIFO ficará cheio ao registrar no sensor a uma taxa específica, supondo que nenhum outro sensor esteja ativado. Em sistemas que não possuem um FIFO de hardware, fifoMaxEventCount é 0. Consulte Lote para obter mais detalhes.
Para sensores com tipo de sensor oficial, alguns campos são substituídos pela estrutura. Por exemplo, os sensores do acelerômetro são forçados a ter um modo de relatório contínuo e os monitores de frequência cardíaca são forçados a ser protegidos pela permissão SENSOR_PERMISSION_BODY_SENSORS .
sensores_evento_t
Os eventos de sensor gerados por sensores Android e relatados por meio da função de enquete são do type sensors_event_t . Aqui estão alguns campos importantes sensors_event_t :
versão: Deve ser sizeof(struct sensors_event_t)
sensor: O identificador do sensor que gerou o evento, conforme definido por sensor_t.handle .
type: O tipo de sensor que gerou o evento, conforme definido por sensor_t.type .
carimbo de data/hora: o carimbo de data/hora do evento em nanossegundos. Esta é a hora em que o evento aconteceu (um passo foi dado ou uma medição do acelerômetro foi feita), e não a hora em que o evento foi relatado. timestamp deve estar sincronizado com o relógio elapsedRealtimeNano e, no caso de sensores contínuos, o jitter deve ser pequeno. A filtragem de carimbo de data e hora às vezes é necessária para satisfazer os requisitos de CDD, pois usar apenas o tempo de interrupção do SoC para definir os carimbos de data e hora causa jitter muito alto, e usar apenas o tempo do chip do sensor para definir os carimbos de data e hora pode causar dessincronização do relógio elapsedRealtimeNano , como o desvios do relógio do sensor.
dados e campos sobrepostos: Os valores medidos pelo sensor. O significado e as unidades desses campos são específicos para cada tipo de sensor. Consultesensores.h e a definição dos diferentes tipos de sensores para obter uma descrição dos campos de dados. Para alguns sensores, a precisão das leituras também é informada como parte dos dados, através de um campo status . Este campo é canalizado apenas para os tipos de sensores selecionados, aparecendo na camada SDK como um valor de precisão. Para esses sensores, o fato de que o campo de status deve ser definido é mencionado na definição do tipo de sensor .
Metadados liberam eventos completos
Os eventos de metadados têm o mesmo tipo que os eventos normais de sensor: sensors_event_meta_data_t = sensors_event_t . Eles são retornados junto com outros eventos do sensor através de poll. Eles possuem os seguintes campos:
versão: deve ser META_DATA_VERSION
tipo: deve ser SENSOR_TYPE_META_DATA
sensor, reservado e carimbo de data/hora : deve ser 0
meta_data.what: Contém o tipo de metadados para este evento. Atualmente existe um único tipo de metadados válido: META_DATA_FLUSH_COMPLETE .
Os eventos META_DATA_FLUSH_COMPLETE representam a conclusão da liberação de um sensor FIFO. Quando meta_data.what=META_DATA_FLUSH_COMPLETE , meta_data.sensor deve ser definido como o identificador do sensor que foi liberado. Eles são gerados quando e somente quando flush é chamada em um sensor. Consulte a seção sobre a função de descarga para obter mais informações.