Hi Jonathan,
> Am 03.03.2019 um 16:19 schrieb Jonathan Cameron <jic23@xxxxxxxxxx>:
>
> On Thu, 21 Feb 2019 18:02:47 +0100
> "H. Nikolaus Schaller" <hns@xxxxxxxxxxxxx> wrote:
>
>> From: Linus Walleij <linus.walleij@xxxxxxxxxx>
>>
>> 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 <linus.walleij@xxxxxxxxxx>
>> Cc: Gregor Boirie <gregor.boirie@xxxxxxxxxx>
>> Cc: Sebastian Reichel <sre@xxxxxxxxxx>
>> Cc: Samu Onkalo <samu.onkalo@xxxxxxxxx>
>> Cc: devicetree@xxxxxxxxxxxxxxx
>> Signed-off-by: Linus Walleij <linus.walleij@xxxxxxxxxx>
>> Signed-off-by: H. Nikolaus Schaller <hns@xxxxxxxxxxxxx>
> 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
