Block Diagram For Learning

Hi there people!

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.
  • Data exchange done via global variables


  • High level over view of the “governing” functions, especially how they all “connect” tgt via the data that they dump or use.


  • Which waypoint to target next.


  • 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


  • This is where more yaw stuff and intermediate servo values are calculated.


  • this is where physical motion is done. What surprised us is that the transition behavior actually happens here.


    Enjoy!

TC

33 Likes

This is awesome.

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.

btw, i vote Contribution of the Month #bestcontribution

1 Like

That’s really good stuff, and a significant amount of work. Awesome!

1 Like

Impressive, kudos!
Would you mind if it is moved to the blog category? I think it would gain even more visibility.

Thank you. Yes sure - if it helps, we are ok for it to move to blog category.

I can tell I will be spending a lot of time studying your work. Kudos. Agree with Contribution of the Month #bestcontribution.

1 Like

Thank you for sharing this compiled information!

Moderators should add this to the official Arduplot doc wiki

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.

But yes, agreed it fits the bill for a wiki PR.

1 Like

Hi @lordneeko

To be clear:

  • @frizensami and @disgruntled-patzer were the ones in the team who did most of the tracing work.
  • 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.

TC

1 Like

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 :slight_smile:

What software did you use to do these diagrams ? :slight_smile:

Kiwa21,

We used Draw.io
TC

@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.

1 Like

these diagrams are awesome. But are they still valid for 4.1.x?

1 Like

Hello. Thank you for the response. Like many in the pandemic, Yonah’s work was severely disrupted and there is currently no active development work.

I am glad you found the diagrams useful. =)

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.