Датчики HAL 1.0

Интерфейс Sensors HAL, объявленный в Sensor.h , представляет собой интерфейс между платформой Android и аппаратным программным обеспечением. Реализация HAL должна определять каждую функцию, объявленную в Sensor.h. Основные функции:

  • get_sensors_list — возвращает список всех датчиков.
  • activate - Запускает или останавливает датчик.
  • batch — устанавливает параметры датчика, такие как частота выборки и максимальная задержка отчета.
  • setDelay — используется только в HAL версии 1.0. Устанавливает частоту дискретизации для данного датчика.
  • flush — сбрасывает FIFO указанного датчика и сообщает о завершении сброса, когда это делается.
  • poll - Возвращает доступные события сенсора.

Реализация должна быть потокобезопасной и позволять вызывать эти функции из разных потоков.

Интерфейс также определяет несколько типов, используемых этими функциями. Основные типы:

  • sensors_module_t
  • sensors_poll_device_t
  • sensor_t
  • sensors_event_t

В дополнение к разделам ниже см. Sensors.h для получения дополнительной информации об этих типах.

get_sensors_list (список)

int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t
  const** list);

Предоставляет список датчиков, реализованных HAL. См. Sensor_t для получения подробной информации о том, как определяются датчики.

Порядок, в котором датчики отображаются в списке, соответствует порядку, в котором датчики будут сообщаться приложениям. Обычно первыми появляются базовые датчики, за которыми следуют составные датчики.

Если несколько датчиков имеют одинаковый тип датчика и свойство пробуждения, первый в списке называется датчиком «по умолчанию». Это тот, который возвращает getDefaultSensor(int sensorType, bool wakeUp) .

Эта функция возвращает количество датчиков в списке.

активировать (датчик, правда/ложь)

int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int
  enabled);

Активирует или деактивирует датчик.

sensor_handle — дескриптор сенсора для активации/деактивации. Дескриптор датчика определяется полем handle его структуры sensor_t .

enabled устанавливается на 1, чтобы включить или на 0, чтобы отключить датчик.

Однократные датчики деактивируются автоматически при получении события, и они все равно должны принять деактивацию через вызов для activate(..., enabled=0) .

Датчики без пробуждения никогда не препятствуют переходу SoC в режим ожидания; то есть HAL не должен удерживать частичную блокировку пробуждения от имени приложений.

Датчики пробуждения при непрерывной доставке событий могут предотвратить переход SoC в режим приостановки, но если нет необходимости в доставке событий, необходимо снять частичную блокировку пробуждения.

Если enabled равно 1 и датчик уже активирован, эта функция неактивна и работает успешно.

Если enabled равно 0, а датчик уже деактивирован, эта функция неактивна и выполняется успешно.

Эта функция возвращает 0 в случае успеха и отрицательный номер ошибки в противном случае.

пакет (датчик, флаги, период выборки, максимальная задержка отчета)

int (*batch)(
     struct sensors_poll_device_1* dev,
     int sensor_handle,
     int flags,
     int64_t sampling_period_ns,
     int64_t max_report_latency_ns);

Задает параметры датчика, включая частоту выборки и максимальную задержку отчета . Эту функцию можно вызывать, когда датчик активирован, и в этом случае она не должна приводить к потере каких-либо измерений датчика: переход от одной частоты дискретизации к другой не может привести к потере событий, равно как и переход от высокой максимальной задержки отчета к низкой. максимальная задержка отчета.

sensor_handle — это дескриптор датчика, который необходимо настроить.

flags в настоящее время не используется.

sampling_period_ns — это период выборки, с которым датчик должен работать, в наносекундах. Дополнительные сведения см. в разделе sample_period_ns .

max_report_latency_ns — это максимальное время, на которое события могут быть задержаны, прежде чем они будут переданы через HAL, в наносекундах. Дополнительные сведения см. в параграфе max_report_latency_ns .

Эта функция возвращает 0 в случае успеха и отрицательный номер ошибки в противном случае.

setDelay (датчик, период выборки)

int (*setDelay)(
     struct sensors_poll_device_t *dev,
     int sensor_handle,
     int64_t sampling_period_ns);

После HAL версии 1.0 эта функция устарела и никогда не вызывается. Вместо этого вызывается batch функция для установки параметра sampling_period_ns .

В HAL версии 1.0 setDelay использовался вместо пакетного для установки sample_period_ns .

промывка (датчик)

int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

Добавить событие завершения сброса в конец аппаратного FIFO для указанного датчика и сбросить FIFO; эти события доставляются как обычно (т. е. как если бы максимальная задержка сообщения истекла) и удаляются из FIFO.

Сброс происходит асинхронно (т.е. эта функция должна возвращаться немедленно). Если реализация использует один FIFO для нескольких датчиков, этот FIFO сбрасывается, и событие завершения сброса добавляется только для указанного датчика.

Если указанный датчик не имеет FIFO (буферизация невозможна) или если FIFO был пуст во время вызова, flush все равно должен завершиться успешно и отправить событие завершения сброса для этого датчика. Это относится ко всем датчикам, кроме однократных датчиков.

При flush , даже если событие сброса уже находится в FIFO для этого датчика, необходимо создать дополнительное событие и добавить его в конец FIFO, а FIFO необходимо сбросить. Количество вызовов flush должно быть равно количеству созданных событий завершения сброса.

flush не применяется к однократным датчикам; если sensor_handle относится к однократному датчику, функция flush должна возвращать -EINVAL и не генерировать никаких событий полного сброса метаданных.

Эта функция возвращает 0 в случае успеха, -EINVAL , если указанный датчик является одноразовым датчиком или не был включен, и отрицательный номер ошибки в противном случае.

опрос()

int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
  count);

Возвращает массив данных датчика, заполняя аргумент data . Эта функция должна быть заблокирована до тех пор, пока не станут доступны события. Он вернет количество событий, прочитанных в случае успеха, или отрицательный номер ошибки в случае ошибки.

Количество событий, возвращаемых в data , должно быть меньше или равно аргументу count . Эта функция никогда не должна возвращать 0 (нет события).

Последовательность звонков

При загрузке устройства get_sensors_list .

Когда датчик активируется, batch функция будет вызываться с запрошенными параметрами, после чего следует activate(..., enable=1) .

Обратите внимание, что в HAL версии 1_0 порядок был обратным: сначала вызывалась activate , а затем set_delay .

Когда запрошенные характеристики датчика изменяются во время его активации, вызывается batch функция.

flush можно вызвать в любое время, даже на неактивированных датчиках (в этом случае он должен возвращать -EINVAL )

Когда датчик деактивируется, будет вызвана activate(..., enable=0) .

Параллельно с этими вызовами функция poll будет неоднократно вызываться для запроса данных. poll может быть вызван, даже если никакие датчики не активированы.

датчики_модуль_t

sensors_module_t — это тип, используемый для создания аппаратного модуля Android для датчиков. Реализация HAL должна определить объект HAL_MODULE_INFO_SYM этого типа для предоставления функции get_sensors_list . Для получения дополнительной информации см. определение sensors_module_t в Sensor.h и определение hw_module_t .

Sensors_poll_device_t/sensors_poll_device_1_t

sensors_poll_device_1_t содержит остальные методы, определенные выше: activate , batch , flush и poll . Его common поле (типа hw_device_t ) определяет номер версии HAL.

датчик_t

sensor_t представляет датчик Android . Вот некоторые из его важных полей:

name: видимая пользователю строка, представляющая датчик. Эта строка часто содержит название детали базового датчика, тип датчика и информацию о том, является ли он датчиком пробуждения. Например, «Акселерометр LIS2HH12», «Некалиброванный гироскоп MAX21000», «Барометр пробуждения BMP280», «Игровой вектор вращения MPU6515».

handle: Целое число, используемое для ссылки на датчик при его регистрации или генерации событий от него.

тип: тип датчика. См. объяснение типа датчика в разделе Что такое датчики Android? для получения более подробной информации и см. Типы датчиков для официальных типов датчиков. Для неофициальных типов датчиков type должен начинаться с SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType: тип датчика в виде строки. Если датчик имеет официальный тип, установите SENSOR_STRING_TYPE_* . Если датчик имеет тип, специфичный для производителя, stringType должен начинаться с обратного доменного имени производителя. Например, датчик (скажем, детектор единорога), определенный командой Cool-product в Fictional-Company, может использовать stringType=”com.fictional_company.cool_product.unicorn_detector” . stringType используется для уникальной идентификации неофициальных типов датчиков. См. Sensor.h для получения дополнительной информации о типах и типах строк.

requiredPermission: строка, представляющая разрешение, которым должны обладать приложения, чтобы видеть датчик, регистрироваться на нем и получать его данные. Пустая строка означает, что приложениям не требуется никаких разрешений для доступа к этому датчику. Некоторые типы датчиков, такие как монитор сердечного ритма , имеют обязательное requiredPermission . Все датчики, предоставляющие конфиденциальную информацию о пользователе (например, частоту сердечных сокращений), должны быть защищены разрешением.

flags: флаги для этого датчика, определяющие режим отчета датчика и то, является ли датчик датчиком пробуждения или нет. Например, однократный датчик пробуждения будет иметь flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . Биты флага, которые не используются в текущей версии HAL, необходимо оставить равными 0.

maxRange: максимальное значение, которое датчик может сообщить, в тех же единицах, что и сообщаемые значения. Датчик должен иметь возможность сообщать значения без насыщения в пределах [-maxRange; maxRange] . Обратите внимание, что это означает, что общий диапазон датчика в общем смысле равен 2*maxRange . Когда датчик сообщает значения по нескольким осям, диапазон применяется к каждой оси. Например, акселерометр «+/- 2g» сообщит maxRange = 2*9.81 = 2g .

разрешение: Наименьшая разница в значении, которую может измерить датчик. Обычно вычисляется на основе maxRange и количества битов в измерении.

мощность: стоимость электроэнергии включения датчика в миллиамперах. Это почти всегда больше, чем потребляемая мощность, указанная в техническом описании базового датчика. Дополнительные сведения см. в разделе Базовые датчики != физические датчики, а в разделе Процесс измерения мощности — подробные сведения о том, как измерить энергопотребление датчика. Если энергопотребление датчика зависит от того, движется ли устройство, энергопотребление во время движения указывается в поле power .

minDelay: для непрерывных датчиков период выборки в микросекундах, соответствующий максимальной скорости, поддерживаемой датчиком. Подробную информацию о том, как используется это значение, см. в разделе sample_period_ns . Имейте в виду, что minDelay выражается в микросекундах, а sampling_period_ns — в наносекундах. Если не указано иное, для датчиков при сдаче и в специальном режиме отчетности minDelay должен быть равен 0. Для однократных датчиков он должен быть равен -1.

maxDelay: для непрерывных датчиков и датчиков при изменении период выборки в микросекундах, соответствующий наименьшей скорости, поддерживаемой датчиком. Подробную информацию о том, как используется это значение, см. в разделе sample_period_ns . Имейте в виду, что maxDelay выражается в микросекундах, а sampling_period_ns — в наносекундах. Для специальных и одноразовых датчиков maxDelay должен быть равен 0.

fifoReservedEventCount: количество событий, зарезервированных для этого датчика в аппаратном FIFO. Если для этого датчика имеется выделенный FIFO, то fifoReservedEventCount — это размер этого выделенного FIFO. Если FIFO используется совместно с другими датчиками, fifoReservedEventCount — это размер части FIFO, зарезервированной для этого датчика. В большинстве систем с общим FIFO и в системах без аппаратного FIFO это значение равно 0.

fifoMaxEventCount: максимальное количество событий, которые могут быть сохранены в FIFO для этого датчика. Это значение всегда больше или равно fifoReservedEventCount . Это значение используется для оценки того, как быстро FIFO заполнится при регистрации на датчике с определенной скоростью, при условии, что никакие другие датчики не активированы. В системах, в которых нет аппаратного FIFO, fifoMaxEventCount равен 0. Дополнительные сведения см. в разделе Пакетная обработка.

Для датчиков с официальным типом некоторые поля перезаписываются фреймворком. Например, датчики акселерометра принудительно имеют режим непрерывной отчетности, а мониторы сердечного ритма принудительно защищены разрешением SENSOR_PERMISSION_BODY_SENSORS .

датчики_event_t

События датчиков, генерируемые датчиками Android и сообщаемые через функцию опроса , относятся к type sensors_event_t . Вот несколько важных полей sensors_event_t :

версия: должен быть sizeof(struct sensors_event_t)

датчик: дескриптор датчика, сгенерировавшего событие, как определено в sensor_t.handle .

type: тип датчика, сгенерировавшего событие, как определено в sensor_t.type .

timestamp: временная метка события в наносекундах. Это время, когда произошло событие (был сделан шаг или было выполнено измерение с помощью акселерометра), а не время сообщения о событии. timestamp должна быть синхронизирована с часами elapsedRealtimeNano , а в случае непрерывных датчиков джиттер должен быть небольшим. Фильтрация временных меток иногда необходима для удовлетворения требований CDD, поскольку использование только времени прерывания SoC для установки временных меток вызывает слишком высокий джиттер, а использование только времени сенсорного чипа для установки временных меток может привести к elapsedRealtimeNano часов RealtimeNano, поскольку часы датчика дрейфуют.

данные и перекрывающиеся поля: значения, измеренные датчиком. Значение и единицы измерения этих полей зависят от каждого типа датчика. См. Sensors.h и определение различных типов датчиков для описания полей данных. Для некоторых датчиков точность показаний также сообщается как часть данных через поле status . Это поле передается только для выбранных типов датчиков и отображается на уровне SDK как значение точности. Для этих датчиков тот факт, что поле состояния должно быть установлено, упоминается в определении их типа датчика .

События полного сброса метаданных

События метаданных имеют тот же тип, что и обычные события датчика: sensors_event_meta_data_t = sensors_event_t . Они возвращаются вместе с другими событиями датчика посредством опроса. Они обладают следующими полями:

версия: должна быть META_DATA_VERSION

тип: Должен быть SENSOR_TYPE_META_DATA

датчик, зарезервировано и отметка времени : должно быть 0

meta_data.what: содержит тип метаданных для этого события. В настоящее время существует единственный допустимый тип метаданных: META_DATA_FLUSH_COMPLETE .

События META_DATA_FLUSH_COMPLETE представляют собой завершение сброса FIFO датчика. Когда meta_data.what=META_DATA_FLUSH_COMPLETE , meta_data.sensor должен быть установлен на дескриптор датчика, который был сброшен. Они генерируются тогда и только тогда, когда для датчика вызывается flush . Дополнительную информацию см. в разделе о функции промывки .