Интерфейс 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 для получения дополнительной информации об этих типах.
получить_список_датчиков(список)
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 — это период выборки, с которым должен работать датчик, в наносекундах. Подробнее см. sampling_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 для установки sampling_period_ns вместо batch использовался setDelay.
промывка(датчик)
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 может быть вызван даже тогда, когда ни один датчик не активирован.
датчики_модуль_т
sensors_module_t — тип, используемый для создания аппаратного модуля Android для датчиков. Реализация HAL должна определять объект HAL_MODULE_INFO_SYM этого типа для предоставления функции get_sensors_list . Для получения дополнительной информации см. определение sensors_module_t в sensors.h и определение hw_module_t .
датчики_опрос_устройства_t / датчики_опрос_устройства_1_t
sensors_poll_device_1_t содержит остальные методы, определенные выше: activate , batch , flush и poll . Его common поле (типа hw_device_t ) определяет номер версии HAL.
датчик_т
sensor_t представляет собой датчик Android . Вот некоторые из его важных полей:
name: Видимая пользователем строка, представляющая датчик. Эта строка часто содержит название детали базового датчика, тип датчика и является ли он датчиком пробуждения. Например, «LIS2HH12 Accelerometer», «MAX21000 Uncalibrated Gyroscope», «BMP280 Wake-up Barometer», «MPU6515 Game Rotation Vector»
handle: Целое число, используемое для ссылки на датчик при регистрации на нем или генерации событий с его помощью.
type: Тип датчика. Подробности см. в пояснении типа датчика в разделе Что такое датчики 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 используется для уникальной идентификации неофициальных типов датчиков. См. sensors.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: Стоимость мощности включения датчика в миллиамперах. Это почти всегда больше, чем потребляемая мощность, указанная в техническом описании базового датчика. См. Базовые датчики != физические датчики для получения более подробной информации и см. Процесс измерения мощности для получения подробной информации о том, как измерить потребляемую мощность датчика. Если потребляемая мощность датчика зависит от того, движется ли устройство, то потребляемая мощность во время движения — это та, которая указана в поле power .
minDelay: Для непрерывных датчиков период выборки в микросекундах, соответствующий самой высокой скорости, поддерживаемой датчиком. Подробную информацию об использовании этого значения см. в sampling_period_ns . Обратите внимание, что minDelay выражается в микросекундах, а sampling_period_ns — в наносекундах. Для датчиков в режиме on-change и специального режима отчетности, если не указано иное, minDelay должен быть равен 0. Для одноразовых датчиков он должен быть равен -1.
maxDelay: Для непрерывных и датчиков по изменению период выборки в микросекундах, соответствующий самой низкой скорости, поддерживаемой датчиком. Подробности использования этого значения см. в sampling_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 .
датчики_события_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 , так как часы датчика дрейфуют.
данные и перекрывающиеся поля: значения, измеренные датчиком. Значение и единицы этих полей специфичны для каждого типа датчика. См. 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 . Для получения дополнительной информации см. раздел о функции очистки .