UAVCAN in PX4 sponsored by NXP

(This is not a public document. It can be seen only by those who have a direct link to it.)

The overall objective of this project is to provide fully functional and well-documented support of UAVCAN v1.0 in PX4 v1.12. The work will be carried out by Nuno with optional involvement of other parties including NXP and Auterion. The work will be coordinated by Pavel and Scott.

The major precondition that has to be satisfied is the availability of Libuavcan v1.0 – a robust implementation of UAVCAN/CAN (reads like “UAVCAN over CAN”) in C++11. The first part of the project will be focused exclusively on Libuavcan, whereas the following sprints are expected to focus on the integration effort itself. The activities described here seem to be highly relevant to the RDDRONE project because it depends on the availability of UAVCAN in PX4, which in turn is conditional on Libuavcan v1.0 being available.

This text is focused on the first part of the project. We are not certain whether the amount of resources allocated to the project so far is sufficient to complete the work outlined here. Shall we run out of funds before the work is completed, the remaining tasks will be transferred over to the next sprint.

In its current state, Libuavcan exists as a high-level description of its architecture and a few definitions of its low-side media layer API. Upon completion of the activities described in this SoW, the library will be implemented according to the description provided in its CONTRIBUTING.md. Of the activities needed to attain that goal, Nuno will focus on the following:

  • Implementation of a deterministic memory manager. This may amount to the reimplementation of O1Heap in C++11 (ca. 500 lines of code).
  • Implementation of the transmission pipeline. This is a part of the library that accepts a transfer payload (i.e., a serialized DSDL object) and serializes it into an ordered set of CAN frames written into the underlying media layer.
  • Implementation of the reception pipeline. This part is responsible for the retrieval of received CAN frame from the media layer and the update of appropriate transfer reassembly state machines.
  • Construction of the high-level OOP API.
  • Extension of the Libuavcan Validation Suite to ensure 100% on-target test coverage. Any new code must meet or exceed the same standards that Scott has established so far.
  • Preparation of the comprehensive user documentation in close collaboration with Hamish of Auterion. Lorenz has pledged his full support. The documentation will be hosted in the same repository with the source code.

One critical part that is absolutely paramount but is intentionally omitted from the list is the DSDL code generator. It is not discussed here because this part will be completed by Scott himself as part of his Nunavut code generation tool; Nuno need not get involved in that.

All of the mentioned functional blocks are obviously available in Libuavcan v0, but direct borrowing of any implementation details from there would be a mistake. As indicated in #185, the reception pipeline is misarchitected, and the transmission pipeline is built on the assumption that the prioritized transmission queue is managed by the library whereas in v1 the queue has been pushed down to the media layer.

Therefore, instead of direct borrowing from v0, it is recommended to consult with Libcanard v1, whose transmission and reception pipelines are much improved based on the experience with v0. In the context of RX/TX data management, the crucial architectural differences of Libuavcan compared to Libcanard would be as follows:

  • As indicated earlier, the library will no longer be managing the transmission queue. However, the library should provide a generic implementation of the prioritized transmission queue for reuse by the media layer if such is found desirable by the user. The queue should be built upon the O(log n) AVL tree instead of the O(n) linked list implemented in Libcanard. A compatible implementation made by Theodoros Ntakouris can be borrowed directly from v0.
  • The transfer emission and reassembly functionality should offer a higher-level object-oriented API like in v0. It should include four fundamental classes:
    • Subscriber – represents the intention of the user to receive messages from a particular subject.
    • Publisher – the inverse of the above.
    • Client – represents the intention of the user to send requests to a UAVCAN service of a particular node and receive responses.
    • Server – the inverse of the above.

Shortly after commencing the work, Nuno will familiarize himself with the following resources (this is to be considered an integral part of the work package):

The low-level coordination and short-term planning will be performed in the agile style on the go. The current activities and progress can be observed in the Libuavcan project board and in the Zubax Slack (please contact me to get access).

Nuno shall not be penalized if Scott or others in the community contribute work that he would otherwise get paid for.

Last, but not least: the name Libuavcan has been found to be unsuitable so the library is going to be renamed. Undisclosed circumstances require us to pick the new name from the following options: 1. Duncan; 2. Candiac.

Okay. But I’ve said quite the opposite in my CONTRIBUTING.md so I’ll need to update to include your guidance instead.

Agreed. Please let me know when there are dates for my needing to complete this work so I can properly prioritize it. I am about 30% complete on this task right now but have paused work to focus on other areas.

Sounds like another forum post and poll perhaps?

But seriously, I thought we wanted to get away from “CAN” so we didn’t end up with “Duncan/can”?

Please add the CONTRIBUTING.md in the project to this list.
Please add a familiarity with googletest/googlemock.

Let’s be sure to structure contracts such that Nuno is not penalized if myself or others in the community contribute work that he would otherwise get paid for.

I can’t stress this enough: we need full and relevant unit-test coverage in the form of the validation suite I started in this project. Any code Nuno writes must meet or exceed the same standards for test I’ve established so far.

Agreed.

I have updated the post.

But seriously, I thought we wanted to get away from “CAN” so we didn’t end up with “Duncan/can”?

It was my understanding that Libuavcan is not interested in supporting transports other than CAN. Hence, I opened the list of cities in Canada and started looking for those that have CAN in the name.

Oh. I somehow missed that detail. Hmm. I’m not sure I agree. I did want libuavcan to support heterogeneous redundancy.

This is interesting. I did not know that.

Do you have a design in mind? Something similar to PyUAVCAN and its RedundantTransport? We are a little bit in the blind here and we are going to need a more detailed description of what exact architecture did you have in mind. The design of Libuavcan v0 is not transport-agnostic and is unable to support heterogeneous redundancy so that would be some departure.

I’m reticent to elaborate lest we become distracted. I’m hoping we can design a transport layer for v1 that is still relevant/compatible with future additions to libuavcan to add HR. For example, one strategy is that any transport layer object that would need a different backing implementation could do so behind the same interfaces such that switching to HR would be only a configuration change that didn’t require application changes outside of initialization logic.

Surprised that both suggestions are places in Canada, but why not just go all out and use “libCanada” :slight_smile:

And if you want something without the reference to CAN, then i’d like to volunteer a city from my home province - “libCharlottetown”

1 Like

The assumption is that since the work will be in sprints, this mostly would mean any contributed work by others frees up time for Nuno to further other work items. (minus time integrating or validating the other contributions)

Yes.

Right now we need a set of specific steps to follow from you to get this finalized and let Nuno commence the work.

This is not going to work. Either we design other transports in right now, or we make the library CAN-only. How much time can you spend on it next week? Perhaps we could draft something sensible out quickly, considering that we have PyUAVCAN to copy ideas from.

@scottdixon Seeing as Nuno is going to be working on Yukon meanwhile, we should use the time to engineer multi-transport support into Libuavcan. Considering that, we should go back to the original renaming proposal and call it LibToronto. Also, I would like to do the branch swap in LibToronto, too, because after the new front page goes live, having v0 in master will be confusing to new visitors. Could you please confirm?

okay