Project

General

Profile

Scenario configuration reference guide » History » Version 4

Florian Seguin, 2020-09-09 14:41

1 1 Rafael Bailon-Ruiz
h1. Scenario configuration
2
3
This page is meant to guide users on how to write a scenario configuration file for the CAMS.
4
5
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.
6
7
h2. General structure of configuration files
8
9 2 Rafael Bailon-Ruiz
Configuration files are written using "YAML":https://yaml.org/ markup.
10 1 Rafael Bailon-Ruiz
11 2 Rafael Bailon-Ruiz
h3. Quick reference:
12
13
* YAML is a hierarchical key-value collection
14
* Values can be: Strings, Lists, Floats, Integers, Booleans (primary types)
15 1 Rafael Bailon-Ruiz
* Namespaces can be defined either as a variable, as a dictionnary if others namespaces are declared inside, or as a list using minuses ( - )
16 2 Rafael Bailon-Ruiz
* Use references to utilize constants at multiple locations: _&name_reference_ value to create and define the reference, _*name_reference_ to use it
17 1 Rafael Bailon-Ruiz
18 3 Rafael Bailon-Ruiz
*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.*
19 1 Rafael Bailon-Ruiz
20 2 Rafael Bailon-Ruiz
h2. Using the config file
21
22
The NEPHELAE_CONFIG environment variable must be in order to use it. There are two ways to do it :
23
24
* Setting the NEPHELAE_CONFIG environment during the current session (using the bashrc for instance, don't forget to source it).
25
<pre>export NEPHELAE_CONFIG="/path/to/the/configuration_file.yaml"</pre>
26
* Executing 'make runserver' with the NEPHELAE_CONFIG as argument (like this : NEPHELAE_CONFIG=_path_file_  make runserver)
27
28 3 Rafael Bailon-Ruiz
The first option is recommended if you plan to use the same file for multiple runs.
29 2 Rafael Bailon-Ruiz
30
h2. Available configuration options
31
32 1 Rafael Bailon-Ruiz
h3. Local Frame :
33
34
**local_frame** is defined in utm coordinates and have 4 different fields : **east**, **north**, **alt**, **utm_zone**.
35
- east, north and alt are floats
36
- utm_zone is a string
37
38
h3. Flight area :
39
40
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.
41
42
h3. Database :
43
 
44
The **database** can be defined by defining three fields :
45
- **enable_save**, boolean. If the boolean is set to true, will write periodically the database in a file
46
- **filepath**, string. This is the string representation of the path used to save the file on your machine (you should use an absolute path)
47
- **overwrite_existing**, boolean. If set to true, will rewrite the existing file (if it exists)
48
49
h3. Wind Map :
50
51
While this is a map, the *wind_map* is set apart from the other maps. It possesses three different fields :
52
- **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.
53
- **name**, which is a string. It is the name of the map.
54
Depending of the type, the third field can be different :
55
- **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.
56
- **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.
57
58
h3. Data Views : 
59
60
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.
61
- **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.
62
- **name** is a string, it is the name of the data view 
63
- **displayable** is an optional field. It is a boolean. If set to true, will appear in the charts of CAMS.
64
Other than that, the data view can have other fields to fill depending of the type set.
65
66
For FetchView :
67
- **tags** is a list of string, representing the tags of the data the view must search in the database.
68 2 Rafael Bailon-Ruiz
69 1 Rafael Bailon-Ruiz
For StatusView :
70
- **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
71
- **info** is an optional string, that is used to fetch a specific status info. (The position in **x**, **y**, **alt**, **time**)
72
73
For HumidityCalibration :
74
- **lt** is a float, that is the threshold value
75
- **gain_1** is a float, that is the factor of the first linear function
76
- **offset_1** is a float, that is the offset of the first linear function
77
- **gain_2** is a float, that is the factor of the second linear function
78
- **offset_2** is a float, that is the offset of the second linear function
79
- **parents** is a list, that contains every parent of this view. The strings contained in the list must exists in data views keys.
80
81
For CloudSensorProcessing :
82
- **cloud_tags** is a list of string, representing the tags of the data related to the clouds that must be searched in the database
83
- **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
84
- **alpha** is a float that is the factor of the linear function applied
85
- **beta** is a float that is the offset of the linear function applied
86
- **scaling** is a float
87
- **lengthMedian** is an integer
88
89
For Scaling : 
90
- **alpha** is a float that is the factor of the linear function applied
91
- **beta** is a float that is the offset of the linear function applied
92
- **parents** is a list, that contains every parent of this view. The strings contained in the list must exists in data views keys.
93
94
For TimeView : 
95
- **parents** is a list, that contains every parent of this view. The strings contained in the list must exists in data views keys.
96
97
h3. Aircrafts
98
99
The **aircrafts** set contains every aircraft that will fly during the scenario. The id of an aircraft is the key used in the collection.
100
Each aircraft can be passed in replay mode by defining the optional **replay** field to true.
101
102
Each aircraft has a **type** field that MUST be set. The values authorized are : 
103
- pprz (usage with paparazzi)
104
- base (usage without any monitoring uav software)
105
106
The aircrafts have also a list of plugins that are contained inside the **plugins** field.
107 4 Florian Seguin
List of plugins available : **MesonhProbe**, **Missions**, **CloudCenterTracker**, **MissionWindUpdater**, **Monitor**, **CloudSensor**, **MeteoStick**, **Energy**, **WindSimulation**
108 1 Rafael Bailon-Ruiz
The following plugins have additional fields that must be filled in order to use them :
109
110
For MesonhProbe :
111
- **mesonhFiles**, that is a string representation of the path of the mesonh file to read (use an absolute path)
112
- **mesonhVariables**, that are the mesonh variables fetched from the mesonh file. This is a list of string
113
- **rctFeedback**, that is a boolean.
114
- **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.
115
- **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)
116
117
For Missions :
118
- **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
119
There are optional fields to add, each representing a different mission. There are four possible at the moment : **Lace**, **Spiral3D**, **Rosette**, **Trinity**
120
121
For CloudCenterTracker :
122
- **mapWhereCenterIs**, that is a string. This string must be one of the key used to define a map (see Maps definition part below)
123
124
For MissionWindUpdater :
125
- **period**, float.
126
127 4 Florian Seguin
For WindSimulation :
128
- **mesonh_files** is the string representation of the path of the mesonh file to read (use an absolute path)
129
130 1 Rafael Bailon-Ruiz
h3. Maps
131
132
**maps** is a set containing kernels used for the maps and the definition of each map (except the wind map)
133
For the **kernels** field, it is a set of kernels defined.
134
Each kernel is defined like this :
135
- **type** is a string representing the type of kernel used. At the moment, you should use only 'WindKernel'
136
- **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
137
- **variance** is a float representing the variance
138
- **noise_variance** is a float representing the variance of the noise
139 2 Rafael Bailon-Ruiz
140 1 Rafael Bailon-Ruiz
Then for the maps, there are only two fields in common :
141
- **name**, the string representation of the name of the map
142
- **type**, the type of map used (it can only be GprMap or MesonhMap)
143
For each type, there are multiple additional fields to fill.
144
145
For MesonhMap :
146
- **mesonh_variable**, string. This is the variable searched in the Mesonh Dataset
147
- **origin**, that is a list of 4 floats, representing the starting point of the mesonh dataset
148
149
For GprMap : 
150
- **kernel**, string. The value must be the same as one of the kernels keys
151
- **data_view**, string. The value must be the same as one of the data_views keys
152
- **data_range**, list of two elements representing the min and max value of the data. Used mainly for display purposes
153
- **threshold**, float. Threshold of the map, used mainly for the computation of cloud data
154
- **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
155
- **border_map**, string optional. If set, will create the border cloud map. The value of the field will be the name of this map
156
157
h3. Additional Fields
158
159
**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)
160
**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
161
**mesonh_files** is the string representation of the path of the mesonh file to read (use an absolute path)