[PATCH] iio: document bindings for mounting matrixes

[PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

The mounting matrix for sensors was introduced in
commit dfc57732ad38 ("iio:core: mounting matrix support")

However the device tree bindings are very terse and since this is
a widely applicable property, we need a proper binding for it
that the other bindings can reference. This will also be useful
for other operating systems and sensor engineering at large.

I think all 3D sensors should support it, the current situation
is probably that the mounting information is confined in magic
userspace components rather than using the mounting matrix, which
is not good for portability and reuse.

Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
---
Please help out to get this right, I think this could be confusing
to users unless documented properly. I think the doc has some rough
edges since I'm not the smartest in physics nor english at all times.
---
 .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt

diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
new file mode 100644
index 000000000000..3e72c92c5689
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
@@ -0,0 +1,104 @@
+Mounting matrix
+
+The mounting matrix is a device tree property used to orient any IIO device
+that produce three-dimensional data.
+
+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 point of reference.
+
+For example a device with some kind of screen, where the user is supposed to
+interact with the environment using a 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.
+
+The axes may also be flipped: 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.
+
+Apart from flipping, a sensor can of course also be mounted in any angle along
+the axes relative to the point of reference. This means that the axes may be
+not only flipped, but tilted.
+
+Examples for some three-dimensional sensor types:
+
+- Accelerometers have their frame of reference is toward the center of gravity,
+  usually to the core of the planet, and users would likely expect a value of
+  9.81N upwards along the (z) axis when the device is held with its screen
+  perpendicular to the planets surface and 0 on the other axes. A reading of
+  the (x,y,z) values will give the orientation of the device relative to the
+  center of the planet, i.e. relative to its surface at this point. Up and down
+  relative to the point of reference can thus be determined.
+
+- Magnetometers (compasses) have their frame of reference relative to the
+  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
+  hardware orientation 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.
+
+- Gyroscopes detects the movement relative the device itself, and has no other
+  frame of reference than the mounting chassis itself. The angular momentum 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 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.
+
+So unless the sensor is ideally mounted, we need a means to indicate the
+relative orientation of any given sensor of this type.
+
+To achieve this, use the device tree property "mount-matrix" for the sensor.
+This supplies a 3x3 transformation 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 coordinates in three-dimensional
+space, relative to some relevant point of reference.
+
+The mounting matrix has the layout:
+
+ (x0, y0, z0)
+ (x1, y1, z1)
+ (x2, y2, z3)
+
+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
+a minus (-) to indicate a negative value.
+
+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";
+
+Flipped X axis (negative values means positive):
+
+mount-matrix = "-1", "0", "0",
+               "0", "1", "0",
+               "0", "0", "1";
+
+X and Y flipped (X values are for Y and Y values are for X):
+
+mount-matrix = "0", "1", "0",
+               "1", "0", "0",
+               "0", "0", "1";
+
+Complex angular mounting with X and Z in a certain tilted orienation and
+Y flipped:
+
+mount-matrix = "-0.984807753012208",  /* x0 */
+               "0",                   /* y0 */
+               "-0.173648177666930",  /* z0 */
+               "0",                   /* x1 */
+               "-1",                  /* y1 */
+               "0",                   /* z1 */
+               "-0.173648177666930",  /* x2 */
+               "0",                   /* y2 */
+               "0.984807753012208";   /* z2 */
-- 
2.7.4

[PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

The mounting matrix for sensors was introduced in
commit dfc57732ad38 ("iio:core: mounting matrix support")

However the device tree bindings are very terse and since this is
a widely applicable property, we need a proper binding for it
that the other bindings can reference. This will also be useful
for other operating systems and sensor engineering at large.

I think all 3D sensors should support it, the current situation
is probably that the mounting information is confined in magic
userspace components rather than using the mounting matrix, which
is not good for portability and reuse.

Cc: Gregor Boirie <gregor.boirie@parrot.com>
Cc: Sebastian Reichel <sre@kernel.org>
Cc: Samu Onkalo <samu.onkalo@intel.com>
Cc: devicetree@vger.kernel.org
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
Please help out to get this right, I think this could be confusing
to users unless documented properly. I think the doc has some rough
edges since I'm not the smartest in physics nor english at all times.
---
 .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt

diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
new file mode 100644
index 000000000000..3e72c92c5689
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
@@ -0,0 +1,104 @@
+Mounting matrix
+
+The mounting matrix is a device tree property used to orient any IIO device
+that produce three-dimensional data.
+
+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 point of reference.
+
+For example a device with some kind of screen, where the user is supposed to
+interact with the environment using a 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.
+
+The axes may also be flipped: 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.
+
+Apart from flipping, a sensor can of course also be mounted in any angle along
+the axes relative to the point of reference. This means that the axes may be
+not only flipped, but tilted.
+
+Examples for some three-dimensional sensor types:
+
+- Accelerometers have their frame of reference is toward the center of gravity,
+  usually to the core of the planet, and users would likely expect a value of
+  9.81N upwards along the (z) axis when the device is held with its screen
+  perpendicular to the planets surface and 0 on the other axes. A reading of
+  the (x,y,z) values will give the orientation of the device relative to the
+  center of the planet, i.e. relative to its surface at this point. Up and down
+  relative to the point of reference can thus be determined.
+
+- Magnetometers (compasses) have their frame of reference relative to the
+  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
+  hardware orientation 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.
+
+- Gyroscopes detects the movement relative the device itself, and has no other
+  frame of reference than the mounting chassis itself. The angular momentum 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 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.
+
+So unless the sensor is ideally mounted, we need a means to indicate the
+relative orientation of any given sensor of this type.
+
+To achieve this, use the device tree property "mount-matrix" for the sensor.
+This supplies a 3x3 transformation 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 coordinates in three-dimensional
+space, relative to some relevant point of reference.
+
+The mounting matrix has the layout:
+
+ (x0, y0, z0)
+ (x1, y1, z1)
+ (x2, y2, z3)
+
+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
+a minus (-) to indicate a negative value.
+
+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";
+
+Flipped X axis (negative values means positive):
+
+mount-matrix = "-1", "0", "0",
+               "0", "1", "0",
+               "0", "0", "1";
+
+X and Y flipped (X values are for Y and Y values are for X):
+
+mount-matrix = "0", "1", "0",
+               "1", "0", "0",
+               "0", "0", "1";
+
+Complex angular mounting with X and Z in a certain tilted orienation and
+Y flipped:
+
+mount-matrix = "-0.984807753012208",  /* x0 */
+               "0",                   /* y0 */
+               "-0.173648177666930",  /* z0 */
+               "0",                   /* x1 */
+               "-1",                  /* y1 */
+               "0",                   /* z1 */
+               "-0.173648177666930",  /* x2 */
+               "0",                   /* y2 */
+               "0.984807753012208";   /* z2 */
-- 
2.7.4

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 24/07/16 11:17, Linus Walleij wrote:
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
> ---
> Please help out to get this right, I think this could be confusing
> to users unless documented properly. I think the doc has some rough
> edges since I'm not the smartest in physics nor english at all times.
Note that there is rather more substantial documentation in the
sysfs abi docs.

Documentation/ABI/testing/sysfs-bus-iio

That's not to say we shouldn't have better docs for the
binding, but rather that we should make sure they agree ;)

I'll try and take a look through this later in the week.

Jonathan
> ---
>  .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>  1 file changed, 104 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
> 
> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> new file mode 100644
> index 000000000000..3e72c92c5689
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> @@ -0,0 +1,104 @@
> +Mounting matrix
> +
> +The mounting matrix is a device tree property used to orient any IIO device
> +that produce three-dimensional data.
> +
> +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 point of reference.
> +
> +For example a device with some kind of screen, where the user is supposed to
> +interact with the environment using a 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.
> +
> +The axes may also be flipped: 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.
> +
> +Apart from flipping, a sensor can of course also be mounted in any angle along
> +the axes relative to the point of reference. This means that the axes may be
> +not only flipped, but tilted.
> +
> +Examples for some three-dimensional sensor types:
> +
> +- Accelerometers have their frame of reference is toward the center of gravity,
> +  usually to the core of the planet, and users would likely expect a value of
> +  9.81N upwards along the (z) axis when the device is held with its screen
> +  perpendicular to the planets surface and 0 on the other axes. A reading of
> +  the (x,y,z) values will give the orientation of the device relative to the
> +  center of the planet, i.e. relative to its surface at this point. Up and down
> +  relative to the point of reference can thus be determined.
> +
> +- Magnetometers (compasses) have their frame of reference relative to the
> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
> +  hardware orientation 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.
> +
> +- Gyroscopes detects the movement relative the device itself, and has no other
> +  frame of reference than the mounting chassis itself. The angular momentum 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 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.
> +
> +So unless the sensor is ideally mounted, we need a means to indicate the
> +relative orientation of any given sensor of this type.
> +
> +To achieve this, use the device tree property "mount-matrix" for the sensor.
> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
> +space, relative to some relevant point of reference.
> +
> +The mounting matrix has the layout:
> +
> + (x0, y0, z0)
> + (x1, y1, z1)
> + (x2, y2, z3)
> +
> +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
> +a minus (-) to indicate a negative value.
> +
> +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";
> +
> +Flipped X axis (negative values means positive):
> +
> +mount-matrix = "-1", "0", "0",
> +               "0", "1", "0",
> +               "0", "0", "1";
> +
> +X and Y flipped (X values are for Y and Y values are for X):
> +
> +mount-matrix = "0", "1", "0",
> +               "1", "0", "0",
> +               "0", "0", "1";
> +
> +Complex angular mounting with X and Z in a certain tilted orienation and
> +Y flipped:
> +
> +mount-matrix = "-0.984807753012208",  /* x0 */
> +               "0",                   /* y0 */
> +               "-0.173648177666930",  /* z0 */
> +               "0",                   /* x1 */
> +               "-1",                  /* y1 */
> +               "0",                   /* z1 */
> +               "-0.173648177666930",  /* x2 */
> +               "0",                   /* y2 */
> +               "0.984807753012208";   /* z2 */
> 

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 24/07/16 11:17, Linus Walleij wrote:
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> ---
> Please help out to get this right, I think this could be confusing
> to users unless documented properly. I think the doc has some rough
> edges since I'm not the smartest in physics nor english at all times.
Note that there is rather more substantial documentation in the
sysfs abi docs.

Documentation/ABI/testing/sysfs-bus-iio

That's not to say we shouldn't have better docs for the
binding, but rather that we should make sure they agree ;)

I'll try and take a look through this later in the week.

Jonathan
> ---
>  .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>  1 file changed, 104 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
> 
> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> new file mode 100644
> index 000000000000..3e72c92c5689
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> @@ -0,0 +1,104 @@
> +Mounting matrix
> +
> +The mounting matrix is a device tree property used to orient any IIO device
> +that produce three-dimensional data.
> +
> +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 point of reference.
> +
> +For example a device with some kind of screen, where the user is supposed to
> +interact with the environment using a 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.
> +
> +The axes may also be flipped: 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.
> +
> +Apart from flipping, a sensor can of course also be mounted in any angle along
> +the axes relative to the point of reference. This means that the axes may be
> +not only flipped, but tilted.
> +
> +Examples for some three-dimensional sensor types:
> +
> +- Accelerometers have their frame of reference is toward the center of gravity,
> +  usually to the core of the planet, and users would likely expect a value of
> +  9.81N upwards along the (z) axis when the device is held with its screen
> +  perpendicular to the planets surface and 0 on the other axes. A reading of
> +  the (x,y,z) values will give the orientation of the device relative to the
> +  center of the planet, i.e. relative to its surface at this point. Up and down
> +  relative to the point of reference can thus be determined.
> +
> +- Magnetometers (compasses) have their frame of reference relative to the
> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
> +  hardware orientation 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.
> +
> +- Gyroscopes detects the movement relative the device itself, and has no other
> +  frame of reference than the mounting chassis itself. The angular momentum 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 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.
> +
> +So unless the sensor is ideally mounted, we need a means to indicate the
> +relative orientation of any given sensor of this type.
> +
> +To achieve this, use the device tree property "mount-matrix" for the sensor.
> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
> +space, relative to some relevant point of reference.
> +
> +The mounting matrix has the layout:
> +
> + (x0, y0, z0)
> + (x1, y1, z1)
> + (x2, y2, z3)
> +
> +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
> +a minus (-) to indicate a negative value.
> +
> +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";
> +
> +Flipped X axis (negative values means positive):
> +
> +mount-matrix = "-1", "0", "0",
> +               "0", "1", "0",
> +               "0", "0", "1";
> +
> +X and Y flipped (X values are for Y and Y values are for X):
> +
> +mount-matrix = "0", "1", "0",
> +               "1", "0", "0",
> +               "0", "0", "1";
> +
> +Complex angular mounting with X and Z in a certain tilted orienation and
> +Y flipped:
> +
> +mount-matrix = "-0.984807753012208",  /* x0 */
> +               "0",                   /* y0 */
> +               "-0.173648177666930",  /* z0 */
> +               "0",                   /* x1 */
> +               "-1",                  /* y1 */
> +               "0",                   /* z1 */
> +               "-0.173648177666930",  /* x2 */
> +               "0",                   /* y2 */
> +               "0.984807753012208";   /* z2 */
> 

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Sun, Jul 24, 2016 at 9:03 PM, Jonathan Cameron <jic23-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:

>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
>
> Note that there is rather more substantial documentation in the
> sysfs abi docs.
>
> Documentation/ABI/testing/sysfs-bus-iio

Yes I used that actually, for the magnetometer example.

Thanks anyways!

> That's not to say we shouldn't have better docs for the
> binding, but rather that we should make sure they agree ;)

Yes, this is mainly for establishing terminology, as the DT bindings
are (in theory, mind you) a standards document used by other
operating systems as well.

There are some problems with the Linux implementation,
primarily that it is "opt-in per driver" and I think it would make
sense to try to enable it by default for any 3-axis 3D things
and move all code to a central spot, if possible. I also think
we should patch generic_buffer to make use of the mount
matrix if it finds one. (I know, talk is cheap, show me the
code, it's all on my TODO list.)

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Sun, Jul 24, 2016 at 9:03 PM, Jonathan Cameron <jic23@kernel.org> wrote:

>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
>
> Note that there is rather more substantial documentation in the
> sysfs abi docs.
>
> Documentation/ABI/testing/sysfs-bus-iio

Yes I used that actually, for the magnetometer example.

Thanks anyways!

> That's not to say we shouldn't have better docs for the
> binding, but rather that we should make sure they agree ;)

Yes, this is mainly for establishing terminology, as the DT bindings
are (in theory, mind you) a standards document used by other
operating systems as well.

There are some problems with the Linux implementation,
primarily that it is "opt-in per driver" and I think it would make
sense to try to enable it by default for any 3-axis 3D things
and move all code to a central spot, if possible. I also think
we should patch generic_buffer to make use of the mount
matrix if it finds one. (I know, talk is cheap, show me the
code, it's all on my TODO list.)

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Gregor Boirie]

Linus, Jonathan,

On 07/24/2016 09:03 PM, Jonathan Cameron wrote:
> On 24/07/16 11:17, Linus Walleij wrote:
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
>> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
>> ---
>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
> Note that there is rather more substantial documentation in the
> sysfs abi docs.
>
> Documentation/ABI/testing/sysfs-bus-iio
Description of mounting matrix DT property structure was probably missing,
i.e. how coefficients are mapped along which axes, floating point format,
etc...

However I'm wondering how to ensure consistent documentation between sysfs
iio ABI and DT binding since there will be duplicates at some point.
Cross-refering Documentation/devicetree/bindings/iio/mount-matrix.txt within
Documentation/ABI/testing/sysfs-bus-iio might be an option since "DT 
bindings
are (in theory, mind you) a standards document used by other" as Linus said.

>
> That's not to say we shouldn't have better docs for the
> binding, but rather that we should make sure they agree ;)
>
> I'll try and take a look through this later in the week.
>
> Jonathan
>> ---
>>   .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>>   1 file changed, 104 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>>
>> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> new file mode 100644
>> index 000000000000..3e72c92c5689
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> @@ -0,0 +1,104 @@
>> +Mounting matrix
>> +
>> +The mounting matrix is a device tree property used to orient any IIO device
>> +that produce three-dimensional data.
>> +
>> +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 point of reference.
>> +
>> +For example a device with some kind of screen, where the user is supposed to
>> +interact with the environment using a 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.
>> +
>> +The axes may also be flipped: 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.
>> +
>> +Apart from flipping, a sensor can of course also be mounted in any angle along
>> +the axes relative to the point of reference. This means that the axes may be
>> +not only flipped, but tilted.
>> +
>> +Examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their frame of reference is toward the center of gravity,
>> +  usually to the core of the planet, and users would likely expect a value of
>> +  9.81N upwards along the (z) axis when the device is held with its screen
>> +  perpendicular to the planets surface and 0 on the other axes. A reading of
>> +  the (x,y,z) values will give the orientation of the device relative to the
>> +  center of the planet, i.e. relative to its surface at this point. Up and down
>> +  relative to the point of reference can thus be determined.
>> +
>> +- Magnetometers (compasses) have their frame of reference relative to the
>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>> +  hardware orientation 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.
>> +
>> +- Gyroscopes detects the movement relative the device itself, and has no other
>> +  frame of reference than the mounting chassis itself. The angular momentum 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 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.
>> +
>> +So unless the sensor is ideally mounted, we need a means to indicate the
>> +relative orientation of any given sensor of this type.
>> +
>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
>> +space, relative to some relevant point of reference.
>> +
>> +The mounting matrix has the layout:
>> +
>> + (x0, y0, z0)
>> + (x1, y1, z1)
>> + (x2, y2, z3)
>> +
>> +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
>> +a minus (-) to indicate a negative value.
>> +
>> +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";
>> +
>> +Flipped X axis (negative values means positive):
>> +
>> +mount-matrix = "-1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
>> +
>> +X and Y flipped (X values are for Y and Y values are for X):
>> +
>> +mount-matrix = "0", "1", "0",
>> +               "1", "0", "0",
>> +               "0", "0", "1";
>> +
>> +Complex angular mounting with X and Z in a certain tilted orienation and
>> +Y flipped:
>> +
>> +mount-matrix = "-0.984807753012208",  /* x0 */
>> +               "0",                   /* y0 */
>> +               "-0.173648177666930",  /* z0 */
>> +               "0",                   /* x1 */
>> +               "-1",                  /* y1 */
>> +               "0",                   /* z1 */
>> +               "-0.173648177666930",  /* x2 */
>> +               "0",                   /* y2 */
>> +               "0.984807753012208";   /* z2 */
>>

Re: [PATCH] iio: document bindings for mounting matrixes

[Gregor Boirie]

Linus, Jonathan,

On 07/24/2016 09:03 PM, Jonathan Cameron wrote:
> On 24/07/16 11:17, Linus Walleij wrote:
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie@parrot.com>
>> Cc: Sebastian Reichel <sre@kernel.org>
>> Cc: Samu Onkalo <samu.onkalo@intel.com>
>> Cc: devicetree@vger.kernel.org
>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>> ---
>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
> Note that there is rather more substantial documentation in the
> sysfs abi docs.
>
> Documentation/ABI/testing/sysfs-bus-iio
Description of mounting matrix DT property structure was probably missing,
i.e. how coefficients are mapped along which axes, floating point format,
etc...

However I'm wondering how to ensure consistent documentation between sysfs
iio ABI and DT binding since there will be duplicates at some point.
Cross-refering Documentation/devicetree/bindings/iio/mount-matrix.txt within
Documentation/ABI/testing/sysfs-bus-iio might be an option since "DT 
bindings
are (in theory, mind you) a standards document used by other" as Linus said.

>
> That's not to say we shouldn't have better docs for the
> binding, but rather that we should make sure they agree ;)
>
> I'll try and take a look through this later in the week.
>
> Jonathan
>> ---
>>   .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>>   1 file changed, 104 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>>
>> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> new file mode 100644
>> index 000000000000..3e72c92c5689
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> @@ -0,0 +1,104 @@
>> +Mounting matrix
>> +
>> +The mounting matrix is a device tree property used to orient any IIO device
>> +that produce three-dimensional data.
>> +
>> +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 point of reference.
>> +
>> +For example a device with some kind of screen, where the user is supposed to
>> +interact with the environment using a 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.
>> +
>> +The axes may also be flipped: 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.
>> +
>> +Apart from flipping, a sensor can of course also be mounted in any angle along
>> +the axes relative to the point of reference. This means that the axes may be
>> +not only flipped, but tilted.
>> +
>> +Examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their frame of reference is toward the center of gravity,
>> +  usually to the core of the planet, and users would likely expect a value of
>> +  9.81N upwards along the (z) axis when the device is held with its screen
>> +  perpendicular to the planets surface and 0 on the other axes. A reading of
>> +  the (x,y,z) values will give the orientation of the device relative to the
>> +  center of the planet, i.e. relative to its surface at this point. Up and down
>> +  relative to the point of reference can thus be determined.
>> +
>> +- Magnetometers (compasses) have their frame of reference relative to the
>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>> +  hardware orientation 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.
>> +
>> +- Gyroscopes detects the movement relative the device itself, and has no other
>> +  frame of reference than the mounting chassis itself. The angular momentum 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 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.
>> +
>> +So unless the sensor is ideally mounted, we need a means to indicate the
>> +relative orientation of any given sensor of this type.
>> +
>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
>> +space, relative to some relevant point of reference.
>> +
>> +The mounting matrix has the layout:
>> +
>> + (x0, y0, z0)
>> + (x1, y1, z1)
>> + (x2, y2, z3)
>> +
>> +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
>> +a minus (-) to indicate a negative value.
>> +
>> +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";
>> +
>> +Flipped X axis (negative values means positive):
>> +
>> +mount-matrix = "-1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
>> +
>> +X and Y flipped (X values are for Y and Y values are for X):
>> +
>> +mount-matrix = "0", "1", "0",
>> +               "1", "0", "0",
>> +               "0", "0", "1";
>> +
>> +Complex angular mounting with X and Z in a certain tilted orienation and
>> +Y flipped:
>> +
>> +mount-matrix = "-0.984807753012208",  /* x0 */
>> +               "0",                   /* y0 */
>> +               "-0.173648177666930",  /* z0 */
>> +               "0",                   /* x1 */
>> +               "-1",                  /* y1 */
>> +               "0",                   /* z1 */
>> +               "-0.173648177666930",  /* x2 */
>> +               "0",                   /* y2 */
>> +               "0.984807753012208";   /* z2 */
>>

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Mon, Jul 25, 2016 at 2:48 PM, Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org> wrote:

> I'm wondering how to ensure consistent documentation between sysfs
> iio ABI and DT binding since there will be duplicates at some point.
> Cross-refering Documentation/devicetree/bindings/iio/mount-matrix.txt within
> Documentation/ABI/testing/sysfs-bus-iio might be an option since "DT
> bindings
> are (in theory, mind you) a standards document used by other" as Linus said.

That's my position on the issue, if the documents should refer each other
in any direction the sysfs should reference the DT bindings.

(Maybe someone will slap me for this...)

Yours.
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Mon, Jul 25, 2016 at 2:48 PM, Gregor Boirie <gregor.boirie@parrot.com> wrote:

> I'm wondering how to ensure consistent documentation between sysfs
> iio ABI and DT binding since there will be duplicates at some point.
> Cross-refering Documentation/devicetree/bindings/iio/mount-matrix.txt within
> Documentation/ABI/testing/sysfs-bus-iio might be an option since "DT
> bindings
> are (in theory, mind you) a standards document used by other" as Linus said.

That's my position on the issue, if the documents should refer each other
in any direction the sysfs should reference the DT bindings.

(Maybe someone will slap me for this...)

Yours.
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Rob Herring]

On Sun, Jul 24, 2016 at 12:17:14PM +0200, Linus Walleij wrote:
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
> ---
> Please help out to get this right, I think this could be confusing
> to users unless documented properly. I think the doc has some rough
> edges since I'm not the smartest in physics nor english at all times.
> ---

I can at least say I understand how it's supposed to work better now.

Acked-by: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>

On the duplication topic, of course I agree that sysfs docs should refer 
to DT and not vice-versa.

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] iio: document bindings for mounting matrixes

[Rob Herring]

On Sun, Jul 24, 2016 at 12:17:14PM +0200, Linus Walleij wrote:
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> ---
> Please help out to get this right, I think this could be confusing
> to users unless documented properly. I think the doc has some rough
> edges since I'm not the smartest in physics nor english at all times.
> ---

I can at least say I understand how it's supposed to work better now.

Acked-by: Rob Herring <robh@kernel.org>

On the duplication topic, of course I agree that sysfs docs should refer 
to DT and not vice-versa.

Rob

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 26/07/16 20:07, Rob Herring wrote:
> On Sun, Jul 24, 2016 at 12:17:14PM +0200, Linus Walleij wrote:
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
>> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
>> ---
>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
>> ---
> 
> I can at least say I understand how it's supposed to work better now.
> 
> Acked-by: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> 
> On the duplication topic, of course I agree that sysfs docs should refer 
> to DT and not vice-versa.
I'd be tempted to keep a 'full' documentation of all the relevant aspects
in each place, but make sure there is a cross reference from the sysfs
ABI docs to the device tree ones as has been suggested.
(rather than converting the sysfs docs just a cross reference + note
on how the bindings and attribute are related).
> 
> Rob
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 26/07/16 20:07, Rob Herring wrote:
> On Sun, Jul 24, 2016 at 12:17:14PM +0200, Linus Walleij wrote:
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie@parrot.com>
>> Cc: Sebastian Reichel <sre@kernel.org>
>> Cc: Samu Onkalo <samu.onkalo@intel.com>
>> Cc: devicetree@vger.kernel.org
>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>> ---
>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
>> ---
> 
> I can at least say I understand how it's supposed to work better now.
> 
> Acked-by: Rob Herring <robh@kernel.org>
> 
> On the duplication topic, of course I agree that sysfs docs should refer 
> to DT and not vice-versa.
I'd be tempted to keep a 'full' documentation of all the relevant aspects
in each place, but make sure there is a cross reference from the sysfs
ABI docs to the device tree ones as has been suggested.
(rather than converting the sysfs docs just a cross reference + note
on how the bindings and attribute are related).
> 
> Rob
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Sun, Jul 24, 2016 at 12:17 PM, Linus Walleij
<linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:

> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
>
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
>
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
>
> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>

AFAICT there is no comments on this patch per se, just chit chat
about misc, and we have Rob's ACK.

Can it be merged?

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Sun, Jul 24, 2016 at 12:17 PM, Linus Walleij
<linus.walleij@linaro.org> wrote:

> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
>
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
>
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
>
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

AFAICT there is no comments on this patch per se, just chit chat
about misc, and we have Rob's ACK.

Can it be merged?

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 11/08/16 12:33, Linus Walleij wrote:
> On Sun, Jul 24, 2016 at 12:17 PM, Linus Walleij
> <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:
> 
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
>> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
> 
> AFAICT there is no comments on this patch per se, just chit chat
> about misc, and we have Rob's ACK.
> 
> Can it be merged?
> 
I failed to actually look at it properly so far...

I'd also like input from Gregor as his usecase is somewhat different
and drove the sysfs docs.  They need to agree and I haven't actually
verified they do as yet!

Also for trivial comments, plural of matrix is matrices.
Isn't English weird sometimes ;)

Jonathan
> Yours,
> Linus Walleij
> 

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 11/08/16 12:33, Linus Walleij wrote:
> On Sun, Jul 24, 2016 at 12:17 PM, Linus Walleij
> <linus.walleij@linaro.org> wrote:
> 
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie@parrot.com>
>> Cc: Sebastian Reichel <sre@kernel.org>
>> Cc: Samu Onkalo <samu.onkalo@intel.com>
>> Cc: devicetree@vger.kernel.org
>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> 
> AFAICT there is no comments on this patch per se, just chit chat
> about misc, and we have Rob's ACK.
> 
> Can it be merged?
> 
I failed to actually look at it properly so far...

I'd also like input from Gregor as his usecase is somewhat different
and drove the sysfs docs.  They need to agree and I haven't actually
verified they do as yet!

Also for trivial comments, plural of matrix is matrices.
Isn't English weird sometimes ;)

Jonathan
> Yours,
> Linus Walleij
> 

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Mon, Aug 15, 2016 at 4:58 PM, Jonathan Cameron <jic23-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:

> I'd also like input from Gregor as his usecase is somewhat different
> and drove the sysfs docs.  They need to agree and I haven't actually
> verified they do as yet!

OK I actually copy-pasted from the sysfs docs for the compass,
but it's good to have him look at it first indeed.

I hope it's OK if I refer to this doc in other patches assuming we
will merge something like it.

> Also for trivial comments, plural of matrix is matrices.
> Isn't English weird sometimes ;)

Aha another irregularity... OK I will fix up when collecting the
feedback.

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Mon, Aug 15, 2016 at 4:58 PM, Jonathan Cameron <jic23@kernel.org> wrote:

> I'd also like input from Gregor as his usecase is somewhat different
> and drove the sysfs docs.  They need to agree and I haven't actually
> verified they do as yet!

OK I actually copy-pasted from the sysfs docs for the compass,
but it's good to have him look at it first indeed.

I hope it's OK if I refer to this doc in other patches assuming we
will merge something like it.

> Also for trivial comments, plural of matrix is matrices.
> Isn't English weird sometimes ;)

Aha another irregularity... OK I will fix up when collecting the
feedback.

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Gregor Boirie]

Linus, Jonathan,

my little bit there... at last. comments in line.


On 08/21/2016 05:56 PM, Jonathan Cameron wrote:
> On 24/07/16 11:17, Linus Walleij wrote:
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
>> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
> Hi Linus,
>
> Sorry I took so long to get to this...
> (out of curiosity are you running a fifo queue of patches? Every time
> I review and merge one, another one turns up in my inbox :)
>> ---
>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
>> ---
> I think we have quite a bit of confusion of measurement frames here.
> (it always confused me when I was doing day to day work with these - now
> I'm decidedly rusty!)
>>   .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>>   1 file changed, 104 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>>
>> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> new file mode 100644
>> index 000000000000..3e72c92c5689
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> @@ -0,0 +1,104 @@
>> +Mounting matrix
>> +
>> +The mounting matrix is a device tree property used to orient any IIO device
>> +that produce three-dimensional data.
>> +
>> +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 point of reference.
> point of reference -> device frame of reference.
+1.
Makes me think we should probably use the same terminology in DT 
bindings and
IIO ABI docs.
What Jonathan calls "device frame of reference" was named as "main hardware
reference frame" in IIO docs. For fixed wings UAVs the most common term 
would
be "body frame".
I think we should pick one and stick with it.

Moreover as, told below, we have to make a clear distinction between 
"world",
"device/main hardware" and "sensor" reference frames.
>> +
>> +For example a device with some kind of screen, where the user is supposed to
>> +interact with the environment using a 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.
> Good description.
>> +
>> +The axes may also be flipped: 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.
> I'm not sure we don't want to define that it can't be flipped and enforce the
> correct coordinate system on the underlying drivers (fingers crossed they are
> currently all left or all right handed? - oops should have been keeping an eye on
> this).
As to coordinate system definition, multiple conventions seem to exist 
across
industries. For UAV, we use the one described here:
https://en.wikipedia.org/wiki/Flight_dynamics_(fixed-wing_aircraft)

So I feel like we should keep away from any temptation to define the 
coordinates
system too strictly.
I also think of systems composed of multiple hardware parts with sensors
scattered all over them. What would be the right "device/main hardware" 
reference
frame definition in these cases ?
As this is product specific, I feel like "device/main hardware" 
reference frame
definition should be left to the "board/main hardware/device..." 
implementor's
choice.
>> +
>> +Apart from flipping, a sensor can of course also be mounted in any angle along
>> +the axes relative to the point of reference. This means that the axes may be
>> +not only flipped, but tilted.
> Just define it as a frame of reference, rather than a point and axis.  Frame hides
> all evils ;)
+1
> For now we are being a bit simplistic as for accelerometers at least, it can be
> of interest to know the translation as well as the rotation.  You can use a couple
> of them to do fairly precise rotation estimate if they are located in different
> places on a device.
>
>> +
>> +Examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their frame of reference
> Not quite right.  Their frame of reference is in the frame of the device - it has
> nothing to do with the world frame which you are describing here (except when
> the device is deliberate oriented to match.
>
> So we have 3 frames - that of the sensor, that of the device and that of the world.
>
> Sensor --<mounting matrix transform>--> Device frame --<Device to world transform> -->
> world frame.
> For the static no motion cases - when moving the acceleration needs to take into account
> what the motion is etc (magnetometer doesn't).
+1

[snip....]

Except for the above mentioned points, I'm happy with the rest of the
description.

best regards,
Grég.

> All the below kind of merge the mounting matrix transform with the device to world
> transform and leave me at least somewhat confused :)
>
>   is toward the center of gravity,
>> +  usually to the core of the planet, and users would likely expect a value of
>> +  9.81N upwards along the (z) axis when the device is held with its screen
>> +  perpendicular to the planets surface and 0 on the other axes.
> I'd have thought screen parallel  - i.e. z is out of the screen?
> Might be the same thing I suppose, but I'd define it simply as into the screen
> then y towards top of screen and x from left to right of the screen.
>   A reading of
>> +  the (x,y,z) values will give the orientation of the device relative to the
>> +  center of the planet, i.e. relative to its surface at this point. Up and down
>> +  relative to the point of reference can thus be determined.
> Will give a project of the gravity vector onto the axis of the sensor. There
> is I think a world to local frame transform missing here...
>
>> +
>> +- Magnetometers (compasses) have their frame of reference relative to the
>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>> +  hardware orientation 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.
> Same issue, world to frame transform is not included...
>> +
>> +- Gyroscopes detects the movement relative the device itself, and has no other
>> +  frame of reference than the mounting chassis itself.
> This is true for all of them as far as we are concerned here...
>> The angular momentum is
> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
> of change of rotation about an axis (lets ignore the significant cross talk and
> effects of linear acceleration and pretend it's all easy here ;)
>
> Rest of this description is fine.
>> +  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 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.
>> +
>> +So unless the sensor is ideally mounted, we need a means to indicate the
>> +relative orientation of any given sensor of this type.
>> +
>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
> vector values as opposed to coordinates...
>> +space, relative to some relevant point of reference.
> Within the frame of the device.
>> +
>> +The mounting matrix has the layout:
>> +
>> + (x0, y0, z0)
>> + (x1, y1, z1)
>> + (x2, y2, z3)
>> +
>> +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
>> +a minus (-) to indicate a negative value.
>> +
>> +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";
>> +
>> +Flipped X axis (negative values means positive):
>> +
>> +mount-matrix = "-1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
> Hmm. This is an odd one as it basically means the device had a right hand
> coordinate system in the first place... If that happens I think we should
> by default report the negative of the scale for that axis.
>
> We've never strictly defined a coordinate system but I think left handed
> is a good start!
>> +
>> +X and Y flipped (X values are for Y and Y values are for X):
>> +
>> +mount-matrix = "0", "1", "0",
>> +               "1", "0", "0",
>> +               "0", "0", "1";
> Same with this one, we are flipping coordinate systems.  I'd expect only
> rotation matrices to be valid mount matrices.
>> +
>> +Complex angular mounting with X and Z in a certain tilted orienation and
> orientation
>> +Y flipped:
>> +
>> +mount-matrix = "-0.984807753012208",  /* x0 */
>> +               "0",                   /* y0 */
>> +               "-0.173648177666930",  /* z0 */
>> +               "0",                   /* x1 */
>> +               "-1",                  /* y1 */
>> +               "0",                   /* z1 */
>> +               "-0.173648177666930",  /* x2 */
>> +               "0",                   /* y2 */
>> +               "0.984807753012208";   /* z2 */
>>
> Anyhow, now my head hurts.
>
> Jonathan

Re: [PATCH] iio: document bindings for mounting matrixes

[Gregor Boirie]

Linus, Jonathan,

my little bit there... at last. comments in line.


On 08/21/2016 05:56 PM, Jonathan Cameron wrote:
> On 24/07/16 11:17, Linus Walleij wrote:
>> The mounting matrix for sensors was introduced in
>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>
>> However the device tree bindings are very terse and since this is
>> a widely applicable property, we need a proper binding for it
>> that the other bindings can reference. This will also be useful
>> for other operating systems and sensor engineering at large.
>>
>> I think all 3D sensors should support it, the current situation
>> is probably that the mounting information is confined in magic
>> userspace components rather than using the mounting matrix, which
>> is not good for portability and reuse.
>>
>> Cc: Gregor Boirie <gregor.boirie@parrot.com>
>> Cc: Sebastian Reichel <sre@kernel.org>
>> Cc: Samu Onkalo <samu.onkalo@intel.com>
>> Cc: devicetree@vger.kernel.org
>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> Hi Linus,
>
> Sorry I took so long to get to this...
> (out of curiosity are you running a fifo queue of patches? Every time
> I review and merge one, another one turns up in my inbox :)
>> ---
>> Please help out to get this right, I think this could be confusing
>> to users unless documented properly. I think the doc has some rough
>> edges since I'm not the smartest in physics nor english at all times.
>> ---
> I think we have quite a bit of confusion of measurement frames here.
> (it always confused me when I was doing day to day work with these - now
> I'm decidedly rusty!)
>>   .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>>   1 file changed, 104 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>>
>> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> new file mode 100644
>> index 000000000000..3e72c92c5689
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> @@ -0,0 +1,104 @@
>> +Mounting matrix
>> +
>> +The mounting matrix is a device tree property used to orient any IIO device
>> +that produce three-dimensional data.
>> +
>> +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 point of reference.
> point of reference -> device frame of reference.
+1.
Makes me think we should probably use the same terminology in DT 
bindings and
IIO ABI docs.
What Jonathan calls "device frame of reference" was named as "main hardware
reference frame" in IIO docs. For fixed wings UAVs the most common term 
would
be "body frame".
I think we should pick one and stick with it.

Moreover as, told below, we have to make a clear distinction between 
"world",
"device/main hardware" and "sensor" reference frames.
>> +
>> +For example a device with some kind of screen, where the user is supposed to
>> +interact with the environment using a 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.
> Good description.
>> +
>> +The axes may also be flipped: 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.
> I'm not sure we don't want to define that it can't be flipped and enforce the
> correct coordinate system on the underlying drivers (fingers crossed they are
> currently all left or all right handed? - oops should have been keeping an eye on
> this).
As to coordinate system definition, multiple conventions seem to exist 
across
industries. For UAV, we use the one described here:
https://en.wikipedia.org/wiki/Flight_dynamics_(fixed-wing_aircraft)

So I feel like we should keep away from any temptation to define the 
coordinates
system too strictly.
I also think of systems composed of multiple hardware parts with sensors
scattered all over them. What would be the right "device/main hardware" 
reference
frame definition in these cases ?
As this is product specific, I feel like "device/main hardware" 
reference frame
definition should be left to the "board/main hardware/device..." 
implementor's
choice.
>> +
>> +Apart from flipping, a sensor can of course also be mounted in any angle along
>> +the axes relative to the point of reference. This means that the axes may be
>> +not only flipped, but tilted.
> Just define it as a frame of reference, rather than a point and axis.  Frame hides
> all evils ;)
+1
> For now we are being a bit simplistic as for accelerometers at least, it can be
> of interest to know the translation as well as the rotation.  You can use a couple
> of them to do fairly precise rotation estimate if they are located in different
> places on a device.
>
>> +
>> +Examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their frame of reference
> Not quite right.  Their frame of reference is in the frame of the device - it has
> nothing to do with the world frame which you are describing here (except when
> the device is deliberate oriented to match.
>
> So we have 3 frames - that of the sensor, that of the device and that of the world.
>
> Sensor --<mounting matrix transform>--> Device frame --<Device to world transform> -->
> world frame.
> For the static no motion cases - when moving the acceleration needs to take into account
> what the motion is etc (magnetometer doesn't).
+1

[snip....]

Except for the above mentioned points, I'm happy with the rest of the
description.

best regards,
Grég.

> All the below kind of merge the mounting matrix transform with the device to world
> transform and leave me at least somewhat confused :)
>
>   is toward the center of gravity,
>> +  usually to the core of the planet, and users would likely expect a value of
>> +  9.81N upwards along the (z) axis when the device is held with its screen
>> +  perpendicular to the planets surface and 0 on the other axes.
> I'd have thought screen parallel  - i.e. z is out of the screen?
> Might be the same thing I suppose, but I'd define it simply as into the screen
> then y towards top of screen and x from left to right of the screen.
>   A reading of
>> +  the (x,y,z) values will give the orientation of the device relative to the
>> +  center of the planet, i.e. relative to its surface at this point. Up and down
>> +  relative to the point of reference can thus be determined.
> Will give a project of the gravity vector onto the axis of the sensor. There
> is I think a world to local frame transform missing here...
>
>> +
>> +- Magnetometers (compasses) have their frame of reference relative to the
>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>> +  hardware orientation 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.
> Same issue, world to frame transform is not included...
>> +
>> +- Gyroscopes detects the movement relative the device itself, and has no other
>> +  frame of reference than the mounting chassis itself.
> This is true for all of them as far as we are concerned here...
>> The angular momentum is
> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
> of change of rotation about an axis (lets ignore the significant cross talk and
> effects of linear acceleration and pretend it's all easy here ;)
>
> Rest of this description is fine.
>> +  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 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.
>> +
>> +So unless the sensor is ideally mounted, we need a means to indicate the
>> +relative orientation of any given sensor of this type.
>> +
>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
> vector values as opposed to coordinates...
>> +space, relative to some relevant point of reference.
> Within the frame of the device.
>> +
>> +The mounting matrix has the layout:
>> +
>> + (x0, y0, z0)
>> + (x1, y1, z1)
>> + (x2, y2, z3)
>> +
>> +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
>> +a minus (-) to indicate a negative value.
>> +
>> +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";
>> +
>> +Flipped X axis (negative values means positive):
>> +
>> +mount-matrix = "-1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
> Hmm. This is an odd one as it basically means the device had a right hand
> coordinate system in the first place... If that happens I think we should
> by default report the negative of the scale for that axis.
>
> We've never strictly defined a coordinate system but I think left handed
> is a good start!
>> +
>> +X and Y flipped (X values are for Y and Y values are for X):
>> +
>> +mount-matrix = "0", "1", "0",
>> +               "1", "0", "0",
>> +               "0", "0", "1";
> Same with this one, we are flipping coordinate systems.  I'd expect only
> rotation matrices to be valid mount matrices.
>> +
>> +Complex angular mounting with X and Z in a certain tilted orienation and
> orientation
>> +Y flipped:
>> +
>> +mount-matrix = "-0.984807753012208",  /* x0 */
>> +               "0",                   /* y0 */
>> +               "-0.173648177666930",  /* z0 */
>> +               "0",                   /* x1 */
>> +               "-1",                  /* y1 */
>> +               "0",                   /* z1 */
>> +               "-0.173648177666930",  /* x2 */
>> +               "0",                   /* y2 */
>> +               "0.984807753012208";   /* z2 */
>>
> Anyhow, now my head hurts.
>
> Jonathan

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 24/08/16 14:18, Gregor Boirie wrote:
> Linus, Jonathan,
> 
> my little bit there... at last. comments in line.
> 
> 
> On 08/21/2016 05:56 PM, Jonathan Cameron wrote:
>> On 24/07/16 11:17, Linus Walleij wrote:
>>> The mounting matrix for sensors was introduced in
>>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>>
>>> However the device tree bindings are very terse and since this is
>>> a widely applicable property, we need a proper binding for it
>>> that the other bindings can reference. This will also be useful
>>> for other operating systems and sensor engineering at large.
>>>
>>> I think all 3D sensors should support it, the current situation
>>> is probably that the mounting information is confined in magic
>>> userspace components rather than using the mounting matrix, which
>>> is not good for portability and reuse.
>>>
>>> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
>>> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>>> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>>> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>>> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
>> Hi Linus,
>>
>> Sorry I took so long to get to this...
>> (out of curiosity are you running a fifo queue of patches? Every time
>> I review and merge one, another one turns up in my inbox :)
>>> ---
>>> Please help out to get this right, I think this could be confusing
>>> to users unless documented properly. I think the doc has some rough
>>> edges since I'm not the smartest in physics nor english at all times.
>>> ---
>> I think we have quite a bit of confusion of measurement frames here.
>> (it always confused me when I was doing day to day work with these - now
>> I'm decidedly rusty!)
>>>   .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>>>   1 file changed, 104 insertions(+)
>>>   create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>>>
>>> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>>> new file mode 100644
>>> index 000000000000..3e72c92c5689
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>>> @@ -0,0 +1,104 @@
>>> +Mounting matrix
>>> +
>>> +The mounting matrix is a device tree property used to orient any IIO device
>>> +that produce three-dimensional data.
>>> +
>>> +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 point of reference.
>> point of reference -> device frame of reference.
> +1.
> Makes me think we should probably use the same terminology in DT bindings and
> IIO ABI docs.
> What Jonathan calls "device frame of reference" was named as "main hardware
> reference frame" in IIO docs. For fixed wings UAVs the most common term would
> be "body frame".
> I think we should pick one and stick with it.
Agreed. Don't actually care which, though body frame of reference seems a bit
odd for a mobile phone ;)
> 
> Moreover as, told below, we have to make a clear distinction between "world",
> "device/main hardware" and "sensor" reference frames.
>>> +
>>> +For example a device with some kind of screen, where the user is supposed to
>>> +interact with the environment using a 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.
>> Good description.
>>> +
>>> +The axes may also be flipped: 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.
>> I'm not sure we don't want to define that it can't be flipped and enforce the
>> correct coordinate system on the underlying drivers (fingers crossed they are
>> currently all left or all right handed? - oops should have been keeping an eye on
>> this).
> As to coordinate system definition, multiple conventions seem to exist across
> industries. For UAV, we use the one described here:
> https://en.wikipedia.org/wiki/Flight_dynamics_(fixed-wing_aircraft)
> 
> So I feel like we should keep away from any temptation to define the coordinates
> system too strictly.
> I also think of systems composed of multiple hardware parts with sensors
> scattered all over them. What would be the right "device/main hardware" reference
> frame definition in these cases ?
> As this is product specific, I feel like "device/main hardware" reference frame
> definition should be left to the "board/main hardware/device..." implementor's
> choice.
Flexible is good, but I think we should define a base rule for the chips frame
of reference and fix up any that disagree (which is nasty ABI breakage :(
Trivial choice of either right handed or left handed frame might be all we
define in general.  Useful to define consistent frames for device types that
are common perhaps as well.  (such as the screen ones Linus has here).
>>> +
>>> +Apart from flipping, a sensor can of course also be mounted in any angle along
>>> +the axes relative to the point of reference. This means that the axes may be
>>> +not only flipped, but tilted.
>> Just define it as a frame of reference, rather than a point and axis.  Frame hides
>> all evils ;)
> +1
>> For now we are being a bit simplistic as for accelerometers at least, it can be
>> of interest to know the translation as well as the rotation.  You can use a couple
>> of them to do fairly precise rotation estimate if they are located in different
>> places on a device.
>>
>>> +
>>> +Examples for some three-dimensional sensor types:
>>> +
>>> +- Accelerometers have their frame of reference
>> Not quite right.  Their frame of reference is in the frame of the device - it has
>> nothing to do with the world frame which you are describing here (except when
>> the device is deliberate oriented to match.
>>
>> So we have 3 frames - that of the sensor, that of the device and that of the world.
>>
>> Sensor --<mounting matrix transform>--> Device frame --<Device to world transform> -->
>> world frame.
>> For the static no motion cases - when moving the acceleration needs to take into account
>> what the motion is etc (magnetometer doesn't).
> +1
> 
> [snip....]
> 
> Except for the above mentioned points, I'm happy with the rest of the
> description.
> 
> best regards,
> Grég.
Thanks,

Jonathan
> 
>> All the below kind of merge the mounting matrix transform with the device to world
>> transform and leave me at least somewhat confused :)
>>
>>   is toward the center of gravity,
>>> +  usually to the core of the planet, and users would likely expect a value of
>>> +  9.81N upwards along the (z) axis when the device is held with its screen
>>> +  perpendicular to the planets surface and 0 on the other axes.
>> I'd have thought screen parallel  - i.e. z is out of the screen?
>> Might be the same thing I suppose, but I'd define it simply as into the screen
>> then y towards top of screen and x from left to right of the screen.
>>   A reading of
>>> +  the (x,y,z) values will give the orientation of the device relative to the
>>> +  center of the planet, i.e. relative to its surface at this point. Up and down
>>> +  relative to the point of reference can thus be determined.
>> Will give a project of the gravity vector onto the axis of the sensor. There
>> is I think a world to local frame transform missing here...
>>
>>> +
>>> +- Magnetometers (compasses) have their frame of reference relative to the
>>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>>> +  hardware orientation 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.
>> Same issue, world to frame transform is not included...
>>> +
>>> +- Gyroscopes detects the movement relative the device itself, and has no other
>>> +  frame of reference than the mounting chassis itself.
>> This is true for all of them as far as we are concerned here...
>>> The angular momentum is
>> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
>> of change of rotation about an axis (lets ignore the significant cross talk and
>> effects of linear acceleration and pretend it's all easy here ;)
>>
>> Rest of this description is fine.
>>> +  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 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.
>>> +
>>> +So unless the sensor is ideally mounted, we need a means to indicate the
>>> +relative orientation of any given sensor of this type.
>>> +
>>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>>> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
>> vector values as opposed to coordinates...
>>> +space, relative to some relevant point of reference.
>> Within the frame of the device.
>>> +
>>> +The mounting matrix has the layout:
>>> +
>>> + (x0, y0, z0)
>>> + (x1, y1, z1)
>>> + (x2, y2, z3)
>>> +
>>> +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
>>> +a minus (-) to indicate a negative value.
>>> +
>>> +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";
>>> +
>>> +Flipped X axis (negative values means positive):
>>> +
>>> +mount-matrix = "-1", "0", "0",
>>> +               "0", "1", "0",
>>> +               "0", "0", "1";
>> Hmm. This is an odd one as it basically means the device had a right hand
>> coordinate system in the first place... If that happens I think we should
>> by default report the negative of the scale for that axis.
>>
>> We've never strictly defined a coordinate system but I think left handed
>> is a good start!
>>> +
>>> +X and Y flipped (X values are for Y and Y values are for X):
>>> +
>>> +mount-matrix = "0", "1", "0",
>>> +               "1", "0", "0",
>>> +               "0", "0", "1";
>> Same with this one, we are flipping coordinate systems.  I'd expect only
>> rotation matrices to be valid mount matrices.
>>> +
>>> +Complex angular mounting with X and Z in a certain tilted orienation and
>> orientation
>>> +Y flipped:
>>> +
>>> +mount-matrix = "-0.984807753012208",  /* x0 */
>>> +               "0",                   /* y0 */
>>> +               "-0.173648177666930",  /* z0 */
>>> +               "0",                   /* x1 */
>>> +               "-1",                  /* y1 */
>>> +               "0",                   /* z1 */
>>> +               "-0.173648177666930",  /* x2 */
>>> +               "0",                   /* y2 */
>>> +               "0.984807753012208";   /* z2 */
>>>
>> Anyhow, now my head hurts.
>>
>> Jonathan

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 24/08/16 14:18, Gregor Boirie wrote:
> Linus, Jonathan,
> 
> my little bit there... at last. comments in line.
> 
> 
> On 08/21/2016 05:56 PM, Jonathan Cameron wrote:
>> On 24/07/16 11:17, Linus Walleij wrote:
>>> The mounting matrix for sensors was introduced in
>>> commit dfc57732ad38 ("iio:core: mounting matrix support")
>>>
>>> However the device tree bindings are very terse and since this is
>>> a widely applicable property, we need a proper binding for it
>>> that the other bindings can reference. This will also be useful
>>> for other operating systems and sensor engineering at large.
>>>
>>> I think all 3D sensors should support it, the current situation
>>> is probably that the mounting information is confined in magic
>>> userspace components rather than using the mounting matrix, which
>>> is not good for portability and reuse.
>>>
>>> Cc: Gregor Boirie <gregor.boirie@parrot.com>
>>> Cc: Sebastian Reichel <sre@kernel.org>
>>> Cc: Samu Onkalo <samu.onkalo@intel.com>
>>> Cc: devicetree@vger.kernel.org
>>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>> Hi Linus,
>>
>> Sorry I took so long to get to this...
>> (out of curiosity are you running a fifo queue of patches? Every time
>> I review and merge one, another one turns up in my inbox :)
>>> ---
>>> Please help out to get this right, I think this could be confusing
>>> to users unless documented properly. I think the doc has some rough
>>> edges since I'm not the smartest in physics nor english at all times.
>>> ---
>> I think we have quite a bit of confusion of measurement frames here.
>> (it always confused me when I was doing day to day work with these - now
>> I'm decidedly rusty!)
>>>   .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>>>   1 file changed, 104 insertions(+)
>>>   create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
>>>
>>> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>>> new file mode 100644
>>> index 000000000000..3e72c92c5689
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>>> @@ -0,0 +1,104 @@
>>> +Mounting matrix
>>> +
>>> +The mounting matrix is a device tree property used to orient any IIO device
>>> +that produce three-dimensional data.
>>> +
>>> +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 point of reference.
>> point of reference -> device frame of reference.
> +1.
> Makes me think we should probably use the same terminology in DT bindings and
> IIO ABI docs.
> What Jonathan calls "device frame of reference" was named as "main hardware
> reference frame" in IIO docs. For fixed wings UAVs the most common term would
> be "body frame".
> I think we should pick one and stick with it.
Agreed. Don't actually care which, though body frame of reference seems a bit
odd for a mobile phone ;)
> 
> Moreover as, told below, we have to make a clear distinction between "world",
> "device/main hardware" and "sensor" reference frames.
>>> +
>>> +For example a device with some kind of screen, where the user is supposed to
>>> +interact with the environment using a 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.
>> Good description.
>>> +
>>> +The axes may also be flipped: 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.
>> I'm not sure we don't want to define that it can't be flipped and enforce the
>> correct coordinate system on the underlying drivers (fingers crossed they are
>> currently all left or all right handed? - oops should have been keeping an eye on
>> this).
> As to coordinate system definition, multiple conventions seem to exist across
> industries. For UAV, we use the one described here:
> https://en.wikipedia.org/wiki/Flight_dynamics_(fixed-wing_aircraft)
> 
> So I feel like we should keep away from any temptation to define the coordinates
> system too strictly.
> I also think of systems composed of multiple hardware parts with sensors
> scattered all over them. What would be the right "device/main hardware" reference
> frame definition in these cases ?
> As this is product specific, I feel like "device/main hardware" reference frame
> definition should be left to the "board/main hardware/device..." implementor's
> choice.
Flexible is good, but I think we should define a base rule for the chips frame
of reference and fix up any that disagree (which is nasty ABI breakage :(
Trivial choice of either right handed or left handed frame might be all we
define in general.  Useful to define consistent frames for device types that
are common perhaps as well.  (such as the screen ones Linus has here).
>>> +
>>> +Apart from flipping, a sensor can of course also be mounted in any angle along
>>> +the axes relative to the point of reference. This means that the axes may be
>>> +not only flipped, but tilted.
>> Just define it as a frame of reference, rather than a point and axis.  Frame hides
>> all evils ;)
> +1
>> For now we are being a bit simplistic as for accelerometers at least, it can be
>> of interest to know the translation as well as the rotation.  You can use a couple
>> of them to do fairly precise rotation estimate if they are located in different
>> places on a device.
>>
>>> +
>>> +Examples for some three-dimensional sensor types:
>>> +
>>> +- Accelerometers have their frame of reference
>> Not quite right.  Their frame of reference is in the frame of the device - it has
>> nothing to do with the world frame which you are describing here (except when
>> the device is deliberate oriented to match.
>>
>> So we have 3 frames - that of the sensor, that of the device and that of the world.
>>
>> Sensor --<mounting matrix transform>--> Device frame --<Device to world transform> -->
>> world frame.
>> For the static no motion cases - when moving the acceleration needs to take into account
>> what the motion is etc (magnetometer doesn't).
> +1
> 
> [snip....]
> 
> Except for the above mentioned points, I'm happy with the rest of the
> description.
> 
> best regards,
> Grég.
Thanks,

Jonathan
> 
>> All the below kind of merge the mounting matrix transform with the device to world
>> transform and leave me at least somewhat confused :)
>>
>>   is toward the center of gravity,
>>> +  usually to the core of the planet, and users would likely expect a value of
>>> +  9.81N upwards along the (z) axis when the device is held with its screen
>>> +  perpendicular to the planets surface and 0 on the other axes.
>> I'd have thought screen parallel  - i.e. z is out of the screen?
>> Might be the same thing I suppose, but I'd define it simply as into the screen
>> then y towards top of screen and x from left to right of the screen.
>>   A reading of
>>> +  the (x,y,z) values will give the orientation of the device relative to the
>>> +  center of the planet, i.e. relative to its surface at this point. Up and down
>>> +  relative to the point of reference can thus be determined.
>> Will give a project of the gravity vector onto the axis of the sensor. There
>> is I think a world to local frame transform missing here...
>>
>>> +
>>> +- Magnetometers (compasses) have their frame of reference relative to the
>>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>>> +  hardware orientation 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.
>> Same issue, world to frame transform is not included...
>>> +
>>> +- Gyroscopes detects the movement relative the device itself, and has no other
>>> +  frame of reference than the mounting chassis itself.
>> This is true for all of them as far as we are concerned here...
>>> The angular momentum is
>> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
>> of change of rotation about an axis (lets ignore the significant cross talk and
>> effects of linear acceleration and pretend it's all easy here ;)
>>
>> Rest of this description is fine.
>>> +  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 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.
>>> +
>>> +So unless the sensor is ideally mounted, we need a means to indicate the
>>> +relative orientation of any given sensor of this type.
>>> +
>>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>>> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
>> vector values as opposed to coordinates...
>>> +space, relative to some relevant point of reference.
>> Within the frame of the device.
>>> +
>>> +The mounting matrix has the layout:
>>> +
>>> + (x0, y0, z0)
>>> + (x1, y1, z1)
>>> + (x2, y2, z3)
>>> +
>>> +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
>>> +a minus (-) to indicate a negative value.
>>> +
>>> +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";
>>> +
>>> +Flipped X axis (negative values means positive):
>>> +
>>> +mount-matrix = "-1", "0", "0",
>>> +               "0", "1", "0",
>>> +               "0", "0", "1";
>> Hmm. This is an odd one as it basically means the device had a right hand
>> coordinate system in the first place... If that happens I think we should
>> by default report the negative of the scale for that axis.
>>
>> We've never strictly defined a coordinate system but I think left handed
>> is a good start!
>>> +
>>> +X and Y flipped (X values are for Y and Y values are for X):
>>> +
>>> +mount-matrix = "0", "1", "0",
>>> +               "1", "0", "0",
>>> +               "0", "0", "1";
>> Same with this one, we are flipping coordinate systems.  I'd expect only
>> rotation matrices to be valid mount matrices.
>>> +
>>> +Complex angular mounting with X and Z in a certain tilted orienation and
>> orientation
>>> +Y flipped:
>>> +
>>> +mount-matrix = "-0.984807753012208",  /* x0 */
>>> +               "0",                   /* y0 */
>>> +               "-0.173648177666930",  /* z0 */
>>> +               "0",                   /* x1 */
>>> +               "-1",                  /* y1 */
>>> +               "0",                   /* z1 */
>>> +               "-0.173648177666930",  /* x2 */
>>> +               "0",                   /* y2 */
>>> +               "0.984807753012208";   /* z2 */
>>>
>> Anyhow, now my head hurts.
>>
>> Jonathan

Re: [PATCH] iio: document bindings for mounting matrixes

[Gregor Boirie]

On 08/24/2016 11:29 PM, Jonathan Cameron wrote:

[snip...]

>>>> +
>>>> +The axes may also be flipped: 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.
>>> I'm not sure we don't want to define that it can't be flipped and enforce the
>>> correct coordinate system on the underlying drivers (fingers crossed they are
>>> currently all left or all right handed? - oops should have been keeping an eye on
>>> this).
>> As to coordinate system definition, multiple conventions seem to exist across
>> industries. For UAV, we use the one described here:
>> https://en.wikipedia.org/wiki/Flight_dynamics_(fixed-wing_aircraft)
>>
>> So I feel like we should keep away from any temptation to define the coordinates
>> system too strictly.
>> I also think of systems composed of multiple hardware parts with sensors
>> scattered all over them. What would be the right "device/main hardware" reference
>> frame definition in these cases ?
>> As this is product specific, I feel like "device/main hardware" reference frame
>> definition should be left to the "board/main hardware/device..." implementor's
>> choice.
> Flexible is good, but I think we should define a base rule for the chips frame
> of reference and fix up any that disagree (which is nasty ABI breakage :(
We might as well expose another property to userspace to indicate
coordinates system convention currently in use.
This seems overly complex to me but might ease portability across platforms
and products. I have no clear opinion on this.

Anyway, DT / BSP maintainer would always have the ability to customize
mounting matrix values on a per-product basis to fit their application
expectations.
E.g., from Parrot's UAVs perspective, flight control stack expects 
coordinates
system to be defined according to aeronautic convention (hardcoded).
Even if DT required a strict definition of coordinates system, this 
would implies
no changes to rotation matrix values currently set into our DTs...
> Trivial choice of either right handed or left handed frame might be all we
> define in general.  Useful to define consistent frames for device types that
> are common perhaps as well.  (such as the screen ones Linus has here).
It seems most common definition is what is described here:
https://www.w3.org/TR/2016/CR-orientation-event-20160818/
and here:
https://developer.android.com/guide/topics/sensors/sensors_overview.html#sensors-coords
given that Android devices represent a fair amount of phones and tablets 
in use.

Searched for IoT related things but no clear conventions came out...
And I can't think of PC world as a reference for this kind of stuff.

Yours,
Greg.

Re: [PATCH] iio: document bindings for mounting matrixes

[Gregor Boirie]

On 08/24/2016 11:29 PM, Jonathan Cameron wrote:

[snip...]

>>>> +
>>>> +The axes may also be flipped: 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.
>>> I'm not sure we don't want to define that it can't be flipped and enforce the
>>> correct coordinate system on the underlying drivers (fingers crossed they are
>>> currently all left or all right handed? - oops should have been keeping an eye on
>>> this).
>> As to coordinate system definition, multiple conventions seem to exist across
>> industries. For UAV, we use the one described here:
>> https://en.wikipedia.org/wiki/Flight_dynamics_(fixed-wing_aircraft)
>>
>> So I feel like we should keep away from any temptation to define the coordinates
>> system too strictly.
>> I also think of systems composed of multiple hardware parts with sensors
>> scattered all over them. What would be the right "device/main hardware" reference
>> frame definition in these cases ?
>> As this is product specific, I feel like "device/main hardware" reference frame
>> definition should be left to the "board/main hardware/device..." implementor's
>> choice.
> Flexible is good, but I think we should define a base rule for the chips frame
> of reference and fix up any that disagree (which is nasty ABI breakage :(
We might as well expose another property to userspace to indicate
coordinates system convention currently in use.
This seems overly complex to me but might ease portability across platforms
and products. I have no clear opinion on this.

Anyway, DT / BSP maintainer would always have the ability to customize
mounting matrix values on a per-product basis to fit their application
expectations.
E.g., from Parrot's UAVs perspective, flight control stack expects 
coordinates
system to be defined according to aeronautic convention (hardcoded).
Even if DT required a strict definition of coordinates system, this 
would implies
no changes to rotation matrix values currently set into our DTs...
> Trivial choice of either right handed or left handed frame might be all we
> define in general.  Useful to define consistent frames for device types that
> are common perhaps as well.  (such as the screen ones Linus has here).
It seems most common definition is what is described here:
https://www.w3.org/TR/2016/CR-orientation-event-20160818/
and here:
https://developer.android.com/guide/topics/sensors/sensors_overview.html#sensors-coords
given that Android devices represent a fair amount of phones and tablets 
in use.

Searched for IoT related things but no clear conventions came out...
And I can't think of PC world as a reference for this kind of stuff.

Yours,
Greg.

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Wed, Aug 24, 2016 at 11:29 PM, Jonathan Cameron <jic23-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
> Gregor:
>> So I feel like we should keep away from any temptation to define the coordinates
>> system too strictly.
>> I also think of systems composed of multiple hardware parts with sensors
>> scattered all over them. What would be the right "device/main hardware" reference
>> frame definition in these cases ?
>> As this is product specific, I feel like "device/main hardware" reference frame
>> definition should be left to the "board/main hardware/device..." implementor's
>> choice.
>
> Flexible is good, but I think we should define a base rule for the chips frame
> of reference and fix up any that disagree (which is nasty ABI breakage :(
> Trivial choice of either right handed or left handed frame might be all we
> define in general.  Useful to define consistent frames for device types that
> are common perhaps as well.  (such as the screen ones Linus has here).

Admittedly I come from the mobile phone industry.

So these frames of reference is not cooked up by me, I installed the
Android app "Sensors test" to test two devices relative the world, so this
is the frame of reference used by all mobile phones and tablets on the
planet (I hardly think iPhone deviates).

I would be happy to write explicitly that for human interaction devices
with screens that frame of reference should always be assumed, but for
other uses and device types other frames of reference may apply, would
you agree?

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Wed, Aug 24, 2016 at 11:29 PM, Jonathan Cameron <jic23@kernel.org> wrote:
> Gregor:
>> So I feel like we should keep away from any temptation to define the coordinates
>> system too strictly.
>> I also think of systems composed of multiple hardware parts with sensors
>> scattered all over them. What would be the right "device/main hardware" reference
>> frame definition in these cases ?
>> As this is product specific, I feel like "device/main hardware" reference frame
>> definition should be left to the "board/main hardware/device..." implementor's
>> choice.
>
> Flexible is good, but I think we should define a base rule for the chips frame
> of reference and fix up any that disagree (which is nasty ABI breakage :(
> Trivial choice of either right handed or left handed frame might be all we
> define in general.  Useful to define consistent frames for device types that
> are common perhaps as well.  (such as the screen ones Linus has here).

Admittedly I come from the mobile phone industry.

So these frames of reference is not cooked up by me, I installed the
Android app "Sensors test" to test two devices relative the world, so this
is the frame of reference used by all mobile phones and tablets on the
planet (I hardly think iPhone deviates).

I would be happy to write explicitly that for human interaction devices
with screens that frame of reference should always be assumed, but for
other uses and device types other frames of reference may apply, would
you agree?

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 25/08/16 23:04, Linus Walleij wrote:
> On Wed, Aug 24, 2016 at 11:29 PM, Jonathan Cameron <jic23-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
>> Gregor:
>>> So I feel like we should keep away from any temptation to define the coordinates
>>> system too strictly.
>>> I also think of systems composed of multiple hardware parts with sensors
>>> scattered all over them. What would be the right "device/main hardware" reference
>>> frame definition in these cases ?
>>> As this is product specific, I feel like "device/main hardware" reference frame
>>> definition should be left to the "board/main hardware/device..." implementor's
>>> choice.
>>
>> Flexible is good, but I think we should define a base rule for the chips frame
>> of reference and fix up any that disagree (which is nasty ABI breakage :(
>> Trivial choice of either right handed or left handed frame might be all we
>> define in general.  Useful to define consistent frames for device types that
>> are common perhaps as well.  (such as the screen ones Linus has here).
> 
> Admittedly I come from the mobile phone industry.
> 
> So these frames of reference is not cooked up by me, I installed the
> Android app "Sensors test" to test two devices relative the world, so this
> is the frame of reference used by all mobile phones and tablets on the
> planet (I hardly think iPhone deviates).
> 
> I would be happy to write explicitly that for human interaction devices
> with screens that frame of reference should always be assumed, but for
> other uses and device types other frames of reference may apply, would
> you agree?
Absolutely.  The references Gregor gave might also be worth mentioning
as they provide pretty pictures etc ;)

Jonathan
> 
> Yours,
> Linus Walleij
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 25/08/16 23:04, Linus Walleij wrote:
> On Wed, Aug 24, 2016 at 11:29 PM, Jonathan Cameron <jic23@kernel.org> wrote:
>> Gregor:
>>> So I feel like we should keep away from any temptation to define the coordinates
>>> system too strictly.
>>> I also think of systems composed of multiple hardware parts with sensors
>>> scattered all over them. What would be the right "device/main hardware" reference
>>> frame definition in these cases ?
>>> As this is product specific, I feel like "device/main hardware" reference frame
>>> definition should be left to the "board/main hardware/device..." implementor's
>>> choice.
>>
>> Flexible is good, but I think we should define a base rule for the chips frame
>> of reference and fix up any that disagree (which is nasty ABI breakage :(
>> Trivial choice of either right handed or left handed frame might be all we
>> define in general.  Useful to define consistent frames for device types that
>> are common perhaps as well.  (such as the screen ones Linus has here).
> 
> Admittedly I come from the mobile phone industry.
> 
> So these frames of reference is not cooked up by me, I installed the
> Android app "Sensors test" to test two devices relative the world, so this
> is the frame of reference used by all mobile phones and tablets on the
> planet (I hardly think iPhone deviates).
> 
> I would be happy to write explicitly that for human interaction devices
> with screens that frame of reference should always be assumed, but for
> other uses and device types other frames of reference may apply, would
> you agree?
Absolutely.  The references Gregor gave might also be worth mentioning
as they provide pretty pictures etc ;)

Jonathan
> 
> Yours,
> Linus Walleij
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 24/07/16 11:17, Linus Walleij wrote:
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Gregor Boirie <gregor.boirie-ITF29qwbsa/QT0dZR+AlfA@public.gmane.org>
> Cc: Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Cc: Samu Onkalo <samu.onkalo-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
Hi Linus,

Sorry I took so long to get to this...
(out of curiosity are you running a fifo queue of patches? Every time
I review and merge one, another one turns up in my inbox :)
> ---
> Please help out to get this right, I think this could be confusing
> to users unless documented properly. I think the doc has some rough
> edges since I'm not the smartest in physics nor english at all times.
> ---
I think we have quite a bit of confusion of measurement frames here.
(it always confused me when I was doing day to day work with these - now
I'm decidedly rusty!)
>  .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>  1 file changed, 104 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
> 
> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> new file mode 100644
> index 000000000000..3e72c92c5689
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> @@ -0,0 +1,104 @@
> +Mounting matrix
> +
> +The mounting matrix is a device tree property used to orient any IIO device
> +that produce three-dimensional data.
> +
> +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 point of reference.
point of reference -> device frame of reference.
> +
> +For example a device with some kind of screen, where the user is supposed to
> +interact with the environment using a 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.
Good description.
> +
> +The axes may also be flipped: 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.
I'm not sure we don't want to define that it can't be flipped and enforce the
correct coordinate system on the underlying drivers (fingers crossed they are
currently all left or all right handed? - oops should have been keeping an eye on
this).
> +
> +Apart from flipping, a sensor can of course also be mounted in any angle along
> +the axes relative to the point of reference. This means that the axes may be
> +not only flipped, but tilted.
Just define it as a frame of reference, rather than a point and axis.  Frame hides
all evils ;)

For now we are being a bit simplistic as for accelerometers at least, it can be 
of interest to know the translation as well as the rotation.  You can use a couple
of them to do fairly precise rotation estimate if they are located in different
places on a device.

> +
> +Examples for some three-dimensional sensor types:
> +
> +- Accelerometers have their frame of reference 
Not quite right.  Their frame of reference is in the frame of the device - it has
nothing to do with the world frame which you are describing here (except when
the device is deliberate oriented to match.

So we have 3 frames - that of the sensor, that of the device and that of the world.

Sensor --<mounting matrix transform>--> Device frame --<Device to world transform> -->
world frame.
For the static no motion cases - when moving the acceleration needs to take into account
what the motion is etc (magnetometer doesn't).

All the below kind of merge the mounting matrix transform with the device to world
transform and leave me at least somewhat confused :)

 is toward the center of gravity,
> +  usually to the core of the planet, and users would likely expect a value of
> +  9.81N upwards along the (z) axis when the device is held with its screen
> +  perpendicular to the planets surface and 0 on the other axes.
I'd have thought screen parallel  - i.e. z is out of the screen?
Might be the same thing I suppose, but I'd define it simply as into the screen
then y towards top of screen and x from left to right of the screen.
 A reading of
> +  the (x,y,z) values will give the orientation of the device relative to the
> +  center of the planet, i.e. relative to its surface at this point. Up and down
> +  relative to the point of reference can thus be determined.
Will give a project of the gravity vector onto the axis of the sensor. There
is I think a world to local frame transform missing here...

> +
> +- Magnetometers (compasses) have their frame of reference relative to the
> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
> +  hardware orientation 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.
Same issue, world to frame transform is not included...
> +
> +- Gyroscopes detects the movement relative the device itself, and has no other
> +  frame of reference than the mounting chassis itself.
This is true for all of them as far as we are concerned here...
> The angular momentum is
Hang on, where did momentum come into it from?  Mems gyros are detecting rate
of change of rotation about an axis (lets ignore the significant cross talk and
effects of linear acceleration and pretend it's all easy here ;)

Rest of this description is fine.
> +  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 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.
> +
> +So unless the sensor is ideally mounted, we need a means to indicate the
> +relative orientation of any given sensor of this type.
> +
> +To achieve this, use the device tree property "mount-matrix" for the sensor.
> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
vector values as opposed to coordinates...
> +space, relative to some relevant point of reference.
Within the frame of the device.
> +
> +The mounting matrix has the layout:
> +
> + (x0, y0, z0)
> + (x1, y1, z1)
> + (x2, y2, z3)
> +
> +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
> +a minus (-) to indicate a negative value.
> +
> +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";
> +
> +Flipped X axis (negative values means positive):
> +
> +mount-matrix = "-1", "0", "0",
> +               "0", "1", "0",
> +               "0", "0", "1";
Hmm. This is an odd one as it basically means the device had a right hand
coordinate system in the first place... If that happens I think we should
by default report the negative of the scale for that axis.

We've never strictly defined a coordinate system but I think left handed
is a good start!
> +
> +X and Y flipped (X values are for Y and Y values are for X):
> +
> +mount-matrix = "0", "1", "0",
> +               "1", "0", "0",
> +               "0", "0", "1";
Same with this one, we are flipping coordinate systems.  I'd expect only
rotation matrices to be valid mount matrices.
> +
> +Complex angular mounting with X and Z in a certain tilted orienation and
orientation
> +Y flipped:
> +
> +mount-matrix = "-0.984807753012208",  /* x0 */
> +               "0",                   /* y0 */
> +               "-0.173648177666930",  /* z0 */
> +               "0",                   /* x1 */
> +               "-1",                  /* y1 */
> +               "0",                   /* z1 */
> +               "-0.173648177666930",  /* x2 */
> +               "0",                   /* y2 */
> +               "0.984807753012208";   /* z2 */
> 

Anyhow, now my head hurts.

Jonathan

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 24/07/16 11:17, Linus Walleij wrote:
> The mounting matrix for sensors was introduced in
> commit dfc57732ad38 ("iio:core: mounting matrix support")
> 
> However the device tree bindings are very terse and since this is
> a widely applicable property, we need a proper binding for it
> that the other bindings can reference. This will also be useful
> for other operating systems and sensor engineering at large.
> 
> I think all 3D sensors should support it, the current situation
> is probably that the mounting information is confined in magic
> userspace components rather than using the mounting matrix, which
> is not good for portability and reuse.
> 
> Cc: Gregor Boirie <gregor.boirie@parrot.com>
> Cc: Sebastian Reichel <sre@kernel.org>
> Cc: Samu Onkalo <samu.onkalo@intel.com>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
Hi Linus,

Sorry I took so long to get to this...
(out of curiosity are you running a fifo queue of patches? Every time
I review and merge one, another one turns up in my inbox :)
> ---
> Please help out to get this right, I think this could be confusing
> to users unless documented properly. I think the doc has some rough
> edges since I'm not the smartest in physics nor english at all times.
> ---
I think we have quite a bit of confusion of measurement frames here.
(it always confused me when I was doing day to day work with these - now
I'm decidedly rusty!)
>  .../devicetree/bindings/iio/mount-matrix.txt       | 104 +++++++++++++++++++++
>  1 file changed, 104 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
> 
> diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> new file mode 100644
> index 000000000000..3e72c92c5689
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> @@ -0,0 +1,104 @@
> +Mounting matrix
> +
> +The mounting matrix is a device tree property used to orient any IIO device
> +that produce three-dimensional data.
> +
> +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 point of reference.
point of reference -> device frame of reference.
> +
> +For example a device with some kind of screen, where the user is supposed to
> +interact with the environment using a 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.
Good description.
> +
> +The axes may also be flipped: 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.
I'm not sure we don't want to define that it can't be flipped and enforce the
correct coordinate system on the underlying drivers (fingers crossed they are
currently all left or all right handed? - oops should have been keeping an eye on
this).
> +
> +Apart from flipping, a sensor can of course also be mounted in any angle along
> +the axes relative to the point of reference. This means that the axes may be
> +not only flipped, but tilted.
Just define it as a frame of reference, rather than a point and axis.  Frame hides
all evils ;)

For now we are being a bit simplistic as for accelerometers at least, it can be 
of interest to know the translation as well as the rotation.  You can use a couple
of them to do fairly precise rotation estimate if they are located in different
places on a device.

> +
> +Examples for some three-dimensional sensor types:
> +
> +- Accelerometers have their frame of reference 
Not quite right.  Their frame of reference is in the frame of the device - it has
nothing to do with the world frame which you are describing here (except when
the device is deliberate oriented to match.

So we have 3 frames - that of the sensor, that of the device and that of the world.

Sensor --<mounting matrix transform>--> Device frame --<Device to world transform> -->
world frame.
For the static no motion cases - when moving the acceleration needs to take into account
what the motion is etc (magnetometer doesn't).

All the below kind of merge the mounting matrix transform with the device to world
transform and leave me at least somewhat confused :)

 is toward the center of gravity,
> +  usually to the core of the planet, and users would likely expect a value of
> +  9.81N upwards along the (z) axis when the device is held with its screen
> +  perpendicular to the planets surface and 0 on the other axes.
I'd have thought screen parallel  - i.e. z is out of the screen?
Might be the same thing I suppose, but I'd define it simply as into the screen
then y towards top of screen and x from left to right of the screen.
 A reading of
> +  the (x,y,z) values will give the orientation of the device relative to the
> +  center of the planet, i.e. relative to its surface at this point. Up and down
> +  relative to the point of reference can thus be determined.
Will give a project of the gravity vector onto the axis of the sensor. There
is I think a world to local frame transform missing here...

> +
> +- Magnetometers (compasses) have their frame of reference relative to the
> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
> +  hardware orientation 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.
Same issue, world to frame transform is not included...
> +
> +- Gyroscopes detects the movement relative the device itself, and has no other
> +  frame of reference than the mounting chassis itself.
This is true for all of them as far as we are concerned here...
> The angular momentum is
Hang on, where did momentum come into it from?  Mems gyros are detecting rate
of change of rotation about an axis (lets ignore the significant cross talk and
effects of linear acceleration and pretend it's all easy here ;)

Rest of this description is fine.
> +  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 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.
> +
> +So unless the sensor is ideally mounted, we need a means to indicate the
> +relative orientation of any given sensor of this type.
> +
> +To achieve this, use the device tree property "mount-matrix" for the sensor.
> +This supplies a 3x3 transformation 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 coordinates in three-dimensional
vector values as opposed to coordinates...
> +space, relative to some relevant point of reference.
Within the frame of the device.
> +
> +The mounting matrix has the layout:
> +
> + (x0, y0, z0)
> + (x1, y1, z1)
> + (x2, y2, z3)
> +
> +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
> +a minus (-) to indicate a negative value.
> +
> +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";
> +
> +Flipped X axis (negative values means positive):
> +
> +mount-matrix = "-1", "0", "0",
> +               "0", "1", "0",
> +               "0", "0", "1";
Hmm. This is an odd one as it basically means the device had a right hand
coordinate system in the first place... If that happens I think we should
by default report the negative of the scale for that axis.

We've never strictly defined a coordinate system but I think left handed
is a good start!
> +
> +X and Y flipped (X values are for Y and Y values are for X):
> +
> +mount-matrix = "0", "1", "0",
> +               "1", "0", "0",
> +               "0", "0", "1";
Same with this one, we are flipping coordinate systems.  I'd expect only
rotation matrices to be valid mount matrices.
> +
> +Complex angular mounting with X and Z in a certain tilted orienation and
orientation
> +Y flipped:
> +
> +mount-matrix = "-0.984807753012208",  /* x0 */
> +               "0",                   /* y0 */
> +               "-0.173648177666930",  /* z0 */
> +               "0",                   /* x1 */
> +               "-1",                  /* y1 */
> +               "0",                   /* z1 */
> +               "-0.173648177666930",  /* x2 */
> +               "0",                   /* y2 */
> +               "0.984807753012208";   /* z2 */
> 

Anyhow, now my head hurts.

Jonathan

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Sun, Aug 21, 2016 at 5:56 PM, Jonathan Cameron <jic23-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:

> Sorry I took so long to get to this...
> (out of curiosity are you running a fifo queue of patches? Every time
> I review and merge one, another one turns up in my inbox :)

Haha no, IIO is just sucking me in, it's such a nice subsystem.

>> +The axes may also be flipped: 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.
>
> I'm not sure we don't want to define that it can't be flipped and enforce the
> correct coordinate system on the underlying drivers (fingers crossed they are
> currently all left or all right handed? - oops should have been keeping an eye on
> this).

I'll reword. What I wante to get across was the concept of flipped axes.

We need to keep an eye on drivers coming from the middle
east as their writing systems go from right to left, but I suspect they are
all aware of this issue.

> For now we are being a bit simplistic as for accelerometers at least, it can be
> of interest to know the translation as well as the rotation.  You can use a couple
> of them to do fairly precise rotation estimate if they are located in different
> places on a device.

Hm the mounting matrix doesn't account for that at all. Oh well sigh, that
would be another property in sysfs the day we need to handle it.

>> +Examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their frame of reference
>
> Not quite right.  Their frame of reference is in the frame of the device - it has
> nothing to do with the world frame which you are describing here (except when
> the device is deliberate oriented to match.

So the core of the crux, the help I'm trying to provide, is for people
that develop sensor drivers to be able to verify that they have the right
mounting matrix.

They need to see that the figures coming out of the buffers match to
something they can verify and thus understand that they got it right.

Maybe this is too ambitious :(

> So we have 3 frames - that of the sensor, that of the device and that of the world.

OK reworded and tried to reflect this.

  is toward the center of gravity,
>> +  usually to the core of the planet, and users would likely expect a value of
>> +  9.81N upwards along the (z) axis when the device is held with its screen
>> +  perpendicular to the planets surface and 0 on the other axes.
>
> I'd have thought screen parallel  - i.e. z is out of the screen?
> Might be the same thing I suppose, but I'd define it simply as into the screen
> then y towards top of screen and x from left to right of the screen.

Trying to fix up the confusion by rewording.

>> +- Magnetometers (compasses) have their frame of reference relative to the
>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>> +  hardware orientation 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.
>
> Same issue, world to frame transform is not included...

OK rewording, this is all about the system-to-world really.

>> +- Gyroscopes detects the movement relative the device itself, and has no other
>> +  frame of reference than the mounting chassis itself.
>
> This is true for all of them as far as we are concerned here...
>> The angular momentum is
> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
> of change of rotation about an axis (lets ignore the significant cross talk and
> effects of linear acceleration and pretend it's all easy here ;)
>
> Rest of this description is fine.

Angular velocity. Sorry, just screwed it up.

>> +Flipped X axis (negative values means positive):
>> +
>> +mount-matrix = "-1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
>
> Hmm. This is an odd one as it basically means the device had a right hand
> coordinate system in the first place... If that happens I think we should
> by default report the negative of the scale for that axis.
>
> We've never strictly defined a coordinate system but I think left handed
> is a good start!
>> +
>> +X and Y flipped (X values are for Y and Y values are for X):
>> +
>> +mount-matrix = "0", "1", "0",
>> +               "1", "0", "0",
>> +               "0", "0", "1";
> Same with this one, we are flipping coordinate systems.

Hm you have a point.

Those are inspired by the touchscreen input properties
Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt
as those have:

 - touchscreen-inverted-x       : X axis is inverted (boolean)
 - touchscreen-inverted-y       : Y axis is inverted (boolean)
 - touchscreen-swapped-x-y      : X and Y axis are swapped (boolean)
                                  Swapping is done after inverting the axis

By supporting the mount matrix we open the door for augmenting
driver bugs with this. Sigh.

> I'd expect only
> rotation matrices to be valid mount matrices.

OK what about sensor mounted upside-down relative device:

mount-matrix = "1", "0", "0",
               "0", "1", "0",
               "0", "0", "-1";

Sensor mounted standing on the side so X becomes Z
and Z becomes X:

mount-matrix = "0", "0", "1",
               "0", "1", "0",
               "1", "0", "0";

Are these proper rotation matrices?

>> +Complex angular mounting with X and Z in a certain tilted orienation and
> orientation
>> +Y flipped:
>> +
>> +mount-matrix = "-0.984807753012208",  /* x0 */
>> +               "0",                   /* y0 */
>> +               "-0.173648177666930",  /* z0 */
>> +               "0",                   /* x1 */
>> +               "-1",                  /* y1 */
>> +               "0",                   /* z1 */
>> +               "-0.173648177666930",  /* x2 */
>> +               "0",                   /* y2 */
>> +               "0.984807753012208";   /* z2 */
>>
>
> Anyhow, now my head hurts.

That is a real-world example from the AK8975 on some Nokia...

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Linus Walleij]

On Sun, Aug 21, 2016 at 5:56 PM, Jonathan Cameron <jic23@kernel.org> wrote:

> Sorry I took so long to get to this...
> (out of curiosity are you running a fifo queue of patches? Every time
> I review and merge one, another one turns up in my inbox :)

Haha no, IIO is just sucking me in, it's such a nice subsystem.

>> +The axes may also be flipped: 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.
>
> I'm not sure we don't want to define that it can't be flipped and enforce the
> correct coordinate system on the underlying drivers (fingers crossed they are
> currently all left or all right handed? - oops should have been keeping an eye on
> this).

I'll reword. What I wante to get across was the concept of flipped axes.

We need to keep an eye on drivers coming from the middle
east as their writing systems go from right to left, but I suspect they are
all aware of this issue.

> For now we are being a bit simplistic as for accelerometers at least, it can be
> of interest to know the translation as well as the rotation.  You can use a couple
> of them to do fairly precise rotation estimate if they are located in different
> places on a device.

Hm the mounting matrix doesn't account for that at all. Oh well sigh, that
would be another property in sysfs the day we need to handle it.

>> +Examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their frame of reference
>
> Not quite right.  Their frame of reference is in the frame of the device - it has
> nothing to do with the world frame which you are describing here (except when
> the device is deliberate oriented to match.

So the core of the crux, the help I'm trying to provide, is for people
that develop sensor drivers to be able to verify that they have the right
mounting matrix.

They need to see that the figures coming out of the buffers match to
something they can verify and thus understand that they got it right.

Maybe this is too ambitious :(

> So we have 3 frames - that of the sensor, that of the device and that of the world.

OK reworded and tried to reflect this.

  is toward the center of gravity,
>> +  usually to the core of the planet, and users would likely expect a value of
>> +  9.81N upwards along the (z) axis when the device is held with its screen
>> +  perpendicular to the planets surface and 0 on the other axes.
>
> I'd have thought screen parallel  - i.e. z is out of the screen?
> Might be the same thing I suppose, but I'd define it simply as into the screen
> then y towards top of screen and x from left to right of the screen.

Trying to fix up the confusion by rewording.

>> +- Magnetometers (compasses) have their frame of reference relative to the
>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>> +  hardware orientation 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.
>
> Same issue, world to frame transform is not included...

OK rewording, this is all about the system-to-world really.

>> +- Gyroscopes detects the movement relative the device itself, and has no other
>> +  frame of reference than the mounting chassis itself.
>
> This is true for all of them as far as we are concerned here...
>> The angular momentum is
> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
> of change of rotation about an axis (lets ignore the significant cross talk and
> effects of linear acceleration and pretend it's all easy here ;)
>
> Rest of this description is fine.

Angular velocity. Sorry, just screwed it up.

>> +Flipped X axis (negative values means positive):
>> +
>> +mount-matrix = "-1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
>
> Hmm. This is an odd one as it basically means the device had a right hand
> coordinate system in the first place... If that happens I think we should
> by default report the negative of the scale for that axis.
>
> We've never strictly defined a coordinate system but I think left handed
> is a good start!
>> +
>> +X and Y flipped (X values are for Y and Y values are for X):
>> +
>> +mount-matrix = "0", "1", "0",
>> +               "1", "0", "0",
>> +               "0", "0", "1";
> Same with this one, we are flipping coordinate systems.

Hm you have a point.

Those are inspired by the touchscreen input properties
Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt
as those have:

 - touchscreen-inverted-x       : X axis is inverted (boolean)
 - touchscreen-inverted-y       : Y axis is inverted (boolean)
 - touchscreen-swapped-x-y      : X and Y axis are swapped (boolean)
                                  Swapping is done after inverting the axis

By supporting the mount matrix we open the door for augmenting
driver bugs with this. Sigh.

> I'd expect only
> rotation matrices to be valid mount matrices.

OK what about sensor mounted upside-down relative device:

mount-matrix = "1", "0", "0",
               "0", "1", "0",
               "0", "0", "-1";

Sensor mounted standing on the side so X becomes Z
and Z becomes X:

mount-matrix = "0", "0", "1",
               "0", "1", "0",
               "1", "0", "0";

Are these proper rotation matrices?

>> +Complex angular mounting with X and Z in a certain tilted orienation and
> orientation
>> +Y flipped:
>> +
>> +mount-matrix = "-0.984807753012208",  /* x0 */
>> +               "0",                   /* y0 */
>> +               "-0.173648177666930",  /* z0 */
>> +               "0",                   /* x1 */
>> +               "-1",                  /* y1 */
>> +               "0",                   /* z1 */
>> +               "-0.173648177666930",  /* x2 */
>> +               "0",                   /* y2 */
>> +               "0.984807753012208";   /* z2 */
>>
>
> Anyhow, now my head hurts.

That is a real-world example from the AK8975 on some Nokia...

Yours,
Linus Walleij

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 25/08/16 22:56, Linus Walleij wrote:
> On Sun, Aug 21, 2016 at 5:56 PM, Jonathan Cameron <jic23-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
> 
>> Sorry I took so long to get to this...
>> (out of curiosity are you running a fifo queue of patches? Every time
>> I review and merge one, another one turns up in my inbox :)
> 
> Haha no, IIO is just sucking me in, it's such a nice subsystem.
> 
>>> +The axes may also be flipped: 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.
>>
>> I'm not sure we don't want to define that it can't be flipped and enforce the
>> correct coordinate system on the underlying drivers (fingers crossed they are
>> currently all left or all right handed? - oops should have been keeping an eye on
>> this).
> 
> I'll reword. What I wante to get across was the concept of flipped axes.
> 
> We need to keep an eye on drivers coming from the middle
> east as their writing systems go from right to left, but I suspect they are
> all aware of this issue.
> 
>> For now we are being a bit simplistic as for accelerometers at least, it can be
>> of interest to know the translation as well as the rotation.  You can use a couple
>> of them to do fairly precise rotation estimate if they are located in different
>> places on a device.
> 
> Hm the mounting matrix doesn't account for that at all. Oh well sigh, that
> would be another property in sysfs the day we need to handle it.
> 
>>> +Examples for some three-dimensional sensor types:
>>> +
>>> +- Accelerometers have their frame of reference
>>
>> Not quite right.  Their frame of reference is in the frame of the device - it has
>> nothing to do with the world frame which you are describing here (except when
>> the device is deliberate oriented to match.
> 
> So the core of the crux, the help I'm trying to provide, is for people
> that develop sensor drivers to be able to verify that they have the right
> mounting matrix.
> 
> They need to see that the figures coming out of the buffers match to
> something they can verify and thus understand that they got it right.
> 
> Maybe this is too ambitious :(
That's fine, but the trick is to explicitly say that under these circumstances
the rotation matrix between the device and the world is the identity matrix
(and highlight that that means it has no effect).  Under these specific
circumstances, the mounting matrix may be easily verified.

> 
>> So we have 3 frames - that of the sensor, that of the device and that of the world.
> 
> OK reworded and tried to reflect this.
> 
>   is toward the center of gravity,
>>> +  usually to the core of the planet, and users would likely expect a value of
>>> +  9.81N upwards along the (z) axis when the device is held with its screen
>>> +  perpendicular to the planets surface and 0 on the other axes.
>>
>> I'd have thought screen parallel  - i.e. z is out of the screen?
>> Might be the same thing I suppose, but I'd define it simply as into the screen
>> then y towards top of screen and x from left to right of the screen.
> 
> Trying to fix up the confusion by rewording.
> 
>>> +- Magnetometers (compasses) have their frame of reference relative to the
>>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>>> +  hardware orientation 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.
>>
>> Same issue, world to frame transform is not included...
> 
> OK rewording, this is all about the system-to-world really.
> 
>>> +- Gyroscopes detects the movement relative the device itself, and has no other
>>> +  frame of reference than the mounting chassis itself.
>>
>> This is true for all of them as far as we are concerned here...
>>> The angular momentum is
>> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
>> of change of rotation about an axis (lets ignore the significant cross talk and
>> effects of linear acceleration and pretend it's all easy here ;)
>>
>> Rest of this description is fine.
> 
> Angular velocity. Sorry, just screwed it up.
> 
>>> +Flipped X axis (negative values means positive):
>>> +
>>> +mount-matrix = "-1", "0", "0",
>>> +               "0", "1", "0",
>>> +               "0", "0", "1";
>>
>> Hmm. This is an odd one as it basically means the device had a right hand
>> coordinate system in the first place... If that happens I think we should
>> by default report the negative of the scale for that axis.
>>
>> We've never strictly defined a coordinate system but I think left handed
>> is a good start!
>>> +
>>> +X and Y flipped (X values are for Y and Y values are for X):
>>> +
>>> +mount-matrix = "0", "1", "0",
>>> +               "1", "0", "0",
>>> +               "0", "0", "1";
>> Same with this one, we are flipping coordinate systems.
> 
> Hm you have a point.
> 
> Those are inspired by the touchscreen input properties
> Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt
> as those have:
> 
>  - touchscreen-inverted-x       : X axis is inverted (boolean)
>  - touchscreen-inverted-y       : Y axis is inverted (boolean)
>  - touchscreen-swapped-x-y      : X and Y axis are swapped (boolean)
>                                   Swapping is done after inverting the axis
> 
> By supporting the mount matrix we open the door for augmenting
> driver bugs with this. Sigh.
> 
>> I'd expect only
>> rotation matrices to be valid mount matrices.
> 
> OK what about sensor mounted upside-down relative device:
> 
> mount-matrix = "1", "0", "0",
>                "0", "1", "0",
>                "0", "0", "-1";
> 
> Sensor mounted standing on the side so X becomes Z
> and Z becomes X:
> 
> mount-matrix = "0", "0", "1",
>                "0", "1", "0",
>                "1", "0", "0";
> 
> Are these proper rotation matrices?
Determinant = 1? 

Err (been a while) but using trusted wolfram alpa.

Nope to the first one That's a rotoinversion.
No to the second as well..  You can't end up just swapping axis.

Imagine taking your thumb and first two fingers to form a 3D axis
then see if you can spin it using your circus skills to match
the new orientation.

> 
>>> +Complex angular mounting with X and Z in a certain tilted orienation and
>> orientation
>>> +Y flipped:
>>> +
>>> +mount-matrix = "-0.984807753012208",  /* x0 */
>>> +               "0",                   /* y0 */
>>> +               "-0.173648177666930",  /* z0 */
>>> +               "0",                   /* x1 */
>>> +               "-1",                  /* y1 */
>>> +               "0",                   /* z1 */
>>> +               "-0.173648177666930",  /* x2 */
>>> +               "0",                   /* y2 */
>>> +               "0.984807753012208";   /* z2 */
>>>
This one is a rotation ;)
>>
>> Anyhow, now my head hurts.
> 
> That is a real-world example from the AK8975 on some Nokia...
> 
> Yours,
> Linus Walleij
> 

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] iio: document bindings for mounting matrixes

[Jonathan Cameron]

On 25/08/16 22:56, Linus Walleij wrote:
> On Sun, Aug 21, 2016 at 5:56 PM, Jonathan Cameron <jic23@kernel.org> wrote:
> 
>> Sorry I took so long to get to this...
>> (out of curiosity are you running a fifo queue of patches? Every time
>> I review and merge one, another one turns up in my inbox :)
> 
> Haha no, IIO is just sucking me in, it's such a nice subsystem.
> 
>>> +The axes may also be flipped: 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.
>>
>> I'm not sure we don't want to define that it can't be flipped and enforce the
>> correct coordinate system on the underlying drivers (fingers crossed they are
>> currently all left or all right handed? - oops should have been keeping an eye on
>> this).
> 
> I'll reword. What I wante to get across was the concept of flipped axes.
> 
> We need to keep an eye on drivers coming from the middle
> east as their writing systems go from right to left, but I suspect they are
> all aware of this issue.
> 
>> For now we are being a bit simplistic as for accelerometers at least, it can be
>> of interest to know the translation as well as the rotation.  You can use a couple
>> of them to do fairly precise rotation estimate if they are located in different
>> places on a device.
> 
> Hm the mounting matrix doesn't account for that at all. Oh well sigh, that
> would be another property in sysfs the day we need to handle it.
> 
>>> +Examples for some three-dimensional sensor types:
>>> +
>>> +- Accelerometers have their frame of reference
>>
>> Not quite right.  Their frame of reference is in the frame of the device - it has
>> nothing to do with the world frame which you are describing here (except when
>> the device is deliberate oriented to match.
> 
> So the core of the crux, the help I'm trying to provide, is for people
> that develop sensor drivers to be able to verify that they have the right
> mounting matrix.
> 
> They need to see that the figures coming out of the buffers match to
> something they can verify and thus understand that they got it right.
> 
> Maybe this is too ambitious :(
That's fine, but the trick is to explicitly say that under these circumstances
the rotation matrix between the device and the world is the identity matrix
(and highlight that that means it has no effect).  Under these specific
circumstances, the mounting matrix may be easily verified.

> 
>> So we have 3 frames - that of the sensor, that of the device and that of the world.
> 
> OK reworded and tried to reflect this.
> 
>   is toward the center of gravity,
>>> +  usually to the core of the planet, and users would likely expect a value of
>>> +  9.81N upwards along the (z) axis when the device is held with its screen
>>> +  perpendicular to the planets surface and 0 on the other axes.
>>
>> I'd have thought screen parallel  - i.e. z is out of the screen?
>> Might be the same thing I suppose, but I'd define it simply as into the screen
>> then y towards top of screen and x from left to right of the screen.
> 
> Trying to fix up the confusion by rewording.
> 
>>> +- Magnetometers (compasses) have their frame of reference relative to the
>>> +  geomagnetic field. In a mounting matrix for a magnetometer sensor the main
>>> +  hardware orientation 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.
>>
>> Same issue, world to frame transform is not included...
> 
> OK rewording, this is all about the system-to-world really.
> 
>>> +- Gyroscopes detects the movement relative the device itself, and has no other
>>> +  frame of reference than the mounting chassis itself.
>>
>> This is true for all of them as far as we are concerned here...
>>> The angular momentum is
>> Hang on, where did momentum come into it from?  Mems gyros are detecting rate
>> of change of rotation about an axis (lets ignore the significant cross talk and
>> effects of linear acceleration and pretend it's all easy here ;)
>>
>> Rest of this description is fine.
> 
> Angular velocity. Sorry, just screwed it up.
> 
>>> +Flipped X axis (negative values means positive):
>>> +
>>> +mount-matrix = "-1", "0", "0",
>>> +               "0", "1", "0",
>>> +               "0", "0", "1";
>>
>> Hmm. This is an odd one as it basically means the device had a right hand
>> coordinate system in the first place... If that happens I think we should
>> by default report the negative of the scale for that axis.
>>
>> We've never strictly defined a coordinate system but I think left handed
>> is a good start!
>>> +
>>> +X and Y flipped (X values are for Y and Y values are for X):
>>> +
>>> +mount-matrix = "0", "1", "0",
>>> +               "1", "0", "0",
>>> +               "0", "0", "1";
>> Same with this one, we are flipping coordinate systems.
> 
> Hm you have a point.
> 
> Those are inspired by the touchscreen input properties
> Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt
> as those have:
> 
>  - touchscreen-inverted-x       : X axis is inverted (boolean)
>  - touchscreen-inverted-y       : Y axis is inverted (boolean)
>  - touchscreen-swapped-x-y      : X and Y axis are swapped (boolean)
>                                   Swapping is done after inverting the axis
> 
> By supporting the mount matrix we open the door for augmenting
> driver bugs with this. Sigh.
> 
>> I'd expect only
>> rotation matrices to be valid mount matrices.
> 
> OK what about sensor mounted upside-down relative device:
> 
> mount-matrix = "1", "0", "0",
>                "0", "1", "0",
>                "0", "0", "-1";
> 
> Sensor mounted standing on the side so X becomes Z
> and Z becomes X:
> 
> mount-matrix = "0", "0", "1",
>                "0", "1", "0",
>                "1", "0", "0";
> 
> Are these proper rotation matrices?
Determinant = 1? 

Err (been a while) but using trusted wolfram alpa.

Nope to the first one That's a rotoinversion.
No to the second as well..  You can't end up just swapping axis.

Imagine taking your thumb and first two fingers to form a 3D axis
then see if you can spin it using your circus skills to match
the new orientation.

> 
>>> +Complex angular mounting with X and Z in a certain tilted orienation and
>> orientation
>>> +Y flipped:
>>> +
>>> +mount-matrix = "-0.984807753012208",  /* x0 */
>>> +               "0",                   /* y0 */
>>> +               "-0.173648177666930",  /* z0 */
>>> +               "0",                   /* x1 */
>>> +               "-1",                  /* y1 */
>>> +               "0",                   /* z1 */
>>> +               "-0.173648177666930",  /* x2 */
>>> +               "0",                   /* y2 */
>>> +               "0.984807753012208";   /* z2 */
>>>
This one is a rotation ;)
>>
>> Anyhow, now my head hurts.
> 
> That is a real-world example from the AK8975 on some Nokia...
> 
> Yours,
> Linus Walleij
>