센서 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를 참조하세요.

센서가 목록에 표시되는 순서가 곧 센서가 애플리케이션에 보고되는 순서입니다. 일반적으로 기본 센서가 먼저 표시되고 복합 센서가 뒤를 따릅니다.

여러 센서가 동일한 센서 유형과 wake-up 속성을 공유하는 경우 목록의 첫 번째 센서를 '기본' 센서라고 부릅니다. 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) 호출을 통해 비활성화되려면 계속 수락해야 합니다.

non-wake-up 센서로 인해 SoC가 정지 모드로 전환되는 경우는 없습니다. 즉, HAL에는 애플리케이션을 대신하여 부분적 wake-lock을 보관하면 안 됩니다.

wake-up 센서는 계속해서 이벤트를 전달할 때 SoC가 정지 모드로 전환되지 않도록 할 수 있지만 전달할 이벤트가 없는 경우에는 부분적 wake-lock을 해제해야 합니다.

enabled가 1이고 센서가 이미 활성화된 경우 이 함수는 no-op이고 성공합니다.

enabled가 0이고 센서가 이미 비활성화된 경우 이 함수는 no-op이고 성공합니다.

이 함수는 성공 시 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이 포함되어 있습니다. 유형 hw_device_t의 common 필드는 HAL의 버전 번호를 정의합니다.

sensor_t

sensor_t는 Android 센서를 나타냅니다. 다음은 몇 가지 중요 필드입니다.

name: 사용자가 볼 수 있는 문자열입니다. 센서를 나타냅니다. 이 문자열에는 보통 기본 센서의 이름 일부, 센서 유형과 wake-up 센서 여부가 포함됩니다. '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 팀에서 정의한 센서(예: unicorn detector)는 stringType=”com.fictional_company.cool_product.unicorn_detector”를 사용할 수 있습니다. stringType은 비공식 센서 유형을 고유하게 식별하는 데 사용할 수 있습니다. 유형 및 문자열 유형에 관한 자세한 내용은 sensors.h를 참고하세요.

requiredPermission: 애플리케이션이 센서를 보고 센서에 등록하고 데이터를 수신하기 위해 보유해야 하는 권한을 나타내는 문자열입니다. 빈 문자열은 애플리케이션이 이 센서에 액세스하기 위한 어떠한 권한도 요구하지 않음을 의미합니다. 심박수 모니터와 같은 일부 센서 유형에는 필수 requiredPermission이 있습니다. 심박수와 같은 민감한 사용자 정보를 제공하는 센서는 권한으로 보호해야 합니다.

flags: 이 센서의 플래그입니다. 센서의 보고 모드, 그리고 센서가 wake-up 센서인지 정의합니다. 예를 들어 원샷 wake-up 센서에는 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: 센서 사용 설정을 위한 전력 소모량입니다(단위: milliAmps). 거의 대부분의 경우 기본 센서의 데이터시트에 보고된 전력 소모량보다 높습니다. 자세한 내용은 기본 센서 != 물리적 센서를, 센서의 전력 소모량 측정 방법에 관한 자세한 내용은 전력 측정 프로세스를 참고하세요. 센서의 전력 소모량이 기기의 움직임 여부에 따라 달라지는 경우에는 이동 중 전력 소모량이 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 and overlapping fields: 센서로 측정되는 값입니다. 두 필드의 의미와 단위는 각 센서 유형과 관련이 있습니다. 데이터 필드에 관한 설명은 sensors.h 및 여러 센서 유형의 정의를 참고하세요. 일부 센서의 경우 status 필드를 통해 판독값의 정확도까지 데이터의 일부로 보고될 수 있습니다. 이 필드는 이러한 특정 센서 유형에만 파이핑되며 SDK 계층에 정확도 값으로 표시됩니다. 이러한 센서의 경우 상태 필드가 설정되어야 한다는 사실이 센서 유형 정의에 언급됩니다.

메타데이터 플러시 완료 이벤트

메타데이터 이벤트의 유형은 일반 센서 이벤트의 유형과 동일합니다(sensors_event_meta_data_t = sensors_event_t). 이러한 유형은 poll을 통해 다른 센서 이벤트와 함께 반환되며, 다음과 같은 필드를 보유합니다.

version: META_DATA_VERSION이어야 합니다.

type: SENSOR_TYPE_META_DATA여야 합니다.

sensor, reserved, and 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 함수 섹션을 참고하세요.