Skip to content

Commit

Permalink
Merge branch 'main' into mabelzhang/science_viz
Browse files Browse the repository at this point in the history
  • Loading branch information
@mabelzhang
mabelzhang committed Nov 13, 2021
2 parents 3853681 + 16bf805 commit 2c8f6ae
Show file tree
Hide file tree
Showing 6 changed files with 275 additions and 59 deletions.
164 changes: 109 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,28 @@ provided to the public on MBARI's DockerHub (see below), the simulated robot
can be controlled using the same code executed on the real robot.
This enables the validation of scientific missions for oceanography research.

## Using Docker for this repository (optional)

Optionally, you may choose to build this repository using Docker, for
convenience.
Make sure you have a recent version of [Docker](https://docs.docker.com/) and
[nvidia-docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker)
installed. Next to get started simply run the following command.
```
docker/build_and_run_docker.sh
```

To join in a separate terminal, remember to source Ignition and the workspace:
```
docker/join.sh mbari_lrauv
. /home/ign_ws/install/setup.bash
. /home/colcon_ws/install/setup.bash
```

## To build

Make sure you have [Ignition Fortress](https://ignitionrobotics.org/docs/fortress) and
To run the code in this repository natively without Docker, make sure you have
[Ignition Fortress](https://ignitionrobotics.org/docs/fortress) and
[colcon](https://colcon.readthedocs.io/en/released/), on Ubuntu Focal or higher.

Install dependencies
Expand All @@ -33,7 +52,7 @@ Clone this repository then run
colcon build
```

## To test Ignition standalone (without MBARI integration)
## To test simulation in Ignition standalone (without MBARI integration)

This package comes with an empty example world. To run this example world simply
source the colcon workspace and run:
Expand All @@ -54,43 +73,35 @@ LRAUV_keyboard_teleop

> Tip: Type `LRAUV_` and press tab for autocomplete to show more example examples.
## Using Docker

You may also choose to use Docker for convenience. Make sure you have
a recent version of [Docker](https://docs.docker.com/) and
[nvidia-docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker)
installed. Next to get started simply run the following command.
```
docker/build_and_run_docker.sh
```

To join in a separate terminal, remember to source Ignition and the workspace:
```
docker/join.sh mbari_lrauv
. /home/ign_ws/install/setup.bash
. /home/colcon_ws/install/setup.bash
```

## To test integration with MBARI LRAUV code base

MBARI's code base lives in a private repository. For people with access,
MBARI's code base lives in a separate, private repository.
For people with access,
[here](https://bitbucket.org/mbari/lrauv-application/src/7b3b5fce1b0ad1af1734952adaf94f2a69193aec/docker_ignition/?at=feature%2F2021-02-12-ignition-sim)
are instructions on setting it up from source.
are instructions on setting it up from source and compiling.

Alternatively, you can use the public Docker image (see below).

The integration assumes that this repository is cloned as a sibling of
the `lrauv-application` repository, i.e.:
```
<workspace>
|-- lrauv
`-- lrauv-application
└-- lrauv-application
```

### Docker image
For quick reference, compilation boils down to running this on the right branch:
```
make ignition
```

### MBARI public Docker image

A public Docker image is available for people without access to the MBARI
codebase.
[MBARI's image on DockerHub](https://hub.docker.com/r/mbari/lrauv-ignition-sim)
contains Ignition, MBARI's LRAUV code base, and this repository.
All the code has been compiled.
```
docker pull mbari/lrauv-ignition-sim
```
Expand All @@ -105,67 +116,69 @@ Once inside a container, source the colcon workspaces:
```
This needs to be done for each terminal.

### Setting up for a run
### Run the Ignition simulation

For ease of development, the following world is set up to run at a real time
factor (RTF) of 0 (as fast as possible) and a step size of 0.02 seconds.

That is significantly faster than the default Ignition setting of RTF 1 and
step size 0.001 seconds, which will give real time performance and roughly the
nominal vehicle speed of 1 m/s.

The RTF and step size can be changed at run time via the GUI by going to the
Inspector panel and then Physics Group.

Alternatively, they can be changed prior to compilation in the world SDF under
`<physics><max_step_size>` and `<physics><real_time_factor>`.

Launch the Ignition simulation:
```
ign launch lrauv_world.ign
```

For verbose debug output, add `--verbose 4`.

Run the LRAUV Main Vehicle Application (MVA), which will bring you to a command prompt:
Unpause Ignition by clicking on the triangle play button in the lower-left
corner of the GUI, or by pressing the space bar.

### Run the MBARI LRAUV application

The MBARI LRAUV Main Vehicle Application (MVA) contains everything needed to
control and operate the vehicle in the real world and in simulation.

Time synchronization has been done between the MBARI application and the
Ignition simulation, such that in most cases, the controller and the simulation
should be running in synchronization.
There may be corner cases that still need to be resolved.

This section assumes you have either compiled the target from source or are
using the MBARI public Docker image, which has everything pre-compiled.
The paths assume you are using the MBARI public Docker image.

Run the LRAUV Main Vehicle Application:
```
cd ~/lrauv_ws/src/lrauv-application
bin/LRAUV
```
This will bring you to a command prompt.

Unpause Ignition by clicking on the triangle play button in the lower-left
corner of the GUI.

At the LRAUV command prompt:
At the LRAUV command prompt (you only need to do this once):
```
>configset micromodem.loadatstartup 0 bool persist
>restart app
```
This sets the micromodem to not load at startup. `persist` means you only need
to do this once.
This sets the micromodem to not load at startup.
`persist` means you only need to do this once.
It will pause for a bit, you might not be able to type right away.

Speed up 100 times for a bit to finish loading, before returning to normal
speed.
This allows the commands to finish loading, before you overwrite them with
control commands.
Otherwise the preloaded commands can kick in after you issue control commands
and make the vehicle go to unexpected places
```
>quick on
>quick off
```
Alternatively, if you have access to the config files, set SBIT.loadAtStartup
to 0 bool in Config/BIT.cfg. This might already be set for you in the Docker
image on MBARI DockerHub.

On the vehicle, an app is always being run.
If no missions are specified, then it is running the default.
On the real vehicle, the default mission is `GoToSurface`.
(NOTE: we have removed the default app in the MBARI public image until
[this issue](https://github.com/osrf/lrauv/issues/38) is resolved.
Currently, nothing is being run by default. Skip this check.)
Verify that it is running the default `GoToSurface` app:
```
>show stack
2021-03-03T18:24:46.699Z,1614795886.699 [Default](IMPORTANT): Priority 0: Default:B.GoToSurface
```
An app is always being run.
If no missions are specified, then it is running the default.

### Control commands

Expand Down Expand Up @@ -223,6 +236,7 @@ run RegressionTests/IgnitionTests/testPitchMass.xml
run RegressionTests/IgnitionTests/testPitchAndDepthMassVBS.xml
run RegressionTests/IgnitionTests/testYoYoCircle.xml
```
Some example behaviors are documented [here](https://github.com/osrf/lrauv/issues/21).

Some parameters can be adjusted - see the mission XML file.
For example, to change the commanded depth in the `testDepthVBS.xml` mission:
Expand All @@ -243,9 +257,21 @@ For example, this will run the yoyo mission and terminate after the mission ends
bin/LRAUV -x "run RegressionTests/IgnitionTests/testYoYoCircle.xml quitAtEnd"
```

### To run the original LRAUV simulation
### To run the original MBARI LRAUV command-line simulation (optional)

The original simulation (`SimDaemon`) is the baseline comparison for the
Ignition simulation.

The original simulation is the baseline comparison for the Ignition simulation.
For developers, it helps to troubleshoot the Ignition simulation by comparing
its values to the original MBARI simulation, which is a pure command-line
interface.

Do not run both Ignition and SimDaemon at the same time.
Choose only one.

```
cd ~/lrauv_ws/src/lrauv-application
```

In the MBARI code base, open `Config/sim/Simulator.cfg`, change these lines to
look like this:
Expand All @@ -255,11 +281,31 @@ look like this:
```
This enables the original ExternalSim and disables the interface with Ignition.

Try it out:
Run the original command-line simulation:
```
bin/SimDaemon
```
The SimDaemon runs in the background by default.

Then run the Main Vehicle Application as usual:
```
bin/LRAUV
```

Speed up 100 times for a bit to finish loading, before returning to normal
speed.
This allows the commands to finish loading, before you overwrite them with
control commands.
Otherwise the preloaded commands can kick in after you issue control commands
and make the vehicle go to unexpected places
```
>quick on
>quick off
```
Alternatively, if you have access to the config files, set SBIT.loadAtStartup
to 0 bool in Config/BIT.cfg. This might already be set for you in the Docker
image on MBARI DockerHub.

Load the circle mission, which will perform two circles:
```
load Engineering/circle_test.xml
Expand Down Expand Up @@ -289,7 +335,7 @@ stop
quit
```

## Using Debug Container to debug the simulator
### Using Debug Container to debug the simulator

A simple dockerfile and tmux config exists that makes launching and debugging the different components of the project a lot easier. To use it simply run

Expand All @@ -299,7 +345,6 @@ This will build a new container with the source code and launch a tmux session.

![tmux_debug](https://user-images.githubusercontent.com/542272/137456870-a0eed740-7206-43c1-8ccf-215148ad4675.gif)


### LRAUV cheat sheet

This contains some most-often used commands for quick reference:
Expand Down Expand Up @@ -449,6 +494,15 @@ quick on
```
to let the system finish loading, before issuing control commands.
#### Unserializing and plotting values
On the MBARI Main Vehicle Application side, all values during the run are
stored to disk.
They can be retrieved after the run and plotted for debugging purposes.
See [`lrauv_ignition_plugins/plots/README.md`](https://github.com/osrf/lrauv/blob/main/lrauv_ignition_plugins/plots/README.md)
for instructions to unserialize and scripts for plotting.
## Science data
Science data can be read from a csv file with the following recognized field
Expand Down
8 changes: 6 additions & 2 deletions lrauv_description/models/tethys_equipped/model.sdf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,8 +118,10 @@
<alpha_stall>0.17</alpha_stall>
<a0>0</a0>
<area>0.0244</area>
<!-- Link's Y is perpendicular to the control surface -->
<upward>0 1 0</upward>
<forward>1 0 0</forward>
<!-- Link's X is pointing towards the back -->
<forward>-1 0 0</forward>
<link_name>vertical_fins</link_name>
<cp>0 0 0</cp>
</plugin>
Expand All @@ -135,8 +137,10 @@
<alpha_stall>0.17</alpha_stall>
<a0>0</a0>
<area>0.0244</area>
<!-- Link's Z is perpendicular to the control surface -->
<upward>0 0 1</upward>
<forward>1 0 0</forward>
<!-- Link's X is pointing towards the back -->
<forward>-1 0 0</forward>
<link_name>horizontal_fins</link_name>
<cp>0 0 0</cp>
</plugin>
Expand Down
2 changes: 2 additions & 0 deletions lrauv_ignition_plugins/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,7 @@ install(
foreach(EXAMPLE
example_buoyancy
example_controller
example_elevator
example_mass_shifter
example_rudder
example_spawn
Expand Down Expand Up @@ -237,6 +238,7 @@ if(BUILD_TESTING)
test_buoyancy_action
test_controller
test_drop_weight
test_elevator
test_mass_shifter
test_mission_depth_vbs
test_mission_pitch_mass
Expand Down
Loading

0 comments on commit 2c8f6ae

Please sign in to comment.