Running Apollo 5.0 with LGSVL Simulator

This repository is a fork of Apollo maintained by the LG Electronics Silicon Valley Lab which has modified and configured to facilitate use with LG's Automotive Simulator.

The software and source code in this repository are intended only for use with LG Automotive Simulator and should not be used in a real vehicle.

Table of Contents

Getting Started top#

The guide outlines the steps required to setup Apollo for use with the LGSVL Simulator. If you have not already set up the simulator, please do so first by following the instructions here.

Prerequisites top#

  • Linux operating system (preferably Ubuntu 14.04 or later)
  • Nvidia graphics card (required for Perception)
    • Nvidia proprietary driver must be installed
    • The current version of Apollo does not support Volta and Turing architectures (this includes Titan V and RTX 2080 GPUs).

Setup top#

Docker top#

Apollo is designed to run out of docker containers. The image will mount this repository as a volume so the image will not need to be rebuilt each time a modification is made.

Installing Docker CE top#

To install Docker CE please refer to the official documentation.

NOTE Apollo does not work if the docker is started with sudo. We suggest following through with the post installation steps.

Installing Nvidia Docker top#

Before installing nvidia-docker make sure that you have an appropriate Nvidia driver installed. To test if nvidia drivers are properly installed enter nvidia-smi in a terminal. If the drivers are installed properly an output similar to the following should appear.

    +-----------------------------------------------------------------------------+
    | NVIDIA-SMI 390.87                 Driver Version: 390.87                    |
    |-------------------------------+----------------------+----------------------+
    | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
    | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
    |===============================+======================+======================|
    |   0  GeForce GTX 108...  Off  | 00000000:65:00.0  On |                  N/A |
    |  0%   59C    P5    22W / 250W |   1490MiB / 11175MiB |      4%      Default |
    +-------------------------------+----------------------+----------------------+

    +-----------------------------------------------------------------------------+
    | Processes:                                                       GPU Memory |
    |  GPU       PID   Type   Process name                             Usage      |
    |=============================================================================|
    |    0      1187      G   /usr/lib/xorg/Xorg                           863MiB |
    |    0      3816      G   /usr/bin/gnome-shell                         305MiB |
    |    0      4161      G   ...-token=7171B24E50C2F2C595566F55F1E4D257    68MiB |
    |    0      4480      G   ...quest-channel-token=3330599186510203656   147MiB |
    |    0     17936      G   ...-token=5299D28BAAD9F3087B25687A764851BB   103MiB |
    +-----------------------------------------------------------------------------+

The installation steps for nvidia-docker are available at the official repo.

Pulling LGSVL Docker image top#

LGSVL maintains a docker image to be used alongside this repository. The docker image is available here.

To pull the image use the following command:

docker pull lgsvl/apollo-5.0

Cloning the Repository top#

This repository includes a couple of submodules for HD Maps and lgsvl msgs. To make sure that the submodules are also cloned use the following command:

git clone --recurse-submodules https://github.com/lgsvl/apollo-5.0.git

Building Apollo and bridge top#

Now everything should be in place to build apollo. Apollo must be built from the container. To launch the container navigate to the directory where the repository was cloned and enter:

./docker/scripts/dev_start.sh

This should launch the container and mount a few volumes. It could take a few minutes to pull the latest volumes on the first run.

To get into the container:

./docker/scripts/dev_into.sh

Build Apollo (optimized, not debug, with GPU support):

./apollo.sh build_opt_gpu

NOTE The Apollo 5.0 build may run out of memory and crash on some machines due to aggressive parallelization in the build, as discussed in Apollo issue 7719.

If the build fails, either re-start it until it succeeds, or try changing line ~150 of function build() in apollo.sh as follows:

Replace this: JOB_ARG="--jobs=$(nproc) --ram_utilization_factor 80"

With this, which will use all but two cores for the build: JOB_ARG="--jobs=$(expr $(nproc) - 2 ) --ram_utilization_factor 70"

Alternatively, you can analyze top while building, and decide how many jobs to enable to avoid running out of memory; then set a specific value in JOB_ARG, e.g. --jobs=6.

If it continues to fail (especially when running the linker) then you'll need to address the low memory situation by either adding more memory to your build machine or enabling or increasing available swap space. If your Apollo build is crashing on a 16GB machine with little or no swap, try setting it to 16GB.

Launching Apollo alongside the Simulator top#

Here we only describe only a simple case of driving from point A to point B using Apollo and the simulator.

To launch apollo, first launch and enter a container as described in the previous steps.

  • To start Apollo:

    Note: you may receive errors about dreamview not being build if you do not run the script from the /apollo directory.

bootstrap.sh
  • Launch bridge (inside docker container):
bridge.sh
  • Run the LG SVL Simulator outside of docker. See instructions in the simulator repository
    • Create a Simulation the BorregasAve map and Lincoln2017MKZ (Apollo 5.0) vehicle
    • Enter localhost:9090 as the Bridge Connection String
    • (Optional) Enable Traffic and Pedestrians
    • (Optional) Set the Time of Day and weather settings
    • Submit the Simulation
    • Select the created Simulation and click "Play"

  • Open Apollo dreamview in a browser by navigating to: localhost:8888

    • Select the Lincoln2017MKZ vehicle and BorregasAve map in the top right corner.
    • Open the Module Controller tap (on the left bar).
    • Enable Localization, Transform, Perception, Traffic Light, Planning, Prediction, Routing, and Control.
    • Navigate to the Route Editing tab.
    • Select a destination by clicking on a lane line and clicking Submit Route.
    • Watch the vehicle navigate to the destination.
    • To stop the docker container run the dev_start.sh stop script in apollo/docker/scripts in a new terminal (not in the docker container).

  • If you are using ufw, it is easiest to completely disable the firewall to allow connections sudo ufw disable

    • If that is not possible, add the following rules:
      • These are required even if running the simulator and Apollo on the same machine
      • sudo ufw allow 8888
      • sudo ufw allow 9090

Adding a Vehicle top#

The default vehicles have their calibration files included in the LGSVL Branch of Apollo 5.0.

Adding an HD Map top#

The default maps have their HD map files included in the LGSVL Branch of Apollo 5.0.