Running an LRAUV vehicle simulator

Requirements

Note

Work on the "dockerized" LRAUV simulator is still preliminary. Please let us know of any questions or suggestions.

Instructions

0. Login to Docker Hub

On your target machine, login with an account having access to the mbari/lrauv repository at Docker Hub:

$ docker login

1. Create an empty directory under which to run the LRAUV simulator. We will assume such directory designation has been captured in the ${MYLRAUVDIR} environment variable.

2. Create a subdirectory simConfig, which will contain files to overwrite default "sim" vehicle configuration settings.

$ mkdir simConfig

In particular, create and edit simConfig/secure.cfg to specify the TethysDash backend (IP or hostname, port, etc.) that the LRAUV simulator will be interacting with. For example:

Vehicle.dashIP          = "127.0.0.1";    // or a name, e.g., "tethysdash.example.net"
Vehicle.dashPort        = "8080";
Vehicle.dashPath        = "/TethysDash";
Vehicle.dashSSL         = 0 bool;
Vehicle.imei            = "mylrauvsim"
Vehicle.imeiPassword    = "mypw";
Vehicle.keyText         = "mykeytext";
Vehicle.hostname        = "";

This is:

  • dashIP and dashPort indicate the host and port of the TethysDash application. dashIP can actually also be name, e.g., "tethysdash.example.net" or "okeanids.mbari.org".
  • dashPath is the TethysDash application context on the host, typically "/TethysDash".
  • dashSSL indicates whether the server should be accessed securely (1 bool) or not (0 bool). (This would be 1 bool in the case of "okeanids.mbari.org".)
  • For a vehicle simulator, imei, imeiPassword, and keyText can be any arbitrary strings. Only requirement is that imei be unique with respect to all vehicles handled by the target TethysDash instance. (imei must be unique per vehicle since it is used by TethysDash to identify the source of incoming data.)
  • hostname is not used.

Also, create and edit simConfig/Sensor.cfg with the following contents:

DataOverHttps.loadAtStartup = 1 bool;

At this point the contents of ${MYLRAUVDIR} should look like this:

.
└── simConfig
   ├── secure.cfg
   └── Sensor.cfg

3. Visit https://cloud.docker.com/u/mbari/repository/docker/mbari/lrauv to select the latest version of the LRAUV image. In what follows we assume the image name is captured in the ${LRAUV_IMAGE} environment variable, for example:

$ export LRAUV_IMAGE="mbari/lrauv:2018-02-07_40d3c9a2"

4. Create the "lrauv" container

Note, we first create the container (so it is ready to be used multiple times), and then run it whenever needed.

The following will pull the image and create the container (additional details about some of the docker commands are provided below):

$ cd ${MYLRAUVDIR}
$ docker create --name lrauv \
                --volume $PWD/simConfig:/opt/lrauv-application/Config/sim/root \
                --volume $PWD/LRAUV_Logs:/opt/lrauv-application/Logs \
                --volume $PWD/LRAUV_Data:/opt/lrauv-application/Data \
                --interactive --tty \
                --net=host \
                ${LRAUV_IMAGE}

5. Run the "lrauv" container

$ docker start -ai lrauv

___ Running process_nav... ___
Opening Config file at: Config/regressionTests/Navigation.cfg
NavChartDb.charts = "US1WC07M,US2WC11M,US3CA52M,US4CA60M,US5CA50M,US5CA61M,US5CA62M,US5CA83M"
2017-03-01T23:34:44.252Z,1488411284.252 [NavChartDb](INFO): Looking for Electronic Nav Chart file at: Resources/ElectronicNavigationCharts/US1WC07M.000
...

___ Launching SimDaemon... ___
SimDaemon waiting to accept a connection!

___ Running simulator... ___
Writer for level Courier will be LZMA encoded.
Writer for level Express will be LZMA encoded.
Writer for level Priority will not be LZMA encoded.
Writer for level Normal will not be LZMA encoded.
...

lrauv>
  • Only on very first execution, a number of indexes are created (Running process_nav...); this may take several minutes.
  • You then should get the LRAUV prompt (shown as lrauv> above but the string before the > may be different). This prompt indicates that the "sim" vehicle is ready to accept commands from and interact with TethysDash. You can also enter commands directly at the prompt.
  • Logs are generated under $PWD/LRAUV_Logs/.
  • When done, enter exit at the prompt to terminate the simulator.

About the docker create/start commands

  • Inside the container, the LRAUV application is located under /opt/lrauv-application/.

  • The use of the --volume option allows to specify these directory mappings:

    Host Container
    $PWD/simConfig /opt/lrauv-application/Config/sim/root
    $PWD/LRAUV_Logs /opt/lrauv-application/Logs
    $PWD/LRAUV_Data /opt/lrauv-application/Data
  • --interactive, --tty, and -ai indicate that we want to run the container in interactive mode (so commands can also be entered directly).

  • --host=net puts the containerized simulator on your host network stack. In particular, this makes it simpler to allow interaction with TethysDash.

Upgrading to a new image

To use a new image of the LRAUV simulator:

  • Exit the currently running "lrauv" instance if any:
    • if running in interactive mode, enter exit at the prompt;
    • otherwise (but also applicable in general), run docker stop lrauv in another terminal.
  • Remove the container: docker rm lrauv
  • Optionally, remove the old image:
    • Run docker images to identify the ID of the image to be removed;
    • Run docker rmi <ID> to remove it.
  • Follow the instructions above starting with the updated new image tag specification for the docker create command.