From ab0b17dc34ec109703765b196fec1bbb04f5519a Mon Sep 17 00:00:00 2001 From: Kenji Miyake Date: Fri, 4 Feb 2022 10:51:52 +0900 Subject: [PATCH] update documents Signed-off-by: Kenji Miyake --- docs/installation/autoware/.pages | 2 +- .../autoware/docker-installation.md | 134 ++++++++- docs/installation/autoware/index.md | 17 +- .../autoware/local-installation.md | 5 - .../autoware/source-installation.md | 105 +++++++ docs/installation/index.md | 40 ++- docs/installation/installation-ade-arm64.md | 123 -------- docs/installation/installation-ade.md | 217 -------------- docs/installation/installation-no-ade.md | 81 ------ docs/installation/lgsvl.md | 275 ------------------ docs/installation/target-environments.md | 17 -- 11 files changed, 281 insertions(+), 735 deletions(-) delete mode 100644 docs/installation/autoware/local-installation.md create mode 100644 docs/installation/autoware/source-installation.md delete mode 100644 docs/installation/installation-ade-arm64.md delete mode 100644 docs/installation/installation-ade.md delete mode 100644 docs/installation/installation-no-ade.md delete mode 100644 docs/installation/lgsvl.md delete mode 100644 docs/installation/target-environments.md diff --git a/docs/installation/autoware/.pages b/docs/installation/autoware/.pages index e4ef1036208..3bda360633c 100644 --- a/docs/installation/autoware/.pages +++ b/docs/installation/autoware/.pages @@ -1,4 +1,4 @@ nav: - index.md - - local-installation.md - docker-installation.md + - source-installation.md diff --git a/docs/installation/autoware/docker-installation.md b/docs/installation/autoware/docker-installation.md index bb436018849..46b1402502f 100644 --- a/docs/installation/autoware/docker-installation.md +++ b/docs/installation/autoware/docker-installation.md @@ -1,5 +1,135 @@ # Docker installation -!!! warning +!!! info - Under Construction + Since this page explains Docker-specific information, it is recommended to see [Source installation](./source-installation.md) as well if you need detailed information. + +## Prerequisites + +- [Git](https://git-scm.com/) + +## How to set up a development environment + +1. Clone `autowarefoundation/autoware` and move to the directory. + + ```bash + git clone https://github.com/autowarefoundation/autoware.git + ``` + +2. Install the dependencies. + + ```bash + ./setup-dev-env.sh docker + ``` + +## How to set up a workspace + +1. Launch a Docker container + + ```bash + rocker --nvidia --x11 --user \ + --volume $HOME/autoware \ + -- ghcr.io/autowarefoundation/autoware-universe:latest + ``` + + See [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md) for more advanced usage. + + After that, move to the workspace in the container: + + ```bash + cd autoware + ``` + +2. Create the `src` directory and clone repositories into it. + + ```bash + mkdir src + vcs import src < autoware.repos + ``` + +3. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + +## How to update a workspace + +1. Update the Docker image. + + ```bash + docker pull ghcr.io/autowarefoundation/autoware-universe:latest + rocker --nvidia --x11 --user \ + --volume $HOME/autoware \ + -- ghcr.io/autowarefoundation/autoware-universe:latest + ``` + +2. Update the `.repos` file. + + ```bash + cd autoware + git pull + ``` + +3. Update the repositories. + + ```bash + vcs import src < autoware.repos + vcs pull + ``` + +4. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + +## Troubleshooting + +Here are solutions for a few specific errors: + +### cuda error: forward compatibility was attempted on non supported hw + +When starting Docker with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error: + +```bash +docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"process_linux.go:432: running prestart hook 0 caused \\\"error running hook: exit status 1, stdout: , stderr: nvidia-container-cli: initialization error: cuda error: forward compatibility was attempted on non supported hw\\\\n\\\"\"": unknown. +ERROR: Command return non-zero exit code (see above): 125 +``` + +This usually indicates that a new NVIDIA graphics driver has been installed (usually via `apt`) but the system has not yet been restarted. A similar message may appear if the graphics driver is not available, for example because of resuming after suspend. + +To fix this, restart your system after installing the new NVIDIA driver. + +## Tips + +### Non-native arm64 System + +This section describes a process to run `arm64` systems on `amd64` systems using [`qemu-user-static`](https://github.com/multiarch/qemu-user-static). + +Initially, your system is usually incompatible with `arm64` systems. +To check that: + +```sh-session +$ docker run --rm -t arm64v8/ubuntu uname -m +WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested +standard_init_linux.go:228: exec user process caused: exec format error +``` + +Installing `qemu-user-static` enables us to run `arm64` images on `amd64` systems. + +```sh-session +$ sudo apt-get install qemu-user-static +$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +$ docker run --rm -t arm64v8/ubuntu uname -m +WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested +aarch64 +``` + +To run specify `arm64` architecture for Autoware's Docker images, add the suffix `-arm64`. + +```sh-session +$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:latest-arm64 +WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested +root@5b71391ad50f:/autoware# +``` diff --git a/docs/installation/autoware/index.md b/docs/installation/autoware/index.md index 292dd772203..b17475390f8 100644 --- a/docs/installation/autoware/index.md +++ b/docs/installation/autoware/index.md @@ -1,5 +1,18 @@ # Installation of Autoware -!!! warning +There are two ways to set up Autoware. Choose one according to your preference. - Under Construction +## 1. Docker installation + +Docker can ensure that all developers in a project have a common, consistent development environment. +It is recommended for beginners, light users, people who do not use Ubuntu. + +See [here](autoware/docker-installation.md) for the detailed steps. + +## 2. Source installation + +Source installation is for the cases where more granular control of the installation environment is needed. +It is recommended for skilled users or people who want to customize the environment. +Note that some problems may occur depending on your local environment. + +See [here](autoware/source-installation.md) for the detailed steps. diff --git a/docs/installation/autoware/local-installation.md b/docs/installation/autoware/local-installation.md deleted file mode 100644 index 06005ba2b7c..00000000000 --- a/docs/installation/autoware/local-installation.md +++ /dev/null @@ -1,5 +0,0 @@ -# Local installation - -!!! warning - - Under Construction diff --git a/docs/installation/autoware/source-installation.md b/docs/installation/autoware/source-installation.md new file mode 100644 index 00000000000..37e9e225c26 --- /dev/null +++ b/docs/installation/autoware/source-installation.md @@ -0,0 +1,105 @@ +# Source installation + +## Prerequisites + +- [Ubuntu 20.04](https://releases.ubuntu.com/20.04/) +- [Git](https://git-scm.com/) + - [Registering SSH keys to GitHub](https://github.com/settings/keys) is preferable. + +```bash +sudo apt-get -y update +sudo apt-get -y install git +``` + +## How to set up a development environment + +1. Clone `autowarefoundation/autoware` and move to the directory. + + ```bash + git clone https://github.com/autowarefoundation/autoware.git + cd autoware + ``` + +2. Install the dependencies. + + We use [Ansible](https://www.ansible.com/) to simplify the steps. + Please see the Ansible playbooks and roles if you want to know exactly what packages are installed. + + > Note: Before installing NVIDIA libraries, confirm and agree with the licenses. + + - [CUDA](https://docs.nvidia.com/cuda/eula/index.html) + - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/sla/index.html) + - [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/sla/index.html) + + ```bash + ./setup-dev-env.sh + ``` + +## How to set up a workspace + +1. Create the `src` directory and clone repositories into it. + + Autoware uses [vcstool](https://github.com/dirk-thomas/vcstool) to construct workspaces. + + ```bash + cd autoware + mkdir src + vcs import src < autoware.repos + ``` + +2. Install dependent ROS packages. + + Autoware requires some ROS 2 packages in addition to the core components. + The tool `rosdep` allows an automatic search and installation of such dependencies. + + ```bash + source /opt/ros/galactic/setup.bash + rosdep install --from-paths src --ignore-src --rosdistro $ROS_DISTRO + ``` + +3. Build the workspace. + + Autoware uses [colcon](https://colcon.readthedocs.io/en/released/index.html) to build workspaces. + Refer to the documentation for more advanced options. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + +## How to update a workspace + +1. Update the `.repos` file. + + ```bash + cd autoware + git pull + ``` + +2. Update the repositories. + + ```bash + vcs import src < autoware.repos + vcs pull + ``` + + For Git users: + + - `vcs import` is similar to `git checkout`. + - Note that it doesn't pull from the remote. + - `vcs pull` is similar to `git pull`. + - Note that it doesn't switch branches. + + Refer to the [official documentation](https://github.com/dirk-thomas/vcstool) for more information. + +3. Install dependent ROS packages. + + ```bash + source /opt/ros/galactic/setup.bash + rosdep install --from-paths src --ignore-src --rosdistro $ROS_DISTRO + ``` + +4. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` diff --git a/docs/installation/index.md b/docs/installation/index.md index cb3cb9d9971..cef81300758 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -1,20 +1,36 @@ # Installation -The supported environments are specified in [target-environments](target-environments.md). +## Target platforms -The recommended method for installation is through the use of [ADE](https://ade-cli.readthedocs.io/en/latest/), -a Docker-based tool to ensure that all developers in a project have a common, consistent development -environment. It comes with a pre-built version of Autoware.Auto, so that you will not need to compile it yourself -if you do not want to. +Autoware targets the platforms listed below. It may change in future versions of Autoware. -- [installation-ade](installation-ade.md) -- [installation-ade-arm64](installation-ade-arm64.md) +The Autoware Foundation provides no support on other platforms than those listed below. -Autoware.Core can also be built without the use of [ADE](https://ade-cli.readthedocs.io/en/latest/) -for cases where a more granular control of the installation environment is needed. +### Architecture -- [installation-no-ade](installation-no-ade.md) +- amd64 +- arm64 -A prerequisite for running the full software stack with simulation is the LGSVL simulator: +### ROS version -- [lgsvl](lgsvl.md) +- ROS 2 Galactic (**active development**) +- ROS 2 Humble (**will be supported in 2022**) + +Refer to [REP-2000](https://www.ros.org/reps/rep-2000.html) for the system dependencies. + +## Installation steps of Autoware + +See [here](autoware) for how to install Autoware. + +## Installation steps of tools for users + +Some other tools are required depending on the evaluation you want to do. +For example, if you run E2E simulation, you need to install a simulator for that. + +See [here](tools-for-users) for how to install the tools. + +## Installation steps of tools for developers + +There are also tools and settings for developers, such as Shells or IDEs. + +See [here](tools-for-developers) for how to install the tools. diff --git a/docs/installation/installation-ade-arm64.md b/docs/installation/installation-ade-arm64.md deleted file mode 100644 index aa85d44d368..00000000000 --- a/docs/installation/installation-ade-arm64.md +++ /dev/null @@ -1,123 +0,0 @@ -# Installation with ADE for arm64 Systems - -## Goals - -This article demonstrates how to launch Autoware.Core using ADE for `arm64` systems and those -wishing to develop using `arm64`. -This document will cover both native and non-native systems using ADE. - -## Native arm64 System - -The following section describes the process required to launch the ade environment on an `arm64` -based system. - -### Prerequisites - -Ensure that ADE has been installed and the `.adehome` file has been created. To complete this, -follow the instructions in [Install ADE](installation-ade.md#install-ade) then subsequently [Setup ADE home and project checkout](installation-ade.md#setup-ade-home-and-project-checkout). - -### Launch ADE arm64 Docker - -Enter the development directory and launch the ADE docker: - -```{bash} -cd ~/adehome/AutowareCore -ade --rc .aderc-arm64 start --update --enter -``` - -## Non-native arm64 System - -The following section describes the process to run multi-architecture systems using Docker, -`binfmt`, and `qemu`. - -### Prerequisites - -Before alternative architectures can be run on a system, ensure that one can run ADE and -Autoware.Core on the native architecture. -Those with `amd64` systems should follow the instructions in [Installation with ADE](installation-ade.md) and ensure -all dependencies are properly installed. -The following will assume that all ADE and Autoware.Core dependencies have been installed. - -!!! note - - The emulation library used for this section is currently only compatible with `x86_64`. - Check your system architecture using the following command: - - ```{bash} - $ uname -m - ``` - -To check the systems which Docker is compatible with run the following command: - -```{bash} -docker buildx ls -``` - -The output the following should look like this: - -```{bash} -$ docker buildx ls -NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS -default * docker - default default running linux/amd64, linux/386 -``` - -To check that your system is currently incompatible with `arm64` systems is by running: - -```{bash} -docker run --rm -t arm64v8/ubuntu uname -m -``` - -The output of this should error and indicate that libraries were not found. - -## Configuring Docker for Multi-architecture Emulation - -First, install emulation and binary support libraries that will allow Docker to run multiple -architectures. -The libraries [`qemu`](https://www.qemu.org/) and [`qemu-user-static`](https://github.com/multiarch/qemu-user-static) -provide emulation support allowing Docker to interpret alternative architectures on an `x86_64` environment. -The kernel module [`binfmt-support`](http://binfmt-support.nongnu.org/) allows for the registry -and invocation of binary interpreters at the system administrator level. - -```{bash} -sudo apt-get install qemu binfmt-support qemu-user-static -``` - -Finally, invoke the `qemu-user-static` docker image to install and link the interpreters and -architectures for various architectures. - -```{bash} -docker run --rm --privileged multiarch/qemu-user-static --reset -p yes -``` - -To check that the installation and registry was successful, run the following command and ensure -that it exits cleanly: - -```{bash} -$ docker run --rm -t arm64v8/ubuntu uname -m -... -aarch64 -``` - -Additional checks include running the `buildx` option with Docker. -This should output a larger variety of build types available to Docker. - -!!! note - - There will be an initial warning that the architecture of the image Docker is trying to bring up is different to the architecture of the system. - - ```{bash} - WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested - ``` - -## Launching ADE - -Now that the set-up is complete, the `arm64` ADE image can be launched with no issues - -```{bash} -ade --rc .aderc-arm64 start --update --enter -``` - -!!! warning - - Launching ADE in the non-native environment leads to incredibly reduced performance as compared to a native configuration due to the binary translation that is happening within Docker; approximately 5x that of a native system. diff --git a/docs/installation/installation-ade.md b/docs/installation/installation-ade.md deleted file mode 100644 index 32b63a20ea8..00000000000 --- a/docs/installation/installation-ade.md +++ /dev/null @@ -1,217 +0,0 @@ -# Installation with ADE - -## Goals - -This article demonstrates how to use the Agile Development Environment (ADE) to develop Autoware.Auto applications. - -## Install ADE - -[ADE](https://ade-cli.readthedocs.io/en/latest/) is a modular Docker-based tool to ensure that all developers in a project have a common, consistent development environment. - -Follow the [install](https://ade-cli.readthedocs.io/en/latest/install.html) instructions, which are reproduced here for convenience: - -1. Verify that the requirements [listed here](https://ade-cli.readthedocs.io/en/latest/install.html#requirements) are fulfilled. In particular, if docker was not used before, one may need to go through the [docker post-install steps](https://docs.docker.com/engine/install/linux-postinstall/). -2. Download the latest statically-linked binary for your platform from the [Releases](https://gitlab.com/ApexAI/ade-cli/-/releases) page of the `ade-cli` project -3. Name the binary `ade` and install it in `PATH`. On Ubuntu, `/usr/local/bin` is recommended for system-wide installation, otherwise choose e.g. `~/.local/bin` for a local installation that doesn't require `sudo` rights. -4. Make the binary executable: `chmod +x ade` -5. Check that it is installed: - -```{bash} -$ which ade -/path/to/ade -$ ade --version - -``` - -## Setup ADE home and project checkout - -ADE needs a directory on the host machine which is mounted as the user's -home directory within the container. The directory is populated with -dotfiles, and must be different than the user's home directory -_outside_ of the container. In the event ADE is used for multiple, projects it -is recommended to use dedicated `adehome` directories for each project. - -ADE looks for a directory containing a file named `.adehome` -starting with the current working directory and continuing with the -parent directories to identify the ADE home directory to be mounted. - -```{bash} -mkdir -p ~/adehome -cd ~/adehome -touch .adehome -``` - -For ADE to function, it must be properly configured. Autoware.Auto provides -an [.aderc](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/blob/master/.aderc) file -which is expected to exist in the current working -directory, or in any parent directory. Additionally, default configuration values can be -overridden by setting environment variables. See the `ade --help` output for more information about -using environment variables to define the configuration. - -```{bash} -cd ~/adehome -git clone https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto.git -``` - -TODO: Fix repo url and release url - -Checkout the [latest release](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/releases) by checking out the corresponding tag or release branch. -Alternatively, when not checking out any specific tag, the latest `master` branch will be used -which may include features that are still being developed. For example: - -```{bash} -cd AutowareAuto -git checkout tags/1.0.0 -b release-1.0.0 -``` - -### Sharing files between the host system and ADE (Optional) - -It might come in handy to share files such as dotfiles or utility programs from your host machine -with ADE. If you only have a single `adehome` directory, there is a way to do that without -duplicating them: move them inside the `adehome` directory, then create a symlink in the host system -to their regular location. For instance, - -```{bash} -cd ~ -cp ~/.bashrc ~/.bashrc.bak -mv ~/.bashrc ~/adehome/.bashrc -ln -s ~/adehome/.bashrc -``` - -It will then appear as `~/.bashrc` to the host system and to ADE. - -Another option is to put utility programs into `~/adehome/.local/bin` and symlink. The opposite -direction will not work, files in a Docker container can not be symlinks to the outside. - -!!! note - - The programs have to be self-contained! They should not depend on loading libraries from e.g. `/usr/lib`. - - There is a risk of an error (symlink would be broken and .bashrc would not be loaded when your terminal is started). In this case, you should delete the symlink and move .bashrc back to the original directory. - -## Entering the development environment - -```{bash} -cd AutowareAuto -``` - -To start the default environment: - -```{bash} -ade start --update --enter -``` - -There are several preconfigured environments to choose from by specifying an ADE rc file. To see -what is available, run - -```{bash} -ls -l .aderc* -``` - -Choose one, then launch with: - -```{bash} -ade --rc .aderc-amd64-foxy start --update --enter -``` - -Congratulations! Now you should have a terminal inside ADE: - -```{bash} -$ade:~$ -``` - -The next steps are to proceed to [Usage](usage.md), or to work on the Autoware.Code code itself as -described in [Contributors guide](contributors-guide.md). - -## What is where inside ADE? - -Upon entering, ADE outputs the images used to create the environment; e.g. - -```{bash} -$ ade enter -Entering ade with following images: -ade-foxy | 8b1e0efdde07 | master | registry.gitlab.com/autowarefoundation/autoware.auto/autowareauto/amd64/ade-foxy:master -binary-foxy | 0e582f863d4c | master | registry.gitlab.com/autowarefoundation/autoware.auto/autowareauto/amd64/binary-foxy:master -foxy | 2020.06 | 2020.06 | registry.gitlab.com/autowarefoundation/autoware.auto/ade-lgsvl/foxy:2020.06 -``` - -The images are mounted under `/opt`: - -```{bash} -@ade:~$ ls /opt -AutowareAuto # image: binary-foxy:master -lgsvl # image: ade-lgsvl/foxy:2020.06 -ros # image: ade-foxy:master -``` - -The code in `/opt/AutowareCore` is built from a particular version of the main branch of -Autoware.Core. The master branch is built multiple times a day in CI; see the [container -registry](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/container_registry). With -`ade ... --update`, the latest available version of each image is downloaded. - -## Cleanup - -ADE uses Docker, and over time unused images, containers, and volumes begin to clutter the hard -drive. Follow the steps below to clean the Docker file system of stale images. - -### Start relevant Docker resources - -First, verify that ADE is running: - -```{bash} -cd ~/adehome/AutowareAuto -ade start -``` - -If ADE is used for more than one project, verify all ADE instances are running; the same rule -applies for any other non-ADE Docker containers that should be preserved. - -!!! note - - Docker resources that are not started/running **will be removed**! - -### Docker disk usage - -To assess the disk usage situation, run the following command: - -```{bash} -$ docker system df -TYPE TOTAL ACTIVE SIZE RECLAIMABLE -Images 13 11 14.03GB 916.9MB (6%) -Containers 11 0 2.311MB 2.311MB (100%) -Local Volumes 17 15 5.411GB 17.8MB (0%) -Build Cache 0 0 0B 0B -``` - -### Remove unused docker items - -Use `docker system prune` to remove any Docker items not used for currently running containers: - -```{bash} -docker system prune -a --volumes -``` - -## Troubleshooting - -Here are solutions for a few specific errors: - -### Error - "forward compatibility was attempted on non supported hw" when starting ADE - -When starting `ade` with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error: - -```{bash} -docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"process_linux.go:432: running prestart hook 0 caused \\\"error running hook: exit status 1, stdout: , stderr: nvidia-container-cli: initialization error: cuda error: forward compatibility was attempted on non supported hw\\\\n\\\"\"": unknown. -ERROR: Command return non-zero exit code (see above): 125 -``` - -This usually indicates that a new NVIDIA graphics driver has been installed (usually via `apt`) but the system has not yet been restarted. A similar message may appear if the graphics driver is not available, for example because of resuming after suspend. - -#### Solution - -Restart your system after installing the new NVIDIA driver. - -```{bash} -ade$ exit -$ ade stop -$ ade start --update --enter -``` diff --git a/docs/installation/installation-no-ade.md b/docs/installation/installation-no-ade.md deleted file mode 100644 index cc078650994..00000000000 --- a/docs/installation/installation-no-ade.md +++ /dev/null @@ -1,81 +0,0 @@ -# Installation without ADE - -## Goals - -This article demonstrates how to successfully build [Autoware.Core](https://www.autoware.core/) applications without the ade framework. - -## Installation Requirements - -To compile [Autoware.Core project](https://www.autoware.core/) from sources, the following tools must be installed in the system. - -- Apt packages - -```{bash} -sudo apt install -y git cmake python3-pip -``` - -- Python modules - -```{bash} -pip3 install -U colcon-common-extensions vcstool -``` - -## ROS 2 core - -First, the [ROS 2](https://index.ros.org/doc/ros2/) core components and tools must be installed. The full guide is available at [ROS 2 Installation](https://index.ros.org/doc/ros2/Installation/). -Once installed source the setup file: - -```{bash} -source /opt/ros/$ROS_DISTRO/setup.bash -``` - -where `ROS_DISTRO` is one of the supported version mentioned in [Target Software Platforms](target-environments.md#target-software-platforms). - -## ROS 2 package dependencies - -[Autoware.Core project](https://www.autoware.core/) requires some [ROS 2](https://index.ros.org/doc/ros2/) packages in addition to the core components. -The tool `rosdep` allows an automatic search and installation of such dependencies. - -```{bash} -sudo apt update -sudo apt install -y python3-rosdep -sudo rosdep init -rosdep update -``` - -Once installed, dependencies can be deduced from the sources of the [Autoware.Core project](https://www.autoware.core/). - -```{bash} -git clone https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto.git -cd AutowareAuto -vcs import < autoware.auto.$ROS_DISTRO.repos -export ROS_VERSION=2 -rosdep install -y -i --from-paths src -``` - -Checkout the [latest release](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/releases) by checking out the corresponding tag or release branch. -Alternatively, when not checking out any specific tag, the latest `master` branch will be used -which may include features that are still being developed. For example: - -```{bash} -git checkout tags/1.0.0 -b release-1.0.0 -``` - -Next, to compile the source code, see @ref building. - -## Troubleshooting - -In case where `ros-foxy-autoware-auto-msgs` is installed on the system, colcon uses it instead of -the one in the `AutowareAuto/src/external/` folder. This may cause errors. -To prevent this, please remove the package by: - -```{bash} -sudo apt purge -y ros-foxy-autoware-auto-msgs -``` - -In case an error occurs related to `acado` package, please run: - -```{bash} -sudo apt purge -y ros-foxy-acado-vendor -sudo apt install -y ros-foxy-acado-vendor -``` diff --git a/docs/installation/lgsvl.md b/docs/installation/lgsvl.md deleted file mode 100644 index e2bb99bb3e7..00000000000 --- a/docs/installation/lgsvl.md +++ /dev/null @@ -1,275 +0,0 @@ -# SVL simulator - -## SVL simulator: running the SVL simulator alongside Autoware.Core - -SVL is a Unity-based multi-robot simulator for autonomous vehicle developers. It provides a simulated world to - -- create sensor inputs to Autoware.Core, -- allow the user to manually steer the ego vehicle similar to a computer game, -- place other moving traffic participants in a scene. - -For more information about the simulator, see [https://www.svlsimulator.com/docs/getting-started/getting-started/](https://www.svlsimulator.com/docs/getting-started/getting-started/). - -## Requirements - -The following guide assumes that the SVL simulator will be run from inside an ADE container, although it is not strictly required. - -- ADE 4.2.0 or later. Follow the [ADE installation instructions](https://ade-cli.readthedocs.io/en/latest/install.html) to install it -- NVidia graphics card -- If using Docker engine version 19.03 or later, [install Native GPU Support](). -- If using Docker engine with a version less than 19.03, either upgrade Docker or [install nvidia-docker2]() -- Cyclone DDS is the DDS vendor; see @ref choosing-a-dds-vendor - -## Using the simulator - -Using the simulator involves the following steps: - -1. Launch it -1. Configure cluster (one time step) -1. Choose or create a simulation -1. Start the simulation - -This section outlines these steps. You also need an SVL account to use the simulator, if you do not have one, create it now on `https://wise.svlsimulator.com/`. - -### Launching the simulator - -Install ADE as described in the [installation section](installation-ade.md): - -Start ADE with the SVL volume: - -```{bash} -cd ~/adehome/AutowareAuto -ade --rc .aderc-amd64-foxy-lgsvl start --update --enter -``` - -Pick a different `.aderc-*-lgsvl` file to manually choose a ROS version. - -To start the SVL simulator, in the same terminal window: - -```{bash} -ade$ /opt/lgsvl/simulator -``` - -#### Troubleshooting - -In case the simulator window opens up with a black screen and the application immediately terminates, have a look at the log file at - -```{bash} -~/.config/unity3d/LGElectronics/SVLSimulator/Player.log -``` - -One possible fix is to remove conflicting graphics drivers from ADE with - -```{bash} -ade$ sudo apt remove mesa-vulkan-drivers -``` - -and launch the simulator again. - -If point cloud data or image data is not being visualized in rviz but other data such as bounding box is visible run the following command inside ade, - -```{bash} -ade$ sudo apt update ; sudo apt dist-upgrade -``` - -### Configure the cluster - -You need to make your ADE environment a valid SVL cluster in order to launch any simulations. This is a one time configuration step. - -On your first simulator run there should be a window with only one button: `LINK TO CLOUD`. Click it and a web browser with `https://wise.svlsimulator.com/` should open. You can create a new cluster there by providing a cluster name and clicking `Create cluster` button. - -More about linking to cloud: [documentation](https://www.svlsimulator.com/docs/installation-guide/installing-simulator/#linktocloud). - -### Creating a simulation - -Creating a simulation takes only a few clicks in the browser. The following steps assume that the launch was successful and illustrate the configuration process with the setup for the @ref avpdemo. - -Start your browser and go to [SVL simulator web interface](https://wise.svlsimulator.com/). You should have your account set up already, so sign in using the button on the top right of the screen. - -#### Choosing a map - -The goal is to add `AutonomouStuff` parking lot map to your library. If that map is already in your library then nothing needs to be done. - -Adding a map to your library: - -- Go to `Store` -> `Maps`. -- Click `+` button next to `AutonomouStuff` map (you can use search bar to filter by name). - -@image html images/svl-map.png "Choosing a map" width=50% - -#### Configuring a vehicle {#lgsvl-configuring-vehicle} - -The goal is to add `AWFLexus2016RXHybrid` vehicle to your library. If this vehicle is already in your library then nothing needs to be done. - -Adding a vehicle to your library: - -- Go to `Store` -> `Vehicles`. -- Click `+` button next to `AWFLexus2016RXHybrid` vehicle (you can use search bar to filter by name). - -@image html images/svl-vehicle.png `Adding a vehicle` width=50% - -#### Adding ROS2ForUnitySVLBridge - -The goal is to add native ROS2 bridge to your library. If this bridge is already in your library then nothing needs to be done: - -- Go to [ROS2ForUnitySVLBridge](https://wise.svlsimulator.com/plugins/profile/d490cb21-2a44-447f-a289-7d869f23aabf) plugin page. -- Click `Add to Library` button. - -You can also search for `ROS2ForUnitySVLBridge` using the search bar. - -#### Configure vehicle sensors - -Once you added vehicle to your library: - -- Go to `Library` -> `Vehicles`. -- Click on the `AWFLexus2016RXHybrid` portrait. You will be forwarded to a vehicle edit page. -- Click a button near `Sensor Configurations` section to modify sensor configurations. - -@image html images/svl-sensors.png "Configuring sensors" - -Notice that there is already an `Autoware.Auto` configuration. To make sure that we are running the newest version possible, it is better to create a new one and use the most recent version of sensor configuration file: - -- Click `+ Create New Configuration` button at the bottom of the page. -- Set a configuration name and pick `ROS2ForUnitySVLBridge` as a bridge. This is a native implementation of ROS2 bridge. -- Confirm. - -In the configuration edit view: - -- Click `{...}` symbol near Visual Editor (preview) window. -- Paste contents of [avp-sensors.json](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/src/launch/autoware_demos/config/svl/avp-sensors.json) file inside edit window. `Configurator` window should populate with bunch of sensors now. -- Click `Save` to save configuration. - -@image html images/svl-sensors-json.png "Json configuration file" width=40% - -That’s it. Now you have a vehicle with a valid configuration. - -#### Choosing/creating a simulation - -The SVL simulator lets you store and reuse multiple simulation configurations. To use an existing simulation, navigate to `Simulations` tab and press the "Run Simulation" button for desired instance. The simulator should now start in the SVL window. - -To create a new simulation, follow the below steps: - -- Switch to the `Simulations` tab and click the `Add new` button. -- Enter a name, description and select a cluster. Click `Next`. -- Select the `Random Traffic` runtime template from the drop-down menu. -- Select `AutonomouStuff` map and `AWFLexus2016RXHybrid` vehicle with your sensor configuration. Click `Next`. -- Select `Other ROS 2 Autopilot` autopilot and leave `Bridge Connection` with default value. -- Click `Next` and then `Publish`. - -You can visit [SVL documentation](https://www.svlsimulator.com/docs/user-interface/web/simulations/) for more in-depth description. - -### Starting the simulation {#lgsvl-start-simulation} - -Once the simulation has been created, you can run it by clicking the `Run Simulation` button next to the simulation configuration widget in `Simulations` view. - -@image html images/svl-simulation-start.png "Starting the simulation" width=40% - -The Lexus should appear in the `SVL Simulator` window (not in the browser). - -The next step is to control the Lexus and to drive around. Press `F1` to see a list of shortcuts and press the cookie button in bottom left corner for more UI controls. - -The essential commands are to use the arrow keys to steer and accelerate, and the `Page Up` and `Page Down` keys to switch between forward and reverse driving. - -Congratulations if everything is working up to this point. The setup of SVL is completed. - -@image html images/lgsvl-controls.png "Controlling the Lexus" width=60% - -@todo #850 Uncomment joystick session when tested again - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -## Bridging with Autoware.Core - -@todo update check section - -SVL uses conventions which are not directly aligned with ROS 2 conventions. The full list of behaviors the `lgsvl_interface` implements is: --# Converts control inputs with CCW positive rotations to the CCW negative inputs the SVL -simulator expects --# Provides a mapping from `VehicleControlCommand` to the `RawControlCommand` SVL expects via -parametrizable 1D lookup tables - -To run the `lgsvl_interface` manually, enter the following in a new terminal window: - -```{bash} -$ ade enter -ade$ source /opt/AutowareAuto/setup.bash -ade$ ros2 run lgsvl_interface lgsvl_interface_exe --ros-args --params-file /opt/AutowareAuto/share/lgsvl_interface/param/lgsvl.param.yaml -``` - -Autoware.Core uses PointCloud2 messages with `x,y,z,intensity` rather than `x,y,z,intensity,timestamp` fields. - -This node will convert `points_xyzi` - -Run `point_type_adapter` to convert the messages. - -```{bash} -$ ade enter -ade$ source /opt/AutowareAuto/setup.bash -ade$ ros2 launch point_type_adapter point_type_adapter.launch.py -``` - -Launch scripts are also provided for convenience. For example for a joystick control demo, run the following in a new terminal window: - -```{bash} -$ ade enter -ade$ source /opt/AutowareAuto/setup.bash -ade$ ros2 launch joystick_vehicle_interface_nodes lgsvl_joystick.launch.py -``` - -For an example of using `VehicleControlCommand` with SVL, run the following demo in a new terminal window: - -```{bash} -$ ade enter -ade$ source /opt/AutowareAuto/setup.bash -ade$ ros2 launch lgsvl_interface lgsvl_vehicle_control_command.launch.py -``` diff --git a/docs/installation/target-environments.md b/docs/installation/target-environments.md deleted file mode 100644 index bc91a14fb79..00000000000 --- a/docs/installation/target-environments.md +++ /dev/null @@ -1,17 +0,0 @@ -# System Dependencies and Target Environments - -Autoware.Core targets the environments and applications listed below, for which automated tests ensure the code works properly. The target environments may change in future versions of Autoware.Core. - -The Autoware foundation provides no support on other platforms than those listed below. - -## Target Hardware Platforms - -- `amd64` / `x86_64` (Intel/AMD) -- `arm64` / `aarch64` / `arm64v8` (ARM v8, 64-bit) - -## Target Software Platforms - -| ROS Version | Operating System | System Dependencies | -| ----------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------- | -| ROS2 Foxy (**active development**) | Ubuntu 20.04 LTS | [REP-2000 section](https://www.ros.org/reps/rep-2000.html#foxy-fitzroy-may-2020-may-2023) | -| ROS2 Dashing (**maintenance only**) | Ubuntu 18.04 LTS | [REP-2000 section](https://www.ros.org/reps/rep-2000.html#dashing-diademata-may-2019-may-2021) |