sensor.h 37 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129
  1. /*
  2. * Copyright (c) 2006-2018, RT-Thread Development Team
  3. *
  4. * SPDX-License-Identifier: Apache-2.0
  5. *
  6. * Change Logs:
  7. * Date Author Notes
  8. * 2014-08-03 Bernard the first version
  9. */
  10. /* Modified from: https://github.com/android/platform_hardware_libhardware/blob/master/include/hardware/sensors.h */
  11. /*
  12. * Copyright (C) 2012 The Android Open Source Project
  13. *
  14. * Licensed under the Apache License, Version 2.0 (the "License");
  15. * you may not use this file except in compliance with the License.
  16. * You may obtain a copy of the License at
  17. *
  18. * http://www.apache.org/licenses/LICENSE-2.0
  19. *
  20. * Unless required by applicable law or agreed to in writing, software
  21. * distributed under the License is distributed on an "AS IS" BASIS,
  22. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  23. * See the License for the specific language governing permissions and
  24. * limitations under the License.
  25. */
  26. #ifndef SENSORS_H__
  27. #define SENSORS_H__
  28. #include <rtdevice.h>
  29. #include <stdint.h>
  30. #ifdef __CC_ARM /* skip warning in armcc */
  31. #pragma anon_unions
  32. #endif
  33. /**
  34. * Handles must be higher than SENSORS_HANDLE_BASE and must be unique.
  35. * A Handle identifies a given sensors. The handle is used to activate
  36. * and/or deactivate sensors.
  37. * In this version of the API there can only be 256 handles.
  38. */
  39. #define SENSORS_HANDLE_BASE 0
  40. #define SENSORS_HANDLE_BITS 8
  41. #define SENSORS_HANDLE_COUNT (1<<SENSORS_HANDLE_BITS)
  42. /*
  43. * flags for (*batch)()
  44. * Availability: SENSORS_DEVICE_API_VERSION_1_0
  45. * see (*batch)() documentation for details
  46. */
  47. enum
  48. {
  49. SENSORS_BATCH_DRY_RUN = 0x00000001,
  50. SENSORS_BATCH_WAKE_UPON_FIFO_FULL = 0x00000002
  51. };
  52. /*
  53. * what field for meta_data_event_t
  54. */
  55. enum
  56. {
  57. /* a previous flush operation has completed */
  58. META_DATA_FLUSH_COMPLETE = 1,
  59. META_DATA_VERSION /* always last, leave auto-assigned */
  60. };
  61. /**
  62. * Definition of the axis used by the sensor HAL API
  63. *
  64. * This API is relative to the screen of the device in its default orientation,
  65. * that is, if the device can be used in portrait or landscape, this API
  66. * is only relative to the NATURAL orientation of the screen. In other words,
  67. * the axis are not swapped when the device's screen orientation changes.
  68. * Higher level services /may/ perform this transformation.
  69. *
  70. * x<0 x>0
  71. * ^
  72. * |
  73. * +-----------+--> y>0
  74. * | |
  75. * | |
  76. * | |
  77. * | | / z<0
  78. * | | /
  79. * | | /
  80. * O-----------+/
  81. * |[] [ ] []/
  82. * +----------/+ y<0
  83. * /
  84. * /
  85. * |/ z>0 (toward the sky)
  86. *
  87. * O: Origin (x=0,y=0,z=0)
  88. *
  89. */
  90. /*
  91. * Interaction with suspend mode
  92. *
  93. * Unless otherwise noted, an enabled sensor shall not prevent the
  94. * SoC to go into suspend mode. It is the responsibility of applications
  95. * to keep a partial wake-lock should they wish to receive sensor
  96. * events while the screen is off. While in suspend mode, and unless
  97. * otherwise noted (batch mode, sensor particularities, ...), enabled sensors'
  98. * events are lost.
  99. *
  100. * Note that conceptually, the sensor itself is not de-activated while in
  101. * suspend mode -- it's just that the data it returns are lost. As soon as
  102. * the SoC gets out of suspend mode, operations resume as usual. Of course,
  103. * in practice sensors shall be disabled while in suspend mode to
  104. * save power, unless batch mode is active, in which case they must
  105. * continue fill their internal FIFO (see the documentation of batch() to
  106. * learn how suspend interacts with batch mode).
  107. *
  108. * In batch mode, and only when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is
  109. * set and supported, the specified sensor must be able to wake-up the SoC and
  110. * be able to buffer at least 10 seconds worth of the requested sensor events.
  111. *
  112. * There are notable exceptions to this behavior, which are sensor-dependent
  113. * (see sensor types definitions below)
  114. *
  115. *
  116. * The sensor type documentation below specifies the wake-up behavior of
  117. * each sensor:
  118. * wake-up: yes this sensor must wake-up the SoC to deliver events
  119. * wake-up: no this sensor shall not wake-up the SoC, events are dropped
  120. *
  121. */
  122. /*
  123. * Sensor type
  124. *
  125. * Each sensor has a type which defines what this sensor measures and how
  126. * measures are reported. All types are defined below.
  127. *
  128. * Device manufacturers (OEMs) can define their own sensor types, for
  129. * their private use by applications or services provided by them. Such
  130. * sensor types are specific to an OEM and can't be exposed in the SDK.
  131. * These types must start at SENSOR_TYPE_DEVICE_PRIVATE_BASE.
  132. */
  133. /*
  134. * Base for device manufacturers private sensor types.
  135. * These sensor types can't be exposed in the SDK.
  136. */
  137. #define SENSOR_TYPE_DEVICE_PRIVATE_BASE 0x10000
  138. /*
  139. * Sensor fusion and virtual sensors
  140. *
  141. * Many sensor types are or can be implemented as virtual sensors from
  142. * physical sensors on the device. For instance the rotation vector sensor,
  143. * orientation sensor, step-detector, step-counter, etc...
  144. *
  145. * From the point of view of this API these virtual sensors MUST appear as
  146. * real, individual sensors. It is the responsibility of the driver and HAL
  147. * to make sure this is the case.
  148. *
  149. * In particular, all sensors must be able to function concurrently.
  150. * For example, if defining both an accelerometer and a step counter,
  151. * then both must be able to work concurrently.
  152. */
  153. /*
  154. * Trigger modes
  155. *
  156. * Sensors can report events in different ways called trigger modes,
  157. * each sensor type has one and only one trigger mode associated to it.
  158. * Currently there are four trigger modes defined:
  159. *
  160. * continuous: events are reported at a constant rate defined by setDelay().
  161. * eg: accelerometers, gyroscopes.
  162. * on-change: events are reported only if the sensor's value has changed.
  163. * setDelay() is used to set a lower limit to the reporting
  164. * period (minimum time between two events).
  165. * The HAL must return an event immediately when an on-change
  166. * sensor is activated.
  167. * eg: proximity, light sensors
  168. * one-shot: upon detection of an event, the sensor deactivates itself and
  169. * then sends a single event. Order matters to avoid race
  170. * conditions. No other event is sent until the sensor get
  171. * reactivated. setDelay() is ignored.
  172. * eg: significant motion sensor
  173. * special: see details in the sensor type specification below
  174. *
  175. */
  176. /*
  177. * SENSOR_TYPE_META_DATA
  178. * trigger-mode: n/a
  179. * wake-up sensor: n/a
  180. *
  181. * NO SENSOR OF THAT TYPE MUST BE RETURNED (*get_sensors_list)()
  182. *
  183. * SENSOR_TYPE_META_DATA is a special token used to populate the
  184. * sensors_meta_data_event structure. It doesn't correspond to a physical
  185. * sensor. sensors_meta_data_event are special, they exist only inside
  186. * the HAL and are generated spontaneously, as opposed to be related to
  187. * a physical sensor.
  188. *
  189. * sensors_meta_data_event_t.version must be META_DATA_VERSION
  190. * sensors_meta_data_event_t.sensor must be 0
  191. * sensors_meta_data_event_t.type must be SENSOR_TYPE_META_DATA
  192. * sensors_meta_data_event_t.reserved must be 0
  193. * sensors_meta_data_event_t.timestamp must be 0
  194. *
  195. * The payload is a meta_data_event_t, where:
  196. * meta_data_event_t.what can take the following values:
  197. *
  198. * META_DATA_FLUSH_COMPLETE
  199. * This event indicates that a previous (*flush)() call has completed for the sensor
  200. * handle specified in meta_data_event_t.sensor.
  201. * see (*flush)() for more details
  202. *
  203. * All other values for meta_data_event_t.what are reserved and
  204. * must not be used.
  205. *
  206. */
  207. #define SENSOR_TYPE_META_DATA (0)
  208. /*
  209. * SENSOR_TYPE_ACCELEROMETER
  210. * trigger-mode: continuous
  211. * wake-up sensor: no
  212. *
  213. * All values are in SI units (m/s^2) and measure the acceleration of the
  214. * device minus the force of gravity.
  215. *
  216. * Acceleration sensors return sensor events for all 3 axes at a constant
  217. * rate defined by setDelay().
  218. *
  219. * x: Acceleration on the x-axis
  220. * y: Acceleration on the y-axis
  221. * z: Acceleration on the z-axis
  222. *
  223. * Note that the readings from the accelerometer include the acceleration
  224. * due to gravity (which is opposite to the direction of the gravity vector).
  225. *
  226. * Examples:
  227. * The norm of <x, y, z> should be close to 0 when in free fall.
  228. *
  229. * When the device lies flat on a table and is pushed on its left side
  230. * toward the right, the x acceleration value is positive.
  231. *
  232. * When the device lies flat on a table, the acceleration value is +9.81,
  233. * which correspond to the acceleration of the device (0 m/s^2) minus the
  234. * force of gravity (-9.81 m/s^2).
  235. *
  236. * When the device lies flat on a table and is pushed toward the sky, the
  237. * acceleration value is greater than +9.81, which correspond to the
  238. * acceleration of the device (+A m/s^2) minus the force of
  239. * gravity (-9.81 m/s^2).
  240. */
  241. #define SENSOR_TYPE_ACCELEROMETER (1)
  242. /*
  243. * SENSOR_TYPE_GEOMAGNETIC_FIELD
  244. * trigger-mode: continuous
  245. * wake-up sensor: no
  246. *
  247. * All values are in micro-Tesla (uT) and measure the geomagnetic
  248. * field in the X, Y and Z axis.
  249. *
  250. * Returned values include calibration mechanisms such that the vector is
  251. * aligned with the magnetic declination and heading of the earth's
  252. * geomagnetic field.
  253. *
  254. * Magnetic Field sensors return sensor events for all 3 axes at a constant
  255. * rate defined by setDelay().
  256. */
  257. #define SENSOR_TYPE_GEOMAGNETIC_FIELD (2)
  258. #define SENSOR_TYPE_MAGNETIC_FIELD SENSOR_TYPE_GEOMAGNETIC_FIELD
  259. /*
  260. * SENSOR_TYPE_ORIENTATION
  261. * trigger-mode: continuous
  262. * wake-up sensor: no
  263. *
  264. * All values are angles in degrees.
  265. *
  266. * Orientation sensors return sensor events for all 3 axes at a constant
  267. * rate defined by setDelay().
  268. *
  269. * azimuth: angle between the magnetic north direction and the Y axis, around
  270. * the Z axis (0<=azimuth<360).
  271. * 0=North, 90=East, 180=South, 270=West
  272. *
  273. * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when
  274. * the z-axis moves toward the y-axis.
  275. *
  276. * roll: Rotation around Y axis (-90<=roll<=90), with positive values when
  277. * the x-axis moves towards the z-axis.
  278. *
  279. * Note: For historical reasons the roll angle is positive in the clockwise
  280. * direction (mathematically speaking, it should be positive in the
  281. * counter-clockwise direction):
  282. *
  283. * Z
  284. * ^
  285. * (+roll) .--> |
  286. * / |
  287. * | | roll: rotation around Y axis
  288. * X <-------(.)
  289. * Y
  290. * note that +Y == -roll
  291. *
  292. *
  293. *
  294. * Note: This definition is different from yaw, pitch and roll used in aviation
  295. * where the X axis is along the long side of the plane (tail to nose).
  296. */
  297. #define SENSOR_TYPE_ORIENTATION (3)
  298. /*
  299. * SENSOR_TYPE_GYROSCOPE
  300. * trigger-mode: continuous
  301. * wake-up sensor: no
  302. *
  303. * All values are in radians/second and measure the rate of rotation
  304. * around the X, Y and Z axis. The coordinate system is the same as is
  305. * used for the acceleration sensor. Rotation is positive in the
  306. * counter-clockwise direction (right-hand rule). That is, an observer
  307. * looking from some positive location on the x, y or z axis at a device
  308. * positioned on the origin would report positive rotation if the device
  309. * appeared to be rotating counter clockwise. Note that this is the
  310. * standard mathematical definition of positive rotation and does not agree
  311. * with the definition of roll given earlier.
  312. * The range should at least be 17.45 rad/s (ie: ~1000 deg/s).
  313. *
  314. * automatic gyro-drift compensation is allowed but not required.
  315. */
  316. #define SENSOR_TYPE_GYROSCOPE (4)
  317. /*
  318. * SENSOR_TYPE_LIGHT
  319. * trigger-mode: on-change
  320. * wake-up sensor: no
  321. *
  322. * The light sensor value is returned in SI lux units.
  323. */
  324. #define SENSOR_TYPE_LIGHT (5)
  325. /*
  326. * SENSOR_TYPE_PRESSURE
  327. * trigger-mode: continuous
  328. * wake-up sensor: no
  329. *
  330. * The pressure sensor return the athmospheric pressure in hectopascal (hPa)
  331. */
  332. #define SENSOR_TYPE_PRESSURE (6)
  333. /* SENSOR_TYPE_TEMPERATURE is deprecated in the HAL */
  334. #define SENSOR_TYPE_TEMPERATURE (7)
  335. /*
  336. * SENSOR_TYPE_PROXIMITY
  337. * trigger-mode: on-change
  338. * wake-up sensor: yes
  339. *
  340. * The distance value is measured in centimeters. Note that some proximity
  341. * sensors only support a binary "close" or "far" measurement. In this case,
  342. * the sensor should report its maxRange value in the "far" state and a value
  343. * less than maxRange in the "near" state.
  344. */
  345. #define SENSOR_TYPE_PROXIMITY (8)
  346. /*
  347. * SENSOR_TYPE_GRAVITY
  348. * trigger-mode: continuous
  349. * wake-up sensor: no
  350. *
  351. * A gravity output indicates the direction of and magnitude of gravity in
  352. * the devices's coordinates. On Earth, the magnitude is 9.8 m/s^2.
  353. * Units are m/s^2. The coordinate system is the same as is used for the
  354. * acceleration sensor. When the device is at rest, the output of the
  355. * gravity sensor should be identical to that of the accelerometer.
  356. */
  357. #define SENSOR_TYPE_GRAVITY (9)
  358. /*
  359. * SENSOR_TYPE_LINEAR_ACCELERATION
  360. * trigger-mode: continuous
  361. * wake-up sensor: no
  362. *
  363. * Indicates the linear acceleration of the device in device coordinates,
  364. * not including gravity.
  365. *
  366. * The output is conceptually:
  367. * output of TYPE_ACCELERATION - output of TYPE_GRAVITY
  368. *
  369. * Readings on all axes should be close to 0 when device lies on a table.
  370. * Units are m/s^2.
  371. * The coordinate system is the same as is used for the acceleration sensor.
  372. */
  373. #define SENSOR_TYPE_LINEAR_ACCELERATION (10)
  374. /*
  375. * SENSOR_TYPE_ROTATION_VECTOR
  376. * trigger-mode: continuous
  377. * wake-up sensor: no
  378. *
  379. * The rotation vector symbolizes the orientation of the device relative to the
  380. * East-North-Up coordinates frame. It is usually obtained by integration of
  381. * accelerometer, gyroscope and magnetometer readings.
  382. *
  383. * The East-North-Up coordinate system is defined as a direct orthonormal basis
  384. * where:
  385. * - X points east and is tangential to the ground.
  386. * - Y points north and is tangential to the ground.
  387. * - Z points towards the sky and is perpendicular to the ground.
  388. *
  389. * The orientation of the phone is represented by the rotation necessary to
  390. * align the East-North-Up coordinates with the phone's coordinates. That is,
  391. * applying the rotation to the world frame (X,Y,Z) would align them with the
  392. * phone coordinates (x,y,z).
  393. *
  394. * The rotation can be seen as rotating the phone by an angle theta around
  395. * an axis rot_axis to go from the reference (East-North-Up aligned) device
  396. * orientation to the current device orientation.
  397. *
  398. * The rotation is encoded as the 4 (reordered) components of a unit quaternion:
  399. * sensors_event_t.data[0] = rot_axis.x*sin(theta/2)
  400. * sensors_event_t.data[1] = rot_axis.y*sin(theta/2)
  401. * sensors_event_t.data[2] = rot_axis.z*sin(theta/2)
  402. * sensors_event_t.data[3] = cos(theta/2)
  403. * where
  404. * - rot_axis.x,y,z are the North-East-Up coordinates of a unit length vector
  405. * representing the rotation axis
  406. * - theta is the rotation angle
  407. *
  408. * The quaternion must be of norm 1 (it is a unit quaternion). Failure to ensure
  409. * this will cause erratic client behaviour.
  410. *
  411. * In addition, this sensor reports an estimated heading accuracy.
  412. * sensors_event_t.data[4] = estimated_accuracy (in radians)
  413. * The heading error must be less than estimated_accuracy 95% of the time
  414. *
  415. * This sensor must use a gyroscope and an accelerometer as main orientation
  416. * change input.
  417. *
  418. * This sensor can also include magnetometer input to make up for gyro drift,
  419. * but it cannot be implemented using only a magnetometer.
  420. */
  421. #define SENSOR_TYPE_ROTATION_VECTOR (11)
  422. /*
  423. * SENSOR_TYPE_RELATIVE_HUMIDITY
  424. * trigger-mode: on-change
  425. * wake-up sensor: no
  426. *
  427. * A relative humidity sensor measures relative ambient air humidity and
  428. * returns a value in percent.
  429. */
  430. #define SENSOR_TYPE_RELATIVE_HUMIDITY (12)
  431. /*
  432. * SENSOR_TYPE_AMBIENT_TEMPERATURE
  433. * trigger-mode: on-change
  434. * wake-up sensor: no
  435. *
  436. * The ambient (room) temperature in degree Celsius.
  437. */
  438. #define SENSOR_TYPE_AMBIENT_TEMPERATURE (13)
  439. /*
  440. * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED
  441. * trigger-mode: continuous
  442. * wake-up sensor: no
  443. *
  444. * Similar to SENSOR_TYPE_MAGNETIC_FIELD, but the hard iron calibration is
  445. * reported separately instead of being included in the measurement.
  446. * Factory calibration and temperature compensation should still be applied to
  447. * the "uncalibrated" measurement.
  448. * Separating away the hard iron calibration estimation allows the system to
  449. * better recover from bad hard iron estimation.
  450. *
  451. * All values are in micro-Tesla (uT) and measure the ambient magnetic
  452. * field in the X, Y and Z axis. Assumptions that the the magnetic field
  453. * is due to the Earth's poles should be avoided.
  454. *
  455. * The uncalibrated_magnetic event contains
  456. * - 3 fields for uncalibrated measurement: x_uncalib, y_uncalib, z_uncalib.
  457. * Each is a component of the measured magnetic field, with soft iron
  458. * and temperature compensation applied, but not hard iron calibration.
  459. * These values should be continuous (no re-calibration should cause a jump).
  460. * - 3 fields for hard iron bias estimates: x_bias, y_bias, z_bias.
  461. * Each field is a component of the estimated hard iron calibration.
  462. * They represent the offsets to apply to the calibrated readings to obtain
  463. * uncalibrated readings (x_uncalib ~= x_calibrated + x_bias)
  464. * These values are expected to jump as soon as the estimate of the hard iron
  465. * changes, and they should be stable the rest of the time.
  466. *
  467. * If this sensor is present, then the corresponding
  468. * SENSOR_TYPE_MAGNETIC_FIELD must be present and both must return the
  469. * same sensor_t::name and sensor_t::vendor.
  470. *
  471. * Minimum filtering should be applied to this sensor. In particular, low pass
  472. * filters should be avoided.
  473. *
  474. * See SENSOR_TYPE_MAGNETIC_FIELD for more information
  475. */
  476. #define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED (14)
  477. /*
  478. * SENSOR_TYPE_GAME_ROTATION_VECTOR
  479. * trigger-mode: continuous
  480. * wake-up sensor: no
  481. *
  482. * Similar to SENSOR_TYPE_ROTATION_VECTOR, but not using the geomagnetic
  483. * field. Therefore the Y axis doesn't point north, but instead to some other
  484. * reference. That reference is allowed to drift by the same order of
  485. * magnitude than the gyroscope drift around the Z axis.
  486. *
  487. * This sensor does not report an estimated heading accuracy:
  488. * sensors_event_t.data[4] is reserved and should be set to 0
  489. *
  490. * In the ideal case, a phone rotated and returning to the same real-world
  491. * orientation should report the same game rotation vector
  492. * (without using the earth's geomagnetic field).
  493. *
  494. * This sensor must be based on a gyroscope. It cannot be implemented using
  495. * a magnetometer.
  496. *
  497. * see SENSOR_TYPE_ROTATION_VECTOR for more details
  498. */
  499. #define SENSOR_TYPE_GAME_ROTATION_VECTOR (15)
  500. /*
  501. * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED
  502. * trigger-mode: continuous
  503. * wake-up sensor: no
  504. *
  505. * All values are in radians/second and measure the rate of rotation
  506. * around the X, Y and Z axis. An estimation of the drift on each axis is
  507. * reported as well.
  508. *
  509. * No gyro-drift compensation shall be performed.
  510. * Factory calibration and temperature compensation should still be applied
  511. * to the rate of rotation (angular speeds).
  512. *
  513. * The coordinate system is the same as is
  514. * used for the acceleration sensor. Rotation is positive in the
  515. * counter-clockwise direction (right-hand rule). That is, an observer
  516. * looking from some positive location on the x, y or z axis at a device
  517. * positioned on the origin would report positive rotation if the device
  518. * appeared to be rotating counter clockwise. Note that this is the
  519. * standard mathematical definition of positive rotation and does not agree
  520. * with the definition of roll given earlier.
  521. * The range should at least be 17.45 rad/s (ie: ~1000 deg/s).
  522. *
  523. * Content of an uncalibrated_gyro event: (units are rad/sec)
  524. * x_uncalib : angular speed (w/o drift compensation) around the X axis
  525. * y_uncalib : angular speed (w/o drift compensation) around the Y axis
  526. * z_uncalib : angular speed (w/o drift compensation) around the Z axis
  527. * x_bias : estimated drift around X axis in rad/s
  528. * y_bias : estimated drift around Y axis in rad/s
  529. * z_bias : estimated drift around Z axis in rad/s
  530. *
  531. * IMPLEMENTATION NOTES:
  532. *
  533. * If the implementation is not able to estimate the drift, then this
  534. * sensor MUST NOT be reported by this HAL. Instead, the regular
  535. * SENSOR_TYPE_GYROSCOPE is used without drift compensation.
  536. *
  537. * If this sensor is present, then the corresponding
  538. * SENSOR_TYPE_GYROSCOPE must be present and both must return the
  539. * same sensor_t::name and sensor_t::vendor.
  540. */
  541. #define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED (16)
  542. /*
  543. * SENSOR_TYPE_SIGNIFICANT_MOTION
  544. * trigger-mode: one-shot
  545. * wake-up sensor: yes
  546. *
  547. * A sensor of this type triggers an event each time significant motion
  548. * is detected and automatically disables itself.
  549. * The only allowed value to return is 1.0.
  550. *
  551. * A significant motion is a motion that might lead to a change in the user
  552. * location.
  553. * Examples of such motions are:
  554. * walking, biking, sitting in a moving car, coach or train.
  555. * Examples of situations that should not trigger significant motion:
  556. * - phone in pocket and person is not moving
  557. * - phone is on a table, even if the table shakes a bit due to nearby traffic
  558. * or washing machine
  559. *
  560. * A note on false positive / false negative / power consumption tradeoff
  561. * - The goal of this sensor is to save power.
  562. * - Triggering an event when the user is not moving (false positive) is costly
  563. * in terms of power, so it should be avoided.
  564. * - Not triggering an event when the user is moving (false negative) is
  565. * acceptable as long as it is not done repeatedly. If the user has been
  566. * walking for 10 seconds, not triggering an event within those 10 seconds
  567. * is not acceptable.
  568. *
  569. * IMPORTANT NOTE: this sensor type is very different from other types
  570. * in that it must work when the screen is off without the need of
  571. * holding a partial wake-lock and MUST allow the SoC to go into suspend.
  572. * When significant motion is detected, the sensor must awaken the SoC and
  573. * the event be reported.
  574. *
  575. * If a particular hardware cannot support this mode of operation then this
  576. * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable
  577. * to "emulate" this sensor in the HAL.
  578. *
  579. * The whole point of this sensor type is to save power by keeping the
  580. * SoC in suspend mode when the device is at rest.
  581. *
  582. * When the sensor is not activated, it must also be deactivated in the
  583. * hardware: it must not wake up the SoC anymore, even in case of
  584. * significant motion.
  585. *
  586. * setDelay() has no effect and is ignored.
  587. * Once a "significant motion" event is returned, a sensor of this type
  588. * must disables itself automatically, as if activate(..., 0) had been called.
  589. */
  590. #define SENSOR_TYPE_SIGNIFICANT_MOTION (17)
  591. /*
  592. * SENSOR_TYPE_STEP_DETECTOR
  593. * trigger-mode: special
  594. * wake-up sensor: no
  595. *
  596. * A sensor of this type triggers an event each time a step is taken
  597. * by the user. The only allowed value to return is 1.0 and an event is
  598. * generated for each step. Like with any other event, the timestamp
  599. * indicates when the event (here the step) occurred, this corresponds to when
  600. * the foot hit the ground, generating a high variation in acceleration.
  601. *
  602. * While this sensor operates, it shall not disrupt any other sensors, in
  603. * particular, but not limited to, the accelerometer; which might very well
  604. * be in use as well.
  605. *
  606. * This sensor must be low power. That is, if the step detection cannot be
  607. * done in hardware, this sensor should not be defined. Also, when the
  608. * step detector is activated and the accelerometer is not, only steps should
  609. * trigger interrupts (not accelerometer data).
  610. *
  611. * setDelay() has no impact on this sensor type
  612. */
  613. #define SENSOR_TYPE_STEP_DETECTOR (18)
  614. /*
  615. * SENSOR_TYPE_STEP_COUNTER
  616. * trigger-mode: on-change
  617. * wake-up sensor: no
  618. *
  619. * A sensor of this type returns the number of steps taken by the user since
  620. * the last reboot while activated. The value is returned as a uint64_t and is
  621. * reset to zero only on a system / android reboot.
  622. *
  623. * The timestamp of the event is set to the time when the first step
  624. * for that event was taken.
  625. * See SENSOR_TYPE_STEP_DETECTOR for the signification of the time of a step.
  626. *
  627. * The minimum size of the hardware's internal counter shall be 16 bits
  628. * (this restriction is here to avoid too frequent wake-ups when the
  629. * delay is very large).
  630. *
  631. * IMPORTANT NOTE: this sensor type is different from other types
  632. * in that it must work when the screen is off without the need of
  633. * holding a partial wake-lock and MUST allow the SoC to go into suspend.
  634. * Unlike other sensors, while in suspend mode this sensor must stay active,
  635. * no events are reported during that time but, steps continue to be
  636. * accounted for; an event will be reported as soon as the SoC resumes if
  637. * the timeout has expired.
  638. *
  639. * In other words, when the screen is off and the device allowed to
  640. * go into suspend mode, we don't want to be woken up, regardless of the
  641. * setDelay() value, but the steps shall continue to be counted.
  642. *
  643. * The driver must however ensure that the internal step count never
  644. * overflows. It is allowed in this situation to wake the SoC up so the
  645. * driver can do the counter maintenance.
  646. *
  647. * While this sensor operates, it shall not disrupt any other sensors, in
  648. * particular, but not limited to, the accelerometer; which might very well
  649. * be in use as well.
  650. *
  651. * If a particular hardware cannot support these modes of operation then this
  652. * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable
  653. * to "emulate" this sensor in the HAL.
  654. *
  655. * This sensor must be low power. That is, if the step detection cannot be
  656. * done in hardware, this sensor should not be defined. Also, when the
  657. * step counter is activated and the accelerometer is not, only steps should
  658. * trigger interrupts (not accelerometer data).
  659. *
  660. * The whole point of this sensor type is to save power by keeping the
  661. * SoC in suspend mode when the device is at rest.
  662. */
  663. #define SENSOR_TYPE_STEP_COUNTER (19)
  664. /*
  665. * SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR
  666. * trigger-mode: continuous
  667. * wake-up sensor: no
  668. *
  669. * Similar to SENSOR_TYPE_ROTATION_VECTOR, but using a magnetometer instead
  670. * of using a gyroscope.
  671. *
  672. * This sensor must be based on a magnetometer. It cannot be implemented using
  673. * a gyroscope, and gyroscope input cannot be used by this sensor, as the
  674. * goal of this sensor is to be low power.
  675. * The accelerometer can be (and usually is) used.
  676. *
  677. * Just like SENSOR_TYPE_ROTATION_VECTOR, this sensor reports an estimated
  678. * heading accuracy:
  679. * sensors_event_t.data[4] = estimated_accuracy (in radians)
  680. * The heading error must be less than estimated_accuracy 95% of the time
  681. *
  682. * see SENSOR_TYPE_ROTATION_VECTOR for more details
  683. */
  684. #define SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR (20)
  685. /**
  686. * Values returned by the accelerometer in various locations in the universe.
  687. * all values are in SI units (m/s^2)
  688. */
  689. #define SENSORS_GRAVITY_SUN (275.0f)
  690. #define SENSORS_GRAVITY_MOON (1.6f)
  691. #define SENSORS_GRAVITY_EARTH (9.80665f)
  692. #define SENSORS_GRAVITY_STANDARD (SENSORS_GRAVITY_EARTH)
  693. /** Maximum magnetic field on Earth's surface */
  694. #define MAGNETIC_FIELD_EARTH_MAX (60.0f)
  695. /** Minimum magnetic field on Earth's surface */
  696. #define MAGNETIC_FIELD_EARTH_MIN (30.0f)
  697. /** Average sea level pressure is 1013.25 hPa */
  698. #define SENSORS_PRESSURE_SEALEVELHPA (1013.25F)
  699. /** Degrees/s to rad/s multiplier */
  700. #define SENSORS_DPS_TO_RADS (0.017453293F)
  701. /** Gauss to micro-Tesla multiplier */
  702. #define SENSORS_GAUSS_TO_MICROTESLA (100)
  703. /**
  704. * status of orientation sensor
  705. */
  706. #define SENSOR_STATUS_UNRELIABLE 0
  707. #define SENSOR_STATUS_ACCURACY_LOW 1
  708. #define SENSOR_STATUS_ACCURACY_MEDIUM 2
  709. #define SENSOR_STATUS_ACCURACY_HIGH 3
  710. /**
  711. * sensor event data
  712. */
  713. typedef struct
  714. {
  715. union
  716. {
  717. float v[3];
  718. struct
  719. {
  720. float x;
  721. float y;
  722. float z;
  723. };
  724. struct
  725. {
  726. float azimuth;
  727. float pitch;
  728. float roll;
  729. };
  730. };
  731. int8_t status;
  732. uint8_t reserved[3];
  733. } sensors_vec_t;
  734. /**
  735. * sensor raw vector data
  736. */
  737. typedef struct
  738. {
  739. struct
  740. {
  741. int16_t x;
  742. int16_t y;
  743. int16_t z;
  744. };
  745. int8_t status;
  746. uint8_t reserved[1];
  747. } sensors_raw_vec_t;
  748. /**
  749. * uncalibrated gyroscope and magnetometer event data
  750. */
  751. typedef struct
  752. {
  753. union
  754. {
  755. float uncalib[3];
  756. struct
  757. {
  758. float x_uncalib;
  759. float y_uncalib;
  760. float z_uncalib;
  761. };
  762. };
  763. union
  764. {
  765. float bias[3];
  766. struct
  767. {
  768. float x_bias;
  769. float y_bias;
  770. float z_bias;
  771. };
  772. };
  773. } uncalibrated_event_t;
  774. typedef struct meta_data_event
  775. {
  776. int32_t what;
  777. int32_t sensor;
  778. } meta_data_event_t;
  779. /**
  780. * Union of the various types of sensor data
  781. * that can be returned.
  782. */
  783. typedef struct sensors_event_t
  784. {
  785. /* must be sizeof(struct sensors_event_t) */
  786. int32_t version;
  787. /* sensor identifier */
  788. int32_t sensor;
  789. /* sensor type */
  790. int32_t type;
  791. /* reserved */
  792. int32_t reserved0;
  793. /* time is in nanosecond */
  794. int64_t timestamp;
  795. union
  796. {
  797. union
  798. {
  799. float data[16];
  800. /* acceleration values are in meter per second per second (m/s^2) */
  801. sensors_vec_t acceleration;
  802. /* raw acceleration data */
  803. sensors_raw_vec_t raw_acceleration;
  804. /* magnetic vector values are in micro-Tesla (uT) */
  805. sensors_vec_t magnetic;
  806. /* raw magnetic data */
  807. sensors_raw_vec_t raw_magnetic;
  808. /* orientation values are in degrees */
  809. sensors_vec_t orientation;
  810. /* gyroscope values are in rad/s */
  811. sensors_vec_t gyro;
  812. /* raw gyroscope data */
  813. sensors_raw_vec_t raw_gyro;
  814. /* temperature is in degrees centigrade (Celsius) */
  815. float temperature;
  816. /* distance in centimeters */
  817. float distance;
  818. /* light in SI lux units */
  819. float light;
  820. /* pressure in hectopascal (hPa) */
  821. float pressure;
  822. /* relative humidity in percent */
  823. float relative_humidity;
  824. /* uncalibrated gyroscope values are in rad/s */
  825. uncalibrated_event_t uncalibrated_gyro;
  826. /* uncalibrated magnetometer values are in micro-Teslas */
  827. uncalibrated_event_t uncalibrated_magnetic;
  828. /* this is a special event. see SENSOR_TYPE_META_DATA above.
  829. * sensors_meta_data_event_t events are all reported with a type of
  830. * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero.
  831. */
  832. meta_data_event_t meta_data;
  833. };
  834. union
  835. {
  836. uint64_t data[8];
  837. /* step-counter */
  838. uint64_t step_counter;
  839. } u64;
  840. };
  841. uint32_t reserved1[4];
  842. } sensors_event_t;
  843. /* see SENSOR_TYPE_META_DATA */
  844. typedef sensors_event_t sensors_meta_data_event_t;
  845. typedef struct sensor_t
  846. {
  847. /* Name of this sensor.
  848. * All sensors of the same "type" must have a different "name".
  849. */
  850. const char *name;
  851. /* vendor of the hardware part */
  852. const char *vendor;
  853. /* version of the hardware part + driver. The value of this field
  854. * must increase when the driver is updated in a way that changes the
  855. * output of this sensor. This is important for fused sensors when the
  856. * fusion algorithm is updated.
  857. */
  858. int version;
  859. /* handle that identifies this sensors. This handle is used to reference
  860. * this sensor throughout the HAL API.
  861. */
  862. int handle;
  863. /* this sensor's type. */
  864. int type;
  865. /* maximum range of this sensor's value in SI units */
  866. float maxRange;
  867. /* smallest difference between two values reported by this sensor */
  868. float resolution;
  869. /* rough estimate of this sensor's power consumption in mA */
  870. float power;
  871. /* this value depends on the trigger mode:
  872. *
  873. * continuous: minimum sample period allowed in microseconds
  874. * on-change : 0
  875. * one-shot :-1
  876. * special : 0, unless otherwise noted
  877. */
  878. int32_t minDelay;
  879. /* number of events reserved for this sensor in the batch mode FIFO.
  880. * If there is a dedicated FIFO for this sensor, then this is the
  881. * size of this FIFO. If the FIFO is shared with other sensors,
  882. * this is the size reserved for that sensor and it can be zero.
  883. */
  884. uint32_t fifoReservedEventCount;
  885. /* maximum number of events of this sensor that could be batched.
  886. * This is especially relevant when the FIFO is shared between
  887. * several sensors; this value is then set to the size of that FIFO.
  888. */
  889. uint32_t fifoMaxEventCount;
  890. /* reserved fields, must be zero */
  891. void *reserved[6];
  892. } sensor_t;
  893. enum SensorMode
  894. {
  895. SENSOR_MODE_RAW,
  896. SENSOR_MODE_CALIBRATED,
  897. SENSOR_MODE_NORMAL,
  898. };
  899. enum SensorAccelRange
  900. {
  901. SENSOR_ACCEL_RANGE_2G,
  902. SENSOR_ACCEL_RANGE_4G,
  903. SENSOR_ACCEL_RANGE_8G,
  904. SENSOR_ACCEL_RANGE_16G,
  905. };
  906. #define SENSOR_ACCEL_SENSITIVITY_2G ((float)2/32768)
  907. #define SENSOR_ACCEL_SENSITIVITY_4G ((float)4/32768)
  908. #define SENSOR_ACCEL_SENSITIVITY_8G ((float)8/32768)
  909. #define SENSOR_ACCEL_SENSITIVITY_16G ((float)16/32768)
  910. enum SensorGyroRange
  911. {
  912. SENSOR_GYRO_RANGE_250DPS,
  913. SENSOR_GYRO_RANGE_500DPS,
  914. SENSOR_GYRO_RANGE_1000DPS,
  915. SENSOR_GYRO_RANGE_2000DPS,
  916. };
  917. #define SENSOR_GYRO_SENSITIVITY_250DPS (0.00875F)
  918. #define SENSOR_GYRO_SENSITIVITY_500DPS (0.0175F)
  919. #define SENSOR_GYRO_SENSITIVITY_1000DPS (0.035F)
  920. #define SENSOR_GYRO_SENSITIVITY_2000DPS (0.070F)
  921. enum SensorDataRate
  922. {
  923. SENSOR_DATARATE_3200HZ,
  924. SENSOR_DATARATE_1600HZ,
  925. SENSOR_DATARATE_800HZ,
  926. SENSOR_DATARATE_400HZ,
  927. SENSOR_DATARATE_200HZ,
  928. SENSOR_DATARATE_100HZ,
  929. SENSOR_DATARATE_50HZ,
  930. SENSOR_DATARATE_25HZ,
  931. SENSOR_DATARATE_12_5HZ,
  932. SENSOR_DATARATE_6_25HZ,
  933. SENSOR_DATARATE_3_13HZ,
  934. SENSOR_DATARATE_1_56HZ,
  935. SENSOR_DATARATE_0_78HZ,
  936. SENSOR_DATARATE_0_39HZ,
  937. SENSOR_DATARATE_0_20HZ,
  938. SENSOR_DATARATE_0_10HZ,
  939. };
  940. /**
  941. * Sensor Configuration
  942. */
  943. typedef struct SensorConfig
  944. {
  945. int mode;
  946. enum SensorDataRate data_rate;
  947. union range
  948. {
  949. int range;
  950. enum SensorAccelRange accel_range;
  951. enum SensorGyroRange gyro_range;
  952. } range;
  953. }SensorConfig;
  954. typedef void (*SensorEventHandler_t)(void *user_data);
  955. #ifdef __cplusplus
  956. class SensorBase;
  957. class SensorManager;
  958. /**
  959. * Sensor Base Class
  960. */
  961. class SensorBase
  962. {
  963. private:
  964. int type;
  965. public:
  966. SensorBase(int type);
  967. ~SensorBase();
  968. virtual int configure(SensorConfig *config) = 0;
  969. virtual int activate(int enable) = 0;
  970. virtual int poll(sensors_event_t *events) = 0;
  971. virtual void getSensor(struct sensor_t *sensor) = 0;
  972. int getType(void);
  973. int setConfig(SensorConfig *config);
  974. int getConfig(SensorConfig *config);
  975. int subscribe(SensorEventHandler_t handler, void *user_data);
  976. int publish(void);
  977. protected:
  978. SensorBase *next;
  979. SensorBase *prev;
  980. /* sensor configuration */
  981. SensorConfig config;
  982. SensorEventHandler_t evtHandler;
  983. void *userData;
  984. friend class SensorManager;
  985. };
  986. /**
  987. * Sensor Manager
  988. */
  989. class SensorManager
  990. {
  991. public:
  992. SensorManager();
  993. ~SensorManager();
  994. static int registerSensor(SensorBase *sensor);
  995. static int unregisterSensor(SensorBase *sensor);
  996. static SensorBase *getDefaultSensor(int type);
  997. static int subscribe(int type, SensorEventHandler_t handler, void *user_data);
  998. static int sensorEventReady(SensorBase *sensor);
  999. static int pollSensor(SensorBase *sensor, sensors_event_t *events, int number, int duration);
  1000. };
  1001. #endif
  1002. /* C programming language APIs */
  1003. /* rt_sensor_t is a C typedef for SensorBase */
  1004. typedef void* rt_sensor_t;
  1005. #ifdef __cplusplus
  1006. extern "C" {
  1007. #endif
  1008. rt_sensor_t rt_sensor_get_default(int type);
  1009. int rt_sensor_subscribe(rt_sensor_t sensor, SensorEventHandler_t handler, void *user_data);
  1010. int rt_sensor_activate (rt_sensor_t sensor, int enable);
  1011. int rt_sensor_configure(rt_sensor_t sensor, SensorConfig *config);
  1012. int rt_sensor_poll(rt_sensor_t sensor, sensors_event_t *event);
  1013. #ifdef __cplusplus
  1014. }
  1015. #endif
  1016. #endif