Sensors 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)。

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

activate(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 進入暫停模式，但如果不需要傳送事件，則必須釋放部分喚醒鎖定。

如果 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, sampling period)

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 的結尾，且必須刷新 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

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 的版本號碼。

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 必須以製造商的反向網域名稱開頭。舉例來說，虛構公司 酷產品團隊定義的傳感器 (例如獨角獸偵測器) 可以使用 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：啟用感應器的耗電量 (以毫安培為單位)。這幾乎總是比 會提供基礎感應器的規格書詳情請參閱「Base sensors != physical sensors」一文，瞭解如何評估感應器的耗電量。電力測量程序一文則會說明如何評估感應器的耗電量。如果感應器的耗電量取決於裝置是否移動， 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 的部分重要欄位：

version：必須為 sizeof(struct sensors_event_t)

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

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

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

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

中繼資料清除完成事件

中繼資料事件的類型與一般感應器事件相同： sensors_event_meta_data_t = sensors_event_t。這類值會與 追蹤其他感應器事件這些記錄包含下列欄位：

version：必須為 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 函式的說明。