204 lines
7.4 KiB
Plaintext
204 lines
7.4 KiB
Plaintext
For discussion. Unclear are:
|
|
* is the definition of +/- values practical or counterintuitive?
|
|
* are the definitions unambiguous and easy to follow?
|
|
* are the examples correct?
|
|
* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
|
|
|
|
====
|
|
|
|
|
|
Mounting matrix
|
|
|
|
The mounting matrix is a device tree property used to orient any device
|
|
that produce three-dimensional data in relation to the world where it is
|
|
deployed.
|
|
|
|
The purpose of the mounting matrix is to translate the sensor frame of
|
|
reference into the device frame of reference using a translation matrix as
|
|
defined in linear algebra.
|
|
|
|
The typical usecase is that where a component has an internal representation
|
|
of the (x,y,z) triplets, such as different registers to read these coordinates,
|
|
and thus implying that the component should be mounted in a certain orientation
|
|
relative to some specific device frame of reference.
|
|
|
|
For example a device with some kind of screen, where the user is supposed to
|
|
interact with the environment using an accelerometer, gyroscope or magnetometer
|
|
mounted on the same chassis as this screen, will likely take the screen as
|
|
reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
|
|
screen and (z) being depth, the axis perpendicular to the screen.
|
|
|
|
For a screen you probably want (x) coordinates to go from negative on the left
|
|
to positive on the right, (y) from negative on the bottom to positive on top
|
|
and (z) depth to be negative under the screen and positive in front of it,
|
|
toward the face of the user.
|
|
|
|
A sensor can be mounted in any angle along the axes relative to the frame of
|
|
reference. This means that the sensor may be flipped upside-down, left-right,
|
|
or tilted at any angle relative to the frame of reference.
|
|
|
|
Another frame of reference is how the device with its sensor relates to the
|
|
external world, the environment where the device is deployed. Usually the data
|
|
from the sensor is used to figure out how the device is oriented with respect
|
|
to this world. When using the mounting matrix, the sensor and device orientation
|
|
becomes identical and we can focus on the data as it relates to the surrounding
|
|
world.
|
|
|
|
Device-to-world examples for some three-dimensional sensor types:
|
|
|
|
- Accelerometers have their world frame of reference toward the center of
|
|
gravity, usually to the core of the planet. A reading of the (x,y,z) values
|
|
from the sensor will give a projection of the gravity vector through the
|
|
device relative to the center of the planet, i.e. relative to its surface at
|
|
this point. Up and down in the world relative to the device frame of
|
|
reference can thus be determined. and users would likely expect a value of
|
|
9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
|
|
is held with its screen flat on the planets surface and 0 on the other axes,
|
|
as the gravity vector is projected 1:1 onto the sensors (z)-axis.
|
|
|
|
If you tilt the device, the g vector virtually coming out of the display
|
|
is projected onto the (x,y) plane of the display panel.
|
|
|
|
Example:
|
|
|
|
^ z: +g ^ z: > 0
|
|
! /!
|
|
! x=y=0 / ! x: > 0
|
|
+--------+ +--------+
|
|
! ! ! !
|
|
+--------+ +--------+
|
|
! /
|
|
! /
|
|
v v
|
|
center of center of
|
|
gravity gravity
|
|
|
|
|
|
If the device is tilted to the left, you get a positive x value. If you point
|
|
its top towards surface, you get a negative y axis.
|
|
|
|
(---------)
|
|
! ! y: -g
|
|
! ! ^
|
|
! ! !
|
|
! !
|
|
! ! x: +g <- z: +g -> x: -g
|
|
! 1 2 3 !
|
|
! 4 5 6 ! !
|
|
! 7 8 9 ! v
|
|
! * 0 # ! y: +g
|
|
(---------)
|
|
|
|
|
|
- Magnetometers (compasses) have their world frame of reference relative to the
|
|
geomagnetic field. The system orientation vis-a-vis the world is defined with
|
|
respect to the local earth geomagnetic reference frame where (y) is in the
|
|
ground plane and positive towards magnetic North, (x) is in the ground plane,
|
|
perpendicular to the North axis and positive towards the East and (z) is
|
|
perpendicular to the ground plane and positive upwards.
|
|
|
|
|
|
^^^ North: y > 0
|
|
|
|
(---------)
|
|
! !
|
|
! !
|
|
! !
|
|
! ! >
|
|
! ! > North: x > 0
|
|
! 1 2 3 ! >
|
|
! 4 5 6 !
|
|
! 7 8 9 !
|
|
! * 0 # !
|
|
(---------)
|
|
|
|
Since the geomagnetic field is not uniform this definition fails if we come
|
|
closer to the poles.
|
|
|
|
Sensors and driver can not and should not take care of this because there
|
|
are complex calculations and empirical data to be taken care of. We leave
|
|
this up to user space.
|
|
|
|
The definition we take:
|
|
|
|
If the device is placed at the equator and the top is pointing north, the
|
|
display is readable by a person standing upright on the earth surface, this
|
|
defines a positive y value.
|
|
|
|
|
|
- Gyroscopes detects the movement relative the device itself. The angular
|
|
velocity is defined as orthogonal to the plane of rotation, so if you put the
|
|
device on a flat surface and spin it around the z axis (such as rotating a
|
|
device with a screen lying flat on a table), you should get a negative value
|
|
along the (z) axis if rotated clockwise, and a positive value if rotated
|
|
counter-clockwise according to the right-hand rule.
|
|
|
|
|
|
(---------) y > 0
|
|
! ! v---\
|
|
! !
|
|
! !
|
|
! ! <--\
|
|
! ! ! z > 0
|
|
! 1 2 3 ! --/
|
|
! 4 5 6 !
|
|
! 7 8 9 !
|
|
! * 0 # !
|
|
(---------)
|
|
|
|
|
|
So unless the sensor is ideally mounted, we need a means to indicate the
|
|
relative orientation of any given sensor of this type with respect to the
|
|
frame of reference.
|
|
|
|
To achieve this, use the device tree property "mount-matrix" for the sensor.
|
|
|
|
This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
|
|
to orient the senor axes relative to a desired point of reference. This means
|
|
the resulting values from the sensor, after scaling to proper units, should be
|
|
multiplied by this matrix to give the proper vectors values in three-dimensional
|
|
space, relative to the device or world point of reference.
|
|
|
|
For more information, consult:
|
|
https://en.wikipedia.org/wiki/Rotation_matrix
|
|
|
|
The mounting matrix has the layout:
|
|
|
|
(mxx, myx, mzx)
|
|
(mxy, myy, mzy)
|
|
(mxz, myz, mzz)
|
|
|
|
Values are intended to be multiplied as:
|
|
|
|
x' = mxx * x + myx * y + mzx * z
|
|
y' = mxy * x + myy * y + mzy * z
|
|
z' = mxz * x + myz * y + mzz * z
|
|
|
|
It is represented as an array of strings containing the real values for
|
|
producing the transformation matrix.
|
|
|
|
Examples:
|
|
|
|
Identity matrix (nothing happens to the coordinates, which means the device was
|
|
mechanically mounted in an ideal way and we need no transformation):
|
|
|
|
mount-matrix = "1", "0", "0",
|
|
"0", "1", "0",
|
|
"0", "0", "1";
|
|
|
|
The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
|
|
compensate by performing a -30 degrees rotation around the X axis:
|
|
|
|
mount-matrix = "1", "0", "0",
|
|
"0", "0.866", "0.5",
|
|
"0", "-0.5", "0.866";
|
|
|
|
The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
|
|
upside-down:
|
|
|
|
mount-matrix = "0.998", "0.054", "0",
|
|
"-0.054", "0.998", "0",
|
|
"0", "0", "1";
|
|
|
|
???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
|