センサー HAL 1.0

sensors.h で宣言されているセンサー HAL インターフェースは、Android フレームワークとハードウェア固有のソフトウェアの間のインターフェースを表します。HAL 実装では、sensor.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 をご覧ください。

センサーリスト内のセンサーの順序は、センサーがアプリケーションにレポートされる順序です。通常、基本センサーが最初にリストされ、その後に複合センサーがリストされます。

複数のセンサーが同じセンサータイプと wakeup プロパティを共有する場合、リスト内の最初のセンサーが「デフォルト」センサーと呼ばれます。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 はアプリケーションに代わって部分的なウェイクロックを保持してはなりません。

ウェイクアップセンサーは、イベントを継続的に配信している場合、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 以降、この関数はサポート終了となり、呼び出されることはありません。代わりに、sampling_period_ns パラメータを設定するために batch 関数が呼び出されます。

HAL バージョン 1.0 では、sampling_period_ns の設定に batch ではなく 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 の実装では、get_sensors_list 関数を公開するために、この型のオブジェクト HAL_MODULE_INFO_SYM を定義する必要があります。詳細については、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 Accelerometer」、「MAX21000 Uncalibrated Gyroscope」、「BMP280 Wake-up Barometer」、「MPU6515 Game Rotation Vector」などです。

handle: センサーへの登録時またはセンサーからイベントを生成する際に、センサーの参照に使用される整数。

type: センサーのタイプ。センサータイプの説明については、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 をレポートします。

resolution: センサーで測定できる値の最小差。通常は 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 クロックと同期しなくなる可能性があるためです。

data フィールドと overlapping フィールド: センサーによって測定される値。各フィールドの意味と単位は、センサータイプごとに異なります。データフィールドの説明については、sensors.h と各種センサータイプの定義をご覧ください。一部のセンサーでは、読み取りの精度もデータの一部として、status フィールドを通じてレポートされます。このフィールドは、限定されたセンサータイプのみをパイプ処理して、SDK レイヤの精度値として表示されます。このようなセンサーの場合、ステータスフィールドを設定する必要があることがセンサータイプの定義で説明されています。

メタデータのフラッシュ完了イベント

メタデータイベントは、通常のセンサーイベントと同じ型です（sensors_event_meta_data_t = sensors_event_t）。どちらのイベントも、ポーリングにより他のセンサーイベントと一緒に返され、次のフィールドがあります。

version: META_DATA_VERSION にする必要があります。

type: SENSOR_TYPE_META_DATA にする必要があります。

sensor、reserved、timestamp: 0 にする必要があります。

meta_data.what: このイベントのメタデータタイプが含まれます。現在有効なメタデータ型は META_DATA_FLUSH_COMPLETE の 1 つのみです。

META_DATA_FLUSH_COMPLETE イベントは、センサー FIFO のフラッシュ完了を表します。meta_data.what=META_DATA_FLUSH_COMPLETE の場合、meta_data.sensor を、フラッシュされたセンサーのハンドルに設定する必要があります。これらは、センサーで flush が呼び出された場合にのみ生成されます。詳細については、flush 関数のセクションをご覧ください。