api

The Crazyflie parameter framework provides a way to get, set and monitor parameters in the quadcopter. Examples of a parameter include which effect the LED ring will display as well as which controller to use for flight.

The parameters have default values and up until now have been reset to those default values on each restart of the Crazyflie. This has not been seen as much of a problem (Or has it? Let us know!) since most use of the Crazyflie platform has been session based and the need for persistent parameters has been low. Our work with getting the Crazyflie Bolt out of early access has however changed this need.

The Bolt will need different values for the tuning parameters for controllers and being forced to set these on each boot would be pretty annoying. And since we want the Crazyflie Bolt and the Crazyflie 2.1 to share the same firmware, persistent parameters would come in handy.

Fortunately the Crazyflie includes an EEPROM (Electronically Erasable Programmable Read-Only Memory) which we can use to store parameter values and have them survive restarts of the quad.

So this means, with the latest branches of the firmware and the python library, you can set values of a persistent parameter, store it to EEPROM, and the parameter will keep its values across reset and even across firmware upgrades.

Persistent Parameter API

Not all parameters will be able to be persistent and stored in the EEPROM. We have added a way to declare a parameter as persistent in the firmware:

PARAM_ADD_CORE(PARAM_UINT8 | PARAM_PERSISTENT, effect, &effect)

This will allow the new API added to our python library to be used with this parameter. The API consists of three actions:

Getting the state of a persistent parameter
Storing the current value of a persistent parameter
Clearing the stored value of a persistent parameter

The state of a persistent parameter consist of three pieces of information:

Is the value stored or not
The default value of the parameter
The stored value of the parameter

Setting a value, using the regular parameter API, is not enough to store the value to the EEPROM for a persistent parameter, you need to be explicit. A special API call is needed to store the current value to memory. And to stop storing the value you need to use the clear API action.

Python API

The above choices corresponds to three methods in our Python API:

def persistent_get_state(self, complete_name, callback)
Code language: PHP (php)

Get the state of the specified persistent parameter. The state will be returned in the supplied callback. The state is represented as a named tuple with members: is_stored, default_value and stored_value. The state is None if the parameter is not persistent or if something goes wrong.

def persistent_store(self, complete_name, callback=None)Code language: PHP (php)

Store the current value of the specified persistent parameter to EEPROM. The supplied callback will be called with True as an argument on success, and with False as an argument on failure.

def persistent_clear(self, complete_name, callback=None)
Code language: PHP (php)

Clear the current value of the specified persistent parameter from EEPROM. The supplied callback will be called with True as an argument on success and with False as an argument on failure.

Example code

We have also added an example script that will showcase the functionality, it will list the state of all persisted parameters in the firmware, and will store and clear some of them. The output when run against current master is:

$ CFLIB_URI=radio://0/80/2M/E7E7E7E7E8 python3 examples/parameters/persistent_params.py 
-- All persistent parameters --
sound.effect: PersistentParamState(is_stored=False, default_value=0, stored_value=None)
ring.effect: PersistentParamState(is_stored=True, default_value=6, stored_value=2)

Set parameter ring.effect to 10

Store the new value in persistent memory
Persisted ring.effect!
The new state is:
ring.effect: PersistentParamState(is_stored=True, default_value=6, stored_value=10)

Clear the persisted parameter
Cleared ring.effect!
The new state is:
ring.effect: PersistentParamState(is_stored=False, default_value=6, stored_value=None)Code language: PHP (php)

You can count on more parameters to be marked as persistent in the near future. Hopefully this will be useful for you! Please report any issues you find!

Happy Hacking!

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.

Powerful Persistent Parameters