| 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 |
