(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):
- Specification v1.0-alpha: https://new.uavcan.org/specification.
- PyUAVCAN reference manual because its OOP API is believed to be sensible and close to Libuavcan.
- Libuavcan v0 tutorials.
- Libcanard v1 documentation (currently this is a work in progress).
- Libuavcan v1 CONTRIBUTING.md
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.
