傳感器 HAL 1.0

Sensors HAL 接口在sensors.h中聲明,表示 Android框架和特定於硬件的軟件之間的接口。 HAL 實現必須定義在 sensors.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是要激活/停用的傳感器的句柄。傳感器的句柄由其sensor_t結構的handle字段定義。

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 而不是 batch 來設置sampling_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_tsensors_module_t的定義和hw_module_t的定義。

sensor_poll_device_t / sensors_poll_device_1_t

sensors_poll_device_1_t包含上面定義的其餘方法: activatebatchflushpoll 。它的common字段(類型為hw_device_t )定義了 HAL 的版本號。

傳感器_t

sensor_t代表一個Android 傳感器。以下是它的一些重要領域:

名稱:代表傳感器的用戶可見字符串。該字符串通常包含底層傳感器的部件名稱、傳感器的類型以及是否為喚醒傳感器。例如“LIS2HH12 Accelerometer”、“MAX21000 Uncalibrated Gyroscope”、“BMP280 Wake-up Barometer”、“MPU6515 Game Rotation Vector”

句柄:用於在向傳感器註冊或從中生成事件時引用傳感器的整數。

類型:傳感器的類型。請參閱什麼是 Android 傳感器?有關更多詳細信息,請參閱官方傳感器類型的傳感器類型。對於非官方傳感器類型, type必須以SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType:傳感器的類型,字符串形式。當傳感器具有官方類型時,設置為SENSOR_STRING_TYPE_* 。當傳感器具有製造商特定類型時, stringType必須以製造商反向域名開頭。例如,由 Fictional-Company 的Cool-product團隊定義的傳感器(比如獨角獸檢測器)可以使用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字段中報告的功耗。

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 傳感器生成並通過poll函數報告的傳感器事件的type sensors_event_t 。以下是sensors_event_t的一些重要字段:

版本:必須是sizeof(struct sensors_event_t)

sensor:產生事件的傳感器的句柄,由sensor_t.handle定義。

type:產生事件的傳感器的傳感器類型,由sensor_t.type定義。

時間戳:事件的時間戳,以納秒為單位。這是事件發生的時間(採取了步驟,或進行了加速度計測量),而不是報告事件的時間。 timestamp必須與elapsedRealtimeNano時鐘同步,並且在連續傳感器的情況下,jitter 必須很小。有時需要時間戳過濾來滿足 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時才會生成它們。有關詳細信息,請參閱有關刷新功能的部分。