/* * Copyright (C) 2012 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef ANDROID_SENSORS_INTERFACE_H #define ANDROID_SENSORS_INTERFACE_H #include #include #include #include #include __BEGIN_DECLS /*****************************************************************************/ #define SENSORS_HEADER_VERSION 1 #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) #define SENSORS_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, SENSORS_HEADER_VERSION) /** * Please see the Sensors section of source.android.com for an * introduction to and detailed descriptions of Android sensor types: * http://source.android.com/devices/sensors/index.html */ /** * The id of this module */ #define SENSORS_HARDWARE_MODULE_ID "sensors" /** * Name of the sensors device to open */ #define SENSORS_HARDWARE_POLL "poll" /** * Handles must be higher than SENSORS_HANDLE_BASE and must be unique. * A Handle identifies a given sensors. The handle is used to activate * and/or deactivate sensors. * In this version of the API there can only be 256 handles. */ #define SENSORS_HANDLE_BASE 0 #define SENSORS_HANDLE_BITS 8 #define SENSORS_HANDLE_COUNT (1< 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 * reporting-mode: one-shot * * A sensor enabling briefly turning the screen on to enable the user to * glance content on screen based on a specific motion. The device should * turn the screen off after a few moments. * * When this sensor triggers, the device turns the screen on momentarily * to allow the user to glance notifications or other content while the * device remains locked in a non-interactive state (dozing). This behavior * (briefly 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 briefly 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_GLANCE_GESTURE (24) #define SENSOR_STRING_TYPE_GLANCE_GESTURE "android.sensor.glance_gesture" /** * SENSOR_TYPE_PICK_UP_GESTURE * reporting-mode: one-shot * * A sensor of this type triggers when the device is picked up regardless of wherever is was * before (desk, pocket, bag). The only allowed return value is 1.0. * This sensor de-activates itself immediately after it triggers. * * Implement only the wake-up version of this sensor. */ #define SENSOR_TYPE_PICK_UP_GESTURE (25) #define SENSOR_STRING_TYPE_PICK_UP_GESTURE "android.sensor.pick_up_gesture" /* * SENSOR_TYPE_WRIST_TILT_GESTURE * trigger-mode: special * wake-up sensor: yes * * A sensor of this type triggers an event each time a tilt of the wrist-worn * device is detected. * * 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_WRIST_TILT_GESTURE (26) #define SENSOR_STRING_TYPE_WRIST_TILT_GESTURE "android.sensor.wrist_tilt_gesture" /** * Values returned by the accelerometer in various locations in the universe. * all values are in SI units (m/s^2) */ #define GRAVITY_SUN (275.0f) #define GRAVITY_EARTH (9.80665f) /** Maximum magnetic field on Earth's surface */ #define MAGNETIC_FIELD_EARTH_MAX (60.0f) /** Minimum magnetic field on Earth's surface */ #define MAGNETIC_FIELD_EARTH_MIN (30.0f) /** * Possible values of the status field of sensor events. */ #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 /** * sensor event data */ 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; /** * uncalibrated gyroscope and magnetometer event data */ 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; /** * Meta data event data */ typedef struct meta_data_event { int32_t what; int32_t sensor; } meta_data_event_t; /** * Heart rate event data */ typedef struct { // Heart rate in beats per minute. // Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT float bpm; // Status of the sensor for this reading. Set to one SENSOR_STATUS_... // Note that this value should only be set for sensors that explicitly define // the meaning of this field. This field is not piped through the framework // for other sensors. int8_t status; } heart_rate_event_t; /** * Union of the various types of sensor data * that can be returned. */ typedef struct sensors_event_t { /* must be 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) */ sensors_vec_t acceleration; /* magnetic vector values are in micro-Tesla (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 */ uncalibrated_event_t uncalibrated_magnetic; /* heart rate data containing value in bpm and status */ 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. */ uint32_t flags; uint32_t reserved1[3]; } sensors_event_t; /* see SENSOR_TYPE_META_DATA */ typedef sensors_event_t sensors_meta_data_event_t; struct sensor_t; /** * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM * and the fields of this data structure must begin with hw_module_t * followed by module specific information. */ struct sensors_module_t { struct hw_module_t common; /** * Enumerate all available sensors. The list is returned in "list". * @return number of sensors in the list */ int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list); /** * Place the module in a specific mode. The following modes are defined * * 0 - Normal operation. Default state of the module. * 1 - Loopback mode. Data is injected for the the supported * sensors by the sensor service in this mode. * @return 0 on success * -EINVAL if requested mode is not supported * -EPERM if operation is not allowed */ int (*set_operation_mode)(unsigned int mode); }; struct sensor_t { /* Name of this sensor. * All sensors of the same "type" must have a different "name". */ const char* name; /* vendor of the hardware part */ const char* vendor; /* version of the hardware part + driver. The value of this field * must increase when the driver is updated in a way that changes the * output of this sensor. This is important for fused sensors when the * fusion algorithm is updated. */ int version; /* handle that identifies this sensors. This handle is used to reference * this sensor throughout the HAL API. */ int handle; /* this sensor's type. */ int type; /* maximum range of this sensor's value in SI units */ float maxRange; /* smallest difference between two values reported by this sensor */ float resolution; /* rough estimate of this sensor's power consumption in mA */ float power; /* this value depends on the reporting mode: * * continuous: minimum sample period allowed in microseconds * on-change : 0 * one-shot :-1 * special : 0, unless otherwise noted */ int32_t minDelay; /* number of events reserved for this sensor in the batch mode FIFO. * If there is a dedicated FIFO for this sensor, then this is the * size of this FIFO. If the FIFO is shared with other sensors, * this is the size reserved for that sensor and it can be zero. */ uint32_t fifoReservedEventCount; /* maximum number of events of this sensor that could be batched. * This is especially relevant when the FIFO is shared between * several sensors; this value is then set to the size of that FIFO. */ uint32_t fifoMaxEventCount; /* type of this sensor as a string. Set to corresponding * SENSOR_STRING_TYPE_*. * When defining an OEM specific sensor or sensor manufacturer specific * sensor, use your reserve domain name as a prefix. * ex: com.google.glass.onheaddetector * For sensors of known type, the android framework might overwrite this * string automatically. */ const char* stringType; /* permission required to see this sensor, register to it and receive data. * Set to "" if no permission is required. Some sensor types like the * heart rate monitor have a mandatory require_permission. * For sensors that always require a specific permission, like the heart * rate monitor, the android framework might overwrite this string * automatically. */ const char* requiredPermission; /* This value is defined only for continuous mode and on-change sensors. It is the delay between * two sensor events corresponding to the lowest frequency that this sensor supports. When lower * frequencies are requested through batch()/setDelay() the events will be generated at this * frequency instead. It can be used by the framework or applications to estimate when the batch * FIFO may be full. * * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds. * continuous, on-change: maximum sampling period allowed in microseconds. * one-shot, special : 0 * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit * on 64 bit architectures only for binary compatibility reasons. * Availability: SENSORS_DEVICE_API_VERSION_1_3 */ #ifdef __LP64__ int64_t maxDelay; #else int32_t maxDelay; #endif /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here. * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons. * Availability: SENSORS_DEVICE_API_VERSION_1_3 */ #ifdef __LP64__ uint64_t flags; #else uint32_t flags; #endif /* reserved fields, must be zero */ void* reserved[2]; }; /* * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 * and is present for backward binary and source compatibility. * See the Sensors HAL interface section for complete descriptions of the * following functions: * 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); }; /* * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0 */ typedef struct sensors_poll_device_1 { union { /* sensors_poll_device_1 is compatible with sensors_poll_device_t, * and can be down-cast to it */ struct sensors_poll_device_t v0; struct { struct hw_device_t common; /* Activate/de-activate one sensor. Return 0 on success, negative * * sensor_handle is the handle of the sensor to change. * enabled set to 1 to enable, or 0 to disable the sensor. * * Return 0 on success, negative errno code otherwise. */ int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled); /** * Set the events's period in nanoseconds for a given sensor. * If sampling_period_ns > max_delay it will be truncated to * max_delay and if sampling_period_ns < min_delay it will be * replaced by min_delay. */ int (*setDelay)(struct sensors_poll_device_t *dev, int sensor_handle, int64_t sampling_period_ns); /** * Returns an array of sensor data. */ int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count); }; }; /* * Sets a sensor’s parameters, including sampling frequency and maximum * report latency. This function can be called while the sensor is * activated, in which case it must not cause any sensor measurements to * be lost: transitioning from one sampling rate to the other cannot cause * lost events, nor can transitioning from a high maximum report latency to * a low maximum report latency. * See the Batching sensor results page for details: * 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); /* * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t) * to the end of the "batch mode" FIFO for the specified sensor and flushes * the FIFO. * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero), * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the * event stream. This applies to all sensors other than one-shot sensors. * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate * any flush complete metadata. * If the sensor is not active at the time flush() is called, flush() should return * -EINVAL. */ int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle); /* * Inject a single sensor sample to be to this device. * data points to the sensor event to be injected * @return 0 on success * -EPERM if operation is not allowed * -EINVAL if sensor event cannot be injected */ int (*inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data); void (*reserved_procs[7])(void); } sensors_poll_device_1_t; /** convenience API for opening and closing a device */ 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); } __END_DECLS #endif // ANDROID_SENSORS_INTERFACE_H