Android传感器HAL头文件sensors.h详细注释

最新推荐文章于 2021-05-26 07:27:00 发布
转载最新推荐文章于 2021-05-26 07:27:00 发布 · 1.6k 阅读
4 ·
CC 4.0 BY-SA版权
原文链接：https://my.oschina.net/cht2000/blog/1610278
文章标签：
#移动开发 #python #数据结构与算法
本文档详细介绍了Android传感器HAL接口中的传感器类型、报告模式、权限等概念，并提供了传感器事件数据结构及HAL接口函数的定义。
摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >
2019独角兽企业重金招聘Python工程师标准>>>
/* Android Sensor HAL头文件分析笔记 */

#ifndef ANDROID_SENSORS_INTERFACE_H		/* 此宏的作用就是避免重复包含此头文件 */
#define ANDROID_SENSORS_INTERFACE_H

#include <stdint.h>
#include <sys/cdefs.h>
#include <sys/types.h>
#include <hardware/hardware.h>
#include <cutils/native_handle.h>

/* 定义传感器头文件的版本 */
#define SENSORS_HEADER_VERSION          1	

/* 下面这几个宏定义了传感器API的版本 */
#define SENSORS_MODULE_API_VERSION_0_1  HARDWARE_MODULE_API_VERSION(0, 1)
#define SENSORS_DEVICE_API_VERSION_0_1  HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION)
#define SENSORS_DEVICE_API_VERSION_1_0  HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION)
#define SENSORS_DEVICE_API_VERSION_1_1  HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION)
#define SENSORS_DEVICE_API_VERSION_1_2  HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION)
#define SENSORS_DEVICE_API_VERSION_1_3  HARDWARE_DEVICE_API_VERSION_2(1, 3, SENSORS_HEADER_VERSION)

/**
 * 有关Android传感器类型的介绍和详细描述,请参考下面的网址,里面有详细的说明.
 * http://source.android.com/devices/sensors/index.html
 */

/* 传感器模块的ID,在写HAL模块时使用 */
#define SENSORS_HARDWARE_MODULE_ID "sensors"

/* 要打开的传感器设备的名称 */
#define SENSORS_HARDWARE_POLL       "poll"

/**
 * Handles必须高于SENSORS_HANDLE_BASE,必须是唯一的;
 * 一个Handle标识给定的传感器. Handle用于启动和/或停用传感器
 * 在这个版本的API中，只能有256个Handle
 */
#define SENSORS_HANDLE_BASE             0
#define SENSORS_HANDLE_BITS             8
#define SENSORS_HANDLE_COUNT            (1<<SENSORS_HANDLE_BITS)

/*
 * **** 过时的东东 *****
 * flags for (*batch)()
 * Availability: SENSORS_DEVICE_API_VERSION_1_0
 * see (*batch)() documentation for details.
 * Deprecated as of SENSORS_DEVICE_API_VERSION_1_3.
 * WAKE_UP_* sensors replace WAKE_UPON_FIFO_FULL concept.
 */
enum {
    SENSORS_BATCH_DRY_RUN               = 0x00000001,
    SENSORS_BATCH_WAKE_UPON_FIFO_FULL   = 0x00000002
};

/*
 * meta_data_event_t的what字段使用的值
 */
enum {
    /* 上一次刷新操作已完成 */
    META_DATA_FLUSH_COMPLETE = 1,
    META_DATA_VERSION   /* 总是最后一个，保留自动分配 */
};

/*
 * 关于身体传感器使用的权限(比如,心率监测器).
 * 有关哪些传感器需要使用此权限,请参阅传感器类型获得更详细信息.
 */
#define SENSOR_PERMISSION_BODY_SENSORS "android.permission.BODY_SENSORS"

/* 下面的枚举值只对"SENSORS_DEVICE_API_VERSION_1_3"版本有效;传感器标志,用于设置sensor_t结构体的flags成员,表示传感器的报告模式 */
enum {
    /*
     * 当数据可用时,传感器是否唤醒处于挂起模式的系统.每当从唤醒传感器传送传感器事件时, 
	 * 驱动程序需要持有唤醒锁，直到传感器服务读取事件，即直到下次调用sensors_poll_device_t.poll()函数;
	 * 一旦poll函数再次被调用，这意味着传感器服务已经读取了事件,驱动程序可以安全地释放唤醒锁.
     * 传感器服务将继续持有唤醒锁，直到应用程序实际读取事件。
     */
    SENSOR_FLAG_WAKE_UP = 1U << 0,
    /* 各种传感器的报告模式.每个传感器都要设置其中一种报告模式 */
    SENSOR_FLAG_CONTINUOUS_MODE        = 0,    // 0000——连续报告模式
    SENSOR_FLAG_ON_CHANGE_MODE         = 0x2,  // 0010——变化报告模式
    SENSOR_FLAG_ONE_SHOT_MODE          = 0x4,  // 0100——单次报告模式
    SENSOR_FLAG_SPECIAL_REPORTING_MODE = 0x6   // 0110——特殊报告模式
};

/* 用于上述定义的传感器报告模式的掩码和移位 */
#define REPORTING_MODE_MASK       (0xE)
#define REPORTING_MODE_SHIFT      (1)

/*
 * 传感器类型：
 *
 * 每个传感器都有其类型,用于定义传感器测量的内容以及如何报告测量结果.有关完整说明,请参阅基本传感器和复合传感器列表：
 * http://source.android.com/devices/sensors/base_triggers.html
 * http://source.android.com/devices/sensors/composite_sensors.html
 *
 * 设备制造商可以定义他们自己的传感器类型,给应用程序或服务专门使用.这种传感器是对于制造商特有的,不能暴露在SDK中.
 * 它们的类型必须设置为"SENSOR_TYPE_DEVICE_PRIVATE_BASE".
 *
 * 在设备专用范围之外定义的所有传感器必须对应于此文件中定义的类型,并且必须满足传感器类型说明中列出的特性.
 *
 * 从版本"SENSORS_DEVICE_API_VERSION_1_2"开始,每个传感器也有一个字符串类型.
 *  - 设备专用传感器的字符串类型必须以传感器提供商或OEM反向域名为前缀.注意,他们不能使用"android.sensor"前缀.
 *  - 设备专用范围之外的传感器字符串类型必须对应于此文件中定义的传感器类型,以"android.sensor"为前缀.
 *    例如,加速度传感器必须具有类型"SENSOR_TYPE_ACCELEROMETER"和"SENSOR_STRING_TYPE_ACCELEROMETER"
 *
 * 当Android引入新的传感器类型以取代OEM私有定义的传感器类型时,OEM必须在支持这种新的官方传感器类型的HAL版本
 * 上使用官方传感器类型和字符串类型.
 */

/* 设备制造商专用传感器类型,这些传感器类型不能暴露在SDK中 */
#define SENSOR_TYPE_DEVICE_PRIVATE_BASE     0x10000

/*
 * SENSOR_TYPE_META_DATA
 * 报告模式:n/a
 * 唤醒传感器:n/a
 *
 * "SENSOR_TYPE_META_DATA"是一个特殊的信标,用于填充"sensors_meta_data_event"结构体.不对应于具体物理传感器 
 * "sensors_meta_data_event"结构体是特殊的,它们只存在于HAL内部,并且是自发产生的,而不是与物理传感器相关.
 *
 *   sensors_meta_data_event_t.version必须设置为"META_DATA_VERSION"
 *   sensors_meta_data_event_t.sensor必须设置为0
 *   sensors_meta_data_event_t.type必须设置为"SENSOR_TYPE_META_DATA"
 *   sensors_meta_data_event_t.reserved必须设置为0
 *   sensors_meta_data_event_t.timestamp必须设置为0
 *
 * 加载的是一个"meta_data_event_t",而"meta_data_event_t"的"what"成员可以设置为以下值:
 *  -"META_DATA_FLUSH_COMPLETE";
 *	-其他值保留不允许使用;
 */
#define SENSOR_TYPE_META_DATA                        (0)

/*
  * 唤醒传感器:
  * 每个传感器可以具有唤醒和非唤醒变体中的一个或两者.
  * 当以批处理模式注册时,唤醒传感器将在其FIFOs已满或批处理超时到期时唤醒系统.
  *	必须为唤醒传感器和非唤醒传感器维护单独的FIFO.
  * 非唤醒传感器需要在FIFOs满时覆盖它们的FIFOs,直到系统唤醒.唤醒传感器将唤醒系统,当它们的FIFOs满时或者当批处理超时到期,以
  * 防止丢失数据.每个传感器的唤醒和非唤醒类型可以以彼此独立的不同速率被激活。
  *	
  * 唤醒传感器可以通过设置"SENSOR_FLAG_WAKE_UP"标志标记.
  *
  * 例如,一个设备上面有两个加速度传感器,其中之一可以是唤醒传感器(通过设置SENSOR_FLAG_WAKE_UP标志),另一个可以是常规的
  * 非唤醒传感器,这两个传感器必须彼此独立地激活/非激活.
  */

/*
 * SENSOR_TYPE_ACCELEROMETER ——加速度传感器
 * 报告模式: 连续报告模式
 *
 * 所有值均以SI单位(m/S^2)表示，并测量设备的加速度减去重力.
 *
 * 实现该传感器的非唤醒版本,如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_ACCELEROMETER                    (1)
#define SENSOR_STRING_TYPE_ACCELEROMETER             "android.sensor.accelerometer"

/*
 * SENSOR_TYPE_GEOMAGNETIC_FIELD ——磁场传感器
 * 报告模式: 连续报告模式
 *
 * 所有数值均以微特斯拉(uT)为单位，测量X、Y和Z轴上的地磁场
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_GEOMAGNETIC_FIELD                (2)
#define SENSOR_TYPE_MAGNETIC_FIELD  SENSOR_TYPE_GEOMAGNETIC_FIELD
#define SENSOR_STRING_TYPE_MAGNETIC_FIELD            "android.sensor.magnetic_field"

/*
 * SENSOR_TYPE_ORIENTATION ——方向传感器
 * 报告模式: 连续报告模式
 *
 * 所有值都是角度(以度为单位).
 *
 * 方向传感器以setDelay()函数设定的恒定速率返回所有3个轴的传感器事件.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_ORIENTATION                      (3)
#define SENSOR_STRING_TYPE_ORIENTATION               "android.sensor.orientation"

/*
 * SENSOR_TYPE_GYROSCOPE ——陀螺仪传感器
 * 报告模式: 连续报告模式
 *
 * 所有值均以"弧度/秒"为单位，并测量绕X、Y和Z轴的旋转速率.
 * 
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_GYROSCOPE                        (4)
#define SENSOR_STRING_TYPE_GYROSCOPE                 "android.sensor.gyroscope"

/*
 * SENSOR_TYPE_LIGHT ——光线传感器
 * 报告模式: 变化报告模式
 *
 * 光传感器以勒克斯为单位返回值。
 *
 * 唤醒和非唤醒版本都使用.
 */
#define SENSOR_TYPE_LIGHT                            (5)
#define SENSOR_STRING_TYPE_LIGHT                     "android.sensor.light"

/*
 * SENSOR_TYPE_PRESSURE	——压力传感器
 * 报告模式: 连续报告模式
 *
 * 压力传感器返回以百帕斯卡为单位的大气压力.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_PRESSURE                         (6)
#define SENSOR_STRING_TYPE_PRESSURE                  "android.sensor.pressure"

/* 在HAL层中不推荐使用温度类型的传感器 */
#define SENSOR_TYPE_TEMPERATURE                      (7)
#define SENSOR_STRING_TYPE_TEMPERATURE               "android.sensor.temperature"

/*
 * SENSOR_TYPE_PROXIMITY ——距离传感器
 * 报告模式: 变化报告模式
 *
 * 在呼叫期间关闭和重新打开屏幕的距离传感器是唤醒距离传感器;在实施唤醒距离传感器之前先实施非唤醒距离传感器.
 * 
 * 对于唤醒距离传感器,设置"SENSOR_FLAG_WAKE_UP"标志.
 * 返回值对应于到最近对象的距离(以厘米为单位).
 */
#define SENSOR_TYPE_PROXIMITY                        (8)
#define SENSOR_STRING_TYPE_PROXIMITY                 "android.sensor.proximity"

/*
 * SENSOR_TYPE_GRAVITY ——重力传感器
 * 报告模式: 连续报告模式
 *
 * 重力输出指示设备坐标中重力的方向和大小.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_GRAVITY                          (9)
#define SENSOR_STRING_TYPE_GRAVITY                   "android.sensor.gravity"

/*
 * SENSOR_TYPE_LINEAR_ACCELERATION ——线性加速度传感器
 * 报告模式: 连续报告模式
 *
 * 指示设备在设备坐标中的线性加速度,不包括重力.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_LINEAR_ACCELERATION             (10)
#define SENSOR_STRING_TYPE_LINEAR_ACCELERATION      "android.sensor.linear_acceleration"


/*
 * SENSOR_TYPE_ROTATION_VECTOR ——旋转矢量传感器
 * 报告模式: 连续报告模式
 *
 * 旋转矢量表示设备相对于"东-北-上"坐标系的方向
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_ROTATION_VECTOR                 (11)
#define SENSOR_STRING_TYPE_ROTATION_VECTOR          "android.sensor.rotation_vector"

/*
 * SENSOR_TYPE_RELATIVE_HUMIDITY ——相对湿度传感器
 * 报告模式: 变化报告模式
 *
 * 相对湿度传感器测量相对环境空气湿度并返回百分比值.
 *
 * 唤醒和非唤醒版本都使用.
 */
#define SENSOR_TYPE_RELATIVE_HUMIDITY               (12)
#define SENSOR_STRING_TYPE_RELATIVE_HUMIDITY        "android.sensor.relative_humidity"

/*
 * SENSOR_TYPE_AMBIENT_TEMPERATURE ——环境温度传感器
 * 报告模式: 变化报告模式
 *
 * 环境(室内)温度(摄氏度)
 *
 * 唤醒和非唤醒版本都使用.
 */
#define SENSOR_TYPE_AMBIENT_TEMPERATURE             (13)
#define SENSOR_STRING_TYPE_AMBIENT_TEMPERATURE      "android.sensor.ambient_temperature"

/*
 * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED ——未校准磁场传感器
 * 报告模式: 连续报告模式
 *
 * 和SENSOR_TYPE_MAGNETIC_FIELD类型传感器相似,但是硬铁校准是单独报告的,而不是包括在测量中.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED     (14)
#define SENSOR_STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED "android.sensor.magnetic_field_uncalibrated"

/*
 * SENSOR_TYPE_GAME_ROTATION_VECTOR ——游戏旋转矢量传感器
 * 报告模式: 连续报告模式
 *
 * 和SENSOR_TYPE_ROTATION_VECTOR类型的传感器相似,但不使用地磁场.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_GAME_ROTATION_VECTOR            (15)
#define SENSOR_STRING_TYPE_GAME_ROTATION_VECTOR     "android.sensor.game_rotation_vector"

/*
 * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED ——未校准陀螺仪传感器
 * 报告模式: 连续报告模式
 *
 * 所有值均以弧度/秒为单位,并测量绕X、Y和Z轴的旋转速率.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */
#define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED          (16)
#define SENSOR_STRING_TYPE_GYROSCOPE_UNCALIBRATED   "android.sensor.gyroscope_uncalibrated"

/*
 * SENSOR_TYPE_SIGNIFICANT_MOTION ——大幅度运动传感器
 * 报告模式: 单次报告模式
 *
 * 这种类型的传感器在每次检测到大幅度运动时触发事件并自动禁用.
 * 为了使此类型传感器有用,必须将其定义为唤醒传感器,设置"SENSOR_FLAG_WAKE_UP"标志.
 */

#define SENSOR_TYPE_SIGNIFICANT_MOTION              (17)
#define SENSOR_STRING_TYPE_SIGNIFICANT_MOTION       "android.sensor.significant_motion"

/*
 * SENSOR_TYPE_STEP_DETECTOR ——步测传感器
 * 报告模式: 特殊报告模式
 * 
 * 这种类型的传感器在用户每次采取步行时触发事件.唯一允许返回的值是1.0,并且为每一步生成一个事件.
 * 
 * 唤醒和非唤醒版本都使用.
 */

#define SENSOR_TYPE_STEP_DETECTOR                   (18)
#define SENSOR_STRING_TYPE_STEP_DETECTOR            "android.sensor.step_detector"


/*
 * SENSOR_TYPE_STEP_COUNTER ——计步传感器
 * 报告模式: 单次报告模式
 *
 * 这种类型的传感器返回自上次重新启动后用户在激活时行走的步数. 
 * 以uint64_t类型返回值,仅在系统/Android重新启动时重置为零.
 *
 * 实现该传感器的非唤醒版本.如果系统具有唤醒FIFO,则实现唤醒版本.
 */

#define SENSOR_TYPE_STEP_COUNTER                    (19)
#define SENSOR_STRING_TYPE_STEP_COUNTER             "android.sensor.step_counter"

/*
 * SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR ——不知道什么类型,估计一般手机上面都不使用
 * reporting-mode: continuous
 *
 *  Similar to SENSOR_TYPE_ROTATION_VECTOR, but using a magnetometer instead
 *  of using a gyroscope.
 *
 * Implement the non-wake-up version of this sensor and implement the wake-up
 * version if the system possesses a wake up fifo.
 */
#define SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR     (20)
#define SENSOR_STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR "android.sensor.geomagnetic_rotation_vector"

/*
 * SENSOR_TYPE_HEART_RATE ——心率传感器
 * 报告模式: 变化报告模式
 *
 * 这种类型的传感器返回当前心率.
 *  The events contain the current heart rate in beats per minute (BPM) and the
 *  status of the sensor during the measurement. See heart_rate_event_t for more
 *  details.
 *
 *  Because this sensor is on-change, events must be generated when and only
 *  when heart_rate.bpm or heart_rate.status have changed since the last
 *  event. In particular, upon the first activation, unless the device is known
 *  to not be on the body, the status field of the first event must be set to
 *  SENSOR_STATUS_UNRELIABLE. The event should be generated no faster than every
 *  period_ns passed to setDelay() or to batch().
 *  See the definition of the on-change reporting mode for more information.
 *
 *  sensor_t.requiredPermission must be set to SENSOR_PERMISSION_BODY_SENSORS.
 *
 *  Both wake-up and non wake-up versions are useful.
 */
#define SENSOR_TYPE_HEART_RATE                      (21)
#define SENSOR_STRING_TYPE_HEART_RATE               "android.sensor.heart_rate"

/*
 * SENSOR_TYPE_WAKE_UP_TILT_DETECTOR
 * reporting-mode: special (setDelay has no impact)
 *
 * A sensor of this type generates an event each time a tilt event is detected. A tilt event
 * should be generated if the direction of the 2-seconds window average gravity changed by at least
 * 35 degrees since the activation or the last trigger of the sensor.
 *     reference_estimated_gravity = average of accelerometer measurements over the first
 *                                 1 second after activation or the estimated gravity at the last
 *                                 trigger.
 *     current_estimated_gravity = average of accelerometer measurements over the last 2 seconds.
 *     trigger when angle (reference_estimated_gravity, current_estimated_gravity) > 35 degrees
 *
 * Large accelerations without a change in phone orientation should not trigger a tilt event.
 * For example, a sharp turn or strong acceleration while driving a car should not trigger a tilt
 * event, even though the angle of the average acceleration might vary by more than 35 degrees.
 *
 * Typically, this sensor is implemented with the help of only an accelerometer. Other sensors can
 * be used as well if they do not increase the power consumption significantly. This is a low power
 * sensor that should allow the AP to go into suspend mode. Do not emulate this sensor in the HAL.
 * Like other wake up sensors, the driver is expected to a hold a wake_lock with a timeout of 200 ms
 * while reporting this event. The only allowed return value is 1.0.
 *
 * Implement only the wake-up version of this sensor.
 */
#define SENSOR_TYPE_TILT_DETECTOR                      (22)
#define SENSOR_STRING_TYPE_TILT_DETECTOR               "android.sensor.tilt_detector"

/*
 * SENSOR_TYPE_WAKE_GESTURE
 * reporting-mode: one-shot
 *
 * A sensor enabling waking up the device based on a device specific motion.
 *
 * When this sensor triggers, the device behaves as if the power button was
 * pressed, turning the screen on. This behavior (turning on the screen when
 * this sensor triggers) might be deactivated by the user in the device
 * settings. Changes in settings do not impact the behavior of the sensor:
 * only whether the framework turns the screen on when it triggers.
 *
 * The actual gesture to be detected is not specified, and can be chosen by
 * the manufacturer of the device.
 * This sensor must be low power, as it is likely to be activated 24/7.
 * The only allowed value to return is 1.0.
 *
 * Implement only the wake-up version of this sensor.
 */
#define SENSOR_TYPE_WAKE_GESTURE                               (23)
#define SENSOR_STRING_TYPE_WAKE_GESTURE                        "android.sensor.wake_gesture"

/*
 * SENSOR_TYPE_GLANCE_GESTURE ——快览手势传感器
 * 报告模式: 单次报告模式
 *
 * 快览手势传感器可短暂开启屏幕,方便用户使用特定动作浏览屏幕内容.然后屏幕将再次关闭.
 *
 * 当该传感器被触发时，设备将短暂开启屏幕，让用户可以在设备处于锁定且非互动状态(低电耗模式)时浏览通知或其他内容，
 * 然后屏幕将再次关闭.
 * 用户可在设备设置中禁用这种行为(当该传感器被触发时，短暂开启屏幕).更改设置不会影响传感器的行为:仅改变当该传感器被触发时,
 * Android框架是否短暂开启屏幕.未指定待检测的实际手势，可由设备制造商进行选择.
 *
 * 只能实现唤醒传感器版本.
 */
#define SENSOR_TYPE_GLANCE_GESTURE                             (24)
#define SENSOR_STRING_TYPE_GLANCE_GESTURE                      "android.sensor.glance_gesture"

/*
 * SENSOR_TYPE_PICK_UP_GESTURE ——拿起手势传感器
 * 报告模式: 单次报告模式
 *
 * 拿起手势传感器仅在拿起设备时被触发,并且不考虑设备在拿起前的所在位置(桌面、口袋里或袋子里).
 * 唯一允许的返回值是1.0.此传感器在触发后立即停止激活.
 *
 * 只能实现唤醒传感器版本.
 */
#define SENSOR_TYPE_PICK_UP_GESTURE                            (25)
#define SENSOR_STRING_TYPE_PICK_UP_GESTURE                     "android.sensor.pick_up_gesture"

/* 加速度传感器在不同位置返回的值,所有值均以SI(m/S^2)为单位 */
#define GRAVITY_SUN             (275.0f)
#define GRAVITY_EARTH           (9.80665f)


/* 地球表面最大磁场 */
#define MAGNETIC_FIELD_EARTH_MAX    (60.0f)

/* 地球表面最小磁场 */
#define MAGNETIC_FIELD_EARTH_MIN    (30.0f)

/* 传感器事件状态字段的可能值 */
#define SENSOR_STATUS_NO_CONTACT        -1
#define SENSOR_STATUS_UNRELIABLE        0
#define SENSOR_STATUS_ACCURACY_LOW      1
#define SENSOR_STATUS_ACCURACY_MEDIUM   2
#define SENSOR_STATUS_ACCURACY_HIGH     3

/* 传感器事件数据 */
typedef struct {
    union {
        float v[3];
        struct {
            float x;
            float y;
            float z;
        };
        struct {
            float azimuth;
            float pitch;
            float roll;
        };
    };
    int8_t status;
    uint8_t reserved[3];
} sensors_vec_t;

/* 未校准陀螺仪和磁力计事件数据 */
typedef struct {
  union {
    float uncalib[3];
    struct {
      float x_uncalib;
      float y_uncalib;
      float z_uncalib;
    };
  };
  union {
    float bias[3];
    struct {
      float x_bias;
      float y_bias;
      float z_bias;
    };
  };
} uncalibrated_event_t;

/* 元数据事件数据 */
typedef struct meta_data_event {
    int32_t what;
    int32_t sensor;
} meta_data_event_t;

/* 心率事件数据 */
typedef struct {
  // 心率(以每分钟搏动为单位).
  // 当状态为"SENSOR_STATUS_UNRELIABLE"或"NO_CONTACT"时,应设置为0.
  float bpm;
  // 要读的传感器的状态,应该设置为"SENSOR_STATUS_..."字段.
  // 请注意，此值应仅针对明确定义此字段含义的传感器进行设置.
  // 此字段不通过其他传感器的框架进行管道传输.
  int8_t status;
} heart_rate_event_t;

/* 可返回的各种类型传感器数据的联合体 */
typedef struct sensors_event_t {
    /* must be sizeof(struct sensors_event_t) 必须设置为"sizeof(struct sensors_event_t)" */
    int32_t version;

    /* sensor identifier 传感器标识符 */
    int32_t sensor;

    /* sensor type 传感器类型 */
    int32_t type;

    /* reserved 保留 */
    int32_t reserved0;

    /* time is in nanosecond 纳秒为单位的时间 */
    int64_t timestamp;

    union {
        union {
            float           data[16];

            /* acceleration values are in meter per second per second (m/s^2) 加速度值以米每秒为单位(m/^2) */
            sensors_vec_t   acceleration;

            /* magnetic vector values are in micro-Tesla (uT) 磁矢量值以微特斯拉(uT)为单位 */
            sensors_vec_t   magnetic;

            /* orientation values are in degrees 方向值以度为单位 */
            sensors_vec_t   orientation;

            /* gyroscope values are in rad/s 陀螺仪值以弧度/秒为单位 */
            sensors_vec_t   gyro;

            /* temperature is in degrees centigrade (Celsius) 温度以摄氏度为单位 */
            float           temperature;

            /* distance in centimeters 距离(以厘米为单位) */
            float           distance;

            /* light in SI lux units 光,单位为司勒克斯 */
            float           light;

            /* pressure in hectopascal (hPa) 压力,单位是百帕斯卡*/
            float           pressure;

            /* relative humidity in percent 相对湿度(百分比) */
            float           relative_humidity;

            /* uncalibrated gyroscope values are in rad/s 未校准陀螺仪值以弧度/秒为单位 */
            uncalibrated_event_t uncalibrated_gyro;

            /* uncalibrated magnetometer values are in micro-Teslas 未校准的磁力计值以微Teslas为单位 */
            uncalibrated_event_t uncalibrated_magnetic;

            /* heart rate data containing value in bpm and status 包含BPM值和状态的心率数据 */
            heart_rate_event_t heart_rate;

            /* this is a special event. see SENSOR_TYPE_META_DATA above. 这是一个特殊的事件,请参阅上面的传感器类型元数据.
             * sensors_meta_data_event_t events are all reported with a type of
             * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero.
             */
            meta_data_event_t meta_data;
        };

        union {
            uint64_t        data[8];
            /* step-counter 步数计数器 */
            uint64_t        step_counter;
        } u64;
    };

    /* Reserved flags for internal use. Set to zero. 保留内部使用,应该设置为0 */
    uint32_t flags;

    uint32_t reserved1[3];
} sensors_event_t;


/* 查看SENSOR_TYPE_META_DATA定义 */
typedef sensors_event_t sensors_meta_data_event_t;


struct sensor_t;

/**
 * 每个硬件模块都必须有一个名为HAL_MODULE_INFO_SYM的数据结构;
 * 并且该数据结构的字段必须以hw_module_t开头,然后是模块特定信息.
 */
struct sensors_module_t {
    struct hw_module_t common;

    /* 列举所有可用的传感器.以列表的形式返回,并且返回列表中传感器的数量 */
    int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list);       
};

struct sensor_t {

    /* 传感器的名称.
     * 同一"类型"的所有传感器必须具有不同的"名称"。
     */
    const char*     name;

    /* 硬件部件供应商 */
    const char*     vendor;

    /* 硬件部件+驱动程序的版本.当驱动程序以更改此传感器输出的方式更新时,此字段的值必须增加.
 	 * 当融合算法更新时,这对于融合传感器是重要的.
     */
    int             version;

    /* 识别传感器的句柄.句柄用于在整个HAL API中引用传感器*/     
    int             handle;

    /* 传感器的类型(type). */
    int             type;

    /* 传感器值的最大范围(以SI为单位) */
    float           maxRange;

    /* 传感器报告的两个值之间的最小差值 */
    float           resolution;

    /* 传感器在电流为毫安时功耗的粗略估计 */
    float           power;

    /* 此值取决于报告模式:
     *
     *   连续报告模式:允许的最小采样周期(微秒);
     *   变化报告模式: 0;
     *   单次报告模式: -1;
     *   特殊报告模式: 0,除非另有说明;
     */
    int32_t         minDelay;

    /* 批处理模式FIFO中为此传感器保留的事件数.如果此传感器有专用的FIFO,则这是此FIFO的大小.
     * 如果FIFO与其它传感器共享,这是为该传感器保留的大小,可以为零.
     */
    uint32_t        fifoReservedEventCount;

    /* 传感器可批处理的最大事件数.当FIFO在多个传感器之间共享时,这尤其相关.
     * 然后将该值设置为该FIFO的大小.
     */
    uint32_t        fifoMaxEventCount;

    /* 传感器的字符串类型.设置为相应的"SENSOR_STRING_TYPE_*"类型.
     * 定义OEM特定传感器或传感器制造商特定传感器时,请使用保留域名作为前缀.
     * 例如: com.google.glass.onheaddetector
     * 对于已知类型的传感器,Android框架可能会自动覆盖此字符串.
     */
    const char*    stringType;

    /* 传感器所需的权限,注册并接收数据.如果设置为"",说明传感器不需要权限.
     * 有些传感器类型(如心率监视器)是必需设置权限的.例如,心率计.
     */
    const char*    requiredPermission;

    /* 此值仅针对连续模式和变化模式传感器定义.这是两个传感器事件之间的延迟,对应于此传感器支持的最低频率.
	 * 当通过batch()/setDelay()请求较低频率时,事件将以此频率生成.
     * 它可以由框架或应用程序用来估计批处理FIFO何时可以满.
     *
     * 注意:1).period_ns以纳秒为单位,而maxDelay/minDelay则以微秒为单位.连续模式、变化模式:允许的最大采样周期(微秒).
     *         单次模式,特殊模式应该设置为0.
     *      2).maxDelay应始终符合32位有符号整数. 仅出于二进制兼容性的原因,才会在64位体系结构上将它声明为64位.
     * 使用API范围: SENSORS_DEVICE_API_VERSION_1_3
     */
     int32_t maxDelay;

    /* 传感器的标志.查看上面定义的"SENSOR_FLAG_*".这里仅使用最低有效32位.
     * 使用API范围: SENSORS_DEVICE_API_VERSION_1_3
     */

    uint32_t flags;

    /* 保留字段,设置为0 */
    void* reserved[2];
};


/*
 * 此结构体在API版本为"SENSORS_DEVICE_API_VERSION_0_1"时使用;且用于向后兼容性.
 * 有关功能的完整说明，请参阅传感器HAL接口部分:
 * http://source.android.com/devices/sensors/index.html#hal
 */
struct sensors_poll_device_t {
    struct hw_device_t common;
    int (*activate)(struct sensors_poll_device_t *dev,int sensor_handle, int enabled);          
    int (*setDelay)(struct sensors_poll_device_t *dev,int sensor_handle, int64_t sampling_period_ns);           
    int (*poll)(struct sensors_poll_device_t *dev,sensors_event_t* data, int count);          
};

/*
 * 此结构体用于HAL版本大于"SENSORS_DEVICE_API_VERSION_1_0"时使用;
 */
typedef struct sensors_poll_device_1 {
    union {
        /* 此结构体和sensors_poll_device_t是兼容的,并且可以向下投射到它 */
        struct sensors_poll_device_t v0;

        struct {
            struct hw_device_t common;

            /* 激活/禁止一个传感器.返回0表示成功,否则返回负值.
             * sensor_handle:是要更换的传感器的手柄;
             * enabled:设置为1表示使能,设置为0表示禁止;
             */
            int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
                   
            /* 设置给定传感器的事件周期(纳秒).也就是设置时间延迟 */            
            int (*setDelay)(struct sensors_poll_device_t *dev,int sensor_handle, int64_t sampling_period_ns);
                    
            /* 返回传感器数据的数组 */
            int (*poll)(struct sensors_poll_device_t *dev,sensors_event_t* data, int count);
                    
        };
    };

    /*
     * 此函数用于设置传感器的参数,包括采样频率和最大报告延迟时间.当传感器被激活时调用;
	 * 在这种情况下,它不得导致任何传感器测量值丢失,从一个采样率转换到另一采样率不能导致丢失事件;
	 * 也不能从高最大报告延迟转换到低最大报告延迟时,导致数据的丢失.
     * 有关详细信息，请参阅批处理传感器结果页面:
     * http://source.android.com/devices/sensors/batching.html
     */
    int (*batch)(struct sensors_poll_device_1* dev,int sensor_handle, int flags, int64_t sampling_period_ns,int64_t max_report_latency_ns);
                

    /*
     * 刷新FIFO.如果FIFO为空或传感器不支持批处理( FIFO大小为零),它应该返回"META_DATA_FLUSH_COMPLETE"刷新完成事件.
     * 这适用于除单次模式传感器之外的所有传感器.如果传感器是单次模式传感器,必须返回"-EINVAL".
     * 如果调用flush()函数时传感器未处于活动状态,应该返回"-EINVAL".
     */
    int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

    void (*reserved_procs[8])(void);

} sensors_poll_device_1_t;


/* 用于打开和关闭设备的API */

static inline int sensors_open(const struct hw_module_t* module,struct sensors_poll_device_t** device) {       
    return module->methods->open(module,SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 
}

static inline int sensors_close(struct sensors_poll_device_t* device) {
    return device->common.close(&device->common);
}

static inline int sensors_open_1(const struct hw_module_t* module,sensors_poll_device_1_t** device) {      
    return module->methods->open(module,SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
}

static inline int sensors_close_1(sensors_poll_device_1_t* device) {
    return device->common.close(&device->common);
}

#endif  // ANDROID_SENSORS_INTERFACE_H
转载于:https://my.oschina.net/cht2000/blog/1610278