The Crazyflie firmware is the result of a lot of engineering (Making It Work) effort over a long period of time, the first commit in the GitHub repository is from 2013.
There are issues, inconsistencies and pain points in our firmware that have been found along the way, things that are difficult to fix because they have, in some sense, become load-bearing.
An examples of an issue like this is our inconsistency in what units are used in the Crazyflie firmware, we would like to use SI units everywhere but today that is not the case. And converting everything is proving to be tough.
More examples can be found in Appendix A of the paper Development of a multi-agent quadrotor research platform with distributed computational capabilities (Ian Scott Mcinerney, 2017).
We would like to fix all of these, but, the problem is that we have APIs to consider. There are programs written that assume that the data received from the Crazyflie is in a certain way. If we were to switch to the, more correct, aerospace axes these programs might break. And worse, they might break silently, meaning there will be no error message.
Our APIs constitute some kind of promise between the Crazyflie ecosystem (firmware, python library, documentation) and our users.
Examples include the parameter- and logging API which today has ideas about which way the coordinate system points and what units are used for values. As well as the Commander Framework / API, since this API has opinions regarding what way X, Y or Z grows in relation to reality.
Our APIs exists both between the Crazyflie firmware and our Python library code and between our Python library code and our users programs, as visualized in the diagram below.
If we were to implement solutions to the known issues we need to take these API into consideration. There are applications, demos, scripts and research code out there that rely on these APIs to behave a certain way.
So what can we do? What are our options? We have tried to enumerate them below.
1. Go Ahead And Change Units and Coordinates – But Do Not Update APIs
We fix as much as we can of the unit, correctness and conventions bugs in the firmware, but we leave the APIs as they are. This means that we keep the name of the parameter- and logging variables and we keep the name of all Python classes and functions. This is the less amount of work, it only needs updates to the crazyflie-firmware repository.
All examples and programs will continue to run. But they might now operate under false pretenses, perhaps with no error messages. The programs might stop working because of the implicit change of API.
We will have to communicate loud and clear that this will happen beforehand.
2. Go Ahead And Change Units and Coordinates – And Update the APIs
We fix as much as we can of the unit, correctness and conventions bugs in the firmware, and we also rework our APIs! We will gather learnings from our years with the current CRTP and Python API and we update them to be more developer ergonomic as well as update the parameter- and logging variables to be more consistent in naming and SI units.
This will require quite a bit of work, both in the crazyflie-firmware repository and possibly in the the crazyflie-lib-python repository.
A big benefit of this would be that we are then open to change where the boundaries for our API lies, what we provide as libraries and what is applications responsibility. And we can address pain points that are deep and structural to todays APIs.
This will break all existing programs out there, they will no longer run. They will get error messages and will need to be updated to the new APIs. We might also get weird issues and scenarios where old library code try to interface with newer firmware. We could create policys on for how long we maintain the old API and try to have them side-by-side for a bit.
3. Go Ahead And Change Units and Coordinates – Keep Old API Forever and Add a New One
We fix as much as we can of the unit, correctness and conventions bugs in the firmware, and we also rework our APIs! We will gather learnings from our years with the current CRTP and Python API and we update them to be more developer ergonomic as well as update the parameter- and logging variables to be more consistent in naming and SI units. And! We will also keep the old API as a legacy API.
It is unclear if this is possible, if we have enough memory in the firmware as well as enough bandwidth to maintain two APIs.
We could in theory keep all of the user-facing Python API and attempt to translate between the old and new one in Python code. This might take a lot of work and effort to do, but it might be possible.
But. Fixing all the correctness, convention and units in the firmware might make it very difficult to support both APIs. It might also limit how creative and how different a new API could be, while still being translatable to the old API.
We could also investigate if it would be possible to keep the API between the firmware and the libraries (CRTP and paramter- and logging variables) but translate to be more correct in regards to Units and Conventions in our library.
Even if this was deemed possible it would not help anyone developing directly against the firmware, without using a Bitcraze library.
4. Do Not Change Units and Coordinates – Keep Old API
Accept that the crazyflie-firmware will not reach correctness in respect to units and conventions and close the issues above. We can make sure all new features going in respect SI units and convention, but consider what we have as a legacy. This is by far the one that requires the less work. zero. But it will keep the pain points and inconsistencies of the Crazyflie platform.
Conclusions
There are trade offs between all solutions. We need to decide what our current APIs are worth to us. And how painful it would be for our users to handle an API break.
Maintaining multiple APIs might be to big of an burden for both us and our code base though. This is very very tricky.
It would help us a lot to hear from our users!
If you are someone who develops or have developed against the Crazyflie ecosystem please get in touch, we have created an GitHub issue here. Tell us if you have hit any of the pain-points described in this post or how an API break would affect you.