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

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/iio/mount-matrix.txt

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/iio/mount-matrix.txt
Extension
.txt
Size
7618 bytes
Lines
204
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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 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
     +--------+             +--------+
     !        !             !        !
     +--------+             +--------+
         !                    /

Annotation

Implementation Notes