0001 For discussion. Unclear are:
0002 * is the definition of +/- values practical or counterintuitive?
0003 * are the definitions unambiguous and easy to follow?
0004 * are the examples correct?
0005 * should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
0006
0007 ====
0008
0009
0010 Mounting matrix
0011
0012 The mounting matrix is a device tree property used to orient any device
0013 that produce three-dimensional data in relation to the world where it is
0014 deployed.
0015
0016 The purpose of the mounting matrix is to translate the sensor frame of
0017 reference into the device frame of reference using a translation matrix as
0018 defined in linear algebra.
0019
0020 The typical usecase is that where a component has an internal representation
0021 of the (x,y,z) triplets, such as different registers to read these coordinates,
0022 and thus implying that the component should be mounted in a certain orientation
0023 relative to some specific device frame of reference.
0024
0025 For example a device with some kind of screen, where the user is supposed to
0026 interact with the environment using an accelerometer, gyroscope or magnetometer
0027 mounted on the same chassis as this screen, will likely take the screen as
0028 reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
0029 screen and (z) being depth, the axis perpendicular to the screen.
0030
0031 For a screen you probably want (x) coordinates to go from negative on the left
0032 to positive on the right, (y) from negative on the bottom to positive on top
0033 and (z) depth to be negative under the screen and positive in front of it,
0034 toward the face of the user.
0035
0036 A sensor can be mounted in any angle along the axes relative to the frame of
0037 reference. This means that the sensor may be flipped upside-down, left-right,
0038 or tilted at any angle relative to the frame of reference.
0039
0040 Another frame of reference is how the device with its sensor relates to the
0041 external world, the environment where the device is deployed. Usually the data
0042 from the sensor is used to figure out how the device is oriented with respect
0043 to this world. When using the mounting matrix, the sensor and device orientation
0044 becomes identical and we can focus on the data as it relates to the surrounding
0045 world.
0046
0047 Device-to-world examples for some three-dimensional sensor types:
0048
0049 - Accelerometers have their world frame of reference toward the center of
0050 gravity, usually to the core of the planet. A reading of the (x,y,z) values
0051 from the sensor will give a projection of the gravity vector through the
0052 device relative to the center of the planet, i.e. relative to its surface at
0053 this point. Up and down in the world relative to the device frame of
0054 reference can thus be determined. and users would likely expect a value of
0055 9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
0056 is held with its screen flat on the planets surface and 0 on the other axes,
0057 as the gravity vector is projected 1:1 onto the sensors (z)-axis.
0058
0059 If you tilt the device, the g vector virtually coming out of the display
0060 is projected onto the (x,y) plane of the display panel.
0061
0062 Example:
0063
0064 ^ z: +g ^ z: > 0
0065 ! /!
0066 ! x=y=0 / ! x: > 0
0067 +--------+ +--------+
0068 ! ! ! !
0069 +--------+ +--------+
0070 ! /
0071 ! /
0072 v v
0073 center of center of
0074 gravity gravity
0075
0076
0077 If the device is tilted to the left, you get a positive x value. If you point
0078 its top towards surface, you get a negative y axis.
0079
0080 (---------)
0081 ! ! y: -g
0082 ! ! ^
0083 ! ! !
0084 ! !
0085 ! ! x: +g <- z: +g -> x: -g
0086 ! 1 2 3 !
0087 ! 4 5 6 ! !
0088 ! 7 8 9 ! v
0089 ! * 0 # ! y: +g
0090 (---------)
0091
0092
0093 - Magnetometers (compasses) have their world frame of reference relative to the
0094 geomagnetic field. The system orientation vis-a-vis the world is defined with
0095 respect to the local earth geomagnetic reference frame where (y) is in the
0096 ground plane and positive towards magnetic North, (x) is in the ground plane,
0097 perpendicular to the North axis and positive towards the East and (z) is
0098 perpendicular to the ground plane and positive upwards.
0099
0100
0101 ^^^ North: y > 0
0102
0103 (---------)
0104 ! !
0105 ! !
0106 ! !
0107 ! ! >
0108 ! ! > North: x > 0
0109 ! 1 2 3 ! >
0110 ! 4 5 6 !
0111 ! 7 8 9 !
0112 ! * 0 # !
0113 (---------)
0114
0115 Since the geomagnetic field is not uniform this definition fails if we come
0116 closer to the poles.
0117
0118 Sensors and driver can not and should not take care of this because there
0119 are complex calculations and empirical data to be taken care of. We leave
0120 this up to user space.
0121
0122 The definition we take:
0123
0124 If the device is placed at the equator and the top is pointing north, the
0125 display is readable by a person standing upright on the earth surface, this
0126 defines a positive y value.
0127
0128
0129 - Gyroscopes detects the movement relative the device itself. The angular
0130 velocity is defined as orthogonal to the plane of rotation, so if you put the
0131 device on a flat surface and spin it around the z axis (such as rotating a
0132 device with a screen lying flat on a table), you should get a negative value
0133 along the (z) axis if rotated clockwise, and a positive value if rotated
0134 counter-clockwise according to the right-hand rule.
0135
0136
0137 (---------) y > 0
0138 ! ! v---\
0139 ! !
0140 ! !
0141 ! ! <--\
0142 ! ! ! z > 0
0143 ! 1 2 3 ! --/
0144 ! 4 5 6 !
0145 ! 7 8 9 !
0146 ! * 0 # !
0147 (---------)
0148
0149
0150 So unless the sensor is ideally mounted, we need a means to indicate the
0151 relative orientation of any given sensor of this type with respect to the
0152 frame of reference.
0153
0154 To achieve this, use the device tree property "mount-matrix" for the sensor.
0155
0156 This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
0157 to orient the senor axes relative to a desired point of reference. This means
0158 the resulting values from the sensor, after scaling to proper units, should be
0159 multiplied by this matrix to give the proper vectors values in three-dimensional
0160 space, relative to the device or world point of reference.
0161
0162 For more information, consult:
0163 https://en.wikipedia.org/wiki/Rotation_matrix
0164
0165 The mounting matrix has the layout:
0166
0167 (mxx, myx, mzx)
0168 (mxy, myy, mzy)
0169 (mxz, myz, mzz)
0170
0171 Values are intended to be multiplied as:
0172
0173 x' = mxx * x + myx * y + mzx * z
0174 y' = mxy * x + myy * y + mzy * z
0175 z' = mxz * x + myz * y + mzz * z
0176
0177 It is represented as an array of strings containing the real values for
0178 producing the transformation matrix.
0179
0180 Examples:
0181
0182 Identity matrix (nothing happens to the coordinates, which means the device was
0183 mechanically mounted in an ideal way and we need no transformation):
0184
0185 mount-matrix = "1", "0", "0",
0186 "0", "1", "0",
0187 "0", "0", "1";
0188
0189 The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
0190 compensate by performing a -30 degrees rotation around the X axis:
0191
0192 mount-matrix = "1", "0", "0",
0193 "0", "0.866", "0.5",
0194 "0", "-0.5", "0.866";
0195
0196 The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
0197 upside-down:
0198
0199 mount-matrix = "0.998", "0.054", "0",
0200 "-0.054", "0.998", "0",
0201 "0", "0", "1";
0202
0203 ???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
