CAMS

h1. 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.

h2. General structure of configuration files

Configuration files are written using "YAML":https://yaml.org/ markup.

h3. 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":https://redmine.laas.fr/projects/nephelae-devel/repository/nephelae_gui/revisions/master/show/config/examples.*

h2. 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).

<pre>export NEPHELAE_CONFIG="/path/to/the/configuration_file.yaml"</pre>

* 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.

h2. Available configuration options

h3. 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

h3. 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.

h3. 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

- **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)

h3. 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.

h3. 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.

h3. 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.

- **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)

h3. 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

h3. 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)