[v2,02/10] iio: document bindings for mounting matrices

Commit Message

H. Nikolaus Schaller Feb. 21, 2019, 5:02 p.m. UTC

From: Linus Walleij <[e-mail]>

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: Linus Walleij <[e-mail]>
Cc: Gregor Boirie <[e-mail]>
Cc: Sebastian Reichel <[e-mail]>
Cc: Samu Onkalo <[e-mail]>
Cc: [e-mail]
Signed-off-by: Linus Walleij <[e-mail]>
Signed-off-by: H. Nikolaus Schaller <[e-mail]>
---
 .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt

Comments

Rob Herring (Arm) Feb. 22, 2019, 11:42 p.m. UTC | #1

On Thu, 21 Feb 2019 18:02:47 +0100, "H. Nikolaus Schaller" wrote:
> From: Linus Walleij <[e-mail]>
> 
> 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: Linus Walleij <[e-mail]>
> Cc: Gregor Boirie <[e-mail]>
> Cc: Sebastian Reichel <[e-mail]>
> Cc: Samu Onkalo <[e-mail]>
> Cc: [e-mail]
> Signed-off-by: Linus Walleij <[e-mail]>
> Signed-off-by: H. Nikolaus Schaller <[e-mail]>
> ---
>  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>  1 file changed, 204 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt
> 

Reviewed-by: Rob Herring <[e-mail]>

Jonathan Corbet Feb. 25, 2019, 4:32 p.m. UTC | #2

On Thu, 21 Feb 2019 18:02:47 +0100
"H. Nikolaus Schaller" <[e-mail]> wrote:

> From: Linus Walleij <[e-mail]>
> 
> 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: Linus Walleij <[e-mail]>
> Cc: Gregor Boirie <[e-mail]>
> Cc: Sebastian Reichel <[e-mail]>
> Cc: Samu Onkalo <[e-mail]>
> Cc: [e-mail]
> Signed-off-by: Linus Walleij <[e-mail]>
> Signed-off-by: H. Nikolaus Schaller <[e-mail]>
> ---
>  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>  1 file changed, 204 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt

So forgive me, but I have to ask: what are the chances of getting this
file in RST format?  It's 99% of the way there now, finishing the job
would allow it to be integrated into our docs tree.

It should probably have an SPDX line too.

Thanks,

jon

Linus Walleij Feb. 25, 2019, 6:24 p.m. UTC | #3

Hi Jon,

On Mon, Feb 25, 2019 at 5:32 PM Jonathan Corbet <[e-mail]> wrote:

> >  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++

So this is a device tree binding.

> So forgive me, but I have to ask: what are the chances of getting this
> file in RST format?  It's 99% of the way there now, finishing the job
> would allow it to be integrated into our docs tree.
>
> It should probably have an SPDX line too.

The recent direction of the Device Tree bindings are not in the RST
direction but in the direction of using another formal structure: YAML
schemas.

See e.g. Documentation/devicetree/bindings/example-schema.yaml

The YAML schema makes it possible to verify device trees and examples
inside the bindings to the specification using a context-free grammar.

If we can join the RST and YAML ambitions is a good question. RST
has nice typesetting properties, YAML has nice grammatic properties.

Yours,
Linus Walleij

Jonathan Corbet Feb. 25, 2019, 6:29 p.m. UTC | #4

On Mon, 25 Feb 2019 19:24:36 +0100
Linus Walleij <[e-mail]> wrote:

> > >  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++  
> 
> So this is a device tree binding.

Ah, duh, I blame caffeine deficiency.  Ignore me, sorry for the noise.

jon

Rob Herring Feb. 25, 2019, 7:38 p.m. UTC | #5

On Mon, Feb 25, 2019 at 12:24 PM Linus Walleij <[e-mail]> wrote:
>
> Hi Jon,
>
> On Mon, Feb 25, 2019 at 5:32 PM Jonathan Corbet <[e-mail]> wrote:
>
> > >  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>
> So this is a device tree binding.
>
> > So forgive me, but I have to ask: what are the chances of getting this
> > file in RST format?  It's 99% of the way there now, finishing the job
> > would allow it to be integrated into our docs tree.
> >
> > It should probably have an SPDX line too.
>
> The recent direction of the Device Tree bindings are not in the RST
> direction but in the direction of using another formal structure: YAML
> schemas.
>
> See e.g. Documentation/devicetree/bindings/example-schema.yaml
>
> The YAML schema makes it possible to verify device trees and examples
> inside the bindings to the specification using a context-free grammar.
>
> If we can join the RST and YAML ambitions is a good question. RST
> has nice typesetting properties, YAML has nice grammatic properties.

In fact there has been some experimentation there. The 'description'
portion of DT schema can be RST. And the rest being structured data
could be transformed to RST. Grant did some experiments there. The
idea being to generate the DT spec from schema (rather than integrate
into the kernel docs). But not much progress there and it's not
something I'm spending time on ATM.

Rob

Jonathan Cameron March 3, 2019, 3:19 p.m. UTC | #6

On Thu, 21 Feb 2019 18:02:47 +0100
"H. Nikolaus Schaller" <[e-mail]> wrote:

> From: Linus Walleij <[e-mail]>
> 
> 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: Linus Walleij <[e-mail]>
> Cc: Gregor Boirie <[e-mail]>
> Cc: Sebastian Reichel <[e-mail]>
> Cc: Samu Onkalo <[e-mail]>
> Cc: [e-mail]
> Signed-off-by: Linus Walleij <[e-mail]>
> Signed-off-by: H. Nikolaus Schaller <[e-mail]>
Hi Nikolaus

A few minor notes inline.

> ---
>  .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>  1 file changed, 204 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..1b64c8b1f689
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
> @@ -0,0 +1,204 @@
> +For discussion. Unclear are:
> +* is the definition of +/- values practical or counterintuitive?
> +* are the definitions unambiguous and easy to follow?
> +* are the examples correct?
> +* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
> +
> +====
> +
> +
> +Mounting matrix
> +
> +The mounting matrix is a device tree property used to orient any IIO device

Minor, but DT bindings are in theory not Linux specific and IIO is, so
should be "any device"

> +that produce three-dimensional data in relation to the world where it is
> +deployed.
> +
> +The purpose of the mounting matrix is to translate the sensor frame of
> +reference into the device frame of reference using a translation matrix as
> +defined in linear algebra.
> +
> +The typical usecase is that where a component has an internal representation
> +of the (x,y,z) triplets, such as different registers to read these coordinates,
> +and thus implying that the component should be mounted in a certain orientation
> +relative to some specific device frame of reference.
> +
> +For example a device with some kind of screen, where the user is supposed to
> +interact with the environment using an accelerometer, gyroscope or magnetometer
> +mounted on the same chassis as this screen, will likely take the screen as
> +reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
> +screen and (z) being depth, the axis perpendicular to the screen.
> +
> +For a screen you probably want (x) coordinates to go from negative on the left
> +to positive on the right, (y) from negative on the bottom to positive on top
> +and (z) depth to be negative under the screen and positive in front of it,
> +toward the face of the user.
> +
> +A sensor can be mounted in any angle along the axes relative to the frame of
> +reference. This means that the sensor may be flipped upside-down, left-right,
> +or tilted at any angle relative to the frame of reference.
> +
> +Another frame of reference is how the device with its sensor relates to the
> +external world, the environment where the device is deployed. Usually the data
> +from the sensor is used to figure out how the device is oriented with respect
> +to this world. When using the mounting matrix, the sensor and device orientation
> +becomes identical and we can focus on the data as it relates to the surrounding
> +world.
> +
> +Device-to-world examples for some three-dimensional sensor types:
> +
> +- Accelerometers have their world frame of reference toward the center of
> +  gravity, usually to the core of the planet. A reading of the (x,y,z) values
> +  from the sensor will give a projection of the gravity vector through the
> +  device relative to the center of the planet, i.e. relative to its surface at
> +  this point. Up and down in the world relative to the device frame of
> +  reference can thus be determined. and users would likely expect a value of
> +  9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
> +  is held with its screen flat on the planets surface and 0 on the other axes,
> +  as the gravity vector is projected 1:1 onto the sensors (z)-axis.

Nitpick: Screen is face down or face up?  Someone might think a screen is
flat when looking up at them from the floor or the other way up.
I 'think' it's face down in the following...


> +
> +  If you tilt the device, the g vector virtually coming out of the display
> +  is projected onto the (x,y) plane of the display panel.
> +
> +  Example:
> +

space after > for z. Or making it consistent anyway.
Hmm. 

> +         ^ z: +g                   ^ z: >0
> +         !                        /!
> +         ! x=y=0                 / ! x: > 0
> +     +--------+             +--------+
> +     !        !             !        !
> +     +--------+             +--------+
> +         !                    /
> +         !                   /
> +         v                  v
> +      center of         center of
> +       gravity           gravity
> +
> +
> +  If the device is tilted to the left, you get a positive x value. If you point
> +  its top towards surface, you get a negative y axis.
> +
> +     (---------)
> +     !         !           y: -g
> +     !         !             ^
> +     !         !             !
> +     !         !
> +     !         !  x: +g <- z: +g  -> x: -g
> +     ! 1  2  3 !
> +     ! 4  5  6 !             !
> +     ! 7  8  9 !             v
> +     ! *  0  # !           y: +g
> +     (---------)
> +
> +
> +- Magnetometers (compasses) have their world frame of reference relative to the
> +  geomagnetic field. The system orientation vis-a-vis the world is defined with
> +  respect to the local earth geomagnetic reference frame where (y) is in the
> +  ground plane and positive towards magnetic North, (x) is in the ground plane,
> +  perpendicular to the North axis and positive towards the East and (z) is
> +  perpendicular to the ground plane and positive upwards.
> +
> +
> +     ^^^ North: y > 0
> +
> +     (---------)
> +     !         !
> +     !         !
> +     !         !
> +     !         !  >
> +     !         !  > North: x > 0
> +     ! 1  2  3 !  >
> +     ! 4  5  6 !
> +     ! 7  8  9 !
> +     ! *  0  # !
> +     (---------)
> +
> +  Since the geomagnetic field is not uniform this definition fails if we come
> +  closer to the poles.
> +
> +  Sensors and driver can not and should not take care of this because there
> +  are complex calculations and empirical data to be taken care of. We leave
> +  this up to user space.
> +
> +  The definition we take:
> +
> +  If the device is placed at the equator and the top is pointing north, the
> +  display is readable by a person standing upright on the earth surface, this
> +  defines a positive y value.
Nice definition. <wonders how consistent it is at the equator - meh close enough :)>
> +
> +
> +- Gyroscopes detects the movement relative the device itself. The angular
> +  velocity is defined as orthogonal to the plane of rotation, so if you put the
> +  device on a flat surface and spin it around the z axis (such as rotating a
> +  device with a screen lying flat on a table), you should get a negative value
> +  along the (z) axis if rotated clockwise, and a positive value if rotated
> +  counter-clockwise according to the right-hand rule.
> +
> +
> +     (---------)     y > 0
> +     !         !     v---\
> +     !         !
> +     !         !
> +     !         !      <--\
> +     !         !         ! z > 0
> +     ! 1  2  3 !       --/
> +     ! 4  5  6 !
> +     ! 7  8  9 !
> +     ! *  0  # !
> +     (---------)
> +
> +
> +So unless the sensor is ideally mounted, we need a means to indicate the
> +relative orientation of any given sensor of this type with respect to the
> +frame of reference.
> +
> +To achieve this, use the device tree property "mount-matrix" for the sensor.
> +
> +This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
> +to orient the senor axes relative to a desired point of reference. This means
> +the resulting values from the sensor, after scaling to proper units, should be
> +multiplied by this matrix to give the proper vectors values in three-dimensional
> +space, relative to the device or world point of reference.
> +
> +For more information, consult:
> +https://en.wikipedia.org/wiki/Rotation_matrix
> +
> +The mounting matrix has the layout:
> +
> + (mxx, myx, mzx)
> + (mxy, myy, mzy)
> + (mxz, myz, mzz)
> +
> +Values are intended to be multiplied as:
> +
> +  x' = mxx * x + myx * y + mzx * z
> +  y' = mxy * x + myy * y + mzy * z
> +  z' = mxz * x + myz * y + mzz * z
> +
> +It is represented as an array of strings containing the real values for
> +producing the transformation matrix. The real values use a decimal point and
> +a minus (-) to indicate a negative value.

I'd drop the decimal point and negative as both fairly obvious and this
sentence can currently be read as a decimal point is necessary for a negative.

> +
> +Examples:
> +
> +Identity matrix (nothing happens to the coordinates, which means the device was
> +mechanically mounted in an ideal way and we need no transformation):
> +
> +mount-matrix = "1", "0", "0",
> +               "0", "1", "0",
> +               "0", "0", "1";
> +
> +The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
> +compensate by performing a -30 degrees rotation around the X axis:
> +
> +mount-matrix = "1", "0", "0",
> +               "0", "0.866", "0.5",
> +               "0", "-0.5", "0.866";
> +
> +The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
> +upside-down:
> +
> +mount-matrix = "0.998", "0.054", "0",
> +               "-0.054", "0.998", "0",
> +               "0", "0", "1";
> +
> +???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
Yes. Good to say this.

Very nice indeed, just these little tidy ups and I'm very happy with the
result!

Jonathan

H. Nikolaus Schaller March 7, 2019, 12:53 p.m. UTC | #7

Hi Jonathan,

> Am 03.03.2019 um 16:19 schrieb Jonathan Cameron <[e-mail]>:
> 
> On Thu, 21 Feb 2019 18:02:47 +0100
> "H. Nikolaus Schaller" <[e-mail]> wrote:
> 
>> From: Linus Walleij <[e-mail]>
>> 
>> 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: Linus Walleij <[e-mail]>
>> Cc: Gregor Boirie <[e-mail]>
>> Cc: Sebastian Reichel <[e-mail]>
>> Cc: Samu Onkalo <[e-mail]>
>> Cc: [e-mail]
>> Signed-off-by: Linus Walleij <[e-mail]>
>> Signed-off-by: H. Nikolaus Schaller <[e-mail]>
> Hi Nikolaus
> 
> A few minor notes inline.

> 
>> ---
>> .../devicetree/bindings/iio/mount-matrix.txt  | 204 ++++++++++++++++++
>> 1 file changed, 204 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..1b64c8b1f689
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
>> @@ -0,0 +1,204 @@
>> +For discussion. Unclear are:
>> +* is the definition of +/- values practical or counterintuitive?
>> +* are the definitions unambiguous and easy to follow?
>> +* are the examples correct?
>> +* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
>> +
>> +====
>> +
>> +
>> +Mounting matrix
>> +
>> +The mounting matrix is a device tree property used to orient any IIO device
> 
> Minor, but DT bindings are in theory not Linux specific and IIO is, so
> should be "any device"
> 
>> +that produce three-dimensional data in relation to the world where it is
>> +deployed.
>> +
>> +The purpose of the mounting matrix is to translate the sensor frame of
>> +reference into the device frame of reference using a translation matrix as
>> +defined in linear algebra.
>> +
>> +The typical usecase is that where a component has an internal representation
>> +of the (x,y,z) triplets, such as different registers to read these coordinates,
>> +and thus implying that the component should be mounted in a certain orientation
>> +relative to some specific device frame of reference.
>> +
>> +For example a device with some kind of screen, where the user is supposed to
>> +interact with the environment using an accelerometer, gyroscope or magnetometer
>> +mounted on the same chassis as this screen, will likely take the screen as
>> +reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
>> +screen and (z) being depth, the axis perpendicular to the screen.
>> +
>> +For a screen you probably want (x) coordinates to go from negative on the left
>> +to positive on the right, (y) from negative on the bottom to positive on top
>> +and (z) depth to be negative under the screen and positive in front of it,
>> +toward the face of the user.
>> +
>> +A sensor can be mounted in any angle along the axes relative to the frame of
>> +reference. This means that the sensor may be flipped upside-down, left-right,
>> +or tilted at any angle relative to the frame of reference.
>> +
>> +Another frame of reference is how the device with its sensor relates to the
>> +external world, the environment where the device is deployed. Usually the data
>> +from the sensor is used to figure out how the device is oriented with respect
>> +to this world. When using the mounting matrix, the sensor and device orientation
>> +becomes identical and we can focus on the data as it relates to the surrounding
>> +world.
>> +
>> +Device-to-world examples for some three-dimensional sensor types:
>> +
>> +- Accelerometers have their world frame of reference toward the center of
>> +  gravity, usually to the core of the planet. A reading of the (x,y,z) values
>> +  from the sensor will give a projection of the gravity vector through the
>> +  device relative to the center of the planet, i.e. relative to its surface at
>> +  this point. Up and down in the world relative to the device frame of
>> +  reference can thus be determined. and users would likely expect a value of
>> +  9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
>> +  is held with its screen flat on the planets surface and 0 on the other axes,
>> +  as the gravity vector is projected 1:1 onto the sensors (z)-axis.
> 
> Nitpick: Screen is face down or face up?  Someone might think a screen is
> flat when looking up at them from the floor or the other way up.
> I 'think' it's face down in the following...
> 
> 
>> +
>> +  If you tilt the device, the g vector virtually coming out of the display
>> +  is projected onto the (x,y) plane of the display panel.
>> +
>> +  Example:
>> +
> 
> space after > for z. Or making it consistent anyway.
> Hmm. 
> 
>> +         ^ z: +g                   ^ z: >0
>> +         !                        /!
>> +         ! x=y=0                 / ! x: > 0
>> +     +--------+             +--------+
>> +     !        !             !        !
>> +     +--------+             +--------+
>> +         !                    /
>> +         !                   /
>> +         v                  v
>> +      center of         center of
>> +       gravity           gravity
>> +
>> +
>> +  If the device is tilted to the left, you get a positive x value. If you point
>> +  its top towards surface, you get a negative y axis.
>> +
>> +     (---------)
>> +     !         !           y: -g
>> +     !         !             ^
>> +     !         !             !
>> +     !         !
>> +     !         !  x: +g <- z: +g  -> x: -g
>> +     ! 1  2  3 !
>> +     ! 4  5  6 !             !
>> +     ! 7  8  9 !             v
>> +     ! *  0  # !           y: +g
>> +     (---------)
>> +
>> +
>> +- Magnetometers (compasses) have their world frame of reference relative to the
>> +  geomagnetic field. The system orientation vis-a-vis the world is defined with
>> +  respect to the local earth geomagnetic reference frame where (y) is in the
>> +  ground plane and positive towards magnetic North, (x) is in the ground plane,
>> +  perpendicular to the North axis and positive towards the East and (z) is
>> +  perpendicular to the ground plane and positive upwards.
>> +
>> +
>> +     ^^^ North: y > 0
>> +
>> +     (---------)
>> +     !         !
>> +     !         !
>> +     !         !
>> +     !         !  >
>> +     !         !  > North: x > 0
>> +     ! 1  2  3 !  >
>> +     ! 4  5  6 !
>> +     ! 7  8  9 !
>> +     ! *  0  # !
>> +     (---------)
>> +
>> +  Since the geomagnetic field is not uniform this definition fails if we come
>> +  closer to the poles.
>> +
>> +  Sensors and driver can not and should not take care of this because there
>> +  are complex calculations and empirical data to be taken care of. We leave
>> +  this up to user space.
>> +
>> +  The definition we take:
>> +
>> +  If the device is placed at the equator and the top is pointing north, the
>> +  display is readable by a person standing upright on the earth surface, this
>> +  defines a positive y value.
> Nice definition. <wonders how consistent it is at the equator - meh close enough :)>
>> +
>> +
>> +- Gyroscopes detects the movement relative the device itself. The angular
>> +  velocity is defined as orthogonal to the plane of rotation, so if you put the
>> +  device on a flat surface and spin it around the z axis (such as rotating a
>> +  device with a screen lying flat on a table), you should get a negative value
>> +  along the (z) axis if rotated clockwise, and a positive value if rotated
>> +  counter-clockwise according to the right-hand rule.
>> +
>> +
>> +     (---------)     y > 0
>> +     !         !     v---\
>> +     !         !
>> +     !         !
>> +     !         !      <--\
>> +     !         !         ! z > 0
>> +     ! 1  2  3 !       --/
>> +     ! 4  5  6 !
>> +     ! 7  8  9 !
>> +     ! *  0  # !
>> +     (---------)
>> +
>> +
>> +So unless the sensor is ideally mounted, we need a means to indicate the
>> +relative orientation of any given sensor of this type with respect to the
>> +frame of reference.
>> +
>> +To achieve this, use the device tree property "mount-matrix" for the sensor.
>> +
>> +This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
>> +to orient the senor axes relative to a desired point of reference. This means
>> +the resulting values from the sensor, after scaling to proper units, should be
>> +multiplied by this matrix to give the proper vectors values in three-dimensional
>> +space, relative to the device or world point of reference.
>> +
>> +For more information, consult:
>> +https://en.wikipedia.org/wiki/Rotation_matrix
>> +
>> +The mounting matrix has the layout:
>> +
>> + (mxx, myx, mzx)
>> + (mxy, myy, mzy)
>> + (mxz, myz, mzz)
>> +
>> +Values are intended to be multiplied as:
>> +
>> +  x' = mxx * x + myx * y + mzx * z
>> +  y' = mxy * x + myy * y + mzy * z
>> +  z' = mxz * x + myz * y + mzz * z
>> +
>> +It is represented as an array of strings containing the real values for
>> +producing the transformation matrix. The real values use a decimal point and
>> +a minus (-) to indicate a negative value.
> 
> I'd drop the decimal point and negative as both fairly obvious and this
> sentence can currently be read as a decimal point is necessary for a negative.
> 
>> +
>> +Examples:
>> +
>> +Identity matrix (nothing happens to the coordinates, which means the device was
>> +mechanically mounted in an ideal way and we need no transformation):
>> +
>> +mount-matrix = "1", "0", "0",
>> +               "0", "1", "0",
>> +               "0", "0", "1";
>> +
>> +The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
>> +compensate by performing a -30 degrees rotation around the X axis:
>> +
>> +mount-matrix = "1", "0", "0",
>> +               "0", "0.866", "0.5",
>> +               "0", "-0.5", "0.866";
>> +
>> +The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
>> +upside-down:
>> +
>> +mount-matrix = "0.998", "0.054", "0",
>> +               "-0.054", "0.998", "0",
>> +               "0", "0", "1";
>> +
>> +???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
> Yes. Good to say this.
> 
> Very nice indeed, just these little tidy ups and I'm very happy with the
> result!
> 
> Jonathan


Thanks for pushing the other patches forwards.

Yes, I know this needs more discussion. So I'll go through your comments in a few days and post an update just for this.

BR and thanks,
Nikolaus

Linus Walleij July 23, 2019, 7:42 a.m. UTC | #8

Hi H. Nikolaus,

On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <[e-mail]> wrote:

> From: Linus Walleij <[e-mail]>

It is fair for you to change authorship to yourself at this point.
Just keeping my Signed-off-by is sufficient.

> 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: Linus Walleij <[e-mail]>
> Cc: Gregor Boirie <[e-mail]>
> Cc: Sebastian Reichel <[e-mail]>
> Cc: Samu Onkalo <[e-mail]>
> Cc: [e-mail]
> Signed-off-by: Linus Walleij <[e-mail]>
> Signed-off-by: H. Nikolaus Schaller <[e-mail]>

Did this patch fall off somewhere? I think it's really neat, even in this
form it is great help for developers. If you want I can try picking up the
comments and resend it.

Linus Walleij

H. Nikolaus Schaller July 23, 2019, 9:46 a.m. UTC | #9

Hi Linus,

> Am 23.07.2019 um 09:42 schrieb Linus Walleij <[e-mail]>:
> 
> Hi H. Nikolaus,
> 
> On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <[e-mail]> wrote:
> 
>> From: Linus Walleij <[e-mail]>
> 
> It is fair for you to change authorship to yourself at this point.
> Just keeping my Signed-off-by is sufficient.

Well, I think my contribution is less than yours :)

> 
>> 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: Linus Walleij <[e-mail]>
>> Cc: Gregor Boirie <[e-mail]>
>> Cc: Sebastian Reichel <[e-mail]>
>> Cc: Samu Onkalo <[e-mail]>
>> Cc: [e-mail]
>> Signed-off-by: Linus Walleij <[e-mail]>
>> Signed-off-by: H. Nikolaus Schaller <[e-mail]>
> 
> Did this patch fall off somewhere? I think it's really neat, even in this
> form it is great help for developers. If you want I can try picking up the
> comments and resend it.

Well, I had planned to review it again and promised to send out a new
version. But as usual this ToDo becomes hidden by always more important
tasks.

So I am fine if you can pick comments and resend it. I think there will
be others who help to make it even better in the future if the mount matrix
is more widely used.

BR,
Nikolaus

Andy Shevchenko July 23, 2019, 3:39 p.m. UTC | #10

On Tue, Jul 23, 2019 at 09:42:59AM +0200, Linus Walleij wrote:
> On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <[e-mail]> wrote:

> > From: Linus Walleij <[e-mail]>
> 
> It is fair for you to change authorship to yourself at this point.
> Just keeping my Signed-off-by is sufficient.

...or Co-developed-by: can be used.

Jonathan Cameron July 28, 2019, 7:50 a.m. UTC | #11

On Tue, 23 Jul 2019 11:46:49 +0200
"H. Nikolaus Schaller" <[e-mail]> wrote:

> Hi Linus,
> 
> > Am 23.07.2019 um 09:42 schrieb Linus Walleij <[e-mail]>:
> > 
> > Hi H. Nikolaus,
> > 
> > On Thu, Feb 21, 2019 at 6:03 PM H. Nikolaus Schaller <[e-mail]> wrote:
> >   
> >> From: Linus Walleij <[e-mail]>  
> > 
> > It is fair for you to change authorship to yourself at this point.
> > Just keeping my Signed-off-by is sufficient.  
> 
> Well, I think my contribution is less than yours :)
> 
> >   
> >> 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: Linus Walleij <[e-mail]>
> >> Cc: Gregor Boirie <[e-mail]>
> >> Cc: Sebastian Reichel <[e-mail]>
> >> Cc: Samu Onkalo <[e-mail]>
> >> Cc: [e-mail]
> >> Signed-off-by: Linus Walleij <[e-mail]>
> >> Signed-off-by: H. Nikolaus Schaller <[e-mail]>  
> > 
> > Did this patch fall off somewhere? I think it's really neat, even in this
> > form it is great help for developers. If you want I can try picking up the
> > comments and resend it.  
> 
> Well, I had planned to review it again and promised to send out a new
> version. But as usual this ToDo becomes hidden by always more important
> tasks.
> 
> So I am fine if you can pick comments and resend it. I think there will
> be others who help to make it even better in the future if the mount matrix
> is more widely used.
> 
> BR,
> Nikolaus
> 
Given the comments that 'need' any response are fairly minor, I've just
taken the view that the perfect is the enemy of the good and applied
it to the togreg branch of iio.git with some really small tweaks.

Thanks for offering to tidy this up Linus, but seems like it would be
a waste of your time for such trivial tweaks!

The only one outstanding that I haven't 'fixed' is the question I raised
on face down or face up when talking about flat on the ground.

That might want a clarifying comment.

Applied to the togreg branch of iio.git and pushed out as testing
for the autobuilders to play with it (or not as the case may be!)

Thanks,

Jonathan

Linus Walleij July 28, 2019, 10:07 a.m. UTC | #12

On Sun, Jul 28, 2019 at 9:50 AM Jonathan Cameron <[e-mail]> wrote:

> Given the comments that 'need' any response are fairly minor, I've just
> taken the view that the perfect is the enemy of the good and applied
> it to the togreg branch of iio.git with some really small tweaks.

Oh that works, too :) whoever is most annoyed will get to fix any
remaining offenders.

The quality of documentation really depends on perspective.
This weekend I read some old UNIX System V manuals
and this was "extremly professional" documentation at one
point. It wasn't very good. I think we're pretty well off with what
we have here.

Yours,
Linus Walleij

Patch

diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
new file mode 100644
index 000000000000..1b64c8b1f689
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
@@ -0,0 +1,204 @@ 
+For discussion. Unclear are:
+* is the definition of +/- values practical or counterintuitive?
+* are the definitions unambiguous and easy to follow?
+* are the examples correct?
+* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
+
+====
+
+
+Mounting matrix
+
+The mounting matrix is a device tree property used to orient any IIO device
+that produce three-dimensional data in relation to the world where it is
+deployed.
+
+The purpose of the mounting matrix is to translate the sensor frame of
+reference into the device frame of reference using a translation matrix as
+defined in linear algebra.
+
+The typical usecase is that where a component has an internal representation
+of the (x,y,z) triplets, such as different registers to read these coordinates,
+and thus implying that the component should be mounted in a certain orientation
+relative to some specific device frame of reference.
+
+For example a device with some kind of screen, where the user is supposed to
+interact with the environment using an accelerometer, gyroscope or magnetometer
+mounted on the same chassis as this screen, will likely take the screen as
+reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
+screen and (z) being depth, the axis perpendicular to the screen.
+
+For a screen you probably want (x) coordinates to go from negative on the left
+to positive on the right, (y) from negative on the bottom to positive on top
+and (z) depth to be negative under the screen and positive in front of it,
+toward the face of the user.
+
+A sensor can be mounted in any angle along the axes relative to the frame of
+reference. This means that the sensor may be flipped upside-down, left-right,
+or tilted at any angle relative to the frame of reference.
+
+Another frame of reference is how the device with its sensor relates to the
+external world, the environment where the device is deployed. Usually the data
+from the sensor is used to figure out how the device is oriented with respect
+to this world. When using the mounting matrix, the sensor and device orientation
+becomes identical and we can focus on the data as it relates to the surrounding
+world.
+
+Device-to-world examples for some three-dimensional sensor types:
+
+- Accelerometers have their world frame of reference toward the center of
+  gravity, usually to the core of the planet. A reading of the (x,y,z) values
+  from the sensor will give a projection of the gravity vector through the
+  device relative to the center of the planet, i.e. relative to its surface at
+  this point. Up and down in the world relative to the device frame of
+  reference can thus be determined. and users would likely expect a value of
+  9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
+  is held with its screen flat on the planets surface and 0 on the other axes,
+  as the gravity vector is projected 1:1 onto the sensors (z)-axis.
+
+  If you tilt the device, the g vector virtually coming out of the display
+  is projected onto the (x,y) plane of the display panel.
+
+  Example:
+
+         ^ z: +g                   ^ z: >0
+         !                        /!
+         ! x=y=0                 / ! x: > 0
+     +--------+             +--------+
+     !        !             !        !
+     +--------+             +--------+
+         !                    /
+         !                   /
+         v                  v
+      center of         center of
+       gravity           gravity
+
+
+  If the device is tilted to the left, you get a positive x value. If you point
+  its top towards surface, you get a negative y axis.
+
+     (---------)
+     !         !           y: -g
+     !         !             ^
+     !         !             !
+     !         !
+     !         !  x: +g <- z: +g  -> x: -g
+     ! 1  2  3 !
+     ! 4  5  6 !             !
+     ! 7  8  9 !             v
+     ! *  0  # !           y: +g
+     (---------)
+
+
+- Magnetometers (compasses) have their world frame of reference relative to the
+  geomagnetic field. The system orientation vis-a-vis the world is defined with
+  respect to the local earth geomagnetic reference frame where (y) is in the
+  ground plane and positive towards magnetic North, (x) is in the ground plane,
+  perpendicular to the North axis and positive towards the East and (z) is
+  perpendicular to the ground plane and positive upwards.
+
+
+     ^^^ North: y > 0
+
+     (---------)
+     !         !
+     !         !
+     !         !
+     !         !  >
+     !         !  > North: x > 0
+     ! 1  2  3 !  >
+     ! 4  5  6 !
+     ! 7  8  9 !
+     ! *  0  # !
+     (---------)
+
+  Since the geomagnetic field is not uniform this definition fails if we come
+  closer to the poles.
+
+  Sensors and driver can not and should not take care of this because there
+  are complex calculations and empirical data to be taken care of. We leave
+  this up to user space.
+
+  The definition we take:
+
+  If the device is placed at the equator and the top is pointing north, the
+  display is readable by a person standing upright on the earth surface, this
+  defines a positive y value.
+
+
+- Gyroscopes detects the movement relative the device itself. The angular
+  velocity is defined as orthogonal to the plane of rotation, so if you put the
+  device on a flat surface and spin it around the z axis (such as rotating a
+  device with a screen lying flat on a table), you should get a negative value
+  along the (z) axis if rotated clockwise, and a positive value if rotated
+  counter-clockwise according to the right-hand rule.
+
+
+     (---------)     y > 0
+     !         !     v---\
+     !         !
+     !         !
+     !         !      <--\
+     !         !         ! z > 0
+     ! 1  2  3 !       --/
+     ! 4  5  6 !
+     ! 7  8  9 !
+     ! *  0  # !
+     (---------)
+
+
+So unless the sensor is ideally mounted, we need a means to indicate the
+relative orientation of any given sensor of this type with respect to the
+frame of reference.
+
+To achieve this, use the device tree property "mount-matrix" for the sensor.
+
+This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
+to orient the senor axes relative to a desired point of reference. This means
+the resulting values from the sensor, after scaling to proper units, should be
+multiplied by this matrix to give the proper vectors values in three-dimensional
+space, relative to the device or world point of reference.
+
+For more information, consult:
+https://en.wikipedia.org/wiki/Rotation_matrix
+
+The mounting matrix has the layout:
+
+ (mxx, myx, mzx)
+ (mxy, myy, mzy)
+ (mxz, myz, mzz)
+
+Values are intended to be multiplied as:
+
+  x' = mxx * x + myx * y + mzx * z
+  y' = mxy * x + myy * y + mzy * z
+  z' = mxz * x + myz * y + mzz * z
+
+It is represented as an array of strings containing the real values for
+producing the transformation matrix. 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";
+
+The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
+compensate by performing a -30 degrees rotation around the X axis:
+
+mount-matrix = "1", "0", "0",
+               "0", "0.866", "0.5",
+               "0", "-0.5", "0.866";
+
+The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
+upside-down:
+
+mount-matrix = "0.998", "0.054", "0",
+               "-0.054", "0.998", "0",
+               "0", "0", "1";
+
+???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation