CAMS

h1. Running CAMS in simulation mode (Tutorial)

This tutorial will teach you how to run the CAMS GUI with a simple scenario in simulation mode.

{{toc}}

First of all, *make sure you have successfully completed the [[Installation]] tutorial*. Then, open a terminal and change the current directory to the folder where the core packages are installed.

<pre><code class="shell">

cd /path/to/nephelae_workspace

</code></pre>

h2. Obtaining the simulated cloud environment files

In order to run CAMS in fully simulated mode first yout need a mesoNH file describing a synthetic atmospheric environment. MesoNH files are databases in "NetCDF _(.nc)_ format":https://en.wikipedia.org/wiki/NetCDF.

h3. Reduced cloud environment

A sample of a full cloud simulation can be found here: https://redmine.laas.fr/attachments/download/3293/cloud_example.nc (which is a crop of an small area from the file below)

h3. Complete cloud environment

The computer @girofle@ at LAAS contains a mesoNH file that can be used with CAMS. You can use the command below to mount the folder the remote folder as a local directory:

<pre><code class="shell">

sshfs girofle.laas.fr:/media/Nephelae-Data/data/Nephelae/ mesonh_girofle_mount/

</code></pre>

The recommended file for this tutorial is:

<pre>

REFHR.1.ARMCu.4D.nc

</pre>

Despite its huge size (~72 GB), the best way to work with this particular file is to download it to your computer. If you are at LAAS connected with an Ethernet cable, you have a high-bandwidth and low-latency link. Therefore you can read the files in the remote folder directly, but beware of errors that can occur if the quality of the connection degrades.

h2. Scenario setup

A valid configuration file is required to run the graphical interface server. Scenario configuration files describe the atmospheric environment and the UAVs so CAMS can use the appropriate algorithms and models to manage them. For this tutorial a simple configuration file is provided describing a scenario built upon a simulated atmosphere with cumulus clouds and two UAVs. 

1. Download the configuration file for this tutorial: https://redmine.laas.fr/projects/nephelae-devel/repository/nephelae_base/revisions/master/raw/examples/config/tutorial_simulation_mesonh_2uav.yaml

2. *You need adapt the following configuration values to match with the path of your CAMS workspace. Replace @/PATH/TO/@ with the actual path.*

<pre>

database: filepath: '/PATH/TO/database01.neph'  # CAMS database file. It stores the atmospheric and UAV information generated during the run

mesonh_files:  &mesonh_files '/PATH/TO/REFHR.1.ARMCu.4D.nc' # MesoNH simulation file.

aircrafts: 200: plugins: Missions: backup_file: '/PATH/TO/backup_200.bin' #

aircrafts: 201: plugins: Missions: backup_file: '/PATH/TO/backup_201.bin' #

</pre>

There are many other options that can be set in this configuration file to adapt CAMS to your needs. For more information, there is a [[scenario configuration reference guide]] in the wiki but for now you should stay with the default setup.

TODO: Introduce & explain the main parameter groups in the configuration file to give an overview of the situation the user will be managing.

h2. Launch the UAV simulation with paparazzi

h3. Configure the UAVs

Open a new terminal, change the current directory to the paparazzi installation folder and open the _Paparazzi center_ :

<pre><code class="shell">

cd /PATH/TO/paparazzi

./paparazzi

</code></pre>

1. Select the aircraft *Lisa_Neph_0* from the A/C list

2. Click build

3. Repeat the same procedure with the *Lisa_Neph_1* aircraft

{{thumbnail(paparazzi_center_instructions.png, size=600, title=Paparazzi center)}}

_You only need to do this operation once, unless you modify the UAVs or change computers!_

h3. Start the simulation

Open two new terminal windows and run respectively to start the simulation of both UAVs:

<pre><code class="shell">

cd nephelae_paparazzi/tests/sim_launchers && python3 sim_launcher.py Lisa_Neph_0 Lisa_Neph_1

</code></pre>

Three new windows will appear

| !server_lisa_neph_0.png! | !server_lisa_neph_1.png! | 

{{thumbnail(paparazzi_gcs_2_UAV_simulation_tutorial.png, size=600, title=Paparazzi GCS)}}

Wait a couple of seconds for the simulation to warm up and then click on the *launch button* !gcs_launch_button.png! followed by the *takeoff button* !gcs_takeoff_button.png! on *Lisa_Neph_0* and *Lisa_Neph_1*

h2. Run the CAMS GUI

Go to the installation folder of nephelae_gui and in a terminal, run:

<pre><code class="shell">

export NEPHELAE_CONFIG="/PATH/TO/tutorial_simulation_mesonh_2uav.yaml"

make runserver

</code></pre>

Replacing @/PATH/TO/@ with the actual path.

h2. Create a mission for a UAV

Open the CAMS GUI on the _Mapping_ tab. Go http://0.0.0.0:8000/map/

{{thumbnail(CAMS gui mapping web.png, size=600, title=CAMS GUI mapping tab)}}

Click somewhere over the map —preferably over the center of a cloud indicated by green shades— and select _New mission_. The _create mission_ window for the aircraft 200 (Lisa_Neph_0) will appear. Click on _Create_ .

{{thumbnail(CAMS gui create mission modal.png, size=300, title=CAMS GUI create mission dialog)}}

Go to the _Mission Validation_ tab and _Authorize_ the request to send the new mission to the paparazzi GCS.

{{thumbnail(CAMS gui mission validation.png, size=600, title=CAMS GUI mission validation)}}

Switch to the paparazzi GCS window and click on the _Mission_ button !gcs_mission_button.png! corresponding to the Lisa_Neph_0 UAV. This will tell the drone to start the mission.

Now you can follow the adaptive cloud mapping mission in the _Mapping_ tab of the CAMS GUI and monitor live raw data in the _Sensor data_ tab

| {{thumbnail(CAMS gui adaptive mapping.png, size=400, title=CAMS GUI mapping)}} | {{thumbnail(CAMS GUI raw data.png, size=400, title=CAMS GUI raw data)}} |

!cloud_mapping_video.gif!

*For more information about the possibilities of CAMS you can continue exploring the [[Graphical User Interface Reference guide]].*

h2. Set an arbitrary horizontal wind for the UAVs

In the paparazzi center open the _Tools_ menu → _Environment Simulator_ to start the _Gaia_ window. You can select there the _desired wind_ and the _simulation speed_.

p{border: solid 1px #FF8C00; padding: 1em; margin: 1em; background: #FEE}. %{color:darkorange; font-weight: bold; font-size: large}Warning:% Changing the time scale setting can produce unintended consecuences with the accuracy of the flight simulation. *CAMS is tied to the wallclock so it will not be aware of this setting*!