A interface HAL de sensores, declarada em sensors.h, representa a interface entre o framework do Android e o software específico do hardware. Uma implementação de HAL deve definir cada função declarados 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 a frequência de amostragem e a latência máxima de relatórios.setDelay
: usado apenas na versão 1.0 da HAL. Define a frequência de amostragem para um em um determinado sensor.flush
: limpa o FIFO do sensor especificado e informa um evento de limpeza concluído quando isso é feito.poll
: retorna os eventos de sensor disponíveis.
A implementação precisa ser segura para linhas de execução e permitir que essas funções sejam chamadas de linhas de execução diferentes.
A interface também define vários tipos usados por essas funções. O principal são:
sensors_module_t
sensors_poll_device_t
sensor_t
sensors_event_t
Além das seções abaixo, consulte sensors.h para 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 saber como os sensores são definidos.
A ordem em que os sensores aparecem na lista é a ordem em que eles serão informados aos aplicativos. Normalmente, os sensores básicos aparecem primeiro, seguidos pelos sensores compostos.
Se vários sensores compartilharem o mesmo tipo de sensor e propriedades de ativação, o primeiro
uma na lista é chamada de sensor "padrão". É aquele retornado pelo
getDefaultSensor(int sensorType, bool wakeUp)
:
Essa 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 a ser ativado/desativado. O sensor
o identificador é definido pelo campo handle
da estrutura sensor_t dele.
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 precisam aceitar a desativação por uma chamada para activate(...,
enabled=0)
.
Os sensores sem ativação nunca impedem que o SoC entre no modo de suspensão. que é que a HAL não deve manter um wake lock parcial em nome dos aplicativos.
Os sensores de ativação, ao fornecer eventos continuamente, podem impedir que o SoC entrar em modo de suspensão, mas se nenhum evento precisar ser fornecido, a parte o wake lock deve ser liberado.
Se enabled
for 1 e o sensor já estiver ativado, esta função será um ambiente autônomo.
e funciona.
Se enabled
for 0 e o sensor já estiver desativado, essa função não vai fazer nada
e vai ser bem-sucedida.
Essa função retorna 0 em caso de sucesso e um número de erro negativo, caso contrário.
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);
Define os parâmetros de um sensor, incluindo frequência de amostragem e máximo de relatórios latência. Essa função pode ser chamada enquanto o sensor está ativado. Nesse caso, ele não pode causar a perda de nenhuma medição do sensor: a transição de uma taxa de amostragem para outra não pode causar a perda de eventos, nem a transição de uma latência máxima alta para uma baixa.
sensor_handle
é a alça 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
precisa ser executado, em nanossegundos. Consulte sample_period_ns para
mais detalhes.
max_report_latency_ns
é o tempo máximo em que os eventos podem ser
atrasados antes de serem informados pelo HAL, em nanossegundos. Consulte o parágrafo max_report_latency_ns
para mais detalhes.
Essa 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 da HAL, essa função foi descontinuada 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);
Adiciona um evento Clean Complete ao final do FIFO do hardware para o sensor especificado e limpa o FIFO. esses eventos sejam entregues como de costume (ou seja, como se a latência máxima dos relatórios expirou) e removido do FIFO.
A limpeza ocorre de forma assíncrona (ou seja, esta função precisa retornar imediatamente). Se a implementação usar um único FIFO para vários sensores, esse FIFO será limpa e o evento de limpeza completa é adicionado apenas para o sensor especificado.
Se o sensor especificado não tiver FIFO (nenhum buffer possível) ou se o FIFO
estiver vazio no momento da chamada, flush
ainda terá sucesso e
enviará um evento de limpeza completa para esse sensor. Isso se aplica a todos os sensores,
exceto os de disparo único.
Quando flush
é chamado, mesmo que um evento de limpeza já esteja no
FIFO para esse sensor, um outro precisa ser criado e adicionado ao final
do FIFO e o FIFO deve ser liberado. O número de chamadas flush
precisa ser igual ao número de eventos de limpeza completa criados.
flush
não se aplica a sensores one-shot.
Se sensor_handle
se referir a um sensor one-shot,
flush
precisará retornar -EINVAL
e não gerar nenhum
evento de limpeza de metadados completo.
Essa função retorna 0 em caso de sucesso, -EINVAL
se o sensor especificado for
único ou não estiver ativado e um número de erro negativo, caso contrário.
poll()
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
. Essa função
precisa ser bloqueada até que os eventos estejam disponíveis. Ela 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 em data
precisa ser menor ou igual ao
argumento count
. Essa função nunca vai retornar 0 (nenhum evento).
Sequência de chamadas
Quando o dispositivo é inicializado, get_sensors_list
é chamado.
Quando um sensor é ativado, a função batch
é chamada com o
parâmetros solicitados, seguidos por activate(..., enable=1)
.
Na versão 1_0 do HAL, a ordem era oposta: activate
era chamado
primeiro, seguido por set_delay
.
Quando as características solicitadas de um sensor mudam enquanto ele está
ativada, a função batch
é chamada.
O flush
pode ser chamado a qualquer momento, mesmo em sensores não ativados. Nesse caso,
ele precisa retornar -EINVAL
)
Quando um sensor é desativado, activate(..., enable=0)
é chamado.
Em paralelo a essas chamadas, a função poll
será chamada repetidamente para
solicitar dados. poll
pode ser chamado mesmo quando nenhum sensor está ativado.
sensores_módulo_t
sensors_module_t
é o tipo usado para criar o hardware do Android.
para os sensores. A implementação da HAL deve definir um objeto
HAL_MODULE_INFO_SYM
desse tipo para expor a função get_sensors_list. Consulte a
definição de sensors_module_t
em sensors.h e a definição de hw_module_t
para 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
. O campo common
(do tipo hw_device_t)
define o número da versão do HAL.
sensor_t
sensor_t
representa um sensor
Android. Veja alguns dos campos importantes:
name: uma string visível para o usuário que representa o sensor. Essa string geralmente contém o nome da parte do sensor subjacente, o tipo do sensor e se ele é um sensor de ativação. Por exemplo, "Acelerômetro LIS2HH12", "Giroscópio MAX21000 não calibrado", "Barômetro de ativação BMP280", "Vetor de rotação do jogo MPU6515"
identificador:o número inteiro usado para se referir ao sensor ao fazer o registro ou gerar eventos com base nele.
type: o tipo do sensor. Confira a explicação do sensor
Digite O que são os sensores do Android? para saber mais e consulte Tipos de sensores para conferir os tipos oficiais. Para
tipos de sensores não oficiais, o type
precisa 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
precisa
começar com o nome de domínio reverso do fabricante. Por exemplo, um sensor (digamos, um
detector de unicórnio) definido pela equipe de Produtos legais em
Empresa fictícia pode ser usada
stringType=”com.fictional_company.cool_product.unicorn_detector”
O stringType
é usado para identificar exclusivamente os tipos de sensores
não oficiais. Consulte sensors.h para saber mais sobre tipos e string
tipos
requiredPermission: uma string que representa a permissão
que os apps precisam ter para acessar o sensor, se registrar nele e receber
os dados. Uma string vazia significa que os aplicativos não precisam de permissão para
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 dados
informações do usuário (como a frequência cardíaca) devem ser protegidas por um
permissão.
flags: flags para esse sensor, que definem o modo de relatório do sensor e se
ele é um sensor de ativação ou não. Por exemplo, um sensor de ativação one-shot
terá flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP
. Os pedaços de
as sinalizações que não são usadas na versão atual da HAL precisam ficar iguais a 0.
maxRange: o valor máximo que o sensor pode informar, na mesma unidade dos
valores informados. O sensor precisa ser capaz de informar valores sem saturar
dentro de [-maxRange; maxRange]
. Isso significa que o alcance total do
sensor no sentido genérico é 2*maxRange
. Quando o sensor informa valores em
vários eixos, o intervalo se aplica a cada eixo. Por exemplo, "+/- 2g"
o acelerômetro vai informar maxRange = 2*9.81 = 2g
.
resolução: a menor diferença de valor que o sensor pode medir.
Geralmente, é calculado com base em maxRange
e no número de bits na medição.
power:o custo de energia para ativar o sensor, em miliAmps.
Isso quase sempre é maior que o consumo de energia informado na
folha de dados do sensor. Consulte Sensores básicos != físicos
sensores para mais detalhes e consulte Medição de energia
para detalhes sobre como medir o consumo de energia de um sensor.
Se o consumo de energia do sensor depender de se o dispositivo está em movimento, o
consumo de energia em movimento será o informado no campo
power
.
minDelay: para sensores contínuos, o período de amostragem, em
microssegundos, corresponde à taxa mais rápida aceita pelo sensor. Consulte sample_period_ns para
detalhes sobre como esse valor é usado. minDelay
é
expresso em microssegundos, enquanto sampling_period_ns
está em
nanossegundos. Para sensores durante a mudança e no modo de relatório especial, a menos que
especificado de outra forma, minDelay
precisa ser 0. Para sensores únicos, ele
precisa ser -1.
maxDelay: para sensores contínuos e de mudança, o período de amostragem, em microssegundos, corresponde à taxa mais lenta com suporte do sensor. Consulte sampling_period_ns para
saber como esse valor é usado. maxDelay
é
expresso em microssegundos, enquanto sampling_period_ns
está em
nanossegundos. Para sensores especiais e de um disparo, maxDelay
precisa ser
0.
fifoScheduledEventCount: o número de eventos reservados para esse sensor no
FIFO de hardware. Se houver um FIFO dedicado para esse sensor,
fifoReservedEventCount
é 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 nos
sistemas que não têm um FIFO de hardware, esse valor é 0.
fifoMaxEventCount: o número máximo de eventos que podem
ser armazenados nos FIFOs deste sensor. Esse valor é sempre maior ou igual a
fifoReservedEventCount
. Esse valor é usado para estimar a
rapidez com que a FIFO vai ficar cheia ao se registrar no sensor a uma taxa
específica, supondo que nenhum outro sensor seja ativado. Em sistemas que não têm
FIFO do hardware, fifoMaxEventCount
é 0. Consulte Como fazer o agrupamento para mais detalhes.
Para sensores com um tipo oficial, alguns campos são substituídos
pelo framework. Por exemplo, sensores de acelerômetro.
precisam usar um modo contínuo de geração de relatórios, e os monitores de frequência cardíaca
precisam ser protegidas pela política de SENSOR_PERMISSION_BODY_SENSORS
permissão.
sensores_event_t
Os eventos gerados pelos sensores do Android e informados pela função poll são de type sensors_event_t
. Confira alguns
campos importantes de sensors_event_t
:
version:precisa ser sizeof(struct sensors_event_t)
.
sensor: o identificador do sensor que gerou o evento, conforme definido por
sensor_t.handle
.
type: o tipo do sensor que gerou o evento, conforme definido por
sensor_t.type
.
timestamp: o carimbo de data/hora do evento em nanossegundos. Esse é o momento
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 informado. O timestamp
precisa estar sincronizado com o
relógio elapsedRealtimeNano
e, no caso de sensores contínuos, a instabilidade
precisa ser pequeno. Às vezes, a filtragem de carimbo de data/hora é necessária para atender ao CDD.
como usar apenas o horário de interrupção de SoC para definir os carimbos de data/hora
causa instabilidade muito alta e usa apenas o tempo do chip do sensor para definir o
os carimbos de data/hora podem causar dessincronização do
Relógio elapsedRealtimeNano
, à medida que o relógio do sensor muda.
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. Consulte sensors.h e a definição dos diferentes tipos de sensores para uma descrição dos
campos de dados. Para alguns sensores, a precisão das leituras também é informada
como parte dos dados, por um campo status
. Esse campo é transmitido apenas para esses tipos de sensores selecionados, aparecendo na camada do SDK como um valor de precisão. Para esses sensores, o fato de que o campo de status deve ser definido
é mencionado no tipo de sensor deles.
definição.
Eventos de limpeza de metadados concluída
Os eventos de metadados são do mesmo tipo que os eventos normais do sensor:
sensors_event_meta_data_t = sensors_event_t
: Eles são retornados com
outros eventos de sensor por meio de pesquisa. Elas têm os seguintes campos:
version:precisa ser META_DATA_VERSION
.
type: precisa ser SENSOR_TYPE_META_DATA
sensor, reservado e carimbo de data/hora: precisa ser 0.
meta_data.what: contém o tipo de metadados desse evento. No momento, há um
único tipo de metadados válido: META_DATA_FLUSH_COMPLETE
.
Os eventos META_DATA_FLUSH_COMPLETE
representam a conclusão do flush de um
FIFO do sensor. Quando meta_data.what=META_DATA_FLUSH_COMPLETE
, meta_data.sensor
precisa ser definido como o identificador do sensor que foi limpo. Elas são
geradas quando e somente quando flush
é chamado em um sensor. Consulte a seção sobre
a função flush para mais informações.