About New Step-by-Step Guides

Discussions about all things Bitcraze
Post Reply
christi
Beginner
Posts: 5
Joined: Mon Aug 10, 2020 6:07 am

About New Step-by-Step Guides

Post by christi »

Hello,

In response to your recent blog posts on creating new step-by-step user guides, I would like to add some suggestions. The new user guides have been very helpful, and I look forward to seeing them expand, but it would be great to have a page with a general overview of everything.

For some background, I am studying mechanical engineering in college and before starting a project using the Crazyflie 2.1 did not have much prior knowledge in robotics, aerospace, electronics or programming. It has taken me many hours to understand what the role of each software/program is and how they connect with each other by reading the Bitcraze guides, github, forums, and the blog. Specifically, I was trying to understand what the cflib and client are, what capabilities the virtual machine provides, and where different tasks should be accomplished, such as programming the drone versus developing software and firmware. I am still trying to figure out what capabilities ROS and ZMQ have and whether I can use it for the project.

The problem is, there is a lot of information out there, but it is scattered all over the place, or even in the case of Bitcraze guides, I do not know that the information is there until I search for it (specifically in the case with autonomous flight, ROS, and ZMQ). Some more specific examples: Some information included in updates about new releases in blog posts should be included in the general information for that software. On Github, it is confusing whether the instructions are for developing the software or for simply using the software. Information and products required for autonomous flights are not directly found.

I've been keeping a guide for myself and others who will join my project to save time on gathering all information. Below is some information from my guide as an example of the approximate format I would like to see for a general summary/overview of all Bitcraze/Crazyflie possibilities (pardon the informal language and grammatical/punctuation errors).
  • Python/C++: sending commands to the drone through the cflib, as well as developing the cflib or the client can be done in the language of your choice, but developing the firmware/bootloaders must be done in C.
  • Python: text editor or IDE? Text editor is enough if you want to send commands to the drone, but you’ll need an IDE to develop the cflib or the client themselves.
  • Bitcraze Virtual Machine: this is kind of like downloading a zipped folder containing all the files you need, except that instead of unzipping the folder to access the files, the folder is a mini computer/operating system that you can use the files within. The files included are: (1) all user guides, examples in Python, and firmware in C from Bitcraze and github, (2) the CF Client, (3) Eclipse set-up for programming environment in C/C++ to develop the firmware/bootloaders which are written in C/C++ (4) a web browser, so you can download things too and (5) a command prompt like any other operating system has. The operating system used is Ubuntu (from Linux). So, you can do everything besides programming in Python, which you’d need to use the cflib to send commands to the drone, but you can set up Python in the VM, although it’s recommended that you download it to your computer and use it that way.
    How to get/use it: Follow instructions on Bitcraze.
  • Crazyflie Client: this is a GUI (graphical user interface) and has nothing to do with coding. The GUI is built using the CFlib. One can do a lot of things on it like monitor the battery and connection status of the drone, see parameters of flight, see graphs of how the motion is changing, etc. The client, however, is only for manual flight mode (i.e. with a game controller, or with your keyboard if you can set that up…). You CANNOT use it for autonomous flight, which would require to code commands and execute the code to send to the drone.
    How to get it: it is included in the Bitcraze Virtual Machine; otherwise you can download it separately to your computer along with cflib, following Bitcraze instructions.
    How to use it: once you download it, it will be an application/program on your computer, like any other app such as your camera app. You can double click on it and a GUI will appear with which you can interact like with any app/program by clicking on tabs/buttons.
    How to build/develop it (AKA modify the GUI to for example create new buttons and tabs, modify the font, etc): You’d have to modify the code behind it, which you can find and find instructions for on Bitcraze and github.
  • CFlib: this is an API; it is a collection of programming classes and commands used by Crazyflie so that you do not have to write every command from scratch. The official Bitcraze cflib is using Python, but APIs with other programming languages can also be found. This is the thing you use to program the crazyflie by sending commands to it and to autonomously control it.
    How to get it: it is /not/ included in the Bitcraze Virtual Machine (VM). The VM has Eclipse with C/C++ set up, so unless you are using cflib in C/C++, you can download the Python extension for Eclipse, or download a different Python text editor or IDE.
    How to use it: for the programming language of your choice, download the text editor (IDE also works but is not necessary). Now you can write programs using the /classes/commands in the cflib (after calling cflib in the code first of course). The executed programs can send commands to the drone.
    How to develop/build it (AKA modify or add new classes and commands): You’ll need an IDE to modify the code behind it and you can follow instructions on Bitcraze/github.
  • Crazyflie/Crazyradio Firmware/bootloaders: this has to do with embedded systems. These are the programs uploaded onto the electronics on the crazyflie/crazyradio. This is what helps receive information from the computer on the Crazyflie itself, this is how crazyflie can stabilize itself, etc. All of it is written in C/C++. You can write commands and flash it to the Crazyflie to also autonomously control it (a different way from sending commands from your computer using the cflib from a text editor/IDE).
  • ROS:

  • ZMQ:



How to Program and Control The Crazyflie

Intro: Control can be manual and autonomous. Manual is when you’re telling the drone what to do as it's doing it (synchronous/live/immediate), like using joysticks on a game controller or your keyboard or an app on your phone. Autonomous is when you first write all the code/commands in a program and the drone then executes it (asynchronous control). Both can be done differently.
  • Manual Control
    The official and most developed ways promoted by Bitcraze are using an actual game controller like PX3 alongside the PC CF client, and using the mobile app. Other ways are developed by the community and usually require more work and modifications.
    • Using a physical game controller: this is in detail explained in all user guides on Bitcraze; it involves using the cf client and connecting the controller to the client along with the crazyradio. You can use the joysticks to control the take off, motion, and landing of the drone and use other useful features like data logging and parameter monitoring in the client.
    • Using the mobile app: this is also explained in Bitcraze guides and involves downloading an app to your mobile device (smart phone). Not sure if this can be used in conjunction with the client.
    • Using a simulated game controller: some people have proposed downloading a game controller simulator to your computer and connecting that to the cf client, so you can use the controller window on your computer; not well tested.
    • Using your computer keyboard: some people have created programs to avoid the simulated game controller that will allow you to use your computer keyboard; not well tested.
  • Autonomous Control
    There are two different ways the drone can be programmed to achieve autonomous control:
    • Sending commands from the computer: a program can be written using the cflib in the language of your choice and executed using the text editor/IDE. The drone must be disconnected from the cf client. This would send the commands within the program to the drone through the radio connection (crazyradio), and the drone would follow the commands.
    • Programming the commands onto the drone: the crazyflie firmware (software contained in the drone’s electronic parts), which is written in C, can be accessed and downloaded online (github) or from Eclipse in the Virtual Machine. The code can be modified to include the code for autonomous flight.
    The type of automatic control may depend not only on your preference, but also on the type of positioning system:
    • Crazyflie as is with no additional onboard and/or external sensors: the way crazyflie arrives on its own, it can only perform very basic autonomous operations such as lifting off, hovering, and landing. Great drift will prevent any other type of motion besides straight up and down. The ramp.py example is a good start for trying a lift/hover program. This can be done using either of the two auto control ways mentioned above.
    • Crazyflie with the flow STEM ranging bundle: This additional deck that is mounted on the drone provides the necessary sensors for autonomous control without any other external sensors. It costs money, but is affordable. This was used by the A Visionless Autonomous Landing paper from the Rutgers GSET group. This uses the first, sending commands from computer, method. There is a lot of documentation and instruction on this method.
    • Crazyflie plus positioning systems. There are three types: Loco provided by Bitcraze, Lighthouse provided by Bitcraze and outside vendors, and Motion Capture provided by outside vendors. All use external sensors mounted in the environment and sensors mounted on the drone. If using the lighthouse positioning system, the firmware will need to be modified, so second method is used.
    • Crazyflie plus onboard camera: not sure how this one works yet.
kimberly
Bitcraze
Posts: 1050
Joined: Fri Jul 06, 2018 11:13 am

Re: About New Step-by-Step Guides

Post by kimberly »

Hi!

Thanks a lot for your feedback! The step-by-step guides is something that we do want to expand indeed, so soon there will be a tutorial for the flowdeck and multiranger. So we want do handle the cflib first, since there aren't any proper userguides for that one. The cfclient already has this userguide that is quite extensive and most of the tutorials are tailored towards the cfclient. But we will add a step by step guide there at one point as well.

You are absolutely right, there is a lot of information out there and we are discussing on many ways how to handle this (this blogpost might be also a good read for that ;) ). However, we did make some kind of starting position with overview pages: https://www.bitcraze.io/documentation/system/ (also accessable through www.bitcraze.io/docs). Here we tried to give a bit of structure to all the documentation we have out there, especially for people who just started. This page is a page for people who already know where to go and just need a quick overview for that. However, it would be nice to know if the overview pages I shared is clear at all and if there is a reason why this can not be found by people who just start? Maybe you can share some thoughts on that as well?

Maintaining documentation is difficult so we are trying to improve it, so your feedback is very valuable! Thanks again!
christi
Beginner
Posts: 5
Joined: Mon Aug 10, 2020 6:07 am

Re: About New Step-by-Step Guides

Post by christi »

Thank you for your response! Before posting and while gathering all information, I did find and look at the links to the overview docs, tutorials, user guides, and the blog post. The website resources are easily found on the website indeed, but some crucial information for further clarification and details is only found in forums and blog posts. The "guide" I posted previously is something that would have helped out more for a total beginner in electronics, programming, and robotics.

My biggest confusion came from trying to understand how to install the cflib, start using it, and whether I should install the Virtual Machine and if I did if I had to install anything further. I later understood that the cflib has to be installed separately.

The Getting Started with the Crazyflie 2.X (https://www.bitcraze.io/documentation/t ... yflie-2-x/) only contains information on setting up the client, and not the cflib. The installation instructions for cflib, at least the most straightforward ones, are not in the cflib API guide (https://www.bitcraze.io/documentation/r ... om_source/), which are confusing for a beginner because installation is on the very bottom and it is preceded by instructions for development, but instead in the Getting Started with the STEM Drone Bundle guide (https://www.bitcraze.io/documentation/t ... ne-bundle/), which contains a very basic straightforward explanation.

The important piece of information missing from the general description of the Virtual Machine is whether the cfclient should be natively installed or installed in the VM. Through forums and blogs, I found that it is better to set up the environment to send commands to the Crazyflie using the cflib (not the client) natively because the VM might be slowing down the commands.
kimberly
Bitcraze
Posts: 1050
Joined: Fri Jul 06, 2018 11:13 am

Re: About New Step-by-Step Guides

Post by kimberly »

Ah yeah got it! We can probably rewrite this page to be closer to your guide, since the page is a bit outdated.

The virtual machine is handy in the sense that we have more control over the environment, and is handy especially for people who are using windows. But some of the getting started guides do explain how to install cflib on windows natively, and on ubuntu everything can be very easily setup. The only problem with windows is the compiling of the onboard software.

We are busy with improving the documentation. It will take time but input like yours is very appreciated! thank you!
christi
Beginner
Posts: 5
Joined: Mon Aug 10, 2020 6:07 am

Re: About New Step-by-Step Guides

Post by christi »

That makes sense and thank you! Glad to help in any way.
Post Reply