1 For discussion. Unclear are: 1 For discussion. Unclear are:
2 * is the definition of +/- values practical or 2 * is the definition of +/- values practical or counterintuitive?
3 * are the definitions unambiguous and easy to 3 * are the definitions unambiguous and easy to follow?
4 * are the examples correct? 4 * are the examples correct?
5 * should we have HOWTO engineer a correct matr 5 * should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
6 6
7 ==== 7 ====
8 8
9 9
10 Mounting matrix 10 Mounting matrix
11 11
12 The mounting matrix is a device tree property 12 The mounting matrix is a device tree property used to orient any device
13 that produce three-dimensional data in relatio 13 that produce three-dimensional data in relation to the world where it is
14 deployed. 14 deployed.
15 15
16 The purpose of the mounting matrix is to trans 16 The purpose of the mounting matrix is to translate the sensor frame of
17 reference into the device frame of reference u 17 reference into the device frame of reference using a translation matrix as
18 defined in linear algebra. 18 defined in linear algebra.
19 19
20 The typical usecase is that where a component 20 The typical usecase is that where a component has an internal representation
21 of the (x,y,z) triplets, such as different reg 21 of the (x,y,z) triplets, such as different registers to read these coordinates,
22 and thus implying that the component should be 22 and thus implying that the component should be mounted in a certain orientation
23 relative to some specific device frame of refe 23 relative to some specific device frame of reference.
24 24
25 For example a device with some kind of screen, 25 For example a device with some kind of screen, where the user is supposed to
26 interact with the environment using an acceler 26 interact with the environment using an accelerometer, gyroscope or magnetometer
27 mounted on the same chassis as this screen, wi 27 mounted on the same chassis as this screen, will likely take the screen as
28 reference to (x,y,z) orientation, with (x,y) c 28 reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
29 screen and (z) being depth, the axis perpendic 29 screen and (z) being depth, the axis perpendicular to the screen.
30 30
31 For a screen you probably want (x) coordinates 31 For a screen you probably want (x) coordinates to go from negative on the left
32 to positive on the right, (y) from negative on 32 to positive on the right, (y) from negative on the bottom to positive on top
33 and (z) depth to be negative under the screen 33 and (z) depth to be negative under the screen and positive in front of it,
34 toward the face of the user. 34 toward the face of the user.
35 35
36 A sensor can be mounted in any angle along the 36 A sensor can be mounted in any angle along the axes relative to the frame of
37 reference. This means that the sensor may be f 37 reference. This means that the sensor may be flipped upside-down, left-right,
38 or tilted at any angle relative to the frame o 38 or tilted at any angle relative to the frame of reference.
39 39
40 Another frame of reference is how the device w 40 Another frame of reference is how the device with its sensor relates to the
41 external world, the environment where the devi 41 external world, the environment where the device is deployed. Usually the data
42 from the sensor is used to figure out how the 42 from the sensor is used to figure out how the device is oriented with respect
43 to this world. When using the mounting matrix, 43 to this world. When using the mounting matrix, the sensor and device orientation
44 becomes identical and we can focus on the data 44 becomes identical and we can focus on the data as it relates to the surrounding
45 world. 45 world.
46 46
47 Device-to-world examples for some three-dimens 47 Device-to-world examples for some three-dimensional sensor types:
48 48
49 - Accelerometers have their world frame of ref 49 - Accelerometers have their world frame of reference toward the center of
50 gravity, usually to the core of the planet. 50 gravity, usually to the core of the planet. A reading of the (x,y,z) values
51 from the sensor will give a projection of th 51 from the sensor will give a projection of the gravity vector through the
52 device relative to the center of the planet, 52 device relative to the center of the planet, i.e. relative to its surface at
53 this point. Up and down in the world relativ 53 this point. Up and down in the world relative to the device frame of
54 reference can thus be determined. and users 54 reference can thus be determined. and users would likely expect a value of
55 9.81 m/s^2 upwards along the (z) axis, i.e. 55 9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
56 is held with its screen flat on the planets 56 is held with its screen flat on the planets surface and 0 on the other axes,
57 as the gravity vector is projected 1:1 onto 57 as the gravity vector is projected 1:1 onto the sensors (z)-axis.
58 58
59 If you tilt the device, the g vector virtual 59 If you tilt the device, the g vector virtually coming out of the display
60 is projected onto the (x,y) plane of the dis 60 is projected onto the (x,y) plane of the display panel.
61 61
62 Example: 62 Example:
63 63
64 ^ z: +g ^ z: > 0 64 ^ z: +g ^ z: > 0
65 ! /! 65 ! /!
66 ! x=y=0 / ! x: > 0 66 ! x=y=0 / ! x: > 0
67 +--------+ +--------+ 67 +--------+ +--------+
68 ! ! ! ! 68 ! ! ! !
69 +--------+ +--------+ 69 +--------+ +--------+
70 ! / 70 ! /
71 ! / 71 ! /
72 v v 72 v v
73 center of center of 73 center of center of
74 gravity gravity 74 gravity gravity
75 75
76 76
77 If the device is tilted to the left, you get 77 If the device is tilted to the left, you get a positive x value. If you point
78 its top towards surface, you get a negative 78 its top towards surface, you get a negative y axis.
79 79
80 (---------) 80 (---------)
81 ! ! y: -g 81 ! ! y: -g
82 ! ! ^ 82 ! ! ^
83 ! ! ! 83 ! ! !
84 ! ! 84 ! !
85 ! ! x: +g <- z: +g -> x: -g 85 ! ! x: +g <- z: +g -> x: -g
86 ! 1 2 3 ! 86 ! 1 2 3 !
87 ! 4 5 6 ! ! 87 ! 4 5 6 ! !
88 ! 7 8 9 ! v 88 ! 7 8 9 ! v
89 ! * 0 # ! y: +g 89 ! * 0 # ! y: +g
90 (---------) 90 (---------)
91 91
92 92
93 - Magnetometers (compasses) have their world f 93 - Magnetometers (compasses) have their world frame of reference relative to the
94 geomagnetic field. The system orientation vi 94 geomagnetic field. The system orientation vis-a-vis the world is defined with
95 respect to the local earth geomagnetic refer 95 respect to the local earth geomagnetic reference frame where (y) is in the
96 ground plane and positive towards magnetic N 96 ground plane and positive towards magnetic North, (x) is in the ground plane,
97 perpendicular to the North axis and positive 97 perpendicular to the North axis and positive towards the East and (z) is
98 perpendicular to the ground plane and positi 98 perpendicular to the ground plane and positive upwards.
99 99
100 100
101 ^^^ North: y > 0 101 ^^^ North: y > 0
102 102
103 (---------) 103 (---------)
104 ! ! 104 ! !
105 ! ! 105 ! !
106 ! ! 106 ! !
107 ! ! > 107 ! ! >
108 ! ! > North: x > 0 108 ! ! > North: x > 0
109 ! 1 2 3 ! > 109 ! 1 2 3 ! >
110 ! 4 5 6 ! 110 ! 4 5 6 !
111 ! 7 8 9 ! 111 ! 7 8 9 !
112 ! * 0 # ! 112 ! * 0 # !
113 (---------) 113 (---------)
114 114
115 Since the geomagnetic field is not uniform t 115 Since the geomagnetic field is not uniform this definition fails if we come
116 closer to the poles. 116 closer to the poles.
117 117
118 Sensors and driver can not and should not ta 118 Sensors and driver can not and should not take care of this because there
119 are complex calculations and empirical data 119 are complex calculations and empirical data to be taken care of. We leave
120 this up to user space. 120 this up to user space.
121 121
122 The definition we take: 122 The definition we take:
123 123
124 If the device is placed at the equator and t 124 If the device is placed at the equator and the top is pointing north, the
125 display is readable by a person standing upr 125 display is readable by a person standing upright on the earth surface, this
126 defines a positive y value. 126 defines a positive y value.
127 127
128 128
129 - Gyroscopes detects the movement relative the 129 - Gyroscopes detects the movement relative the device itself. The angular
130 velocity is defined as orthogonal to the pla 130 velocity is defined as orthogonal to the plane of rotation, so if you put the
131 device on a flat surface and spin it around 131 device on a flat surface and spin it around the z axis (such as rotating a
132 device with a screen lying flat on a table), 132 device with a screen lying flat on a table), you should get a negative value
133 along the (z) axis if rotated clockwise, and 133 along the (z) axis if rotated clockwise, and a positive value if rotated
134 counter-clockwise according to the right-han 134 counter-clockwise according to the right-hand rule.
135 135
136 136
137 (---------) y > 0 137 (---------) y > 0
138 ! ! v---\ 138 ! ! v---\
139 ! ! 139 ! !
140 ! ! 140 ! !
141 ! ! <--\ 141 ! ! <--\
142 ! ! ! z > 0 142 ! ! ! z > 0
143 ! 1 2 3 ! --/ 143 ! 1 2 3 ! --/
144 ! 4 5 6 ! 144 ! 4 5 6 !
145 ! 7 8 9 ! 145 ! 7 8 9 !
146 ! * 0 # ! 146 ! * 0 # !
147 (---------) 147 (---------)
148 148
149 149
150 So unless the sensor is ideally mounted, we ne 150 So unless the sensor is ideally mounted, we need a means to indicate the
151 relative orientation of any given sensor of th 151 relative orientation of any given sensor of this type with respect to the
152 frame of reference. 152 frame of reference.
153 153
154 To achieve this, use the device tree property 154 To achieve this, use the device tree property "mount-matrix" for the sensor.
155 155
156 This supplies a 3x3 rotation matrix in the str 156 This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
157 to orient the senor axes relative to a desired 157 to orient the senor axes relative to a desired point of reference. This means
158 the resulting values from the sensor, after sc 158 the resulting values from the sensor, after scaling to proper units, should be
159 multiplied by this matrix to give the proper v 159 multiplied by this matrix to give the proper vectors values in three-dimensional
160 space, relative to the device or world point o 160 space, relative to the device or world point of reference.
161 161
162 For more information, consult: 162 For more information, consult:
163 https://en.wikipedia.org/wiki/Rotation_matrix 163 https://en.wikipedia.org/wiki/Rotation_matrix
164 164
165 The mounting matrix has the layout: 165 The mounting matrix has the layout:
166 166
167 (mxx, myx, mzx) 167 (mxx, myx, mzx)
168 (mxy, myy, mzy) 168 (mxy, myy, mzy)
169 (mxz, myz, mzz) 169 (mxz, myz, mzz)
170 170
171 Values are intended to be multiplied as: 171 Values are intended to be multiplied as:
172 172
173 x' = mxx * x + myx * y + mzx * z 173 x' = mxx * x + myx * y + mzx * z
174 y' = mxy * x + myy * y + mzy * z 174 y' = mxy * x + myy * y + mzy * z
175 z' = mxz * x + myz * y + mzz * z 175 z' = mxz * x + myz * y + mzz * z
176 176
177 It is represented as an array of strings conta 177 It is represented as an array of strings containing the real values for
178 producing the transformation matrix. 178 producing the transformation matrix.
179 179
180 Examples: 180 Examples:
181 181
182 Identity matrix (nothing happens to the coordi 182 Identity matrix (nothing happens to the coordinates, which means the device was
183 mechanically mounted in an ideal way and we ne 183 mechanically mounted in an ideal way and we need no transformation):
184 184
185 mount-matrix = "1", "0", "0", 185 mount-matrix = "1", "0", "0",
186 "0", "1", "0", 186 "0", "1", "0",
187 "0", "0", "1"; 187 "0", "0", "1";
188 188
189 The sensor is mounted 30 degrees (Pi/6 radians 189 The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
190 compensate by performing a -30 degrees rotatio 190 compensate by performing a -30 degrees rotation around the X axis:
191 191
192 mount-matrix = "1", "0", "0", 192 mount-matrix = "1", "0", "0",
193 "0", "0.866", "0.5", 193 "0", "0.866", "0.5",
194 "0", "-0.5", "0.866"; 194 "0", "-0.5", "0.866";
195 195
196 The sensor is flipped 180 degrees (Pi radians) 196 The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
197 upside-down: 197 upside-down:
198 198
199 mount-matrix = "0.998", "0.054", "0", 199 mount-matrix = "0.998", "0.054", "0",
200 "-0.054", "0.998", "0", 200 "-0.054", "0.998", "0",
201 "0", "0", "1"; 201 "0", "0", "1";
202 202
203 ???: this does not match "180 degrees" - facto 203 ???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.