How to Navigate through the Docs

2021-08-09 | Kimberly McGuire | Leave a comment

How to handle our documentation has been always a bit of struggle. For almost 2 years (see this blogpost and this one) we have working on improving the documentation structure, with by transferring information from the wiki, putting information closer to the code and setting up automating documentation. A few months ago, we managed to have automated logging and parameter documentation (see this blogpost).

Even though we think there is some improvement already, it can always be better! We have noticed that some of our users are a bit confused of how to go through our documentation. So in this blogpost we are discussing some navigational strategies of how you can maneuver yourself through the documentation as it is presented on bitcraze.io, which can also be found here.

Ecosystem-based navigation

So more than a year ago, we also started with a Ecosystem overview page, which are meant to take first-timers by the hand through the Crazyflie ecosystem.. This type of overview pages are starting from the three main pillars: the Crazyflie Platform, the Clients and Positioning Technology. This is a type of navigation that we mostly advise to take if you are a beginner Crazyflie user who do not know the structure of the eco system fully.

The Crazyflie platform page consist of all the important elements of the Crazyflie itself. It points to which hardware components the Crazyflie has, mainly the STM32 and NRF51 processor. It also points to the the existing expansion decks with their specifications and combination possibilities. Moreover, it refers to the family tree, which currently consist of the Bolt, Roadrunner and, of course, Crazyflie 2.X. Crazyradio and Clients overview page splits up the elements in the Crazyflie Python client & library, documentation about the Crazyradio PA, and the mobile clients development documentation for both Android and IOS. And finally, the positioning technologies overview page links to the information pages of the Lighthouse Positioning System, Loco Positioning System and the Motion capture system (also check out this blogpost).

Ecosystem-based documentation navigation tree

Repository-based navigation

For those that already have experience with the Crazyflie and its Ecosystem, the previous way of navigating through the docs might be a bit convoluted. With the Ecosystem-based navigation, it takes about 3 scrolls and clicks to reach the STM development documentation, which is a bit to much of a round way if you already know what you are looking for. We have made the repository overview page not for this purpose but we actually started using ourselves a lot within the company, as a direct pathway to the development repository per element. So this is a page that would be useful to other advanced developers as well!

So the repository overview page is split up in 4 main categories: Python-based software, C-based firmware, Other languages and bootloaders. See the navigation tree which of those repositories approximately point too. By the way, have you noticed that repository documentation has a gray header (like this one) and all the overview pages on the web have a green header (like this one)? This are meant to make you aware if you are still on a fluffy overview website page or going in the nitty gritty details of the development documentation.

Feature-based navigation ?

Still a remaining problem is that the repository documentation might not be enough to get a good overview. Where do you need to look if you are interested in ‘controllers’ or ‘state estimators’, or how to make an app-layer application? Currently all of this is within the stm32 firmware documentation, as that is the exact location of where all of this is implemented. But how to document spanning features like the CRTP, where not only the STM chip but also the NRF, Crazyradio PA and the Crazyflie python library are also involved? Or how about the loco positioning system, where the Crazyflie communicates through the LPS deck with a separate LPS node?

So perhaps a good way how to present all this information, is to do it feature-based, like ‘controllers’, ‘positioning’, ‘high level commander’, where we present a structure that points to parts of the detailed documentation within the repo-docs. With ecosystem-based, or even repository-based, navigation documentation strategy, it will take for instance 4-7 clicks to come to the specific controller page, as you can verify by looking at the bread-crumb of the header. Perhaps splitting it up based on feature instead of Ecosystem elements or programming language might be a more logical structure of the current state of the Crazyflie documentation.

Feedback

One reason why it is so difficult to do this properly, is that we have a lot of repositories based on each microprocessor of all of our products, which makes our opensource projects quite unique. It is therefore difficult to find another opensource project of which we can take inspiration from. So, let us know what you would prefer for navigating through our documentation in this poll, but we are always open to other suggestions! If you know of any example of a similar opensource software project that is doing it the right way, or have any other tips, send us an email (contact_at_bitcraze.io), contact us on social media platforms or post a comment on this blogpost!

Update 2021-12-21:

The poll is closed and this is the result! Thanks all for responding!

Forms response chart. Question title: What type of documentation navigation would you prefer on bitcraze.io. Number of responses: 9 responses.

Crazyflie logging and parameters interface

2021-05-31 | Jonas Danielsson | Leave a comment

Background

In the past couple of weeks we have been busy trying to improve the development interface of the Crazyflie. We want to make developing with and for the platform a more pleasant experience.

We have started looking at the logging- and parameter framework and how to improve it for our users. The aim of this framework is to easily be able to log data from the Crazyflie and to set variables during runtime. Your application can use them to control the behavior of the platform or to receive data about what it is currently up to. As of today, in the firmware there are 227 parameters and 467 logging variables defined.

View from the cfclient of the different logging variables one could subscribe to

These logging variables and parameters have been added to the Crazyflie firmware over the course of years. Some are critical infrastructure, needed to be able to write proper applications that interface with the platform. Some are duplicates or were added as debug years ago. Others have in some way outlived their usefulness as the firmware and functionality has moved on. The problem is that we have no way of conveying this information to our users and this is what we are trying to rectify.

An attempt of stability

We are currently reviewing all of our logging variables and parameters in an attempt to make the situation clearer for our users … and ourselves. We are adding documentation to make the purpose of each individual parameters and logging variables more clear. And we are also dividing them up into two categories: core and non-core.

If a parameter or logging variable is marked as core in the firmware that constitutes a promise that we will try very hard to not remove, rename or in any other way change the behavior of it. The idea is that this variable or parameter can be used in applications without any fear or doubt about it going away.

If a variable or parameter is non-core it does not mean that it is marked for removal. But, it could mean that we need more time to make sure that it is the proper interface for the platform. It means that it could change in some way or in some cases be removed in later firmware releases.

The reason for doing this is twofold: we want to make the Crazyflie interface clearer for our users and we want something that we feel we can maintain and keep an up-to-date documentation of.

What is the result?

We have introduced a pair of new macros to the firmware, LOG_ADD_CORE and PARAM_ADD_CORE which can be used to mark a parameter or variable as core. When using these we also mandate that there should be a Doxygen comment attached to the macro.

Below is an example from the barometer log group, showing the style of documentation expected and how to mark a logging variable as core. Parameters gets treated in the same way.

/**
 * Log group for the barometer
 */
LOG_GROUP_START(baro)

/**
 * @brief Altitude above Sea Level [m]
 */
LOG_ADD_CORE(LOG_FLOAT, asl, &sensorData.baro.asl)

/**
 * @brief Temperature [degrees Celsius]
 */
LOG_ADD(LOG_FLOAT, temp, &sensorData.baro.temperature)

/**
 * @brief Air pressure [mbar]
 */
LOG_ADD_CORE(LOG_FLOAT, pressure, &sensorData.baro.pressure)

LOG_GROUP_STOP(baro)

We have also added a script In the firmware repository: elf_sanity.py. The script will return data about parameters and logging variables that it is included in a firmware elf. This can be used to count the number of core parameters. If we point it to a newly built Crazyflie elf, after we’ve done our initial review pass of the parameters and variables, we get the result below.

$ python3 tools/build/elf_sanity.py --core cf2.elf 
101 parameters and 78 log vars in elf

To produce a list of the parameters and variables you can add the --list-params and --list-logs options to the script.

What is the next step?

Once we have finished our review of the parameters and logging variables we will explore different ways of making the documentation of them available in a clear and accessible way. And we will come up with a scheme for making changes to the set of parameters and variables. Once this is all finished you can expect an update from us.

The end goal of our efforts is making developing for the Crazyflie a smoother process, and we would love to hear from you. What is confusing? What are your pain points? Let us know! So we can do better.

Documenting the new Lighthouse Functionality

2021-04-19 | Kimberly McGuire | 2 Comments

A few weeks ago we released version 2021-03 including the python library, Cfclient and the firmware. The biggest feature of that release was that we (finally) got the lighthouse positioning system out of early access and added it as an official product to the Crazyflie eco system! Of course we are very excited about that milestone, but the work does not end there… We also need to communicate how to use it, features and where to find all this new information to you – our favourite users!

New Landing Page

First of all, we made a new landing page for only the lighthouse system (similar to bitcraze.io/start) we now also have bitcraze.io/lighthouse. This landing page is what will be printed on the Lighthouse base station box that will be available soon in our store, but is also directly accessible from the front page under ‘Product News’.

This landing page has all kinds of handy links which directs the user to the getting started tutorial, the shop page or to its place within the different positioning systems we offer/support. It is meant to give a very generic first overview of the system without being overloaded right off the bat and we hope that the information funnel will be more smooth with this landing page.

New tutorial and product pages

For getting started with the lighthouse positioning system, we heavily advise everybody to follow the new getting started tutorial page, even if you have used the lighthouse system since it’s early access days. The thing is is that the procedure of setting the system up has changed drastically. The calibration data and geometry are now stored in persistent memory on-board the Crazyflie and the lighthouse deck itself is now properly flashed. So if you are still using custom config.mk, hardcode geometry in the app layer or use get_bs_geometry.py to get the geometry… stop what you are doing and update the crazyflie firmware, install the newest Cfclient, and follow the tutorial!

We also already made some product page for the Lighthouse Swarm bundle. Currently it is still noted as coming soon but you can already sign up to get a notification when it is out, which we hope to have ready in about 1-2 month(s). The lighthouse deck was of course already available for those that can not wait and want to buy a SteamVR base station somewhere else. Just keep in mind that, even though the v1 is supported, in the future we will mostly focus on the version 2 of the base stations.

Video tutorial

Once again we have ventured into the land of videos and recorded a “Getting started with the Lighthouse positioning system” tutorial for those who prefer video over text.

Feedback

We love feedback and want to improve! Please don’t hesitate to contact us on contact@bitcraze.io if you have comments or suggestions!

New Step-by-Step Guides

2020-08-03 | Kimberly McGuire | Leave a comment

As you probably already know we have been wondering how to best handle our documentation and how to provide information to new Crazyflie starters as easy as possible, as you can read in our blogpost of two weeks ago. In the mean time, we also had a chance to think about the results of a poll we had when we discussed about new ways on how to meet our users. We had about 30 responses, but it became clear that many of you are in the need of getting some more knowledge about working with the Crazyflie. The majority voted for online tutorials, and although it might be difficult to do those during the summer holidays, we already started to make step-by-step guides of various parts of the Crazyflie Eco-system.

Python Library Tutorials

Currently we have started with step-by-step tutorials of the CFLIB (the python library of the crazyflie). Usually we refer to the example pages of the CFLIB, however we feel that many users copy paste parts of these scripts for their own purposes, without understanding what is actually going on. Therefore, in order to move Crazyflie beginners to the starting developer phase, we have made these guides in order to teach exactly what is going on in each module, step-by-step.

These tutorials can be found in the python library documentation. The first tutorial focuses on connecting, logging and parameters, which guides you through the process of connecting the Crazyflie through a python script, starting up logging configurations in two ways (asynchronous and synchronous) and how to read and set parameters.

The second tutorial is about the motion commander and is a logical continuation of the first. A nice thing is that we also show how to build in some protection in your script as well. If the Flowdeck is not attached, you can check that and prevent the Crazyflie from taking off altogether if it does not detect the Flowdeck. This will be a life saver in your future endeavors, and trust me I know from experience ;). Afterwards it will go into how to take off – fly forward and go back to the initial position. The application of the end of the motion commander tutorial, is where we also use the logging functionality to get the actual estimated position of the Crazyflie. With this information, we show how to write an application that create a virtual bounding box where the Crazyflie can bounce around in (like the old windows screensaver).

The results of the motion commander step by step guide.

We are planning to finish this step-by-step guide by adding the multi-ranger to the mix, continuing on the bouncing ball example. After that we will probably start some tutorials on how to use the swarming functionality before moving on to the firmware or the client.

Work in Progress

The tutorials are still work in progress. So let us know on the forum, python library github repository or as a comment on this blogpost if you see anything wrong or if something is not very clear. This will improve the quality further so that other users can benefit as well. Also once the these step-by-step tutorials are finished we can start working on video based tutorials as well.

Remember, it is possible to contribute your own fixes (or tutorials) to our repositories if you want to. It’s an open source project after all ;)

Dilemma of Documentation

2020-07-20 | Kimberly McGuire | 4 Comments

It is apparently a recurrent theme within Bitcraze:New people come into the office, claim that the documentation is a bit of a mess, then will make it their personal mission on the company to try to fix it (because ‘how hard can it be?’) and come close to a mini depression when it turns out that it ain’t so easy at all.

And yes, I absolutely fell in into that trap too. During my PhD I did not really work on documentation like this (with the exception of papers) so I made quite ambitious plans last year as you can read in this blogpost. We managed to already cross a couple of things off: we moved wiki pages to the github and host it on our website and created datasheets for products, which should make it possible to close the wiki product pages.

However, we still haven not managed to completely close off the wiki because some pages can not really be split up or might have information on there that might not be very future proof. But there are definitely many matters to improve, so we are just writing some of our thoughts down.

Beginner – ? – Developer

One of the things that we noticed that is missing, also by comments of you guys on the forum or by mail, are the means to bring the crazyflie starters quickly to the developer phase. There are some tutorials to be found on our website, but the general feeling is that it does not elevate the general understanding of how everything works. Even the tutorials that cover the autonomous flight with a flowdeck does not go further than giving install instructions and handing over the full python script while not explaining which element does what.

Of course, there are already user manuals to be found in the github docs, however those are maybe too big of a step and take much for granted that the reader knows every ‘in between’ step. It would be much better, for any level, to have step-by-step guides on how to set thing up and what each element’s role is in the code. That would probably work much more effectively as a start for beginning developers.

So we had some tutorials in mind that can elevate first starters to come closer to the developer page:

CFCLIENT: How to working with the logging / parameter framework and the plotting tab
CFCLIENT: How to interpret the debug console output
CFLIB: How to connect to the Crazyflie and read out logs and parameters
CFLIB: How to send set points and the commander framework
CFLIB: How to build up the Multiranger push demo step by step
CF FIRMWARE: How to work with the Applayer (adding own modules or code)

If there are more tutorials that you would like to see, please let us know!

Doc closer to the code

The consensus here in general, is that we would like to have the documentation as close as possible to the doc. At least we have taken a step into the right direction by importing the docs into the Github Repos. This means that with every new feature added, the person responsible can add documentation to it directly in the same commit/pull request.

However, if the description is part of function’s or classes doc strings, it is as close as it can get! The contributor does not need to change the separate markdown file but can change the information directly. Moreover, it can also auto generate documentation for us, as you can see here from one of our try-outs with sphinx and our crazyflie-lib-python repo:

Part of the class and module overview of CFLIB with some auto doc of the high level commander.

Maybe for a beginner such documentation would not be great as a start, but for a more trained developer this could be very useful. My personal problem with most automatic generated documentation is that I find them difficult to read and find the functions that I need. However it would be possible to change the layout to make it a bit more readable since we will host it on our website. And since we mostly use C and Python in our repos, the most logical tools would be Doxygen and Sphinx. There are probably other possibilities out there, but if we would like to integrate this in our framework, we would like to go with tools that are future proof.

The whole picture

The problem with Autodoc is that it mostly shows the itty-bitty-gritty details of a library or firmware, however the users tend to get lost and can not see the whole picture. Also we are maintaining a lot of libraries and firmwares to consider (as you can see here in this list) based on which hardware they are applied for. This means that we have separate documentation pages on almost all of those.

And then comes the decision of where to place information. For instance, the CRTP (Crazy RealTime Protocol) is documented in the crazyflie firmware documentation, since there it is indeed how it is implemented, but CRTP does not only affect the crazyflie firmware. It goes from the STM32F4 to the NRF to the crazyradio through the USB on your computer through the cflib which is the backbone of the CFclient. This is an topic that users would like to have to an overview from if they would like to develop something with the CRTP.

Step-by-step guides are maybe still too detailed to explain the whole picture so maybe we should have some other way to have this overview shown. Maybe by an online lecture or a more lesson type of medium?

There is a lot of sources out there (like write the doc) that have tips on how to maintain the information sources for users, but of course we need to have a documentation structure that is useful and readable for many types of users and maintainable from our side. Let us know if you want to share any insight from your own experiences!

Improving Documentation

2019-07-22 | Kimberly McGuire | Leave a comment

Our usual blog posts usually consists of the awesome new products and demos that we make here at Bitcraze, but now we will talk about… documentation! Alright alright, it is maybe not the most thrilling topic, however you should be excited about it! Good documentation about the Crazyflie and its tools will not only enable you to recreate the demos and the work of others, but also to implement your own ideas and to contribute to our open-source firmware.

In the years that Bitcraze has been around, there has been quite the build-up of information, which can be either found on the main website, the wiki, the github repositories, and in bits & pieces on the forum. Although we try to provide all the information necessary for getting started with development, it is currently quite a clutter. If we at Bitcraze already have difficulty of finding and maintaining all the documentation, we can only imagine how difficult it would be for a starting developer. We therefore would like to improve the flow of information dramatically!

Here are some ideas of what we would like to do with the documentation:

Moving product information to the shop.

LED ring expansion deck in the main website, shop, and wiki.

Currently there are three different locations where you can find information about physical Crazyflie, localization systems or expansion decks, which is the main website, the online store and the wiki. We see that a lot of electronic and hardware shops usually put all the details of the product directly on the product page of their shops. We aim to do that as well, since there will only be one page for users to go to for schematics, specifications, instructions and more, and for us it will be also easier to maintain and update any product information

Moving Software Info to GitHub

There is a lot of bits and pieces of information to handle the firmware on the Crazyflie and all the tools in the tutorials on our main website, wiki and Github repository. This again makes a lot of duplicate information, which is difficult for us to maintain and therefore gets easily outdated. We could put all the information on the wiki, but what if somebody changes something in the code which requires a change in the procedure as well?

It would be the best to keep all the information about the firmware as close to the source as possible, therefore we think is best to move everything to the github repositories. For instance, the wiki cfclient instructions can be moved to the documentation of the cfclient repostitory, or Onchip debugging instructions can go to crazyflie firmware repostitory To keep it all manageable we will:

Create a /doc folder on the repositories to better structure all the information
Add more Doxygen comments to all the function in the the codes and automatically generate documentation for this.

Restructuring the Wiki Content

After moving all the hardware- related content to the shop, and moving all the firmwar- related info to the Github repositories, we will need to think about what we want to do with the Wiki! You would think that there is nothing left to put on the wiki anymore after the replacement of the earlier documentation, but we beg to differ! For instance, there is so many Github repositories that there is a really a need for an overview. The wiki can educate developers on which tools we have an how to properly use them. Of course, we already have the getting started tutorials, but we want to also provide a more in-depth explanation of the overall structure and how the different repositories would need tho work together, like this .

This does mean that we would need to restructure the wiki entirely and only focusing on topics like:

System Architecture Crazyflie
Communication protocol between STM and the NRF
Communication protocol between the Python library and the Client
Overview Github-repositories
Projects and hacks
etc etc

What do you think?!

Of course we can change all we want in the documentation, but you guys are the ones who actually use it! We are very curious of what what you think of the plans and give us more tips or suggestions on how to improve the overall documentation experience. Please leave a message below or express your opinion on this forum thread.