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