Improve new contributor's experience

[jpreiss]

I want to make the project easier to understand for new contributors. I think the most important thing is adding code comments, followed by adding more tutorial-type content in readthedocs for different use cases.

Code cleanup would also be good, but it will require more testing effort. Documentation/comments seems like low-hanging fruit.

This raises the question of where to put the canonical, most-detailed description of each PC->CF command. As far as I can tell, there is no single friendly place where a new contributor can learn "these are all the commands I can send to the Crazyflie". The CRTP documentation is pretty close, but it might be a little bit low-level - for example, it forces the contributor to read about the integer quantization of the full-state setpoint, which is abstracted away from almost all of the PC side.

Some options:

• crazyflie_cppcomments. crtp.h might be the most cohesive and trustworthy source of truth for the Crazyflie's radio protocol; the crazyflie.h method declarations abstract away the exact data formats.
• ROS service definition comments. I would lean away from these, since from the perspective of the Crazyflie itself and the perspective of the high-level script writer, use of ROS is an implementation detail.
• crazyflie_server method definition comments. Also seem a little too closely tied to ROS.
• pycrazyswarm wrapper method definition comments. Probably the most convenient place for Crazyswarm script writers, but maybe not discoverable for non-Crazyswarm developers.
• crazyflie-firmware code comments. Unfortunately, the radio packet definitions are spread all over the code, so this fails the "single friendly place" criterion.
• some neutral Bitcraze documentation location, like the CRTP documentation above. Big advantage: has more contributors, easier to get Bitcraze employees to contribute.

Any opinions?

[whoenig]

One major takeaway from IROS for me is the same, although in a different order: The most important thing is tutorial-style docs (similar to pyTorch for example), followed by code documentation. Most users do not want to change the Crazyswarm, but simply use it for their particular research.

Some notes:

• I don't think it makes sense to replicate docs that are handled by Bitcraze. For example, they recently started moving docs into the repos. As a result, they might also do the CRTP clean-up at some point to simplify documentation.
• Since most users seem to be high-level users, perhaps a top-down documentation approach is good: Create high-level examples; document the Python API (we already have this here: https://crazyswarm.readthedocs.io/en/latest/api.html); document the ROS API; document CPP API (doxygen I guess)

I already started working on the docs, but didn't push it yet. For the tutorials, I was thinking on using the use-cases that I presented in my IROS talk (i.e., Waypoint following, trajectory following, centralized setpoints generated at a basestation, and distributed algorithms running on-board).

The tutorial-style approach will also force us to fix some of the long-standing issues, such as the low/high-level switching logic.

[jpreiss]

Leaving CRTP to Bitcraze sounds reasonable.

I like the top-down idea. I guess for tutorials, writing them as docs will let us include images, videos, links, etc. But for the API docs, surely there is some way to make sphinx/readthedocs pull them from docstrings instead of writing everything in rst? Always good to decrease the effort needed to keep per-method docs up to date :) Plus, IDEs can consume the docstrings.

Another anticipated pain point: the controller units issue. It's really confusing.

[whoenig]

Sphinx can definitely autogenerate from Python and it can also handle doxygen for C++ code. I think back then the API was just so simple that it was much easier to hand-write the doc than setting up the automatic generation.

Agreed with the units, although that is mostly a problem for low-level development. Everything on the ROS side should be in SI units already.

[jpreiss]

After another meeting introducing our new student to Crazyswarm, I also noticed it was kind of hard to justify the existence of the ROS layer without a historical argument ;)

[whoenig]

If you just want to use the basic functionality, ROS is used to allow easy scripting (might be hard to implement otherwise). Also, for more advanced usage you get all the ROS advantages (graphical tools, re-usability of components such as high-level planners, using heterogeneous robot systems.)

[jpreiss]

Doxygen in 38500c2 and a fairly deep tutorial in 0cd2e97 but won't close this yet...

[hanzheteng]

Thanks for all of your great contributions so far. I am really happy to see the new docs. I would like to share a bit more experiences from my side.

The most important thing I would like to know/learn is the design idea behind the crazyswarm stack.

Roughly 1-2 years ago, when I started working on Crazyflie and crazyswarm stack, I was confused about how the --sim parameter and the parser works, and did not understand why the timeHelper is useful to support both simulator and real robot. Sometimes if I want to change a parameter, I have to change some related parameters somewhere else (like a chain). I had to read the code in details. Now they are all in the docs. I believe it would greatly help newcomers.

Also, we used to plan to apply our online trajectory planning algorithms on a team of Crazyflies. However, the cmdPosition and cmdVel were not supported back to that time. Therefore, I started building our own multi-robot stack directly on top of crazyflie_ros. It is the great news that we have almost everything ready now, including the single marker tracking feature, etc.

As I mentioned to Wolfgang in IROS, the last remaining and important issue for us would be the switching problem between high/low level commands, since we want to use high level commands for take-off and landing, and send cmdPosition and cmdVel in between for online planning algorithms.

Thanks again for all of your great work so far. If there is anything I can help from my side, please let me know.

[jpreiss]

@hanzheteng Thank you for the positive comments! It's good to know that this effort is helping someone.

I agree that the inability to switch from low-level commands back to high-level commands is a major issue. It is almost (entirely?) an issue with the Crazyflie firmware. I couldn't find an open issue in the firmware repo. We may implement that in a PR soon, but no exact plans yet.

If you encounter other design ideas that are confusing at first but make sense later, we welcome pull requests with comments or documentation. Sometimes we are too familiar with the system to realize that something is non-intuitive. Feel free to leave questions or TODOs for us to fill in!

[hanzheteng]

Absolutely!

[jpreiss]

New demo script in ebf8477b.

[jpreiss]

https://documentation.divio.com/

This is an interesting resource on writing good documentation. They suggest that software should have 4 kinds of documentation: Tutorials, How-to guides, Reference, and Explanation.

I think the content in our docs is pretty good, but maybe it could be organized more effectively. For example, the streaming setpoint mode tutorial is predominantly a How-to guide:

A how-to guide is an answer to a question that only a user with some experience could even formulate.

but it's mixed together with motivations of the Crazyswarm design (as mentioned by hanzheteng above), which would be Explanation.

[jpreiss]

293, #294, #295 apply some of these ideas, focusing on the setup/tutorial stage.