Data Fields | |
| union { | |
| struct { | |
| float x | |
| float y | |
| float z | |
| } | |
| struct { | |
| float azimuth | |
| float pitch | |
| float roll | |
| } | |
| float v [3] | |
| }; | |
| uint8_t | reserved [3] |
| int8_t | status |
This API is relative to the screen of the device in its default orientation, that is, if the device can be used in portrait or landscape, this API is only relative to the NATURAL orientation of the screen. In other words, the axis are not swapped when the device's screen orientation changes. Higher level services /may/ perform this transformation.
x<0 x>0 ^ | +--------—+–> y>0
| | / z<0 | | / | | / O--------—+/ |[] [ ] []/ +-------—/+ y<0 / / |/ z>0 (toward the sky)
O: Origin (x=0,y=0,z=0)
All values are angles in degrees.
Orientation sensors return sensor events for all 3 axes at a constant rate defined by setDelay().
azimuth: angle between the magnetic north direction and the Y axis, around the Z axis (0<=azimuth<360). 0=North, 90=East, 180=South, 270=West
pitch: Rotation around X axis (-180<=pitch<=180), with positive values when the z-axis moves toward the y-axis.
roll: Rotation around Y axis (-90<=roll<=90), with positive values when the x-axis moves towards the z-axis.
Note: For historical reasons the roll angle is positive in the clockwise direction (mathematically speaking, it should be positive in the counter-clockwise direction):
Z
^
(+roll) .–> | / | | | roll: rotation around Y axis X <----—(.) Y note that +Y == -roll
Note: This definition is different from yaw, pitch and roll used in aviation where the X axis is along the long side of the plane (tail to nose).
All values are in SI units (m/s^2) and measure the acceleration of the device minus the force of gravity.
Acceleration sensors return sensor events for all 3 axes at a constant rate defined by setDelay().
x: Acceleration minus Gx on the x-axis y: Acceleration minus Gy on the y-axis z: Acceleration minus Gz on the z-axis
Examples: When the device lies flat on a table and is pushed on its left side toward the right, the x acceleration value is positive.
When the device lies flat on a table, the acceleration value is +9.81, which correspond to the acceleration of the device (0 m/s^2) minus the force of gravity (-9.81 m/s^2).
When the device lies flat on a table and is pushed toward the sky, the acceleration value is greater than +9.81, which correspond to the acceleration of the device (+A m/s^2) minus the force of gravity (-9.81 m/s^2).
All values are in micro-Tesla (uT) and measure the ambient magnetic field in the X, Y and Z axis.
Magnetic Field sensors return sensor events for all 3 axes at a constant rate defined by setDelay().
All values are in radians/second and measure the rate of rotation around the X, Y and Z axis. The coordinate system is the same as is used for the acceleration sensor. Rotation is positive in the counter-clockwise direction (right-hand rule). That is, an observer looking from some positive location on the x, y or z axis at a device positioned on the origin would report positive rotation if the device appeared to be rotating counter clockwise. Note that this is the standard mathematical definition of positive rotation and does not agree with the definition of roll given earlier. The range should at least be 17.45 rad/s (ie: ~1000 deg/s).
The distance value is measured in centimeters. Note that some proximity sensors only support a binary "close" or "far" measurement. In this case, the sensor should report its maxRange value in the "far" state and a value less than maxRange in the "near" state.
Proximity sensors report a value only when it changes and each time the sensor is enabled.
The light sensor value is returned in SI lux units.
Light sensors report a value only when it changes and each time the sensor is enabled.
The pressure sensor return the athmospheric pressure in hectopascal (hPa)
Pressure sensors report events at a constant rate defined by setDelay().
A gravity output indicates the direction of and magnitude of gravity in the devices's coordinates. On Earth, the magnitude is 9.8 m/s^2. Units are m/s^2. The coordinate system is the same as is used for the acceleration sensor. When the device is at rest, the output of the gravity sensor should be identical to that of the accelerometer.
Indicates the linear acceleration of the device in device coordinates, not including gravity. This output is essentially Acceleration - Gravity. Units are m/s^2. The coordinate system is the same as is used for the acceleration sensor.
A rotation vector represents the orientation of the device as a combination of an angle and an axis, in which the device has rotated through an angle theta around an axis <x, y, z>. The three elements of the rotation vector are <x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude of the rotation vector is equal to sin(theta/2), and the direction of the rotation vector is equal to the direction of the axis of rotation. The three elements of the rotation vector are equal to the last three components of a unit quaternion <cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>. Elements of the rotation vector are unitless. The x, y, and z axis are defined in the same was as for the acceleration sensor.
The reference coordinate system is defined as a direct orthonormal basis, where:
The rotation-vector is stored as:
sensors_event_t.data[0] = x*sin(theta/2) sensors_event_t.data[1] = y*sin(theta/2) sensors_event_t.data[2] = z*sin(theta/2) sensors_event_t.data[3] = cos(theta/2)
A relative humidity sensor measures relative ambient air humidity and returns a value in percent.
Relative humidity sensors report a value only when it changes and each time the sensor is enabled.
The ambient (room) temperature in degree Celsius.
Temperature sensors report a value only when it changes and each time the sensor is enabled.
| union { ... } |