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_t
中sensors_module_t的定義和hw_module_t
的定義。
sensor_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 傳感器。以下是它的一些重要領域:
名稱:代表傳感器的用戶可見字符串。該字符串通常包含底層傳感器的部件名稱、傳感器的類型以及是否為喚醒傳感器。例如“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
時才會生成它們。有關詳細信息,請參閱有關刷新功能的部分。