HAL 1.0 de sensores

A interface HAL de sensores, declarada em sensors.h, representa a interface entre o framework do Android e o softwares específicos de hardware. Uma implementação de HAL precisa 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 frequência de amostragem e latência 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 uma limpeza concluída. quando isso é concluído.
  • poll: retorna eventos de sensor disponíveis.

A implementação precisa ser thread-safe e permitir que essas funções sejam chamadas em 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 pela HAL. Consulte sensor_t para mais detalhes sobre como os sensores são definidos.

Os sensores aparecem na lista em ordem de exibição os sensores serão informados aos aplicativos. Normalmente, os sensores da base aparecem primeiro, seguido pelos sensores compostos.

Se vários sensores compartilharem o mesmo tipo de sensor e propriedades de ativação, o primeiro um na lista é chamado 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, esta função será um ambiente autônomo. e funciona.

Essa função retorna 0 em caso de sucesso e um número de erro negativo, caso contrário.

lote(sensor, sinalizações, 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 máximo de relatórios latência. Esta função pode ser chamada enquanto o sensor está ativado, caso em que ele não deve fazer com que as medições dos sensores sejam perdidas: fazer uma transição de uma taxa de amostragem para outra não podem causar perdas de eventos, nem podem transição de uma latência máxima de relatório alta para um relatório máximo baixo latência de rede.

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 deve ser executada 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 relatados pela HAL, em nanossegundos. Confira max_report_reporting_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 da HAL, foi usado setDelay em vez de lote para definir sample_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 (sem armazenamento em buffer possível) ou se o FIFO, estava vazio no momento da chamada, flush ainda deve funcionar e enviar um evento de limpeza completa para esse sensor. Isso se aplica a todos os sensores do que os sensores one-shot.

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 flush chamadas devem ser iguais ao número de eventos de limpeza completa criados.

flush não se aplica ao modo one-shot sensores se sensor_handle se referir a um sensor one-shot, flush precisa retornar -EINVAL e não gerar nenhum evento de metadados de limpeza completa.

Essa função retorna 0 em caso de sucesso, -EINVAL se o sensor especificado for um sensor único ou não foi ativado; caso contrário, será um número de erro negativo.

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. Essa função precisam ser bloqueados 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 a o argumento count. Essa 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 é chamada com o parâmetros solicitados, seguidos por activate(..., enable=1).

Na versão 1_0 da HAL, a ordem era o oposto: 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, o método 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 da HAL.

sensor_t

sensor_t representa uma sensor. Veja alguns dos campos importantes:

name:uma string visível ao usuário que representa o sensor. Muitas vezes, essa string contém o nome da peça do sensor subjacente, o tipo do sensor e seja um sensor de ativação. Por exemplo, “Acelerômetro LIS2HH12”, “MAX21000 Uncalibrated Gyroscope”, “BMP280 Wake-up Barometer”, “MPU6515 Game” de rotação".

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 o sensor tem um tipo oficial, definido como SENSOR_STRING_TYPE_*. Quando o sensor tiver um tipo específico do fabricante, stringType precisará comece com o nome de domínio inverso 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 sensores não oficiais. tipos Consulte sensors.h para saber mais sobre tipos e string tipos

requiredPermission:uma string que representa a permissão. necessários para os aplicativos verem, registrarem e receberem o sensor os dados. Uma string vazia significa que os aplicativos não precisam de permissão para para acessar esse sensor. Alguns tipos de sensor, como o monitor de frequência cardíaca, têm 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:sinalizações para esse sensor, que definem o modo de comunicação do sensor e se se o 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 que o os valores informados. O sensor precisa ser capaz de informar valores sem saturar em [-maxRange; maxRange]. Isso significa que o intervalo total sensor no sentido genérico é 2*maxRange. Quando o sensor informa valores acima de 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. Quase sempre, esse valor é maior do que o consumo de energia relatado nas sobre o sensor subjacente. 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 o dispositivo estar em movimento, o consumo de energia em movimento é o relatado no power .

minDelay: para sensores contínuos, o período de amostragem, em microssegundos, correspondendo à taxa mais rápida que o sensor aceita. Consulte sample_period_ns para detalhes sobre como esse valor é usado. Esteja ciente de que minDelay é expresso em microssegundos, enquanto sampling_period_ns está no 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. No caso dos sensores one-shot, deve ser -1.

maxDelay: para sensores contínuos e ao mudar, a amostragem período, em microssegundos, correspondendo à taxa mais lenta suporta. Consulte sample_period_ns para detalhes sobre como esse valor é usado. Esteja ciente de que maxDelay é expresso em microssegundos, enquanto sampling_period_ns está no nanossegundos. Para sensores especiais e de um disparo, maxDelay precisa ser 0.

fifoReserveEventCount: 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 é compartilhada com outros sensores, fifoReservedEventCount é o tamanho da parte do no FIFO reservado para esse sensor. Na maioria dos sistemas FIFO compartilhados, sistemas que não têm um FIFO de hardware, esse valor será 0.

fifoMaxEventCount: o número máximo de eventos que podem ser armazenados nos FIFOs deste sensor. Isto é sempre maior ou igual a fifoReservedEventCount: Esse valor é usado para estimar como rapidamente o FIFO ficará cheio ao se registrar no sensor em um horário uma vez que nenhum outro sensor está ativado. Em sistemas que não têm FIFO do hardware, fifoMaxEventCount é 0. Consulte Agrupamento em lotes para mais detalhes.

No caso de sensores com um tipo oficial, alguns dos campos são substituídos. pela estrutura. 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:a alça do sensor que gerou o evento, conforme definido pelo sensor_t.handle

type:o tipo do sensor que gerou o evento, conforme definido pelo 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 sensor. não é válido. Consulte sensors.h e a definição dos diferentes tipos de sensor para ver uma descrição dos campos de dados. Para alguns sensores, a precisão das leituras também é informada. como parte dos dados, usando um campo status. Este campo só é que são transmitidos para os tipos de sensor selecionados, aparecendo na camada do SDK o valor de acurácia. 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: Elas são retornadas junto com de outros eventos do sensor com uma enquete. Elas têm os seguintes campos:

version:precisa ser META_DATA_VERSION.

tipo: 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 da limpeza de um sensor FIFO. Quando meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor deve ser definido como a alça do sensor que foi descarregado. São gerados somente quando flush é chamado em um sensor. Consulte a seção sobre a função clean para mais informações.