Add mobile robot kinematics 101 and improve steering library docs

[christophfroehlich]

This is the first step of #931, but I focused only on steering on the front axle for now. Edit: I also added the diff-drive kinematics to have a complete documentation.

After peer-reviewing of the equations I'd start to rename the variables of the library to match the doc and fix possible bugs. E.g., if I'm not wrong:

Wrong IK in case of traction on the back wheels? https://github.com/ros-controls/ros2_controllers/blob/dcd15ee6bac003aecd668943f3d4c93c1e0ee171/steering_controllers_library/src/steering_odometry.cpp#L226

Wrong odometry? https://github.com/ros-controls/ros2_controllers/blob/dcd15ee6bac003aecd668943f3d4c93c1e0ee171/steering_controllers_library/src/steering_odometry.cpp#L108-L109 https://github.com/ros-controls/ros2_controllers/blob/dcd15ee6bac003aecd668943f3d4c93c1e0ee171/steering_controllers_library/src/steering_odometry.cpp#L134-L136 https://github.com/ros-controls/ros2_controllers/blob/dcd15ee6bac003aecd668943f3d4c93c1e0ee171/steering_controllers_library/src/steering_odometry.cpp#L156-L157 https://github.com/ros-controls/ros2_controllers/blob/dcd15ee6bac003aecd668943f3d4c93c1e0ee171/steering_controllers_library/src/steering_odometry.cpp#L169-L171

rendered docs

[christophfroehlich]

:eyes: @aleksandrsizmailovs @roncapat @franzrammerstorfer @petkovich @ARK3r

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 47.43%. Comparing base (0b43291) to head (ba808b1). Report is 20 commits behind head on master.

:exclamation: Current head ba808b1 differs from pull request most recent head 6910604. Consider uploading reports for the commit 6910604 to get more accurate results

Additional details and impacted files

@@             Coverage Diff             @@
##           master     #954       +/-   ##
===========================================
- Coverage   71.86%   47.43%   -24.43%     
===========================================
  Files          41       41               
  Lines        3650     3862      +212     
  Branches     1794     1816       +22     
===========================================
- Hits         2623     1832      -791     
- Misses        707      769       +62     
- Partials      320     1261      +941     

Flag	Coverage Δ
unittests	47.43% <ø> (-24.43%)	:arrow_down:

Flags with carried forward coverage won't be shown. Click here to find out more.

see 39 files with indirect coverage changes

[christophfroehlich]

Ad odometry of ackermann steering: There is a not negligible error imho. (average is the equation implemented in the library, plotted for l = 1, w = 1; the equation from above gives the correct angle phi)

[roncapat]

Impressive job! I think this is very valuable. At least for now everything seems ok to me, I would maybe suggest to be more explicit in the derivation of some formulas, maybe with collapsable sections.

For example, for the unicycle: this implies at least one or two intermediate steps and to make the description more appealing to readers I may tend to add detail (so the attention of the reader is shifted from understanding the formulas to trusting them) even if sometimes it seems trivial :)

The point is... there are not so many places on the internet where you can find a clean explanation. This can become one of these 👍🏻

About the "overdetermined" odometry solution of ackermann with traction, I would start to think about a set of recommendations or methods to find the best solution. It gets even worse with 4-wheel-4-steer vehicles and becomes an hell when considering mars-like rovers (6 wheeled).

[christophfroehlich]

Impressive job! I think this is very valuable. At least for now everything seems ok to me, I would maybe suggest to be more explicit in the derivation of some formulas, maybe with collapsable sections.

For example, for the unicycle: this implies at least one or two intermediate steps and to make the description more appealing to readers I may tend to add detail (so the attention of the reader is shifted from understanding the formulas to trusting them) even if sometimes it seems trivial :)

The point is... there are not so many places on the internet where you can find a clean explanation. This can become one of these 👍🏻

Thanks! I was not sure where to start and where to end. I think about it.

About the "overdetermined" odometry solution of ackermann with traction, I would start to think about a set of recommendations or methods to find the best solution. It gets even worse with 4-wheel-4-steer vehicles and becomes an hell when considering mars-like rovers (6 wheeled).

We should at least assume, that ever actuated joint has a feedback sensor (e.g., no combination of traction joints on the rear axle but speed sensors on the front axle) -> this would get very complicated to parameterize for every combination.

But as far as I understood: the claim of this lib at the current state was bicycle, tricycle, ackermann; all with front or back steering; and with the traction axle being the other than the steering axle? (the steering+traction ackermann description is not part of this then, but part of this proposal of a "general" library https://github.com/ros-controls/ros2_controllers/issues/692#issuecomment-1749748573) This is the first real difference to the tricycle_controller for #850, which expects the steering wheel be the only traction wheel, and the two behind are just following.

[christophfroehlich]

Am I right that for a trailing steering axis (front_steering=false) one has just to use a negative value for the wheel-base l, and that's it?

[bmagyar]

@petkovich this may be interesting to you

[mergify[bot]]

This pull request is in conflict. Could you fix it @christophfroehlich?

[MCFurry]

Very nice @christophfroehlich this looks like a very good documentation page! Nice work! Looks alright to me. IMHO I would finish and merge this PR. The documentation page will then be available to the public and more sets of eyes can look at it and possibly spot errors or recommend improvements?

[christophfroehlich]

Very nice @christophfroehlich this looks like a very good documentation page! Nice work! Looks alright to me. IMHO I would finish and merge this PR. The documentation page will then be available to the public and more sets of eyes can look at it and possibly spot errors or recommend improvements?

Thanks! Would you mind adding a review in the UI? (Below "Files Changed" tab -> Review Changes). Yes, this will be published on control.ros.org.