Running Apollo 5.0 with SVL Simulator #

Table of Contents

Getting Started top#

This guide outlines the steps required to setup Apollo 5.0 for use with the SVL Simulator. If you have not already set up the simulator, please do so first by following the instructions in Installing the SVL Simulator.

Prerequisites top#

  • Linux operating system (preferably Ubuntu 18.04 or later)
  • NVIDIA graphics card (required for Perception)
    • NVIDIA proprietary drivers must be installed.
    • Apollo 5.0 does not support Volta, Turing, or Ampere architectures (this includes Titan V, GTX 16xx, and RTX GPUs).

Setup top#

Docker top#

Apollo 5.0 is designed to be run inside of a Docker container. The working directory of this repository will be mounted as a volume when starting the container 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 5.0 does not work if the Docker is started with sudo. We suggest following through with the post installation steps.

Installing NVIDIA Container Toolkit top#

Before installing the NVIDIA Container Toolkit, make sure that you have the appropriate NVIDIA drivers installed. To test if the 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 450.102.04   Driver Version: 450.102.04   CUDA Version: 11.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  GeForce GTX 1080    Off  | 00000000:02:00.0  On |                  N/A |
| 41%   31C    P8    21W / 260W |    270MiB / 11016MiB |      3%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|    0   N/A  N/A      1404      G   /usr/lib/xorg/Xorg                 20MiB |
|    0   N/A  N/A      1467      G   /usr/bin/gnome-shell               57MiB |
|    0   N/A  N/A      2491      G   /usr/lib/xorg/Xorg                131MiB |
|    0   N/A  N/A      2630      G   /usr/bin/gnome-shell               44MiB |
|    0   N/A  N/A      3423      G   ...AAAAAAAA== --shared-files       12MiB |
+-----------------------------------------------------------------------------+

The installation steps for the NVIDIA Container Toolkit are available from the official documentation.

Pulling LGSVL Docker image top#

LGSVL maintains a Docker image to be used alongside this repository. The Docker image is available from Docker Hub.

To pull the image use the following command:

docker pull lgsvl/apollo-5.0

Cloning the Repository top#

This repository includes the protobuf branch of lgsvl_msgs as a submodule. To make sure that the submodule is 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 inside 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.

Enter the container:

docker/scripts/dev_into.sh

Build Apollo 5.0 (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 with 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 5.0 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 5.0 and the SVL Simulator.

  • Launch Apollo 5.0

    • Enter the container:

      docker/scripts/dev_into.sh

    • Start Apollo 5.0:

      bootstrap.sh

      Note: You may receive errors about Dreamview not being built if you do not run the script from the /apollo directory.

    • Start the bridge:

      bridge.sh

  • Run the SVL Simulator (outside of Docker). See these instructions.

    • Create a Simulation from the Random Traffic runtime template selecting the BorregasAve Map, the Lincoln2017MKZ Vehicle, and the Apollo 5.0 Sensor Configuration.
    • Enter localhost:9090 as the Bridge IP.
    • (Optional) Enable Traffic and Pedestrians.
    • (Optional) Set the Time of Day and weather settings.
    • Publish the simulation.
    • Select the created simulation and click Run Simulation.

  • Open Apollo 5.0 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 this in a new terminal (not inside the Docker container):

    docker/scripts/dev_start.sh stop

  • 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:

    sudo ufw allow 8888
sudo ufw allow 9090

These are required even if running the simulator and Apollo on the same machine.

Supported Vehicles top#

Only the calibration files for Lincoln 2017 MKZ, Jaguar 2015 XE, and Hyundai 2018 Nexo are included in the the simulator branch of the LGSVL fork of Apollo 5.0 at this time. More calibration files may be added later.

Adding an HD Map top#

  • Some default maps in your Maps library have their HD map files included in the simulator branch of the LGSVL fork of Apollo 5.0.
  • You can find other maps are in the Maps store.
  • If you want to add a new HD map to Apollo 5.0, follow these steps:
    • Either select a map in your Maps library and download the apollo50 HD map or export your own map from our map annotation tool as base_map.bin.
    • Create a new map folder under APOLLO_ROOT/modules/map/data/ and put base_map.bin in the folder.

    • Inside Apollo 5.0 Docker container:

      • Generate map files required by Apollo 5.0:

        cd /apollo
generate_map.sh YOUR_MAP_FOLDER_NAME

      • You need to restart Dreamview to refresh the map list:

        bootstrap.sh stop && bootstrap.sh