HAL 1.0 de sensores

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 do HAL precisa definir cada função declarada em sensors.h. As funções principais 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 do HAL. Define a frequência de amostragem para um determinado sensor.
• flush: limpa o FIFO do sensor especificado e informa um evento de limpeza concluído quando isso é feito.
• 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 pelo HAL. Consulte sensor_t para mais detalhes sobre como os sensores são definidos.

Os sensores aparecem na lista na ordem em que o os sensores serão informados aos aplicativos. Normalmente, os sensores básicos aparecem primeiro, seguidos pelos sensores compostos.

Se vários sensores compartilharem o mesmo tipo e a mesma propriedade de ativação, o primeiro na lista será 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 é o identificador do sensor a ser ativado/desativado. O identificador de um sensor é definido pelo campo handle da estrutura sensor_t.

enabled é definido como 1 para ativar ou 0 para desativar o sensor.

Os sensores únicos são desativados automaticamente ao receber um evento e ainda precisam aceitar a desativação por uma chamada para activate(..., enabled=0).

Sensores que não ativam nunca impedem que o SoC entre no modo de suspensão. Ou seja, o HAL não pode manter um wake lock parcial em nome de 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 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. 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 é usado no momento.

sampling_period_ns é o período de amostragem em que o sensor deve ser executada em nanossegundos. Consulte sampling_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. 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, sampling period)

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, 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 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. Ele vai 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 os 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 estão mudando enquanto ele está ativado, a função batch é chamada.

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.

Paralelamente a essas chamadas, a função poll será chamada repetidamente para solicitar dados. O poll pode ser chamado mesmo quando nenhum sensor é ativado.

sensores_módulo_t

sensors_module_t é o tipo usado para criar o módulo de 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.

sensors_poll_device_t / sensors_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 um sensor Android. Estes são 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"

handle: o número inteiro usado para se referir ao sensor ao se registrar nele ou gerar eventos dele.

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, 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 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. necessários para os aplicativos verem, registrarem e receberem o sensor os dados. Uma string vazia significa que os aplicativos não precisam de nenhuma permissão 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 informações sensíveis do usuário (como a frequência cardíaca) precisam ser protegidos por uma 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 único 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 dentro de [-maxRange; maxRange]. Isso significa que o intervalo total 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, um acelerômetro "+/- 2g" 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 miliampéres. 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, 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 sampling_period_ns para saber 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.

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 é 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 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 um FIFO de hardware, fifoMaxEventCount é 0. Consulte Agrupamento em lotes 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 de sensor gerados por 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

carimbo de data/hora: o carimbo de data/hora do evento em nanossegundos. É o horário em que o evento ocorreu (uma etapa foi realizada ou uma medição do acelerômetro foi feita), não o horário 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 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 têm o mesmo tipo que os eventos de sensor normais: sensors_event_meta_data_t = sensors_event_t. Eles são retornados com outros eventos de sensor por meio de pesquisa. Eles 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 para este 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 precisa ser definido como o identificador do sensor que foi limpo. São gerados somente quando flush é chamado em um sensor. Consulte a seção sobre a função clean para mais informações.