Inertial (measurement unit) data published by ServerInertial and IOrientationSensor is not fully defined

[traversaro]

The data published by the inertial device (ServerInertial class, documented in http://www.yarp.it/classyarp_1_1dev_1_1ServerInertial.html ) is not completely defined.
In particular:

• The convention used for the RPY angles is undocumented.
• The location of the "inertial" world frame with respect to which the sensor frame is expressed is not documented.

The first point is not critical (the convention is not documented but well understood among the users, see iDynTree::Rotation documentation for a documentation we can copy) while the second one is more subtle.

Considering that the XSens MTx was the device for which the inertial was firstly implemented, we can take its definition of the "inertial" world frame, i.e. :
X : NORTH
Y : WEST
Z : UP
See http://wiki.icub.org/images/8/82/XsensMtx.pdf , page 6 , section 2.3.2 .

However we should make sure that existing device follow this convention, see for example this issue in Gazebo : https://bitbucket.org/osrf/gazebo/issues/1959/add-ability-to-set-imu-initial-orientation .

Note that under the proposed convention, we are assuming that the IMU sensors are used near the earth surface, however considering that this kind of sensor only works near the earth surface it seems to be a reasonable assumption.

[traversaro]

Apparently also in Gazebo we are (implicitly) using the NWU frame by default, see https://bitbucket.org/osrf/gazebo/pull-requests/2316/issue-1959-imu-fixes/diff#Lgazebo/sensors/ImuSensor.ccT238 .

[traversaro]

Just noticed that in http://www.yarp.it/classyarp_1_1dev_1_1ServerInertial.html we also need to document the unit of measurement.

[randaz81]

I dislike the inheritance of server inertial from IGenericSensor (or from generic IAnalogSensor et similia). Generally speaking, I think we should go for more detailed interfaces (for example: IInertialSensor) and use more the client interfaces in our modules. For example, the interface could have a non-ambiguous, well documented getRPYangles(), getGyros() etc..

[traversaro]

The same problems actually still applies to IOrientationSensors interfaces (see

yarp/src/libYARP_dev/include/yarp/dev/MultipleAnalogSensorsInterfaces.h

Line 215 in 7ee03f8

class YARP_dev_API yarp::dev::IOrientationSensors

).

Fortunately, since 2016 a few standards emerged that fortunately should match what we always did in the IMU, so in the documentation we should just reference that standards.

The convention used for the RPY angles is undocumented.

Fortunatly, the convention that we use is consistent with the one adopted in the section 12.29 3DOrientation of the OPC 10001-11 - Amendment 11: Spatial Types OPC UA standard https://opcfoundation.org/developer-tools/specifications-unified-architecture/errata-and-amendments/ . In particular, the Appendix G is quite useful (if you pretend that the Wikipedia reference is not there O_o ):

I think it make sense to mention this standard in the documentation to explain the RPY convention used in YARP.

The location of the "inertial" world frame with respect to which the sensor frame is expressed is not documented.

Not sure if it is relevant, but this https://www.w3.org/TR/orientation-sensor/ could be useful.

cc @CarlottaSartore @fjandrad @nunoguedelha

[fjandrad]

I see that the reference you posted

https://www.w3.org/TR/orientation-sensor/

Has the convention for absolute orientation with Y pointing to North instead of X as we were discussing previously. Which in the end is a choice. I am biased towards using X since it is more comfortable to explain when using the right hand rule xD

[fjandrad]

I'm not sure an action was decided or will be implemented. Should we close this issue @traversaro ?

[traversaro]

I'm not sure an action was decided or will be implemented. Should we close this issue @traversaro ?

The two main points of the issue are:

The convention used for the RPY angles is undocumented.

This has actually been fixed for MAP interfaces in http://www.yarp.it/classyarp_1_1dev_1_1IOrientationSensors.html#adb2a40d03c747aa9c8b7fc542f193fd9 . For ServerInertial, we should just point at this docs.

The location of the "inertial" world frame with respect to which the sensor frame is expressed is not documented.

This still is not solved, and I think it is quite important to clarify it especially checking the existing implementations and see if the comply with it, as otherwise user will not know how to use the measure. For example, can we at least assume that the inertial frame will have the Z direction opposite to gravity? If not, this will affect a lot of user code. I think that for example @MiladShafiee @prashanthr05 had exactly problem of this kind. In this case, the action is clear, and even if no one is currently working on it, I do not think it makes a lot of sense to close the issue.