Documentation/devicetree/bindings/iio/mount-matrix.txt

   1 For 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
  10 Mounting matrix
  11
  12 The mounting matrix is a device tree property used to orient any device
  13 that produce three-dimensional data in relation to the world where it is
  14 deployed.
  15
  16 The purpose of the mounting matrix is to translate the sensor frame of
  17 reference into the device frame of reference using a translation matrix as
  18 defined in linear algebra.
  19
  20 The typical usecase is that where a component has an internal representation
  21 of the (x,y,z) triplets, such as different registers to read these coordinates,
  22 and thus implying that the component should be mounted in a certain orientation
  23 relative to some specific device frame of reference.
  24
  25 For example a device with some kind of screen, where the user is supposed to
  26 interact with the environment using an accelerometer, gyroscope or magnetometer
  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) corresponding to these axes on the
  29 screen and (z) being depth, the axis perpendicular to the screen.
  30
  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 the bottom to positive on top
  33 and (z) depth to be negative under the screen and positive in front of it,
  34 toward the face of the user.
  35
  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 flipped upside-down, left-right,
  38 or tilted at any angle relative to the frame of reference.
  39
  40 Another frame of reference is how the device with its sensor relates to the
  41 external world, the environment where the device is deployed. Usually the data
  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, the sensor and device orientation
  44 becomes identical and we can focus on the data as it relates to the surrounding
  45 world.
  46
  47 Device-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
 150 So unless the sensor is ideally mounted, we need a means to indicate the
 151 relative orientation of any given sensor of this type with respect to the
 152 frame of reference.
 153
 154 To achieve this, use the device tree property "mount-matrix" for the sensor.
 155
 156 This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
 157 to orient the senor axes relative to a desired point of reference. This means
 158 the resulting values from the sensor, after scaling to proper units, should be
 159 multiplied by this matrix to give the proper vectors values in three-dimensional
 160 space, relative to the device or world point of reference.
 161
 162 For more information, consult:
 163 https://en.wikipedia.org/wiki/Rotation_matrix
 164
 165 The mounting matrix has the layout:
 166
 167  (mxx, myx, mzx)
 168  (mxy, myy, mzy)
 169  (mxz, myz, mzz)
 170
 171 Values 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
 177 It is represented as an array of strings containing the real values for
 178 producing the transformation matrix.
 179
 180 Examples:
 181
 182 Identity matrix (nothing happens to the coordinates, which means the device was
 183 mechanically mounted in an ideal way and we need no transformation):
 184
 185 mount-matrix = "1", "0", "0",
 186                "0", "1", "0",
 187                "0", "0", "1";
 188
 189 The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
 190 compensate by performing a -30 degrees rotation around the X axis:
 191
 192 mount-matrix = "1", "0", "0",
 193                "0", "0.866", "0.5",
 194                "0", "-0.5", "0.866";
 195
 196 The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
 197 upside-down:
 198
 199 mount-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