Начиная с 27 марта 2025 г. мы рекомендуем использовать android-latest-release вместо aosp-main для создания и участия в AOSP. Дополнительные сведения см. в разделе Изменения в AOSP .

Эта страница переведена с помощью Cloud Translation API.

Датчики HAL 1.0

Интерфейс 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 .

sensors_poll_device_t / sensors_poll_device_1_t

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

сенсор_т

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

Имя: Видимая пользователем строка, представляющая датчик. Эта строка часто содержит название компонента датчика, его тип и информацию о том, является ли он датчиком пробуждения. Например, «LIS2HH12 Accelerometer», «MAX21000 Uncalibrated Gyroscope», «BMP280 Wake-up Barometer», «MPU6515 Game Rotation Vector».

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

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

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

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

Флаги: Флаги для этого датчика, определяющие режим отчётности датчика и то, является ли датчик пробуждающим. Например, для датчика с однократным пробуждением будут заданы 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: Для непрерывных датчиков период выборки в микросекундах, соответствующий максимальной частоте, поддерживаемой датчиком. Подробнее об использовании этого значения см. в параметре sampling_period_ns . Обратите внимание, что minDelay выражается в микросекундах, а sampling_period_ns — в наносекундах. Для датчиков, работающих по смене режима и в режиме специального отчёта, если не указано иное, 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 .

датчики_события_т

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

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

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

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

Отметка времени: Отметка времени события в наносекундах. Это время, когда произошло событие (был сделан шаг или измерен акселерометр), а не время регистрации события. 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 для датчика. Подробнее см. в разделе о функции flush .