感應器 HAL 1.0

感應器 HAL 介面 (在 sensors.h 中宣告) 代表 Android 架構和 硬體專屬軟體HAL 實作必須定義每個函式 物件宣告中。主要功能如下：

  • 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 不得代表應用程式保留部分 Wake Lock。

喚醒感應器在持續傳送事件時可防止 SoC 將進入暫停模式 但如果不需要提交活動 必須解除 Wake Lock 狀態

如果 enabled 為 1，且感應器已啟用，此函式即免人工管理 所以要還是對

如果 enabled 為 0，且感應器已停用，此函式即為免人工管理 所以要還是對

這個函式會在成功時傳回 0，否則會傳回負錯誤數。

batch(感應器, 旗標, 取樣期間, 報表延遲時間上限)

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如果指定的感應器是 單樣本感應器或未啟用，若未啟用，則會顯示負錯誤數。

投票結果

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 Wake-up Barometer」、「MPU6515 Game」 旋轉向量」

handle：註冊感應器時，用於參照感應器的整數；或 並從中產生事件

type：感應器的類型，查看感應器的說明 詳情請參閱「什麼是 Android 感應器？」一文。詳情請參閱官方感應器類型的「感應器類型」一文。適用對象 非官方感應器類型，type 必須以 SENSOR_TYPE_DEVICE_PRIVATE_BASE 開頭

stringType：以字串形式的感應器類型。當 感應器的官方類型設為 SENSOR_STRING_TYPE_*。時間 感應器具有製造商專屬類型，「stringType」必須 開頭是製造商反向網域名稱例如感應器 (例如 由 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。

Resolution：感應器可測量的最小值， 通常根據 maxRange 和測量中的位元數計算。

功率：啟用感應器的耗電成本 (以 milliAmp 為單位)。 這幾乎總是比 會提供基礎感應器的規格書請參閱基礎感應器 != 實體 感應器瞭解詳情及查看電源測量結果 程序，進一步瞭解如何測量感應器耗電量。 如果感應器的耗電量取決於裝置是否移動， 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」保護 權限。

Sensor_event_t

Android 感應器產生且透過 poll 函式回報的感應器事件為 type sensors_event_t。以下是一些 sensors_event_t 的重要欄位：

版本：必須為 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、保留和 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 函式的說明。