Document / update coordinates and units

[chapulina]

As I'm going through the code, I have various questions about coordinates, units, etc. I'm planning to go over them one by one, documenting them and fixing anything in case it's not correct (hopefully it's all correct though).

• prop omega: Document propOmega, flip thruster, fix coefficient #76
• rudder angle: 8648879
• elevator angle: Elevator example, test and docs #63
• mass position: 2b07660
• buoyancy action: Document buoyancy action / VBS #65
• pitch (as defined on missions): 2b07660
• speed (as defined on missions): Document propOmega, flip thruster, fix coefficient #76

[mabelzhang]

A reminder to whoever closing the ticket:
Currently, these conventions in English are only documented in the protobuf messages, which is not an obvious place to look.

The condition for closing this ticket should be that we document this in the README, preferably in diagram form with the vehicle and rotational arrows indicating positive directions.

Another possibility is to document it in the Wiki. However, I must note that it came up in another project that GitHub does not allow search engines to crawl GitHub Wikis. That means for us a loss of discoverability (which otherwise comes for free), if we put more and more things in the Wiki. I would lean toward putting things in the repo rather than the Wiki.

The other argument against the Wiki is that putting things in the repo is more visible because PRs are required. Wiki updates does not require PRs.

A third argument is that the wiki is more disorganized because folders don't go into URLs, if the amount of content ever requires organizing in folders.

I don't have anything personal against GitHub Wikis, I'm just making everyone aware of the disadvantages of GitHub wikis that we found with NPS.

[chapulina]

As part of this issue, I started writing tests for the Thruster plugin upstream, because it was originally merged without tests in gazebosim/gz-sim#749.

Working on this branch:

gazebosim/gz-sim@ign-gazebo5...chapulina/5/thruster_test

[chapulina]

Reopening, we still need to sort out the coordinate frames

[chapulina]

What still needs fixing:

• Model faces West by default (i.e. zero orientation means West), but it should be North to satisfy NED.
  • The hardcoded model in buoyant_tethys needs to be updated: tethys_equipped face North by default #154
  • The spawning mechanism in empty_environment needs to be updated: Spawn vehicle at requested orientation #143
• Some state reported from simulation to the controller needs updates
  • pos_ should be in NED, but it's currently in ESD: tethys_equipped face North by default #154
  • rph_ should be in NED, but it's currently in END: tethys_equipped face North by default #154
  • posRPH_ should match rph_ but isn't being populated: tethys_equipped face North by default #154
  • posDot_ should be in NED, but it's currently in ESD: Update posDot state velocity to NED #155
  • rateUVW_ should be in FSK, but I'm not sure what it currently is State message: populate UVW and PQR rates #163
  • ratePQR_ should be in FSK, it isn't currently populated State message: populate UVW and PQR rates #163

What's been done so far:

• Fix coordinate frames on state message #81

  • Updates documentation
  • Adds tests
  • Initially attempted to fix frames by adding offsets when spawning the model and then when converting the data back to the controller.
  • That started to feel hard to debug and I thought the "correct" approach would be to update the model to face North and be FSK without extra offsets.
  • So I went down the road of updating the model and hit stability issues.
  • Put on hold while the model auto-generation was at work so I could build on top of that.

• Branch chapuilna/frames

  • Starting Fix coordinate frames on state message #81 from scratch on top of the model autogeneration
  • Identified one source of instability (buoyancy can't handle Z down), fix in Buoyancy: fix center of volume's reference frame gazebosim/gz-sim#1302
  • The next issue is an ODE collision checker crash after some simulation time
    • I noticed that LiftDrag and Hydrodynamics are applying forces to the order of e+38
    • Tracked it down to large angular and linear velocities to the order of e+28
    • Not sure yet which one causes the other. I suspect that just like with buoyancy, other plugins may have calculation errors that only manifest with Z-down. It could also be that I've incorrectly flipped some sign on SDF.

Given all the issues orienting the model with Z-down, I'm now considering going back to the initial approach of inserting multiple offsets within TethysComm and WorldComm.

[chapulina]

Done!