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以獲取有關這些類型的更多資訊。
取得感測器列表(列表)
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
是感測器應運行的採樣週期(以奈秒為單位)。有關更多詳細信息,請參閱抽樣週期_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 而不是批量來設定抽樣週期_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
並且不產生任何flush完成元資料事件。
函數成功時傳回 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.h中的sensors_module_t
的定義和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 的版本號。
感測器_t
sensor_t
代表Android 感測器。以下是它的一些重要領域:
name:代表感測器的使用者可見字串。此字串通常包含底層感測器的零件名稱、感測器的類型以及是否為喚醒感測器。例如,“LIS2HH12加速度計”、“MAX21000未校準陀螺儀”、“BMP280喚醒氣壓計”、“MPU6515遊戲旋轉向量”
句柄:在註冊感測器或從中產生事件時用於引用感測器的整數。
類型:感測器的類型。請參閱什麼是 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:啟用感測器的功耗,以毫安培為單位。這幾乎總是高於底層感測器資料表中報告的功耗。有關更多詳細信息,請參閱基本感測器 != 物理感測器;有關如何測量感測器功耗的詳細信息,請參閱功率測量過程。如果感測器的功耗取決於裝置是否正在移動,則移動時的功耗就是power
欄位中報告的功耗。
minDelay:對於連續感測器,採樣週期(以微秒為單位),對應於感測器支援的最快速率。有關如何使用此值的詳細信息,請參閱抽樣週期_ns 。請注意, minDelay
以微秒為單位,而sampling_period_ns
以奈秒為單位。對於 on-change 和特殊報告模式感測器,除非另有說明, minDelay
必須為 0。對於一次性感測器,它必須為 -1。
maxDelay:對於連續和變化的感測器,採樣週期(以微秒為單位)對應於感測器支援的最慢速率。有關如何使用此值的詳細信息,請參閱抽樣週期_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_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
時才會產生它們。有關詳細信息,請參閱有關刷新功能的部分。