[Documentation] [TitleIndex] [WordIndex] 

API review

Proposer: Wim

Present at review:

1. Define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?

(a) Casual users of PR2 who just expect to use the nav-stack and so expect to interact only at a launch file (b) Developers who may want to add new sensors to the filtered pose

2. Are all of these APIs documented?

1.(a) is documented. However, the documentation is inconsistent with the changes made last week. robot_pose_ekf no longer supports 2D pose and 3D rotations. 1.(b) is not documented.

3. Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage)

No, the package has no tutorials.

4. If there are hardware dependencies of your Package, are these documented?

There should be no hardware dependencies and there are none.

5. Is it clear to an outside user what the roadmap is for your Package?

No, there is no roadmap outlined here. The documentation should include, at the very least, information on how to add new sensors, what parameters can be tweaked and what the expected behavior is with the tweaking, what errors can occur and why they would occur, what possible error messages can pop-up and what the resolution is for them.

6. Is it clear to an outside user what the stability is for your Package?

No, the package has already changed over the last week.

7. Are concepts introduced by your Package well illustrated?

(a) The concept of what kind of filter is being used in here should be clearly explained in documentation. (b) Since BFL supports multiple filters, it should be easy for users to choose the type of filter they would like to use.

8. Is the research related to your Package referenced properly? i.e. can users easily get to relevant papers?

I don't think this really applies to this package since Kalman filters are pretty well documented. However, I think, we should include a few pages worth of information on how exactly this filter works. In particular, there is a little bit of magic in terms of waiting for the correct sensor inputs to come in the right sequence that should be well documented.

9. Are any mathematical formulas in your Package not covered by papers properly documented?

No, but see (8) above.

CONCRETE SUGGESTIONS FOR THIS PACKAGE

(a) If we are going along the "every sensor message looks like a 3D pose with covariance" (which in my opinion is a very very bad idea), we need to change the model for inputs to this package. The input can now be a generic sensor with a name, type, topic name along with 3D pose with covariance. The parameters "vo_used" etc. should also change appropriately.

(b) Adding new sensors should be clearly documented. E.g., if someone came up with an indoor gps, how would that be incorporated? This could be done with a tutorial walking users through the process of adding a sensor, eg GPS.

(c) The library should be easier to use for developers who may want to use it for purposes other than navigation. Eg. currently the library does not fuse velocity information. It should be clearer how to do that if someone wanted to use it for that purpose. This is a more long-term goal.

Conclusion

Package status change mark change manifest)

2022-05-28 12:55