2012-09-18 07:14:48 -07:00
|
|
|
#ifndef EEZE_SENSOR_H
|
|
|
|
#define EEZE_SENSOR_H
|
|
|
|
|
|
|
|
#ifdef EAPI
|
|
|
|
# undef EAPI
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#ifdef __GNUC__
|
|
|
|
# if __GNUC__ >= 4
|
|
|
|
# define EAPI __attribute__ ((visibility("default")))
|
|
|
|
# else
|
|
|
|
# define EAPI
|
|
|
|
# endif
|
|
|
|
#else
|
|
|
|
# define EAPI
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#include <Eina.h>
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @file Eeze_Sensor.h
|
2012-12-05 05:42:37 -08:00
|
|
|
* @brief Sensor information subsystem
|
2012-09-18 07:14:48 -07:00
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Eeze sensor functions allow you to gather sensor information from different
|
2012-12-05 05:42:37 -08:00
|
|
|
* sensor sources available on your hardware. It supports a plugin architecture
|
2012-12-03 06:44:33 -08:00
|
|
|
* to support different hardware platforms and devices. These plugins can be
|
2012-12-05 05:42:37 -08:00
|
|
|
* loaded at runtime.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Right now we have support for the Tizen sensor framework as well as a simple
|
2012-12-05 05:42:37 -08:00
|
|
|
* fake plugin to be used as a test harness for development. Plugins for other
|
|
|
|
* sensor frameworks or platforms are always welcome.
|
|
|
|
*
|
|
|
|
* Synchronous as well as asynchronous reads are possible. As reading the
|
|
|
|
* physical sensor might be bound to a high latency and thus cost the value of
|
|
|
|
* the last read is cached within Eeze_Sensor together with a timestamp of the
|
|
|
|
* actual read out. This can speed up the value access for application while the
|
|
|
|
* values are still getting updating asynchronously in the background. The
|
|
|
|
* timestamp should be checked if the specific time requirements are needed.
|
|
|
|
*
|
|
|
|
* As an alternative the sensor could be read synchronously. With the
|
|
|
|
* disadvantage that the function call will block until the data is read from
|
|
|
|
* the sensor.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
|
|
|
* @since 1.8
|
2012-09-18 07:14:48 -07:00
|
|
|
*
|
2013-01-03 12:37:42 -08:00
|
|
|
* @addtogroup Eeze_Sensor Sensor
|
|
|
|
* Gather sensor information from different sources. Works based on plugins,
|
|
|
|
* with a Tizen plugin being available.
|
|
|
|
*
|
|
|
|
* @ingroup Eeze
|
2012-09-18 07:14:48 -07:00
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @enum Eeze_Sensor_Type
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* All sensor types known by Eeze Sensor. This list of types include real
|
|
|
|
* physical types like proximity or light as well as "aggregated" types like
|
2012-12-13 06:17:14 -08:00
|
|
|
* facedown or doubletap. All types with MOTION in their name can be used as
|
|
|
|
* real events coming from the underlying system. This is not supported on all
|
|
|
|
* systems.
|
2012-12-03 06:44:33 -08:00
|
|
|
*
|
|
|
|
* @since 1.8
|
2012-09-18 07:14:48 -07:00
|
|
|
*/
|
|
|
|
typedef enum
|
|
|
|
{
|
|
|
|
EEZE_SENSOR_TYPE_ACCELEROMETER, /**< Accelerometer sensor */
|
2013-04-02 07:59:51 -07:00
|
|
|
EEZE_SENSOR_TYPE_GRAVITY, /**< Gravity sensor */
|
|
|
|
EEZE_SENSOR_TYPE_LINEAR_ACCELERATION, /**< */
|
|
|
|
EEZE_SENSOR_TYPE_DEVICE_ORIENTATION, /**< */
|
2012-09-18 07:14:48 -07:00
|
|
|
EEZE_SENSOR_TYPE_MAGNETIC, /**< Magnetic sensor */
|
|
|
|
EEZE_SENSOR_TYPE_ORIENTATION, /**< Orientation sensor */
|
|
|
|
EEZE_SENSOR_TYPE_GYROSCOPE, /**< Gyroscope sensor */
|
|
|
|
EEZE_SENSOR_TYPE_LIGHT, /**< Light sensor */
|
|
|
|
EEZE_SENSOR_TYPE_PROXIMITY, /**< Proximity sensor */
|
|
|
|
EEZE_SENSOR_TYPE_MOTION_SNAP, /**< Snap motion sensor */
|
|
|
|
EEZE_SENSOR_TYPE_MOTION_SHAKE, /**< Shake motion sensor */
|
|
|
|
EEZE_SENSOR_TYPE_MOTION_DOUBLETAP, /**< Doubletap motion sensor */
|
|
|
|
EEZE_SENSOR_TYPE_MOTION_PANNING, /**< Panning motion sensor */
|
2013-04-02 07:59:51 -07:00
|
|
|
EEZE_SENSOR_TYPE_MOTION_PANNING_BROWSE, /**< */
|
|
|
|
EEZE_SENSOR_TYPE_MOTION_TILT, /**< */
|
2012-09-18 07:14:48 -07:00
|
|
|
EEZE_SENSOR_TYPE_MOTION_FACEDOWN, /**< Facedown motion sensor */
|
2013-04-02 07:59:51 -07:00
|
|
|
EEZE_SENSOR_TYPE_MOTION_DIRECT_CALL, /**< */
|
|
|
|
EEZE_SENSOR_TYPE_MOTION_SMART_ALERT, /**< */
|
|
|
|
EEZE_SENSOR_TYPE_MOTION_NO_MOVE, /**< */
|
2012-09-18 07:14:48 -07:00
|
|
|
/* Non-Tizen from here */
|
|
|
|
EEZE_SENSOR_TYPE_BAROMETER, /**< Barometer sensor */
|
|
|
|
EEZE_SENSOR_TYPE_TEMPERATURE, /**< Temperature sensor */
|
|
|
|
EEZE_SENSOR_TYPE_LAST = 0xFF /**< Last item to mark end of enum */
|
|
|
|
} Eeze_Sensor_Type;
|
|
|
|
|
|
|
|
/**
|
2013-01-03 12:37:42 -08:00
|
|
|
* @defgroup Eeze_Sensor_Events Available eeze sensor events
|
2012-09-18 07:14:48 -07:00
|
|
|
* @brief Sensor events that are emitted from the library as ecore events
|
2013-01-03 12:37:42 -08:00
|
|
|
* @ingroup Eeze
|
2012-09-18 07:14:48 -07:00
|
|
|
*
|
2012-12-03 06:45:10 -08:00
|
|
|
* Event types used to register ecore_event_handler on. These events are used
|
2012-12-03 06:44:33 -08:00
|
|
|
* for #eeze_sensor_async_read to deliver read out data. It is also used for
|
2012-12-13 06:17:14 -08:00
|
|
|
* generated events like facedown or shake. Subscribing to these events in your
|
|
|
|
* application allowsyou to react on these changes in an efficient way without
|
|
|
|
* polling for new updates and wasting power and computing cycles.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
* @{
|
|
|
|
*/
|
2014-10-01 00:29:21 -07:00
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_ACCELEROMETER;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_GRAVITY;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_LINEAR_ACCELERATION;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_DEVICE_ORIENTATION;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_MAGNETIC;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_ORIENTATION;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_GYROSCOPE;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_LIGHT;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_PROXIMITY;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_SNAP;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_SHAKE;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_DOUBLETAP;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_PANNING;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_PANNING_BROWSE;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_TILT;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_FACEDOWN;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_DIRECT_CALL;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_SMART_ALERT;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_NO_MOVE;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_BAROMETER;
|
|
|
|
EAPI extern int EEZE_SENSOR_EVENT_TEMPERATURE;
|
2012-09-18 07:14:48 -07:00
|
|
|
/**@}*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eeze_Sensor_Obj;
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Object for a sensor type. Keeps information about the type and holds the
|
|
|
|
* data for the accessor functions. As this information gets also updated by
|
|
|
|
* asynchronous reads it might be a good idea to check the timestamp value to
|
2013-04-16 05:16:55 -07:00
|
|
|
* see when the data has been updated. The timestamp is given as floating point
|
|
|
|
* value in seconds.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* You are not supposed to access the raw data values from here but use the
|
|
|
|
* getter functions for it. Using the raw values from this struct might break
|
|
|
|
* your applications later if the internal structure changes.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
|
|
|
* @since 1.8
|
2012-09-18 07:14:48 -07:00
|
|
|
*/
|
|
|
|
typedef struct _Eeze_Sensor_Obj
|
|
|
|
{
|
2013-04-11 03:21:07 -07:00
|
|
|
Eeze_Sensor_Type type; /**< Sensor type see #Eeze_Sensor_Type */
|
2012-09-18 07:14:48 -07:00
|
|
|
int accuracy; /**< Accuracy of the sensor value */
|
|
|
|
float data[3]; /**< Sensor data depending on the sensor type */
|
2013-04-16 05:16:55 -07:00
|
|
|
double timestamp; /**< Timestamp of data read */
|
2012-09-18 07:14:48 -07:00
|
|
|
Eina_Bool continuous_flow; /**< FUTURE USE: Continuous flow of sensor read out */
|
2013-04-19 01:55:02 -07:00
|
|
|
void *user_data; /**< Data pointer used for passing data to the asynchronous callback */
|
2012-09-18 07:14:48 -07:00
|
|
|
} Eeze_Sensor_Obj;
|
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
extern "C" {
|
|
|
|
#endif
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Create sensor object to operate on.
|
|
|
|
* @param type Sensor type to create object from.
|
|
|
|
* @return Sensor object for the given type.
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Takes the sensor type and create an object for it to operate on. During this
|
|
|
|
* it also does an initial sensor data read to fill the sensor data into the
|
|
|
|
* object. The #eeze_sensor_free function must be used to destroy the object
|
|
|
|
* and release its memory.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* For every sensor type you want to work with this is the first thing you have
|
|
|
|
* to do. Create the object from the type and everything else the operates on
|
|
|
|
* this object.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-12-13 06:17:14 -08:00
|
|
|
* This also takes into account what runtime modules are loaded and handles
|
|
|
|
* them in a given priority to pick up the best sensor source for your sensor
|
|
|
|
* object.
|
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eeze_Sensor_Obj *eeze_sensor_new(Eeze_Sensor_Type type);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Free a sensor object.
|
|
|
|
* @param sens Sensor object to operate on.
|
|
|
|
*
|
2012-12-13 06:17:14 -08:00
|
|
|
* Free an sensor object when it is no longer needed. Always use this function
|
|
|
|
* to cleanup unused sensor objects.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Get accuracy from sensor object.
|
|
|
|
* @param sens Sensor object to operate on.
|
2012-09-28 02:10:40 -07:00
|
|
|
* @param accuracy Pointer to write accuracy value into.
|
2012-09-18 07:14:48 -07:00
|
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Access function to get the accuracy property from the sensor object. The
|
|
|
|
* accuracy value can have the following values and meaning:
|
2012-10-02 01:47:45 -07:00
|
|
|
* -1 Undefined accuracy
|
|
|
|
* 0 Bad accurancy
|
|
|
|
* 1 Normal accuracy
|
|
|
|
* 2 Good accuracy
|
|
|
|
* 3 Very good accuracy
|
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Get data from all three data properties
|
|
|
|
* @param sens Sensor object to operate on.
|
|
|
|
* @param x Pointer to write first data property value into.
|
|
|
|
* @param y Pointer to write second data property value into.
|
|
|
|
* @param z Pointer to write third data property value into.
|
|
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Access function to get all three data properties from the sensor object.
|
|
|
|
* This is used for sensor types that offer all three values. Like accelerometer
|
|
|
|
* and magnetic.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eeze_sensor_xyz_get(Eeze_Sensor_Obj *sens, float *x, float *y, float *z);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Get data from first two data properties
|
|
|
|
* @param sens Sensor object to operate on.
|
|
|
|
* @param x Pointer to write first data property value into.
|
|
|
|
* @param y Pointer to write second data property value into.
|
|
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Access function to get the first two data properties from the sensor object.
|
|
|
|
* This is used for sensor types that offer two values. Like panning.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eeze_sensor_xy_get(Eeze_Sensor_Obj *sens, float *x, float *y);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Get the data from first data property
|
|
|
|
* @param sens Sensor object to operate on.
|
|
|
|
* @param x Pointer to write first data property value into.
|
|
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Access function to get the first data property from the sensor object. This
|
|
|
|
* is used for sensor types that only offer one value. Like light or proximity.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eeze_sensor_x_get(Eeze_Sensor_Obj *sens, float *x);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Get timestamp from sensor object.
|
|
|
|
* @param sens Sensor object to operate on.
|
|
|
|
* @param timestamp Pointer to write timestamp value into.
|
|
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* Access function to get the timestamp property from the sensor object. It
|
|
|
|
* allows you to determine if the values have been updated since the last time
|
2013-04-16 05:16:55 -07:00
|
|
|
* you requested them. Timestamp is given as a floating point value in seconds.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
2013-04-16 05:16:55 -07:00
|
|
|
EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, double *timestamp);
|
2012-09-18 07:14:48 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Read out sensor data
|
|
|
|
* @param sens Sensor object to operate on.
|
|
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* This function reads sensor data from the device and fills the sensor object
|
|
|
|
* with the data. This call is synchronous and blocks until the data is read out
|
|
|
|
* and updated in the sensor object. For simple applications this is fine and
|
2012-12-13 06:17:14 -08:00
|
|
|
* the easiest way to use the API. A more efficient way is to use
|
|
|
|
* #eeze_sensor_async_read which allows the sensor readout to happen in the
|
|
|
|
* background and the application would check the timestamp of the data to
|
|
|
|
* determine how recent the data is.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Asynchronous read out sensor data
|
|
|
|
* @param sens Sensor object to operate on.
|
|
|
|
* @param user_data Data to pass to the callback function.
|
|
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
|
|
*
|
2012-12-03 06:44:33 -08:00
|
|
|
* This function reads sensor data from the device and fills the sensor object
|
|
|
|
* with the data. The read is done asynchronously and thus does not block after
|
2012-12-13 06:17:14 -08:00
|
|
|
* calling. Instead the given the application can determine how recent the
|
|
|
|
* values are from the timestamp value that can be accessed through
|
|
|
|
* #eeze_sensor_timestamp_get.
|
|
|
|
*
|
|
|
|
* This function is more efficient but needs a bit more work in the application.
|
|
|
|
* An easier way is to use the synchronous #eeze_sensor_read functions. The
|
|
|
|
* downside of it is that it blocks until the data was read out from the
|
|
|
|
* physical sensor. That might be a long time depending on the hardware and its
|
|
|
|
* interface.
|
2012-10-02 01:47:45 -07:00
|
|
|
*
|
2013-04-19 01:55:02 -07:00
|
|
|
* The extra data passed in as user_data here will be available in the user_data
|
|
|
|
* pointer of the sensor object when the ecore event arrives.
|
|
|
|
*
|
2012-09-18 07:14:48 -07:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eeze_sensor_async_read(Eeze_Sensor_Obj *sens, void *user_data);
|
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
}
|
|
|
|
#endif
|
|
|
|
/** @} */
|
|
|
|
#endif
|