I, along with @frizensami and @disgruntled-patzer, am from Yonah and we are in the midst of building a quad-plane based cargo drone infrastructure to help our hospital partner deliver vaccines. Its been a wild ride and many things have happened since we started the journey back in Jan 2017 - going from a tandem helicopter design to now a quadplane (since Sep 17); We have now gone through 3 iterations of quadplane and is now on our 3rd big boy quadplane.
Our journey led us to want to understand what’s going on under the hood in Arduplane. As we chugged along, because there was a lack in code documentation in a way that newbies can learn easily, my team (mostly @frizensami and @disgruntled-patzer) traced the code function by function and came up with a bunch of block diagrams to try and understand just how Arduplane-QP works and flows.
Having been blessed much by various open source projects in the past - Arduino, Reprap, ROS, OpenCV - I’ve always only been taking and its always been on my mind to give back when I can - projects sometimes move so fast that most times I don’t have time to. I hope that in sharing these diagrams, it’ll help someone out there learn Ardupilot, at the code level, better and faster. I also hope it’ll help to draw some help from the more experienced ones in this community if we have made any mistakes.
A few things to note regarding these diagrams:
It is still ongoing; i don’t think we have captured all the mistakes.
it is based on Arduplane 3.8.4
Because there are so many routes and cases in the code that one could trace, we set for ourselves the context of a “typical AUTO quadplane flight” when we trace.
We define governing functions to be the few key functions that has the most active influence on flight behavior (that closes the loop from mission file to servo) of a typical AUTO flight of a quadplane. Right now, we have identified and diagrammed out 4 functions in the scheduler list: navgiation.cpp, update_flight_mode.cpp, stabilize.cpp and set_servos.cpp
We understood the scheduler with an analogy “video game player queue analogy”; If there’s demand from the community, we’ll be happy to expound. Understanding how the scheduler works is key to understanding how AP works.
This is kinda another view of AP’s architecture. We needed an accurate imagery to relate to and hold everything together as we trace and understand how the cogs accurately move at the highest level.
When we finished tracing this, it became clear that a lot of the “copter” part of a quadplane angle and rate are calculated here, how differently yaw and throttle is treated and how update_flight_mode “connects” with navigation, L1 and the TECS
I wonder if there is a code documentation / UML generation tool that can be tied into GitHub and produced on each iteration.
Something like SciTools Understand but compatible with CI
While it’d be “very ugly” at first, many of these tools can provide clarity into how the code functions that even the most knowledgable of the developers couldnt’ even visualize.
This block diagram is awesome though @TianChang_Yonah. One of the things that tends to be lost with Agile/Scrum/etc type paradigms is adequate code documentation. I’m use to seeing block diagrams like this because I work military programs…but in the general world, adequate documentation is normally non-existent. Probably, mostly, because many companies buld a product to ship out the door and never see again. I think now that MOST devleopment has gone “Agile” more tools for accurately autogenerating this documentation is needed.
As much as I trust @TianChang_Yonah’s hard work, it’d be nice if the ArduPilot geniouses out there could validate that it is in fact accurate, at least as far as they understand it.
Actually, it might be more accurate as far as they understand it since Chang (and team) actually went through the process of mapping it out.
I played a more big picture “project manager”, “fresh eyes” roles and enforcing preso discipline across the diagrams to help contextualize & guide the process; There were so many rabbit trails that we could have chased in the code that it can get a bit confusing as to which trail we should pursue.
Just to add on, the ArduPilot codebase is very well commented (with a few exceptions here and there) so that made our life much easier when tracing. Kudos to the developers for the great work
@TianChang_Yonah These diagrams look quite useful to me; thanks for posting them.
One issue I’ve noticed: The set_servos chart refers to G:Lower level servo motor code, but I don’t see it above.
Unfortunately, I won’t be able to comment on that. Ardupilot’s code base do not always change drastically. If you do a diff between the versions, I’m sure the architecture, at least, would be very similar. If so, then these diagrams would still be of some use.
