summaryrefslogtreecommitdiff
path: root/legacy/eeze/src/lib/Eeze_Sensor.h
blob: ffc6266e88ca40eb5486895c0684cd4d85d6b6b7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
#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
 *
 * Eeze sensor functions allow you to gather sensor information from different sensor sources
 * available on the hardware. It supports a plugin architecture to support different hardware
 * platforms and devices. These plugins can be loaded at runtime to allow support for a specific
 * set of hardware or platform.
 *
 * 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 developing.
 *
 * @since 1.8
 *
 * @addtogroup sensor Sensor
 * @{
 */

/**
 * @enum Eeze_Sensor_Type
 * @since 1.8
 *
 * 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.
 */
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
 *
 * @since 1.8
 */
Eina_Bool            eeze_sensor_init(void);

/**
 * @brief Clean up and shutdown the Eeze sensor subsystem.
 *
 * @since 1.8
 */
void                 eeze_sensor_shutdown(void);

#ifdef __cplusplus
}
#endif
/** @} */
#endif