Add unit and frame enums to Magnetometer protobuf message

[bperseghetti]

Summary

Add MagneticFieldUnit enum (GAUSS, TESLA, MICRO_TESLA, NANO_TESLA) and CoordinateFrame enum (ENU, NED) to the Magnetometer message. This allows consumers to know the unit and reference frame of the published magnetic field vector. The field name is kept as field_tesla for backward compatibility.

This fixes the fundamental issue that right now the message currently sends an NED frame in Gauss despite Gazebo being ENU and the message stating that the magnetic field is in Tesla.

Checklist

• Signed all commits for DCO
• Added tests
• Updated documentation (as needed)
• Updated migration guide (as needed)
• codecheck passed (See contributing)
• All tests passed (See test coverage)

Needed for:
gazebosim/gz-sensors#595
gazebosim/gz-sim#3373

[mjcarroll]

For all of our other sensors, I believe we require that measurements to be in SI units and ENU coordinates, correct? What is the benefit of diverging from that pattern here?

[bperseghetti]

Well, want to guess what units and coordinate frame our current magnetometer is publishing in?

[bperseghetti]

Here's the SDF specification:
https://sdformat.org/spec/1.12/world/#world_magnetic_field

Now here's the test world values (roughly gauss units, but maybe it's some arbitrary environment):
https://github.com/gazebosim/gz-sim/blame/5049587241f63826dca7fd9a4b501d1ba91a0a73/test/worlds/magnetometer.sdf#L4

Here's what happens when you take that same world, don't define a magnetic field and instead just allow it to use spherical coordinates (in this case Tokyo):

<sdf version="1.6">
  <world name="magnetometer_sensor">
    <physics name="1ms" type="ode">
      <max_step_size>0.001</max_step_size>
      <real_time_factor>0</real_time_factor>
    </physics>
    <plugin
      filename="gz-sim-physics-system"
      name="gz::sim::systems::Physics">
    </plugin>
    <plugin
      filename="gz-sim-magnetometer-system"
      name="gz::sim::systems::Magnetometer">
    </plugin>
    <plugin
      filename="gz-sim-scene-broadcaster-system"
      name="gz::sim::systems::SceneBroadcaster">
    </plugin>
    <spherical_coordinates>
      <surface_model>EARTH_WGS84</surface_model>
      <latitude_deg>35.6762</latitude_deg>
      <longitude_deg>139.6503</longitude_deg>
      <elevation>0</elevation>
      <heading_deg>0</heading_deg>
    </spherical_coordinates>
    
    <model name="ground_plane">
..........

This outputs:

[bperseghetti]

Except the test world has the magnetometer with some rotations applied to it, so then remove those:

    <model name="magnetometer_model">
      <pose>4 0 3.0 0 0.0 0</pose>
      <link name="link">
        <pose>0.05 0.05 0.05 0 0 0</pose>
        <inertial>
          <mass>0.1</mass>

Granted this uses the old crude approximation method that as of today an "expired epoch".

field_tesla {
  x: 0.29964852333068837
  y: -0.04052930325269713
  z: 0.353400468826294
}

[bperseghetti]

The Official WMM for that exact same location in NED and nT gives:
x: 30086.0
y: -4179.3
z: 35641.7

or if you want it in Tesla (still the NED truth data):
x: 0.0000300860
y: -0.0000041793
z: 0.0000356417

Now for Gauss (still the NED truth data):
x: 0.300860
y: -0.041793
z: 0.356417

As you can see though, our unchanged current magnetometer is actually outputting NED Gauss...

And while I'm willing to allow for declaration of "Gauss" as the default since that's a meaningful unit for a magnetometer (compared to Tesla) the NED should not be the default and is definitely a MASSIVE BUG IMO:
https://xkcd.com/1172

[bperseghetti]

I think the easy obvious one here is that since this is protobuf, if you don't change from the default, the fields don't even show up. It breaks nobody. If for some reason you really need your output in NED or some other units, then by all means change it, but then that should show in the message.

[peci1]

Hmm, what you write holds for people looking at gz topic. But that's a minority case I'd say. Tha majority case is code looking at the field. And code has to look at the field in any case. And then all subscribers need to implement the conversion routines because what if somebody decided to use nT. It seems that this is a quite high price for this little convenience.

[bperseghetti]

Not sure I follow, protobuf messages are for gazebo, not for ROS, those get converted anyhow for ROS, that conversion is trivial if we can say what frame and unit it is in. Have you ever used Ardupilot, PX4 or any POSIX rtos connected to gazebo before?

[peci1]

Hmm, now I don't know if I follow... What do these systems have in common with the topic in this PR? Do they only support float32 or something like that? And if you're using SITL/HITL, you anyways need a bridge between Gazebo and the system, which usually runs on the full-fledged system... So your PX4 can happily send Gauss and the bridge can translate to Tesla.

[bperseghetti]

I think the main thing is they take direct gz-transport messages and use gauss native internally. Anyone can convert anything anywhere... If they know what it is... I'm fine with throwing everyone under the bus and forcing it to ENU and Tesla if we are that scared/worried of enums in a single protobuf message...

I mean, people do realize that Gauss is the actual true unit of measure and that Tesla was a made up unit in 1960 to honor an "inventor" who didn't even believe in the electron let alone do ANYTHING for E&M theory or math that describes the magnetic field...

"In 1833, Carl_Friedrich_Gauss, head of the Geomagnetic Observatory in Göttingen, published a paper on measurement of the Earth's magnetic field.[12] It described a new instrument that consisted of a permanent bar magnet suspended horizontally from a gold fibre. The difference in the oscillations when the bar was magnetised and when it was demagnetised allowed Gauss to calculate an absolute value for the strength of the Earth's magnetic field.[13] The gauss, the CGS unit of magnetic flux density was named in his honour"

This is like a new measurement system coming out in 2060 for electromotive force and it gets the name "Musk" and happens to have units of 10^5 Volts.... Just so we can make sure we count all the zeros proceeding our lithium cells charge...

[scpeters]

there was a similar issue with the //joint/thread_pitch parameter in SDFormat and Gazebo classic that was weirdly defined (see gazebosim/sdformat#1125). In gazebosim/sdformat#1168 we added a new parameter screw_thread_pitch with more sane units and deprecated the previous parameter, so that it would be read properly but would print warnings when people use it.

how do you feel about changing the documentation of field_tesla to match the legacy gazebo behavior and adding another field to the message with ENU and whatever unit makes sense and then fix Gazebo to actually match that behavior?