Scenario configuration (Reference guide)¶

This page is meant to guide users on how to write a scenario configuration file for the CAMS.

A scenario configuration file is the description of the agents and processes that will be used by CAMS. These include: Aircrafts, Maps, Flight zones, Navigation frame, Data views, GPR Kernels and Database options among others.

General structure of configuration files¶

Configuration files are written using YAML markup.

Quick reference:¶

• YAML is a hierarchical key-value collection
• Values can be: Strings, Lists, Floats, Integers, Booleans (primary types)
• Namespaces can be defined either as a variable, as a dictionnary if others namespaces are declared inside, or as a list using minuses ( - )
• Use references to utilize constants at multiple locations: &name_reference value to create and define the reference, *name_reference to use it

Sample configuration files can be found in the CAMS code repository of the graphical user interface.

Using the config file¶

The NEPHELAE_CONFIG environment variable must be in order to use it. There are two ways to do it :

• Setting the NEPHELAE_CONFIG environment during the current session (using the bashrc for instance, don't forget to source it).
  

  export NEPHELAE_CONFIG="/path/to/the/configuration_file.yaml"

• Executing 'make runserver' with the NEPHELAE_CONFIG as argument (like this : NEPHELAE_CONFIG=_path_file_ make runserver)

The first option is recommended if you plan to use the same file for multiple runs.

Available configuration options¶

Local Frame :¶

local_frame is defined in utm coordinates and have 4 different fields : east, north, alt, utm_zone.
- east, north and alt are floats
- utm_zone is a string

Flight area :¶

The flight_area is a single value that is a list. This list contains two other list and both of the lists containing three floats (x, y, z). These floats are the minimal (first list) and maximal (last list) boundaries of the flight area.

Database :¶

The database can be defined by defining three fields :
- enable_save, boolean. If the boolean is set to true, will write periodically the database in a file ( deprecated since 1.1.0 )
- filepath, string. This is the string representation of the path used to save the file on your machine (you should use an absolute path)
- overwrite_existing, boolean. If set to true, will rewrite the existing file (if it exists) ( deprecated since 1.1.0 )
- timer_tick ( deprecated since 1.1.0 )

Wind Map :¶

While this is a map, the wind_map is set apart from the other maps. It possesses three different fields :
- type, which is a string. It refers to the type of wind map that will be used. For now you can only choose between 'WindObserverMap' and 'WindMapConstant'. Check the python documentation for the different types of wind maps.
- name, which is a string. It is the name of the map.
Depending of the type, the third field can be different :
- wind, if the type set is WindMapConstant. In this case, the value of this field is a list of two floats, representing respectively the speed of the wind in east and north directions.
- sampleName, if the type set is WindObserverMap. In this case, the value of this field is a list of two string, representing respectively the variables that are listened by the map to fetch informations on the wind.

Data Views :¶

The data_views is a collection of data views, each defined with a unique namespace. The number of data views can change between multiple scenarios. Each data view has two mandatory fields and an optional one.
- type is a string, representing the type of the data view used. This type can only be one of the following : 'FetchView', 'StatusView', 'HumidityCalibration', 'CloudSensorProcessing', 'Scaling', 'TimeView'. Refer to the python documentation for more informations on these types.
- name is a string, it is the name of the data view
- displayable is an optional field. It is a boolean. If set to true, will appear in the charts of CAMS.
Other than that, the data view can have other fields to fill depending of the type set.

For FetchView :
- tags is a list of string, representing the tags of the data the view must search in the database.

For StatusView :
- tags is a single string, representing the id of uav to search for in the database. It can be set to null, resulting on fetching status of every uavs
- info is an optional string, that is used to fetch a specific status info. (The position in x, y, alt, time)

For HumidityCalibration :
- lt is a float, that is the threshold value
- gain_1 is a float, that is the factor of the first linear function
- offset_1 is a float, that is the offset of the first linear function
- gain_2 is a float, that is the factor of the second linear function
- offset_2 is a float, that is the offset of the second linear function
- parents is a list, that contains every parent of this view. The strings contained in the list must exists in data views keys.

For CloudSensorProcessing :
- cloud_tags is a list of string, representing the tags of the data related to the clouds that must be searched in the database
- energy_tags is a list of string, representing the tags of the data related to the uav energy (battery) that must be searched in the database
- alpha is a float that is the factor of the linear function applied
- beta is a float that is the offset of the linear function applied
- scaling is a float
- lengthMedian is an integer

For Scaling :
- alpha is a float that is the factor of the linear function applied
- beta is a float that is the offset of the linear function applied
- parents is a list, that contains every parent of this view. The strings contained in the list must exists in data views keys.

For TimeView :
- parents is a list, that contains every parent of this view. The strings contained in the list must exists in data views keys.

Aircrafts¶

The aircrafts set contains every aircraft that will fly during the scenario. The id of an aircraft is the key used in the collection.
Each aircraft can be passed in replay mode by defining the optional replay field to true.

Each aircraft has a type field that MUST be set. The values authorized are :
- pprz (usage with paparazzi)
- base (usage without any monitoring uav software)

The aircrafts have also a list of plugins that are contained inside the plugins field.
List of plugins available : MesonhProbe, Missions, CloudCenterTracker, MissionWindUpdater, Monitor, CloudSensor, MeteoStick, Energy, WindSimulation
The following plugins have additional fields that must be filled in order to use them :

For MesonhProbe :
- mesonhFiles, that is a string representation of the path of the mesonh file to read (use an absolute path)
- mesonhVariables, that are the mesonh variables fetched from the mesonh file. This is a list of string
- rctFeedback, that is a boolean.
- mesonhOrigin, that is a list of 4 floats, representing the starting point of the mesonh dataset [t, x, y, z]. If a value is negative, it means that the last index of the database minus this value will be set as the origin. For example: [0.0, 1000.0, 0.0, 0.0] shifts the values of MesoNH map 1km to the west.
fixTime, that is a number. Ignores always the time sent by the requests and returns only the state of the dataset for this value. (for more coherence, use the mesonh_fixed_time field as reference)

For Missions :
- backup_file, that is a string representation of the path of the file that will save and be loaded at the start of the simulation, and containing all informations on the missions for this uav
There are optional fields to add, each representing a different mission. There are four possible at the moment : Lace, Spiral3D, Rosette, Trinity

For CloudCenterTracker :
- mapWhereCenterIs, that is a string. This string must be one of the key used to define a map (see Maps definition part below)

For MissionWindUpdater :
- period, float.

For WindSimulation :
- mesonh_files is the string representation of the path of the mesonh file to read (use an absolute path)

Maps¶

maps is a set containing kernels used for the maps and the definition of each map (except the wind map)
For the kernels field, it is a set of kernels defined.
Each kernel is defined like this :
- type is a string representing the type of kernel used. At the moment, you should use only 'WindKernel'
- length_scales is a list of 4 float (t, x, y, z). It represents the distance of a data from the current point before it becomes useless
- variance is a float representing the variance
- noise_variance is a float representing the variance of the noise

Then for the maps, there are only two fields in common :
- name, the string representation of the name of the map
- type, the type of map used (it can only be GprMap or MesonhMap)
For each type, there are multiple additional fields to fill.

For MesonhMap :
- mesonh_variable, string. This is the variable searched in the Mesonh Dataset
- origin, that is a list of 4 floats, representing the starting point of the mesonh dataset

For GprMap :
- kernel, string. The value must be the same as one of the kernels keys
- data_view, string. The value must be the same as one of the data_views keys
- data_range, list of two elements representing the min and max value of the data. Used mainly for display purposes
- threshold, float. Threshold of the map, used mainly for the computation of cloud data
- std_map, string optional. If set, will create the standard deviation of the map. The value of the field will be the name of this map
- border_map, string optional. If set, will create the border cloud map. The value of the field will be the name of this map

Additional Fields¶

allow_warm_start is a boolean. If it is set to True, will load the database and continue on it. (see the field filepath of the database)
mesonh_fixed_time is a number. This number is meant to indicate the only time read in the Mesonh Read (for instance, if the value is 96, the only time that is read is (time origin of the mesonh + 96) in the dataset). Other times are simply ignored. This variable must be set. If null, will work without a time fixed. The value is in seconds
mesonh_files is the string representation of the path of the mesonh file to read (use an absolute path)