A interface Sensors HAL, declarada em sensores.h , representa a interface entre o framework Android e o software específico do 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- Lava o FIFO do sensor especificado e relata um evento de lavagem completa quando isso é feito. -
poll- Retorna os eventos do 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, consulte sensores.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 relatados aos aplicativos. Normalmente, os sensores básicos aparecem primeiro, seguidos pelos sensores compostos.
Se vários sensores compartilham o mesmo tipo de sensor e propriedade de ativação, o primeiro da lista é chamado de sensor “padrão”. É o 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 é a alça do sensor para ativar/desativar. O handle de um sensor é definido pelo campo handle de sua estrutura sensor_t .
enabled é definido como 1 para habilitar ou 0 para desabilitar o sensor.
Os sensores one-shot se desativam automaticamente ao receber um evento, devendo ainda aceitar ser desativados através de uma chamada para activate(..., enabled=0) .
Os sensores que não despertam nunca impedem que o SoC entre no modo de suspensão; ou seja, o HAL não deve manter um wake-lock parcial em nome dos aplicativos.
Os sensores de despertar, 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 deve ser liberado.
Se enabled for 1 e o sensor já estiver ativado, esta função é no-op e é bem-sucedida.
Se enabled for 0 e o sensor já estiver desativado, esta função é no-op 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 no qual o sensor deve ser executado, 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. Veja o parágrafo max_report_latency_ns para 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, essa função é preterida e nunca é chamada. Em vez disso, a função batch é chamada para definir o parâmetro sampling_period_ns .
No HAL versão 1.0, 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 de liberação completa ao final do FIFO de hardware para o sensor especificado e libera o FIFO; esses eventos são entregues como de costume (ou seja: como se a latência máxima de relatório tivesse expirado) e removidos do FIFO.
A descarga 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 de liberação completa será adicionado apenas para o sensor especificado.
Se o sensor especificado não tiver FIFO (sem buffering possível), ou se o FIFO estava vazio no momento da chamada, a flush ainda deve ser bem-sucedida e enviar um evento de liberação completa para esse sensor. Isso se aplica a todos os sensores que não sejam sensores de disparo único.
Quando o flush é chamado, mesmo que um evento de flush já esteja no FIFO para aquele sensor, um evento adicional deve ser criado e adicionado ao final do FIFO, e o FIFO deve ser liberado. O número de chamadas de flush deve ser igual ao número de eventos de liberação completa criados.
flush não se aplica a sensores de disparo único ; se sensor_handle se referir a um sensor de disparo único, a liberação deve retornar flush e não gerar nenhum evento de metadados de -EINVAL completa.
Esta função retorna 0 em caso de sucesso, -EINVAL se o sensor especificado for um sensor de disparo único ou não foi 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 de data . Esta função deve bloquear 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 de count . Esta função nunca deve retornar 0 (sem 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, seguido de activate(..., enable=1) .
Observe que no HAL versão 1_0, a ordem era oposta: activate foi chamado primeiro, seguido por set_delay .
Quando as características solicitadas de um sensor estão mudando enquanto ele está ativado, a função de batch é chamada.
flush pode ser chamado a qualquer momento, mesmo em sensores não ativados (nesse caso deve retornar -EINVAL )
Quando um sensor for desativado, activate(..., enable=0) será chamado.
Em paralelo a essas chamadas, a função poll será chamada repetidamente para solicitar dados. poll pode ser chamado mesmo quando nenhum sensor estiver 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 de sensores_module_t em sensores.he a definição de sensors_module_t para hw_module_t 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:
name: uma string visível ao usuário que representa o sensor. Essa string geralmente contém o nome da parte do sensor subjacente, o tipo do sensor e se é um sensor de ativação. Por exemplo, “LIS2HH12 Acelerômetro”, “MAX21000 Giroscópio não calibrado”, “BMP280 Wake-up Barometer”, “MPU6515 Game Rotation Vector”
handle: O inteiro usado para se referir ao sensor ao se registrar nele ou gerar eventos a partir dele.
type: 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, o 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, defina como SENSOR_STRING_TYPE_* . Quando o sensor tem 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 pode usar stringType=”com.fictional_company.cool_product.unicorn_detector” . O stringType é usado para identificar exclusivamente tipos de sensores não oficiais. Consulte sensores.h para obter mais informações sobre tipos e tipos de string.
requiredPermission: 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 precisam de permissão para acessar esse sensor. Alguns tipos de sensores, como o monitor de frequência cardíaca, têm um requiredPermission obrigatório. Todos os sensores que fornecem informações confidenciais do usuário (como a 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 de disparo único terá flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . Os bits do sinalizador 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 relatar 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 informa valores em vários eixos, a faixa se aplica a cada eixo. Por exemplo, um acelerômetro “+/- 2g” reportará maxRange = 2*9.81 = 2g .
resolução: A menor diferença de valor que o sensor pode medir. Normalmente calculado com base em maxRange e o número de bits na medição.
power: O custo de energia para habilitar o sensor, em miliAmps. Isso é quase sempre mais do 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 de o dispositivo estar em movimento, o consumo de energia durante o movimento é o relatado no campo de power .
minDelay: Para sensores contínuos, o período de amostragem, em microssegundos, corresponde à taxa mais rápida que o sensor suporta. Consulte sampling_period_ns para obter detalhes sobre como esse valor é usado. Observe que minDelay é expresso em microssegundos enquanto sampling_period_ns é em nanossegundos. Para sensores de modo de relatório em mudança e especial, a menos que especificado de outra forma, minDelay deve ser 0. Para sensores de disparo único, deve ser -1.
maxDelay: Para sensores contínuos e em mudança, o período de amostragem, em microssegundos, corresponde à taxa mais lenta que o sensor suporta. Consulte sampling_period_ns para obter detalhes sobre como esse valor é usado. Observe que maxDelay é expresso em microssegundos enquanto sampling_period_ns é 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 desse 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 nas FIFOs para este sensor. Isso é sempre maior ou igual a fifoReservedEventCount . Este valor é usado para estimar a rapidez com que o FIFO ficará cheio ao se registrar no sensor em uma taxa específica, supondo que nenhum outro sensor seja ativado. Em sistemas que não possuem um FIFO de hardware, fifoMaxEventCount é 0. Consulte Batching para obter mais detalhes.
Para sensores com um tipo de sensor oficial, alguns dos 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 serem protegidos pela permissão SENSOR_PERMISSION_BODY_SENSORS .
sensores_event_t
Os eventos de sensor gerados por sensores Android e relatados por meio da função poll são do type sensors_event_t . Aqui estão alguns campos importantes de 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 do sensor que gerou o evento, conforme definido por sensor_t.type .
timestamp: O timestamp 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), não a hora em que o evento foi relatado. timestamp deve ser sincronizado com o relógio elapsedRealtimeNano e, no caso de sensores contínuos, o jitter deve ser pequeno. A filtragem de timestamp às vezes é necessária para satisfazer os requisitos do CDD, pois usar apenas o tempo de interrupção do SoC para definir os timestamps causa jitter muito alto e usar apenas o tempo do chip do sensor para definir os timestamps pode causar dessincronização do relógio elapsedRealtimeNano , pois o O relógio do sensor oscila.
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. Veja sensores.he a definição dos diferentes tipos de Sensor para uma descrição dos campos de dados. Para alguns sensores, a precisão das leituras também é informada como parte dos dados, por meio de um campo de status . Este campo só é canalizado para os tipos de sensor 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 .
Eventos completos de liberação de metadados
Os eventos de metadados têm o mesmo tipo que os eventos de sensor normais: sensors_event_meta_data_t = sensors_event_t . Eles são retornados junto com outros eventos do sensor por meio de pesquisa. Eles possuem os seguintes campos:
versão: deve ser META_DATA_VERSION
tipo: deve ser SENSOR_TYPE_META_DATA
sensor, reservado e timestamp : deve ser 0
meta_data.what: contém o tipo de metadados para este evento. Atualmente, há um único tipo de metadados válido: META_DATA_FLUSH_COMPLETE .
Os eventos META_DATA_FLUSH_COMPLETE representam a conclusão da descarga de um sensor FIFO. Quando meta_data.what=META_DATA_FLUSH_COMPLETE , meta_data.sensor deve ser definido para o identificador do sensor que foi liberado. Eles são gerados quando e somente quando a flush é chamada em um sensor. Consulte a seção sobre a função de descarga para obter mais informações.