Module2 - proj - Project phase 1

The Crazyflie

The Crazyflie is a small Unmanned Aerial Vehicle (UAV) that poses many interesting theoretical and practical challenges with respect to control and state estimation. It is produced by the company Bitcraze Links to an external site.. This short tutorial is designed to get you acquainted with the Crazyflie by performing some minimal system identification experiments (using standard office supplies), performing some simulation and control and presenting you with the task connected to the examination of the first phase of the project.

This page is structured in the following way:

Assembling your Crazyflie - the Crazyflie comes in pieces and you need to put it together
Flashing the Crazyflie Firmware - How to flash from your computer via radio
The Crazyflie Client - A GUI for communicating with the UAV. How to log signals.
Modifying the Firmware - How to modify the UAV code
Identification Experiments - A simple control signal vs thrust experiment
Crazyflie Control - A simulation-based introduction to the full Crazyflie model with PID and LQ control.
Milestone 1 - The task to be completed to show that you have got a good enough understanding of the first part of the project.

You will need an assembled Crazyflie, see figure above (+ a micro USB cable and the USB radio dongle).

Warning: Be aware that the UAV might possibly be able to hurt you (or people in your surrounding, or pets, or stuff) if you are extremely unlucky, for instance if you get a rotor in your eye. So use some caution.

1. Assembling your Crazyflie

You will need an assembled Crazyflie. The parts you should be given are

1 Crazyflie 2.0 box
1 micro USB cable
1 USB radio dongle

The assembling of the Crazyflie will be done on the first local module 2 session. The instructions for this are available on this page Links to an external site. (you only need to do the "Testing" and "Assembling" steps. The rest will be explained below. If you are very eager, you may download a mobile app for some manual test flights. You will find it is quite hard avoiding crashing though, and we will not use the mobile app in the following.

Before you move any further, make sure that you have completed the instruction here Module2 - project - Setup and configuration

The password to the VM is "crazyflie" in lowercase letters and the username is bitcraze.

2. The Crazyflie Client (cfclient)

You should have the VM up and running (as described here Module2 - project - Setup and configuration).

Charge your Crazyflie by plugging it into the computer via the micro USB cable. Plug in the USB radio dongle and make sure that it is found in the virtual machine by clicking the USB icon in the bottom VM toolbar "Bitcraze Crazyradio PA USB Dongle [0053]", see figure.

We will attempt to communicate with it. Press the "Crazyflie client" icon on your desktop. This GUI serves many purposes, and can be used to (i) fly the Crazyflie using a joystick controller, (ii) log data, (iii) plotting, (iv) setting parameters and (v) simpler debugging of the real-time implementation through the console.

Once the GUI has been opened, power on your Crazyflie, plug in the USB radio dongle and press SCAN in the GUI. Your Crazyflie should then be found in the "Select an interface menu", as a textstring such as "radio://0/80/250K". Pressing CONNECT should now establish a connection to your Crazyflie. Note that if the Crazyflie is too close to the radio dongle in the computer, you might find oddly many Crazyflies due to radio disturbances. It suffices to move the UAV a couple of decimeters away, and do a new scan, to avoid this problem.

When a connection has been established (this might take some seconds), open the "Connect->Configure 2.0" to open the Crazyflie 2.0 config window. Here you can change the channel of the radio, allowing multiple Crazyflies to be worked on in the same room (make sure that your office neighbour is not on the same channel ). Then press "Write" for your changes to take effect. It is a good idea to change the radio bandwidth to 2 MBit/s and to choose some unique channel in the range of 80-110. Press Write and then Exit. Restart your Crazyflie for the changes to take effect (i.e. power off and on, do not start in bootloader mode).

3. Exploring the Crazyflie Client

Connect again to the Crazyflie using the GUI (Scan and Connect). Under the menu item "View->Tabs" you will find a set of useful tabs which can be added to the GUI. Add the following

Console -Messages from the Crazyflie can be printed here using the consolePrintf() function in the C-implementation. Useful for debugging.
Parameters - An interface for changing defined parameters in the C-code over the radio link, list all available parameters. The parameters are defined in the C-code using the * ADD_PARAM *macros [6] Links to an external site..
Log Blocks - This allows you to define custom log blocks defined in the C-code using the LOG_GROUP macros [7] Links to an external site..
Log TOC - This shows the currently available attributes which may be logged.
Plotter - Plots any defined log block in real-time.

(note: you should also check the Plotter alternative)

Spend some minutes exploring the new Tabs.

To get acquainted with the functionality offered by the GUI, investigate that the gyroscope works by rotating the Crazyflie and logging some data. To log data, simply open the Log Blocks Tab and check the "Write to file" boxes for the data you want to log. For example, check the Stabilizer logging with Period 20ms, log for a while, and then uncheck the box again. To view the log, go to Settings -> open config folder and go to the logdata directory (notice the path to the logdata for later use, for instance in moving results into Matlab for further analysis).

Open the plotter and use the menu bar, located inside the Plotter window and below all the Tabs, to choose the "Stabilizer" log-block, see figure below where the menu bar is shown on top.

This plots the rotational estimate in terms of the roll, pitch and yaw angles in the stabilizer Log Block (Facts for the interested expert: ZYX intrinsic Euler angles are used. The angles are estimated online using a simple non-linear estimator, called a Mahony filter, a non-linear complementary filter).

Additional information on how to configure the client can be found here [6] Links to an external site..

4. Changing the Firmware

We will now change the firmware of the crazyflie, i.e. change the program running on the micro controller on the Crazyflie to show how this works. Open a terminal and execute the following (the last command will take a while)

cd ~/projects/crazyflie-firmware
make clean && make all

The make clean && make all compiles the binaries from scratch.

Flash the firmware with (you do not need to set it into boot loader mode manually, it is taken care of automatically)

make CLOAD_CMDS="-w radio://0/109/2M/E7E7E7E7E7" cload

where you should replace 109 with the ID of your drone. Your Crazyflie should start flashing assuming the Crazyflie successfully enter bootloader mode. You can edit the Makefile on line 21 and make it look like

CLOAD_CMDS ?= -w radio://0/109/2M/E7E7E7E7E7

again assuming that your drone's id is 109. This way you can flash with only "make cload".

Later, if you only make minor updates to the code, you could simply use make all && make cload. When the Crazyflie has been flashed, it will light up, run the motors in quick succession, showing that it is ready to take off. During this process, it is important that it lies still on a flat surface.

A red light blinking at 1 Hz is the sign of life - the heartbeat - if it instead glows a steady red and flatlines the battery is discharged. If red lights flash in another (ternary) sequence, the system has hard faulted - check the console for additional details and reflash the UAV with the clean firmware.

4.1 The General Structure

The motors are controlled using a so called pulse-width modulated (PWM) duty cycle. For some background on PWM signals you can watch this video [8] Links to an external site.

The firmware is written in C and implemented in FreeRTOS with several external dependencies. The structure is rather complex at a first glance, but in the part we will only edit a single file in order to enable manual motor control.

Start by opening a terminal and cd to the ~/projects/crazyflie-firmware directory. Open your favourite text editor and enter the directory ~/projects/crazyflie-firmware/src/modules/src, a directory that contains a subset of the modules implemented in the Crazyflie. One of the more interesting ones is the file stabilizer.c, defining the main stabilizer task which is run at 1000 Hz. If you use atom, you can open it directly by typing:

atom ~/projects/crazyflie-firmware/src/modules/src/stabilizer.c

or change atom for some other editor such as leafpad which comes preinstalled.

4.2 The WASP fork of the crazyflie-firmware

We have our own fork of the crazyflie-firmware to keep track of local changes for the WASP course. You are welcome to use that directly if you want. It is not needed for what you will do on this page.

cd ~/
git clone https://github.com/pjensfelt/crazyflie-firmware.git wasp-crazyflie-firmware
cd wasp-crazyflie-firmware
git checkout gh/ls2
git submodule init
git submodule update

In what follows you would thus modify/use files in ~/wasp-crazyflie-firmware instead of ~/projects/crazyflie-firmware. The WASP fork already contains the version of the stabilizer.c file that you will use in section 5 below, i.e. you do not need to download anything extra.

5. Identifying Parameters

A common assumption when designing controllers for small UAVs is that the PWM duty cycle is roughly proportional to the generated thrust which, in turn, is proportional to the rotor speed squared (see [9] Links to an external site. for additional details relating to blade element theory). This relationship, which we will see is roughly but not exactly as described above, is central to any control algorithm, which typically computes a set of forces which are to be generated from the rotors, converting these into an appropriate PWM duty cycle subsequently written to the motors.

Up until this point, you have set up the system, logged rotational estimates and modified code so as to allow individual rotors to be set with a specific PWM duty cycle.

To change a motor signal manually, go to the tab "Parameters", scroll down to powerModeSet, where you can set the motor signals to the 4 motors. M1 to M4 corresponds to motorID 0 to 3. If you look carefully on the Crazyflie, the M1-M4 axes are marked with white text as shown in the figure below.

Change m1 to e.g. 5000. M1, should then start rotating at a moderate speed (not enough to make the Crazyflie move). You can also experiment with motors M2-M4.

5.1 - Identifying the PWM to thrust map

We will now explore the rotor dynamics using a pen (or even better, a thin metal rod), a rubber band and two coffee cups (could also be tea cups).

Attach the pen, or metal rod, to the UAV with a rubber band as shown below. We will only use the two lower motors, so notice their labels. Hang the construction in the ears of the cups such that the Crazyflie is free to dangle with low friction.

Now, set an arbitrary duty cycle to any of the lower motors, in the configuration in the above image this would be M1 or M4, and log the resulting reported pitch angle after the Crazyflie has stabilized. (you should know how to, at this point...) Knowing that the Crazyflie weighs approximately 27 g and that the center of mass is roughly halfway between the axis of rotation (the rod) and the used motor will allow us to compute the generated force (in Newton) as a function of the set PWM duty cycle (convert 0-65535 to numbers 0-1), using the logged pitch data.

Question 1: Is the relationship between motor signal (PWM) and generated force approximately linear, or are there better approximations?

Question 2: Knowing that we have four propellers and that the UAV weighs 27 grams, how much additional load do you estimate that we can possible fly with?

5.2 - Exploring the motor torques

Motor torques are used to make the UAV change yaw direction. Attach the pen to the Crazyflie along the M4 motor axis using the rubber band as shown in the figure below. Crank up the PWM signal of motor M2 (do NOT use motor M4 near the rod) from 1000 to some value close to its maximum at 65535, e.g. 60000. You do not need to log data, only observe what happens.

Question 3: What do you observe? In which direction is the UAV rotating? What happens if you turn off M2 and use M1 instead? Or M3?

Question 4: Compare what happens when you use the diagonally opposite motors, M1 and M3, simultaneously compared to when only M1 is used? Does the total yaw torque increase or decrease?

Question 5: What happens when you use two neighboring motors, such as M1 and M2, simultaneously? Does the total yaw torque increase or decrease?

By the UAV construction, where two rotors spin clockwise and two counter-clockwise, one can decouple the total generated torque (impacting yaw rate) and total generated thrust (impacting elevation change). The quad-rotor construction actually allows independent control of the pitch, yaw and roll, as well as the UAV elevation, by combining M1-M4 cleverly (can you describe how?).

Your experiments on relation between duty cycle and thrust should give results similar to the first image below. These accurate plots of the two relevant maps have been generated with a more sophisticated method, showing that the approximations are indeed reasonable (see e.g., [9] Links to an external site. for additional details relating to blade element theory), even though the first plot is not perfectly linear. You will not be able to do the second plot since the rotor speed is not measurable without extra equipment. Another issue to be slightly worried about is whether the generated thrust is actually the same when measured in a static situation like this, as to when the quadcopter is dynamically moving through air. Experience has shown the simple model described here seems good enough.

Controller simulation in Matlab/Simulink

NOTE: The following has been tested on Matlab r2017b and Simulink 9.0. (The following instructions should be expanded sometime in the future.)

To simulate the Crazyflie controller, which will be used when you study controller design, you will need access to Matlab and its Simulink toolbox on your computer.

Download the following matlab/simulink code crazyflie-controllers.zip Download crazyflie-controllers.zip

and unpack in a suitable directory where you will be able to run matlab (probably on your host computer, not in the VM).

Now that we have identified some of the parameters, we can try to design controllers for UAV flight control and it will be useful to simulate it before you try on the real process. In the provided matlab+simulink code, a total of four controllers are provided as a start - a simple PD controller, an LQ controller, an LQ controller with integral action, and additional for experts: and an interesting controller based on differential geometry. Later on during the examination tasks you will implement PD controllers for moving the UAV through (x,y,z) space. For now, the matlab models are provided as is. We will later prototype the real-time controllers using similar models!

To run the controllers, you will need a Matlab installation of version 2016a or later. Start matlab, cd to the directory where you downloaded the crazyflie-controllers matlab+simulink code and run the file init_project.m. Next, enter any of the four controller repositories, run init.m and then simulate the model by pressing the play button in simulink.

Summary of work so far

At this point, you should have

a working computer environment,
the knowledge of how to flash the Crazyflie with new code,
a basic intuition of the rotor dynamics,
an idea of which states we may control in the UAV and why,
a working dynamical model with some initial controllers.

Understanding LEDs

Power on and all is good: The blue LEDs (2 and 3) are fully lit and the front right LED (1) is blinking red twice every second.
Power on and all is good but sensors are not yet calibrated: The blue LEDs (2 and 3) are fully lit and the front right LED (1) is blinking red with 2 seconds interval. Put the Crazyflie 2.0 on a level surface and keep it absolutely still to calibrate.
Radio connected: The front left LED (4) is flickering in red and/or green.
Battery low: The front right LED (1) is fully lit in red. It’s time to land and re-charge the battery.
Charging: The back left blue LED (3) is blinking while the right back blue LED (4) is lit.
Boot loader mode: The blue LEDs (2 and 3) at the back are blinking approximately once every second.
Self test fail: The right front LED (1) is repeatedly blinking five short red pulses with a longer pause between groups.

Task: Milestone 1

As the final task for the first phase of the project you should make your Crazyflie be able to rotate on the desk to change yaw angle. You have studied above how the the rotation of the propellers influence the yaw. Your task is now to use this to make the UAV rotate a certain angle, compared to the start position. You should input the desired angle as a parameter via the Parameter tab in the Crazyflie Client.

The deliverable consists of

a video where you see both the Crazyflie rotating on the desk and the Client window where one can see the Plotter tab and how the yaw angle changes to your desired angle.
the stabilizer.c code

Upload your video and code here.

An example how such a video could look is given below

Crazyflie yaw control +-20 degs Links to an external site.