Blog

I know a lot of you will be too distracted by chocolate to read this post, so I will make it short.

I am, too, a little distracted by sugar

As I mentioned earlier, we’re a little under-staffed right now. Jonas left us for new adventures, and Arnaud is enjoying some time with his baby (here in Sweden parental leave is thankfully long for dads too). On top of that, Kimberly was away the last two weeks to visit various labs in Europe. She will talk to you about it once she’s back, I’m sure. But with just 4 people at the office, time is a valuable resource. So what are we doing with it?

Well, a lot of that has been dedicated to the AI deck, but that’s not the only thing we’ve been working on. Recently, we had the visit of one expert on dangerous goods shipment. During 2 days, we got to learn about how to properly send the batteries we have, the regulations that are involved and what we have to implement to ship them. It may sound boring… and honestly, it was not the most interesting. But we got a certification out of it, that now allows us to ship as many batteries as we want with your order ! The 2 batteries only restriction that we have on the shop should be lifted – but please be aware that if you exceed 2 batteries per Crazyflie, the shipping cost will be higher, because of the fee Fedex imposes on dangerous goods shipments.

And speaking of Fedex, there are some problems right now on their air routes. Avoiding Ukraine and dealing with some strikes for air traffic operators in Europe has not been easy on their infrastructure, and we have experienced some delays in deliveries unfortunately. It seems to go back to normal gradually, so let’s hope their usual speediness resumes soon.

We’re also working on the Mini BAMs, which is on the 18th of May and will talk about drones for aerial show. Our special guest speakers are from Collmot and Flapper Drones, make sure to answer this survey if you want to participate ! You will get more informations soon.

And if want to play around with the AI deck, you will have an interesting occasion in September. IMAV launched a competition, where the goal is to have the Crazyflie equipped with the AI deck perform vision-based obstacle avoidance at increasing speeds. Deadline for registering are Mid-May, you can find more informations here.

We are now enjoying a long Easter week-end, recharging our batteries with families (and chocolate!), hoping that the Swedish spring finally settles here. I hope you’re enjoying it too !

A lot has happened at Bitcraze over the last months, which left us quite short-staffed. Thankfully, Victor has joined us again for a while. He mainly works on finishing his thesis with us, and we all agree that having an extra person at the office feels nice – especially considering the exciting stuff he’s working on! But let’s hear it from him first:

“Hi! I’m Victor, 26 years old, and studying towards a bachelor’s degree in Computer Science and Computer Engineering at LTH. I worked at Bitcraze during the summers of 2019 and 2020 and I’m now doing my bachelor’s thesis here.
During this thesis I will make a prototype deck that combines multiple ToF solid state lidar’s (more specifically, the new VL53L5CX). While there exists the Multi-ranger deck today, this new sensor outputs a matrix of distances, which opens up new possibilities that the Multi-ranger can not. Onboard the deck, there will also be an ESP32-S3, which will collect the data from the sensors and then send it to the PC, either through the Crazyflie, or through WiFi. This is all super exciting stuff and has endless potential, so let’s see how far I will get!”

Meet Victor!

I’m sure you will hear more on his progress in the next months, so make sure to keep updated!

Stock issues

We’ve been dealing with the component shortage as good as we can, but production is still unpredictable. Sadly, it means the impact on our stock is too. . The AI deck, the Bolt and the battery chargers are unfortunately out of stock right now. We had to change slightly the Swarm bundles to adjust to the lack of chargers. We’re also low on Multi Rangers, which are expected to run out of stock next week.

All those products are expected back by mid-May, if luck is on our side. It depends on our manufacturer in China, where there is sadly a new Corona outbreak, so it’s not easy to say for sure if this estimation is accurate. We hope that production and delivery stay unimpacted. Just know that we are working on getting everything back on stock as soon as possible. If you want to stay updated on the status of one of our out-of-stock product, you can choose to be informed by mail in our webshop. Just go to the product’s page, and put your email there: you’ll be the first one to know when it’s back in stock !

You surely remember that last fall, to celebrate our 10 year anniversary, we organized a 3 days online conference on our own. We actually loved it, and you seemed to like it to. So we’ve been contemplating the possibility of having another, on a smaller format.

And after some thoughts, we are glad to announce the Mini BAMs! As the name implies, they are shorter (maximum 3 hours if the discussions get lively), with a simplified platform (to be determined yet), but still with interesting talks, and a lot to discover from speakers and the community. Each Mini BAM will be dedicated to a specific subject, with one or two guest speakers, followed by discussions.

We already have a session programmed, so let’s see what we have in store for our very first Mini BAM!

When? The 18th of May, in the afternoon (CEST)(the exact time will be determined shortly)

What ? Our focus this time is shows in the sky! You surely couldn’t have missed that drones are getting more and more involved in shows and productions. But while aerial entertainment is getting popular, its implementation is not easy. At Bitcraze, we try to accompany artists to help them create a unique experience, but it’s not our main area of expertise. that’s why we’re turning to 2 close partners for those shows in the sky. Which lead me to….

Who ? We will have two distinguished speakers with us this afternoon.

Gábor Vásárhelyi was born in Budapest, Hungary, in 1979. He received his MSc in engineering-physics from the Technical University of Budapest, Hungary, in 2003, and his PhD in technical sciences (info-bionics) from Péter Pázmány Catholic University, Hungary, in 2007. Since 2009 he is with Eötvös University, Department of Biological Physics as leader of the Robotic Lab at Tamas Vicsek’s Research Group on collective motion. Since 2015, he is the CEO of CollMot Robotics Ltd., a spinoff dedicated to multi-drone services. His research fields are connected to the collective motion and collective behavior of animals and robots (drones). He received many awards, for exemple: Junior Prima Award, category of informatics (2007), Magyary Postdoctoral Grant (2013), Bolyai János Research Scholarship (2015), ELTE Innovative Researcher Award (2021).

You may recognize Gabor as the author of this post. For this Mini BAM, he will present us with Skybrush, his very clean platform for any kind of swarm/fleet/multi-UAV mission control.

We will also be joined by Matěj Karásek.

Matěj Karásek studied mechanical engineering and holds a PhD in engineering sciences. He spent 10 years in the academia (ULB Brussels, TU Delft) researching animal flight and developing bioinspired flying robots. He is a founder of Flapper Drones, a startup company developing bird-like robots for research and entertainment applications. 

Matej will talk to us about his Bolt-based drone, that is set up with flapping wings!

You will have time to ask them questions, and be sure to stay afterwards for discussions about show drones, the Bolt, and Skybrush!

If you’re interested in joining, follow this link to pre-register:

https://forms.gle/spDpKqhrus7WrHYJ8

More informations will of course come soon, stay updated!

Batteries in the shop

And now, for something completely different: you may have noticed that it’s difficult to order batteries with us these past weeks. That’s due to a change in transport regulation for Lithium batteries. Thankfully, we got a certification last week that allows us to ship batteries without the limitations that we had to put in the shop. We’re working on getting everything up to par with the new regulations, and shipping only batteries should soon be possible. Finally, the Swarm bundles will be, for a short time, sold without any chargers as we’re out of stock for those. The prices have been regulated accordingly.

There is a new fresh release of both the firmware and the python library and client! The last release (2022.01) was from 2 months ago but we already added quite some extra functionality so we wanted to make a snapshot of this before continuing on other priorities.

Kbuild on CF firmware

One of the biggest changes that you will notice, is that there is now a new way to configure your Crazyflie firmware before building it. The old config.mk is gone and you will now need to either automatically generate a config file or generate one with the menuconfig, of which kbuild is most known for. For more information, please read the blogpost about this latest change, for the exception that we do prefer the users to use ‘make cf2_config’ as instructed in the 2022.03 version of the repo documentation.

Platform support for Bolt

We now defined the Bolt as a different platform. That means that for each release, there should now also be a bolt flavor zip file, next to the cf2 and tag zips, as you can see in the release page. Moreover, if you want to build the firmware to be Bolt compatible, you would first need to do ‘make bolt_defconfig’ to generate the needed configs with kbuild. For more information of how to add your own custom platform, please check out these instructions.

2+ Lighthouse base stations (experimental)

For those that feel constrained by the max 2 lighthouse base station support in the firmware and client, this functionality is now part of the release. This blogpost will explain more about this, and it is still experimental in nature, as you would need to reconfigure the firmware with… you guessed it: Kbuild! Also the geometry estimation needs to be done as a separate python script as well all from the Crazyflie python library. No worries, if you still prefer using the cfclient, it still uses the old way of estimating if you click the button, but just remember that you would need to do something extra in order to get 2+ base station support.

New VM release

We were also made aware of a pretty big error in the bitcraze VM, namely that we still used the old git:// type url for github repositories. IN the new release of the bitcraze VM this should be fixed, so please download the new one, or fix it yourself in your current VM by changing the remote URLs of the github repos you are working on to https://.

There has been some background work going on related to the Lighthouse system, as mentioned in a previous blogpost. The solution has been improved since that blog post and we believe the functionality is now on a level where it works pretty well and can add value to most Lighthouse users.

How to use it?

We have added a brief documentation to get you started. Though the solution has been stabilized, it is still a bit experimental and it has not been fully integrated into the client yet. The base station geometry estimator still has to be run as a python script from the command line, and a reconfigured version of the Crazyflie firmware has to be built and flashed.

We have added some improvements to the client thought to enable it to display base station status for 2+ base stations. This was the final part of the client UI that did not support 2+ base stations, and now remains only the possibility to run the new geometry estimation from the client.

Benefits

What kind of improvements does it bring?

First of all, the functionality to use more than 2 base stations and the possibility to cover a larger flight space. It also makes it possible to set up multi-room systems to support flight from one room to another.

Secondly an improved estimation of the base station geometry (also when using 2 base stations) that generally reduces the errors and improves the position estimation of the Crazyflie when flying. “Jumping” of the estimated position when one base station is occluded should be reduced. When following a trajectory that is straight line through space, the Crazyflie should now actually fly on a fairly straight line, previously the flown path might be a bit curved.

The new solution has a better match to the physical world and hopefully the estimated Z will be closer to zero when the Crazyflie is on the floor, with the “old” method, the solution sometimes is slightly tilted with a Z != 0 in some areas.

Problems

Most of the Lighthouse system works just like before, the new functionality is related to base station geometry estimation. The “standard” geometry estimation is still available in the client and if you continue to use this nothing is changed, the following list is for the new estimation method.

  • The new geometry estimation is a bit clunky to use and the user still has to rebuild the firmware and run a python script.
  • Lighthouse 1 is not fully supported
  • The new geometry estimation does not work with one base station.

We hope to address the above problems in future releases.

Release

Talking about releases, we are working on a new official release. If no unforeseen obstacles are found, we plan to make a new release within a week or two.

The functionality discussed in this blog post is still only in source code, on master or possibly in some pull requests. If you wait for the release all repositories should be syncronized and make it a bit easier to try out.

Feedback

As the environment of the system has an impact on this type of functionality, we would love to get feedback from you if you try it out. We’d love to hear how it works for you!

In December we had a blogpost where we gave an overview of existing simulation models that were out there. In the mean time, I have done some work during my Fun Fridays to get this to work even further. Currently I moved the efforts from my personal Github repo to the Bitcraze organization github called crazyflie-simulation. It is all still very much work in progress but in this blogpost I will explain the content of the repository and what these elements can already do.

Low Poly CAD model

The first thing that you will need to have for any simulation, is a 3D model of the Crazyflie. There is of course already great models available from the CrazyS project, the sim_cf project and the multi_uav_simulator, which are completely fine to use as well. But since we have direct access to the exact geometries of the real crazyflie itself, I wanted to see if I could abstract the shapes myself. And also I would like to improve my Blender skills, so this seemed to be a nice project to work with! Moreover, it might be handy to have a central place if anybody is looking for a 3D simulation model of the Crazyflie.

For simulations with only one or a few Crazyflie, the higher resolution models from the other repository are absolutely sufficient, especially if you are not using a very complicated physics geometry model (because that is where most of the computation is). But if you would like to simulate very big swarms, then the polygon count will have more influences on the speed of the simulation. So I managed to make it to 1970 vertices with the below Crazyflie model, which is not too bad! I am sure that we can make it even with lesser polygons but this is perhaps a good place to start out with for now.

In the crazyflie-simulation, you can find the Blender, stl files and collada files under the folder ‘meshes’.

Webots model

We implemented the above model in a Webots simulator, which was much easier to implement than I thought! The tutorials they provide are great so I was able to get the model flying within a day or two. By combining the propeller node and rotational motor, and adjusting the thrust and drag coefficient to be a bit more ‘Crazyflie like’, it was able to take off. It would be nice to perhaps base these coefficients on the system identification of the Crazyflie, like what was done for this bachelor thesis, but for now our goal is just to make it fly!

The webots model can found in the same simulation repository under /webots/. You can try out the model by

webots webots/world/crazyfly_world.wbt

It would then be possible to control the pitch and roll with the arrow keys of your keyboard while it is maintaining a current height of 1 meter. This is current state of the code as of commit 79640a.

Ignition Gazebo model

Ignition will be the replacement for Gazebo Classic, which is already a well known simulator for many of you. Writing controllers and plugins is slightly more challenging as it is only in C++ but it is such a landmark in the world of simulation, it only makes sense that we will try to make a Gazebo model of the Crazyflie as well! In the previous blogpost I mentioned that I already experimented a bit with Ignition Gazebo, as it has the nice multicopter motor model plugin standard within the framework now. Then I tried to make it controllable with the intergrated multicopter velocity control plugin but I wasn’t super successful, probably because I didn’t have the right coefficients and gains! I will rekindle these efforts another time, but if anybody would like to try that out, please do so!

First I made my own controller plugin for the gazebo model, which can be found in the repository in a different branch under /gazebo-ignition/. This controller plugin needs to be built first and it’s bin file added to the path IGN_GAZEBO_SYSTEM_PLUGIN_PATH, and the Crazyflie model in IGN_GAZEBO_RESOURCE_PATH , but then if you try to fly the model with the following:

 ign gazebo crazyflie_world.sdf

It will take off and hover nicely. Unfortunately, if you try out the key publisher widget with the arrow keys, you see that the Crazyflie immediately crashes. So there is still something fishy there! Please check out the issue list of the repo to check the state on that.

Controllers

So the reason why I made my own controller plugins for the above mentioned simulation models, is that I want to experiment with a way that we can separate the crazyflie firmware controllers, make a code wrapper for them, and use those controllers directly in the simulator. So this way it will become a hybrid software in the loop without having to compile the entire firmware that contains all kinds of extra things that the simulation probably does not need. We can’t do this hybrid SITL yet, but at least it would be nice to have the elements in place to make it possible.

Currently I’m only experimenting with a simple fixed height and attitude PID controller written in C, and some extra files to make it possible to make a python wrapper for those. The C-controller itself you can try out in Webots as of this commit 79640a, but hopefully we will have the python version of it working too.

What is next?

As you probably noticed, the simulation work are still very much work in process and there is still a lot enhancements to add or fix. Currently this is only done on available Fridays so the progress is not super fast unfortunately, but at least there is one model flying.

Some other elements that we would like to work on:

  • Velocity controller, so that the models are able to react on twist messages.
  • Crazyflie firmware bindings of controllers
  • Better system variables (at least so that the ign gazebo model and the webots model are more similar)
  • CFlib integration
  • Add a multiranger and/or camera.
  • and more!

I might turn a couple of these into topics that would be good for contribution, so that any community members can help out with. Please keep an eye on the issue list, and we are communicating on the Crazyswarm2 Discussion page about simulations if you want to share your thoughts on this as well.

During the last couple of months we’ve been working on getting the AI-deck out of early-access. One of the things needed for this to happen is an improved infrastructure for the AI-deck, like bootloading and how the deck fits into the rest of the eco-system. For this there’s two new repositories:

CPX (Crazyflie Packet eXchange)

With the addition of two new MCUs (ESP32 and GAP8) as well as the possibility to connect via the WiFi, we quickly run into the issue of how to communicate between the targets. Even more so since there’s no direct access between some of these (like the Crazyflie<->WiFi, Crazyflie<->GAP8, GAP8<->WiFi).

What we needed was a protocol that …

  • … could be routed though intermediaries to reach it’s destination
  • … could handle high transfer rates with large amounts of data as well as small messages
  • … could handle different memory budgets
  • … doesn’t drop data along the way if some parts of the system is loaded

We decided to design and implement a new protocol, which we’ve named CPX (Crazyflie Packet eXchange). The protocol solves the issues above by:

  • Each packet has a source and destination ID, so it can be routed to (and from) the target of the packet
  • Each link between targets can have it’s own MTU, which allows each target to optimize memory usage. In order to handle this, intermediaries are allowed to split packages along the way, so data can be transferred in smaller pieces.
  • Instead of dropping packages if targets become overloaded, congestion in created in the system, where the sender will not be able to send more data until the receiver has been able to handle it.

Currently the new protocol is used for the GAP8 bootloader, for setting up the WiFi on the ESP32 and in the WiFi streamer example. But we’re hoping to expand it in the future to include more functionality, like logging and other plumbing that could be used in user applications.

WiFi configuration changes

With CPX it’s now possible to set up the WiFi from either the Crazyflie, the GAP8 or from the ESP32 itself. For doing this from the Crazyflie we’ve added the option of configuring this using KConfig, where we’ve added the following options in the expansion decks menu for the AI-deck:

  • Do not set-up the WiFi: Should be used if another target is setting up the WiFi, like the GAP8
  • Act as an access point: This will make it possible to connect to the AI-deck as an access point
  • Connect to an access point: This will connect the AI-deck to an access point using SSID/PASSWD entered in the menuconfig

GAP 8 bootloader

To make things easier for the user we want to remove the requirement of using a JTAG dongle to program the GAP8. In order to achieve this we’ve implemented a bootloader for the GAP8 which uses CPX, which means it can be used either from the Crazyflie or over the WiFi. We still haven’t had time to implement the Crazyflie part, where this will fit nicely together with the cload and client deck firmware upgrade, but it’s currently working via the WiFi. So until the implementation is done via the Crazyflie Python library, this script can be used to bootload and start your custom GAP8 firmware. Note though, that you will first have to flash the GAP8 bootloader and set-up the WiFi.

What’s next?

We’re continuing working towards getting the AI-deck out of early access. For CPX and the GAP8 bootloader there’s still a few bugs to iron out and examples to be updated as well as improved support for building using our toolbelt.

Keeping things in stock has not been easy the last couple of years due to the general problems with availability of components. We have been mitigating this by increasing stock volumes when it has been possible, but we have also looked at redesigns of some products to be able to switch to other components. A positive side effect has been that it also enabled us to do some small changes we wanted to do for a long time.

The decks we have updated are the Lighthouse, SD-card and BigQuad decks. There are no big functionality changes so the decks have not gotten any updated version only a new board revision.

Lighthouse (Rev.D -> Rev.D1)
The outline of the PCB has changed a bit in the hope of protecting the photo-diode sensors a bit better during hard crashes.

SD-card (Rev.C -> Rev.D)
Some solder bridges were added to the bottom of the PCB to make it easier to utilize the “hidden” SPI port. This can be useful if wanting to log a lot of values to the SD-card in combination with decks using the SPI port as well, such as the Loco or Flow decks. See the datasheet for more details.

Biq-Quad (Rev.C -> Rev.C1)
The capacitor C1 was removed. This was used to filter the analog current measurement reading but also caused problem for the SPI bus on the deck port. The SPI bus turned out to be a more used functionality and therefore capacitor C1 was removed. If the analog filtering functionality is wanted, a 100nF 0603 capacitor can be soldered to C1.

From now on we ship the updated revisions if you order in our store.

Jonas is leaving Bitcraze

We are sad to announce that Jonas is leaving Bitcraze. He has been involved in a lot of Github management, setting up the Crazy Stabilization lab, and various improvements and tools within our eco-system. Although he will be missed, we are excited that he is able to start a new chapter in his live and hope the best for him in his future endeavors.

This week we merged a pretty big change in the Crazyflie firmware code repository. The change altered the way we configure and build what goes in to the drone. We now make use of the Kbuild build system.

The Kbuild build system is the build system used, foremost, by the Linux kernel, but is also used in other projects like Busybox, U-Boot and sort of Zephyr. It is mostly known from its terminal based configuration tool, menuconfig.

A view of the Expansion deck configuration in the menuconfig

Kbuild leverages Kconfig files to build up an hierarchy of configuration options to use when building the software. It allows you to setup dependencies between your configuration, allowing us to do things like only enable the Kalman filter when there is a deck driver that needs it enabled.

This new way of building the firmware replaces the old way of using config.mk to set the build defines you need. Our hope is that Kbuild will make it easier to customize the Crazyflie firmware to fit the need of your department or project.

What does this mean for you?

If you are not changing the firmware as part of your Crazyflie development this will not change anything for you. The Python library will continue to work just like before and Bitcraze will release official firmwares, just like before.

If you are in the habit of fetching and building the latest and greatest version of the Bitcraze firmware there will be some minor changes. This can be seen in our updated build documentation on the web. The biggest deal is that the firmware code needs a configuration file before building is possible. To get the default one you can go:

$ make defconfig
make[1]: Entering directory '/home/jonasdn/sandbox/kbuild-firmware/build'
  GEN     ./Makefile
scripts/kconfig/conf  --defconfig Kconfig
#
# configuration written to .config
#
make[1]: Leaving directory '/home/jonasdn/sandbox/kbuild-firmware/build'

The way to compile app-layer applications has changed a bit and you will need to adapt (sorry!) the new way of building your app-layer application can be seen in the updated documentation.

If you make heavy use of config.mk and frequently change code in the firmware there are many new possibilities for you. Check the documentation and keep reading this blog.

Making the firmware more modular

With the new build systems help we hope to make it easier to enable and disable features and sub systems in the quad copter. In the default firmware all drivers for all expansion decks are included, as well as all estimators. If you are pushing a feature or experiment that need more RAM or flash, that might be inconvenient for you.

As an experiment we can try building the current maximum-, minimum- and default configuration of the Crazyflie. We say current because the work to make the firmware more modular is ongoing.

The default configuration, the official firmware, we can obtain by invoking the special make command defconfig.

$ make defconfig

And building the maximum is done using allyesconfig this gives us configuration file with all options enabled.

$ make allyesconfig

And conversely the minimum configuration can be set using allnoconfig, which will disable all features that can be disabled.

$ make allnoconfig

The resulting firmware sizes can seen in the table below:

BuildFlashRAMCCM
defconfig232 Kb (23%)76 Kb (59%)57 Kb (89%)
allyesconfig428 Kb (42%)80 Kb (62%)57 Kb (90%)
allnoconfig139 Kb (14%)62 Kb (48%)45 Kb (71%)

This shows some of the potential of the modularization of the firmware. We hope it will make it easier for you to get your stuff to fit, without having to hack around in the code too much.

Making it easier for us to merge your contributions

The new system makes it easier include code in the firmware repository without necessary needing to include it in the official firmware. This will make it easier for us to merge controllers, estimators, algorithms, deck drivers and other stuff from you.

We can include them in our Kconfig files, allowing people to select them and build firmware using them and we can make sure they get (at least compile) tested as part of our continuous integration. So you can sleep soundly knowing your code will not suddenly break with new versions of the firmware.

Creating and distributing your own config

If you want to create your own configuration, and spread it around you can do so.

You can use:

$ make menuconfig

To create a base .config file with your special configuration. If you copy the file, or have us merge it, to the configs/ directory.

$ cp build/.config configs/waggle-drone_defconfig

Then it will be possible for other people to build your configuration by going:

$ make waggle-drone_defconfig
make[1]: Entering directory '/home/jonasdn/sandbox/kbuild-firmware/build'
  GEN     ./Makefile
#
# configuration written to .config
#
make[1]: Leaving directory '/home/jonasdn/sandbox/kbuild-firmware/build'

But it would also be possible to just add the configuration that differ with the default configuration to your config file:

$ echo CONFIG_PLATFORM_BOLT=y > configs/waggle-drone_defconfig

$ make waggle-drone_defconfig

$ grep PLATFORM build/.config
# CONFIG_PLATFORM_CF2 is not set
CONFIG_PLATFORM_BOLT=y
# CONFIG_PLATFORM_TAG is not set

Help out and test it please!

This is quite a big change and we are still shaking out bugs. Please give it a test run and report any issues you find!

If you want to help out, there is a GitHub project that contain the issues we know about, feel free to grab one and contribute your solution!

Happy hacking!

The Toolbelt has been around for a pretty long time but we have not been that good at promoting it and documentation is unfortunately a bit sparse. In this blog post we will talk a bit about the Toolbelt and how to use it.

The basic idea behind the Toolbelt is to provide an easy to access tool that helps the user to do common tasks in Bitcraze projects, without installing a lot of special tool-chains, libs or programs. The intention is also to harmonize the use in all our projects to make them as similar as possible and reduce the cognitive load when switching between repositories.

A functional view

After a standard installation (see below), the Toolbelt is available using the tb command and it is intended to be executed from the root of (almost) any Bitcraze repository file tree. You can run tools (commands) from the toolbelt with the extra spice that they run in the required environment, for instance when building the firmware the correct compiler is automatically available.

Without any arguments the Toolbelt will display a brief help. For instance if I run it in the root of the crazyflie-firmware repository I get this:

kristoffer@kristoffer-XPS-13-9310:~/code/bitcraze/crazyflie-firmware$ tb
Usage:  tb [-d] tool [arguments]
The toolbelt is used to develop, test and build Bitcraze modules. When the toolbelt is called, it will first try to find the tool in the belt, after that it will try the tools in the module if the working directory is the root of a module. Module tools are executed in the context of a docker container based on the module requirements configured in the module.json config file.

-d:  print the docker call that executes the tool

Tools in the belt:
  help, -h, --help - Help
  update - Update tool belt to latest version
  version, -V, --version - Display version of the tool belt
  ghrn - Generate release notes from github milestone
  docs - Serve docs locally

Tools in the current module:
  build
  test
  compile
  check_elf
  make
  test_python
  clean
  build-docs

We can see that there are two groups of tools; “Tools in the belt” that are available in all repositories and ” Tools in the current module”, these are tools that are specific to the current repository.

To run a tool, simply use tb and the command. To build the firmware for instance, you can use make

kristoffer@kristoffer-XPS-13-9310:~/code/bitcraze/crazyflie-firmware$ tb make
Running script tools/build/make in a container based on the bitcraze/builder docker image as uid 1000
Using default tag: latest
latest: Pulling from bitcraze/builder
Digest: sha256:bee591d94db757465b88338c69be847cdf527698f0270ea1a86a2ccaa3c9845d
Status: Image is up to date for bitcraze/builder:latest
docker.io/bitcraze/builder:latest
make: Entering directory '/module'
  CLEAN_VERSION
  CC    stm32f4xx_dma.o
  CC    stm32f4xx_exti.o
  CC    stm32f4xx_flash.o
  CC    stm32f4xx_gpio.o
...

We can see that the firmware is built but we did not have to set our environment beforehand like instructed in the build/install page. The Toolbelt handled that by providing an precompiled development environment to do the firmware-compiling for us.

I will not go through all the tools but I’d like to mention the docs command. The docs command starts a web server and renders a simplified version of the documentation for a repository (in the docs directory). It is useful when browsing or editing the documentation.

Implementation

The Toolbelt is based on Docker and it runs in container. When executing a tool, the Toolbelt starts a second container where the tool runs. This second container is called a builder and it contains all the software required to execute the tool. There are a few different builders with tool-chains that are appropriate for various languages, CPUs and so on, luckily the Toolbelt picks the correct one automatically.

The directory that the tool is executed from is mapped into the docker containers and this is how the tools access the files, for instance when compiling.

In the example above we can see that the Toolbelt is pulling the latest version of the bitcraze/builder image from docker hub to have the latest and greatest builder when running make. It will take a while to download the builder image the first time (or when it has been updated) but usually this is not necessary and usually starting a tool takes only around 1 second.

The builder images are also used by our build servers for CI and release builds, this means that building with the Toolbelt replicates the exact same environment as on our builder servers.

The tools that are specific to a repository can be found in the tools/build and tools/build-docs directories. They are usually bash or python scripts and often they can also be executed without the toolbelt if you have the appropriate software installed on your system.

The source code for the Toolbelt is available on github. You can also find the source code for the builders on github, search for “builder”

Installation

The Toolbelt is mainly designed for Linux like environments and works on MacOS and in WSL (Windows Subsystem for Linux). Some operations are slowish on Mac as file access is a bit slower from docker containers.

To run the Toolbelt you need to have Docker installed on your system, after that installation is as simple as adding an alias to your .bashrc (or similar). For instructions run:

docker run --rm -it bitcraze/toolbelt

Native installation VS Toolbelt VS Virtual machine

There are three paths for building and working with Bitcraze source code; native install, the Toolbelt and the VM (Virtual machine). They all have their pros and cons.

Native installation

All build tools installed on the machine.

Pros: fast, access to USB and Crazyradio which enables flashing of firmware, can use your standard development environment

Cons: Possible compatibility issues with other software on the system. Must maintain installation and upgrade from time to time.

Toolbelt

Pros: highly separated from the OS, automatically updated with the appropriate tools and versions

Cons: can not access USB and the Crazyradio – flashing not possible. No access to GUIs – can not run the client

VM

Pros: Everything ready in one place, also supports USB, Crazyradio and flashing. Client works. Highly separated from the OS.

Cons: A bit bulky

Conclusions

The Toolbelt is an option for users that are interested in working with the source code for the Bitcraze ecosystem, but do not want to put too much time into installing tool-chains and setting up environments. It does not solve all problems but hopefully simplifies some tasks.

Any feedback is welcome!