Re: [PATCH] iio/hid: Add mount_matrix

[Jakob Hauser <jahau@rocketmail.com>]

Hi Hans,

On 28.06.22 14:33, Hans de Goede wrote:
> Hi,
> 
> On 6/27/22 11:55, Bastien Nocera wrote:
...
>>
>> [1]:
>> https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/tree/Documentation/ABI/testing/sysfs-bus-iio#n1838
>> An implementor might consider that for a hand-held device, a
>> 'natural' orientation would be 'front facing camera at the top'.
>> The main hardware reference frame could then be described as :
>> * Y is in the plane of the screen and is positive towards the
>>   top of the screen ;
>> * X is in the plane of the screen, perpendicular to Y axis, and
>>   positive towards the right hand side of the screen ;
>> * Z is perpendicular to the screen plane and positive out of the
>>   screen.
> 
> Note though that this does not clearly define what
> e.g. "positive towards the top of the screen" means if
> you look at the axis illustrations in both the Windows,
> Android and W3C docs they all have an arrow pointing
> towards the top of the screen for the Y axis, which
> matches the "positive towards the top of the screen"
> wording.

The above actually just defines the general coordinate system of a
hand-held device. Similar to e.g. [1].

[1]
https://source.android.com/devices/sensors/sensor-types#sensor_axis_definition

> Yet Android / W3C expect a positive reading when
> the G force vector is pointing down. Which I still
> find confusing.

In the Android docs in link [2], the third example description states:

"When the device lies flat on a table, the acceleration value along z is
+9.81 alo, which corresponds to the acceleration of the device (0 m/s^2)
minus the force of gravity (-9.81 m/s^2)."

So it is 0 - (-9.81) = +9.81. Confusing indeed. I think this is what you
called "force countering gravity". More on this further below.

[2] https://source.android.com/devices/sensors/sensor-types#accelerometer

> This means that we to add a text similar to the Windows
> docs here, say something like (made up by me not copy
> pasted from Windows docs):
> 
> "The Z-axis reading will be -1G when a device is laying
> flat on a table with its display facing up"
> 
> To fix the are we measuring gravity or force countering
> gravity confusion.

As far as I can see, Windows distinguishes between "standard
accelerometer", "linear accelerometer" and "gravity accelerometer".
Links [3] and [4] are from the accelerometer sample, link [5] is from
the API. The general description [6] is not very clear on this.

[3]
https://github.com/Microsoft/Windows-universal-samples/tree/main/Samples/Accelerometer#accelerometer-sample
[4]
https://github.com/microsoft/Windows-universal-samples/blob/win10-2004/Samples/Accelerometer/cpp/Scenario0_Choose.xaml.cpp#L40-L47
[5]
https://docs.microsoft.com/en-us/uwp/api/windows.devices.sensors.accelerometerreadingtype?view=winrt-22621#fields
[6]
https://docs.microsoft.com/en-us/windows/uwp/devices-sensors/sensors#accelerometer

W3C also has such differentiation called "Accelerometer",
"LinearAccelerationSensor" and "GravitySensor", see e.g. link [7]
chapter 6. A further link [8] indicates that the subtypes "are most
likely fusion sensors".

[7] https://w3c.github.io/accelerometer/#contents
[8] https://www.w3.org/TR/motion-sensors/#gravity-and-linear-acceleration

That doesn't explain much yet. I'm just raising the topic of different
purposes. It looks to me like at a device on a table with screen up, -1G
is the gravity vector and +1G is the acceleration acting on the device.
So according to that, we're measuring the gravity vector. That's fine
for auto-rotating the display.

What does this means for dynamic acceleration measurement? In the above
link [2] about Android accelerometer, there are four example
descriptions. Let's take our case with the device on the table, screen
up, measuring -1G. For the first example, free fall, we would need to
accelerate positively to get 0G. The fourth example, accelerating into
the sky, this would mean a negative acceleration in our case, getting
closer to -2G. Accordingly, in the second example, pushing the device
"on its left side toward the right", we would get a negative x acceleration.

I'm not fully sure I got this right, I don't have any practical
experience with accelerometers. Though from the last paragraph, it looks
to me that dynamic acceleration measurement return inverted values.
Maybe someone would need to confirm this, though it's not easy to take
measurements on a device being accelerated dynamically.

The Windows documentation in the above link [6] is not very clear about
this. It says "[...] Accelerometer sensor measures G-force values along
the X, Y, and Z axes of the device [...]". This sounds rather unspecific
to me. I don't really know what it does in the end. However, if they
mean "g-force" literally, it's the inverse reaction of acceleration [9].
Also it looks to me that Windows is not measuring acceleration in m/s^2
but "g-force" in "g", according to the sentence "Note that the
gravitational vector should normalize to 1 for a stationary device" in
the above link [6].

[9] https://en.wikipedia.org/wiki/G-force

My intention of writing these lines here is not to change the current
implementation but rather to get a clearer picture of what we're
actually measuring, thus helping to improve the documentation.
Summarizing it looks to me that statically we're measuring the gravity
vector and dynamically the centrifugal acceleration.

Although for gravity, within IIO subsystem there is another interface
called "in_gravity_" [10].

[10]
https://github.com/torvalds/linux/blob/v5.18/Documentation/ABI/testing/sysfs-bus-iio#L236-L244

> Jonathan, shall I submit a patch to add this, maybe with
> some extra text that we are following the Windows/HID
> convention and that Android/W3C do things differently?

The following file [11] would need to be adapted accordingly.

[11]
https://github.com/torvalds/linux/blob/v5.18/Documentation/devicetree/bindings/iio/mount-matrix.txt#L49-L91

Kind regards,
Jakob