summaryrefslogtreecommitdiff
path: root/legacy/eeze/src/lib/Eeze_Sensor.h
blob: 0f53f0b60148059584a522ba7ed7b05ed2189d08 (plain) (blame)
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
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
#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. 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.
 *
 * @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. 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.
 *
 * @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.
 *
 * 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.
 *
 * @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. Always use this function
 * to cleanup unused sensor objects.
 *
 * @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. 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.
 *
 * @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 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.
 *
 * @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