感應器 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 包含上述定義的其他方法： activate、batch、flush和 poll。其 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： 詳述該值的使用方式請注意，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 權限進行保護。

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_COMPLETE、meta_data.sensor 必須設定成清除感應器的控點。這些 只會在感應器上呼叫 flush 時產生。詳情請參閱「flush」函式相關章節。