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