Интерфейс Sensors HAL, объявленный в Sensors.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 для установки выборки_периода_ns вместо пакета использовался 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
можно вызвать, даже если ни один датчик не активирован.
датчики_модуль_t
sensors_module_t
— это тип, используемый для создания аппаратного модуля Android для датчиков. Реализация HAL должна определить объект HAL_MODULE_INFO_SYM
этого типа, чтобы предоставить функцию get_sensors_list . Дополнительную информацию см. в определении sensors_module_t
в файле Sensor.h и в определении hw_module_t
.
датчики_poll_device_t / датчики_poll_device_1_t
sensors_poll_device_1_t
содержит остальные методы, определенные выше: activate
, batch
, flush
и poll
. Его common
поле (типа hw_device_t ) определяет номер версии HAL.
датчик_т
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
используется для уникальной идентификации неофициальных типов датчиков. Дополнительную информацию о типах и типах строк см. в файле Sensors.h.
requirePermission: строка, представляющая разрешение, которым должны обладать приложения, чтобы видеть датчик, регистрироваться на нем и получать его данные. Пустая строка означает, что приложениям не требуется никаких разрешений для доступа к этому датчику. Некоторые типы датчиков, такие как монитор сердечного ритма, имеют обязательное 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
часами RealtimeNano, а в случае непрерывных датчиков джиттер должен быть небольшим. Фильтрация временных меток иногда необходима для удовлетворения требований 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
. Дополнительную информацию см. в разделе о функции смыва .