/* * Copyright (C) 2008 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 /** * The id of this module */ #define SENSORS_HARDWARE_MODULE_ID "sensors" /** * Name of the sensors device to open */ #define SENSORS_HARDWARE_CONTROL "control" #define SENSORS_HARDWARE_DATA "data" #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<0 * ^ * | * +-----------+--> y>0 * | | * | | * | | * | | / z<0 * | | / * | | / * O-----------+/ * |[] [ ] []/ * +----------/+ y<0 * / * / * |/ z>0 (toward the sky) * * O: Origin (x=0,y=0,z=0) * * * Orientation * ----------- * * All values are angles in degrees. * * azimuth: angle between the magnetic north direction and the Y axis, around * the Z axis (0<=azimuth<360). * 0=North, 90=East, 180=South, 270=West * * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when * the z-axis moves toward the y-axis. * * roll: Rotation around Y axis (-90<=roll<=90), with positive values when * the x-axis moves towards the z-axis. * * Note: For historical reasons the roll angle is positive in the clockwise * direction (mathematically speaking, it should be positive in the * counter-clockwise direction): * * Z * ^ * (+roll) .--> | * / | * | | roll: rotation around Y axis * X <-------(.) * Y * note that +Y == -roll * * * * Note: This definition is different from yaw, pitch and roll used in aviation * where the X axis is along the long side of the plane (tail to nose). * * * Acceleration * ------------ * * All values are in SI units (m/s^2) and measure the acceleration of the * device minus the force of gravity. * * x: Acceleration minus Gx on the x-axis * y: Acceleration minus Gy on the y-axis * z: Acceleration minus Gz on the z-axis * * Examples: * When the device lies flat on a table and is pushed on its left side * toward the right, the x acceleration value is positive. * * When the device lies flat on a table, the acceleration value is +9.81, * which correspond to the acceleration of the device (0 m/s^2) minus the * force of gravity (-9.81 m/s^2). * * When the device lies flat on a table and is pushed toward the sky, the * acceleration value is greater than +9.81, which correspond to the * acceleration of the device (+A m/s^2) minus the force of * gravity (-9.81 m/s^2). * * * Magnetic Field * -------------- * * All values are in micro-Tesla (uT) and measure the ambient magnetic * field in the X, Y and Z axis. * * Proximity * --------- * * The distance value is measured in centimeters. Note that some proximity * sensors only support a binary "close" or "far" measurement. In this case, * the sensor should report its maxRange value in the "far" state and a value * less than maxRange in the "near" state. * * Light * ----- * * The light sensor value is returned in SI lux units. * */ 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; /** * Union of the various types of sensor data * that can be returned. */ typedef struct { /* sensor identifier */ int sensor; union { /* x,y,z values of the given sensor */ sensors_vec_t vector; /* orientation values are in degrees */ sensors_vec_t orientation; /* 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; /* temperature is in degrees centigrade (Celsius) */ float temperature; /* distance in centimeters */ float distance; /* light in SI lux units */ float light; }; /* time is in nanosecond */ int64_t time; uint32_t reserved; } sensors_data_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 { 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; /* temperature is in degrees centigrade (Celsius) */ float temperature; /* distance in centimeters */ float distance; /* light in SI lux units */ float light; }; uint32_t reserved1[4]; } sensors_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); }; struct sensor_t { /* name of this sensors */ const char* name; /* vendor of the hardware part */ const char* vendor; /* version of the hardware part + driver. The value of this field is * left to the implementation and doesn't have to be monotonically * increasing. */ int version; /* handle that identifies this sensors. This handle is used to activate * and deactivate this sensor. The value of the handle must be 8 bits * in this version of the API. */ int handle; /* this sensor's type. */ int type; /* maximaum 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; /* reserved fields, must be zero */ void* reserved[9]; }; /** * Every device data structure must begin with hw_device_t * followed by module specific public methods and attributes. */ struct sensors_poll_device_t { struct hw_device_t common; /** Activate/deactivate one sensor. * * @param handle is the handle of the sensor to change. * @param 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 handle, int enabled); /** * Set the delay between sensor events in nanoseconds for a given sensor * * @return 0 if successful, < 0 on error */ int (*setDelay)(struct sensors_poll_device_t *dev, int handle, int64_t ns); /** * Returns an array of sensor data. * * @return the number of events read on success, or -errno in case of an error. * */ int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count); }; struct sensors_control_device_t { struct hw_device_t common; /** * Returns a native_handle_t, which will be the parameter to * sensors_data_device_t::open_data(). * The caller takes ownership of this handle. This is intended to be * passed cross processes. * * @return a native_handle_t if successful, NULL on error */ native_handle_t* (*open_data_source)(struct sensors_control_device_t *dev); /** * Releases any resources that were created by open_data_source. * This call is optional and can be NULL if not implemented * by the sensor HAL. * * @return 0 if successful, < 0 on error */ int (*close_data_source)(struct sensors_control_device_t *dev); /** Activate/deactivate one sensor. * * @param handle is the handle of the sensor to change. * @param enabled set to 1 to enable, or 0 to disable the sensor. * * @return 0 on success, negative errno code otherwise */ int (*activate)(struct sensors_control_device_t *dev, int handle, int enabled); /** * Set the delay between sensor events in ms * * @return 0 if successful, < 0 on error */ int (*set_delay)(struct sensors_control_device_t *dev, int32_t ms); /** * Causes sensors_data_device_t.poll() to return -EWOULDBLOCK immediately. */ int (*wake)(struct sensors_control_device_t *dev); }; struct sensors_data_device_t { struct hw_device_t common; /** * Prepare to read sensor data. * * This routine does NOT take ownership of the handle * and must not close it. Typically this routine would * use a duplicate of the nh parameter. * * @param nh from sensors_control_open. * * @return 0 if successful, < 0 on error */ int (*data_open)(struct sensors_data_device_t *dev, native_handle_t* nh); /** * Caller has completed using the sensor data. * The caller will not be blocked in sensors_data_poll * when this routine is called. * * @return 0 if successful, < 0 on error */ int (*data_close)(struct sensors_data_device_t *dev); /** * Return sensor data for one of the enabled sensors. * * @return sensor handle for the returned data, 0x7FFFFFFF when * sensors_control_device_t.wake() is called and -errno on error * */ int (*poll)(struct sensors_data_device_t *dev, sensors_data_t* data); }; /** 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_control_open(const struct hw_module_t* module, struct sensors_control_device_t** device) { return module->methods->open(module, SENSORS_HARDWARE_CONTROL, (struct hw_device_t**)device); } static inline int sensors_control_close(struct sensors_control_device_t* device) { return device->common.close(&device->common); } static inline int sensors_data_open(const struct hw_module_t* module, struct sensors_data_device_t** device) { return module->methods->open(module, SENSORS_HARDWARE_DATA, (struct hw_device_t**)device); } static inline int sensors_data_close(struct sensors_data_device_t* device) { return device->common.close(&device->common); } __END_DECLS #endif // ANDROID_SENSORS_INTERFACE_H