Parameter files

Parameter files

This page provides a sample parameter file for MSF with detailed description of the meaning of the parameters. In addition it gives heuristics on how to choose them where possible. A sample parameter file can be found in the repository. For an introduction on how to run MSF refer to the Setup for GPS and ROVIO page.

MSF Core Parameters

These parameters belong to the main MSF programm and not to a specific sensor and are necessary independent of the sensors in use.

• scale_init: Here a scaling factor can be defined. I found this to be (almost) always 1, i.e. no scaling.
• core/data_playback: This boolean variable should be set True if you are running the system from a ROSbag and False otherwise. Note that when using a ROSbag you need to set the ROS parameter to use simulation time to true: "roscore set /use_sim_time True". In addition you should play your ROSbag using the "--clock" option.
• core/fixed_bias: This is a boolean variable as well. When set to True the IMU bias can not be adapted online by MSF. In general setting this to False is a good idea unless you are very confident in your biases and certain they won't change during runtime.
• core IMU parameters: Theser parameters are specific to the IMU used as MSF's IMU. Note that there might be multiple IMU's but only one should be mapped to MSF's IMU intput. The 4 parameters to be set are: core/core_noise_acc, core/core_noise_accbias, core/core_noise_gyr, core/core_noise_gyrbias

MSF single sensor Parameters

These parameters belong to a single sensor of MSF. They only need to be set for sensors in use and might vary slightly depending on the sensor in use. For simplicity I will only list the parameters once, where sensortype should be replaced by the appropriate name (i.e. sensortype/init/q_ic should be replaced by pose_sensor/init/q_ic for a pose sensor. For pose and position sensor all necessary parameters are listed in the sample parameter file.

• Transformation parameters: This values define the transformation between the measurement point of the respective sensor and the drone IMU and have to be computed/estimated a priori. For pose measurement this is a 6 DOF transform and for position a 3 DOF transform. The corresponding parameters are: sensortype/init/q_ic/x, sensortype/init/q_ic/y, sensortype/init/q_ic/z, sensortype/init/q_ic/w, sensortype/init/p_ic/x, sensortype/init/p_ic/y, sensortype/init/p_ic/z
• sensortype/type_absolute_measurements: This boolean parameter defines wether the measurements of the sensor are given as absolute measurements or relative to its last measurement.
• sensortype/type_use_fixed_covariance: This boolean parameter defines wether MSF should use a fixed covariance (True) or the covariance provided by the sensor (False). This has to be set to True if the sensor does not provide a covariance measurement. (I did not test this feature so I cant argue about its performance)
• sensortype/type_measurement_world_sensor: This parameter is boolean as well. It selects if the sensor measures its position w.r.t. the world (true, e.g. Vicon, Rovio) or the position of the world coordinate system w.r.t. the sensor (false, e.g. ethzasl_ptam)

Stability features

These features are, as their name says, generally to use as a tradeoff between stability on precision. By default they are all set to False, but should be taken into consideration unless you are very certain about the behavior of your system.

• Outlier rejection: There are two parameters used for outlier rejection. The first sensortype/enable_mah_outlier_rejection is boolean and simply enables the feature when set to True. The second is sensortype/mah_threshold. It is of type double and defines the limit of accepting measurements. Generally it is a good idea to use outlier rejection unless you are really confident your sensors won't produce outliers and event then it does not significantly decrease precision. As a threshold choosing around 5 proved to work well. Recall that the mahalanobis distance depends on the covariance of the sensor and therefore does not have to be adjusted for noisier sensors as lon as the noise parameter is choosen accordingly.
• Noise Estimation: Note that this feature is only relevant if you are NOT using covariance from sensor. Noise estimation is defined using 3 parameters. The first sensortype/enable_noise_estimation again is a boolean to enable or disable the noise estimation feature. If disabled the noise parameter is kept constant at the initial value. The second parameter is sensortype/noise_estimation_discount_factor and is used to define the discount factor of the average computation: average_{i+1}=(1-alpha)d+alphaaverage_i. It has to be \elem(0,1). The final parameter is sensortype/max_noise_threshold. It is optional and can be used to define an upper limit for noise. If the "true" noise exceeds this limit MSF will no longer increase its estimate and therefore most likely reject all measurements from this sensor. Generally noise estimation proved to be useful if you are either uncertain about your noise estimate or if you expect the noise to change during operation. Given an exact initial noise, noise estimation might loose some precision. When choosing the discount factor one should think about the frequency of the sensor. The higher the frequency the closer it should be choosen to one, since otherwise noise might be adjusted too frequently. A value of 0.999 turned out to be reasonable for a frequency of 100Hz. The maximal noise threshold might help in case of diverging sensors, where otherwise the noise estimate might become extremly large an thus take a long time to recover. However for stability reasons it should be choosen rather large.
• Sensor Recovery: There are three main parameters for sensor recovery. In addition there are some more parameters related to recovery discussed under transform recovery below. The first parameter again is a boolean called sensortype/enable_divergence_recovery that enables or disables sensor recovery. The second parameter sensortype/divergence_rejection_limit defines how many measurements have to be rejected back-to-back until the sensor is regarded as diverging. The last parameter called sensortype/use_reset_to_pose defines wether the sensor should be reset to the last pose estimate(True) or completly restarted(False). This should always be choosen True if the sensor provides a method to reset to pose, since it increases accuracy. This feature should only be enabled for sensors that are not expected to recover on their own, such as ROVIO. Sensors like GPS that will eventually recover on their own do not benefit from this feature. Using it anyways would decrease precision. The rejection limit gives a tradeoff between time to reaction and precision, since in general the system will loose some accuracy when reseting one does not want to choose this parameter too small since otherwise the sensor might be reset even when it is not actually diverging. On the other hand choosing it too large will cause the system to take longer to take actions loosing in a loss of information. Choosing a threshold of ~30 proved to work well, however again one might think about the frequency of the sensor when choosing this parameter.

Sensor handler parameters

These parameters correspond to a MSF sensorhandler and not to a specific sensor. For a description of the difference please refer to its ROS wiki. Generally they should rather be choosen to large than too small. If there is no good a priori estimate the noise estimation feature should be enabled.

• Noise parameters: handlertype/sensortype_noise_meas_p and handlertype/sensortype_noise_meas_q give the initial values for noise of corresponding sensortype for translation (p) and rotation (q) as in a EKF setting.
• Transform noise: These parameters give the noise (or uncertainty) in the transformations. Each noise parameter is accompanied by a boolean that makes the transform fixed (True) or part of the state (False). For example position_pose_sensor/pose_fixed_p_ic is the boolean corresponding to position_pose_sensor/pose_noise_p_ic. For a complete list please refer to the sample parameter file. Generally one should keep internal transforms (i.e. between IMU's) fixed since they can not change during flight and can be estimated precisely a priori. On the other hand it usually makes sense to add some noise to transforms between different external frames (i.e. GPS and ROVIO) since this can change and usually is not precisely known a priori. This noise however should never be choosen larger than the noise of the sensor.
• handlertype/use_stable_initialization: This parameter defines wether the simple initialization based on a single measurement (False) or the dynamic initialization based on multiple measurements (True) should be used. When choosen False the drone has to be aligned with the GPS frame. Otherwise this should be True. If True it is important that after initialization the system follows some movement to be able to estimate a stable transform.