LRAUV Simulation

This repository contains packages for simulating the MBARI Tethys.

To build

Make sure you have ignition-fortress and colcon, on Ubuntu Focal or higher.

Install dependencies

sudo apt-get install libpcl-dev

Clone this repository then run

colcon build

To test 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:

. install/setup.bash
ign launch lrauv_world.ign

Send example commands to move some joints:

LRAUV_example_controller

Keyboard teleop:

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 and nvidia-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, here are instructions on setting it up from source.

The integration assumes that this repository is cloned as a sibling of the lrauv-application repository, i.e.:

<workspace>
|-- lrauv
`-- lrauv-application

Docker image

A public Docker image is available for people without access to the MBARI codebase. MBARI's image on DockerHub contains Ignition, MBARI's LRAUV code base, and this repository.

docker pull mbari/lrauv-ignition-sim

Note: To update that image, see instructions in MBARI's private lrauv-application repository.

Once inside a container, source the colcon workspaces:

. ~/ign_ws/install/setup.bash
. ~/lrauv_ws/install/setup.bash

This needs to be done for each terminal.

Setting up for a run

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

Keep it paused.

For verbose debug output, add --verbose 4.

Run the LRAUV Main Vehicle Application (MVA), which will bring you to a command prompt:

cd ~/lrauv_ws/src/lrauv-application
bin/LRAUV

Unpause Ignition by clicking on the triangle play button in the lower-left corner of the GUI. Note that Ignition should not be unpaused too far in advance of starting the MVA. That would produce a large gap in timestamp, which the MVA does not expect.

At the LRAUV command prompt:

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

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

Control commands can be issued to overwrite mission controls. For example, the rudder can be held at a constant angle like so:

>maintain control horizontalcontrol.rudderangleaction -15 degree

This overwrites the controller and maintains the rudder at -15 degrees (-0.261799 radians), which is the joint limit.

Unit conversions are automatically done in the MBARI code. Alternatively, you can specify in radians.

>maintain control horizontalcontrol.rudderangleaction -0.2 radian

A thruster command can then be issued to move the vehicle in a circle:

>maintain control SpeedControl.propOmegaAction 300 rpm

Currently, this is the tested and preferred method of control.

A sample list of command variables:

Config/Control-->HorizontalControl.loadAtStartup=1 bool
Config/Control-->HorizontalControl.kdHeading=0.049999 s
Config/Control-->HorizontalControl.kiHeading=0.001000 1/s
Config/Control-->HorizontalControl.kiwpHeading=0.000500 rad/s/m
Config/Control-->HorizontalControl.kpHeading=0.400000 n/a
Config/Control-->HorizontalControl.kwpHeading=0.049999 rad/m
Config/Control-->HorizontalControl.maxHdgAccel=7.499876 arcdeg/s2
Config/Control-->HorizontalControl.maxHdgInt=0.087266 rad
Config/Control-->HorizontalControl.maxHdgRate=11.999932 arcdeg/s
Config/Control-->HorizontalControl.maxKxte=45.000001 arcdeg
Config/Control-->HorizontalControl.rudDeadband=0.500000 arcdeg
Config/Control-->HorizontalControl.rudLimit=15.000000 arcdeg
VerticalControl-->VerticalControl.buoyancyAction=944.986938 cc
VerticalControl-->VerticalControl.depthIntegralInternal=nan rad
VerticalControl-->VerticalControl.depth2buoyIntInternal=nan cc
VerticalControl-->VerticalControl.massIntegralInternal=nan m
VerticalControl-->VerticalControl.elevatorIntegralInternal=nan rad
HorizontalControl-->HorizontalControl.rudderAngleAction=0.000000 rad
SpeedControl-->SpeedControl.propOmegaAction=0.000000 rad/s

Run missions designed for Ignition integration tests

The following are "unit test" missions that test one or two actuators at a time. Run one at a time, in separate runs of Ignition and the Main Vehicle Application (bin/LRAUV):

run RegressionTests/IgnitionTests/testDepthVBS.xml
run RegressionTests/IgnitionTests/testPitchMass.xml
run RegressionTests/IgnitionTests/testPitchAndDepthMassVBS.xml
run RegressionTests/IgnitionTests/testYoYoCircle.xml

Some parameters can be adjusted - see the mission XML file. For example, to change the commanded depth in the testDepthVBS.xml mission:

load RegressionTests/IgnitionTests/testDepthVBS.xml
set buoy_test_vbs.DepthCmd 20 meter
run

To stop a mission, run

stop

You can automate typing into the command prompt by issuing -x. 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

The original simulation is the baseline comparison for the Ignition simulation.

In the MBARI code base, open Config/sim/Simulator.cfg, change these lines to look like this:

   ExternalSim.loadAtStartup = 1 bool;
   ExternalSimIgnition.loadAtStartup = 0 bool;

This enables the original ExternalSim and disables the interface with Ignition.

Try it out:

bin/LRAUV

Load the circle mission, which will perform two circles:

load Engineering/circle_test.xml

Set some parameters as desired:

set circle_test.Depth01 10 meter;set circle_test.Depth02 15 meter;set circle_test.RudderAngle01 15 degree;set circle_test.RudderAngle02 10 degree;set circle_test.WaitDuration 10 minute
run;quick off

You can check variables like depth:

report touch depth
quick on

To clear the report and go back to normal speed:

report clear
quick off

To stop the mission and terminate:

stop
quit

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

$ docker/debug_integration.sh

This will build a new container with the source code and launch a tmux session. The tmux session has 2 windows: 0:simulation and 1:logging. In the simulation window you will see the top pane runs the ignition simulation while the bottom pane runs the actual bin/LRAUV controller. The logging pane on the other hand will automatically convert the sim slate and write it to the results directory on your computer one layer above the directory to where you checked out.

LRAUV cheat sheet

This contains some most-often used commands for quick reference:

Show general help or for a specific command:

>?
>help report

Show mission currently being run

>show stack

Speed up 100 times faster than real time:

>quick on
# To go back to normal speed
>quick off

To report the value continuously on variable touch:

>report touch <componentName>.<variableName>
# To stop reporting
>report clear

To get the current value of a variable:

>get <componentName>.<variableName>

A sample list of variables in the ExternalSim component:

ExternalSim.latitudeSim=36.803400 arcdeg
ExternalSim.longitudeSim=-121.822200 arcdeg
ExternalSim.eastingSim=605067.311028 m
ExternalSim.northingSim=4073710.248871 m
ExternalSim.utmZoneSim=10 enum
ExternalSim.propThrustSim=-0.000000 N
ExternalSim.propTorqueSim=-0.000000 N-m
ExternalSim.netBuoySim=0.000000 N
ExternalSim.forceXSim=0.000000 N
ExternalSim.forceYSim=0.000000 N
ExternalSim.forceZSim=0.000000 N
ExternalSim.posXSim=0.000000 m
ExternalSim.posYSim=0.000000 m
ExternalSim.posZSim=0.000000 m
ExternalSim.rollSim=0.000000 rad
ExternalSim.pitchSim=0.000000 rad
ExternalSim.headingSim=0.000000 rad
ExternalSim.posXDotSim=0.000000 m
ExternalSim.posYDotSim=0.000000 m
ExternalSim.posZDotSim=0.000000 m
ExternalSim.rateUSim=0.000000 m/s
ExternalSim.rateVSim=0.000000 m/s
ExternalSim.rateWSim=0.000000 m/s
ExternalSim.ratePSim=0.000000 m/s
ExternalSim.rateQSim=0.000000 m/s
ExternalSim.rateRSim=0.000000 m/s
ExternalSim.homingSensorRangeSim=27.335945 m
ExternalSim.homingSensorAzimSim=-1.531450 rad
ExternalSim.homingSensorElevSim=1.073800 rad

To stop a mission:

>stop

To terminate:

>quit

Troubleshoot

After issuing control commands, for example, rudder and thrust, if you then notice that the vehicle gets some commands by itself, such as a non-zero elevator angle, this is because a preloaded mission is being loaded, and you need to wait to issue the control commands after it is done loading. Make sure to use

quick on

to let the system finish loading, before issuing control commands.

Science data

Science data can be read from a csv file with the following recognized field names in the first line of the file:

elapsed_time_second
northings_meter
eastings_meter
depth_meter
sea_water_temperature_degC
sea_water_salinity_psu
mass_concentration_of_chlorophyll_in_sea_water_ugram_per_liter
eastward_sea_water_velocity_meter_per_sec
northward_sea_water_velocity_meter_per_sec