[PATCH 2/9] iio: bindings: clarifications for mount-matrix bindings

[H. Nikolaus Schaller]

This adds some clarifications and drawings to make the
orientation of the X/Y/Z axis more clear and better
prescribe how the values of the matrix are intended to
be used.

Signed-off-by: H. Nikolaus Schaller <hns@xxxxxxxxxxxxx>
---
 .../devicetree/bindings/iio/mount-matrix.txt  | 60 ++++++++++++++++++-
 1 file changed, 57 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
index a3714727f739..003279fd735b 100644
--- a/Documentation/devicetree/bindings/iio/mount-matrix.txt
+++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
@@ -23,6 +23,8 @@ For a screen you probably want (x) coordinates to go from negative on the left
 to positive on the right and (z) depth to be negative under the screen and
 positive in front of it, toward the face of the user.
 
+??? whatabout y-axis orientation - bottop-up or top-down?
+
 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.
@@ -46,6 +48,20 @@ Device-to-world examples for some three-dimensional sensor types:
   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.
 
+
+     (---------)
+     !         !           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
@@ -53,6 +69,22 @@ Device-to-world examples for some three-dimensional sensor types:
   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  # !
+     (---------)
+
+
 - 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
@@ -60,6 +92,20 @@ Device-to-world examples for some three-dimensional sensor types:
   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.
@@ -76,9 +122,15 @@ https://en.wikipedia.org/wiki/Rotation_matrix
 
 The mounting matrix has the layout:
 
- (x0, y0, z0)
- (x1, y1, z1)
- (x2, y2, z3)
+ (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
 
 And it is represented as an array of strings containing the real values for
 producing the transformation matrix. The real values use a decimal point and
@@ -106,3 +158,5 @@ upside-down:
 mount-matrix = "0.998", "0.054", "0",
                "-0.054", "0.998", "0",
                "0", "0", "1";
+
+??? does not match "180 degrees" - factors indicate ca. 3 degrees compensation
-- 
2.19.1