302 lines
10 KiB
C
302 lines
10 KiB
C
#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
|
|
* @brief Sensor information subsystem
|
|
*
|
|
* Eeze sensor functions allow you to gather sensor information from different
|
|
* sensor sources available on your hardware. It supports a plugin architecture
|
|
* to support different hardware platforms and devices. These plugins can be
|
|
* loaded at runtime.
|
|
*
|
|
* Right now we have support for the Tizen sensor framework as well as a simple
|
|
* 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.
|
|
*
|
|
* @since 1.8
|
|
*
|
|
* @addtogroup sensor Sensor
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @enum Eeze_Sensor_Type
|
|
*
|
|
* 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
|
|
* facedown or doubletap.
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
typedef enum
|
|
{
|
|
EEZE_SENSOR_TYPE_ACCELEROMETER, /**< Accelerometer sensor */
|
|
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 */
|
|
EEZE_SENSOR_TYPE_MOTION_FACEDOWN, /**< Facedown motion sensor */
|
|
/* 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;
|
|
|
|
/**
|
|
* @defgroup Sensor_Events Available eeze sensor events
|
|
* @brief Sensor events that are emitted from the library as ecore events
|
|
*
|
|
* Event types used to register ecore_event_handler on. These events are used
|
|
* for #eeze_sensor_async_read to deliver read out data. It is also used for
|
|
* generated events like facedown or shake.
|
|
*
|
|
* @since 1.8
|
|
* @{
|
|
*/
|
|
EAPI int EEZE_SENSOR_EVENT_ACCELEROMETER;
|
|
EAPI int EEZE_SENSOR_EVENT_MAGNETIC;
|
|
EAPI int EEZE_SENSOR_EVENT_ORIENTATION;
|
|
EAPI int EEZE_SENSOR_EVENT_GYROSCOPE;
|
|
EAPI int EEZE_SENSOR_EVENT_LIGHT;
|
|
EAPI int EEZE_SENSOR_EVENT_PROXIMITY;
|
|
EAPI int EEZE_SENSOR_EVENT_SNAP;
|
|
EAPI int EEZE_SENSOR_EVENT_SHAKE;
|
|
EAPI int EEZE_SENSOR_EVENT_DOUBLETAP;
|
|
EAPI int EEZE_SENSOR_EVENT_PANNING;
|
|
EAPI int EEZE_SENSOR_EVENT_FACEDOWN;
|
|
EAPI int EEZE_SENSOR_EVENT_BAROMETER;
|
|
EAPI int EEZE_SENSOR_EVENT_TEMPERATURE;
|
|
/**@}*/
|
|
|
|
/**
|
|
* @typedef Eeze_Sensor_Obj;
|
|
*
|
|
* 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
|
|
* see when the data has been updated. The timestamp is given in microseconds.
|
|
*
|
|
* 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.
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
typedef struct _Eeze_Sensor_Obj
|
|
{
|
|
unsigned int type; /**< Sensor type see #Eeze_Sensor_Type */
|
|
int accuracy; /**< Accuracy of the sensor value */
|
|
float data[3]; /**< Sensor data depending on the sensor type */
|
|
unsigned long long timestamp; /**< Timestamp of data read */
|
|
Eina_Bool continuous_flow; /**< FUTURE USE: Continuous flow of sensor read out */
|
|
} 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.
|
|
*
|
|
* 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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* Free an sensor object when it is no longer needed.
|
|
*
|
|
* @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.
|
|
* @param accuracy Pointer to write accuracy value into.
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
*
|
|
* Access function to get the accuracy property from the sensor object. The
|
|
* accuracy value can have the following values and meaning:
|
|
* -1 Undefined accuracy
|
|
* 0 Bad accurancy
|
|
* 1 Normal accuracy
|
|
* 2 Good accuracy
|
|
* 3 Very good accuracy
|
|
*
|
|
* @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
|
|
*
|
|
* 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.
|
|
*
|
|
* @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
|
|
*
|
|
* 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.
|
|
*
|
|
* @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
|
|
*
|
|
* 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.
|
|
*
|
|
* @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
|
|
*
|
|
* 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
|
|
* you requested them.
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long long *timestamp);
|
|
|
|
/**
|
|
* @brief Read out sensor data
|
|
* @param sens Sensor object to operate on.
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
*
|
|
* 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
|
|
* the easiest way to use the API.
|
|
*
|
|
* @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
|
|
*
|
|
* 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
|
|
* calling. Instead the given callback function is called once the read is
|
|
* finished and the object filled.
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
EAPI Eina_Bool eeze_sensor_async_read(Eeze_Sensor_Obj *sens, void *user_data);
|
|
|
|
/**
|
|
* @brief Fetch the sensor object by type from the sensor object list
|
|
* @param type Sensor type to fetch from the list of sensor objects.
|
|
* @return The sensor object matching the given type
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
EAPI Eeze_Sensor_Obj *eeze_sensor_obj_get(Eeze_Sensor_Type type);
|
|
|
|
/**
|
|
* @brief Initialize the Eeze sensor subsystem.
|
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
|
*
|
|
* This function must be called before using any of the Eeze_Sensor
|
|
* functionality to make sure the subsystem is setup correctly for usage. If
|
|
* you already call #eeze_init in your program this is already been take care
|
|
* of and there is no need to call this to initialize this subsystem manually.
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
EAPI Eina_Bool eeze_sensor_init(void);
|
|
|
|
/**
|
|
* @brief Clean up and shutdown the Eeze sensor subsystem.
|
|
*
|
|
* This function must be called when now longer using Eeze_Sensor to allow the
|
|
* subsystem to shutdown cleanly. If you already called #eeze_shutdown this is
|
|
* already been taken care of and there is no need to call this to shutdown this
|
|
* subsystem manually.
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
EAPI void eeze_sensor_shutdown(void);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
/** @} */
|
|
#endif
|