感應器 HAL 1.0

sensors.h 中宣告的感應器 HAL 介面,代表 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(list)

int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t
  const** list);

提供 HAL 實作的感應器清單。如要進一步瞭解感應器的定義方式,請參閱 sensor_t

感應器在清單中顯示的順序 系統會將感應器回報給應用程式。通常會顯示基礎感應器 後面接著複合感應器

如果多個感應器共用相同的感應器類型和喚醒屬性,清單中的第一個感應器就會稱為「預設」感應器。也就是 getDefaultSensor(int sensorType, bool wakeUp)

這個函式會傳回清單中的感應器數量。

enable(sensor, true/false)

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,否則會傳回負錯誤數。

batch(sensor, flags, sampling period, maximum report latency)

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(sensor, 取樣期間)

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 並非批次,而是使用 setDelay。

flush(sensor)

int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

清除完成事件新增至指定感應器的硬體 FIFO 結尾,並清除 FIFO;這些事件會照常傳送 (也就是說,如果回報延遲時間上限已到期),並從 FIFO 中移除。

清除以非同步方式進行 (亦即,這個函式必須立即傳回)。 如果實作項目針對多個感應器使用單一 FIFO,該 FIFO 就會是 且只會為指定的感應器新增清除完成事件。

如果指定的感應器沒有 FIFO (無法進行緩衝處理),或者 FIFO 通話時沒有任何內容,flush 仍必須成功,且 傳送該感應器的清除完成事件。這適用於所有感應器 設計精良的

當呼叫 flush 時,即使清除事件已 你必須為該感應器建立 FIFO,並加入那邊 而且 FIFO 就必須排清flush數量 呼叫的數量必須等於已建立的清除完整事件數。

flush 不適用於一次性感應器;如果 sensor_handle 是指一次性感應器,flush 必須傳回 -EINVAL,且不得產生任何清除完成中繼資料事件。

這個函式會在成功時傳回 0;-EINVAL如果指定的感應器是 單樣本感應器或未啟用,若未啟用,則會顯示負錯誤數。

poll()

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.h 中的 sensors_module_t 定義,以及 hw_module_t 的定義 瞭解詳情

sensor_poll_device_t / Sensor_poll_device_1_t

sensors_poll_device_1_t 包含上述定義的其他方法: activatebatchflushpoll。其 common 欄位 (類型為 hw_device_t) 定義 HAL 的版本號碼

sensor_t

sensor_t 代表 Android 感應器。以下是部分重要欄位:

name:代表感應器的使用者可見字串。這個字串通常包含底層感應器的零件名稱、感應器類型,以及是否為喚醒感應器。例如「LIS2HH12 加速計」、「MAX21000 未校正陀螺儀」、「BMP280 喚醒氣壓計」、「MPU6515 遊戲旋轉向量」

handle:註冊感應器時,用於參照感應器的整數;或 並從中產生事件

type:感應器類型。如要進一步瞭解感應器類型,請參閱「Android 感應器是什麼?」一文中的說明,並參閱「感應器類型」一文,瞭解官方感應器類型。對於非官方感應器類型,type 必須以 SENSOR_TYPE_DEVICE_PRIVATE_BASE 開頭

stringType:感應器類型,以字串表示。如果感應器有官方類型,請設為 SENSOR_STRING_TYPE_*。時間 感應器具有製造商專屬類型,「stringType」必須 開頭是製造商反向網域名稱舉例來說,虛構公司 酷產品團隊定義的傳感器 (例如獨角獸偵測器) 可以使用 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:連續感應器的取樣期間, 微秒,對應感應器支援的最快速率。請參閱 sampling_period_ns: 詳述該值的使用方式請注意,minDelaysampling_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 權限進行保護。

sensors_event_t

由 Android 感應器產生,並透過 poll 函式回報的感應器事件,其類型為 type sensors_event_t。以下是一些 sensors_event_t 的重要欄位:

version:必須為 sizeof(struct sensors_event_t)

sensor:產生事件的感應器處理常式,定義如下: sensor_t.handle

type:產生事件的感應器類型,如 sensor_t.type 所定義。

timestamp:事件的時間戳記,以奈秒為單位。此時, 或加速計測量事件) 而不是回報事件的時間。timestamp 必須與 elapsedRealtimeNano 時鐘同步,如果是連續感應器,抖動必須很小。有時必須篩選時間戳記才能符合 CDD 要求 以符合需求,因為僅使用 SoC 中斷時間來設定時間戳記 導致時基誤差過長,只用感應器晶片時間設定 可能會導致未同步的 elapsedRealtimeNano 時鐘:感應器時鐘偏移。

資料和重疊欄位:由 感應器。這些欄位的意義和單位都因感應器而異 類型。如需資料欄位的說明,請參閱 sensors.h 和不同感應器類型的定義。某些感應器也會回報讀數的準確度 透過 status 欄位做為資料的一部分。這個欄位只會傳送至所選感應器類型,並在 SDK 層級顯示為精確度值。對於這些感應器,其實必須設定狀態欄位 是在感應器類型中提及 定義

中繼資料刷新完成事件

中繼資料事件的類型與一般感應器事件相同: sensors_event_meta_data_t = sensors_event_t。這些事件會透過輪詢與其他感應器事件一併傳回。具有以下欄位:

版本:必須為 META_DATA_VERSION

type:必須為 SENSOR_TYPE_META_DATA

sensor、reserved 和 timestamp:必須為 0

meta_data.what:包含這個事件的中繼資料類型。目前只有一種有效的中繼資料類型:META_DATA_FLUSH_COMPLETE

META_DATA_FLUSH_COMPLETE 事件代表 感應器 FIFO時間:meta_data.what=META_DATA_FLUSH_COMPLETEmeta_data.sensor 必須設定成清除感應器的控點。這些 只會在感應器上呼叫 flush 時產生。詳情請參閱「flush」函式相關章節。