1 /*
2  * Copyright (C) 2017 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef _CHRE_SENSOR_TYPES_H_
18 #define _CHRE_SENSOR_TYPES_H_
19 
20 /**
21  * @file
22  * Standalone definition of sensor types, and the data structures of the sample
23  * events they emit.
24  */
25 
26 #include <stdint.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /**
33  * @file
34  * The CHRE_SENSOR_TYPE_* defines are the sensor types supported.
35  *
36  * Unless otherwise noted, each of these sensor types is based off of a
37  * corresponding sensor type in the Android API's sensors.h interface.
38  * For a given CHRE_SENSOR_TYPE_FOO, it corresponds to the SENSOR_TYPE_FOO in
39  * hardware/libhardware/include/hardware/sensors.h of the Android code base.
40  *
41  * Unless otherwise noted below, a CHRE_SENSOR_TYPE_FOO should be assumed
42  * to work the same as the Android SENSOR_TYPE_FOO, as documented in the
43  * sensors.h documentation and as detailed within the Android Compatibility
44  * Definition Document.
45  *
46  * Note that every sensor will generate CHRE_EVENT_SENSOR_SAMPLING_CHANGE
47  * events, so it is not listed with each individual sensor.
48  */
49 
50 /**
51  * Start value for all of the vendor-defined private sensors.
52  *
53  * @since v1.2
54  */
55 #define CHRE_SENSOR_TYPE_VENDOR_START  UINT8_C(192)
56 
57 /**
58  * Accelerometer.
59  *
60  * Generates: CHRE_EVENT_SENSOR_ACCELEROMETER_DATA and
61  *     optionally CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO
62  *
63  * Note that the ACCELEROMETER_DATA is always the fully calibrated data,
64  * including factory calibration and runtime calibration if available.
65  *
66  * @see chreConfigureSensorBiasEvents
67  */
68 #define CHRE_SENSOR_TYPE_ACCELEROMETER  UINT8_C(1)
69 
70 /**
71  * Instantaneous motion detection.
72  *
73  * Generates: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA
74  *
75  * This is a one-shot sensor.
76  *
77  * This does not have a direct analogy within sensors.h.  This is similar
78  * to SENSOR_TYPE_MOTION_DETECT, but this triggers instantly upon any
79  * motion, instead of waiting for a period of continuous motion.
80  */
81 #define CHRE_SENSOR_TYPE_INSTANT_MOTION_DETECT  UINT8_C(2)
82 
83 /**
84  * Stationary detection.
85  *
86  * Generates: CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA
87  *
88  * This is a one-shot sensor.
89  */
90 #define CHRE_SENSOR_TYPE_STATIONARY_DETECT  UINT8_C(3)
91 
92 /**
93  * Gyroscope.
94  *
95  * Generates: CHRE_EVENT_SENSOR_GYROSCOPE_DATA and
96  *     optionally CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO
97  *
98  * Note that the GYROSCOPE_DATA is always the fully calibrated data, including
99  * factory calibration and runtime calibration if available.
100  *
101  * @see chreConfigureSensorBiasEvents
102  */
103 #define CHRE_SENSOR_TYPE_GYROSCOPE  UINT8_C(6)
104 
105 /**
106  * Uncalibrated gyroscope.
107  *
108  * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA
109  *
110  * Note that the UNCALIBRATED_GYROSCOPE_DATA must be factory calibrated data,
111  * but not runtime calibrated.
112  */
113 #define CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE  UINT8_C(7)
114 
115 /**
116  * Magnetometer.
117  *
118  * Generates: CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA and
119  *     optionally CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO
120  *
121  * Note that the GEOMAGNETIC_FIELD_DATA is always the fully calibrated data,
122  * including factory calibration and runtime calibration if available.
123  *
124  * @see chreConfigureSensorBiasEvents
125  */
126 #define CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD  UINT8_C(8)
127 
128 /**
129  * Uncalibrated magnetometer.
130  *
131  * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA
132  *
133  * Note that the UNCALIBRATED_GEOMAGNETIC_FIELD_DATA must be factory calibrated
134  * data, but not runtime calibrated.
135  */
136 #define CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD  UINT8_C(9)
137 
138 /**
139  * Barometric pressure sensor.
140  *
141  * Generates: CHRE_EVENT_SENSOR_PRESSURE_DATA
142  */
143 #define CHRE_SENSOR_TYPE_PRESSURE  UINT8_C(10)
144 
145 /**
146  * Ambient light sensor.
147  *
148  * Generates: CHRE_EVENT_SENSOR_LIGHT_DATA
149  *
150  * This is an on-change sensor.
151  */
152 #define CHRE_SENSOR_TYPE_LIGHT  UINT8_C(12)
153 
154 /**
155  * Proximity detection.
156  *
157  * Generates: CHRE_EVENT_SENSOR_PROXIMITY_DATA
158  *
159  * This is an on-change sensor.
160  */
161 #define CHRE_SENSOR_TYPE_PROXIMITY  UINT8_C(13)
162 
163 /**
164  * Step detection.
165  *
166  * Generates: CHRE_EVENT_SENSOR_STEP_DETECT_DATA
167  *
168  * @since v1.3
169  */
170 #define CHRE_SENSOR_TYPE_STEP_DETECT  UINT8_C(23)
171 
172 /**
173  * Uncalibrated accelerometer.
174  *
175  * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA
176  *
177  * Note that the UNCALIBRATED_ACCELEROMETER_DATA must be factory calibrated
178  * data, but not runtime calibrated.
179  */
180 #define CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER  UINT8_C(55)
181 
182 /**
183  * Accelerometer temperature.
184  *
185  * Generates: CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA
186  */
187 #define CHRE_SENSOR_TYPE_ACCELEROMETER_TEMPERATURE  UINT8_C(56)
188 
189 /**
190  * Gyroscope temperature.
191  *
192  * Generates: CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA
193  */
194 #define CHRE_SENSOR_TYPE_GYROSCOPE_TEMPERATURE  UINT8_C(57)
195 
196 /**
197  * Magnetometer temperature.
198  *
199  * Generates: CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA
200  */
201 #define CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD_TEMPERATURE  UINT8_C(58)
202 
203 #if CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD_TEMPERATURE >= CHRE_SENSOR_TYPE_VENDOR_START
204 #error Too many sensor types
205 #endif
206 
207 /**
208  * Values that can be stored in the accuracy field of chreSensorDataHeader.
209  * If CHRE_SENSOR_ACCURACY_UNKNOWN is returned, then the driver did not provide
210  * accuracy information with the data. Values in the range
211  * [CHRE_SENSOR_ACCURACY_VENDOR_START, CHRE_SENSOR_ACCURACY_VENDOR_END] are
212  * reserved for vendor-specific values for vendor sensor types, and are not used
213  * by CHRE for standard sensor types.
214  *
215  * Otherwise, the values have the same meaning as defined in the Android
216  * Sensors definition:
217  * https://developer.android.com/reference/android/hardware/SensorManager
218  *
219  * @since v1.3
220  *
221  * @defgroup CHRE_SENSOR_ACCURACY
222  * @{
223  */
224 
225 #define CHRE_SENSOR_ACCURACY_UNKNOWN       UINT8_C(0)
226 #define CHRE_SENSOR_ACCURACY_UNRELIABLE    UINT8_C(1)
227 #define CHRE_SENSOR_ACCURACY_LOW           UINT8_C(2)
228 #define CHRE_SENSOR_ACCURACY_MEDIUM        UINT8_C(3)
229 #define CHRE_SENSOR_ACCURACY_HIGH          UINT8_C(4)
230 #define CHRE_SENSOR_ACCURACY_VENDOR_START  UINT8_C(192)
231 #define CHRE_SENSOR_ACCURACY_VENDOR_END    UINT8_MAX
232 
233 /** @} */
234 
235 /**
236  * Header used in every structure containing batchable data from a sensor.
237  *
238  * The typical structure for sensor data looks like:
239  *
240  *   struct chreSensorTypeData {
241  *       struct chreSensorDataHeader header;
242  *       struct chreSensorTypeSampleData {
243  *           uint32_t timestampDelta;
244  *           union {
245  *               <type> value;
246  *               <type> interpretation0;
247  *               <type> interpretation1;
248  *           };
249  *       } readings[1];
250  *   };
251  *
252  * Despite 'readings' being declared as an array of 1 element,
253  * an instance of the struct will actually have 'readings' as
254  * an array of header.readingCount elements (which may be 1).
255  * The 'timestampDelta' is in relation to the previous 'readings' (or
256  * the baseTimestamp for readings[0].  So,
257  * Timestamp for readings[0] == header.baseTimestamp +
258  *     readings[0].timestampDelta.
259  * Timestamp for readings[1] == timestamp for readings[0] +
260  *     readings[1].timestampDelta.
261  * And thus, in order to determine the timestamp for readings[N], it's
262  * necessary to process through all of the N-1 readings.  The advantage,
263  * though, is that our entire readings can span an arbitrary length of time,
264  * just as long as any two consecutive readings differ by no more than
265  * 4.295 seconds (timestampDelta, like all time in the CHRE, is in
266  * nanoseconds).
267  *
268  * If a sensor has batched readings where two consecutive readings differ by
269  * more than 4.295 seconds, the CHRE will split them across multiple
270  * instances of the struct, and send multiple events.
271  *
272  * The value from the sensor is typically expressed in a union,
273  * allowing a generic access to the data ('value'), along with
274  * differently named access giving a more natural interpretation
275  * of the data for the specific sensor types which use this
276  * structure.  This allows, for example, barometer code to
277  * reference readings[N].pressure, and an ambient light sensor
278  * to reference readings[N].light, while both use the same
279  * structure.
280  */
281 struct chreSensorDataHeader {
282     /**
283      * The base timestamp, in nanoseconds.
284      */
285     uint64_t baseTimestamp;
286 
287     /**
288      * The handle of the sensor producing this event.
289      */
290     uint32_t sensorHandle;
291 
292     /**
293      * The number elements in the 'readings' array.
294      *
295      * This must be at least 1.
296      */
297     uint16_t readingCount;
298 
299     /**
300      * The accuracy of the sensor data.
301      *
302      * @ref CHRE_SENSOR_ACCURACY
303      *
304      * @since v1.3
305      */
306     uint8_t accuracy;
307 
308     /**
309      * Reserved bytes.
310      *
311      * This must be 0.
312      */
313     uint8_t reserved;
314 };
315 
316 /**
317  * Data for a sensor which reports on three axes.
318  *
319  * This is used by CHRE_EVENT_SENSOR_ACCELEROMETER_DATA,
320  * CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO,
321  * CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA,
322  * CHRE_EVENT_SENSOR_GYROSCOPE_DATA,
323  * CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO,
324  * CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA,
325  * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA,
326  * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO, and
327  * CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA.
328  */
329 struct chreSensorThreeAxisData {
330     /**
331      * @see chreSensorDataHeader
332      */
333     struct chreSensorDataHeader header;
334     struct chreSensorThreeAxisSampleData {
335         /**
336          * @see chreSensorDataHeader
337          */
338         uint32_t timestampDelta;
339         union {
340             float values[3];
341             float v[3];
342             struct {
343                 float x;
344                 float y;
345                 float z;
346             };
347             float bias[3];
348             struct {
349                 float x_bias;
350                 float y_bias;
351                 float z_bias;
352             };
353         };
354     } readings[1];
355 };
356 
357 /**
358  * Data from a sensor where we only care about a event occurring.
359  *
360  * This is a bit unusual in that our readings have no data in addition
361  * to the timestamp.  But since we only care about the occurrence, we
362  * don't need to know anything else.
363  *
364  * Used by: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA,
365  *     CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA, and
366  *     CHRE_EVENT_SENSOR_STEP_DETECT_DATA.
367  */
368 struct chreSensorOccurrenceData {
369     struct chreSensorDataHeader header;
370     struct chreSensorOccurrenceSampleData {
371         uint32_t timestampDelta;
372         // This space intentionally left blank.
373         // Only the timestamp is meaningful here, there
374         // is no additional data.
375     } readings[1];
376 };
377 
378 /**
379  * This is used by CHRE_EVENT_SENSOR_LIGHT_DATA,
380  * CHRE_EVENT_SENSOR_PRESSURE_DATA,
381  * CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA,
382  * CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA, and
383  * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA.
384  */
385 struct chreSensorFloatData {
386     struct chreSensorDataHeader header;
387     struct chreSensorFloatSampleData {
388         uint32_t timestampDelta;
389         union {
390             float value;
391             float light;        //!< Unit: lux
392             float pressure;     //!< Unit: hectopascals (hPa)
393             float temperature;  //!< Unit: degrees Celsius
394         };
395     } readings[1];
396 };
397 
398 /**
399  * CHRE_EVENT_SENSOR_PROXIMITY_DATA.
400  */
401 struct chreSensorByteData {
402     struct chreSensorDataHeader header;
403     struct chreSensorByteSampleData {
404         uint32_t timestampDelta;
405         union {
406             uint8_t value;
407             struct {
408                 uint8_t isNear : 1;
409                 //! @deprecated As of v1.2, this field is deprecated and must
410                 //! always be set to 0
411                 uint8_t invalid : 1;
412                 uint8_t padding0 : 6;
413             };
414         };
415     } readings[1];
416 };
417 
418 
419 #ifdef __cplusplus
420 }
421 #endif
422 
423 #endif  /* _CHRE_SENSOR_TYPES_H_ */
424