From dfcbbb0f9ba389ffbe8a88a9c6cfe0722b636ad6 Mon Sep 17 00:00:00 2001 From: github-actions Date: Wed, 22 Nov 2023 05:56:47 +0000 Subject: [PATCH] Deployed 21c9fea44 to pr-385 with MkDocs 1.4.3 and mike 2.1.0.dev0 --- .../perception/index.html | 6 +++--- pr-385/search/search_index.json | 2 +- pr-385/sitemap.xml.gz | Bin 1891 -> 1891 bytes 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pr-385/design/autoware-architecture/perception/index.html b/pr-385/design/autoware-architecture/perception/index.html index bfc74d0baa8..c86929e7422 100644 --- a/pr-385/design/autoware-architecture/perception/index.html +++ b/pr-385/design/autoware-architecture/perception/index.html @@ -4523,12 +4523,12 @@

Supported FunctionsSupported FunctionsAutoware is the world\u2019s leading open-source software project for autonomous driving. Autoware is built on Robot Operating System (ROS) and enables commercial deployment of autonomous driving in a broad range of vehicles and applications.

Please see here for more details.

"},{"location":"#related-documentations","title":"Related Documentations","text":"

This Autoware Documentation is for Autoware's general information.

For detailed documents of Autoware Universe components, see Autoware Universe Documentation.

"},{"location":"#getting-started","title":"Getting started","text":"
  • Installation pages explain the installation steps of Autoware and related tools.
  • Tutorials pages explain several tutorials that you should try after installation.
  • How-to guides pages explain advanced topics that you should read after you get used to Autoware.
  • Design pages explain the design concept of Autoware.
  • Contributing pages explain how to contribute to Autoware.
  • Datasets pages contain information about datasets that can be used with Autoware.
  • Support pages explain several support resources.
"},{"location":"contributing/","title":"Contributing","text":""},{"location":"contributing/#contributing","title":"Contributing","text":"

Thank you for your interest in contributing! Autoware is supported by people like you, and all types and sizes of contribution are welcome.

As a contributor, here are the guidelines that we would like you to follow for Autoware and its associated repositories.

  • Code of Conduct
  • What should I know before I get started?
    • Autoware concepts
    • Contributing to open source projects
  • How can I get help?
  • How can I contribute?
    • Participate in discussions
    • Join a working group
    • Report bugs
    • Make a pull request

Like Autoware itself, these guidelines are being actively developed and suggestions for improvement are always welcome! Guideline changes can be proposed by creating a discussion in the Ideas category.

"},{"location":"contributing/#code-of-conduct","title":"Code of Conduct","text":"

To ensure the Autoware community stays open and inclusive, please follow the Code of Conduct.

If you believe that someone in the community has violated the Code of Conduct, please make a report by emailing conduct@autoware.org.

"},{"location":"contributing/#what-should-i-know-before-i-get-started","title":"What should I know before I get started?","text":""},{"location":"contributing/#autoware-concepts","title":"Autoware concepts","text":"

To gain a high-level understanding of Autoware's architecture and design, the following pages provide a brief overview:

  • Autoware architecture
  • Autoware concepts

For experienced developers, the Autoware interfaces and individual component pages should also be reviewed to understand the inputs and outputs for each component or module at a more detailed level.

"},{"location":"contributing/#contributing-to-open-source-projects","title":"Contributing to open source projects","text":"

If you are new to open source projects, we recommend reading GitHub's How to Contribute to Open Source guide for an overview of why people contribute to open source projects, what it means to contribute and much more besides.

"},{"location":"contributing/#how-can-i-get-help","title":"How can I get help?","text":"

Do not open issues for general support questions as we want to keep GitHub issues for confirmed bug reports. Instead, open a discussion in the Q&A category. For more details on the support mechanisms for Autoware, refer to the Support guidelines.

Note

Issues created for questions or unconfirmed bugs will be moved to GitHub discussions by the maintainers.

"},{"location":"contributing/#how-can-i-contribute","title":"How can I contribute?","text":""},{"location":"contributing/#discussions","title":"Discussions","text":"

You can contribute to Autoware by facilitating and participating in discussions, such as:

  • Proposing a new feature to enhance Autoware
  • Joining an existing discussion and expressing your opinion
  • Organizing discussions for other contributors
  • Answering questions and supporting other contributors
"},{"location":"contributing/#working-groups","title":"Working groups","text":"

The various working groups within the Autoware Foundation are responsible for accomplishing goals set by the Technical Steering Committee. These working groups are open to everyone, and joining a particular working group will allow you to gain an understanding of current projects, see how those projects are managed within each group and to contribute to issues that will help progress a particular project.

To see the schedule for upcoming working group meetings, refer to the Autoware Foundation events calendar.

"},{"location":"contributing/#bug-reports","title":"Bug reports","text":"

Before you report a bug, please search the issue tracker for the appropriate repository. It is possible that someone has already reported the same issue and that workarounds exist. If you can't determine the appropriate repository, ask the maintainers for help by creating a new discussion in the Q&A category.

When reporting a bug, you should provide a minimal set of instructions to reproduce the issue. Doing so allows us to quickly confirm and focus on the right problem.

If you want to fix the bug by yourself that will be appreciated, but you should discuss possible approaches with the maintainers in the issue before submitting a pull request.

Creating an issue is straightforward, but if you happen to experience any problems then create a Q&A discussion to ask for help.

"},{"location":"contributing/#pull-requests","title":"Pull requests","text":"

You can submit pull requests for small changes such as:

  • Minor documentation updates
  • Fixing spelling mistakes
  • Fixing CI failures
  • Fixing warnings detected by compilers or analysis tools
  • Making small changes to a single package

If your pull request is a large change, the following process should be followed:

  1. Create a GitHub Discussion to propose the change. Doing so allows you to get feedback from other members and the Autoware maintainers and to ensure that the proposed change is in line with Autoware's design philosophy and current development plans. If you're not sure where to have that conversation, then create a new Q&A discussion.

  2. Create an issue following consensus in the discussions

  3. Create a pull request to implement the changes that references the Issue created in step 2

  4. Create documentation for the new addition (if relevant)

Examples of large changes include:

  • Adding a new feature to Autoware
  • Adding a new documentation page or section

For more information on how to submit a good pull request, have a read of the pull request guidelines and don't forget to review the required license notations!

"},{"location":"contributing/license/","title":"License","text":""},{"location":"contributing/license/#license","title":"License","text":"

Autoware is licensed under Apache License 2.0. Thus all contributions will be licensed as such as per clause 5 of the Apache License 2.0:

5. Submission of Contributions. Unless You explicitly state otherwise,\n   any Contribution intentionally submitted for inclusion in the Work\n   by You to the Licensor shall be under the terms and conditions of\n   this License, without any additional terms or conditions.\n   Notwithstanding the above, nothing herein shall supersede or modify\n   the terms of any separate license agreement you may have executed\n   with Licensor regarding such Contributions.\n

Here is an example copyright header to add to the top of a new file:

Copyright [first year of contribution] The Autoware Contributors\nSPDX-License-Identifier: Apache-2.0\n

We don't write copyright notations of each contributor here. Instead, we place them in the NOTICE file like the following.

This product includes code developed by [company name].\nCopyright [first year of contribution] [company name]\n

Let us know if your legal department has a special request for the copyright notation.

Currently, the old formats explained here are also acceptable. Those old formats can be replaced by this new format if the original authors agree. Note that we won't write their copyrights to the NOTICE file unless they agree with the new format.

References:

  • https://opensource.google/docs/copyright/#the-year
  • https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/
  • https://www.apache.org/licenses/LICENSE-2.0
  • https://www.apache.org/legal/src-headers.html
  • https://www.apache.org/foundation/license-faq.html
  • https://infra.apache.org/licensing-howto.html
"},{"location":"contributing/coding-guidelines/","title":"Coding guidelines","text":""},{"location":"contributing/coding-guidelines/#coding-guidelines","title":"Coding guidelines","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/#common-guidelines","title":"Common guidelines","text":"

Refer to the following links for now:

  • https://docs.ros.org/en/humble/Contributing/Developer-Guide.html

Also, keep in mind the following concepts.

  • Keep things consistent.
  • Automate where possible, using simple checks for formatting, syntax, etc.
  • When it comes to code reviews, don't spend too much time on trivial disagreements. For details see:
    • https://en.wikipedia.org/wiki/Law_of_triviality
    • https://steemit.com/programming/@emrebeyler/code-reviews-and-parkinson-s-law-of-triviality
"},{"location":"contributing/coding-guidelines/languages/cmake/","title":"CMake","text":""},{"location":"contributing/coding-guidelines/languages/cmake/#cmake","title":"CMake","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.ros.org/en/humble/Contributing/Code-Style-Language-Versions.html#cmake
"},{"location":"contributing/coding-guidelines/languages/cmake/#use-the-autoware_package-macro","title":"Use the autoware_package macro","text":"

To reduce duplications in CMakeLists.txt, there is the autoware_package() macro. See the README and use it in your package.

"},{"location":"contributing/coding-guidelines/languages/cpp/","title":"C++","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#c","title":"C++","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/languages/cpp/#references","title":"References","text":"

Follow the guidelines below if a rule is not defined on this page.

  1. https://docs.ros.org/en/humble/Contributing/Code-Style-Language-Versions.html
  2. https://www.autosar.org/fileadmin/standards/adaptive/22-11/AUTOSAR_RS_CPP14Guidelines.pdf
  3. https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines

Also, it is encouraged to apply Clang-Tidy to each file. For the usage, see Applying Clang-Tidy to ROS packages.

Note that not all rules are covered by Clang-Tidy.

"},{"location":"contributing/coding-guidelines/languages/cpp/#style-rules","title":"Style rules","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#include-header-files-in-the-defined-order-required-partially-automated","title":"Include header files in the defined order (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale","title":"Rationale","text":"
  • Due to indirect dependencies, the include system of C++ makes different behaviors if the header order is different.
  • To reduce unintended bugs, local header files should come first.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference","title":"Reference","text":"
  • https://llvm.org/docs/CodingStandards.html#include-style
"},{"location":"contributing/coding-guidelines/languages/cpp/#example","title":"Example","text":"

Include the headers in the following order:

  • Main module header
  • Local package headers
  • Other package headers
  • Message headers
  • Boost headers
  • C system headers
  • C++ system headers
// Compliant\n#include \"my_header.hpp\"\n\n#include \"my_package/foo.hpp\"\n\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n

If you use \"\" and <> properly, ClangFormat in pre-commit sorts headers automatically.

Do not define macros between #include lines because it prevents automatic sorting.

// Non-compliant\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#define EIGEN_MPL2_ONLY\n#include \"my_header.hpp\"\n#include \"my_package/foo.hpp\"\n\n#include <Eigen/Core>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n

Instead, define macros before #include lines.

// Compliant\n#define EIGEN_MPL2_ONLY\n\n#include \"my_header.hpp\"\n\n#include \"my_package/foo.hpp\"\n\n#include <Eigen/Core>\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n

If there are any reasons for defining macros at a specific position, write a comment before the macro.

// Compliant\n#include \"my_header.hpp\"\n\n#include \"my_package/foo.hpp\"\n\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n\n// For the foo bar reason, the FOO_MACRO must be defined here.\n#define FOO_MACRO\n#include <foo/bar.hpp>\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#use-lower-snake-case-for-function-names-required-partially-automated","title":"Use lower snake case for function names (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_1","title":"Rationale","text":"
  • It is consistent with the C++ standard library.
  • It is consistent with other programming languages such as Python and Rust.
"},{"location":"contributing/coding-guidelines/languages/cpp/#exception","title":"Exception","text":"
  • For member functions of classes inherited from external project classes such as Qt, follow that naming convention.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_1","title":"Reference","text":"
  • https://docs.ros.org/en/humble/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html#function-and-method-naming
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_1","title":"Example","text":"
void function_name()\n{\n}\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#use-upper-camel-case-for-enum-names-required-partially-automated","title":"Use upper camel case for enum names (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_2","title":"Rationale","text":"
  • It is consistent with ROS 2 core packages.
"},{"location":"contributing/coding-guidelines/languages/cpp/#exception_1","title":"Exception","text":"
  • Enums defined in the rosidl file can use other naming conventions.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_2","title":"Reference","text":"
  • http://wiki.ros.org/CppStyleGuide (Refer to \"15. Enumerations\")
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_2","title":"Example","text":"
enum class Color\n{\nRed, Green, Blue\n}\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#use-lower-snake-case-for-constant-names-required-partially-automated","title":"Use lower snake case for constant names (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_3","title":"Rationale","text":"
  • It is consistent with ROS 2 core packages.
  • It is consistent with std::numbers.
"},{"location":"contributing/coding-guidelines/languages/cpp/#exception_2","title":"Exception","text":"
  • Constants defined in the rosidl file can use other naming conventions.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_3","title":"Reference","text":"
  • https://en.cppreference.com/w/cpp/numeric/constants
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_3","title":"Example","text":"
constexpr double gravity = 9.80665;\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#count-acronyms-and-contractions-of-compound-words-as-one-word-required-partially-automated","title":"Count acronyms and contractions of compound words as one word (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_4","title":"Rationale","text":"
  • To clarify the boundaries of words when acronyms are consecutive.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_4","title":"Reference","text":"
  • https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_4","title":"Example","text":"
class RosApi;\nRosApi ros_api;\n
"},{"location":"contributing/coding-guidelines/languages/docker/","title":"Docker","text":""},{"location":"contributing/coding-guidelines/languages/docker/#docker","title":"Docker","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://github.com/hadolint/hadolint
"},{"location":"contributing/coding-guidelines/languages/github-actions/","title":"GitHub Actions","text":""},{"location":"contributing/coding-guidelines/languages/github-actions/#github-actions","title":"GitHub Actions","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.github.com/en/actions/guides
"},{"location":"contributing/coding-guidelines/languages/markdown/","title":"Markdown","text":""},{"location":"contributing/coding-guidelines/languages/markdown/#markdown","title":"Markdown","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.ros.org/en/foxy/Contributing/Code-Style-Language-Versions.html#markdown-restructured-text-docblocks
  • https://github.com/DavidAnson/markdownlint
"},{"location":"contributing/coding-guidelines/languages/package-xml/","title":"package.xml","text":""},{"location":"contributing/coding-guidelines/languages/package-xml/#packagexml","title":"package.xml","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://ros.org/reps/rep-0149.html
  • https://github.com/tier4/pre-commit-hooks-ros#prettier-package-xml
"},{"location":"contributing/coding-guidelines/languages/python/","title":"Python","text":""},{"location":"contributing/coding-guidelines/languages/python/#python","title":"Python","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.ros.org/en/foxy/Contributing/Code-Style-Language-Versions.html#python
  • https://github.com/psf/black
  • https://github.com/PyCQA/isort
"},{"location":"contributing/coding-guidelines/languages/shell-scripts/","title":"Shell scripts","text":""},{"location":"contributing/coding-guidelines/languages/shell-scripts/#shell-scripts","title":"Shell scripts","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://google.github.io/styleguide/shellguide.html
  • https://github.com/koalaman/shellcheck
  • https://github.com/mvdan/sh
"},{"location":"contributing/coding-guidelines/ros-nodes/class-design/","title":"Class design","text":""},{"location":"contributing/coding-guidelines/ros-nodes/class-design/#class-design","title":"Class design","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/","title":"Console logging","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#console-logging","title":"Console logging","text":"

ROS 2 logging is a powerful tool for understanding and debugging ROS nodes.

This page focuses on how to design console logging in Autoware and shows several practical examples. To comprehensively understand how ROS 2 logging works, refer to the logging documentation.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#logging-use-cases-in-autoware","title":"Logging use cases in Autoware","text":"
  • Developers debug code by seeing the console logs.
  • Vehicle operators take appropriate risk-avoiding actions depending on the console logs.
  • Log analysts analyze the console logs that are recorded in rosbag files.

To efficiently support these use cases, clean and highly visible logs are required. For that, several rules are defined below.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rules","title":"Rules","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#choose-appropriate-severity-levels-required-non-automated","title":"Choose appropriate severity levels (required, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale","title":"Rationale","text":"

It's confusing if severity levels are inappropriate as follows:

  • Useless messages are marked as FATAL.
  • Very important error messages are marked as INFO.
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example","title":"Example","text":"

Use the following criteria as a reference:

  • DEBUG: Use this level to show debug information for developers. Note that logs with this level is hidden by default.
  • INFO: Use this level to notify events (cyclic notifications during initialization, state changes, service responses, etc.) to operators.
  • WARN: Use this level when a node can continue working correctly, but unintended behaviors might happen.
    • For example, \"path optimization failed but the previous data can be used\", \"the localization score is low\", etc.
  • ERROR: Use this level when a node can't continue working correctly, and unintended behaviors would happen.
    • For example, \"path optimization failed and the path is empty\", \"the vehicle will trigger an emergency stop\", etc.
  • FATAL: Use this level when the entire system can't continue working correctly, and the system must be stopped.
    • For example, \"the vehicle control ECU doesn't respond\", \"the system storage crashed\", etc.
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#filter-out-unnecessary-logs-by-setting-logging-options-required-non-automated","title":"Filter out unnecessary logs by setting logging options (required, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale_1","title":"Rationale","text":"

Some third-party nodes such as drivers may not follow the Autoware's guidelines. If the logs are noisy, unnecessary logs should be filtered out.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example_1","title":"Example","text":"

Use the --log-level {level} option to change the minimum level of logs to be displayed:

<launch>\n<!-- This outputs only FATAL level logs. -->\n<node pkg=\"demo_nodes_cpp\" exec=\"talker\" ros_args=\"--log-level fatal\" />\n</launch>\n

If you want to disable only specific output targets, use the --disable-stdout-logs, --disable-rosout-logs, and/or --disable-external-lib-logs options:

<launch>\n<!-- This outputs to rosout and disk. -->\n<node pkg=\"demo_nodes_cpp\" exec=\"talker\" ros_args=\"--disable-stdout-logs\" />\n</launch>\n
<launch>\n<!-- This outputs to stdout. -->\n<node pkg=\"demo_nodes_cpp\" exec=\"talker\" ros_args=\"--disable-rosout-logs --disable-external-lib-logs\" />\n</launch>\n
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#use-throttled-logging-when-the-log-is-unnecessarily-shown-repeatedly-required-non-automated","title":"Use throttled logging when the log is unnecessarily shown repeatedly (required, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale_2","title":"Rationale","text":"

If tons of logs are shown on the console, people miss important message.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example_2","title":"Example","text":"

While waiting for some messages, throttled logs are usually enough. In such cases, wait about 5 seconds as a reference value.

// Compliant\nvoid FooNode::on_timer() {\nif (!current_pose_) {\nRCLCPP_ERROR_THROTTLE(get_logger(), *get_clock(), 5000, \"Waiting for current_pose_.\");\nreturn;\n}\n}\n\n// Non-compliant\nvoid FooNode::on_timer() {\nif (!current_pose_) {\nRCLCPP_ERROR(get_logger(), \"Waiting for current_pose_.\");\nreturn;\n}\n}\n
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#exception","title":"Exception","text":"

The following cases are acceptable even if it's not throttled.

  • The message is really worth displaying every time.
  • The message level is DEBUG.
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#do-not-depend-on-rclcppnode-in-core-library-classes-but-depend-only-on-rclcpplogginghpp-advisory-non-automated","title":"Do not depend on rclcpp::Node in core library classes but depend only on rclcpp/logging.hpp (advisory, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale_3","title":"Rationale","text":"

Core library classes, which contain reusable algorithms, may also be used for non-ROS platforms. When porting libraries to other platforms, fewer dependencies are preferred.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example_3","title":"Example","text":"
// Compliant\n#include <rclcpp/logging.hpp>\n\nclass FooCore {\npublic:\nexplicit FooCore(const rclcpp::Logger & logger) : logger_(logger) {}\n\nvoid process() {\nRCLCPP_INFO(logger_, \"message\");\n}\n\nprivate:\nrclcpp::Logger logger_;\n};\n\n// Compliant\n// Note that logs aren't published to `/rosout` if the logger name is different from the node name.\n#include <rclcpp/logging.hpp>\n\nclass FooCore {\nvoid process() {\nRCLCPP_INFO(rclcpp::get_logger(\"foo_core_logger\"), \"message\");\n}\n};\n\n\n// Non-compliant\n#include <rclcpp/node.hpp>\n\nclass FooCore {\npublic:\nexplicit FooCore(const rclcpp::NodeOptions & node_options) : node_(\"foo_core_node\", node_options) {}\n\nvoid process() {\nRCLCPP_INFO(node_.get_logger(), \"message\");\n}\n\nprivate:\nrclcpp::Node node_;\n};\n
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#tips","title":"Tips","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#use-rqt_console-to-filter-logs","title":"Use rqt_console to filter logs","text":"

To filter logs, using rqt_console is useful:

ros2 run rqt_console rqt_console\n

For more details, refer to ROS 2 Documentation.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#useful-marco-expressions","title":"Useful marco expressions","text":"

To debug program, sometimes you need to see which functions and lines of code are executed. In that case, you can use __FILE__, __LINE__ and __FUNCTION__ macro:

void FooNode::on_timer() {\nRCLCPP_DEBUG(get_logger(), \"file: %s, line: %s, function: %s\" __FILE__, __LINE__, __FUNCTION__);\n}\n

The example output is as follows:

[DEBUG] [1671720414.395456931] [foo]: file: /path/to/file.cpp, line: 100, function: on_timer

"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/","title":"Coordinate system","text":""},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#coordinate-system","title":"Coordinate system","text":""},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#overview","title":"Overview","text":"

The commonly used coordinate systems include the world coordinate system, the vehicle coordinate system, and the sensor coordinate system.

  • The world coordinate system is a fixed coordinate system that defines the physical space in the environment where the vehicle is located.
  • The vehicle coordinate system is the vehicle's own coordinate system, which defines the vehicle's position and orientation in the world coordinate system.
  • The sensor coordinate system is the sensor's own coordinate system, which is used to define the sensor's position and orientation in the vehicle coordinate system.
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#how-coordinates-are-used-in-autoware","title":"How coordinates are used in Autoware","text":"

In Autoware, coordinate systems are typically used to represent the position and movement of vehicles and obstacles in space. Coordinate systems are commonly used for path planning, perception and control, can help the vehicle decide how to avoid obstacles and to plan a safe and efficient path of travel.

  1. Transformation of sensor data

    In Autoware, each sensor has a unique coordinate system and their data is expressed in terms of the coordinates. In order to correlate the independent data between different sensors, we need to find the position relationship between each sensor and the vehicle body. Once the installation position of the sensor on the vehicle body is determined, it will remain fixed during running, so the offline calibration method can be used to determine the precise position of each sensor relative to the vehicle body.

  2. ROS TF2

    The TF2 system maintains a tree of coordinate transformations to represent the relationships between different coordinate systems. Each coordinate system is given a unique name and they are connected by coordinate transformations. How to use TF2, refer to the TF2 tutorial.

"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#tf-tree","title":"TF tree","text":"

In Autoware, a common coordinate system structure is shown below:

graph TD\n    /earth --> /map\n    /map --> /base_link\n    /base_link --> /imu\n    /base_link --> /lidar\n    /base_link --> /gnss\n    /base_link --> /radar\n    /base_link --> /camera_link\n    /camera_link --> /camera_optical_link
  • earth: earth coordinate system describe the position of any point on the earth in terms of geodetic longitude, latitude, and altitude. In Autoware, the earth frame is only used in the GnssInsPositionStamped message.
  • map: map coordinate system is used to represent the location of points on a local map. Geographical coordinate system are mapped into plane rectangular coordinate system using UTM or MGRS. The map frame`s axes point to the East, North, Up directions as explained in Coordinate Axes Conventions.
  • base_link: vehicle coordinate system, the origin of the coordinate system is the center of the rear axle of the vehicle.
  • imu, lidar, gnss, radar: these are sensor frames, transfer to vehicle coordinate system through mounting relationship.
  • camera_link: camera_link is ROS standard camera coordinate system .
  • camera_optical_link: camera_optical_link is image standard camera coordinate system.
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#estimating-the-base_link-frame-by-using-the-other-sensors","title":"Estimating the base_link frame by using the other sensors","text":"

Generally we don't have the localization sensors physically at the base_link frame. So various sensors localize with respect to their own frames, let's call it sensor frame.

We introduce a new frame naming convention: x_by_y:

x: estimated frame name\ny: localization method/source\n

We cannot directly get the sensor frame. Because we would need the EKF module to estimate the base_link frame first.

Without the EKF module the best we can do is to estimate Map[map] --> sensor_by_sensor --> base_link_by_sensor using this sensor.

"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#example-by-the-gnssins-sensor","title":"Example by the GNSS/INS sensor","text":"

For the integrated GNSS/INS we use the following frames:

flowchart LR\n    earth --> Map[map] --> gnss_ins_by_gnss_ins --> base_link_by_gnss_ins

The gnss_ins_by_gnss_ins frame is obtained by the coordinates from GNSS/INS sensor. The coordinates are converted to map frame using the gnss_poser node.

Finally gnss_ins_by_gnss_ins frame represents the position of the gnss_ins estimated by the gnss_ins sensor in the map.

Then by using the static transformation between gnss_ins and the base_link frame, we can obtain the base_link_by_gnss_ins frame. Which represents the base_link estimated by the gnss_ins sensor.

References:

  • https://www.ros.org/reps/rep-0105.html#earth
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#coordinate-axes-conventions","title":"Coordinate Axes Conventions","text":"

We are using East, North, Up (ENU) coordinate axes convention by default throughout the stack.

X+: East\nY+: North\nZ+: Up\n

The position, orientation, velocity, acceleration are all defined in the same axis convention.

Position by the GNSS/INS sensor is expected to be in earth frame.

Orientation, velocity, acceleration by the GNSS/INS sensor are expected to be in the sensor frame. Axes parallel to the map frame.

If roll, pitch, yaw is provided, they correspond to rotation around X, Y, Z axes respectively.

Rotation around:\nX+: roll\nY+: pitch\nZ+: yaw\n

References:

  • https://www.ros.org/reps/rep-0103.html#axis-orientation
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#how-they-can-be-created","title":"How they can be created","text":"

  1. Calibration of sensor

    The conversion relationship between every sensor coordinate system and base_link can be obtained through sensor calibration technology. How to calibrating your sensors refer to this link calibrating your sensors.

  2. Localization

    The relationship between the base_link coordinate system and the map coordinate system is determined by the position and orientation of the vehicle, and can be obtained from the vehicle localization result.

  3. Geo-referencing of map data

    The geo-referencing information can get the transformation relationship of earth coordinate system to local map coordinate system.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/","title":"Directory structure","text":""},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#directory-structure","title":"Directory structure","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#c-package","title":"C++ package","text":"
<package_name>\n\u251c\u2500 config\n\u2502   \u251c\u2500 foo_ros.param.yaml\n\u2502   \u2514\u2500 foo_non_ros.yaml\n\u251c\u2500 include\n\u2502   \u2514\u2500 <package_name>\n\u2502      \u2514\u2500 foo_public.hpp\n\u251c\u2500 launch\n\u2502   \u251c\u2500 foo.launch.xml\n\u2502   \u2514\u2500 foo.launch.py\n\u251c\u2500 src\n\u2502   \u251c\u2500 foo_node.cpp\n\u2502   \u251c\u2500 foo_node.hpp\n\u2502   \u2514\u2500 foo_private.hpp\n\u251c\u2500 test\n\u2502   \u2514\u2500 test_foo.cpp\n\u251c\u2500 package.xml\n\u2514\u2500 CMakeLists.txt\n
"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#config-directory","title":"config directory","text":"

Place configuration files such as node parameters.

For ROS parameters, use the extension .param.yaml. For non-ROS parameters, use the extension .yaml.

Rationale: Since ROS parameters files are type-sensitive, they should not be the target of some code formatters and linters. In order to distinguish the file type, we use different file extensions.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#include-directory","title":"include directory","text":"

Place header files exposed to other packages. Do not place files directly under the include directory, but place files under the directory with the package name. This directory is used for mostly library headers. Note that many headers do not need to be placed here. It is enough to place the headers under the src directory.

Reference: https://docs.ros.org/en/rolling/How-To-Guides/Ament-CMake-Documentation.html#adding-files-and-headers

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#launch-directory","title":"launch directory","text":"

Place launch files (.launch.xml and .launch.py).

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#src-directory","title":"src directory","text":"

Place source files and private header files.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#test-directory","title":"test directory","text":"

Place source files for testing.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#python-package","title":"Python package","text":"

T.B.D.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/","title":"Launch files","text":""},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#launch-files","title":"Launch files","text":""},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#overview","title":"Overview","text":"

Autoware use ROS2 launch system to startup the software. Please see the official documentation to get a basic understanding about ROS 2 Launch system if you are not familiar with it.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#guideline","title":"Guideline","text":""},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#the-organization-of-launch-files-in-autoware","title":"The organization of launch files in Autoware","text":"

Autoware mainly has two repositories related to launch file organization: the autoware.universe and the autoware_launch.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#autowareuniverse","title":"autoware.universe","text":"

the autoware.universe contains the code of the main Autoware modules, and its launch directory is responsible for launching the nodes of each module. Autoware software stack is organized based on the architecture, so you may find that we try to match the launch structure similar to the architecture (splitting of files, namespace). For example, the tier4_map_launch subdirectory corresponds to the map module, so do the other tier4_*_launch subdirectories.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#autoware_launch","title":"autoware_launch","text":"

The autoware_launch is a repository referring to autoware.universe. The mainly purpose of introducing this repository is to provide the general entrance to start the Autoware software stacks, i.e, calling the launch file of each module.

  • The autoware.launch.xml is the basic launch file for road driving scenarios.

    As can be seen from the content, the entire launch file is divided into several different modules, including Vehicle, System, Map, Sensing, Localization, Perception, Planning, Control, etc. By setting the launch_* argument equals to true or false , we can determine which modules to be loaded.

  • The logging_simulator.launch.xml is often used together with the recorded ROS bag to debug if the target module (e.g, Sensing, Localization or Perception) functions normally.
  • The planning_simulator.launch.xml is based on the Planning Simulator tool, mainly used for testing/validation of Planning module by simulating traffic rules, interactions with dynamic objects and control commands to the ego vehicle.
  • The e2e_simulator.launch.xml is the launcher for digital twin simulation environment.
graph LR\nA11[logging_simulator.launch.xml]-.->A10[autoware.launch.xml]\nA12[planning_simulator.launch.xml]-.->A10[autoware.launch.xml]\nA13[e2e_simulator.launch.xml]-.->A10[autoware.launch.xml]\n\nA10-->A21[tier4_map_component.launch.xml]\nA10-->A22[xxx.launch.py]\nA10-->A23[tier4_localization_component.launch.xml]\nA10-->A24[xxx.launch.xml]\nA10-->A25[tier4_sensing_component.launch.xml]\n\nA23-->A30[localization.launch.xml]\nA30-->A31[pose_estimator.launch.xml]\nA30-->A32[util.launch.xml]\nA30-->A33[pose_twist_fusion_filter.launch.xml]\nA30-->A34[xxx.launch.xml]\nA30-->A35[twist_estimator.launch.xml]\n\nA33-->A41[stop_filter.launch.xml]\nA33-->A42[ekf_localizer.launch.xml]\nA33-->A43[twist2accel.launch.xml]
"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#add-a-new-package-in-autoware","title":"Add a new package in Autoware","text":"

If a newly created package has executable node, we expect sample launch file and configuration within the package, just like the recommended structure shown in previous directory structure page.

In order to automatically load the newly added package when starting Autoware, you need to make some necessary changes to the corresponding launch file. For example, if using ICP instead of NDT as the pointcloud registration algorithm, you can modify the autoware.universe/launch/tier4_localization_launch/launch/pose_estimator/pose_estimator.launch.xml file to load the newly added ICP package.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#parameter-management","title":"Parameter management","text":"

Another purpose of introducing the autoware_launch repository is to facilitate the parameter management of Autoware. Thinking about this situation: if we want to integrate Autoware to a specific vehicle and modify parameters, we have to fork autoware.universe which also has a lot of code other than parameters and is frequently updated by developers. By intergrating these parameters in autoware_launch, we can customize the Autoware parameters just by forking autoware_launch repository. Taking the localization module as an examples:

  1. all the \u201claunch parameters\u201d for localization component is listed in the files under autoware_launch/autoware_launch/config/localization.
  2. the \"launch parameters\" file paths are set in the autoware_launch/autoware_launch/launch/components/tier4_localization_component.launch.xml file.
  3. in autoware.universe/launch/tier4_localization_launch/launch, the launch files loads the \u201claunch parameters\u201d if the argument is given in the parameter configuration file. You can still use the default parameters in each packages to launch tier4_localization_launch within autoware.universe.
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/","title":"Message guidelines","text":""},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#message-guidelines","title":"Message guidelines","text":""},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#format","title":"Format","text":"

All messages should follow ROS message description specification.

The accepted formats are:

  • .msg
  • .srv
  • .action
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#naming","title":"Naming","text":"

Under Construction

Use Array as a suffix when creating a plural type of a message. This suffix is commonly used in common_interfaces.

"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#default-units","title":"Default units","text":"

All the fields by default have the following units depending on their types:

type default unit distance meter (m) angle radians (rad) time second (s) speed m/s velocity m/s acceleration m/s\u00b2 angular vel. rad/s angular accel. rad/s\u00b2

If a field in a message has any of these default units, don't add any suffix or prefix denoting the type.

"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#non-default-units","title":"Non-default units","text":"

For non-default units, use following suffixes:

type non-default unit suffix distance nanometer _nm distance micrometer _um distance millimeter _mm distance kilometer _km angle degree (deg) _deg time nanosecond _ns time microsecond _us time millisecond _ms time minute _min time hour (h) _hour velocity km/h _kmph

If a unit that you'd like to use doesn't exist here, create an issue/PR to add it to this list.

"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#message-field-types","title":"Message field types","text":"

For list of types supported by the ROS interfaces see here.

Also copied here for convenience:

Message Field Type C++ equivalent bool bool byte uint8_t char char float32 float float64 double int8 int8_t uint8 uint8_t int16 int16_t uint16 uint16_t int32 int32_t uint32 uint32_t int64 int64_t uint64 uint64_t string std::string wstring std::u16string"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#arrays","title":"Arrays","text":"

For arrays, use unbounded dynamic array type.

Example:

int32[] unbounded_integer_array\n
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#enumerations","title":"Enumerations","text":"

ROS 2 interfaces don't support enumerations directly.

It is possible to define integers constants and assign them to a non-constant integer parameter.

Constants are written in CONSTANT_CASE.

Assign a different value to each element of a constant.

Example from shape_msgs/msg/SolidPrimitive.msg

uint8 BOX=1\nuint8 SPHERE=2\nuint8 CYLINDER=3\nuint8 CONE=4\nuint8 PRISM=5\n\n# The type of the shape\nuint8 type\n
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#comments","title":"Comments","text":"

On top of the message, briefly explain what the message contains and/or what it is used for. For an example, see sensor_msgs/msg/Imu.msg.

If necessary, add line comments before the fields that explain the context and/or meaning.

For simple fields like x, y, z, w you might not need to add comments.

Even though it is not strictly checked, try not to pass 100 characters in a line.

Example:

# Number of times the vehicle performed an emergency brake\nuint32 count_emergency_brake\n\n# Seconds passed since the last emergency brake\nuint64 duration\n
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#example-usages","title":"Example usages","text":"
  • Don't use unit suffixes for default types:
    • Bad: float32 path_length_m
    • Good: float32 path_length
  • Don't prefix the units:
    • Bad: float32 kmph_velocity_vehicle
    • Good: float32 velocity_vehicle_kmph
  • Use recommended suffixes if they are available in the table:
    • Bad: float32 velocity_vehicle_km_h
    • Good: float32 velocity_vehicle_kmph
"},{"location":"contributing/coding-guidelines/ros-nodes/parameters/","title":"Parameters","text":""},{"location":"contributing/coding-guidelines/ros-nodes/parameters/#parameters","title":"Parameters","text":"

The ROS packages in Autoware have ROS parameters. You need to customize the parameters depending on your applications. It is recommended not to set default values when declaring ROS parameters to avoid unintended behaviors due to accidental use of default values. Instead, set parameters from configuration files named *.param.yaml.

For understanding ROS 2 parameters, also check out the official documentation Understanding parameters.

"},{"location":"contributing/coding-guidelines/ros-nodes/parameters/#parameter-files","title":"Parameter files","text":"

Autoware has the following two types of parameter files for ROS packages:

  • Node parameter file
    • Node parameter files store the default parameters provided for each package in Autoware.
      • For example, the parameter of behavior_path_planner
    • All nodes in Autoware must have a parameter file if one or more parameters that can be customized by the user are defined.
    • For FOO_package, the parameter is expected to be stored in FOO_package/config.
    • The launch file for individual packages must load node parameter by default:
<launch>\n<arg name=\"foo_node_param_path\" default=\"$(find-pkg-share FOO_package)/config/foo_node.param.yaml\" />\n\n<node pkg=\"FOO_package\" exec=\"foo_node\">\n...\n    <param from=\"$(var foo_node_param_path)\" />\n</node>\n</launch>\n
  • Launch parameter file
    • Launch parameter files store the customized parameters for user's vehicle.
      • For example, the customized parameter of behavior_path_planner stored under autoware_launch
    • Launch parameter files are stored under autoware_launch.

All the parameter files should have the .param.yaml suffix so that the auto-format can be applied properly.

"},{"location":"contributing/coding-guidelines/ros-nodes/task-scheduling/","title":"Task scheduling","text":""},{"location":"contributing/coding-guidelines/ros-nodes/task-scheduling/#task-scheduling","title":"Task scheduling","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/","title":"Topic namespaces","text":""},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#topic-namespaces","title":"Topic namespaces","text":""},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#overview","title":"Overview","text":"

ROS allows topics, parameters and nodes to be namespaced which provides the following benefits:

  • Multiple instances of the same node type will not cause naming clashes.
  • Topics published by a node can be automatically namespaced with the node's namespace providing a meaningful and easily-visible connection.
  • Keeps from cluttering the root namespace.
  • Helps to maintain separation-of-concerns.

This page focuses on how to use namespaces in Autoware and shows some useful examples. For basic information on topic namespaces, refer to this tutorial.

"},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#how-topics-should-be-named-in-node","title":"How topics should be named in node","text":"

Autoware divides the node into the following functional categories, and adds the start namespace for the nodes according to the categories.

  • localization
  • perception
  • planning
  • control
  • sensing
  • vehicle
  • map
  • system

When a node is run in a namespace, all topics which that node publishes are given that same namespace. All nodes in the Autoware stack must support namespaces by avoiding practices such as publishing topics in the global namespace.

In general, topics should be namespaced based on the function of the node which produces them and not the node (or nodes) which consume them.

Classify topics as input or output topics based on they are subscribed or published by the node. In the node, input topic is named input/topic_name and output topic is named output/topic_name.

Configure the topic in the node's launch file. Take the joy_controller node as an example, in the following example, set the input and output topics and remap topics in the joy_controller.launch.xml file.

<launch>\n<arg name=\"input_joy\" default=\"/joy\"/>\n<arg name=\"input_odometry\" default=\"/localization/kinematic_state\"/>\n\n<arg name=\"output_control_command\" default=\"/external/$(var external_cmd_source)/joy/control_cmd\"/>\n<arg name=\"output_external_control_command\" default=\"/api/external/set/command/$(var external_cmd_source)/control\"/>\n<arg name=\"output_shift\" default=\"/api/external/set/command/$(var external_cmd_source)/shift\"/>\n<arg name=\"output_turn_signal\" default=\"/api/external/set/command/$(var external_cmd_source)/turn_signal\"/>\n<arg name=\"output_heartbeat\" default=\"/api/external/set/command/$(var external_cmd_source)/heartbeat\"/>\n<arg name=\"output_gate_mode\" default=\"/control/gate_mode_cmd\"/>\n<arg name=\"output_vehicle_engage\" default=\"/vehicle/engage\"/>\n\n<node pkg=\"joy_controller\" exec=\"joy_controller\" name=\"joy_controller\" output=\"screen\">\n<remap from=\"input/joy\" to=\"$(var input_joy)\"/>\n<remap from=\"input/odometry\" to=\"$(var input_odometry)\"/>\n\n<remap from=\"output/control_command\" to=\"$(var output_control_command)\"/>\n<remap from=\"output/external_control_command\" to=\"$(var output_external_control_command)\"/>\n<remap from=\"output/shift\" to=\"$(var output_shift)\"/>\n<remap from=\"output/turn_signal\" to=\"$(var output_turn_signal)\"/>\n<remap from=\"output/gate_mode\" to=\"$(var output_gate_mode)\"/>\n<remap from=\"output/heartbeat\" to=\"$(var output_heartbeat)\"/>\n<remap from=\"output/vehicle_engage\" to=\"$(var output_vehicle_engage)\"/>\n</node>\n</launch>\n
"},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#topic-names-in-the-code","title":"Topic names in the code","text":"

  1. Have ~ so that namespace in launch configuration is applied(should not start from root /).

  2. Have ~/input ~/output namespace before topic name used to communicate with other nodes.

    e.g., In node obstacle_avoidance_planner, using topic names of type ~/input/topic_name to subscribe to topics.

    objects_sub_ = create_subscription<PredictedObjects>(\n\"~/input/objects\", rclcpp::QoS{10},\nstd::bind(&ObstacleAvoidancePlanner::onObjects, this, std::placeholders::_1));\n

    e.g., In node obstacle_avoidance_planner, using topic names of type ~/output/topic_name to publish topic.

    traj_pub_ = create_publisher<Trajectory>(\"~/output/path\", 1);\n

  3. Visualization or debug purpose topics should have ~/debug/ namespace.

    e.g., In node obstacle_avoidance_planner, in order to debug or visualizing topics, using topic names of type ~/debug/topic_name to publish information.

    debug_markers_pub_ =\ncreate_publisher<visualization_msgs::msg::MarkerArray>(\"~/debug/marker\", durable_qos);\n\ndebug_msg_pub_ =\ncreate_publisher<tier4_debug_msgs::msg::StringStamped>(\"~/debug/calculation_time\", 1);\n

    The launch configured namespace will be add the topics before, so the topic names will be as following:

    /planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/marker /planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/calculation_time

  4. Rationale: we want to make topic names remapped and configurable from launch files.

"},{"location":"contributing/discussion-guidelines/","title":"Discussion guidelines","text":""},{"location":"contributing/discussion-guidelines/#discussion-guidelines","title":"Discussion guidelines","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.github.com/en/discussions/guides/best-practices-for-community-conversations-on-github
  • https://opensource.guide/how-to-contribute/#communicating-effectively
"},{"location":"contributing/documentation-guidelines/","title":"Documentation guidelines","text":""},{"location":"contributing/documentation-guidelines/#documentation-guidelines","title":"Documentation guidelines","text":""},{"location":"contributing/documentation-guidelines/#workflow","title":"Workflow","text":"

Contributions to Autoware's documentation are welcome, and the same principles described in the contribution guidelines should be followed. Small, limited changes can be made by forking this repository and submitting a pull request, but larger changes should be discussed with the community and Autoware maintainers via GitHub Discussion first.

Examples of small changes include:

  • Fixing spelling or grammatical mistakes
  • Fixing broken links
  • Making an addition to an existing, well-defined page, such as the Troubleshooting guide.

Examples of larger changes include:

  • Adding new pages with a large amount of detail, such as a tutorial
  • Re-organization of the existing documentation structure
"},{"location":"contributing/documentation-guidelines/#style-guide","title":"Style guide","text":"

You should refer to the Google developer documentation style guide as much as possible. Reading the Highlights page of that guide is recommended, but if not then the key points below should be noted.

  • Use standard American English spelling and punctuation.
  • Use sentence case for document titles and section headings.
  • Use descriptive link text.
  • Write short sentences that are easy to understand and translate.
"},{"location":"contributing/documentation-guidelines/#tips","title":"Tips","text":""},{"location":"contributing/documentation-guidelines/#how-to-preview-your-modification","title":"How to preview your modification","text":"

There are two ways to preview your modification on a documentation website.

"},{"location":"contributing/documentation-guidelines/#1-using-github-actions-workflow","title":"1. Using GitHub Actions workflow","text":"

Follow the steps below.

  1. Create a pull request to the repository.
  2. Add the deploy-docs label from the sidebar (See below figure).
  3. Wait for a couple of minutes, and the github-actions bot will notify the URL for the pull request's preview.

"},{"location":"contributing/documentation-guidelines/#2-running-an-mkdocs-server-in-your-local-environment","title":"2. Running an MkDocs server in your local environment","text":"

Instead of creating a PR, you can use the mkdocs command to build Autoware's documentation websites on your local computer. Assuming that you are using Ubuntu OS, run the following to install the required libraries.

python3 -m pip install -U $(curl -fsSL https://raw.githubusercontent.com/autowarefoundation/autoware-github-actions/main/deploy-docs/mkdocs-requirements.txt)\n

Then, run mkdocs serve on your documentation directory.

cd /PATH/TO/YOUR-autoware-documentation\nmkdocs serve\n

It will launch the MkDocs server. Access http://127.0.0.1:8000/ to see the preview of the website.

"},{"location":"contributing/pull-request-guidelines/","title":"Pull request guidelines","text":""},{"location":"contributing/pull-request-guidelines/#pull-request-guidelines","title":"Pull request guidelines","text":""},{"location":"contributing/pull-request-guidelines/#general-pull-request-workflow","title":"General pull request workflow","text":"

Autoware uses the fork-and-pull model. For more details about the model, refer to GitHub Docs.

The following is a general example of the pull request workflow based on the fork-and-pull model. Use this workflow as a reference when you contribute to Autoware.

  1. Create an issue.
    • Discuss the approaches to the issue with maintainers.
    • Confirm the support guidelines before creating an issue.
    • Follow the discussion guidelines when you discuss with other contributors.
  2. Create a fork repository. (for the first time only)
  3. Write code in your fork repository according to the approach agreed upon in the issue.
    • Write the tests and documentation as appropriate.
    • Follow the coding guidelines guidelines when you write code.
    • Follow the Testing guidelines guidelines when you write tests.
    • Follow the Documentation guidelines guidelines when you write documentation.
    • Follow the commit guidelines when you commit your changes.
  4. Test the code.
    • It is recommended that you summarize the test results, because you will need to explain the test results in the later review process.
    • If you are not sure what tests should be done, discuss them with maintainers.
  5. Create a pull request.
    • Follow the pull request rules when you create a pull request.
  6. Wait for the pull request to be reviewed.
    • The reviewers will review your code following the review guidelines.
      • Not only the reviewers, but also the author is encouraged to understand the review guidelines.
    • If CI checks have failed, fix the errors.
  7. Address the review comments pointed out by the reviewers.
    • If you don't understand the meaning of a review comment, ask the reviewers until you understand it.
      • Fixing without understanding the reason is not recommended because the author should be responsible for the final content of their own pull request.
    • If you don't agree with a review comment, ask the reviewers for a rational reason.
      • The reviewers are obligated to make the author understand the meanings of each comment.
    • After you have done with the review comments, re-request a review to the reviewers and back to 6.
    • If there are no more new review comments, the reviewers will approve the pull request and proceed to 8.
  8. Merge the pull request.
    • Anyone with write access can merge the pull request if there is no special request from maintainers.
      • The author is encouraged to merge the pull request to feel responsible for their own pull request.
      • If the author does not have write access, ask the reviewers or maintainers.
"},{"location":"contributing/pull-request-guidelines/#pull-request-rules","title":"Pull request rules","text":""},{"location":"contributing/pull-request-guidelines/#use-an-appropriate-pull-request-template-required-non-automated","title":"Use an appropriate pull request template (required, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale","title":"Rationale","text":"
  • The unified style of descriptions by templates can make reviews efficient.
"},{"location":"contributing/pull-request-guidelines/#example","title":"Example","text":"

There are two types of templates. Select one based on the following condition.

  1. Standard change:
    • Complexity:
      • New features or significant updates.
      • Requires deeper understanding of the codebase.
    • Impact:
      • Affects multiple parts of the system.
      • Basically includes minor features, bug fixes and performance improvement.
      • Needs testing before merging.
  2. Small change:
    • Complexity:
      • Documentation, simple refactoring, or style adjustments.
      • Easy to understand and review.
    • Impact:
      • Minimal effect on the system.
      • Quicker merge with less testing needed.
"},{"location":"contributing/pull-request-guidelines/#steps-to-use-an-appropriate-pull-request-template","title":"Steps to use an appropriate pull request template","text":"
  1. Select the appropriate template, as shown in this video.
  2. Read the selected template carefully and fill the required content.
  3. Check the checkboxes during a review.
    • There are pre-review checklist and post-review checklist for the author.
"},{"location":"contributing/pull-request-guidelines/#set-appropriate-reviewers-after-creating-a-pull-request-required-partially-automated","title":"Set appropriate reviewers after creating a pull request (required, partially automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_1","title":"Rationale","text":"
  • Pull requests must be reviewed by appropriate reviewers to keep the quality of the codebase.
"},{"location":"contributing/pull-request-guidelines/#example_1","title":"Example","text":"
  • For most ROS packages, reviewers will be automatically assigned based on the maintainer information in package.xml.
  • If no reviewer is assigned automatically, assign reviewers manually following the instructions in GitHub Docs.
    • You can find the reviewers by seeing the .github/CODEOWNERS file of the repository.
  • If you are not sure the appropriate reviewers, ask @autoware-maintainers.
  • If you have no rights to assign reviewers, mention reviewers instead.
"},{"location":"contributing/pull-request-guidelines/#apply-conventional-commits-to-the-pull-request-title-required-automated","title":"Apply Conventional Commits to the pull request title (required, automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_2","title":"Rationale","text":"
  • Conventional Commits can generate categorized changelogs, for example using git-cliff.
"},{"location":"contributing/pull-request-guidelines/#example_2","title":"Example","text":"
feat(trajectory_follower): add an awesome feature\n

Note

You have to start the description part (here add an awesome feature) with a lowercase.

If your change breaks some interfaces, use the ! (breaking changes) mark as follows:

feat(trajectory_follower)!: remove package\nfeat(trajectory_follower)!: change parameter names\nfeat(planning)!: change topic names\nfeat(autoware_utils)!: change function names\n

For the repositories that contain code (most repositories), use the definition of conventional-commit-types for the type.

For documentation repositories such as autoware-documentation, use the following definition:

  • feat
    • Add new pages.
    • Add contents to the existing pages.
  • fix
    • Fix the contents in the existing pages.
  • refactor
    • Move contents to different pages.
  • docs
    • Update documentation for the documentation repository itself.
  • build
    • Update the settings of the documentation site builder.
  • ! (breaking changes)
    • Remove pages.
    • Change the URL of pages.

perf and test are generally unused. Other types have the same meaning as the code repositories.

"},{"location":"contributing/pull-request-guidelines/#add-the-related-component-names-to-the-scope-of-conventional-commits-advisory-non-automated","title":"Add the related component names to the scope of Conventional Commits (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_3","title":"Rationale","text":"
  • It helps contributors find pull requests that are relevant to them.
  • It makes the changelog clearer.
"},{"location":"contributing/pull-request-guidelines/#example_3","title":"Example","text":"

For ROS packages, adding the package name or component name is good.

feat(trajectory_follower): add an awesome feature\nrefactor(planning, control): use common utils\n
"},{"location":"contributing/pull-request-guidelines/#keep-a-pull-request-small-advisory-non-automated","title":"Keep a pull request small (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_4","title":"Rationale","text":"
  • Small pull requests are easy to understand for reviewers.
  • Small pull requests are easy to revert for maintainers.
"},{"location":"contributing/pull-request-guidelines/#exception","title":"Exception","text":"

It is acceptable if it is agreed with maintainers that there is no other way but to submit a big pull request.

"},{"location":"contributing/pull-request-guidelines/#example_4","title":"Example","text":"
  • Avoid developing two features in one pull request.
  • Avoid mixing different types (feat, fix, refactor, etc.) of changes in the same commit.
"},{"location":"contributing/pull-request-guidelines/#remind-reviewers-if-there-is-no-response-for-more-than-a-week-advisory-non-automated","title":"Remind reviewers if there is no response for more than a week (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_5","title":"Rationale","text":"
  • It is the author's responsibility to care about their own pull request until it is merged.
"},{"location":"contributing/pull-request-guidelines/#example_5","title":"Example","text":"
@{some-of-developers} Would it be possible for you to review this PR?\n@autoware-maintainers friendly ping.\n
"},{"location":"contributing/pull-request-guidelines/ci-checks/","title":"CI checks","text":""},{"location":"contributing/pull-request-guidelines/ci-checks/#ci-checks","title":"CI checks","text":"

Autoware has several checks for a pull request. The results are shown at the bottom of the pull request page as below.

If the \u274c mark is shown, click the Details button and investigate the failure reason.

If the Required mark is shown, you cannot merge the pull request unless you resolve the error. If not, it is optional, but preferably it should be fixed.

The following sections explain about common CI checks in Autoware. Note that some repositories may have different settings.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#dco","title":"DCO","text":"

The Developer Certificate of Origin (DCO) is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project.

This workflow checks whether the pull request fulfills DCO. You need to confirm the required items and commit with git commit -s.

For more information, refer to the GitHub App page.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#semantic-pull-request","title":"semantic-pull-request","text":"

This workflow checks whether the pull request follows Conventional Commits.

For the detailed rules, see the pull request rules.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#pre-commit","title":"pre-commit","text":"

pre-commit is a tool to run formatters or linters when you commit.

This workflow checks whether the pull request has no error with pre-commit.

In the workflow pre-commit.ci - pr is enabled in the repository, it will automatically fix errors by pre-commit.ci as many as possible. If there are some errors remain, fix them manually.

You can run pre-commit in your local environment by the following command:

pre-commit run -a\n

Or you can install pre-commit to the repository and automatically run it before committing:

pre-commit install\n

Since it is difficult to detect errors with no false positives, some jobs are split into another config file and marked as optional. To check them, use the --config option:

pre-commit run -a --config .pre-commit-config-optional.yaml\n
"},{"location":"contributing/pull-request-guidelines/ci-checks/#spell-check-differential","title":"spell-check-differential","text":"

This workflow detects spelling mistakes using CSpell with our dictionary file. You can submit pull requests to tier4/autoware-spell-check-dict to update the dictionary.

Since it is difficult to detect errors with no false positives, it is an optional workflow, but it is preferable to remove spelling mistakes as many as possible.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#build-and-test-differential","title":"build-and-test-differential","text":"

This workflow checks colcon build and colcon test for the pull request. To make the CI faster, it doesn't check all packages but only modified packages and the dependencies.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#build-and-test-differential-self-hosted","title":"build-and-test-differential-self-hosted","text":"

This workflow is the ARM64 version of build-and-test-differential. You need to add the ARM64 label to run this workflow.

For reference information, since ARM machines are not supported by GitHub-hosted runners, we use self-hosted runners prepared by the AWF. For the details about self-hosted runners, refer to GitHub Docs.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#deploy-docs","title":"deploy-docs","text":"

This workflow deploys the preview documentation site for the pull request. You need to add the deploy-docs label to run this workflow.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/","title":"Commit guidelines","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#commit-guidelines","title":"Commit guidelines","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#branch-rules","title":"Branch rules","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#start-branch-names-with-the-corresponding-issue-numbers-advisory-non-automated","title":"Start branch names with the corresponding issue numbers (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale","title":"Rationale","text":"
  • Developers can quickly find the corresponding issues.
  • It is helpful for tools.
  • It is consistent with GitHub's default behavior.
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#exception","title":"Exception","text":"

If there are no corresponding issues, you can ignore this rule.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example","title":"Example","text":"
123-add-feature\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#reference","title":"Reference","text":"
  • GitHub Docs
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#use-dash-case-for-the-separator-of-branch-names-advisory-non-automated","title":"Use dash-case for the separator of branch names (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale_1","title":"Rationale","text":"
  • It is consistent with GitHub's default behavior.
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example_1","title":"Example","text":"
123-add-feature\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#reference_1","title":"Reference","text":"
  • GitHub Docs
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#make-branch-names-descriptive-advisory-non-automated","title":"Make branch names descriptive (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale_2","title":"Rationale","text":"
  • It can avoid conflicts of names.
  • Developers can understand the purpose of the branch.
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#exception_1","title":"Exception","text":"

If you have already submitted a pull request, you do not have to change the branch name because you need to re-create a pull request, which is noisy and a waste of time. Be careful from the next time.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example_2","title":"Example","text":"

Usually it is good to start with a verb.

123-fix-memory-leak-of-trajectory-follower\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#commit-rules","title":"Commit rules","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#sign-off-your-commits-required-automated","title":"Sign-off your commits (required, automated)","text":"

Developers must certify that they wrote or otherwise have the right to submit the code they are contributing to the project.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale_3","title":"Rationale","text":"

If not, it will lead to complex license problems.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example_3","title":"Example","text":"
git commit -s\n
feat: add a feature\n\nSigned-off-by: Autoware <autoware@example.com>\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#reference_2","title":"Reference","text":"
  • GitHub Apps - DCO
"},{"location":"contributing/pull-request-guidelines/review-guidelines/","title":"Review guidelines","text":""},{"location":"contributing/pull-request-guidelines/review-guidelines/#review-guidelines","title":"Review guidelines","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://google.github.io/eng-practices/review/
  • https://docs.gitlab.com/ee/development/code_review.html
  • https://www.swarmia.com/blog/a-complete-guide-to-code-reviews/
  • https://rewind.com/blog/best-practices-for-reviewing-pull-requests-in-github/
"},{"location":"contributing/pull-request-guidelines/review-tips/","title":"Review tips","text":""},{"location":"contributing/pull-request-guidelines/review-tips/#review-tips","title":"Review tips","text":""},{"location":"contributing/pull-request-guidelines/review-tips/#toggle-annotations-or-review-comments-in-the-diff-view","title":"Toggle annotations or review comments in the diff view","text":"

There might be some annotations or review comments in the diff view during your review.

To toggle annotations, press the A key.

Before:

After:

To toggle review comments, press the I key.

For other keyboard shortcuts, refer to GitHub Docs.

"},{"location":"contributing/pull-request-guidelines/review-tips/#view-code-in-the-web-based-visual-studio-code","title":"View code in the web-based Visual Studio Code","text":"

You can open Visual Studio Code from your browser to view code in a rich UI. To use it, press the . key on any repository or pull request.

For more detailed usage, refer to github/dev.

"},{"location":"contributing/pull-request-guidelines/review-tips/#check-out-the-branch-of-a-pull-request-quickly","title":"Check out the branch of a pull request quickly","text":"

If you want to check out the branch of a pull request, it's generally troublesome with the fork-and-pull model.

# Copy the user name and the fork URL.\ngit remote add {user-name} {fork-url}\ngit checkout {user-name}/{branch-name}\ngit remote rm {user-name} # To clean up\n

Instead, you can use GitHub CLI to simplify the steps, just run gh pr checkout {pr-number}.

You can copy the command from the top right of the pull request page.

"},{"location":"contributing/testing-guidelines/","title":"Testing guidelines","text":""},{"location":"contributing/testing-guidelines/#testing-guidelines","title":"Testing guidelines","text":""},{"location":"contributing/testing-guidelines/#unit-testing","title":"Unit testing","text":"

Unit testing is a software testing method that tests individual units of source code to determine whether they satisfy the specification.

For details, see the Unit testing guidelines.

"},{"location":"contributing/testing-guidelines/#integration-testing","title":"Integration testing","text":"

Integration testing combines and tests the individual software modules as a group, and is done after unit testing.

While performing integration testing, the following subtypes of tests are written:

  1. Fault injection testing
  2. Back-to-back comparison between a model and code
  3. Requirements-based testing
  4. Anomaly detection during integration testing
  5. Random input testing

For details, see the Integration testing guidelines.

"},{"location":"contributing/testing-guidelines/integration-testing/","title":"Integration testing","text":""},{"location":"contributing/testing-guidelines/integration-testing/#integration-testing","title":"Integration testing","text":"

An integration test is defined as the phase in software testing where individual software modules are combined and tested as a group. Integration tests occur after unit tests, and before validation tests.

The input to an integration test is a set of independent modules that have been unit tested. The set of modules is tested against the defined integration test plan, and the output is a set of properly integrated software modules that is ready for system testing.

"},{"location":"contributing/testing-guidelines/integration-testing/#value-of-integration-testing","title":"Value of integration testing","text":"

Integration tests determine if independently developed software modules work correctly when the modules are connected to each other. In ROS 2, the software modules are called nodes. Testing a single node is a special type of integration test that is commonly referred to as component testing.

Integration tests help to find the following types of errors:

  • Incompatible interactions between nodes, such as non-matching topics, different message types, or incompatible QoS settings.
  • Edge cases that were not touched by unit testing, such as a critical timing issue, network communication delays, disk I/O failures, and other such problems that can occur in production environments.
  • Issues that can occur while the system is under high CPU/memory load, such as malloc failures. This can be tested using tools like stress and udpreplay to test the performance of nodes with real data.

With ROS 2, it is possible to program complex autonomous-driving applications with a large number of nodes. Therefore, a lot of effort has been made to provide an integration-test framework that helps developers test the interaction of ROS 2 nodes.

"},{"location":"contributing/testing-guidelines/integration-testing/#integration-test-framework","title":"Integration-test framework","text":"

A typical integration-test framework has three parts:

  1. A series of executables with arguments that work together and generate outputs.
  2. A series of expected outputs that should match the output of the executables.
  3. A launcher that starts the tests, compares the outputs to the expected outputs, and determines if the test passes.

In Autoware, we use the launch_testing framework.

"},{"location":"contributing/testing-guidelines/integration-testing/#smoke-tests","title":"Smoke tests","text":"

Autoware has a dedicated API for smoke testing. To use this framework, in package.xml add:

<test_depend>autoware_testing</test_depend>\n

And in CMakeLists.txt add:

if(BUILD_TESTING)\nfind_package(autoware_testing REQUIRED)\nadd_smoke_test(${PROJECT_NAME} ${NODE_NAME})\nendif()\n

Doing so adds smoke tests that ensure that a node can be:

  1. Launched with a default parameter file.
  2. Terminated with a standard SIGTERM signal.

For the full API documentation, refer to the package design page.

Note

This API is not suitable for all smoke test cases. It cannot be used when a specific file location (eg: for a map) is required to be passed to the node, or if some preparation needs to be conducted before node launch. In such cases use the manual solution from the component test section below.

"},{"location":"contributing/testing-guidelines/integration-testing/#integration-test-with-a-single-node-component-test","title":"Integration test with a single node: component test","text":"

The simplest scenario is a single node. In this case, the integration test is commonly referred to as a component test.

To add a component test to an existing node, you can follow the example of the lanelet2_map_loader in the map_loader package (added in this PR).

In package.xml, add:

<test_depend>ros_testing</test_depend>\n

In CMakeLists.txt, add or modify the BUILD_TESTING section:

if(BUILD_TESTING)\nadd_ros_test(\ntest/lanelet2_map_loader_launch.test.py\nTIMEOUT \"30\"\n)\ninstall(DIRECTORY\ntest/data/\nDESTINATION share/${PROJECT_NAME}/test/data/\n)\nendif()\n

In addition to the command add_ros_test, we also install any data that is required by the test using the install command.

Note

  • The TIMEOUT argument is given in seconds; see the add_ros_test.cmake file for details.
  • The add_ros_test command will run the test in a unique ROS_DOMAIN_ID which avoids interference between tests running in parallel.

To create a test, either read the launch_testing quick-start example, or follow the steps below.

Taking test/lanelet2_map_loader_launch.test.py as an example, first dependencies are imported:

import os\nimport unittest\n\nfrom ament_index_python import get_package_share_directory\nimport launch\nfrom launch import LaunchDescription\nfrom launch_ros.actions import Node\nimport launch_testing\nimport pytest\n

Then a launch description is created to launch the node under test. Note that the test_map.osm file path is found and passed to the node, something that cannot be done with the smoke testing API:

@pytest.mark.launch_test\ndef generate_test_description():\n\n    lanelet2_map_path = os.path.join(\n        get_package_share_directory(\"map_loader\"), \"test/data/test_map.osm\"\n    )\n\n    lanelet2_map_loader = Node(\n        package=\"map_loader\",\n        executable=\"lanelet2_map_loader\",\n        parameters=[{\"lanelet2_map_path\": lanelet2_map_path}],\n    )\n\n    context = {}\n\n    return (\n        LaunchDescription(\n            [\n                lanelet2_map_loader,\n                # Start test after 1s - gives time for the map_loader to finish initialization\n                launch.actions.TimerAction(\n                    period=1.0, actions=[launch_testing.actions.ReadyToTest()]\n                ),\n            ]\n        ),\n        context,\n    )\n

Note

  • Since the node need time to process the input lanelet2 map, we use a TimerAction to delay the start of the test by 1s.
  • In the example above, the context is empty but it can be used to pass objects to the test cases.
  • You can find an example of using the context in the ROS 2 context_launch_test.py test example.

Finally, a test is executed after the node executable has been shut down (post_shutdown_test). Here we ensure that the node was launched without error and exited cleanly.

@launch_testing.post_shutdown_test()\nclass TestProcessOutput(unittest.TestCase):\n    def test_exit_code(self, proc_info):\n        # Check that process exits with code 0: no error\n        launch_testing.asserts.assertExitCodes(proc_info)\n
"},{"location":"contributing/testing-guidelines/integration-testing/#running-the-test","title":"Running the test","text":"

Continuing the example from above, first build your package:

colcon build --packages-up-to map_loader\nsource install/setup.bash\n

Then either execute the component test manually:

ros2 test src/universe/autoware.universe/map/map_loader/test/lanelet2_map_loader_launch.test.py\n

Or as part of testing the entire package:

colcon test --packages-select map_loader\n

Verify that the test is executed; e.g.

$ colcon test-result --all --verbose\n...\nbuild/map_loader/test_results/map_loader/test_lanelet2_map_loader_launch.test.py.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\n
"},{"location":"contributing/testing-guidelines/integration-testing/#next-steps","title":"Next steps","text":"

The simple test described in Integration test with a single node: component test can be extended in numerous directions, such as testing a node's output.

"},{"location":"contributing/testing-guidelines/integration-testing/#testing-the-output-of-a-node","title":"Testing the output of a node","text":"

To test while the node is running, create an active test by adding a subclass of Python's unittest.TestCase to *launch.test.py. Some boilerplate code is required to access output by creating a node and a subscription to a particular topic, e.g.

import unittest\n\nclass TestRunningDataPublisher(unittest.TestCase):\n\n    @classmethod\n    def setUpClass(cls):\n        cls.context = Context()\n        rclpy.init(context=cls.context)\n        cls.node = rclpy.create_node(\"test_node\", context=cls.context)\n\n    @classmethod\n    def tearDownClass(cls):\n        rclpy.shutdown(context=cls.context)\n\n    def setUp(self):\n        self.msgs = []\n        sub = self.node.create_subscription(\n            msg_type=my_msg_type,\n            topic=\"/info_test\",\n            callback=self._msg_received\n        )\n        self.addCleanup(self.node.destroy_subscription, sub)\n\n    def _msg_received(self, msg):\n        # Callback for ROS 2 subscriber used in the test\n        self.msgs.append(msg)\n\n    def get_message(self):\n        startlen = len(self.msgs)\n\n        executor = rclpy.executors.SingleThreadedExecutor(context=self.context)\n        executor.add_node(self.node)\n\n        try:\n            # Try up to 60 s to receive messages\n            end_time = time.time() + 60.0\n            while time.time() < end_time:\n                executor.spin_once(timeout_sec=0.1)\n                if startlen != len(self.msgs):\n                    break\n\n            self.assertNotEqual(startlen, len(self.msgs))\n            return self.msgs[-1]\n        finally:\n            executor.remove_node(self.node)\n\n    def test_message_content():\n        msg = self.get_message()\n        self.assertEqual(msg, \"Hello, world\")\n
"},{"location":"contributing/testing-guidelines/integration-testing/#references","title":"References","text":"
  • colcon is used to build and run tests.
  • launch testing launches nodes and runs tests.
  • Testing guidelines describes the different types of tests performed in Autoware and links to the corresponding guidelines.
"},{"location":"contributing/testing-guidelines/unit-testing/","title":"Unit testing","text":""},{"location":"contributing/testing-guidelines/unit-testing/#unit-testing","title":"Unit testing","text":"

Unit testing is the first phase of testing and is used to validate units of source code such as classes and functions. Typically, a unit of code is tested by validating its output for various inputs. Unit testing helps ensure that the code behaves as intended and prevents accidental changes of behavior.

Autoware uses the ament_cmake framework to build and run tests. The same framework is also used to analyze the test results.

ament_cmake provides several convenience functions to make it easy to register tests in a CMake-based package and to ensure that JUnit-compatible result files are generated. It currently supports a few different testing frameworks like pytest, gtest, and gmock.

In order to prevent tests running in parallel from interfering with each other when publishing and subscribing to ROS topics, it is recommended to use commands from ament_cmake_ros to run tests in isolation.

See below for an example of using ament_add_ros_isolated_gtest with colcon test. All other tests follow a similar pattern.

"},{"location":"contributing/testing-guidelines/unit-testing/#create-a-unit-test-with-gtest","title":"Create a unit test with gtest","text":"

In my_cool_pkg/test, create the gtest code file test_my_cool_pkg.cpp:

#include \"gtest/gtest.h\"\n#include \"my_cool_pkg/my_cool_pkg.hpp\"\nTEST(TestMyCoolPkg, TestHello) {\nEXPECT_EQ(my_cool_pkg::print_hello(), 0);\n}\n

In package.xml, add the following line:

<test_depend>ament_cmake_ros</test_depend>\n

Next add an entry under BUILD_TESTING in the CMakeLists.txt to compile the test source files:

if(BUILD_TESTING)\n\nament_add_ros_isolated_gtest(test_my_cool_pkg test/test_my_cool_pkg.cpp)\ntarget_link_libraries(test_my_cool_pkg ${PROJECT_NAME})\n...\nendif()\n

This automatically links the test with the default main function provided by gtest. The code under test is usually in a different CMake target (${PROJECT_NAME} in the example) and its shared object for linking needs to be added.

To register a new gtest item, wrap the test code with the macro TEST (). TEST () is a predefined macro that helps generate the final test code, and also registers a gtest item to be available for execution. The test case name should be in CamelCase, since gtest inserts an underscore between the fixture name and the class case name when creating the test executable.

gtest/gtest.h also contains predefined macros of gtest like ASSERT_TRUE(condition), ASSERT_FALSE(condition), ASSERT_EQ(val1,val2), ASSERT_STREQ(str1,str2), EXPECT_EQ(), etc. ASSERT_* will abort the test if the condition is not satisfied, while EXPECT_* will mark the test as failed but continue on to the next test condition.

Info

More information about gtest and its features can be found in the gtest repo.

In the demo CMakeLists.txt, ament_add_ros_isolated_gtest is a predefined macro in ament_cmake_ros that helps simplify adding gtest code. Details can be viewed in ament_add_gtest.cmake.

"},{"location":"contributing/testing-guidelines/unit-testing/#build-test","title":"Build test","text":"

By default, all necessary test files (ELF, CTestTestfile.cmake, etc.) are compiled by colcon:

cd ~/workspace/\ncolcon build --packages-select my_cool_pkg\n

Test files are generated under ~/workspace/build/my_cool_pkg.

"},{"location":"contributing/testing-guidelines/unit-testing/#run-test","title":"Run test","text":"

To run all tests for a specific package, call:

$ colcon test --packages-select my_cool_pkg\n\nStarting >>> my_cool_pkg\nFinished <<< my_cool_pkg [7.80s]\n\nSummary: 1 package finished [9.27s]\n

The test command output contains a brief report of all the test results.

To get job-wise information of all executed tests, call:

$ colcon test-result --all\n\nbuild/my_cool_pkg/test_results/my_cool_pkg/copyright.xunit.xml: 8 tests, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/cppcheck.xunit.xml: 6 tests, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/lint_cmake.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/my_cool_pkg_exe_integration_test.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml: 1 test, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/xmllint.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\n\nSummary: 18 tests, 0 errors, 0 failures, 0 skipped\n

Look in the ~/workspace/log/test_<date>/<package_name> directory for all the raw test commands, std_out, and std_err. There is also the ~/workspace/log/latest_*/ directory containing symbolic links to the most recent package-level build and test output.

To print the tests' details while the tests are being run, use the --event-handlers console_cohesion+ option to print the details directly to the console:

$ colcon test --event-handlers console_cohesion+ --packages-select my_cool_pkg\n\n...\ntest 1\n    Start 1: test_my_cool_pkg\n\n1: Test command: /usr/bin/python3 \"-u\" \"~/workspace/install/share/ament_cmake_test/cmake/run_test.py\" \"~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml\" \"--package-name\" \"my_cool_pkg\" \"--output-file\" \"~/workspace/build/my_cool_pkg/ament_cmake_gtest/test_my_cool_pkg.txt\" \"--command\" \"~/workspace/build/my_cool_pkg/test_my_cool_pkg\" \"--gtest_output=xml:~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml\"\n1: Test timeout computed to be: 60\n1: -- run_test.py: invoking following command in '~/workspace/src/my_cool_pkg':\n1:  - ~/workspace/build/my_cool_pkg/test_my_cool_pkg --gtest_output=xml:~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml\n1: [==========] Running 1 test from 1 test case.\n1: [----------] Global test environment set-up.\n1: [----------] 1 test from test_my_cool_pkg\n1: [ RUN      ] test_my_cool_pkg.test_hello\n1: Hello World\n1: [       OK ] test_my_cool_pkg.test_hello (0 ms)\n1: [----------] 1 test from test_my_cool_pkg (0 ms total)\n1:\n1: [----------] Global test environment tear-down\n1: [==========] 1 test from 1 test case ran. (0 ms total)\n1: [  PASSED  ] 1 test.\n1: -- run_test.py: return code 0\n1: -- run_test.py: inject classname prefix into gtest result file '~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml'\n1: -- run_test.py: verify result file '~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml'\n1/5 Test #1: test_my_cool_pkg ...................   Passed    0.09 sec\n\n...\n\n100% tests passed, 0 tests failed out of 5\n\nLabel Time Summary:\ncopyright     =   0.49 sec*proc (1 test)\ncppcheck      =   0.20 sec*proc (1 test)\ngtest         =   0.05 sec*proc (1 test)\nlint_cmake    =   0.18 sec*proc (1 test)\nlinter        =   1.34 sec*proc (4 tests)\nxmllint       =   0.47 sec*proc (1 test)\n\nTotal Test time (real) =   7.91 sec\n...\n
"},{"location":"contributing/testing-guidelines/unit-testing/#code-coverage","title":"Code coverage","text":"

Loosely described, a code coverage metric is a measure of how much of the program code has been exercised (covered) during testing.

In the Autoware repositories, Codecov is used to automatically calculate coverage of any open pull request.

More details about the code coverage metrics can be found in the Codecov documentation.

"},{"location":"datasets/","title":"Datasets","text":""},{"location":"datasets/#datasets","title":"Datasets","text":"

Autoware partners provide datasets for testing and development. These datasets are available for download here.

"},{"location":"datasets/#bus-odd-operational-design-domain-datasets","title":"Bus-ODD (Operational Design Domain) datasets","text":""},{"location":"datasets/#leo-drive-isuzu-sensor-data","title":"Leo Drive - ISUZU sensor data","text":"

This dataset contains data from the Isuzu bus used in the Bus ODD project.

The data contains data from following sensors:

  • 1 x VLP16
  • 2 x VLP32C
  • 1 x Applanix POS LV 120 GNSS/INS
  • 3 x Lucid Vision Triton 5.4MP cameras (left, right, front)
  • Vehicle status report

It also contains /tf topic for static transformations between sensors.

"},{"location":"datasets/#required-message-types","title":"Required message types","text":"

The GNSS data is available in sensor_msgs/msg/NavSatFix message type.

But also the Applanix raw messages are also included in applanix_msgs/msg/NavigationPerformanceGsof50 and applanix_msgs/msg/NavigationSolutionGsof49 message types. In order to be able to play back these messages, you need to build and source the applanix_msgs package.

# Create a workspace and clone the repository\nmkdir -p ~/applanix_ws/src && cd \"$_\"\ngit clone https://github.com/autowarefoundation/applanix.git\ncd ..\n\n# Build the workspace\ncolcon build --symlink-install --packages-select applanix_msgs\n\n# Source the workspace\nsource ~/applanix_ws/install/setup.bash\n\n# Now you can play back the messages\n

Also make sure to source Autoware Universe workspace too.

"},{"location":"datasets/#download-instructions","title":"Download instructions","text":"
# Install awscli\n$ sudo apt update && sudo apt install awscli -y\n\n# This will download the entire dataset to the current directory.\n# (About 10.9GB of data)\n$ aws s3 sync s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/ ./2022-08-22_leo_drive_isuzu_bags  --no-sign-request\n\n# Optionally,\n# If you instead want to download a single bag file, you can get a list of the available files with following:\n$ aws s3 ls s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/ --no-sign-request\n   PRE all-sensors-bag1_compressed/\n   PRE all-sensors-bag2_compressed/\n   PRE all-sensors-bag3_compressed/\n   PRE all-sensors-bag4_compressed/\n   PRE all-sensors-bag5_compressed/\n   PRE all-sensors-bag6_compressed/\n   PRE driving_20_kmh_2022_06_10-16_01_55_compressed/\n   PRE driving_30_kmh_2022_06_10-15_47_42_compressed/\n\n# Then you can download a single bag file with the following:\naws s3 sync s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/all-sensors-bag1_compressed/ ./all-sensors-bag1_compressed  --no-sign-request\n
"},{"location":"datasets/#autocoreai-lidar-ros-2-bag-file-and-pcap","title":"AutoCore.ai - lidar ROS 2 bag file and pcap","text":"

This dataset contains pcap files and ros2 bag files from Ouster OS1-64 Lidar. The pcap file and ros2 bag file is recorded in the same time with slight difference in duration.

Click here to download (~553MB)

Reference Issue

"},{"location":"design/","title":"Autoware's Design","text":""},{"location":"design/#autowares-design","title":"Autoware's Design","text":""},{"location":"design/#architecture","title":"Architecture","text":"

Core and Universe.

Autoware provides the runtimes and technology components by open-source software. The runtimes are based on the Robot Operating System (ROS). The technology components are provided by contributors, which include, but are not limited to:

  • Sensing
    • Camera Component
    • LiDAR Component
    • RADAR Component
    • GNSS Component
  • Computing
    • Localization Component
    • Perception Component
    • Planning Component
    • Control Component
    • Logging Component
    • System Monitoring Component
  • Actuation
    • DBW Component
  • Tools
    • Simulator Component
    • Mapping Component
    • Remote Component
    • ML Component
    • Annotation Component
    • Calibration Component
"},{"location":"design/#concern-assumption-and-limitation","title":"Concern, Assumption, and Limitation","text":"

The downside of the microautonomy architecture is that the computational performance of end applications is sacrificed due to its data path overhead attributed to functional modularity. In other words, the trade-off characteristic of the microautonomy architecture exists between computational performance and functional modularity. This trade-off problem can be solved technically by introducing real-time capability. This is because autonomous driving systems are not really designed to be real-fast, that is, low-latency computing is nice-to-have but not must-have. The must-have feature for autonomous driving systems is that the latency of computing is predictable, that is, the systems are real-time. As a whole, we can compromise computational performance to an extent that is predictable enough to meet the given timing constraints of autonomous driving systems, often referred to as deadlines of computation.

"},{"location":"design/#design","title":"Design","text":"

Warning

Under Construction

"},{"location":"design/#autoware-concepts","title":"Autoware concepts","text":"

The Autoware concepts page describes the design philosophy of Autoware. Readers (service providers and all Autoware users) will learn the basic concepts underlying Autoware development, such as microautonomy and the Core/Universe architecture.

"},{"location":"design/#autoware-architecture","title":"Autoware architecture","text":"

The Autoware architecture page describes an overview of each module that makes up Autoware. Readers (all Autoware users) will gain a high-level picture of how each module that composes Autoware works.

"},{"location":"design/#autoware-interfaces","title":"Autoware interfaces","text":"

The Autoware interfaces page describes in detail the interface of each module that makes up Autoware. Readers (intermediate developers) will learn how to add new functionality to Autoware and how to integrate their own modules with Autoware.

"},{"location":"design/#configuration-management","title":"Configuration management","text":""},{"location":"design/#conclusion","title":"Conclusion","text":""},{"location":"design/autoware-architecture/","title":"Architecture overview","text":""},{"location":"design/autoware-architecture/#architecture-overview","title":"Architecture overview","text":"

This page describes the architecture of Autoware.

"},{"location":"design/autoware-architecture/#introduction","title":"Introduction","text":"

The current Autoware is defined to be a layered architecture that clarifies each module's role and simplifies the interface between them. By doing so:

  • Autoware's internal processing becomes more transparent.
  • Collaborative development is made easier because of the reduced interdependency between modules.
  • Users can easily replace an existing module (e.g. localization) with their own software component by simply wrapping their software to fit in with Autoware's interface.

Note that the initial focus of this architecture design was solely on driving capability, and so the following features were left as future work:

  • Fail safe
  • Human Machine Interface
  • Real-time processing
  • Redundant system
  • State monitoring system
"},{"location":"design/autoware-architecture/#high-level-architecture-design","title":"High-level architecture design","text":"

Autoware's architecture consists of the following six stacks. Each linked page contains a more detailed set of requirements and use cases specific to that stack:

  • Sensing design
  • Map design
  • Localization design
  • Perception design
  • Planning design
  • Control design
  • Vehicle Interface design
"},{"location":"design/autoware-architecture/#node-diagram","title":"Node diagram","text":"

A diagram showing Autoware's nodes in the default configuration can be found on the Node diagram page. Detailed documents for each node are available in the Autoware Universe docs.

Note that Autoware configurations are scalable / selectable and will vary depending on the environment and required use cases.

"},{"location":"design/autoware-architecture/#references","title":"References","text":"
  • The architecture presentation given to the AWF Technical Steering Committee, March 2020
"},{"location":"design/autoware-architecture/control/","title":"Control component design","text":""},{"location":"design/autoware-architecture/control/#control-component-design","title":"Control component design","text":""},{"location":"design/autoware-architecture/control/#abstract","title":"Abstract","text":"

This document presents the design concept of the Control Component. The content is as follows:

  • Autoware Control Design
    • Outlining the policy for Autoware's control, which deals with only general information for autonomous driving systems and provides generic control commands to the vehicle.
  • Vehicle Adaptation Design
    • Describing the policy for vehicle adaptation, which utilizes adapter mechanisms to standardize the characteristics of the vehicle's drive system and integrate it with Autoware.
  • Control Feature Design
    • Demonstrating the features provided by Autoware's control.
    • Presenting the approach towards the functions installed in the vehicle such as ABS.
"},{"location":"design/autoware-architecture/control/#autoware-control-design","title":"Autoware Control Design","text":"

The Control Component generates the control signal to which the Vehicle Component subscribes. The generated control signals are computed based on the reference trajectories from the Planning Component.

The Control Component consists of two modules. The trajectory_follower module generates a vehicle control command to follow the reference trajectory received from the planning module. The command includes, for example, the desired steering angle and target speed. The vehicle_command_gate is responsible for filtering the control command to prevent abnormal values and then sending it to the vehicle. This gate also allows switching between multiple sources such as the MRM (minimal risk maneuver) module or some remote control module, in addition to the trajectory follower.

The Autoware control system is designed as a platform for automated driving systems that can be compatible with a diverse range of vehicles.

The control process in Autoware uses general information (such as target acceleration and deceleration) and no vehicle-specific information (such as brake pressure) is used. Hence it can be adjusted independently of the vehicle's drive interface enabling easy integration or performance tuning.

Furthermore, significant differences that affect vehicle motion constraints, such as two-wheel steering or four-wheel steering, are addressed by switching the control vehicle model, achieving control specialized for each characteristic.

Autoware's control module outputs the necessary information to control the vehicle as a substitute for a human driver. For example, the control command from the control module looks like the following:

- Target steering angle\n- Target steering torque\n- Target speed\n- Target acceleration\n

Note that vehicle-specific values such as pedal positions and low-level information such as individual wheel rotation speeds are excluded from the command.

"},{"location":"design/autoware-architecture/control/#vehicle-adaptation-design","title":"Vehicle Adaptation Design","text":""},{"location":"design/autoware-architecture/control/#vehicle-interface-adapter","title":"Vehicle interface adapter","text":"

Autoware is designed to be an autonomous driving platform able to accommodate vehicles with various drivetrain types.

This is an explanation of how Autoware handles the standardization of systems with different vehicle drivetrains. The interfaces for vehicle drivetrains are diverse, including steering angle, steering angular velocity, steering torque, speed, accel/brake pedals, and brake pressure. To accommodate these differences, Autoware adds an adapter module between the control component and the vehicle interface. This module performs the conversion between the proprietary message types used by the vehicle (such as brake pressure) and the generic types used by Autoware (such as desired acceleration). By providing this conversion information, the differences in vehicle drivetrain can be accommodated.

If the information is not known in advance, an automatic calibration tool can be used. Calibration will occur within limited degrees of freedom, generating the information necessary for the drivetrain conversion automatically.

This configuration is summarized in the following diagram.

"},{"location":"design/autoware-architecture/control/#examples-of-several-vehicle-interfaces","title":"Examples of several vehicle interfaces","text":"

This is an example of the several drivetrain types in the vehicle interface.

Vehicle Lateral interface Longitudinal interface Note Lexus Steering angle Accel/brake pedal position Acceleration lookup table conversion for longitudinal JPN TAXI Steering angle Accel/brake pedal position Acceleration lookup table conversion for longitudinal GSM8 Steering EPS voltage Acceleration motor voltage, Deceleration brake hydraulic pressure lookup table and PID conversion for lateral and longitudinal YMC Golfcart Steering angle Velocity Logiees yaw rate Velocity F1 TENTH Steering angle Motor RPM interface code"},{"location":"design/autoware-architecture/control/#control-feature-design","title":"Control Feature Design","text":"

The following lists the features provided by Autoware's Control/Vehicle component, as well as the conditions and assumptions required to utilize them effectively.

The proper operation of the ODD is limited by factors such as whether the functions are enabled, delay time, calibration accuracy and degradation rate, and sensor accuracy.

Feature Description\u3000 Requirements/Assumptions Note \u3000Limitation for now Lateral Control Control the drivetrain system related to lateral vehicle motion Trying to increase the number of vehicle types that can be supported in the future. Only front-steering type is supported. Longitudinal Control Control the drivetrain system related to longitudinal vehicle motion Slope Compensation Supports precise vehicle motion control on slopes Gradient information can be obtained from maps or sensors attached to the chassis If gradient information is not available, the gradient is estimated from the vehicle's pitch angle. Delay Compensation Controls the drivetrain system appropriately in the presence of time delays The drivetrain delay information is provided in advance If there is no delay information, the drivetrain delay is estimated automatically (automatic calibration). However, the effect of delay cannot be completely eliminated, especially in scenarios with sudden changes in speed. Only fixed delay times can be set for longitudinal and lateral drivetrain systems separately. It does not accommodate different delay times for the accelerator and brake. Drivetrain IF Conversion (Lateral Control) Converts the drivetrain-specific information of the vehicle into the drivetrain information used by Autoware (e.g., target steering angular velocity \u2192 steering torque) The conversion information is provided in advance If there is no conversion information, the conversion map is estimated automatically (automatic calibration). The degree of freedom for conversion is limited (2D lookup table + PID FB). Drivetrain IF Conversion (Longitudinal Control) Converts the drivetrain-specific information of the vehicle into the drivetrain information used by Autoware (e.g., target acceleration \u2192 accelerator/brake pedal value) The conversion information is provided in advance If there is no conversion information, the conversion map is estimated automatically (automatic calibration). The degree of freedom for conversion is limited (2D lookup table + PID FB). Automatic Calibration Automatically estimates and applies values such as drivetrain IF conversion map and delay time. The drivetrain status can be obtained (must) Anomaly Detection Notifies when there is a discrepancy in the calibration or unexpected drivetrain behavior The drivetrain status can be obtained (must) Steering Zero Point Correction Corrects the midpoint of the steering to achieve appropriate steering control The drivetrain status can be obtained (must) Steering Deadzone Correction Corrects the deadzone of the steering to achieve appropriate steering control The steering deadzone parameter is provided in advance If the parameter is unknown, the deadzone parameter is estimated from driving information Not available now Steering Deadzone Estimation Dynamically estimates the steering deadzone from driving data Not available now Weight Compensation Performs appropriate vehicle control according to weight Weight information can be obtained from sensors If there is no weight sensor, estimate the weight from driving information. Currently not available Weight Estimation Dynamically estimates weight from driving data Currently not available

The list above does not cover wheel control systems such as ABS commonly used in vehicles. Regarding these features, the following considerations are taken into account.

"},{"location":"design/autoware-architecture/control/#integration-with-vehicle-side-functions","title":"Integration with vehicle-side functions","text":"

ABS (Anti-lock Brake System) and ESC (Electric Stability Control) are two functions that may be pre-installed on a vehicle, directly impacting its controllability. The control modules of Autoware assume that both ABS and ESC are installed on the vehicle and their absence may cause unreliable controls depending on the target ODD. For example, with low-velocity driving in a controlled environment, these functions are not necessary.

Also, note that this statement does not negate the development of ABS functionality in autonomous driving systems.

"},{"location":"design/autoware-architecture/control/#autoware-capabilities-and-vehicle-requirements","title":"Autoware Capabilities and Vehicle Requirements","text":"

As an alternative to human driving, autonomous driving systems essentially aim to handle tasks that humans can perform. This includes not only controlling the steering wheel, accel, and brake, but also automatically detecting issues such as poor brake response or a misaligned steering angle. However, this is a trade-off, as better vehicle performance will lead to superior system behavior, ultimately affecting the design of ODD.

On the other hand, for tasks that are not typically anticipated or cannot be handled by a human driver, processing in the vehicle ECU is expected. Examples of such scenarios include cases where the brake response is clearly delayed or when the vehicle rotates due to a single-side tire slipping. These tasks are typically handled by ABS or ESC.

"},{"location":"design/autoware-architecture/localization/","title":"Index","text":"

LOCALIZATION COMPONENT DESIGN DOC

"},{"location":"design/autoware-architecture/localization/#abstract","title":"Abstract","text":""},{"location":"design/autoware-architecture/localization/#1-requirements","title":"1. Requirements","text":"

Localization aims to estimate vehicle pose, velocity, and acceleration.

Goals:

  • Propose a system that can estimate vehicle pose, velocity, and acceleration for as long as possible.
  • Propose a system that can diagnose the stability of estimation and send a warning message to the error-monitoring system if the estimation result is unreliable.
  • Design a vehicle localization function that can work with various sensor configurations.

Non-goals:

  • This design document does not aim to develop a localization system that
    • is infallible in all environments
    • works outside of the pre-defined ODD (Operational Design Domain)
    • has better performance than is required for autonomous driving
"},{"location":"design/autoware-architecture/localization/#2-sensor-configuration-examples","title":"2. Sensor Configuration Examples","text":"

This section shows example sensor configurations and their expected performances. Each sensor has its own advantages and disadvantages, but overall performance can be improved by fusing multiple sensors.

"},{"location":"design/autoware-architecture/localization/#3d-lidar-pointcloud-map","title":"3D-LiDAR + PointCloud Map","text":""},{"location":"design/autoware-architecture/localization/#expected-situation","title":"Expected situation","text":"
  • The vehicle is located in a structure-rich environment, such as an urban area
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable","title":"Situations that can make the system unstable","text":"
  • The vehicle is placed in a structure-less environment, such as a rural landscape, highway, or tunnel
  • Environmental changes have occurred since the map was created, such as snow cover or the construction/destruction of buildings.
  • Surrounding objects are occluded
  • The car is surrounded by objects undetectable by LiDAR, e.g., glass windows, reflections, or absorption (dark objects)
  • The environment contains laser beams at the same frequency as the car's LiDAR sensor(s)
"},{"location":"design/autoware-architecture/localization/#functionality","title":"Functionality","text":"
  • The system can estimate the vehicle location on the point cloud map with the error of ~10cm.
  • The system is operable at night.
"},{"location":"design/autoware-architecture/localization/#3d-lidar-or-camera-vector-map","title":"3D-LiDAR or Camera + Vector Map","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_1","title":"Expected situation","text":"
  • Road with clear white lines and loose curvatures, such as a highway or an ordinary local road.
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_1","title":"Situations that can make the system unstable","text":"
  • White lines are scratchy or covered by rain or snow
  • Tight curvature such as intersections
  • Large reflection change of the road surface caused by rain or paint
"},{"location":"design/autoware-architecture/localization/#functionalities","title":"Functionalities","text":"
  • Correct vehicle positions along the lateral direction.
  • Pose correction along the longitudinal can be inaccurate, but can be resolved by fusing with GNSS.
"},{"location":"design/autoware-architecture/localization/#gnss","title":"GNSS","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_2","title":"Expected situation","text":"
  • The vehicle is placed in an open environment with few to no surrounding objects, such as a rural landscape.
"},{"location":"design/autoware-architecture/localization/#situation-that-can-make-the-system-unstable","title":"Situation that can make the system unstable","text":"
  • GNSS signals are blocked by surrounding objects, e.g., tunnels or buildings.
"},{"location":"design/autoware-architecture/localization/#functionality_1","title":"Functionality","text":"
  • The system can estimate vehicle position in the world coordinate within an error of ~10m.
  • With a RKT-GNSS (Real Time Kinematic Global Navigation Satellite System) attached, the accuracy can be improved to ~10cm.
  • A system with this configuration can work without environment maps (both point cloud and vector map types).
"},{"location":"design/autoware-architecture/localization/#camera-visual-odometry-visual-slam","title":"Camera (Visual Odometry, Visual SLAM)","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_3","title":"Expected situation","text":"
  • The vehicle is placed in an environment with rich visual features, such as an urban area.
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_2","title":"Situations that can make the system unstable","text":"
  • The vehicle is placed in a texture-less environment.
  • The vehicle is surrounded by other objects.
  • The camera observes significant illumination changes, such as those caused by sunshine, headlights from other vehicles or when approaching the exit of a tunnel.
  • The vehicle is placed in a dark environment.
"},{"location":"design/autoware-architecture/localization/#functionality_2","title":"Functionality","text":"
  • The system can estimate odometry by tracking visual features.
"},{"location":"design/autoware-architecture/localization/#wheel-speed-sensor","title":"Wheel speed sensor","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_4","title":"Expected situation","text":"
  • The vehicle is running on a flat and smooth road.
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_3","title":"Situations that can make the system unstable","text":"
  • The vehicle is running on a slippery or bumpy road, which can cause incorrect observations of wheel speed.
"},{"location":"design/autoware-architecture/localization/#functionality_3","title":"Functionality","text":"
  • The system can acquire the vehicle velocity and estimate distance traveled.
"},{"location":"design/autoware-architecture/localization/#imu","title":"IMU","text":""},{"location":"design/autoware-architecture/localization/#expected-environments","title":"Expected environments","text":"
  • Flat, smooth roads
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_4","title":"Situations that can make the system unstable","text":"
  • IMUs have a bias1 that is dependent on the surrounding temperature, and can cause incorrect sensor observation or odometry drift.
"},{"location":"design/autoware-architecture/localization/#functionality_4","title":"Functionality","text":"
  • The system can observe acceleration and angular velocity.
  • By integrating these observations, the system can estimate the local pose change and realize dead-reckoning
"},{"location":"design/autoware-architecture/localization/#geomagnetic-sensor","title":"Geomagnetic sensor","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_5","title":"Expected situation","text":"
  • The vehicle is placed in an environment with low magnetic noise
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_5","title":"Situations that can make the system unstable","text":"
  • The vehicle is placed in an environment with high magnetic noise, such as one containing buildings or structures with reinforced steel or other materials that generate electromagnetic waves.
"},{"location":"design/autoware-architecture/localization/#functionality_5","title":"Functionality","text":"
  • The system can estimate the vehicle's direction in the world coordinate system.
"},{"location":"design/autoware-architecture/localization/#magnetic-markers","title":"Magnetic markers","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_6","title":"Expected situation","text":"
  • The car is placed in an environment with magnetic markers installed.
"},{"location":"design/autoware-architecture/localization/#situations-where-the-system-becomes-unstable","title":"Situations where the system becomes unstable","text":"
  • The markers are not maintained.
"},{"location":"design/autoware-architecture/localization/#functionality_6","title":"Functionality","text":"
  • Vehicle location can be obtained on the world coordinate by detecting the magnetic markers.
  • The system can work even if the road is covered with snow.
"},{"location":"design/autoware-architecture/localization/#3-requirements","title":"3. Requirements","text":"
  • By implementing different modules, various sensor configurations and algorithms can be used.
  • The localization system can start pose estimation from an ambiguous initial location.
  • The system can produce a reliable initial location estimation.
  • The system can manage the state of the initial location estimation (uninitialized, initializable, or non-initializable) and can report to the error monitor.
"},{"location":"design/autoware-architecture/localization/#4-architecture","title":"4. Architecture","text":""},{"location":"design/autoware-architecture/localization/#abstract_1","title":"Abstract","text":"

Two architectures are defined, \"Required\" and \"Recommended\". However, the \"Required\" architecture only contains the inputs and outputs necessary to accept various localization algorithms. To improve the reusability of each module, the required components are defined in the \"Recommended\" architecture section along with a more detailed explanation.

"},{"location":"design/autoware-architecture/localization/#required-architecture","title":"Required Architecture","text":""},{"location":"design/autoware-architecture/localization/#input","title":"Input","text":"
  • Sensor message
    • e.g., LiDAR, camera, GNSS, IMU, CAN Bus, etc.
    • Data types should be ROS primitives for reusability
  • Map data
    • e.g., point cloud map, lanelet2 map, feature map, etc.
    • The map format should be chosen based on use case and sensor configuration
    • Note that map data is not required for some specific cases (e.g., GNSS-only localization)
  • tf, static_tf
    • map frame
    • base_link frame
"},{"location":"design/autoware-architecture/localization/#output","title":"Output","text":"
  • Pose with covariance stamped
    • Vehicle pose, covariance, and timestamp on the map coordinate
    • 50Hz~ frequency (depending on the requirements of the Planning and Control components)
  • Twist with covariance stamped
    • Vehicle velocity, covariance, and timestamp on the base_link coordinate
    • 50Hz~ frequency
  • Accel with covariance stamped
    • Acceleration, covariance, and timestamp on the base_link coordinate
    • 50Hz~ frequency
  • Diagnostics
    • Diagnostics information that indicates if the localization module works properly
  • tf
    • tf of map to base_link
"},{"location":"design/autoware-architecture/localization/#recommended-architecture","title":"Recommended Architecture","text":""},{"location":"design/autoware-architecture/localization/#pose-estimator","title":"Pose Estimator","text":"
  • Estimates the vehicle pose on the map coordinate by matching external sensor observation to the map
  • Provides the obtained pose and its covariance to PoseTwistFusionFilter
"},{"location":"design/autoware-architecture/localization/#twist-accel-estimator","title":"Twist-Accel Estimator","text":"
  • Produces the vehicle velocity, angular velocity, acceleration, angular acceleration, and their covariances
    • It is possible to create a single module for both twist and acceleration or to create two separate modules - the choice of architecture is up to the developer
  • The twist estimator produces velocity and angular velocity from internal sensor observation
  • The accel estimator produces acceleration and angular acceleration from internal sensor observations
"},{"location":"design/autoware-architecture/localization/#kinematics-fusion-filter","title":"Kinematics Fusion Filter","text":"
  • Produces the likeliest pose, velocity, acceleration, and their covariances, computed by fusing two kinds of information:
    • The pose obtained from the pose estimator.
    • The velocity and acceleration obtained from the twist-accel estimator
  • Produces tf of map to base_link according to the pose estimation result
"},{"location":"design/autoware-architecture/localization/#localization-diagnostics","title":"Localization Diagnostics","text":"
  • Monitors and guarantees the stability and reliability of pose estimation by fusing information obtained from multiple localization modules
  • Reports error status to the error monitor
"},{"location":"design/autoware-architecture/localization/#tf-tree","title":"TF tree","text":"frame meaning earth ECEF (Earth Centered Earth Fixed\uff09 map Origin of the map coordinate (ex. MGRS origin) viewer User-defined frame for rviz base_link Reference pose of the ego-vehicle (projection of the rear-axle center onto the ground surface) sensor Reference pose of each sensor

Developers can optionally add other frames such as odom or base_footprint as long as the tf structure above is maintained.

"},{"location":"design/autoware-architecture/localization/#the-localization-modules-ideal-functionality","title":"The localization module's ideal functionality","text":"
  • The localization module should provide pose, velocity, and acceleration for control, planning, and perception.
  • Latency and stagger should be sufficiently small or adjustable such that the estimated values can be used for control within the ODD (Operational Design Domain).
  • The localization module should produce the pose on a fixed coordinate frame.
  • Sensors should be independent of each other so that they can be easily replaced.
  • The localization module should provide a status indicating whether or not the autonomous vehicle can operate with the self-contained function or map information.
  • Tools or manuals should describe how to set proper parameters for the localization module
  • Valid calibration parameters should be provided to align different frame or pose coordinates and sensor timestamps.
"},{"location":"design/autoware-architecture/localization/#kpi","title":"KPI","text":"

To maintain sufficient pose estimation performance for safe operation, the following metrics are considered:

  • Safety
    • The distance traveled within the ODD where pose estimation met the required accuracy, divided by the overall distance traveled within the ODD, as a percentage.
    • The anomaly detection rate for situations where the localization module cannot estimate pose within the ODD
    • The accuracy of detecting when the vehicle goes outside of the ODD, as a percentage.
  • Computational load
  • Latency
"},{"location":"design/autoware-architecture/localization/#5-interface-and-data-structure","title":"5. Interface and Data Structure","text":""},{"location":"design/autoware-architecture/localization/#6-concerns-assumptions-and-limitations","title":"6. Concerns, Assumptions, and Limitations","text":""},{"location":"design/autoware-architecture/localization/#prerequisites-of-sensors-and-inputs","title":"Prerequisites of sensors and inputs","text":""},{"location":"design/autoware-architecture/localization/#sensor-prerequisites","title":"Sensor prerequisites","text":"
  • Input data is not defective.
    • Internal sensor observation such as IMU continuously keeps the proper frequency.
  • Input data has correct and exact time stamps.
    • Estimated poses can be inaccurate or unstable if the timestamps are not exact.
  • Sensors are correctly mounted with exact positioning and accessible from TF.
    • If the sensor positions are inaccurate, estimation results may be incorrect or unstable.
    • A sensor calibration framework is required to properly obtain the sensor positions.
"},{"location":"design/autoware-architecture/localization/#map-prerequisites","title":"Map prerequisites","text":"
  • Sufficient information is contained within the map.
    • Pose estimation might be unstable if there is insufficient information in the map.
    • A testing framework is necessary to check if the map has adequate information for pose estimation.
  • Map does not differ greatly from the actual environment.
    • Pose estimation might be unstable if the actual environment has different objects from the map.
    • Maps need updates according to new objects and seasonal changes.
  • Maps must be aligned to a uniform coordinate, or an alignment framework is in place.
    • If multiple maps with different coordinate systems are used, the misalignment between them can affect the localization performance.
"},{"location":"design/autoware-architecture/localization/#computational-resources","title":"Computational resources","text":"
  • Sufficient computational resources should be provided to maintain accuracy and computation speed.

  1. For more details about bias, refer to the VectorNav IMU specifications page.\u00a0\u21a9

"},{"location":"design/autoware-architecture/map/","title":"Map component design","text":""},{"location":"design/autoware-architecture/map/#map-component-design","title":"Map component design","text":""},{"location":"design/autoware-architecture/map/#1-overview","title":"1. Overview","text":"

Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks such as localization, route planning, traffic light detection, and predicting the trajectories of pedestrians and other vehicles.

This document describes the design of map component of Autoware, including its requirements, architecture design, features, data formats, and interface to distribute map information to the rest of autonomous driving stack.

"},{"location":"design/autoware-architecture/map/#2-requirements","title":"2. Requirements","text":"

Map should provide two types of information to the rest of the stack:

  • Semantic information about roads as a vector map
  • Geometric information about the environment as a point cloud map (optional)

A vector map contains highly accurate information about a road network, lane geometry, and traffic lights. It is required for route planning, traffic light detection, and predicting the trajectories of other vehicles and pedestrians.

A 3D point cloud map is primarily used for LiDAR-based localization and part of perception in Autoware. In order to determine the current position and orientation of the vehicle, a live scan captured from one or more LiDAR units is matched against a pre-generated 3D point cloud map. Therefore, an accurate point cloud map is crucial for good localization results. However, if the vehicle has an alternate localization method with enough accuracy, for example using camera-based localization, point cloud map may not be required to use Autoware.

"},{"location":"design/autoware-architecture/map/#3-architecture","title":"3. Architecture","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/map/#4-features","title":"4. Features","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/map/#5-map-specification","title":"5. Map Specification","text":""},{"location":"design/autoware-architecture/map/#point-cloud-map","title":"Point Cloud Map","text":"

The point cloud map must be supplied as a file with the following requirements:

  • It must be in the PCD (Point Cloud Data) file format, but can be a single PCD file or divided into multiple PCD files.
  • Each point in the map must contain X, Y, and Z coordinates.
  • An intensity or RGB value for each point may be optionally included.
  • It must cover the entire operational area of the vehicle. It is also recommended to include an additional buffer zone according to the detection range of sensors attached to the vehicle.
  • Its resolution should be at least 0.2 m to yield reliable localization results.
  • It can be in either local or global coordinates, but must be in global coordinates (georeferenced) to use GNSS data for localization.

Note

Three global coordinate systems are currently supported by Autoware, including Military Grid Reference System (MGRS), Universal Transverse Mercator (UTM), and Japan Rectangular Coordinate System. However, MGRS is a preferred coordinate system for georeferenced maps. In a map with MGRS coordinate system, the X and Y coordinates of each point represent the point's location within the 100,000-meter square, while the Z coordinate represents the point's elevation.

If it is split into a single file, Autoware assumes the following directory structure by default.

sample-map-rosbag\n\u251c\u2500\u2500 lanelet2_map.osm\n\u251c\u2500\u2500 pointcloud_map.pcd\n

If it is split into multiple files, Autoware assumes the following directory structure by default.

sample-map-rosbag\n\u251c\u2500\u2500 lanelet2_map.osm\n\u251c\u2500\u2500 pointcloud_map\n\u251c\u2500\u2500 pcd_00.pcd\n\u251c\u2500\u2500 pcd_01.pcd\n\u251c\u2500\u2500 pcd_02.pcd\n\u251c\u2500\u2500 ...\n\u2514\u2500\u2500 pointcloud_map_metadata.yaml\n

Note that, if you split the map into multiple files, you must meet the following additional conditions:

  • It must be split by lines parallel to the x-y axis.
  • Additional metadata must be provided as well.

Metadata should look like as follows:

x_resolution: 100.0\ny_resolution: 150.0\nA.pcd: [1200, 2500] # -> 1200 < x < 1300, 2500 < y < 2650\nB.pcd: [1300, 2500] # -> 1300 < x < 1400, 2500 < y < 2650\nC.pcd: [1200, 2650] # -> 1200 < x < 1300, 2650 < y < 2800\nD.pcd: [1400, 2650] # -> 1400 < x < 1500, 2650 < y < 2800\n

You may use pointcloud_divider from MAP IV for dividing pointcloud map as well as generating the compatible metadata.yaml.

"},{"location":"design/autoware-architecture/map/#vector-map","title":"Vector Map","text":"

The vector cloud map must be supplied as a file with the following requirements:

  • It must be in Lanelet2 format, with additional modifications required by Autoware.
  • It must contain the shape and position information of lanes, traffic lights, stop lines, crosswalks, parking spaces, and parking lots.
  • Except at the beginning or end of a road, each lanelet in the map must be correctly connected to its predecessor, successors, left neighbor, and right neighbor.
  • Each lanelet in the map must contain traffic rule information including its speed limit, right of way, traffic direction, associated traffic lights, stop lines, and traffic signs.
  • It must cover the entire operational area of the vehicle.

Warning

Under Construction

"},{"location":"design/autoware-architecture/node-diagram/","title":"Node diagram","text":""},{"location":"design/autoware-architecture/node-diagram/#node-diagram","title":"Node diagram","text":"

This page depicts the node diagram designs for Autoware Core/Universe architecture.

"},{"location":"design/autoware-architecture/node-diagram/#autoware-core","title":"Autoware Core","text":"

TBD.

"},{"location":"design/autoware-architecture/node-diagram/#autoware-universe","title":"Autoware Universe","text":"

Open in draw.io for fullscreen

Note that the diagram is for reference. We are planning to update this diagram every release and may have old information between the releases. If you wish to check the latest node diagram use rqt_graph after launching the Autoware.

"},{"location":"design/autoware-architecture/perception/","title":"Perception Component Design","text":""},{"location":"design/autoware-architecture/perception/#perception-component-design","title":"Perception Component Design","text":""},{"location":"design/autoware-architecture/perception/#purpose-of-this-document","title":"Purpose of this document","text":"

This document outlines the high-level design strategies, goals and related rationales in the development of the Perception Component. Through this document, it is expected that all OSS developers will comprehend the design philosophy, goals and constraints under which the Perception Component is designed, and participate seamlessly in the development.

"},{"location":"design/autoware-architecture/perception/#overview","title":"Overview","text":"

The Perception Component receives inputs from Sensing, Localization, and Map components, and adds semantic information (e.g., Object Recognition, Obstacle Segmentation, Traffic Light Recognition, Occupancy Grid Map), which is then passed on to Planning Component. This component design follows the overarching philosophy of Autoware, defined as the microautonomy concept.

"},{"location":"design/autoware-architecture/perception/#goals-and-non-goals","title":"Goals and non-goals","text":"

The role of the Perception Component is to recognize the surrounding environment based on the data obtained through Sensing and acquire sufficient information (such as the presence of dynamic objects, stationary obstacles, blind spots, and traffic signal information) to enable autonomous driving.

In our overall design, we emphasize the concept of microautonomy architecture. This term refers to a design approach that focuses on the proper modularization of functions, clear definition of interfaces between these modules, and as a result, high expandability of the system. Given this context, the goal of the Perception Component is set not to solve every conceivable complex use case (although we do aim to support basic ones), but rather to provide a platform that can be customized to the user's needs and can facilitate the development of additional features.

To clarify the design concepts, the following points are listed as goals and non-goals.

Goals:

  • The basic functions are provided so that a simple ODD can be defined.
  • To achieve a design that can provide Perception functionality to every autonomous vehicle.
  • The capability is extensible with the third-party components.
  • The Perception Component is designed to provide a platform that enables Autoware users to develop the complete functionality and capability.
  • The Perception Component is designed to provide a platform that enables Autoware users to develop the autonomous driving system which always outperforms human drivers.
  • The Perception Component is designed to provide a platform that enables Autoware users to develop the autonomous driving system achieving \"zero overlooks\" or \"error-free recognition\".

Non-goals:

  • The Perception Component should not operate perfectly only in specific environments and be completely useless in other environments.
  • The Perception Component is not self-contained but can be extended with third parties.
  • The Perception Component is not aimed at the complete functionality and capability.
  • The Perception Component is not designed to always outperform human drivers.
  • The Perception Component is not capable of achieving \"zero overlooks\" or \"error-free recognition\".
"},{"location":"design/autoware-architecture/perception/#high-level-architecture","title":"High-level architecture","text":"

This diagram describes the high-level architecture of the Perception Component.

The Perception Component consists of the following sub-components:

  • Object Recognition: Recognizes dynamic objects surrounding the ego vehicle in the current frame and predicts their future trajectories.
  • Obstacle Segmentation: Identifies point clouds originating from obstacles(not only dynamic objects but also static obstacles that should be avoided, such as stationary obstacles) that the ego vehicle should avoid.
  • Occupancy Grid Map: Detects blind spots (areas where no information is available and where dynamic objects may jump out).
  • Traffic Light Recognition: Recognizes the colors of traffic lights and the directions of arrow signals.
"},{"location":"design/autoware-architecture/perception/#component-interface","title":"Component interface","text":"

The following describes the input/output concept between Perception Component and other components. See the Perception Component Interface (WIP) page for the current implementation.

"},{"location":"design/autoware-architecture/perception/#input-to-the-perception-component","title":"Input to the Perception Component","text":"
  • From Sensing: This input should provide real-time information about the environment.
    • Camera Image: Image data obtained from the camera.
    • Point Cloud: Point Cloud data obtained from LiDAR.
    • Radar Object: Object data obtained from radar.
  • From Localization: This input should provide real-time information about the ego vehicle.
    • Vehicle motion information: Includes the ego vehicle's position.
  • From Map: This input should provide real-time information about the static information about the environment.
    • Vector Map: Contains all static information about the environment, including lane aria information.
    • Point Cloud Map: Contains static point cloud maps, which should not include information about the dynamic objects.
  • From API:
    • V2X information: The information from V2X modules. For example, the information from traffic signals.
"},{"location":"design/autoware-architecture/perception/#output-from-the-perception-component","title":"Output from the Perception Component","text":"
  • To Planning
    • Dynamic Objects: Provides real-time information about objects that cannot be known in advance, such as pedestrians and other vehicles.
    • Obstacle Segmentation: Supplies real-time information about the location of obstacles, which is more primitive than Detected Object.
    • Occupancy Grid Map: Offers real-time information about the presence of occluded area information.
    • Traffic Light Recognition result: Provides the current state of each traffic light in real time.
"},{"location":"design/autoware-architecture/perception/#how-to-add-new-modules-wip","title":"How to add new modules (WIP)","text":"

As mentioned in the goal session, this perception module is designed to be extensible by third-party components. For specific instructions on how to add new modules and expand its functionality, please refer to the provided documentation or guidelines (WIP).

"},{"location":"design/autoware-architecture/perception/#supported-functions","title":"Supported Functions","text":"Feature Description Requirements LiDAR DNN based 3D detector This module takes point clouds as input and performs detection of objects such as vehicles, trucks, buses, pedestrians, and bicycles. - Point Clouds Camera DNN based 2D detector This module takes camera image as input and performs detection of objects such as vehicles, trucks, buses, pedestrians, and bicycles. - Camera Images LiDAR Clustering This module performs clustering of point clouds and shape estimation to achieve object detection without labels. - Point Clouds Semi-rule based detector This module performs object detection using information from both images and point clouds, and it consists of two components: LiDAR Clustering and Camera DNN based 2D detector. - Output from Camera DNN based 2D detector and LiDAR Clustering Object Merger This module integrates results from various detectors. - Detected Objects Interpolator This module stabilizes the object detection results by maintaining long-term detection results using Tracking results. - Detected Objects - Tracked Objects Tracking This module gives ID and estimate velocity to the detection results. - Detected Objects Prediction This module predicts the future paths (and their probabilities) of dynamic objects according to the shape of the map and the surrounding environment. - Tracked Objects - Vector Map Obstacle Segmentation This module identifies point clouds originating from obstacles that the ego vehicle should avoid. - Point Clouds - Point Cloud Map Occupancy Grid Map This module detects blind spots (areas where no information is available and where dynamic objects may jump out). - Point Clouds - Point Cloud Map Traffic Light Recognition This module detects the position and state of traffic signals. - Camera Images - Vector Map"},{"location":"design/autoware-architecture/perception/#reference-implementation","title":"Reference Implementation","text":"

When Autoware is launched, the default parameters are loaded, and the Reference Implementation is started. For more details, please refer to the Reference Implementation.

"},{"location":"design/autoware-architecture/perception/reference_implementation/","title":"Perception Component Reference Implementation Design","text":""},{"location":"design/autoware-architecture/perception/reference_implementation/#perception-component-reference-implementation-design","title":"Perception Component Reference Implementation Design","text":""},{"location":"design/autoware-architecture/perception/reference_implementation/#purpose-of-this-document","title":"Purpose of this document","text":"

This document outlines detailed design of the reference imprementations. This allows developers and users to understand what is currently available with the Perception Component, how to utilize, expand, or add to its features.

"},{"location":"design/autoware-architecture/perception/reference_implementation/#architecture","title":"Architecture","text":"

This diagram describes the architecture of the reference implementation.

The Perception component consists of the following sub-components:

  • Obstacle Segmentation: Identifies point clouds originating from obstacles(not only dynamic objects but also static obstacles that should be avoided, such as stationary obstacles) that the ego vehicle should avoid. For example, construction cones are recognized using this module.
  • Occupancy Grid Map: Detects blind spots (areas where no information is available and where dynamic objects may jump out).
  • Object Recognition: Recognizes dynamic objects surrounding the ego vehicle in the current frame and predicts their future trajectories.
    • Detection: Detects the pose and velocity of dynamic objects such as vehicles and pedestrians.
      • Detector: Triggers object detection processing frame by frame.
      • Interpolator: Maintains stable object detection. Even if the output from Detector suddenly becomes unavailable, Interpolator uses the output from the Tracking module to maintain the detection results without missing any objects.
    • Tracking: Associates detected results across multiple frames.
    • Prediction: Predicts trajectories of dynamic objects.
  • Traffic Light Recognition: Recognizes the colors of traffic lights and the directions of arrow signals.
"},{"location":"design/autoware-architecture/perception/reference_implementation/#internal-interface-in-the-perception-component","title":"Internal interface in the perception component","text":"
  • Obstacle Segmentation to Object Recognition
    • Point Cloud: A Point Cloud observed in the current frame, where the ground and outliers are removed.
  • Obstacle Segmentation to Occupancy Grid Map
    • Ground filtered Point Cloud: A Point Cloud observed in the current frame, where the ground is removed.
  • Occupancy Grid Map to Obstacle Segmentation
    • Occupancy Grid Map: This is used for filtering outlier.
"},{"location":"design/autoware-architecture/planning/","title":"Planning component design","text":""},{"location":"design/autoware-architecture/planning/#planning-component-design","title":"Planning component design","text":""},{"location":"design/autoware-architecture/planning/#overview","title":"Overview","text":"

The Planning component generates the trajectory message that will be subscribed to by the Control component based on the environmental state obtained from the Localization and the Perception components.

"},{"location":"design/autoware-architecture/planning/#requirements","title":"Requirements","text":"

The goal of the Planning component is to generate a trajectory (path and velocity) of the ego vehicle that is safe and well-regulated while satisfying the given mission.

Goals:

  • The basic functions are provided so that a simple ODD can be defined.
  • The functionality is modularized to accommodate the third-party components. That is, a complicated or realistic ODD needs not be defined by the basic functions provided by default.
  • The capability is extensible with the third-party components or the decision of human operators.
  • The mechanism and policy are separated to allow the system or operators to change the behavior of the ego vehicle. Ultimately speaking, the policy can be set to crash an obstacle and the mechanism always follows. Otherwise, the system is not safe from the design point of view.

Non-goals:

  • The Planning component is not self-contained but can be extended with third parties.
  • The Planning component is not aimed at the complete functionality and capability.
  • The Planning component is not designed to always outperform human drivers.
  • The Planning component is not capable of \u201cnever crashes\u201d.
"},{"location":"design/autoware-architecture/planning/#high-level-architecture","title":"High-level architecture","text":"

This diagram describes the high-level architecture of the Planning Component.

The Planning component consists of the following sub-components:

  • Mission Planning: Calculates the route based on the given goal and map information.
  • Scenario Planning: Determines the trajectory based on the current scenario, such as Lane Driving or Parking.
    • Lane Driving: Calculates the trajectory for driving within constructed lanes.
      • Behavior Planner: Calculates suitable trajectory based on safety considerations and traffic rules.
      • Motion Planner: Calculates suitable trajectory for the vehicle by taking into account safety factors, vehicle motion considerations, and instructions from the behavior planner.
    • Parking: Calculates the trajectory for parking in unstructured areas.
  • Validation: Verifies the safety of the trajectory.

Each component contains some modules that can be dynamically loaded and unloaded based on the situation. For instance, the Behavior Planning component includes modules such as lane change, intersection, and crosswalk modules.

Our planning components are built based on the microautonomy architecture with Autoware. We adopt a modular system framework where the tasks are implemented as modules that can be dynamically loaded and unloaded to achieve different features depending on the given use cases.

"},{"location":"design/autoware-architecture/planning/#component-interface","title":"Component interface","text":"

The following describes the input/output concept between Planning Component and other components. See the Planning Component Interface (WIP) page for the current implementation.

"},{"location":"design/autoware-architecture/planning/#input-to-the-planning-component","title":"Input to the planning component","text":"
  • From Map
    • Vector map: Contains all static information about the environment, including lane connection information for route planning, lane geometry for generating a reference path, and traffic rule-related information.
  • From Perception
    • Detected object information: Provides real-time information about objects that cannot be known in advance, such as pedestrians and other vehicles. The Planning Component plans maneuvers to avoid collisions with these objects.
    • Detected obstacle information: Supplies real-time information about the location of obstacles, which is more primitive than Detected Object and used for emergency stops and other safety measures.
    • Occupancy map information: Offers real-time information about the presence of pedestrians and other vehicles and occluded area information.
    • Traffic light recognition result: Provides the current state of each traffic light in real time. The Planning Component extracts relevant information for the planned path and determines whether to stop at intersections.
  • From Localization
    • Vehicle motion information: Includes the ego vehicle's position, velocity, acceleration, and other motion-related data.
  • From System
    • Operation mode: Indicates whether the vehicle is operating in Autonomous mode.
  • From Human Machine Interface (HMI)
    • Feature execution: Allows for executing/authorizing autonomous driving operations, such as lane changes or entering intersections, by human operators.
  • From API Layer
    • Goal: Represents the final position that the Planning Component aims to reach.
    • Checkpoint: Represents a midpoint along the route to the destination. This is used during route calculation.
    • Velocity limit: Sets the maximum speed limit for the vehicle.
"},{"location":"design/autoware-architecture/planning/#output-from-the-planning-component","title":"Output from the planning component","text":"
  • To Control
    • Trajectory: Provides a smooth sequence of pose, twist, and acceleration that the Control Component must follow. The trajectory is typically 10 seconds long with a 0.1-second resolution.
    • Turn Signals: Controls the vehicle's turn indicators, such as right, left, hazard, etc. based on the planned maneuvers.
  • To System
    • Diagnostics: Reports the state of the Planning Component, indicating whether the processing is running correctly and whether a safe plan is being generated.
  • To Human Machine Interface (HMI)
    • Feature execution availability: Indicates the status of operations that can be executed or are required, such as lane changes or entering intersections.
    • Trajectory candidate: Shows the potential trajectory that will be executed after the user's execution.
  • To API Layer
    • Planning factors: Provides information about the reasoning behind the current planning behavior. This may include the position of target objects to avoid, obstacles that led to the decision to stop, and other relevant information.
"},{"location":"design/autoware-architecture/planning/#internal-interface-in-the-planning-component","title":"Internal interface in the planning component","text":"
  • Mission Planning to Scenario Planning
    • Route: Offers guidance for the path that needs to be followed from the starting point to the destination. This path is determined based on information such as lane IDs defined on the map. At the route level, it doesn't explicitly indicate which specific lanes to take, and the route can contain multiple lanes.
  • Behavior Planning to Motion Planning
    • Path: Provides a rough position and velocity to be followed by the vehicle. These path points are usually defined with an interval of about 1 meter. Although other interval distances are possible, it may impact the precision or performance of the planning component.
    • Drivable area: Defines regions where the vehicle can drive, such as within lanes or physically drivable areas. It assumes that the motion planner will calculate the final trajectory within this defined area.
  • Scenario Planning to Validation
    • Trajectory: Defines the desired positions, velocities, and accelerations which the Control Component will try to follow. Trajectory points are defined at intervals of approximately 0.1 seconds based on the trajectory velocities.
  • Validation to Control Component
    • Trajectory: Same as above but with some additional safety considerations.
"},{"location":"design/autoware-architecture/planning/#how-to-add-new-modules-wip","title":"How to add new modules (WIP)","text":"

As mentioned in the goal session, this planning module is designed to be extensible by third-party components. For specific instructions on how to add new modules and expand its functionality, please refer to the provided documentation or guidelines (WIP).

"},{"location":"design/autoware-architecture/planning/#supported-functions","title":"Supported Functions","text":"Feature Description Requirements Figure Route Planning Plan route from the ego vehicle position to the destination. Reference implementation is in Mission Planner, enabled by launching the mission_planner node. - Lanelet map (driving lanelets) Path Planning from Route Plan path to be followed from the given route. Reference implementation is in Behavior Path Planner. - Lanelet map (driving lanelets) Obstacle Avoidance Plan path to avoid obstacles by steering operation. Reference implementation is in Avoidance, Obstacle Avoidance Planner. Enable flag in parameter: launch obstacle_avoidance_planner true - objects information Path Smoothing Plan path to achieve smooth steering. Reference implementation is in Obstacle Avoidance Planner. - Lanelet map (driving lanelet) Narrow Space Driving Plan path to drive within the drivable area. Furthermore, when it is not possible to drive within the drivable area, stop the vehicle to avoid exiting the drivable area. Reference implementation is in Obstacle Avoidance Planner. - Lanelet map (high-precision lane boundaries) Lane Change Plan path for lane change to reach the destination. Reference implementation is in Lane Change.. Enable flag in both parameters: - Lanelet map (driving lanelets) Pull Over Plan path for pull over to park at the road shoulder. Reference implementation is in Goal Planner. - Lanelet map (shoulder lane) Pull Out Plan path for pull over to start from the road shoulder. Reference implementation is in Pull Out Module. - Lanelet map (shoulder lane) Path Shift Plan path in lateral direction in response to external instructions. Reference implementation is in Side Shift Module. - None Obstacle Stop Plan velocity to stop for an obstacle on the path. Reference implementation is in Obstacle Stop Planner, Obstacle Cruise Planner. launch obstacle_stop_planner and enable flag: TODO, launch obstacle_cruise_planner and enable flag: TODO - objects information Obstacle Deceleration Plan velocity to decelerate for an obstacle located around the path. Reference implementation is in Obstacle Stop Planner, Obstacle Cruise Planner. - objects information Adaptive Cruise Control Plan velocity to follow the vehicle driving in front of the ego vehicle. Reference implementation is in Obstacle Stop Planner, Obstacle Cruise Planner. - objects information Decelerate for cut-in vehicles Plan velocity to avoid a risk for cutting-in vehicle to ego lane. Reference implementation is in Obstacle Cruise Planner. - objects information Surround Check at starting Plan velocity to prevent moving when an obstacle exists around the vehicle. Reference implementation is in Surround Obstacle Checker. - objects information Curve Deceleration Plan velocity to decelerate the speed on a curve. Reference implementation is in Motion Velocity Smoother. - None Curve Deceleration for Obstacle Plan velocity to decelerate the speed on a curve for a risk of obstacle collision around the path. Reference implementation is in Obstacle Velocity Limiter. - objects information - Lanelet map (static obstacle) Crosswalk Plan velocity to stop or decelerate for pedestrians approaching or walking on a crosswalk. Reference implementation is in Crosswalk Module. - objects information - Lanelet map (pedestrian crossing) Intersection Oncoming Vehicle Check Plan velocity for turning right/left at intersection to avoid a risk with oncoming other vehicles. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane and yield lane) Intersection Blind Spot Check Plan velocity for turning right/left at intersection to avoid a risk with other vehicles or motorcycles coming from behind blind spot. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane) Intersection Occlusion Check Plan velocity for turning right/left at intersection to avoid a risk with the possibility of coming vehicles from occlusion area. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane) WIP Intersection Traffic Jam Detection Plan velocity for intersection not to enter the intersection when a vehicle is stopped ahead for a traffic jam. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane) Traffic Light Plan velocity for intersection according to a traffic light signal. Reference implementation is in Traffic Light Module. - Traffic light color information Run-out Check Plan velocity to decelerate for the possibility of nearby objects running out into the path. Reference implementation is in Run Out Module. - objects information Stop Line Plan velocity to stop at a stop line. Reference implementation is in Stop Line Module. - Lanelet map (stop line) Occlusion Spot Check Plan velocity to decelerate for objects running out from occlusion area, for example, from behind a large vehicle. Reference implementation is in Occlusion Spot Module. - objects information - Lanelet map (private/public lane) No Stop Area Plan velocity not to stop in areas where stopping is prohibited, such as in front of the fire station entrance. Reference implementation is in No Stopping Area Module. - Lanelet map (no stopping area) Merge from Private Area to Public Road Plan velocity for entering the public road from a private driveway to avoid a risk of collision with pedestrians or other vehicles. Reference implementation is in Merge from Private Area Module. - objects information - Lanelet map (private/public lane) WIP Speed Bump Plan velocity to decelerate for speed bumps. Reference implementation is in Speed Bump Module. - Lanelet map (speed bump) WIP Detection Area Plan velocity to stop at the corresponding stop when an object exist in the designated detection area. Reference implementation is in Detection Area Module. - Lanelet map (detection area) Out of ODD area Plan velocity to stop before exiting the area designated by ODD (Operational Design Domain). Reference implementation is in (WIP). - Lanelet map (invalid lanelet) WIP Collision Detection when deviating from lane Plan velocity to avoid conflict with other vehicles driving in the another lane when the ego vehicle is deviating from own lane. Reference implementation is in Out of Lane Module. - objects information - Lanelet map (driving lane) WIP Parking Plan path and velocity for given goal in parking area. Reference implementation is in Free Space Planner. - objects information - Lanelet map (parking area) Autonomous Emergency Braking (AEB) Perform an emergency stop if a collision with an object ahead is anticipated. It is noted that this function is expected as a final safety layer, and this should work even in the event of failures in the Localization or Perception system. Reference implementation is in Out of Lane Module. - Primitive objects WIP Minimum Risk Maneuver (MRM) Provide appropriate MRM (Minimum Risk Maneuver) instructions when a hazardous event occurs. For example, when a sensor trouble found, send an instruction for emergency braking, moderate stop, or pulling over to the shoulder, depending on the severity of the situation. Reference implementation is in TODO - TODO WIP Trajectory Validation Check the planned trajectory is safe. If it is unsafe, take appropriate action, such as modify the trajectory, stop sending the trajectory or report to the autonomous driving system. Reference implementation is in Planning Validator. - None WIP Running Lane Map Generation Generate lane map from localization data recorded in manual driving. Reference implementation is in WIP - None WIP Running Lane Optimization Optimize the centerline (reference path) of the map to make it smooth considering the vehicle kinematics. Reference implementation is in Static Centerline Optimizer. - Lanelet map (driving lanes) WIP"},{"location":"design/autoware-architecture/planning/#reference-implementation","title":"Reference Implementation","text":"

The following diagram describes the reference implementation of the Planning component. By adding new modules or extending the functionalities, various ODDs can be supported.

Note that some implementation does not adhere to the high-level architecture design and require updating.

For more details, please refer to the design documents in each package.

  • mission_planner: calculate route from start to goal based on the map information.
  • behavior_path_planner: calculates path and drivable area based on the traffic rules.
    • lane_following
    • lane_change
    • avoidance
    • pull_over
    • pull_out
    • side_shift
  • behavior_velocity_planner: calculates max speed based on the traffic rules.
    • detection_area
    • blind_spot
    • cross_walk
    • stop_line
    • traffic_light
    • intersection
    • no_stopping_area
    • virtual_traffic_light
    • occlusion_spot
    • run_out
  • obstacle_avoidance_planner: calculate path shape under obstacle and drivable area constraints
  • surround_obstacle_checker: keeps the vehicle being stopped when there are obstacles around the ego-vehicle. It works only when the vehicle is stopped.
  • obstacle_stop_planner: When there are obstacles on or near the trajectory, it calculates the maximum velocity of the trajectory points depending on the situation: stopping, slowing down, or adaptive cruise (following the car).
    • stop
    • slow_down
    • adaptive_cruise
  • costmap_generator: generates a costmap for path generation from dynamic objects and lane information.
  • freespace_planner: calculates trajectory considering the feasibility (e.g. curvature) for the freespace scene. Algorithms are described here.
  • scenario_selector : chooses a trajectory according to the current scenario.
  • external_velocity_limit_selector: takes an appropriate velocity limit from multiple candidates.
  • motion_velocity_smoother: calculates final velocity considering velocity, acceleration, and jerk constraints.
"},{"location":"design/autoware-architecture/planning/#important-parameters","title":"Important Parameters","text":"Package Parameter Type Description obstacle_stop_planner stop_planner.stop_position.max_longitudinal_margin double distance between the ego and the front vehicle when stopping (when cruise_planner_type:=obstacle_stop_planner) obstacle_cruise_planner common.safe_distance_margin double distance between the ego and the front vehicle when stopping (when cruise_planner_type:=obstacle_cruise_planner) behavior_path_planner avoidance.avoidance.lateral.lateral_collision_margin double minimum lateral margin to obstacle on avoidance behavior_path_planner avoidance.avoidance.lateral.lateral_collision_safety_buffer double additional lateral margin to obstacle if possible on avoidance obstacle_avoidance_planner option.enable_outside_drivable_area_stop bool If set true, a stop point will be inserted before the path footprint is outside the drivable area."},{"location":"design/autoware-architecture/planning/#notation","title":"Notation","text":""},{"location":"design/autoware-architecture/planning/#1-self-crossing-road-and-overlapped","title":"[1] self-crossing road and overlapped","text":"

To support the self-crossing road and overlapped road in the opposite direction, each planning module has to meet the specifications

Currently, the supported modules are as follows.

  • lane_following (in behavior_path_planner)
  • detection_area (in behavior_velocity_planner)
  • stop_line (in behavior_velocity_planner)
  • virtual_traffic_light (in behavior_velocity_planner)
  • obstacle_avoidance_planner
  • obstacle_stop_planner
  • motion_velocity_smoother
"},{"location":"design/autoware-architecture/planning/#2-size-of-path-points","title":"[2] Size of Path Points","text":"

Some functions do not support paths with only one point. Therefore, each modules should generate the path with more than two path points.

"},{"location":"design/autoware-architecture/sensing/","title":"Sensing component design","text":""},{"location":"design/autoware-architecture/sensing/#sensing-component-design","title":"Sensing component design","text":""},{"location":"design/autoware-architecture/sensing/#overview","title":"Overview","text":"

Sensing component is a collection of modules that apply some primitive pre-processing to the raw sensor data.

The sensor input formats are defined in this component.

"},{"location":"design/autoware-architecture/sensing/#role","title":"Role","text":"
  • Abstraction of data formats to enable usage of sensors from various vendors
  • Perform common/primitive sensor data processing required by each component
"},{"location":"design/autoware-architecture/sensing/#inputs","title":"Inputs","text":""},{"location":"design/autoware-architecture/sensing/#input-types","title":"Input types","text":"Sensor Data Message Type Point cloud (Lidars, depth cameras, etc.) sensor_msgs/msg/PointCloud2.msg Image (RGB, monochrome, depth, etc. cameras) sensor_msgs/msg/Image.msg Radar scan radar_msgs/msg/RadarScan.msg Radar tracks radar_msgs/msg/RadarTracks.msg GNSS-INS position sensor_msgs/msg/NavSatFix.msg GNSS-INS orientation autoware_sensing_msgs/GnssInsOrientationStamped.msg GNSS-INS velocity geometry_msgs/msg/TwistWithCovarianceStamped.msg GNSS-INS acceleration geometry_msgs/msg/AccelWithCovarianceStamped.msg Ultrasonics sensor_msgs/msg/Range.msg"},{"location":"design/autoware-architecture/sensing/#design-by-data-types","title":"Design by data-types","text":"
  • GNSS/INS data pre-processing design
  • Image pre-processing design
  • Point cloud pre-processing design
  • Radar data pre-processing design
  • Ultrasonics data pre-processing design
"},{"location":"design/autoware-architecture/sensing/data-types/gnss-ins-data/","title":"GNSS/INS data pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/gnss-ins-data/#gnssins-data-pre-processing-design","title":"GNSS/INS data pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/sensing/data-types/image/","title":"Image pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/image/#image-pre-processing-design","title":"Image pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/","title":"Point cloud pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#point-cloud-pre-processing-design","title":"Point cloud pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#overview","title":"Overview","text":"

Point cloud pre-processing is a collection of modules that apply some primitive pre-processing to the raw sensor data.

This pipeline covers the flow of data from drivers to the perception stack.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#recommended-processing-pipeline","title":"Recommended processing pipeline","text":"
graph TD\n    Driver[\"Lidar Driver\"] -->|\"Cloud XYZIRCADT\"| FilterPR[\"Polygon Remover Filter / CropBox Filter\"]\n\n    subgraph \"sensing\"\n    FilterPR -->|\"Cloud XYZIRCADT\"| FilterDC[\"Motion Distortion Corrector Filter\"]\n    FilterDC -->|\"Cloud XYZIRCAD\"| FilterOF[\"Outlier Remover Filter\"]\n    FilterOF -->|\"Cloud XYZIRC\"| FilterDS[\"Downsampler Filter\"]\n    FilterDS -->|\"Cloud XYZIRC\"| FilterTrans[\"Cloud Transformer\"]\n    FilterTrans -->|\"Cloud XYZIRC\"| FilterC\n\n    FilterX[\"...\"] -->|\"Cloud XYZIRC (i)\"| FilterC[\"Cloud Concatenator\"]\n    end\n\n    FilterC -->|\"Cloud XYZIRC\"| SegGr[\"Ground Segmentation\"]
"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#list-of-modules","title":"List of modules","text":"

The modules used here are from pointcloud_preprocessor package.

For details about the modules, see the following table.

It is recommended that these modules are used in a single container as components. For details see ROS 2 Composition

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#point-cloud-fields","title":"Point cloud fields","text":"

In the ideal case, the driver is expected to output a point cloud with the PointXYZIRCADT point type.

name datatype derived description X FLOAT32 false X position Y FLOAT32 false Y position Z FLOAT32 false Z position I (intensity) UINT8 false Measured reflectivity, intensity of the point R (return type) UINT8 false Laser return type for dual return lidars C (channel) UINT16 false Vertical channel id of the laser that measured the point A (azimuth) FLOAT32 true atan2(Y, X), Horizontal angle from the front of the lidar to the point D (distance) FLOAT32 true hypot(X, Y, Z), Euclidean distance of the point to lidar T (time) UINT32 false Nanoseconds passed since the time of the header when this point was measured

Note

A (azimuth) and D (distance) fields are derived fields. They are provided by the driver to reduce the computational load on some parts of the perception stack.

Note

If the Motion Distortion Corrector Filter won't be used, the T (time) field can be omitted, PointXYZIRCAD point type can be used.

Warning

Autoware will support conversion from PointXYZI to PointXYZIRC or PointXYZIRCAD (with channel and return is set to 0) for prototyping purposes. However, this conversion is not recommended for production use since it's not efficient.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#intensity","title":"Intensity","text":"

We will use following ranges for intensity, compatible with the VLP16 User Manual:

Quoting from the VLP-16 User Manual:

For each laser measurement, a reflectivity byte is returned in addition to distance. Reflectivity byte values are segmented into two ranges, allowing software to distinguish diffuse reflectors (e.g. tree trunks, clothing) in the low range from retroreflectors (e.g. road signs, license plates) in the high range. A retroreflector reflects light back to its source with a minimum of scattering. The VLP-16 provides its own light, with negligible separation between transmitting laser and receiving detector, so retroreflecting surfaces pop with reflected IR light compared to diffuse reflectors that tend to scatter reflected energy.

  • Diffuse reflectors report values from 0 to 100 for reflectivities from 0% to 100%.
  • Retroreflectors report values from 101 to 255, where 255 represents an ideal reflection.

In a typical point cloud without retroreflectors, all intensity points will be between 0 and 100.

Retroreflective Gradient road sign, Image Source

But in a point cloud with retroreflectors, the intensity points will be between 0 and 255.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#intensity-mapping-for-other-lidar-brands","title":"Intensity mapping for other lidar brands","text":""},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#hesai-pandarxt16","title":"Hesai PandarXT16","text":"

Hesai Pandar XT16 User Manual

This lidar has 2 modes for reporting reflectivity:

  • Linear mapping
  • Non-linear mapping

If you are using linear mapping mode, you should map from [0, 255] to [0, 100] when constructing the point cloud.

If you are using non-linear mapping mode, you should map (hesai to autoware)

  • [0, 251] to [0, 100] and
  • [252, 254] to [101, 255]

when constructing the point cloud.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#livox-mid-70","title":"Livox Mid-70","text":"

Livox Mid-70 User Manual

This lidar has 2 modes for reporting reflectivity similar to Velodyne VLP-16, only the ranges are slightly different.

You should map (livox to autoware)

  • [0, 150] to [0, 100] and
  • [151, 255] to [101, 255]

when constructing the point cloud.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#robosense-rs-lidar-16","title":"RoboSense RS-LiDAR-16","text":"

RoboSense RS-LiDAR-16 User Manual

No mapping required, same as Velodyne VLP-16.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#ouster-os-1-64","title":"Ouster OS-1-64","text":"

Software User Manual v2.0.0 for all Ouster sensors

In the manual it is stated:

Reflectivity [16 bit unsigned int] - sensor Signal Photons measurements are scaled based on measured range and sensor sensitivity at that range, providing an indication of target reflectivity. Calibration of this measurement has not currently been rigorously implemented, but this will be updated in a future firmware release.

So it is advised to map the 16 bit reflectivity to [0, 100] range.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#leishen-ch64w","title":"Leishen CH64W","text":"

I couldn't get the english user manual, link of website

In a user manual I was able to find it says:

Byte 7 represents echo strength, and the value range is 0-255. (Echo strength can reflect the energy reflection characteristics of the measured object in the actual measurement environment. Therefore, the echo strength can be used to distinguish objects with different reflection characteristics.)

So it is advised to map the [0, 255] to [0, 100] range.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#return-type","title":"Return type","text":"

Various lidars support multiple return modes. Velodyne lidars support Strongest and Last return modes.

In the PointXYZIRCT and PointXYZIRC types, R field represents return mode with an UINT8.

R (return type) Description 0 Unknown / Not Marked 1 Strongest 2 Last"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#channel","title":"Channel","text":"

The channel field is used to identify the vertical channel of the laser that measured the point. In various lidar manuals or literature, it can also be called laser id, ring, laser line.

For Velodyne VLP-16, there are 16 channels. Default order of channels in drivers are generally in firing order.

In the PointXYZIRCT and PointXYZIRC types, C field represents the vertical channel id with an UINT16.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#solid-state-and-petal-pattern-lidars","title":"Solid state and petal pattern lidars","text":"

Warning

This section is subject to change. Following are suggestions and open for discussion.

For solid state lidars that have lines, assign row number as the channel id.

For petal pattern lidars, you can keep channel 0.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#time","title":"Time","text":"

In lidar point clouds, each point measurement can have its individual time stamp. This information can be used to eliminate the motion blur that is caused by the movement of the lidar during the scan.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#point-cloud-header-time","title":"Point cloud header time","text":"

The header contains a Time field. The time field has 2 components:

Field Type Description sec int32 Unix time (seconds elapsed since January 1, 1970) nanosec uint32 Nanoseconds elapsed since the sec field

The header of the point cloud message is expected to have the time of the earliest point it has.

Note

The sec field is int32 in ROS 2 humble. The largest value it can represent is 2^31 seconds, it is subject to year 2038 problems. We will wait for actions on ROS 2 community side.

More info at: https://github.com/ros2/rcl_interfaces/issues/85

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#individual-point-time","title":"Individual point time","text":"

Each PointXYZIRCT point type has the T field for representing the nanoseconds passed since the first-shot point of the point cloud.

To calculate exact time each point was shot, the T nanoseconds are added to the header time.

Note

The T field is uint32 type. The largest value it can represent is 2^32 nanoseconds, which equates to roughly 4.29 seconds. Usual point clouds don't last more than 100ms for full cycle. So this field should be enough.

"},{"location":"design/autoware-architecture/sensing/data-types/radar-data/","title":"Radar data pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/radar-data/#radar-data-pre-processing-design","title":"Radar data pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/sensing/data-types/ultrasonics-data/","title":"Ultrasonics data pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/ultrasonics-data/#ultrasonics-data-pre-processing-design","title":"Ultrasonics data pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/vehicle/","title":"Vehicle Interface design","text":""},{"location":"design/autoware-architecture/vehicle/#vehicle-interface-design","title":"Vehicle Interface design","text":""},{"location":"design/autoware-architecture/vehicle/#abstract","title":"Abstract","text":"

The Vehicle Interface component provides an interface between Autoware and a vehicle that passes control signals to the vehicle\u2019s drive-by-wire system and receives vehicle information that is passed back to Autoware.

"},{"location":"design/autoware-architecture/vehicle/#1-requirements","title":"1. Requirements","text":"

Goals:

  • The Vehicle Interface component converts Autoware commands to a vehicle-specific format and converts vehicle status in a vehicle-specific format to Autoware messages.
  • The interface between Autoware and the Vehicle component is abstracted and independent of hardware.
  • The interface is extensible such that additional vehicle-specific commands can be easily added. For example, headlight control.

Non-goals:

  • Accuracy of responses from the vehicle will not be defined, but example accuracy requirements from reference designs are provided as examples.
  • Response speed will not be defined.
"},{"location":"design/autoware-architecture/vehicle/#2-architecture","title":"2. Architecture","text":"

The Vehicle Interface component consists of the following components:

  • A Raw Vehicle Command Converter component that will pass through vehicle commands from the Control component if velocity/acceleration control is supported by the drive-by-wire system. Otherwise, the Control commands will be modified according to the control method (eg: converting a target acceleration from the Control component to a vehicle specific accel/brake pedal value through the use of an acceleration map)
  • A Vehicle Interface component (vehicle specific) that acts as an interface between Autoware and a vehicle to communicate control signals and to obtain information about the vehicle (steer output, tyre angle etc)

Each component contains static nodes of Autoware, while each module can be dynamically loaded and unloaded (corresponding to C++ classes). The mechanism of the Vehicle Interface component is depicted by the following figures:

"},{"location":"design/autoware-architecture/vehicle/#3-features","title":"3. Features","text":"

The Vehicle Interface component can provide the following features in functionality and capability:

  • Basic functions

    • Converting Autoware control commands to vehicle specific command
    • Converting vehicle specific status information (velocity, steering) to Autoware status message
  • Diagnostics
    • List available features
    • Provide a warning if the Control component tries to use a feature that is not available in the Vehicle Interface component

Additional functionality and capability features may be added, depending on the vehicle hardware. Some example features are listed below:

  • Safety features
    • Disengage autonomous driving via manual intervention.
      • This can be done through the use of an emergency disengage button, or by a safety driver manually turning the steering wheel or pressing the brake
  • Optional controls
    • Turn indicator
    • Handbrake
    • Headlights
    • Hazard lights
    • Doors
    • Horn
    • Wipers
"},{"location":"design/autoware-architecture/vehicle/#4-interface-and-data-structure","title":"4. Interface and Data Structure","text":"

The interface of the Vehicle Interface component for other components running in the same process space to access the functionality and capability of the Vehicle Interface component is defined as follows.

From Control

  • Actuation Command
    • target acceleration, braking, and steering angle

From Planning

  • Vehicle Specific Commands (optional and a separate message for each type)
    • Shift
    • Door
    • Wiper
    • etc

From the vehicle

  • Vehicle status messages
    • Vehicle-specific format messages for conversion into Autoware-specific format messages
      • Velocity status
      • Steering status (optional)
      • Shift status (optional)
      • Turn signal status (optional)
      • Actuation status (optional)

The output interface of the Vehicle Interface component:

  • Vehicle control messages to the vehicle
    • Control signals to drive the vehicle
    • Depends on the vehicle type/protocol, but should include steering and velocity commands at a minimum
  • Vehicle status messages to Autoware
  • Actuation Status
    • Acceleration, brake, steering status
  • Vehicle odometry (output to Localization)
    • Vehicle twist information
  • Control mode
    • Information about whether the vehicle is under autonomous control or manual control
  • Shift status (optional)
    • Vehicle shift status
  • Turn signal status (optional)
    • Vehicle turn signal status

The data structure for the internal representation of semantics for the objects and trajectories used in the Vehicle Interface component is defined as follows:

"},{"location":"design/autoware-architecture/vehicle/#5-concerns-assumptions-and-limitations","title":"5. Concerns, Assumptions, and Limitations","text":"

Concerns

  • Architectural trade-offs and scalability

Assumptions

-

Limitations

"},{"location":"design/autoware-architecture/vehicle/#6-examples-of-accuracy-requirements-by-odd","title":"6. Examples of accuracy requirements by ODD","text":""},{"location":"design/autoware-concepts/","title":"Autoware concepts","text":""},{"location":"design/autoware-concepts/#autoware-concepts","title":"Autoware concepts","text":"

Autoware is the world\u2019s first open-source software for autonomous driving systems. Autoware provides value for both The technology developers of autonomous driving systems can create new components based on Autoware. The service operators of autonomous driving systems, on the other hand, can select appropriate technology components with Autoware. This is enabled by the microautonomy architecture that modularizes its software stack into the core and universe subsystems (modules).

"},{"location":"design/autoware-concepts/#microautonomy-architecture","title":"Microautonomy architecture","text":"

Autoware uses a pipeline architecture to enable the development of autonomous driving systems. The pipeline architecture used in Autoware consists of components similar to three-layer-architecture. And they run in parallel. There are 2 main modules: the Core and the Universe. The components in these modules are designed to be extensible and reusable. And we call it microautonomy architecture.

"},{"location":"design/autoware-concepts/#the-core-module","title":"The Core module","text":"

The Core module contains basic runtimes and technology components that satisfy the basic functionality and capability of sensing, computing, and actuation required for autonomous driving systems. AWF develops and maintains the Core module with their architects and leading members through their working groups. Anyone can contribute to the Core but the PR(Pull Request) acceptance criteria is more strict compared to the Universe.

"},{"location":"design/autoware-concepts/#the-universe-module","title":"The Universe module","text":"

The Universe modules are extensions to the Core module that can be provided by the technology developers to enhance the functionality and capability of sensing, computing, and actuation. AWF provides the base Universe module to extend from. A key feature of the microautonomy architecture is that the Universe modules can be contributed to by any organization and individual. That is, you can even create your Universe and make it available for the Autoware community and ecosystem. AWF is responsible for quality control of the Universe modules through their development process. As a result, there are multiple types of the Universe modules - some are verified and validated by AWF and others are not. It is up to the users of Autoware which Universe modules are selected and integrated to build their end applications.

"},{"location":"design/autoware-concepts/#interface-design","title":"Interface design","text":"

The interface design is the most essential piece of the microautonomy architecture, which is classified into internal and external interfaces. The component interface is designed for the components in a Universe module to communicate with those in other modules, including the Core module, within Autoware internally. The AD(Autonomous Driving) API, on the other hand, is designed for the applications of Autoware to access the technology components in the Core and Universe modules of Autoware externally. Designing solid interfaces, the microautonomy architecture is made possible with AWF's partners, and at the same time is made feasible for the partners.

"},{"location":"design/autoware-concepts/#challenges","title":"Challenges","text":"

A grand challenge of the microautonomy architecture is to achieve real-time capability, which guarantees all the technology components activated in the system to predictably meet timing constraints (given deadlines). In general, it is difficult, if not impossible, to tightly estimate the worst-case execution times (WCETs) of components.

In addition, it is also difficult, if not impossible, to tightly estimate the end-to-end latency of components connected by a DAG. Autonomous driving systems based on the microautonomy architecture, therefore, must be designed to be fail-safe but not never-fail. We accept that the timing constraints may be violated (the given deadlines may be missed) as far as the overrun is taken into account. The overrun handlers are two-fold: (i) platform-defined and (ii) user-defined. The platform-defined handler is implemented as part of the platform by default, while the user-defined handler can overwrite it or add a new handler to the system. This is what we call \u201cfail-safe\u201d on a timely basis.

"},{"location":"design/autoware-concepts/#requirements-and-roadmap","title":"Requirements and roadmap","text":"

Goals:

  • All open-source
  • Use case driven
  • Real-time (predictable) framework with overrun handling
  • Code quality
"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/","title":"How is Autoware Core/Universe different from Autoware.AI and Autoware.Auto?","text":""},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#how-is-autoware-coreuniverse-different-from-autowareai-and-autowareauto","title":"How is Autoware Core/Universe different from Autoware.AI and Autoware.Auto?","text":"

Autoware is the world's first \"all-in-one\" open-source software for self-driving vehicles. Since it was first released in 2015, there have been multiple releases made with differing underlying concepts, each one aimed at improving the software.

"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#autowareai","title":"Autoware.AI","text":"

Autoware.AI is the first distribution of Autoware that was released based on ROS 1. The repository contains a variety of packages covering different aspects of autonomous driving technologies - sensing, actuation, localization, mapping, perception and planning.

While it was successful in attracting many developers and contributions, it was difficult to improve Autoware.AI's capabilities for a number of reasons:

  • A lack of concrete architecture design leading to a lot of built-up technical debt, such as tight coupling between modules and unclear module responsibility.
  • Differing coding standards for each package, with very low test coverage.

Furthermore, there was no clear definition of the conditions under which an Autoware-enabled autonomous vehicle could operate, nor of the use cases or situations supported (eg: the ability to overtake a stationary vehicle).

From the lessons learned from Autoware.AI development, a different development process was taken for Autoware.Auto to develop a ROS 2 version of Autoware.

Warning

Autoware.AI is currently in maintenance mode and will reach end-of-life at the end of 2022.

"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#autowareauto","title":"Autoware.Auto","text":"

Autoware.Auto is the second distribution of Autoware that was released based on ROS 2. As part of the transition to ROS 2, it was decided to avoid simply porting Autoware.AI from ROS 1 to ROS 2. Instead, the codebase was rewritten from scratch with proper engineering practices, including defining target use cases and ODDs (eg: Autonomous Valet Parking [AVP], Cargo Delivery, etc.), designing a proper architecture, writing design documents and test code.

Autoware.Auto development seemed to work fine initially, but after completing the AVP and and Cargo Delivery ODD projects, we started to see the following issues:

  • The barrier to new engineers was too high.
    • A lot of work was required to merge new features into Autoware.Auto, and so it was difficult for researchers and students to contribute to development.
    • As a consequence, most Autoware.Auto developers were from companies in the Autoware Foundation and so there were very few people who were able to add state-of-the-art features from research papers.
  • Making large-scale architecture changes was too difficult.
    • To try out experimental architecture, there was a very large overhead involved in keeping the main branch stable whilst also making sure that every change satisfied the continuous integration requirements.
"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#autoware-coreuniverse","title":"Autoware Core/Universe","text":"

In order to address the issues with Autoware.Auto development, the Autoware Foundation decided to create a new architecture called Autoware Core/Universe.

Autoware Core carries over the original policy of Autoware.Auto to be a stable and well-tested codebase. Alongside Autoware Core is a new concept called Autoware Universe, which acts as an extension of Autoware Core with the following benefits:

  • Users can easily replace a Core component with a Universe equivalent in order to use more advanced features, such as a new Localization or Perception algorithm.
  • Code quality requirements for Universe are more relaxed to make it easier for new developers, students and researchers to contribute, but will still be stricter than the requirements for Autoware.AI.
  • Any advanced features added to Universe that are useful to the wider Autoware community will be reviewed and considered for potential inclusion in the main Autoware Core codebase.

This way, the primary requirement of having a stable and safe autonomous driving system can be achieved, whilst simultaneously enabling access to state-of-the-art features created by third-party contributors. For more details about the design of Autoware Core/Universe, refer to the Autoware concepts documentation page.

"},{"location":"design/autoware-interfaces/","title":"Autoware interface design","text":""},{"location":"design/autoware-interfaces/#autoware-interface-design","title":"Autoware interface design","text":""},{"location":"design/autoware-interfaces/#abstract","title":"Abstract","text":"

Autoware defines three categories of interfaces. The first one is Autoware AD API for operating the vehicle from outside the autonomous driving system such as the Fleet Management System (FMS) and Human Machine Interface (HMI) for operators or passengers. The second one is Autoware component interface for components to communicate with each other. The last one is the local interface used inside the component.

"},{"location":"design/autoware-interfaces/#concept","title":"Concept","text":"

  • Applications can operate multiple and various vehicles in a common way.

  • Applications are not affected by version updates and implementation changes.

  • Developers only need to know the interface to add new features and hardware.

"},{"location":"design/autoware-interfaces/#requirements","title":"Requirements","text":"

Goals:

  • AD API provides functionality to create the following applications:
    • Drive the vehicle on the route or drive to the requested positions in order.
    • Operate vehicle behavior such as starting and stopping.
    • Display or announce the vehicle status to operators, passengers, and people around.
    • Control vehicle devices such as doors.
    • Monitor the vehicle or drive it manually.
  • AD API provides stable and long-term specifications. This enables unified access to all vehicles.
  • AD API hides differences in version and implementation and absorbs the impact of changes.
  • AD API has a default implementation and can be applied to some simple ODDs with options.
  • The AD API implementation is extensible with the third-party components as long as it meets the specifications.
  • The component interface provides stable and medium-term specifications. This makes it easier to add components.
  • The component interface clarifies the public and private parts of a component and improves maintainability.
  • The component interface is extensible with the third-party design to improve the sub-components' reusability.

Non-goals:

  • AD API does not cover security. Use it with other reliable methods.
  • The component interface is just a specification, it does not include an implementation.
"},{"location":"design/autoware-interfaces/#architecture","title":"Architecture","text":"

The components of Autoware are connected via the component interface. Each component uses the interface to provide functionality and to access other components. AD API implementation is also a component. Since the functional elements required for AD API are defined as the component interface, other components do not need to consider AD API directly. Tools for evaluation and debugging, such as simulators, access both AD API and the component interface.

The component interface has a hierarchical specification. The top-level architecture consists of some components. Each component has some options of the next-level architecture. Developers select one of them when implementing the component. The simplest next-level architecture is monolithic. This is an all-in-one and black box implementation, and is suitable for small group development, prototyping, and very complex functions. Others are arbitrary architecture consists of sub-components and have advantages for large group development. A sub-component can be combined with others that adopt the same architecture. Third parties can define and publish their own architecture and interface for open source development. It is desirable to propose them for standardization if they are sufficiently evaluated.

"},{"location":"design/autoware-interfaces/#features","title":"Features","text":""},{"location":"design/autoware-interfaces/#communication-methods","title":"Communication methods","text":"

As shown in the table below, interfaces are classified into four communication methods to define their behavior. Function Call is a request-response communication and is used for processing that requires immediate results. The others are publish-subscribe communication. Notification is used to process data that changes with some event, typically a callback. Streams handle continuously changing data. Reliable Stream expects all data to arrive without loss, Realtime Stream expects the latest data to arrive with low delay.

Communication Method ROS Implementation Optional Implementation Function Call Service HTTP Notification Topic (reliable, transient_local) MQTT (QoS=2, retain) Reliable Stream Topic (reliable, volatile) MQTT (QoS=2) Realtime Stream Topic (best_effort, volatile) MQTT (QoS=0)

These methods are provided as services or topics of ROS since Autoware is developed using ROS and mainly communicates with its packages. On the other hand, FMS and HMI are often implemented without ROS, Autoware is also expected to communicate with applications that do not use ROS. It is wasteful for each of these applications to have an adapter for Autoware, and a more suitable means of communication is required. HTTP and MQTT are suggested as additional options because these protocols are widely used and can substitute the behavior of services and topics. In that case, text formats such as JSON where field names are repeated in an array of objects, are inefficient and it is necessary to consider the serialization.

"},{"location":"design/autoware-interfaces/#naming-convention","title":"Naming convention","text":"

The name of the interface must be /<component name>/api/<interface name>, where <component name> is the name of the component. For an AD API component, omit this part and start with /api. The <interface name> is an arbitrary string separated by slashes. Note that this rule causes a restriction that the namespace api must not be used as a name other than AD API and the component interface.

The following are examples of correct interface names for AD API and the component interface:

  • /api/autoware/state
  • /api/autoware/engage
  • /planning/api/route/set
  • /vehicle/api/status

The following are examples of incorrect interface names for AD API and the component interface:

  • /ad_api/autoware/state
  • /autoware/engage
  • /planning/route/set/api
  • /vehicle/my_api/status
"},{"location":"design/autoware-interfaces/#logging","title":"Logging","text":"

It is recommended to log the interface for analysis of vehicle behavior. If logging is needed, rosbag is available for topics, and use logger in rclcpp or rclpy for services. Typically, create a wrapper for service and client classes that logs when a service is called.

"},{"location":"design/autoware-interfaces/#restrictions","title":"Restrictions","text":"

For each API, consider the restrictions such as following and describe them if necessary.

Services:

  • response time
  • pre-condition
  • post-condition
  • execution order
  • concurrent execution

Topics:

  • recommended delay range
  • maximum delay
  • recommended frequency range
  • minimum frequency
  • default frequency
"},{"location":"design/autoware-interfaces/#data-structure","title":"Data structure","text":""},{"location":"design/autoware-interfaces/#data-type-definition","title":"Data type definition","text":"

Do not share the types in AD API unless they are obviously the same to avoid changes in one API affecting another. Also, implementation-dependent types, including the component interface, should not be used in AD API for the same reason. Use the type in AD API in implementation, or create the same type and copy the data to convert the type.

"},{"location":"design/autoware-interfaces/#constants-and-enumeration","title":"Constants and enumeration","text":"

Since ROS don't support enumeration, use constants instead. The default value of type such as zero and empty string should not be used to detect that a variable is unassigned. Alternatively, assign it a dedicated name to indicate that it is undefined. If one type has multiple enumerations, comment on the correspondence between constants and variables. Do not use enumeration values directly, as assignments are subject to change when the version is updated.

"},{"location":"design/autoware-interfaces/#time-stamp","title":"Time stamp","text":"

Clarify what the timestamp indicates. for example, send time, measurement time, update time, etc. Consider having multiple timestamps if necessary. Use std_msgs/msg/Header when using ROS transform. Also consider whether the header is common to all data, independent for each data, or additional timestamp is required.

"},{"location":"design/autoware-interfaces/#request-header","title":"Request header","text":"

Currently, there is no required header.

"},{"location":"design/autoware-interfaces/#response-status","title":"Response status","text":"

The interfaces whose communication method is Function Call use a common response status to unify the error format. These interfaces should include a variable of ResponseStatus with the name status in the response. See autoware_adapi_v1_msgs/msg/ResponseStatus for details.

"},{"location":"design/autoware-interfaces/#concerns-assumptions-and-limitations","title":"Concerns, assumptions and limitations","text":"
  • The applications use the version information provided by AD API to check compatibility. Unknown versions are also treated as available as long as the major versions match (excluding major version 0). Compatibility between AD API and the component interface is assumed to be maintained by the version management system.
  • If an unintended behavior of AD API is detected, the application should take appropriate action. Autoware tries to keep working as long as possible, but it is not guaranteed to be safe. Safety should be considered for the entire system, including the applications.
"},{"location":"design/autoware-interfaces/ad-api/","title":"AD API","text":""},{"location":"design/autoware-interfaces/ad-api/#ad-api","title":"AD API","text":"

Warning

Under Construction

See here for an overview.

"},{"location":"design/autoware-interfaces/ad-api/list/","title":"List of Autoware AD API","text":""},{"location":"design/autoware-interfaces/ad-api/list/#list-of-autoware-ad-api","title":"List of Autoware AD API","text":"
  • Interface
  • Operation Mode
  • Routing
  • Localization
  • Motion
  • Planning
  • Fail-safe
"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/","title":"Fail-safe API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#fail-safe-api","title":"Fail-safe API","text":"
  • /api/fail_safe/mrm_state
"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#description","title":"Description","text":"

This API manages the behavior related to the abnormality of the vehicle. It provides the state of Request to Intervene (RTI), Minimal Risk Maneuver (MRM) and Minimal Risk Condition (MRC). As shown below, Autoware has the gate to switch between the command during normal operation and the command during abnormal operation. For safety, Autoware switches the operation to MRM when an abnormality is detected. Since the required behavior differs depending on the situation, MRM is implemented in various places as a specific mode in a normal module or as an independent module. The fail-safe module selects the behavior of MRM according to the abnormality and switches the gate output to that command.

"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#states","title":"States","text":"

The MRM state indicates whether MRM is operating. This state also provides success or failure. Generally, MRM will switch to another behavior if it fails.

State Description NONE MRM is not operating. OPERATING MRM is operating because an abnormality has been detected. SUCCEEDED MRM succeeded. The vehicle is in a safe condition. FAILED MRM failed. The vehicle is still in an unsafe condition."},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#behavior","title":"Behavior","text":"

There is a dependency between MRM behaviors. For example, it switches from a comfortable stop to a emergency stop, but not the other way around. This is service dependent. Autoware supports the following transitions by default.

State Description NONE MRM is not operating or is operating but no special behavior is required. COMFORTABLE_STOP The vehicle will stop quickly with a comfortable deceleration. EMERGENCY_STOP The vehicle will stop immediately with as much deceleration as possible."},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/","title":"Mrm state","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/#apifail_safemrm_state","title":"/api/fail_safe/mrm_state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/MrmState
"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/#description","title":"Description","text":"

Get the MRM state. For details, see the fail-safe.

"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/#message","title":"Message","text":"Name Type Description state uint16 The state of MRM operation. behavior uint16 The currently selected behavior of MRM."},{"location":"design/autoware-interfaces/ad-api/list/api/interface/","title":"Interface API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/interface/#interface-api","title":"Interface API","text":"
  • /api/interface/version
"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/#description","title":"Description","text":"

This API provides the interface version of the set of AD APIs. It follows Semantic Versioning in order to provide an intuitive understanding of the changes between versions.

"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/","title":"Version","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#apiinterfaceversion","title":"/api/interface/version","text":"
  • Method: function call
  • Type: autoware_adapi_version_msgs/srv/InterfaceVersion
"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#description","title":"Description","text":"

Get the interface version. The version follows Semantic Versioning.

"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#response","title":"Response","text":"Name Type Description major uint16 major version minor uint16 minor version patch uint16 patch version"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/","title":"Localization API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/localization/#localization-api","title":"Localization API","text":"
  • /api/localization/initialization_state
  • /api/localization/initialize
"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/#description","title":"Description","text":"

This API manages the initialization of localization. Autoware requires a global pose as the initial guess for localization.

"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/#states","title":"States","text":"State Description UNINITIALIZED Localization is not initialized. Waiting for a global pose as the initial guess. INITIALIZING Localization is initializing. INITIALIZED Localization is initialized. Initialization can be requested again if necessary."},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/","title":"Initialization state","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/#apilocalizationinitialization_state","title":"/api/localization/initialization_state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/LocalizationInitializationState
"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/#description","title":"Description","text":"

Get the initialization state of localization. For details, see the localization initialization state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/#message","title":"Message","text":"Name Type Description state uint16 A value of the localization initialization state."},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/","title":"Initialize","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#apilocalizationinitialize","title":"/api/localization/initialize","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/InitializeLocalization
"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#description","title":"Description","text":"

Request to initialize localization. For details, see the pose state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#request","title":"Request","text":"Name Type Description pose geometry_msgs/msg/PoseWithCovarianceStamped[<=1] A global pose as the initial guess. If omitted, the GNSS pose will be used."},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/","title":"Motion API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/motion/#motion-api","title":"Motion API","text":"
  • /api/motion/state
  • /api/motion/accept_start
"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/#description","title":"Description","text":"

This API manages the current behavior of the vehicle. Applications can notify the vehicle behavior to the people around and visualize it for operator and passengers.

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/#states","title":"States","text":"

The motion state manages the stop and start of the vehicle. Once the vehicle has stopped, the state will be STOPPED. After this, when the vehicle tries to start (is still stopped), the state will be STARTING. In this state, calling the start API changes the state to MOVING and the vehicle starts. This mechanism can add processing such as announcements before the vehicle starts. Depending on the configuration, the state may transition directly from STOPPED to MOVING.

State Description STOPPED The vehicle is stopped. STARTING The vehicle is stopped, but is trying to start. MOVING The vehicle is moving. BRAKING (T.B.D.) The vehicle is decelerating strongly."},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/","title":"Accept start","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#apimotionaccept_start","title":"/api/motion/accept_start","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/AcceptStart
"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#description","title":"Description","text":"

Accept the vehicle to start. This API can be used when the motion state is STARTING.

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/","title":"State","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/#apimotionstate","title":"/api/motion/state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/MotionState
"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/#description","title":"Description","text":"

Get the motion state. For details, see the motion state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/#message","title":"Message","text":"Name Type Description state uint16 A value of the motion state."},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/","title":"Operation Mode API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#operation-mode-api","title":"Operation Mode API","text":"
  • /api/operation_mode/state
  • /api/operation_mode/change_to_autonomous
  • /api/operation_mode/change_to_stop
  • /api/operation_mode/change_to_local
  • /api/operation_mode/change_to_remote
  • /api/operation_mode/enable_autoware_control
  • /api/operation_mode/disable_autoware_control
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#description","title":"Description","text":"

As shown below, Autoware assumes that the vehicle interface has two modes, Autoware control and direct control. In direct control mode, the vehicle is operated using devices such as steering and pedals. If the vehicle does not support direct control mode, it is always treated as Autoware control mode. Autoware control mode has four operation modes.

Mode Description Stop Keep the vehicle stopped. Autonomous Autonomously control the vehicle. Local Manually control the vehicle from nearby with some device such as a joystick. Remote Manually control the vehicle from a web application on the cloud.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#states","title":"States","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#autoware-control-flag","title":"Autoware control flag","text":"

The flag is_autoware_control_enabled indicates if the vehicle is controlled by Autoware. The enable and disable APIs can be used if the control can be switched by software. These APIs will always fail if the vehicle does not support mode switching or is switched by hardware.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#operation-mode-and-change-flags","title":"Operation mode and change flags","text":"

The state operation_mode indicates what command is used when Autoware control is enabled. The flags change_to_* can be used to check if it is possible to transition to each mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#transition-flag","title":"Transition flag","text":"

Since Autoware may not be able to guarantee safety, such as switching to autonomous mode during overspeed. There is the flag is_in_transition for this situation and it will be true when changing modes. The operator who changed the mode should ensure safety while this flag is true. The flag will be false when the mode change is complete.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/","title":"Change to autonomous","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#apioperation_modechange_to_autonomous","title":"/api/operation_mode/change_to_autonomous","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#description","title":"Description","text":"

Change the operation mode to autonomous. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/","title":"Change to local","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#apioperation_modechange_to_local","title":"/api/operation_mode/change_to_local","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#description","title":"Description","text":"

Change the operation mode to local. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/","title":"Change to remote","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#apioperation_modechange_to_remote","title":"/api/operation_mode/change_to_remote","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#description","title":"Description","text":"

Change the operation mode to remote. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/","title":"Change to stop","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#apioperation_modechange_to_stop","title":"/api/operation_mode/change_to_stop","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#description","title":"Description","text":"

Change the operation mode to stop. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/","title":"Disable autoware control","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#apioperation_modedisable_autoware_control","title":"/api/operation_mode/disable_autoware_control","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#description","title":"Description","text":"

Disable vehicle control by Autoware. For details, see the operation mode. This API fails if the vehicle does not support mode change by software.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/","title":"Enable autoware control","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#apioperation_modeenable_autoware_control","title":"/api/operation_mode/enable_autoware_control","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#description","title":"Description","text":"

Enable vehicle control by Autoware. For details, see the operation mode. This API fails if the vehicle does not support mode change by software.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/","title":"State","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/#apioperation_modestate","title":"/api/operation_mode/state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/OperationModeState
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/#description","title":"Description","text":"

Get the operation mode state. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/#message","title":"Message","text":"Name Type Description mode uint8 The selected command for Autoware control. is_autoware_control_enabled bool True if vehicle control by Autoware is enabled. is_in_transition bool True if the operation mode is in transition. is_stop_mode_available bool True if the operation mode can be changed to stop. is_autonomous_mode_available bool True if the operation mode can be changed to autonomous. is_local_mode_available bool True if the operation mode can be changed to local. is_remote_mode_available bool True if the operation mode can be changed to remote."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/","title":"Planning API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#planning-api","title":"Planning API","text":"
  • /api/planning/velocity_factors
  • /api/planning/steering_factors
"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#description","title":"Description","text":"

This API manages the planned behavior of the vehicle. Applications can notify the vehicle behavior to the people around and visualize it for operator and passengers.

"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#velocity-factors","title":"Velocity factors","text":"

The velocity factors is an array of information on the behavior that the vehicle stops (or slows down). Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type. As the vehicle approaches the stop position, this factor appears with a status of APPROACHING. And when the vehicle reaches that position and stops, the status will be STOPPED. The pose indicates the stop position or the base link if the stop position cannot be calculated.

Factor Type Description SURROUNDING_OBSTACLE There are obstacles immediately around the vehicle. ROUTE_OBSTACLE There are obstacles along the route ahead. INTERSECTION There are obstacles in other lanes in the path. CROSSWALK There are obstacles on the crosswalk. REAR_CHECK There are obstacles behind that would be in a human driver's blind spot. USER_DEFINED_DETECTION_AREA There are obstacles in the predefined detection area. NO_STOPPING_AREA There is not enough space beyond the no stopping area. STOP_SIGN A stop by a stop sign. TRAFFIC_SIGNAL A stop by a traffic signal. V2I_GATE_CONTROL_ENTER A stop by a V2I gate entering. V2I_GATE_CONTROL_LEAVE A stop by a V2I gate leaving. MERGE A stop before merging lanes. SIDEWALK A stop before crossing the sidewalk. LANE_CHANGE A lane change. AVOIDANCE A path change to avoid an obstacle in the current lane. EMERGENCY_OPERATION A stop by emergency instruction from the operator."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#steering-factors","title":"Steering factors","text":"

The steering factors is an array of information on the maneuver that requires use of turn indicators, such as turning left or right. Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type. As the vehicle approaches the position to start steering, this factor appears with a status of APPROACHING. And when the vehicle reaches that position, the status will be TURNING. The pose indicates the start position when APPROACHING and the end position when TURNING.

In cases such as lane change and avoidance, the vehicle will start steering at any position in the range depending on the situation. As the vehicle approaches the start position of the range, this factor appears with a status of APPROACHING. And when the vehicle reaches that position, the status will be TRYING. Then, when it is possible, the vehicle will start steering and the status will be TURNING. The pose indicates the start of the range (A) when APPROACHING and the end of the range (B) when TRYING. The position to end steering (C to D) for TURNING depends on the position to start steering.

Factor Type Description INTERSECTION A turning left or right at an intersection. LANE_CHANGE A lane change. AVOIDANCE_PATH_CHANGE A path change to avoid an obstacle in the current lane. AVOIDANCE_PATH_RETURN A path change to return to the original lane after avoiding an obstacle. STATION T.B.D. (bus stop) PULL_OUT T.B.D. PULL_OVER T.B.D. EMERGENCY_OPERATION A path change by emergency instruction from the operator."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/","title":"Steering factors","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/#apiplanningsteering_factors","title":"/api/planning/steering_factors","text":"
  • Method: realtime stream
  • Type: autoware_adapi_v1_msgs/msg/SteeringFactorArray
"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/#description","title":"Description","text":"

Get the steering factors, sorted in ascending order of distance. For details, see the planning.

"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/#message","title":"Message","text":"Name Type Description factors.pose geometry_msgs/msg/Pose[2] The base link pose related to the steering factor. factors.distance float32[2] The distance from the base link to the above pose. factors.type uint16 The type of the steering factor. factors.direction uint16 The direction of the steering factor. factors.status uint16 The status of the steering factor. factors.detail string The additional information of the steering factor."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/","title":"Velocity factors","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/#apiplanningvelocity_factors","title":"/api/planning/velocity_factors","text":"
  • Method: realtime stream
  • Type: autoware_adapi_v1_msgs/msg/VelocityFactorArray
"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/#description","title":"Description","text":"

Get the velocity factors, sorted in ascending order of distance. For details, see the planning.

"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/#message","title":"Message","text":"Name Type Description factors.pose geometry_msgs/msg/Pose The base link pose related to the velocity factor. factors.distance float32 The distance from the base link to the above pose. factors.type uint16 The type of the velocity factor. factors.status uint16 The status of the velocity factor. factors.detail string The additional information of the velocity factor."},{"location":"design/autoware-interfaces/ad-api/list/api/routing/","title":"Route API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/#route-api","title":"Route API","text":"
  • /api/routing/state
  • /api/routing/route
  • /api/routing/set_route_points
  • /api/routing/set_route
  • /api/routing/clear_route
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/#description","title":"Description","text":"

This API manages destination and waypoints. Note that waypoints are not like stops and just points passing through. In other words, Autoware does not support the route with multiple stops, the application needs to split it up and switch them. There are two ways to set the route. The one is a generic method that uses pose, another is a map-dependent.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/#states","title":"States","text":"State Description UNSET The route is not set. Waiting for a route request. SET The route is set. ARRIVED The vehicle has arrived at the destination. CHANGING Trying to change the route. Not implemented yet."},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/","title":"Clear route","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#apiroutingclear_route","title":"/api/routing/clear_route","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ClearRoute
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#description","title":"Description","text":"

Clear the route.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/","title":"Route","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/#apiroutingroute","title":"/api/routing/route","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/Route
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/#description","title":"Description","text":"

Get the route with the waypoint segments in lanelet format. It is empty if route is not set.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/#message","title":"Message","text":"Name Type Description header std_msgs/msg/Header header for pose transformation data autoware_adapi_v1_msgs/msg/RouteData[<=1] The route in lanelet format"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/","title":"Set route","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#apiroutingset_route","title":"/api/routing/set_route","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/SetRoute
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#description","title":"Description","text":"

Set the route with the waypoint segments in lanelet format. If start pose is not specified, the current pose will be used.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#request","title":"Request","text":"Name Type Description header std_msgs/msg/Header header for pose transformation goal geometry_msgs/msg/Pose goal pose segments autoware_adapi_v1_msgs/msg/RouteSegment[] waypoint segments in lanelet format"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/","title":"Set route points","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#apiroutingset_route_points","title":"/api/routing/set_route_points","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/SetRoutePoints
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#description","title":"Description","text":"

Set the route with the waypoint poses. If start pose is not specified, the current pose will be used.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#request","title":"Request","text":"Name Type Description header std_msgs/msg/Header header for pose transformation goal geometry_msgs/msg/Pose goal pose waypoints geometry_msgs/msg/Pose[] waypoint poses"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/","title":"State","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/#apiroutingstate","title":"/api/routing/state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/RouteState
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/#description","title":"Description","text":"

Get the route state. For details, see the route state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/#message","title":"Message","text":"Name Type Description state uint16 A value of the route state."},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/","title":"Localization initialization state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#autoware_adapi_v1_msgsmsglocalizationinitializationstate","title":"autoware_adapi_v1_msgs/msg/LocalizationInitializationState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#definition","title":"Definition","text":"
uint16 UNKNOWN = 0\nuint16 UNINITIALIZED = 1\nuint16 INITIALIZING = 2\nuint16 INITIALIZED = 3\n\nbuiltin_interfaces/Time stamp\nuint16 state\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/","title":"Motion state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#autoware_adapi_v1_msgsmsgmotionstate","title":"autoware_adapi_v1_msgs/msg/MotionState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#definition","title":"Definition","text":"
uint16 UNKNOWN = 0\nuint16 STOPPED = 1\nuint16 STARTING = 2\nuint16 MOVING = 3\n\nbuiltin_interfaces/Time stamp\nuint16 state\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/","title":"Mrm state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#autoware_adapi_v1_msgsmsgmrmstate","title":"autoware_adapi_v1_msgs/msg/MrmState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#definition","title":"Definition","text":"
builtin_interfaces/Time stamp\n\n# For common use\nuint16 UNKNOWN = 0\n\n# For state\nuint16 NORMAL = 1\nuint16 MRM_OPERATING = 2\nuint16 MRM_SUCCEEDED = 3\nuint16 MRM_FAILED = 4\n\n# For behavior\nuint16 NONE = 1\nuint16 EMERGENCY_STOP = 2\nuint16 COMFORTABLE_STOP = 3\n\nuint16 state\nuint16 behavior\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/","title":"Operation mode state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#autoware_adapi_v1_msgsmsgoperationmodestate","title":"autoware_adapi_v1_msgs/msg/OperationModeState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#definition","title":"Definition","text":"
# constants for mode\nuint8 UNKNOWN = 0\nuint8 STOP = 1\nuint8 AUTONOMOUS = 2\nuint8 LOCAL = 3\nuint8 REMOTE = 4\n\n# variables\nbuiltin_interfaces/Time stamp\nuint8 mode\nbool is_autoware_control_enabled\nbool is_in_transition\nbool is_stop_mode_available\nbool is_autonomous_mode_available\nbool is_local_mode_available\nbool is_remote_mode_available\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/","title":"Response status","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#autoware_adapi_v1_msgsmsgresponsestatus","title":"autoware_adapi_v1_msgs/msg/ResponseStatus","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#definition","title":"Definition","text":"
# error code\nuint16 UNKNOWN = 50000\nuint16 SERVICE_UNREADY = 50001\nuint16 SERVICE_TIMEOUT = 50002\nuint16 TRANSFORM_ERROR = 50003\nuint16 PARAMETER_ERROR = 50004\n\n# warning code\nuint16 DEPRECATED = 60000\nuint16 NO_EFFECT = 60001\n\n# variables\nbool   success\nuint16 code\nstring message\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/srv/AcceptStart
  • autoware_adapi_v1_msgs/srv/ChangeOperationMode
  • autoware_adapi_v1_msgs/srv/ClearRoute
  • autoware_adapi_v1_msgs/srv/InitializeLocalization
  • autoware_adapi_v1_msgs/srv/SetRoute
  • autoware_adapi_v1_msgs/srv/SetRoutePoints
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/","title":"Route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#autoware_adapi_v1_msgsmsgroute","title":"autoware_adapi_v1_msgs/msg/Route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#definition","title":"Definition","text":"
std_msgs/Header header\nautoware_adapi_v1_msgs/RouteData[<=1] data\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/RouteData
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/","title":"Route data","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#autoware_adapi_v1_msgsmsgroutedata","title":"autoware_adapi_v1_msgs/msg/RouteData","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#definition","title":"Definition","text":"
geometry_msgs/Pose start\ngeometry_msgs/Pose goal\nautoware_adapi_v1_msgs/RouteSegment[] segments\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/RouteSegment
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/Route
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/","title":"Route primitive","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#autoware_adapi_v1_msgsmsgrouteprimitive","title":"autoware_adapi_v1_msgs/msg/RoutePrimitive","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#definition","title":"Definition","text":"
int64 id\nstring type  # The same id may be used for each type.\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/RouteSegment
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/","title":"Route segment","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#autoware_adapi_v1_msgsmsgroutesegment","title":"autoware_adapi_v1_msgs/msg/RouteSegment","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#definition","title":"Definition","text":"
autoware_adapi_v1_msgs/RoutePrimitive   preferred\nautoware_adapi_v1_msgs/RoutePrimitive[] alternatives  # Does not include the preferred primitive.\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/RoutePrimitive
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/RouteData
  • autoware_adapi_v1_msgs/srv/SetRoute
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/","title":"Route state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#autoware_adapi_v1_msgsmsgroutestate","title":"autoware_adapi_v1_msgs/msg/RouteState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#definition","title":"Definition","text":"
uint16 UNKNOWN = 0\nuint16 UNSET = 1\nuint16 SET = 2\nuint16 ARRIVED = 3\nuint16 CHANGING = 4\n\nbuiltin_interfaces/Time stamp\nuint16 state\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/","title":"Steering factor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#autoware_adapi_v1_msgsmsgsteeringfactor","title":"autoware_adapi_v1_msgs/msg/SteeringFactor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#definition","title":"Definition","text":"
# constants for common use\nuint16 UNKNOWN = 0\n\n# constants for type\nuint16 INTERSECTION = 1\nuint16 LANE_CHANGE = 2\nuint16 AVOIDANCE_PATH_CHANGE = 3\nuint16 AVOIDANCE_PATH_RETURN = 4\nuint16 STATION = 5\nuint16 PULL_OUT = 6\nuint16 PULL_OVER = 7\nuint16 EMERGENCY_OPERATION = 8\n\n# constants for direction\nuint16 LEFT = 1\nuint16 RIGHT = 2\nuint16 STRAIGHT = 3\n\n# constants for status\nuint16 APPROACHING = 1\nuint16 TRYING = 2\nuint16 TURNING = 3\n\n# variables\ngeometry_msgs/Pose[2] pose\nfloat32[2] distance\nuint16 type\nuint16 direction\nuint16 status\nstring detail\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/SteeringFactorArray
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/","title":"Steering factor array","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#autoware_adapi_v1_msgsmsgsteeringfactorarray","title":"autoware_adapi_v1_msgs/msg/SteeringFactorArray","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#definition","title":"Definition","text":"
std_msgs/Header header\nautoware_adapi_v1_msgs/SteeringFactor[] factors\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/SteeringFactor
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/","title":"Velocity factor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#autoware_adapi_v1_msgsmsgvelocityfactor","title":"autoware_adapi_v1_msgs/msg/VelocityFactor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#definition","title":"Definition","text":"
# constants for common use\nuint16 UNKNOWN = 0\n\n# constants for type\nuint16 SURROUNDING_OBSTACLE = 1\nuint16 ROUTE_OBSTACLE = 2\nuint16 INTERSECTION = 3\nuint16 CROSSWALK = 4\nuint16 REAR_CHECK = 5\nuint16 USER_DEFINED_DETECTION_AREA = 6\nuint16 NO_STOPPING_AREA = 7\nuint16 STOP_SIGN = 8\nuint16 TRAFFIC_SIGNAL = 9\nuint16 V2I_GATE_CONTROL_ENTER = 10\nuint16 V2I_GATE_CONTROL_LEAVE = 11\nuint16 MERGE = 12\nuint16 SIDEWALK = 13\nuint16 LANE_CHANGE = 14\nuint16 AVOIDANCE = 15\nuint16 EMERGENCY_STOP_OPERATION = 16\n\n# constants for status\nuint16 APPROACHING = 1\nuint16 STOPPED = 2\n\n# variables\ngeometry_msgs/Pose pose\nfloat32 distance\nuint16 type\nuint16 status\nstring detail\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/VelocityFactorArray
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/","title":"Velocity factor array","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#autoware_adapi_v1_msgsmsgvelocityfactorarray","title":"autoware_adapi_v1_msgs/msg/VelocityFactorArray","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#definition","title":"Definition","text":"
std_msgs/Header header\nautoware_adapi_v1_msgs/VelocityFactor[] factors\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/VelocityFactor
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/","title":"Accept start","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#autoware_adapi_v1_msgssrvacceptstart","title":"autoware_adapi_v1_msgs/srv/AcceptStart","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#definition","title":"Definition","text":"
---\nuint16 ERROR_NOT_STARTING = 1\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/","title":"Change operation mode","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#autoware_adapi_v1_msgssrvchangeoperationmode","title":"autoware_adapi_v1_msgs/srv/ChangeOperationMode","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#definition","title":"Definition","text":"
---\nuint16 ERROR_NOT_AVAILABLE = 1\nuint16 ERROR_IN_TRANSITION = 2\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/","title":"Clear route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#autoware_adapi_v1_msgssrvclearroute","title":"autoware_adapi_v1_msgs/srv/ClearRoute","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#definition","title":"Definition","text":"
---\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/","title":"Initialize localization","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#autoware_adapi_v1_msgssrvinitializelocalization","title":"autoware_adapi_v1_msgs/srv/InitializeLocalization","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#definition","title":"Definition","text":"
geometry_msgs/PoseWithCovarianceStamped[<=1] pose\n---\nuint16 ERROR_UNSAFE = 1\nuint16 ERROR_GNSS_SUPPORT = 2\nuint16 ERROR_GNSS = 3\nuint16 ERROR_ESTIMATION = 4\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/","title":"Set route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#autoware_adapi_v1_msgssrvsetroute","title":"autoware_adapi_v1_msgs/srv/SetRoute","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#definition","title":"Definition","text":"
std_msgs/Header header\ngeometry_msgs/Pose goal\nautoware_adapi_v1_msgs/RouteSegment[] segments\n---\nuint16 ERROR_ROUTE_EXISTS = 1\nuint16 ERROR_PLANNER_UNREADY = 2\nuint16 ERROR_PLANNER_FAILED = 3\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
  • autoware_adapi_v1_msgs/msg/RouteSegment
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/","title":"Set route points","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#autoware_adapi_v1_msgssrvsetroutepoints","title":"autoware_adapi_v1_msgs/srv/SetRoutePoints","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#definition","title":"Definition","text":"
std_msgs/Header header\ngeometry_msgs/Pose goal\ngeometry_msgs/Pose[] waypoints\n---\nuint16 ERROR_ROUTE_EXISTS = 1\nuint16 ERROR_PLANNER_UNREADY = 2\nuint16 ERROR_PLANNER_FAILED = 3\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/","title":"Interface version","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#autoware_adapi_version_msgssrvinterfaceversion","title":"autoware_adapi_version_msgs/srv/InterfaceVersion","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#definition","title":"Definition","text":"
---\nuint16 major\nuint16 minor\nuint16 patch\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/use-cases/","title":"Use cases of Autoware AD API","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/#use-cases-of-autoware-ad-api","title":"Use cases of Autoware AD API","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/#user-stories","title":"User stories","text":"

The user stories are service scenarios that AD API assumes. AD API is designed based on these scenarios. Each scenario is realized by a combination of use cases described later. If there are scenarios that cannot be covered, please discuss adding a user story.

  • Bus service
  • Taxi service
"},{"location":"design/autoware-interfaces/ad-api/use-cases/#use-cases","title":"Use cases","text":"

Use cases are partial scenarios derived from the user story and generically designed. Service providers can combine these use cases to define user stories and check if AD API can be applied to their own scenarios.

  • Launch and terminate
  • Initialize the pose
  • Change the operation mode
  • Drive to the designated position
  • Get on and get off
"},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/#user-story-of-bus-service","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/#overview","title":"Overview","text":"

This user story is a bus service that goes around the designated stops.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/#scenario","title":"Scenario","text":"Step Operation Use Case 1 Startup the autonomous driving system. Launch and terminate 2 Drive the vehicle from the garage to the waiting position. Change the operation mode 3 Enable autonomous control. Change the operation mode 4 Drive the vehicle to the next bus stop. Drive to the designated position 5 Get on and off the vehicle. Get on and get off 6 Return to step 4 unless it's the last bus stop. 7 Drive the vehicle to the waiting position. Drive to the designated position 8 Drive the vehicle from the waiting position to the garage. Change the operation mode 9 Shutdown the autonomous driving system. Launch and terminate"},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/","title":"Change the operation mode","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/#change-the-operation-mode","title":"Change the operation mode","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/#related-api","title":"Related API","text":"
  • Operation mode
"},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/#sequence","title":"Sequence","text":"

  • Change the mode with software switch.

  • Change the mode with hardware switch.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/","title":"Drive to the designated position","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/#drive-to-the-designated-position","title":"Drive to the designated position","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/#related-api","title":"Related API","text":"
  • Driving
  • Route
"},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/#sequence","title":"Sequence","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/","title":"Get on and get off","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/#get-on-and-get-off","title":"Get on and get off","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/#related-api","title":"Related API","text":"
  • Door
"},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/#sequence","title":"Sequence","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/","title":"Initialize the pose","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/#initialize-the-pose","title":"Initialize the pose","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/#related-api","title":"Related API","text":"
  • Pose
"},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/#sequence","title":"Sequence","text":"

  • Initialization of the pose using input.

  • Initialization of the pose using GNSS.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/","title":"Launch and terminate","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/#launch-and-terminate","title":"Launch and terminate","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/#related-api","title":"Related API","text":"
  • Interface
  • Launcher
"},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/#sequence","title":"Sequence","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/#user-story-of-bus-service","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/#overview","title":"Overview","text":"

This user story is a taxi service that picks up passengers and drives them to their destination.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/#scenario","title":"Scenario","text":"Step Operation Use Case 1 Startup the autonomous driving system. Launch and terminate 2 Drive the vehicle from the garage to the waiting position. Change the operation mode 3 Enable autonomous control. Change the operation mode 4 Drive the vehicle to the position to pick up. Drive to the designated position 5 Get on the vehicle. Get on and get off 6 Drive the vehicle to the destination. Drive to the designated position 7 Get off the vehicle. Get on and get off 8 Drive the vehicle to the waiting position. Drive to the designated position 9 Return to step 4 if there is another request. 10 Drive the vehicle from the waiting position to the garage. Change the operation mode 11 Shutdown the autonomous driving system. Launch and terminate"},{"location":"design/autoware-interfaces/components/","title":"Component interfaces","text":""},{"location":"design/autoware-interfaces/components/#component-interfaces","title":"Component interfaces","text":"

Warning

Under Construction

See here for an overview.

"},{"location":"design/autoware-interfaces/components/control/","title":"Control","text":""},{"location":"design/autoware-interfaces/components/control/#control","title":"Control","text":""},{"location":"design/autoware-interfaces/components/control/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/control/#vehicle-kinematic-state","title":"Vehicle kinematic state","text":"

Current position and orientation of ego. Published by the Localization module.

  • nav_msgs/Odometry
    • std_msgs/Header header
    • string child_frame_id
    • geometry_msgs/PoseWithCovariance pose
    • geometry_msgs/TwistWithCovariance twist
"},{"location":"design/autoware-interfaces/components/control/#trajectory","title":"Trajectory","text":"

trajectory to be followed by the controller. See Outputs of Planning.

"},{"location":"design/autoware-interfaces/components/control/#steering-status","title":"Steering Status","text":"

Current steering of the ego vehicle. Published by the Vehicle Interface.

  • Steering message (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 steering_angle
"},{"location":"design/autoware-interfaces/components/control/#actuation-status","title":"Actuation Status","text":"

Actuation status of the ego vehicle for acceleration, steering, and brake.

TODO This represents the reported physical efforts exerted by the vehicle actuators. Published by the Vehicle Interface.

  • ActuationStatus (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 acceleration
    • float32 steering
"},{"location":"design/autoware-interfaces/components/control/#output","title":"Output","text":""},{"location":"design/autoware-interfaces/components/control/#vehicle-control-command","title":"Vehicle Control Command","text":"

A motion signal to drive the vehicle, achieved by the low-level controller in the vehicle layer. Used by the Vehicle Interface.

  • autoware_auto_control_msgs/AckermannControlCommand
    • builtin_interfaces::msg::Time stamp
    • autoware_auto_control_msgs/AckermannLateralCommand lateral
      • builtin_interfaces::msg::Time stamp
      • float steering_tire_angle
      • float steering_tire_rotation_rate
    • autoware_auto_control_msgs/LongitudinalCommand longitudinal
      • builtin_interfaces::msg::Time stamp
      • builtin_interfaces::msg::Duration duration
      • builtin_interfaces::msg::Duration time_step
      • float[] speeds
      • float[] accelerations
      • float[] jerks
"},{"location":"design/autoware-interfaces/components/localization/","title":"Localization","text":""},{"location":"design/autoware-interfaces/components/localization/#localization","title":"Localization","text":""},{"location":"design/autoware-interfaces/components/localization/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/localization/#pointcloud-map","title":"Pointcloud Map","text":"

Environment map created with point cloud, published by the map server.

  • sensor_msgs/msg/PointCloud2

A 3d point cloud map is used for LiDAR-based localization in Autoware.

"},{"location":"design/autoware-interfaces/components/localization/#manual-initial-pose","title":"Manual Initial Pose","text":"

Start pose of ego, published by the user interface.

  • geometry_msgs/msg/PoseWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msgs/msg/PoseWithCovariance pose
      • geometry_msgs/msg/Pose pose
        • geometry_msgs/msg/Point position
        • geometry_msg/msg/Quaternion orientation
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#3d-lidar-scanning","title":"3D-LiDAR Scanning","text":"

LiDAR scanning for NDT matching, published by the LiDAR sensor.

  • sensor_msgs/msg/PointCloud2

The raw 3D-LiDAR data needs to be processed by the point cloud pre-processing modules before being used for localization.

"},{"location":"design/autoware-interfaces/components/localization/#automatic-initial-pose","title":"Automatic Initial pose","text":"

Start pose of ego, calculated from INS(Inertial navigation sensor) sensing data.

  • geometry_msgs/msg/PoseWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msgs/msg/PoseWithCovariance pose
      • geometry_msgs/msg/Pose pose
        • geometry_msgs/msg/Point position
        • geometry_msg/msg/Quaternion orientation
      • double[36] covariance

When the initial pose is not set manually, the message can be used for automatic pose initialization.

Current Geographic coordinate of the ego, published by the GNSS sensor.

  • sensor_msgs/msg/NavSatFix
    • std_msgs/msg/Header header
    • sensor_msgs/msg/NavSatStatus status
    • double latitude
    • double longitude
    • double altitude
    • double[9] position_covariance
    • unit8 position_covariance_type

Current orientation of the ego, published by the GNSS-INS.

  • autoware_sensing_msgs/msg/GnssInsOrientationStamped
    • std_msgs/Header header
    • autoware_sensing_msgs/msg/GnssInsOrientation orientation
      • geometry_msgs/Quaternion orientation
      • float32 rmse_rotation_x
      • float32 rmse_rotation_y
      • float32 rmse_rotation_z
"},{"location":"design/autoware-interfaces/components/localization/#imu-data","title":"IMU Data","text":"

Current orientation, angular velocity and linear acceleration of ego, calculated from IMU sensing data.

  • sensor_msgs/msg/Imu
    • std_msgs/msg/Header header
    • geometry_msgs/msg/Quaternion orientation
    • double[9] orientation_covariance
    • geometry_msgs/msg/Vector3 angular_velocity
    • double[9] angular_velocity_covariance
    • geometry_msgs/msg/Vector3 linear_acceleration
    • double[9] linear_acceleration_covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-velocity-status","title":"Vehicle Velocity Status","text":"

Current velocity of the ego vehicle, published by the vehicle interface.

  • autoware_auto_vehicle_msgs/msg/VelocityReport
    • std_msgs/msg/Header header;
    • float longitudinal_velocity;
    • float lateral_velocity;
    • float heading_rate;

Before the velocity input localization interface, module vehicle_velocity_converter converts message type autoware_auto_vehicle_msgs/msg/VelocityReport to geometry_msgs/msg/TwistWithCovarianceStamped.

"},{"location":"design/autoware-interfaces/components/localization/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/localization/#vehicle-pose","title":"Vehicle pose","text":"

Current pose of ego, calculated from localization interface.

  • geometry_msgs/msg/PoseWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msg/PoseWithCovariance pose
      • geometry_msgs/msg/Pose pose
        • geometry_msgs/msg/Point position
        • geometry_msgs/msg/Quaternion orientation
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-velocity","title":"Vehicle velocity","text":"

Current velocity of ego, calculated from localization interface.

  • geometry_msgs/msg/TwistWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msg/TwistWithCovariance twist
      • geometry_msgs/msg/Twist twist
        • geometry_msgs/msg/Vector3 linear
        • geometry_msgs/msg/Vector3 angular
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-acceleration","title":"Vehicle acceleration","text":"

Current acceleration of ego, calculated from localization interface.

  • geometry_msgs/msg/AccelWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msg/AccelWithCovariance accel
      • geometry_msgs/msg/Accel accel
        • geometry_msgs/msg/Vector3 linear
        • geometry_msgs/msg/Vector3 angular
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-kinematic-state","title":"Vehicle kinematic state","text":"

Current pose, velocity and acceleration of ego, calculated from localization interface.

Note: Kinematic state contains pose, velocity and acceleration. In the future, pose, velocity and acceleration will not be used as output for localization.

  • autoware_msgs/autoware_localization_msgs/msg/KinematicState
    • std_msgs/msg/Header header
    • string child_frame_id
    • geometry_msgs/PoseWithCovariance pose_with_covariance
    • geometry_msgs/TwistWithCovariance twist_with_covariance
    • geometry_msgs/AccelWithCovariance accel_with_covariance

The message will be subscribed by the planning and control module.

"},{"location":"design/autoware-interfaces/components/localization/#localization-accuracy","title":"Localization Accuracy","text":"

Diagnostics information that indicates if the localization module works properly.

TBD.

"},{"location":"design/autoware-interfaces/components/map/","title":"Map","text":""},{"location":"design/autoware-interfaces/components/map/#map","title":"Map","text":""},{"location":"design/autoware-interfaces/components/map/#overview","title":"Overview","text":"

Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks. Before launching Autoware, you need to load the pre-created map files.

"},{"location":"design/autoware-interfaces/components/map/#inputs","title":"Inputs","text":"
  • Point cloud maps (.pcd)
  • Lanelet2 maps (.osm)

Refer to Creating maps on how to create maps.

"},{"location":"design/autoware-interfaces/components/map/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/map/#point-cloud-map","title":"Point cloud map","text":"

It loads point cloud files and publishes the maps to the other Autoware nodes in various configurations. Currently, it supports the following types:

  • Raw point cloud map (sensor_msgs/msg/PointCloud2)
  • Downsampled point cloud map (sensor_msgs/msg/PointCloud2)
  • Partial point cloud map loading via ROS service (autoware_map_msgs/srv/GetPartialPointCloudMap)
  • Differential point cloud map loading via ROS service (autoware_map_msgs/srv/GetDifferentialPointCloudMap)
"},{"location":"design/autoware-interfaces/components/map/#lanelet2-map","title":"Lanelet2 map","text":"

It loads a Lanelet2 file and publishes the map data as autoware_auto_mapping_msgs/msg/HADMapBin message. The lan/lon coordinates are projected onto the MGRS coordinates.

  • autoware_auto_mapping_msgs/msg/HADMapBin
    • std_msgs/Header header
    • string version_map_format
    • string version_map
    • string name_map
    • uint8[] data
"},{"location":"design/autoware-interfaces/components/map/#lanelet2-map-visualization","title":"Lanelet2 map visualization","text":"

Visualize autoware_auto_mapping_msgs/HADMapBin messages in Rviz.

  • visualization_msgs/msg/MarkerArray
"},{"location":"design/autoware-interfaces/components/perception/","title":"Perception","text":""},{"location":"design/autoware-interfaces/components/perception/#perception","title":"Perception","text":"

Warning

Under Construction

This page provides specific specifications about the Interface of the Perception Component. Please refer to the perception architecture reference implementation design document for concepts and data flow.

"},{"location":"design/autoware-interfaces/components/perception/#input","title":"Input","text":""},{"location":"design/autoware-interfaces/components/perception/#from-map-component","title":"From Map Component","text":"Name Topic / Service Type Description Vector Map /map/vector_map autoware_auto_mapping_msgs/msg/HADMapBin HD Map including the information about lanes Point Cloud Map /service/get_differential_pcd_map autoware_map_msgs/srv/GetDifferentialPointCloudMap Point Cloud Map

Notes:

  • Point Cloud Map
    • input can be both topic or service, but we highly recommend to use service because since this interface enables processing without being constrained by map file size limits.
"},{"location":"design/autoware-interfaces/components/perception/#from-sensing-component","title":"From Sensing Component","text":"Name Topic Type Description Camera Image /sensing/camera/camera*/image_rect_color sensor_msgs/Image Camera image data, processed with Lens Distortion Correction (LDC) Camera Image /sensing/camera/camera*/image_raw sensor_msgs/Image Camera image data, not processed with Lens Distortion Correction (LDC) Point Cloud /sensing/lidar/concatenated/pointcloud sensor_msgs/PointCloud2 Concatenated point cloud from multiple LiDAR sources Radar Object /sensing/radar/detected_objects autoware_auto_perception_msgs/msg/DetectedObject Radar objects"},{"location":"design/autoware-interfaces/components/perception/#from-localization-component","title":"From Localization Component","text":"Name Topic Type Description Vehicle Odometry /localization/kinematic_state nav_msgs/msg/Odometry Ego vehicle odometry topic"},{"location":"design/autoware-interfaces/components/perception/#from-api","title":"From API","text":"Name Topic Type Description External Traffic Signals /external/traffic_signals autoware_perception_msgs::msg::TrafficSignalArray The traffic signals from an external system"},{"location":"design/autoware-interfaces/components/perception/#output","title":"Output","text":""},{"location":"design/autoware-interfaces/components/perception/#to-planning","title":"To Planning","text":"Name Topic Type Description Dynamic Objects /perception/object_recognition/objects autoware_auto_perception_msgs/msg/PredictedObjects Set of dynamic objects with information such as a object class and a shape of the objects Obstacles /perception/obstacle_segmentation/pointcloud sensor_msgs/PointCloud2 Obstacles, which includes dynamic objects and static objetcs Occupancy Grid Map /perception/occupancy_grid_map/map nav_msgs/msg/OccupancyGrid The map with the imformation about the presence of obstacles and blind spot Traffic Signal /perception/traffic_light_recognition/traffic_signals autoware_perception_msgs::msg::TrafficSignalArray The traffic signal information such as a color (green, yellow, read) and an arrow (right, left, straight)"},{"location":"design/autoware-interfaces/components/planning/","title":"Planning","text":""},{"location":"design/autoware-interfaces/components/planning/#planning","title":"Planning","text":""},{"location":"design/autoware-interfaces/components/planning/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/planning/#3d-object-predictions","title":"3D Object Predictions","text":"

set of perceived objects around ego that need to be avoided when planning a trajectory. Published by the Perception module.

  • autoware_auto_perception_msgs/msg/PredictedObjects
    • std_msgs/Header header
    • sequence<autoware_auto_perception_msgs::msg::PredictedObject> objects
      • unique_identifier_msgs::msg::UUID uuid
      • float existence_probability
      • sequence<autoware_auto_perception_msgs::msg::ObjectClassification> classification
        • uint8 classification
        • float probability
      • autoware_auto_perception_msgs::msg::PredictedObjectKinematics kinematics
        • geometry_msgs::msg::PoseWithCovariance initial_pose
        • geometry_msgs::msg::TwistWithCovariance
        • geometry_msgs::msg::AccelWithCovariance initial_acceleration
        • sequence<autoware_auto_perception_msgs::msg::PredictedPath, 10> predicted_paths
          • sequence<geometry_msgs::msg::Pose, 100> path
          • builtin_interfaces::msg::Duration time_step
          • float confidence
      • sequence<autoware_auto_perception_msgs::msg::Shape, 5> shape
        • geometry_msgs::msg::Polygon polygon
        • float height
"},{"location":"design/autoware-interfaces/components/planning/#traffic-light-response","title":"Traffic Light Response","text":"

Service response with traffic light information. The message definition is under discussion.

  • TrafficLightResponse
    • uint64 traffic_light_id
    • uint8 traffic_light_state

With the traffic_light_state being one of the following

  • GREEN = 1
  • GREEN_BLINKING = 2
  • YELLOW = 3
  • YELLOW_BLINKING = 4
  • RED = 5
  • RED_BLINKING = 6
  • OFF = 7
  • UNKNOWN = 8
"},{"location":"design/autoware-interfaces/components/planning/#vehicle-kinematic-state","title":"Vehicle kinematic state","text":"

current position and orientation of ego. Published by the Localization module.

  • VehicleKinematicState
    • nav_msgs/Odometry
    • std_msgs/Header header
    • string child_frame_id
    • geometry_msgs/PoseWithCovariance pose
    • geometry_msgs/TwistWithCovariance twist
"},{"location":"design/autoware-interfaces/components/planning/#lanelet2-map","title":"Lanelet2 Map","text":"

map of the environment where the planning takes place. Published by the Map Server.

  • autoware_auto_mapping_msgs/msg/HADMapBin
    • std_msgs::msg::Header header
    • uint8 map_format
    • string format_version
    • string map_version
    • sequence < uint8 > data
"},{"location":"design/autoware-interfaces/components/planning/#goal-pose","title":"Goal Pose","text":"

target pose of ego. Published by the User Interface.

  • geometry_msgs/PoseStamped
"},{"location":"design/autoware-interfaces/components/planning/#engagement-response","title":"Engagement Response","text":"

TBD.

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#error-status","title":"Error status","text":"

a status corresponding to the current state of Autoware. Used by the Vehicle Interface to switch between different modes in case of emergency. Published by the Diagnostic Manager.

  • autoware_auto_system_msgs/msg/EmergencyState
    • builtin_interfaces::msg::Time stamp
    • uint8 state

With the state being one of the following:

  • NORMAL = 1
  • OVERRIDE_REQUESTING = 2
  • MRM_OPERATING = 3
  • MRM_SUCCEEDED = 4
  • MRM_FAILED = 5

[TODO] original design for these messages: diagnostic manager also publishes an overriding emergency control command (Add the monitoring system related messages - Autoware.Auto). Possible new design: gate of the vehicle interface switches to the emergency control command (generated by another controller) when receiving an OVERRIDE_REQUESTING message.

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/planning/#traffic-light-query","title":"Traffic Light Query","text":"

service request for the state of a specific traffic light. Sent to the Perception module.

  • uint64 traffic_light_id

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#trajectory","title":"Trajectory","text":"

A sequence of space and velocity points to be followed by the controller.

  • autoware_auto_planning_msgs/Trajectory
    • std_msgs/Header header
    • sequence<autoware_auto_planning_msgs::msg::TrajectoryPoint, 100> points
      • builtin_interfaces::msg::Duration time_from_start
      • geometry_msgs::msg::Pose pose
      • float longitudinal_velocity_mps
      • float lateral_velocity_mps
      • float acceleration_mps2
      • float heading_rate_rps
      • float front_wheel_angle_rad
      • float rear_wheel_angle_rad
"},{"location":"design/autoware-interfaces/components/planning/#vehicle-signal-commands","title":"Vehicle Signal Commands","text":"

Commands for various elements of the vehicle unrelated to motion. Sent to the Vehicle Interface. (For the definition, see autoware_auto_vehicle_msgs.)

  • HandBrake Command
  • Hazard Lights Command
  • Headlights Command
  • Horn Command
  • Stationary Locking Command
  • Turn Indicator Command
  • Wipers Command
"},{"location":"design/autoware-interfaces/components/planning/#missions-status","title":"Missions Status","text":"

TBD.

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#engagement-request","title":"Engagement Request","text":"

TBD,

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/","title":"Vehicle dimensions","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle-dimensions","title":"Vehicle dimensions","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle-axes-and-base_link","title":"Vehicle axes and base_link","text":"

The base_link frame is used very frequently throughout the Autoware stack, and is a projection of the rear-axle center onto the ground surface.

  • Localization module outputs the map to base_link transformation.
  • Planning module plans the poses for where the base_link frame should be in the future.
  • Control module tries to fit base_link to incoming poses.
"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle-dimensions_1","title":"Vehicle dimensions","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheelbase","title":"wheelbase","text":"

The distance between front and rear axles.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#track_width","title":"track_width","text":"

The distance between left and right wheels.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#overhangs","title":"Overhangs","text":"

Overhangs are part of the minimum safety box calculation.

When measuring overhangs, side mirrors, protruding sensors and wheels should be taken into consideration.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#left_overhang","title":"left_overhang","text":"

The distance between the axis centers of the left wheels and the left-most point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#right_overhang","title":"right_overhang","text":"

The distance between the axis centers of the right wheels and the right-most point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#front_overhang","title":"front_overhang","text":"

The distance between the front axle and the foremost point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#rear_overhang","title":"rear_overhang","text":"

The distance between the rear axle and the rear-most point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle_length","title":"vehicle_length","text":"

Total length of the vehicle. Calculated by front_overhang + wheelbase + rear_overhang

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle_width","title":"vehicle_width","text":"

Total width of the vehicle. Calculated by left_overhang + track_width + right_overhang

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel-parameters","title":"Wheel parameters","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel_width","title":"wheel_width","text":"

The lateral width of a wheel tire, primarily used for dead reckoning.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel_radius","title":"wheel_radius","text":"

The radius of the wheel, primarily used for dead reckoning.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#polygon_footprint","title":"polygon_footprint","text":"

The polygon defines the minimum collision area for the vehicle.

The points should be ordered clockwise, with the origin on the base_link.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel-orientations","title":"Wheel orientations","text":"

If the vehicle is going forward, a positive wheel angle will result in the vehicle turning left.

Autoware assumes the rear wheels don't turn on z axis.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#notice","title":"Notice","text":"

The vehicle used in the illustrations was created by xvlblo22 and is from https://www.turbosquid.com/3d-models/modular-sedan-3d-model-1590886.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/","title":"Vehicle Interface","text":""},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-interface","title":"Vehicle Interface","text":"

The Vehicle Interface receives the Vehicle Signal Commands and Vehicle Control Commands and publishes the vehicle status. It also communicates with vehicle by the vehicle-specific protocol.

The Gate switches multiple Vehicle Control Commands. These signals include autonomous diving command, joystick, remote control, and emergency operation, etc. The Adapter converts generalized control command (target steering, steering rate, velocity, acceleration, jerk) into vehicle-specific control values (steering-torque, wheel-torque, voltage, pressure, accel pedal position, etc).

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/vehicle-interface/#error-status","title":"Error status","text":"

(See Inputs of Planning.)

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-control-command","title":"Vehicle Control Command","text":"

(See Output of Control.)

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-signals-commands","title":"Vehicle Signals Commands","text":"

Commands for various elements of the vehicle unrelated to motion. Published by the Planning module.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-signal-reports","title":"Vehicle Signal Reports","text":"

Reports for various elements of the vehicle unrelated to motion. Published by the Vehicle Interface.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-odometry","title":"Vehicle Odometry","text":"

Odometry of the vehicle. Used by the Localization module to update the pose of the vehicle in the map.

  • geometry_msgs/TwistWithCovarianceStamped odometry
"},{"location":"design/autoware-interfaces/components/vehicle-interface/#steering-status","title":"Steering Status","text":"

Steering of the ego vehicle. Published by the Vehicle Interface.

  • Steering message (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 steering_angle
"},{"location":"design/autoware-interfaces/components/vehicle-interface/#actuation-status","title":"Actuation Status","text":"

Actuation status of the ego vehicle for acceleration, steering, and brake. This represents the reported physical efforts exerted by the vehicle actuators. Published by the Vehicle Interface.

  • ActuationStatus (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 acceleration
    • float32 steering
    • float32 brake

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#actuation-command","title":"Actuation Command","text":"

Actuation command sent to the ego vehicle. This represents the requested physical efforts to be exerted by the vehicle actuators. Published by the Vehicle Interface as generated by the adapter.

  • ActuationCommand (github discussion.)
    • builtin_interfaces::msg::Time stamp
    • float32 acceleration
    • float32 steering
    • float32 brake

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-communication","title":"Vehicle Communication","text":"

Vehicle specific messages protocol like CAN (Controller Area Network).

"},{"location":"design/configuration-management/","title":"Configuration management","text":""},{"location":"design/configuration-management/#configuration-management","title":"Configuration management","text":"

Warning

Under Construction

"},{"location":"design/configuration-management/development-process/","title":"Development process","text":""},{"location":"design/configuration-management/development-process/#development-process","title":"Development process","text":"

Warning

Under Construction

"},{"location":"design/configuration-management/release-process/","title":"Release process","text":""},{"location":"design/configuration-management/release-process/#release-process","title":"Release process","text":"

Warning

Under Construction

"},{"location":"design/configuration-management/repository-structure/","title":"Repository structure","text":""},{"location":"design/configuration-management/repository-structure/#repository-structure","title":"Repository structure","text":"

Warning

Under Construction

"},{"location":"how-to-guides/","title":"How-to guides","text":""},{"location":"how-to-guides/#how-to-guides","title":"How-to guides","text":""},{"location":"how-to-guides/#integrating-autoware","title":"Integrating Autoware","text":"
  • Overview
"},{"location":"how-to-guides/#others","title":"Others","text":"
  • Debug Autoware
  • Running Autoware without CUDA
  • Fixing dependent package versions
  • Add a custom ROS message
  • Determining component dependencies
  • Advanced usage of colcon
  • Applying Clang-Tidy to ROS packages
  • Using Eagleye in Autoware

TODO: Write the following contents.

  • Create an Autoware package
  • etc.
"},{"location":"how-to-guides/integrating-autoware/creating-your-autoware-meta-repository/","title":"1. Creating your Autoware meta repository","text":""},{"location":"how-to-guides/integrating-autoware/creating-your-autoware-meta-repository/#creating-your-autoware-meta-repository","title":"Creating your Autoware meta repository","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/launch-autoware/","title":"5. Launch Autoware","text":""},{"location":"how-to-guides/integrating-autoware/launch-autoware/#launch-autoware","title":"Launch Autoware","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/overview/","title":"Overview","text":""},{"location":"how-to-guides/integrating-autoware/overview/#overview","title":"Overview","text":""},{"location":"how-to-guides/integrating-autoware/overview/#requirement-prepare-your-real-vehicle-hardware","title":"Requirement: prepare your real vehicle hardware","text":"

Prerequisites for the vehicle:

  • An onboard computer that satisfies the Autoware installation prerequisites
  • The following devices attached
    • Drive-by-wire interface
    • LiDAR
    • Optional: Inertial measurement unit
    • Optional: Camera
    • Optional: GNSS
"},{"location":"how-to-guides/integrating-autoware/overview/#1-creating-your-autoware-meta-repository","title":"1. Creating your Autoware meta-repository","text":"

Create your Autoware meta-repository. One easy way is to fork autowarefoundation/autoware and clone it. For how to fork a repository, refer to GitHub Docs.

git clone https://github.com/YOUR_NAME/autoware.git\n

If you set up multiple types of vehicles, adding a suffix like \"autoware.vehicle_A\" or \"autoware.vehicle_B\" is recommended.

"},{"location":"how-to-guides/integrating-autoware/overview/#2-creating-the-your-vehicle-and-sensor-description","title":"2. Creating the your vehicle and sensor description","text":"

Next, you need to create description packages that define the vehicle and sensor configuration of your vehicle.

Create the following two packages:

  • YOUR_VEHICLE_launch (see here for example)
  • YOUR_SENSOR_KIT_launch (see here for example)

Once created, you need to update the autoware.repos file of your cloned Autoware repository to refer to these two description packages.

-  # sensor_kit\n-  sensor_kit/sample_sensor_kit_launch:\n-    type: git\n-    url: https://github.com/autowarefoundation/sample_sensor_kit_launch.git\n-    version: main\n-  # vehicle\n-  vehicle/sample_vehicle_launch:\n-    type: git\n-    url: https://github.com/autowarefoundation/sample_vehicle_launch.git\n-    version: main\n+  # sensor_kit\n+  sensor_kit/YOUR_SENSOR_KIT_launch:\n+    type: git\n+    url: https://github.com/YOUR_NAME/YOUR_SENSOR_KIT_launch.git\n+    version: main\n+  # vehicle\n+  vehicle/YOUR_VEHICLE_launch:\n+    type: git\n+    url: https://github.com/YOUR_NAME/YOUR_VEHICLE_launch.git\n+    version: main\n
"},{"location":"how-to-guides/integrating-autoware/overview/#adapt-your_vehicle_launch-for-autoware-launching-system","title":"Adapt YOUR_VEHICLE_launch for autoware launching system","text":""},{"location":"how-to-guides/integrating-autoware/overview/#at-your_vehicle_description","title":"At YOUR_VEHICLE_description","text":"

Define URDF and parameters in the vehicle description package (refer to the sample vehicle description package for an example).

"},{"location":"how-to-guides/integrating-autoware/overview/#at-your_vehicle_launch","title":"At YOUR_VEHICLE_launch","text":"

Create a launch file (refer to the sample vehicle launch package for example). If you have multiple vehicles with the same hardware setup, you can specify vehicle_id to distinguish them.

"},{"location":"how-to-guides/integrating-autoware/overview/#adapt-your_sensor_kit_description-for-autoware-launching-system","title":"Adapt YOUR_SENSOR_KIT_description for autoware launching system","text":""},{"location":"how-to-guides/integrating-autoware/overview/#at-your_sensor_kit_description","title":"At YOUR_SENSOR_KIT_description","text":"

Define URDF and extrinsic parameters for all the sensors here (refer to the sample sensor kit description package for example). Note that you need to calibrate extrinsic parameters for all the sensors beforehand.

"},{"location":"how-to-guides/integrating-autoware/overview/#at-your_sensor_kit_launch","title":"At YOUR_SENSOR_KIT_launch","text":"

Create launch/sensing.launch.xml that launches the interfaces of all the sensors on the vehicle. (refer to the sample sensor kit launch package for example).

Note

At this point, you are now able to run Autoware's Planning Simulator to do a basic test of your vehicle and sensing packages. To do so, you need to build and install Autoware using your cloned repository. Follow the steps for either Docker or source installation (starting from the dependency installation step) and then run the following command:

ros2 launch autoware_launch planning_simulator.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP\n
"},{"location":"how-to-guides/integrating-autoware/overview/#3-create-a-vehicle_interface-package","title":"3. Create a vehicle_interface package","text":"

You need to create an interface package for your vehicle. The package is expected to provide the following two functions.

  1. Receive command messages from vehicle_cmd_gate and drive the vehicle accordingly
  2. Send vehicle status information to Autoware

You can find detailed information about the requirements of the vehicle_interface package in the Vehicle Interface design documentation. You can also refer to TIER IV's pacmod_interface repository as an example of a vehicle interface package.

"},{"location":"how-to-guides/integrating-autoware/overview/#4-create-maps","title":"4. Create maps","text":"

You need both a pointcloud map and a vector map in order to use Autoware. For more information on map design, please click here.

"},{"location":"how-to-guides/integrating-autoware/overview/#create-a-pointcloud-map","title":"Create a pointcloud map","text":"

Use third-party tools such as a LiDAR-based SLAM (Simultaneous Localization And Mapping) package to create a pointcloud map in the .pcd format. For more information, please click here.

"},{"location":"how-to-guides/integrating-autoware/overview/#create-vector-map","title":"Create vector map","text":"

Use third-party tools such as TIER IV's Vector Map Builder to create a Lanelet2 format .osm file.

"},{"location":"how-to-guides/integrating-autoware/overview/#5-launch-autoware","title":"5. Launch Autoware","text":"

This section briefly explains how to run your vehicle with Autoware.

"},{"location":"how-to-guides/integrating-autoware/overview/#install-autoware","title":"Install Autoware","text":"

Follow the installation steps of Autoware.

"},{"location":"how-to-guides/integrating-autoware/overview/#launch-autoware","title":"Launch Autoware","text":"

Launch Autoware with the following command:

ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP\n
"},{"location":"how-to-guides/integrating-autoware/overview/#set-initial-pose","title":"Set initial pose","text":"

If GNSS is available, Autoware automatically initializes the vehicle's pose.

If not, you need to set the initial pose using the RViz GUI.

  1. Click the 2D Pose estimate button in the toolbar, or hit the P key
  2. In the 3D View pane, click and hold the left mouse button, and then drag to set the direction for the initial pose.
"},{"location":"how-to-guides/integrating-autoware/overview/#set-goal-pose","title":"Set goal pose","text":"

Set a goal pose for the ego vehicle.

  1. Click the 2D Nav Goal button in the toolbar, or hit the G key
  2. In the 3D View pane, click and hold the left mouse button, and then drag to set the direction for the goal pose. If successful, you will see the calculated planning path on RViz.
"},{"location":"how-to-guides/integrating-autoware/overview/#engage","title":"Engage","text":"

In your terminal, execute the following command.

source ~/autoware.YOURS/install/setup.bash\nros2 topic pub /autoware.YOURS/engage autoware_auto_vehicle_msgs/msg/Engage \"engage: true\" -1\n

You can also engage via RViz with \"AutowareStatePanel\". The panel can be found in Panels > Add New Panel > tier4_state_rviz_plugin > AutowareStatePanel.

Now the vehicle should drive along the calculated path!

"},{"location":"how-to-guides/integrating-autoware/overview/#6-tune-parameters-for-your-vehicle-environment","title":"6. Tune parameters for your vehicle & environment","text":"

You may need to tune your parameters depending on the domain in which you will operate your vehicle.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/","title":"Creating maps","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/#creating-maps","title":"Creating maps","text":"

Autoware requires a pointcloud map and a vector map for the vehicle's operating environment. (Check the map design documentation page for the detailed specification).

This page explains how users can create maps that can be used for Autoware.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/#creating-a-point-cloud-map","title":"Creating a point cloud map","text":"

Traditionally, a Mobile Mapping System (MMS) is used in order to create highly accurate large-scale point cloud maps. However, since a MMS requires high-end sensors for precise positioning, its operational cost can be very expensive and may not be suitable for a relatively small driving environment. Alternatively, a Simultaneous Localization And Mapping (SLAM) algorithm can be used to create a point cloud map from recorded LiDAR scans. Some of the useful open-source SLAM implementations are listed in this page.

If you prefer proprietary software that is easy to use, you can try a fully automatic mapping tool from MAP IV, Inc., MapIV Engine. They currently provide a trial license for Autoware users free of charge.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/#creating-a-vector-map","title":"Creating a vector map","text":"

The easiest way to create an Autoware-compatible vector map is to use Vector Map Builder, a free web-based tool provided by TIER IV, Inc.. Vector Map Builder allows you to create lanes and add additional regulatory elements such as stop signs or traffic lights using a point cloud map as a reference.

For open-source software options, MapToolbox is a plugin for Unity specifically designed to create Lanelet2 maps for Autoware. Although JOSM is another open-source tool that can be used to create Lanelet2 maps, be aware that a number of modifications must be done manually to make the map compatible with Autoware. This process can be tedious and time-consuming, so the use of JOSM is not recommended.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/#autoware-compatible-map-providers","title":"Autoware-compatible map providers","text":"

If it is not possible to create HD maps yourself, you can use a mapping service from the following Autoware-compatible map providers instead:

  • MAP IV, Inc.
  • AISAN TECHNOLOGY CO., LTD.
  • TomTom

The table below shows each company's mapping technology and the types of HD maps they support.

Company Mapping technology Available maps MAP IV, Inc. SLAM Point cloud and vector maps AISAN TECHNOLOGY CO., LTD. MMS Point cloud and vector maps TomTom MMS Vector map*

Note

Maps provided by TomTom use their proprietary AutoStream format, not Lanelet2. The open-source AutoStreamForAutoware tool can be used to convert an AutoStream map to a Lanelet2 map. However, the converter is still in its early stages and has some known limitations.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/","title":"Available Open Source SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#available-open-source-slam","title":"Available Open Source SLAM","text":"

This page provides the list of available open source Simultaneous Localization And Mapping (SLAM) implementation that can be used to generete a point cloud (.pcd) map file.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#selecting-which-implementation-to-use","title":"Selecting which implementation to use","text":"

Lidar odometry drifts accumulatively as time goes by and there is solutions to solve that problem such as graph optimization, loop closure and using gps sensor to decrease accumulative drift error. Because of that, a SLAM algorithm should have loop closure feature, graph optimization and should use gps sensor. Additionally, some of the algorithms are using IMU sensor to add another factor to graph for decreasing drift error. While some of the algorithms requires 9-axis IMU sensor strictly, some of them requires only 6-axis IMU sensor or not even using the IMU sensor. Before choosing an algorithm to create maps for Autoware please consider these factors depends on your sensor setup or expected quality of generated map.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#tips","title":"Tips","text":"

Commonly used open-source SLAM implementations are lidarslam-ros2 (LiDAR, IMU*) and LIO-SAM (LiDAR, IMU, GNSS). The required sensor data for each algorithm is specified in the parentheses, where an asterisk (*) indicates that such sensor data is optional. For supported LiDAR models, please check the Github repository of each algorithm. While these ROS 2-based SLAM implementations can be easily installed and used directly on the same machine that runs Autoware, it is important to note that they may not be as well-tested or as mature as ROS 1-based alternatives.

The notable open-source SLAM implementations that are based on ROS 1 include hdl-graph-slam (LiDAR, IMU*, GNSS*), LeGO-LOAM (LiDAR, IMU*), LeGO-LOAM-BOR (LiDAR), and LIO-SAM (LiDAR, IMU, GNSS).

Most of these algorithms already have a built-in loop-closure and pose graph optimization. However, if the built-in, automatic loop-closure fails or does not work correctly, you can use Interactive SLAM to adjust and optimize a pose graph manually.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#list-of-third-party-slam-implementations","title":"List of Third Party SLAM Implementations","text":"Package Name Explanation Repository Link Loop Closure Sensors ROS Version Dependencies FAST-LIO-LC A computationally efficient and robust LiDAR-inertial odometry package with loop closure module and graph optimization https://github.com/yanliang-wang/FAST_LIO_LC &check; LidarIMUGPS [Optional] ROS1 ROS MelodicPCL >= 1.8Eigen >= 3.3.4GTSAM >= 4.0.0 FAST_LIO_SLAM FAST_LIO_SLAM is the integration of FAST_LIO and SC-PGO which is scan context based loop detection and GTSAM based pose-graph optimization https://github.com/gisbi-kim/FAST_LIO_SLAM &check; LidarIMUGPS [Optional] ROS1 PCL >= 1.8Eigen >= 3.3.4 FD-SLAM FD_SLAM is Feature&Distribution-based 3D LiDAR SLAM method based on Surface Representation Refinement. In this algorithm novel feature-based Lidar odometry used for fast scan-matching, and used a proposed UGICP method for keyframe matching https://github.com/SLAMWang/FD-SLAM &check; LidarIMU [Optional]GPS ROS1 PCLg2oSuitesparse hdl_graph_slam An open source ROS package for real-time 6DOF SLAM using a 3D LIDAR. It is based on 3D Graph SLAM with NDT scan matching-based odometry estimation and loop detection. It also supports several graph constraints, such as GPS, IMU acceleration (gravity vector), IMU orientation (magnetic sensor), and floor plane (detected in a point cloud) https://github.com/koide3/hdl_graph_slam &check; LidarIMU [Optional]GPS [Optional] ROS1 PCLg2oOpenMP IA-LIO-SAM IA_LIO_SLAM is created for data acquisition in unstructured environment and it is a framework for Intensity and Ambient Enhanced Lidar Inertial Odometry via Smoothing and Mapping that achieves highly accurate robot trajectories and mapping https://github.com/minwoo0611/IA_LIO_SAM &check; LidarIMUGPS ROS1 GTSAM ISCLOAM ISCLOAM presents a robust loop closure detection approach by integrating both geometry and intensity information https://github.com/wh200720041/iscloam &check; Lidar ROS1 Ubuntu 18.04ROS MelodicCeresPCLGTSAMOpenCV LeGO-LOAM-BOR LeGO-LOAM-BOR is improved version of the LeGO-LOAM by improving quality of the code, making it more readable and consistent. Also, performance is improved by converting processes to multi-threaded approach https://github.com/facontidavide/LeGO-LOAM-BOR &check; LidarIMU ROS1 ROS MelodicPCLGTSAM LIO_SAM A framework that achieves highly accurate, real-time mobile robot trajectory estimation and map-building. It formulates lidar-inertial odometry atop a factor graph, allowing a multitude of relative and absolute measurements, including loop closures, to be incorporated from different sources as factors into the system https://github.com/TixiaoShan/LIO-SAM &check; LidarIMUGPS [Optional] ROS1ROS2 PCLGTSAM Optimized-SC-F-LOAM An improved version of F-LOAM and uses an adaptive threshold to further judge the loop closure detection results and reducing false loop closure detections. Also it uses feature point-based matching to calculate the constraints between a pair of loop closure frame point clouds and decreases time consumption of constructing loop frame constraints https://github.com/SlamCabbage/Optimized-SC-F-LOAM &check; Lidar ROS1 PCLGTSAMCeres SC-A-LOAM A real-time LiDAR SLAM package that integrates A-LOAM and ScanContext. https://github.com/gisbi-kim/SC-A-LOAM &check; Lidar ROS1 GTSAM >= 4.0 SC-LeGO-LOAM SC-LeGO-LOAM integrated LeGO-LOAM for lidar odometry and 2 different loop closure methods: ScanContext and Radius search based loop closure. While ScanContext is correcting large drifts, radius search based method is good for fine-stitching https://github.com/irapkaist/SC-LeGO-LOAM &check; LidarIMU ROS1 PCLGTSAM"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/","title":"FAST_LIO_LC","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#fast_lio_lc","title":"FAST_LIO_LC","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#what-is-fast_lio_lc","title":"What is FAST_LIO_LC?","text":"
  • A computationally efficient and robust LiDAR-inertial odometry package with loop closure module and graph optimization.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#original-repository-link","title":"Original Repository link","text":"

https://github.com/yanliang-wang/FAST_LIO_LC

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne, Ouster, Livox]
  • IMU [6-AXIS, 9-AXIS]
  • GPS [Optional]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#dependencies","title":"Dependencies","text":"
  • Ubuntu 18.04
  • ROS Melodic
  • PCL >= 1.8, Follow PCL Installation.
  • Eigen >= 3.3.4, Follow Eigen Installation.
  • GTSAM >= 4.0.0, Follow GTSAM Installation.
  wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\n  cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\n  cd ~/Downloads/gtsam-4.0.0-alpha2/\n  mkdir build && cd build\n  cmake ..\n  sudo make install\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#1-build","title":"1) Build","text":"
    mkdir -p ~/ws_fastlio_lc/src\n    cd ~/ws_fastlio_lc/src\n    git clone https://github.com/gisbi-kim/FAST_LIO_SLAM.git\n    git clone https://github.com/Livox-SDK/livox_ros_driver\n    cd ..\n    catkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#2-set-parameters","title":"2) Set parameters","text":"
  • After downloading the repository, change topic and sensor settings on the config file (workspace/src/FAST_LIO_LC/FAST_LIO/config/ouster64_mulran.yaml) with the lidar topic name in your bag file.
  • For imu-lidar compatibility, extrinsic matrices from calibration must be changed.
  • To enable auto-save, pcd_save_enable must be 1 from the launch file (workspace/src/FAST_LIO_LC/FAST_LIO/launch/mapping_ouster64_mulran.launch).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#3-run","title":"3) Run","text":"
  • For Ouster OS1-64
    # open new terminal: run FAST-LIO\nroslaunch fast_lio mapping_ouster64.launch\n\n# open the other terminal tab: run SC-PGO\nroslaunch aloam_velodyne fastlio_ouster64.launch\n\n# play bag file in the other terminal\nrosbag play RECORDED_BAG.bag --clock\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#other-examples","title":"Other Examples","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#example-dataset","title":"Example dataset","text":"

Check original repository link for example dataset.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#contact","title":"Contact","text":"
  • Maintainer: Yanliang Wang (wyl410922@qq.com)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#acknowledgements","title":"Acknowledgements","text":"
  • Thanks for FAST_LIO authors.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/","title":"FAST_LIO_SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#fast_lio_slam","title":"FAST_LIO_SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#what-is-fast_lio_slam","title":"What is FAST_LIO_SLAM?","text":"
  • FAST_LIO_SLAM is the integration of FAST_LIO and SC-PGO which is scan context based loop detection and GTSAM based pose-graph optimization.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/gisbi-kim/FAST_LIO_SLAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Livox, Velodyne, Ouster]
  • IMU [6-AXIS, 9-AXIS]
  • GPS [OPTIONAL]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • Gtsam
wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.0-alpha2/\nmkdir build && cd build\ncmake ..\nsudo make install\n
  • PCL >= 1.8, Follow PCL Installation.
  • Eigen >= 3.3.4, Follow Eigen Installation.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#1-build","title":"1) Build","text":"
    mkdir -p ~/catkin_fastlio_slam/src\n    cd ~/catkin_fastlio_slam/src\n    git clone https://github.com/gisbi-kim/FAST_LIO_SLAM.git\n    git clone https://github.com/Livox-SDK/livox_ros_driver\n    cd ..\n    catkin_make\n    source devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#2-set-parameters","title":"2) Set parameters","text":"
  • Set imu and lidar topic on Fast_LIO/config/ouster64.yaml
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#3-run","title":"3) Run","text":"
    # terminal 1: run FAST-LIO2\nroslaunch fast_lio mapping_ouster64.launch\n\n    # open the other terminal tab: run SC-PGO\ncd ~/catkin_fastlio_slam\n    source devel/setup.bash\n    roslaunch aloam_velodyne fastlio_ouster64.launch\n\n    # play bag file in the other terminal\nrosbag play xxx.bag -- clock --pause\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#other-examples","title":"Other Examples","text":"

  • Tutorial video 1 (using KAIST 03 sequence of MulRan dataset)

    • Example result captures

    • download the KAIST03 pcd map made by FAST-LIO-SLAM, 500MB
  • Example Video 2 (Riverside 02 sequence of MulRan dataset)
    • Example result captures

    • download the Riverisde02 pcd map made by FAST-LIO-SLAM, 400MB
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#acknowledgements","title":"Acknowledgements","text":"
  • Thanks for FAST_LIO authors.
  • You may have an interest in this version of FAST-LIO + Loop closure, implemented by yanliang-wang
  • Maintainer: Giseop Kim (paulgkim@kaist.ac.kr)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/","title":"FD-SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#fd-slam","title":"FD-SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#what-is-fd-slam","title":"What is FD-SLAM?","text":"
  • FD_SLAM is Feature&Distribution-based 3D LiDAR SLAM method based on Surface Representation Refinement. In this algorithm novel feature-based Lidar odometry used for fast scan-matching, and used a proposed UGICP method for keyframe matching.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#repository-information","title":"Repository Information","text":"

This is an open source ROS package for real-time 6DOF SLAM using a 3D LIDAR.

It is based on hdl_graph_slam and the steps to run our system are same with hdl-graph-slam.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/SLAMWang/FD-SLAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR[VLP-16, HDL-32, HDL-64, OS1-64]
  • GPS
  • IMU [Optional]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • g2o
  • Suitesparse

The following ROS packages are required:

  • geodesy
  • nmea_msgs
  • pcl_ros
  • ndt_omp
  • U_gicp This is modified based on fast_gicp by us. We use UGICP for keyframe matching.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/SLAMWang/FD-SLAM.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#2-services","title":"2) Services","text":"
/hdl_graph_slam/dump  (hdl_graph_slam/DumpGraph)\n- save all the internal data (point clouds, floor coeffs, odoms, and pose graph) to a directory.\n\n/hdl_graph_slam/save_map (hdl_graph_slam/SaveMap)\n- save the generated map as a PCD file.\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#3-set-parameters","title":"3) Set parameters","text":"
  • All the configurable parameters are listed in launch/****.launch as ros params.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#4-run","title":"4) Run","text":"
source devel/setup.bash\nroslaunch hdl_graph_slam hdl_graph_slam_400_ours.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/","title":"hdl_graph_slam","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#hdl_graph_slam","title":"hdl_graph_slam","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#what-is-hdl_graph_slam","title":"What is hdl_graph_slam?","text":"
  • An open source ROS package for real-time 6DOF SLAM using a 3D LIDAR. It is based on 3D Graph SLAM with NDT scan matching-based odometry estimation and loop detection. It also supports several graph constraints, such as GPS, IMU acceleration (gravity vector), IMU orientation (magnetic sensor), and floor plane (detected in a point cloud).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/koide3/hdl_graph_slam

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne, Ouster, RoboSense]
  • IMU [6-AXIS, 9-AXIS] [OPTIONAL]
  • GPS [OPTIONAL]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • g2o
  • OpenMP

The following ROS packages are required:

  • geodesy
  • nmea_msgs
  • pcl_ros
  • ndt_omp
  • fast_gicp
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#1-build","title":"1) Build","text":"
# for melodic\nsudo apt-get install ros-melodic-geodesy ros-melodic-pcl-ros ros-melodic-nmea-msgs ros-melodic-libg2o\ncd catkin_ws/src\ngit clone https://github.com/koide3/ndt_omp.git -b melodic\ngit clone https://github.com/SMRT-AIST/fast_gicp.git --recursive\ngit clone https://github.com/koide3/hdl_graph_slam\n\ncd .. && catkin_make -DCMAKE_BUILD_TYPE=Release\n\n# for noetic\nsudo apt-get install ros-noetic-geodesy ros-noetic-pcl-ros ros-noetic-nmea-msgs ros-noetic-libg2o\n\ncd catkin_ws/src\ngit clone https://github.com/koide3/ndt_omp.git\ngit clone https://github.com/SMRT-AIST/fast_gicp.git --recursive\ngit clone https://github.com/koide3/hdl_graph_slam\n\ncd .. && catkin_make -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#2-set-parameter","title":"2) Set parameter","text":"
  • Set lidar topic on launch/hdl_graph_slam_400.launch
  • Set registration settings on launch/hdl_graph_slam_400.launch
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#3-run","title":"3) Run","text":"
rosparam set use_sim_time true\nroslaunch hdl_graph_slam hdl_graph_slam_400.launch\n
roscd hdl_graph_slam/rviz\nrviz -d hdl_graph_slam.rviz\n
rosbag play --clock hdl_400.bag\n

Save the generated map by:

rosservice call /hdl_graph_slam/save_map \"resolution: 0.05\ndestination: '/full_path_directory/map.pcd'\"\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#example2-outdoor","title":"Example2 (Outdoor)","text":"

Bag file (recorded in an outdoor environment):

  • hdl_400.bag.tar.gz (raw data, about 900MB)
rosparam set use_sim_time true\nroslaunch hdl_graph_slam hdl_graph_slam_400.launch\n
roscd hdl_graph_slam/rviz\nrviz -d hdl_graph_slam.rviz\n
rosbag play --clock dataset.bag\n

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#papers","title":"Papers","text":"

Kenji Koide, Jun Miura, and Emanuele Menegatti, A Portable 3D LIDAR-based System for Long-term and Wide-area People Behavior Measurement, Advanced Robotic Systems, 2019 [link].

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#contact","title":"Contact","text":"

Kenji Koide, k.koide@aist.go.jp, https://staff.aist.go.jp/k.koide

[Active Intelligent Systems Laboratory, Toyohashi University of Technology, Japan] [Mobile Robotics Research Team, National Institute of Advanced Industrial Science and Technology (AIST), Japan]

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/","title":"IA-LIO-SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#ia-lio-sam","title":"IA-LIO-SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#what-is-ia-lio-sam","title":"What is IA-LIO-SAM?","text":"
  • IA_LIO_SLAM is created for data acquisition in unstructured environment and it is a framework for Intensity and Ambient Enhanced Lidar Inertial Odometry via Smoothing and Mapping that achieves highly accurate robot trajectories and mapping.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/minwoo0611/IA_LIO_SAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne, Ouster]
  • IMU [9-AXIS]
  • GNSS
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#dependencies","title":"Dependencies","text":"

  • ROS (tested with Kinetic and Melodic)

    • for ROS melodic:

      sudo apt-get install -y ros-melodic-navigation\nsudo apt-get install -y ros-melodic-robot-localization\nsudo apt-get install -y ros-melodic-robot-state-publisher\n

    • for ROS kinetic:

      sudo apt-get install -y ros-kinetic-navigation\nsudo apt-get install -y ros-kinetic-robot-localization\nsudo apt-get install -y ros-kinetic-robot-state-publisher\n

  • GTSAM (Georgia Tech Smoothing and Mapping library)

    wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.2/\nmkdir build && cd build\ncmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF ..\nsudo make install -j8\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#1-build","title":"1) Build","text":"
    mkdir -p ~/catkin_ia_lio/src\n    cd ~/catkin_ia_lio/src\n    git clone https://github.com/minwoo0611/IA_LIO_SAM\n    cd ..\n    catkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#2-set-parameters","title":"2) Set parameters","text":"
  • After downloading the repository, change topic and sensor settings on the config file (workspace/src/IA_LIO_SAM/config/params.yaml)
  • For imu-lidar compatibility, extrinsic matrices from calibration must be changed.
  • To enable autosave, savePCD must be true on the params.yaml file (workspace/src/IA_LIO_SAM/config/params.yaml).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#3-run","title":"3) Run","text":"
  # open new terminal: run IA_LIO\n  source devel/setup.bash\n  roslaunch lio_sam mapping_ouster64.launch\n\n  # play bag file in the other terminal\n  rosbag play RECORDED_BAG.bag --clock\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#sample-dataset-images","title":"Sample dataset images","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#example-dataset","title":"Example dataset","text":"

Check original repo link for example dataset.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#contact","title":"Contact","text":"
  • Maintainer: Kevin Jung (Github: minwoo0611)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#paper","title":"Paper","text":"

Thank you for citing IA-LIO-SAM(./config/doc/KRS-2021-17.pdf) if you use any of this code.

Part of the code is adapted from LIO-SAM (IROS-2020).

@inproceedings{legoloam2018shan,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Shan, Tixiao and Englot, Brendan},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#acknowledgements","title":"Acknowledgements","text":"
  • IA-LIO-SAM is based on LIO-SAM (T. Shan, B. Englot, D. Meyers, W. Wang, C. Ratti, and D. Rus. LIO-SAM: Tightly-coupled Lidar Inertial Odometry via Smoothing and Mapping).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/","title":"ISCLOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#iscloam","title":"ISCLOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#what-is-iscloam","title":"What is ISCLOAM?","text":"
  • ISCLOAM presents a robust loop closure detection approach by integrating both geometry and intensity information.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/wh200720041/iscloam

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#dependencies","title":"Dependencies","text":"
  • Ubuntu 64-bit 18.04
  • ROS Melodic ROS Installation
  • Ceres Solver Ceres Installation
  • PCL PCL Installation
  • Gtsam GTSAM Installation
  • OpenCV OPENCV Installation
  • Trajectory visualization

For visualization purpose, this package uses hector trajectory sever, you may install the package by

sudo apt-get install ros-melodic-hector-trajectory-server\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#build-and-run","title":"Build and Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#1-clone-repository","title":"1. Clone repository","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/wh200720041/iscloam.git\ncd ..\ncatkin_make -j1\nsource ~/catkin_ws/devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#2-set-parameter","title":"2. Set Parameter","text":"

Change the bag location and sensor parameters on launch files.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#3-launch","title":"3. Launch","text":"
roslaunch iscloam iscloam.launch\n

if you would like to generate the map of environment at the same time, you can run

roslaunch iscloam iscloam_mapping.launch\n

Note that the global map can be very large, so it may takes a while to perform global optimization, some lag is expected between trajectory and map since they are running in separate thread. More CPU usage will happen when loop closure is identified.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#example-result","title":"Example Result","text":"

Watch demo video at Video Link

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#ground-truth-comparison","title":"Ground Truth Comparison","text":"

Green: ISCLOAM Red: Ground Truth

                  KITTI sequence 00                                  KITTI sequence 05\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#citation","title":"Citation","text":"

If you use this work for your research, you may want to cite the paper below, your citation will be appreciated

@inproceedings{wang2020intensity,\n  author={H. {Wang} and C. {Wang} and L. {Xie}},\n  booktitle={2020 IEEE International Conference on Robotics and Automation (ICRA)},\n  title={Intensity Scan Context: Coding Intensity and Geometry Relations for Loop Closure Detection},\n  year={2020},\n  volume={},\n  number={},\n  pages={2095-2101},\n  doi={10.1109/ICRA40945.2020.9196764}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#acknowledgements","title":"Acknowledgements","text":"

Thanks for A-LOAM and LOAM(J. Zhang and S. Singh. LOAM: Lidar Odometry and Mapping in Real-time) and LOAM_NOTED.

Author: Wang Han, Nanyang Technological University, Singapore

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/","title":"LeGO-LOAM-BOR","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#lego-loam-bor","title":"LeGO-LOAM-BOR","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#what-is-lego-loam-bor","title":"What is LeGO-LOAM-BOR?","text":"
  • LeGO-LOAM-BOR is improved version of the LeGO-LOAM by improving quality of the code, making it more readable and consistent. Also, performance is improved by converting processes to multi-threaded approach.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#original-repository-link","title":"Original Repository link","text":"

https://github.com/facontidavide/LeGO-LOAM-BOR

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16]
  • IMU [9-AXIS]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#dependencies","title":"Dependencies","text":"
  • ROS Melodic ROS Installation
  • PCL PCL Installation
  • Gtsam GTSAM Installation
wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.0-alpha2/\nmkdir build && cd build\ncmake ..\nsudo make install\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/facontidavide/LeGO-LOAM-BOR.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#2-set-parameters","title":"2) Set parameters","text":"
  • Set parameters on LeGo-LOAM/loam_config.yaml
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#3-run","title":"3) Run","text":"
source devel/setup.bash\nroslaunch lego_loam_bor run.launch rosbag:=/path/to/your/rosbag lidar_topic:=/velodyne_points\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#cite-lego-loam","title":"Cite LeGO-LOAM","text":"

Thank you for citing our LeGO-LOAM paper if you use any of this code:

@inproceedings{legoloam2018,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Tixiao Shan and Brendan Englot},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/","title":"LIO_SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#lio_sam","title":"LIO_SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#what-is-lio_sam","title":"What is LIO_SAM?","text":"
  • A framework that achieves highly accurate, real-time mobile robot trajectory estimation and map-building. It formulates lidar-inertial odometry atop a factor graph, allowing a multitude of relative and absolute measurements, including loop closures, to be incorporated from different sources as factors into the system
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/TixiaoShan/LIO-SAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Livox, Velodyne, Ouster]
  • IMU [9-AXIS]
  • GPS [OPTIONAL]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
  • For ROS 2
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL

  • Gtsam (Georgia Tech Smoothing and Mapping library)

    sudo add-apt-repository ppa:borglab/gtsam-release-4.0\nsudo apt install libgtsam-dev libgtsam-unstable-dev\n
  sudo apt-get install -y ros-melodic-navigation\n  sudo apt-get install -y ros-melodic-robot-localization\n  sudo apt-get install -y ros-melodic-robot-state-publisher\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#1-build","title":"1) Build","text":"
    mkdir -p ~/catkin_lio_sam/src\n    cd ~/catkin_lio_sam/src\n    git clone https://github.com/TixiaoShan/LIO-SAM.git\n    cd ..\n    catkin_make\n    source devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#2-set-parameters","title":"2) Set parameters","text":"
  • Set topics and sensor settings on lio_sam/config/params.yaml
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#3-run","title":"3) Run","text":"
    # Run the Launch File\nroslaunch lio_sam run.launch\n\n    # Play bag file in the other terminal\nrosbag play xxx.bag --clock\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#paper","title":"Paper","text":"

Thank you for citing LIO-SAM (IROS-2020) if you use any of this code.

@inproceedings{liosam2020shan,\n  title={LIO-SAM: Tightly-coupled Lidar Inertial Odometry via Smoothing and Mapping},\n  author={Shan, Tixiao and Englot, Brendan and Meyers, Drew and Wang, Wei and Ratti, Carlo and Rus Daniela},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={5135-5142},\n  year={2020},\n  organization={IEEE}\n}\n

Part of the code is adapted from LeGO-LOAM.

@inproceedings{legoloam2018shan,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Shan, Tixiao and Englot, Brendan},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#acknowledgements","title":"Acknowledgements","text":"
  • LIO-SAM is based on LOAM (J. Zhang and S. Singh. LOAM: Lidar Odometry and Mapping in Real-time).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/","title":"Optimized-SC-F-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#optimized-sc-f-loam","title":"Optimized-SC-F-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#what-is-optimized-sc-f-loam","title":"What is Optimized-SC-F-LOAM?","text":"
  • An improved version of F-LOAM and uses an adaptive threshold to further judge the loop closure detection results and reducing false loop closure detections. Also it uses feature point-based matching to calculate the constraints between a pair of loop closure frame point clouds and decreases time consumption of constructing loop frame constraints.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/SlamCabbage/Optimized-SC-F-LOAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16, HDL-32, HDL-64]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • Gtsam
  • Ceres Solver
  • For visualization purpose, this package uses hector trajectory sever, you may install the package by
sudo apt-get install ros-noetic-hector-trajectory-server\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/SlamCabbage/Optimized-SC-F-LOAM.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#2-create-message-file","title":"2) Create message file","text":"

In this folder, Ground Truth information, optimized pose information, F-LOAM pose information and time information are stored

mkdir -p ~/message/Scans\n\nChange line 383 in the laserLoopOptimizationNode.cpp to your own \"message\" folder path\n

(Do not forget to rebuild your package)

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#3-set-parameters","title":"3) Set parameters","text":"
  • Set LIDAR topic and LIDAR properties on 'sc_f_loam_mapping.launch'
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#4-run","title":"4) Run","text":"
source devel/setup.bash\nroslaunch optimized_sc_f_loam optimized_sc_f_loam_mapping.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#results-on-kitti-sequence-00-and-sequence-05","title":"Results on KITTI Sequence 00 and Sequence 05","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#comparison-of-trajectories-on-kitti-dataset","title":"Comparison of trajectories on KITTI dataset","text":"

Test on KITTI sequence You can download the sequence 00 and 05 datasets from the KITTI official website and convert them into bag files using the kitti2bag open source method.

00: 2011_10_03_drive_0027 000000 004540

05: 2011_09_30_drive_0018 000000 002760

See the link: https://github.com/ethz-asl/kitti_to_rosbag

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#acknowledgements","title":"Acknowledgements","text":"

Thanks for SC-A-LOAM(Scan context: Egocentric spatial descriptor for place recognition within 3d point cloud map) and F-LOAM(F-LOAM : Fast LiDAR Odometry and Mapping).

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#citation","title":"Citation","text":"
@misc{https://doi.org/10.48550/arxiv.2204.04932,\n  doi = {10.48550/ARXIV.2204.04932},\n\n  url = {https://arxiv.org/abs/2204.04932},\n\n  author = {Liao, Lizhou and Fu, Chunyun and Feng, Binbin and Su, Tian},\n\n  keywords = {Robotics (cs.RO), FOS: Computer and information sciences, FOS: Computer and information sciences},\n\n  title = {Optimized SC-F-LOAM: Optimized Fast LiDAR Odometry and Mapping Using Scan Context},\n\n  publisher = {arXiv},\n\n  year = {2022},\n\n  copyright = {arXiv.org perpetual, non-exclusive license}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/","title":"SC-A-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#sc-a-loam","title":"SC-A-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#what-is-sc-a-loam","title":"What is SC-A-LOAM?","text":"
  • A real-time LiDAR SLAM package that integrates A-LOAM and ScanContext.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/gisbi-kim/SC-A-LOAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16, HDL-32, HDL-64, Ouster OS1-64]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#prerequisites-dependencies","title":"Prerequisites (dependencies)","text":"
  • ROS
  • GTSAM version 4.x.

  • If GTSAM is not installed, follow the steps below.

      wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.2.zip\n  cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\n  cd ~/Downloads/gtsam-4.0.2/\n  mkdir build && cd build\n  cmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF ..\n  sudo make install -j8\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#1-build","title":"1) Build","text":"

  • First, install the abovementioned dependencies and follow below lines.

     mkdir -p ~/catkin_scaloam_ws/src\n cd ~/catkin_scaloam_ws/src\n git clone https://github.com/gisbi-kim/SC-A-LOAM.git\n cd ../\n catkin_make\n source ~/catkin_scaloam_ws/devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#2-set-parameters","title":"2) Set parameters","text":"
  • After downloading the repository, change topic and sensor settings on the launch files.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#scan-context-parameters","title":"Scan Context parameters","text":"
  • If encountering ghosting error or loop is not closed, change the scan context parameters.
  • Adjust the scan context settings with the parameters in the marked area.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#3-run","title":"3) Run","text":"
roslaunch aloam_velodyne aloam_mulran.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#4-saving-as-pcd-file","title":"4) Saving as PCD file","text":"
  rosrun pcl_ros pointcloud_to_pcd input:=/aft_pgo_map\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#example-results","title":"Example Results","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#riverside-01-mulran-dataset","title":"Riverside 01, MulRan dataset","text":"
  • The MulRan dataset provides lidar scans (Ouster OS1-64, horizontally mounted, 10Hz) and consumer level gps (U-Blox EVK-7P, 4Hz) data.
  • About how to use (publishing data) data: see here https://github.com/irapkaist/file_player_mulran

  • example videos on Riverside 01 sequence.

    1. with consumer level GPS-based altitude stabilization: https://youtu.be/FwAVX5TVm04\n2. without the z stabilization: https://youtu.be/okML_zNadhY\n

  • example result:

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#kitti-05","title":"KITTI 05","text":"

  • For KITTI (HDL-64 sensor), run using the command

    roslaunch aloam_velodyne aloam_velodyne_HDL_64.launch # for KITTI dataset setting\n
  • To publish KITTI scans, you can use mini-kitti publisher, a simple python script: https://github.com/gisbi-kim/mini-kitti-publisher
  • example video (no GPS used here): https://youtu.be/hk3Xx8SKkv4

  • example result:

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#contact","title":"Contact","text":"
  • Maintainer: paulgkim@kaist.ac.kr
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/","title":"SC-LeGO-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#sc-lego-loam","title":"SC-LeGO-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#what-is-sc-lego-loam","title":"What is SC-LeGO-LOAM?","text":"
  • SC-LeGO-LOAM integrated LeGO-LOAM for lidar odometry and 2 different loop closure methods: ScanContext and Radius search based loop closure. While ScanContext is correcting large drifts, radius search based method is good for fine-stitching.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/irapkaist/SC-LeGO-LOAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16, HDL-32E, VLS-128, Ouster OS1-16, Ouster OS1-64]
  • IMU [9-AXIS]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • Gtsam
wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.0-alpha2/\nmkdir build && cd build\ncmake ..\nsudo make install\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/irapkaist/SC-LeGO-LOAM.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#2-set-parameters","title":"2) Set parameters","text":"
  • Set imu and lidar topic on include/utility.h
  • Set lidar properties on include/utility.h
  • Set scancontex settings on include/Scancontext.h

(Do not forget to rebuild after setting parameters.)

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#3-run","title":"3) Run","text":"
source devel/setup.bash\nroslaunch lego_loam run.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#other-examples","title":"Other Examples","text":"
  • Video 1: DCC (MulRan dataset)
  • Video 2: Riverside (MulRan dataset)
  • Video 3: KAIST (MulRan dataset)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#mulran-dataset","title":"MulRan dataset","text":"
  • If you want to reproduce the results as the above video, you can download the MulRan dataset and use the ROS topic publishing tool .
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#cite-sc-lego-loam","title":"Cite SC-LeGO-LOAM","text":"
@INPROCEEDINGS { gkim-2018-iros,\n  author = {Kim, Giseop and Kim, Ayoung},\n  title = { Scan Context: Egocentric Spatial Descriptor for Place Recognition within {3D} Point Cloud Map },\n  booktitle = { Proceedings of the IEEE/RSJ International Conference on Intelligent Robots and Systems },\n  year = { 2018 },\n  month = { Oct. },\n  address = { Madrid }\n}\n

and

@inproceedings{legoloam2018,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Shan, Tixiao and Englot, Brendan},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#contact","title":"Contact","text":"
  • Maintainer: Giseop Kim (paulgkim@kaist.ac.kr)
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/","title":"Calibrating your sensors","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#calibrating-your-sensors","title":"Calibrating your sensors","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#overview","title":"Overview","text":"

Autoware expects to have multiple sensors attached to the vehicle as input to perception, localization, and planning stack. These sensors must be calibrated correctly and their positions must be defined using either urdf files (as in sample_sensor_kit) or as tf launch files.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#camera-calibration","title":"Camera calibration","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#intrinsic-calibration","title":"Intrinsic Calibration","text":"
  • Navigation2 provides a good tutorial for camera internal calibration.
  • AutoCore provides a light-weight tool.
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-lidar-calibration","title":"Lidar-lidar calibration","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-lidar-calibration-tool-from-autocore","title":"Lidar-Lidar Calibration tool from Autocore","text":"

LL-Calib on Github, provided by AutoCore, is a lightweight toolkit for online/offline 3D LiDAR to LiDAR calibration. It's based on local mapping and \"GICP\" method to derive the relation between main and sub lidar. Information on how to use the tool, troubleshooting tips and example rosbags can be found at the above link.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-camera-calibration","title":"Lidar-camera calibration","text":"

Developed by MathWorks, The Lidar Camera Calibrator app enables you to interactively estimate the rigid transformation between a lidar sensor and a camera.

https://ww2.mathworks.cn/help/lidar/ug/get-started-lidar-camera-calibrator.html

SensorsCalibration toolbox v0.1: One more open source method for Lidar-camera calibration. This is a project for LiDAR to camera calibration,including automatic calibration and manual calibration

https://github.com/PJLab-ADG/SensorsCalibration/blob/master/lidar2camera/README.md

Developed by AutoCore, an easy-to-use lightweight toolkit for Lidar-camera-calibration is proposed. Only in three steps, a fully automatic calibration will be done.

https://github.com/autocore-ai/calibration_tools/tree/main/lidar-cam-calib-related

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-imu-calibration","title":"Lidar-IMU calibration","text":"

Developed by APRIL Lab at Zhejiang University in China, the LI-Calib calibration tool is a toolkit for calibrating the 6DoF rigid transformation and the time offset between a 3D LiDAR and an IMU, based on continuous-time batch optimization. IMU-based cost and LiDAR point-to-surfel (surfel = surface element) distance are minimized jointly, which renders the calibration problem well-constrained in general scenarios.

AutoCore has forked the original LI-Calib tool and overwritten the Lidar input for more general usage. Information on how to use the tool, troubleshooting tips and example rosbags can be found at the LI-Calib fork on Github.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description/","title":"Creating vehicle and sensor description","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description/#creating-vehicle-and-sensor-description","title":"Creating vehicle and sensor description","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model/","title":"Creating vehicle interface for ackerman kinematic model","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model/#creating-vehicle-interface-for-ackerman-kinematic-model","title":"Creating vehicle interface for ackerman kinematic model","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/","title":"Customizing for differential drive vehicle","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#customizing-for-differential-drive-vehicle","title":"Customizing for differential drive vehicle","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#1-introduction","title":"1. Introduction","text":"

Currently, Autoware assumes that vehicles use an Ackermann kinematic model with Ackermann steering. Thus, Autoware adopts the Ackermann command format for the Control module's output (see the AckermannDrive ROS message definition for an overview of Ackermann commands, and the AckermannControlCommands struct used in Autoware for more details).

However, it is possible to integrate Autoware with a vehicle that follows a differential drive kinematic model, as commonly used by small mobile robots.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#2-procedure","title":"2. Procedure","text":"

One simple way of using Autoware with a differential drive vehicle is to create a vehicle_interface package that translates Ackermann commands to differential drive commands. Here are two points that you need to consider:

  • Create vehicle_interface package for differential drive vehicle
  • Set an appropriate wheel_base
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#21-create-a-vehicle_interface-package-for-differential-drive-vehicle","title":"2.1 Create a vehicle_interface package for differential drive vehicle","text":"

An Ackermann command in Autoware consists of two main control inputs:

  • steering angle (\\omega)
  • velocity (v)

Conversely, a typical differential drive command consists of the following inputs:

  • left wheel velocity (v_l)
  • right wheel velocity (v_r)

So, one way in which an Ackermann command can be converted to a differential drive command is by using the following equations:

v_l = v - \\frac{l\\omega}{2}, v_r = v + \\frac{l\\omega}{2}

where l denotes wheel tread.

For information about other factors that need to be considered when creating a vehicle_interface package, refer to the vehicle_interface component page.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#22-set-an-appropriate-wheel_base","title":"2.2 Set an appropriate wheel_base","text":"

A differential drive robot does not necessarily have front and rear wheels, which means that the wheelbase (the horizontal distance between the axles of the front and rear wheels) cannot be defined. However, Autoware expects wheel_base to be set in vehicle_info.param.yaml with some value. Thus, you need to set a pseudo value for wheel_base.

The appropriate pseudo value for wheel_base depends on the size of your vehicle. Setting it to be the same value as wheel_tread is one possible choice.

Warning

  • If the wheel_base value is set too small then the vehicle may behave unexpectedly. For example, the vehicle may drive beyond the bounds of a calculated path.
  • Conversely, if wheel_base is set too large, the vehicle's range of motion will be restricted. The reason being that Autoware's Planning module will calculate an overly conservative trajectory based on the assumed vehicle length.
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#3-known-issues","title":"3. Known issues","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#motion-model-incompatibility","title":"Motion model incompatibility","text":"

Since Autoware assumes that vehicles use a steering system, it is not possible to take advantage of the flexibility of a differential drive system's motion model.

For example, when planning a parking maneuver with the freespace_planner module, Autoware may drive the differential drive vehicle forward and backward, even if the vehicle can be parked with a simpler trajectory that uses pure rotational movement.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/","title":"Evaluating the controller performance","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#evaluating-the-controller-performance","title":"Evaluating the controller performance","text":"

This page shows how to use control_performance_analysis package to evaluate the controllers.

control_performance_analysis is the package to analyze the tracking performance of a control module and monitor the driving status of the vehicle.

If you need more detailed information about package, refer to the control_performance_analysis.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#how-to-use","title":"How to use","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#before-driving","title":"Before Driving","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#1-firstly-you-need-to-launch-autoware-you-can-also-use-this-tool-with-real-vehicle-driving","title":"1. Firstly you need to launch Autoware. You can also use this tool with real vehicle driving","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#2-initialize-the-vehicle-and-send-goal-position-to-create-route","title":"2. Initialize the vehicle and send goal position to create route","text":"
  • If you have any problem with launching Autoware, please see the tutorials page.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#3-launch-the-control_performance_analysis-package","title":"3. Launch the control_performance_analysis package","text":"
ros2 launch control_performance_analysis controller_performance_analysis.launch.xml\n
  • After this command, you should be able to see the driving monitor and error variables in topics.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#4-run-the-plotjuggler-in-sourced-terminal","title":"4. Run the PlotJuggler in sourced terminal","text":"
source ~/autoware/install/setup.bash\n
ros2 run plotjuggler plotjuggler\n
  • If you do not have PlotJuggler in your computer, please refer here for installation guideline.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#5-increase-the-buffer-size-maximum-is-100-and-import-the-layout-from-autowareuniversecontrolcontrol_performance_analysisconfigcontroller_monitorxml","title":"5. Increase the buffer size (maximum is 100), and import the layout from /autoware.universe/control/control_performance_analysis/config/controller_monitor.xml","text":"
  • After import the layout, please specify the topics that are listed below.
  • /localization/kinematic_state
  • /vehicle/status/steering_status
  • /control_performance/driving_status
  • /control_performance/performance_vars
  • Please mark the If present, use the timestamp in the field [header.stamp] box, then select the OK.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#6-now-you-can-start-to-driving-you-should-see-all-the-performance-and-driving-variables-in-plotjuggler","title":"6. Now, you can start to driving. You should see all the performance and driving variables in PlotJuggler","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#after-driving","title":"After Driving","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#1-you-can-export-the-statistical-output-and-all-data-to-compare-and-later-usage","title":"1. You can export the statistical output and all data to compare and later usage","text":"
  • With statistical data, you can export the all statistical values like (min, max, average) to compare the controllers.
  • You can also export all data to later use. To investigate them again, after launch PlotJuggler, import the .cvs file from data section.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#tips","title":"Tips","text":"
  • You can plot the vehicle position. Select the two curve (keeping CTRL key pressed) and Drag & Drop them using the RIGHT Mouse button. Please visit the Help -> Cheatsheet in PlotJuggler to see more tips about it.
  • If you see too much noised curve in plots, you can adjust the odom_interval and low_pass_filter_gain from here to avoid noised data.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/","title":"Evaluating real-time performance","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#evaluating-real-time-performance","title":"Evaluating real-time performance","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#introduction","title":"Introduction","text":"

Autoware should be real-time system when integrated to a service. Therefore, the response time of each callback should be as small as possible. If Autoware appears to be slow, it is imperative to conduct performance measurements and implement improvements based on the analysis. However, Autoware is a complex software system comprising numerous ROS 2 nodes, potentially complicating the process of identifying bottlenecks. To address this challenge, we will discuss methods for conducting detailed performance measurements for Autoware and provide case studies. It is worth noting that multiple factors can contribute to poor performance, such as scheduling and memory allocation in the OS layer, but our focus in this page will be on user code bottlenecks. The outline of this section is as follows:

  • Performance measurement
    • Single node execution
    • Prepare separated cores
    • Run single node separately
    • Measurement and visualization
  • Case studies
    • Sensing component
    • Planning component
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#performance-measurement","title":"Performance measurement","text":"

Improvement is impossible without precise measurements. To measure the performance of the application code, it is essential to eliminate any external influences. Such influences include interference from the operating system and CPU frequency fluctuations. Scheduling effects also occur when core resources are shared by multiple threads. This section outlines a technique for accurately measuring the performance of the application code for a specific node. Though this section only discusses the case of Linux on Intel CPUs, similar considerations should be made in other environments.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#single-node-execution","title":"Single node execution","text":"

To eliminate the influence of scheduling, the node being measured should operate independently, using the same logic as when the entire Autoware system is running. To accomplish this, record all input topics of the node to be measured while the whole Autoware system is running. To achieve this objective, a tool called ros2_single_node_replayer has been prepared.

Details on how to use the tool can be found in the README. This tool records the input topics of a specific node during the entire Autoware operation and replays it in a single node with the same logic. The tool relies on the ros2 bag record command, and the recording of service/action is not supported as of ROS 2 Humble, so nodes that use service/action as their main logic may not work well.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#prepare-separated-cores","title":"Prepare separated cores","text":"

Isolated cores running the node to be measured must meet the following conditions.

  • Fix CPU frequency and disable turbo boost
  • Minimize timer interruptions
  • Offload RCU (Read Copy Update) callback
  • Isolate the paired core if hyper-threading enabled

To fulfill these conditions on Linux, a custom kernel build with the following kernel configurations is required. You can find many resources to instruct you on how to build a custom Linux kernel (like this one). Note that even if full tickless is enabled, timer interrupts are generated for scheduling if more than two tasks exist in one core.

# Enable CONFIG_NO_HZ_FULL\n-> General setup\n-> Timers subsystem\n-> Timer tick handling (Full dynticks system (tickless))\n(X) Full dynticks system (tickless)\n\n# Allows RCU callback processing to be offloaded from selected CPUs\n# (CONFIG_RCU_NOCB_CPU=y)\n-> General setup\n-> RCU Subsystem\n-*- Offload RCU callback processing from boot-selected CPUs\n

Additionally, the kernel boot parameters need to be set as follows.

GRUB_CMDLINE_LINUX_DEFAULT=\n  \"... isolcpus=2,8 rcu_nocbs=2,8 rcu_nocb_poll nohz_full=2,8 intel_pstate=disable\u201d\n

In the above configuration, for example, the node to be measured is assumed to run on core 2, and core 8, which is a hyper-threading pair, is also being isolated. Appropriate decisions on which cores to run the measurement target and which nodes to isolate need to be made based on the cache and core layout of the measurement machine. You can easily check if it is properly configured by running cat /proc/softirqs. Since intel_pstate=disable is specified in the kernel boot parameter, userspace can be specified in the scaling governor.

cat /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor // ondemand\nsudo sh -c \"echo userspace > /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor\"\n

This allows you to freely set the desired frequency within a defined range.

sudo sh -c \"echo <freq(kz)> > /sys/devices/system/cpu/cpu2/cpufreq/scaling_setspeed\"\n

Turbo Boost needs to be switched off on Intel CPUs, which is often overlooked.

sudo sh -c \"echo 0 > /sys/devices/system/cpu/cpufreq/boost\"\n
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#run-single-node-separately","title":"Run single node separately","text":"

Following the instructions in the ros2_single_node_replayer README, start the node and play the dedicated rosbag created by the tool. Before playing the rosbag, appropriately set the CPU affinity of the thread on which the node runs, so it is placed on the isolated core prepared.

taskset --cpu-list -p <target cpu> <pid>\n

To avoid interference in the last level cache, minimize the number of other applications running during the measurement.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#measurement-and-visualization","title":"Measurement and visualization","text":"

To visualize the performance of the measurement target, embed code for logging timestamps and performance counter values in the target source code. To achieve this objective, a tool called pmu_analyzer has been prepared.

Details on how to use the tool can be found in the README. This tool can measure the turnaround time of any section in the source code, as well as various performance counters.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#case-studies","title":"Case studies","text":"

In this section, we will present several case studies that demonstrate the performance improvements. These examples not only showcase our commitment to enhancing the system's efficiency but also serve as a valuable resource for developers who may face similar challenges in their own projects. The performance improvements discussed here span various components of the Autoware system, including sensing modules and planning modules. There are tendencies for each component regarding which points are becoming bottlenecks. By examining the methods, techniques, and tools employed in these case studies, readers can gain a better understanding of the practical aspects of optimizing complex software systems like Autoware.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#sensing-component","title":"Sensing component","text":"

First, we will explain the procedure for performance improvement, taking the node ring_outlier_filter as an example. Refer to the Pull Request for details.

The following figure is a time-series plot of the turnaround time of the main processing part of ring_outlier_filter, analyzed as described in the \"Performance Measurement\" section above.

The horizontal axis indicates the number of callbacks called (i.e., callback index), and the vertical axis indicates the turnaround time.

When analyzing the performance of the sensing module from the viewpoint of performance counter, pay attention to instructions, LLC-load-misses, LLC-store-misses, cache-misses, and minor-faults.

Analysis of the performance counter shows that the largest fluctuations come from minor-faults (i.e., soft page faults), the second largest from LLC-store-misses and LLC-load-misses (i.e., cache misses in the last level cache), and the slowest fluctuations come from instructions (i.e., message data size fluctuations). For example, when we plot minor-faults on the horizontal axis and turnaround time on the vertical axis, we can see the following dominant proportional relationship.

To achieve zero soft page faults, heap allocations must only be made from areas that have been first touched in advance. We have developed a library called heaphook to avoid soft page faults while running Autoware callback. If you are interested, refer to the GitHub discussion and the issue.

To reduce LLC misses, it is necessary to reduce the working set and to use cache-efficient access patterns.

In the sensing component, which handles large message data such as LiDAR point cloud data, minimizing copying is important. A callback that takes sensor data message types as input and output should be written in an in-place algorithm as much as possible. This means that in the following pseudocode, when generating output_msg from input_msg, it is crucial to avoid using buffers as much as possible to reduce the number of memory copies.

void callback(const PointCloudMsg &input_msg) {\nauto output_msg = allocate_msg<PointCloudMsg>(output_size);\nfill(input_msg, output_msg);\npublish(std::move(output_msg));\n}\n

To improve cache efficiency, implement an in-place style as much as possible, instead of touching memory areas sporadically. In ROS applications using PCL, the code shown below is often seen.

void callback(const sensor_msgs::PointCloud2ConstPtr &input_msg) {\npcl::PointCloud<PointT>::Ptr input_pcl(new pcl::PointCloud<PointT>);\npcl::fromROSMsg(*input_msg, *input_pcl);\n\n// Algorithm is described for point cloud type of pcl\npcl::PointCloud<PointT>::Ptr output_pcl(new pcl::PointCloud<PointT>);\nfill_pcl(*input_pcl, *output_pcl);\n\nauto output_msg = allocate_msg<sensor_msgs::PointCloud2>(output_size);\npcl::toROSMsg(*output_pcl, *output_msg);\npublish(std::move(output_msg));\n}\n

To use the PCL library, fromROSMsg() and toROSMsg() are used to perform message type conversion at the beginning and end of the callback. This is a wasteful copying process and should be avoided. We should eliminate unnecessary type conversions by removing dependencies on PCL (e.g., https://github.com/tier4/velodyne_vls/pull/39). For large message types such as map data, there should be only one instance in the entire system in terms of physical memory.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#planning-component","title":"Planning component","text":"

First, we will pick up detection_area module in behavior_velocity_planner node, which tends to have long turnaround time. We have followed the performance analysis steps above to obtain the following graph. Axises are the same as the graphs in the sensing case study.

Using pmu_analyzer tool to further identify the bottleneck, we have found that the following multiple loops were taking up a lot of processing time:

for ( area : detection_areas )\nfor ( point : point_clouds )\nif ( boost::geometry::within(point, area) )\n// do something with O(1)\n

It checks whether each point cloud is contained in each detection area. Let N be the size of point_clouds and M be the size of detection_areas, then the computational complexity of this program is O(N^2 * M), since the complexity of within is O(N). Here, given that most of the point clouds are located far away from a certain detection area, a certain optimization can be achieved. First, calculate the minimum enclosing circle that completely covers the detection area, and then check whether the points are contained in that circle. Most of the point clouds can be quickly ruled out by this method, we don\u2019t have to call the within function in most cases. Below is the pseudocode after optimization.

for ( area : detection_areas )\ncircle = calc_minimum_enclosing_circle(area)\nfor ( point : point_clouds )\nif ( point is in circle )\nif ( boost::geometry::within(point, area) )\n// do something with O(1)\n

By using O(N) algorithm for minimum enclosing circle, the computational complexity of this program is reduced to almost O(N * (N + M)) (note that the exact computational complexity does not really change). If you are interested, refer to the Pull Request.

Similar to this example, in the planning component, we take into consideration thousands to tens of thousands of point clouds, thousands of points in a path representing our own route, and polygons representing obstacles and detection areas in the surroundings, and we repeatedly create paths based on them. Therefore, we access the contents of the point clouds and paths multiple times using for-loops. In most cases, the bottleneck lies in these naive for-loops. Here, understanding Big O notation and reducing the order of computational complexity directly leads to performance improvements.

"},{"location":"how-to-guides/others/add-a-custom-ros-message/","title":"Add a custom ROS message","text":""},{"location":"how-to-guides/others/add-a-custom-ros-message/#add-a-custom-ros-message","title":"Add a custom ROS message","text":""},{"location":"how-to-guides/others/add-a-custom-ros-message/#overview","title":"Overview","text":"

During the Autoware development, you will probably need to define your own messages. Read the following instructions before adding a custom message.

  1. Message in autoware_msgs define interfaces of Autoware Core.

    • If a contributor wishes to make changes or add new messages to autoware_msgs, they should first create a new discussion post under the Design category.

  2. Any other minor or proposal messages used for internal communication within a component(such as planning) should be defined in another repository.

    • tier4_autoware_msgs is an example of that.

The following is a simple tutorial of adding a message package to autoware_msgs. For the general ROS2 tutorial, see Create custom msg and srv files.

"},{"location":"how-to-guides/others/add-a-custom-ros-message/#how-to-create-custom-message","title":"How to create custom message","text":"

Make sure you are in the Autoware workspace, and then run the following command to create a new package. As an example, let's create a package to define sensor messages.

  1. Create a package

    cd ./src/core/autoware_msgs\nros2 pkg create --build-type ament_cmake autoware_sensing_msgs\n

  2. Create custom messages

    You should create .msg files and place them in the msg directory.

    NOTE: The initial letters of the .msg and .srv files must be capitalized.

    As an example, let's make .msg files GnssInsOrientation.msg and GnssInsOrientationStamped.msg to define GNSS/INS orientation messages:

    mkdir msg\ncd msg\ntouch GnssInsOrientation.msg\ntouch GnssInsOrientationStamped.msg\n

    Edit GnssInsOrientation.msg with your editor to be the following content:

    geometry_msgs/Quaternion orientation\nfloat32 rmse_rotation_x\nfloat32 rmse_rotation_y\nfloat32 rmse_rotation_z\n

    In this case, the custom message uses a message from another message package geometry_msgs/Quaternion.

    Edit GnssInsOrientationStamped.msg with your editor to be the following content:

    std_msgs/Header header\nGnssInsOrientation orientation\n

    In this case, the custom message uses a message from another message package std_msgs/Header.

  3. Edit CMakeLists.txt

    In order to use this custom message in C++ or Python languages, we need to add the following lines to CMakeList.txt:

    rosidl_generate_interfaces(${PROJECT_NAME}\n\"msg/GnssInsOrientation.msg\"\n\"msg/GnssInsOrientationStamped.msg\"\nDEPENDENCIES\ngeometry_msgs\nstd_msgs\nADD_LINTER_TESTS\n)\n

    The ament_cmake_auto tool is very useful and is more widely used in Autoware, so we recommend using ament_cmake_auto instead of ament_cmake.

    We need to replace

    find_package(ament_cmake REQUIRED)\n\nament_package()\n

    with

    find_package(ament_cmake_auto REQUIRED)\n\nament_auto_package()\n

  4. Edit package.xml

    We need to declare relevant dependencies in package.xml. For the above example we need to add the following content:

    <buildtool_depend>rosidl_default_generators</buildtool_depend>\n\n<exec_depend>rosidl_default_runtime</exec_depend>\n\n<depend>geometry_msgs</depend>\n<depend>std_msgs</depend>\n\n<member_of_group>rosidl_interface_packages</member_of_group>\n

    We need to replace <buildtool_depend>ament_cmake</buildtool_depend> with <buildtool_depend>ament_cmake_auto</buildtool_depend> in the package.xml file.

  5. Build the custom message package

    You can build the package in the root of your workspace, for example by running the following command:

    colcon build --packages-select autoware_sensing_msgs\n

    Now the GnssInsOrientationStamped message will be discoverable by other packages in Autoware.

"},{"location":"how-to-guides/others/add-a-custom-ros-message/#how-to-use-custom-messages-in-autoware","title":"How to use custom messages in Autoware","text":"

You can use the custom messages in Autoware by following these steps:

  • Add dependency in package.xml.
    • For example, <depend>autoware_sensing_msgs</depend>.
  • Include the .hpp file of the relevant message in the code.
    • For example, #include <autoware_sensing_msgs/msg/gnss_ins_orientation_stamped.hpp>.
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/","title":"Advanced usage of colcon","text":""},{"location":"how-to-guides/others/advanced-usage-of-colcon/#advanced-usage-of-colcon","title":"Advanced usage of colcon","text":"

This page shows some advanced and useful usage of colcon. If you need more detailed information, refer to the colcon documentation.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#common-mistakes","title":"Common mistakes","text":""},{"location":"how-to-guides/others/advanced-usage-of-colcon/#do-not-run-from-other-than-the-workspace-root","title":"Do not run from other than the workspace root","text":"

It is important that you always run colcon build from the workspace root because colcon builds only under the current directory. If you have mistakenly built in a wrong directory, run rm -rf build/ install/ log/ to clean the generated files.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#do-not-unnecessarily-overlay-workspaces","title":"Do not unnecessarily overlay workspaces","text":"

colcon overlays workspaces if you have sourced the setup.bash of other workspaces before building a workspace. You should take care of this especially when you have multiple workspaces.

Run echo $COLCON_PREFIX_PATH to check whether workspaces are overlaid. If you find some workspaces are unnecessarily overlaid, remove all built files, restart the terminal to clean environment variables, and re-build the workspace.

For more details about workspace overlaying, refer to the ROS 2 documentation.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#cleaning-up-the-build-artifacts","title":"Cleaning up the build artifacts","text":"

colcon sometimes causes errors of because of the old cache. To remove the cache and rebuild the workspace, run the following command:

rm -rf build/ install/\n

In case you know what packages to remove:

rm -rf {build,install}/{package_a,package_b}\n
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#selecting-packages-to-build","title":"Selecting packages to build","text":"

To just build specified packages:

colcon build --packages-select <package_name1> <package_name2> ...\n

To build specified packages and their dependencies recursively:

colcon build --packages-up-to <package_name1> <package_name2> ...\n

You can also use these options for colcon test.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#changing-the-optimization-level","title":"Changing the optimization level","text":"

Set DCMAKE_BUILD_TYPE to change the optimization level.

Warning

If you specify DCMAKE_BUILD_TYPE=Debug or no DCMAKE_BUILD_TYPE is given for building the entire Autoware, it may be too slow to use.

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug\n
colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo\n
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#changing-the-default-configuration-of-colcon","title":"Changing the default configuration of colcon","text":"

Create $COLCON_HOME/defaults.yaml to change the default configuration.

mkdir -p ~/.colcon\ncat << EOS > ~/.colcon/defaults.yaml\n{\n\"build\": {\n\"symlink-install\": true\n}\n}\n

For more details, see here.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#generating-compile_commandsjson","title":"Generating compile_commands.json","text":"

compile_commands.json is used by IDEs/tools to analyze the build dependencies and symbol relationships.

You can generate it with the flag DCMAKE_EXPORT_COMPILE_COMMANDS=1:

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1\n
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#seeing-compiler-commands","title":"Seeing compiler commands","text":"

To see the compiler and linker invocations for a package, use VERBOSE=1 and --event-handlers console_cohesion+:

VERBOSE=1 colcon build --packages-up-to <package_name> --event-handlers console_cohesion+\n

For other options, see here.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#using-ccache","title":"Using Ccache","text":"

Ccache can speed up recompilation. It is recommended to use it to save your time unless you have a specific reason not to do so.

  1. Install Ccache:

    sudo apt update && sudo apt install ccache\n

  2. Write the following in your .bashrc:

    export CC=\"/usr/lib/ccache/gcc\"\nexport CXX=\"/usr/lib/ccache/g++\"\n
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/","title":"Applying Clang-Tidy to ROS packages","text":""},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#applying-clang-tidy-to-ros-packages","title":"Applying Clang-Tidy to ROS packages","text":"

Clang-Tidy is a powerful C++ linter.

"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#preparation","title":"Preparation","text":"

You need to generate build/compile_commands.json before using Clang-Tidy.

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1\n
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#usage","title":"Usage","text":"
clang-tidy -p build/ path/to/file1 path/to/file2 ...\n

If you want to apply Clang-Tidy to all files in a package, using the fd command is useful. To install fd, see the installation manual.

clang-tidy -p build/ $(fd -e cpp -e hpp --full-path \"/autoware_utils/\")\n
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#ide-integration","title":"IDE integration","text":""},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#clion","title":"CLion","text":"

Refer to the CLion Documentation.

"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#visual-studio-code","title":"Visual Studio Code","text":"

Use either one of the following extensions:

  • C/C++
  • clangd
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#troubleshooting","title":"Troubleshooting","text":"

If you encounter clang-diagnostic-error, try installing libomp-dev.

Related: https://github.com/autowarefoundation/autoware-github-actions/pull/172

"},{"location":"how-to-guides/others/debug-autoware/","title":"Debug Autoware","text":""},{"location":"how-to-guides/others/debug-autoware/#debug-autoware","title":"Debug Autoware","text":"

This page provides some methods for debugging Autoware.

"},{"location":"how-to-guides/others/debug-autoware/#print-debug-messages","title":"Print debug messages","text":"

The essential thing for debug is to print the program information clearly, which can quickly judge the program operation and locate the problem. Autoware uses ROS 2 logging tool to print debug messages, how to design console logging refer to tutorial Console logging.

"},{"location":"how-to-guides/others/debug-autoware/#using-ros-tools-debug-autoware","title":"Using ROS tools debug Autoware","text":""},{"location":"how-to-guides/others/debug-autoware/#using-command-line-tools","title":"Using command line tools","text":"

ROS 2 includes a suite of command-line tools for introspecting a ROS 2 system. The main entry point for the tools is the command ros2, which itself has various sub-commands for introspecting and working with nodes, topics, services, and more. How to use the ROS 2 command line tool refer to tutorial CLI tools.

"},{"location":"how-to-guides/others/debug-autoware/#using-rviz2","title":"Using rviz2","text":"

Rviz2 is a port of Rviz to ROS 2. It provides a graphical interface for users to view their robot, sensor data, maps, and more. You can run Rviz2 tool easily by:

rviz2\n

When Autoware launch the simulators, the Rviz2 tool is opened by default to visualize the autopilot graphic information.

"},{"location":"how-to-guides/others/debug-autoware/#using-rqt-tools","title":"Using rqt tools","text":"

RQt is a graphical user interface framework that implements various tools and interfaces in the form of plugins. You can run any RQt tools/plugins easily by:

rqt\n

This GUI allows you to choose any available plugins on your system. You can also run plugins in standalone windows. For example, RQt Console:

ros2 run rqt_console rqt_console\n
"},{"location":"how-to-guides/others/debug-autoware/#common-rqt-tools","title":"Common RQt tools","text":"

  1. rqt_graph: view node interaction

    In complex applications, it may be helpful to get a visual representation of the ROS node interactions.

    ros2 run rqt_graph rqt_graph\n

  2. rqt_console: view messages

    rqt_console is a great gui for viewing ROS topics.

    ros2 run rqt_console rqt_console\n

  3. rqt_plot: view data plots

    rqt_plot is an easy way to plot ROS data in real time.

    ros2 run rqt_plot rqt_plot\n
"},{"location":"how-to-guides/others/debug-autoware/#using-ros2_graph","title":"Using ros2_graph","text":"

ros2_graph can be used to generate mermaid description of ROS 2 graphs to add on your markdown files.

It can also be used as a colorful alternative to rqt_graph even though it would require some tool to render the generated mermaid diagram.

It can be installed with:

pip install ros2-graph\n

Then you can generate a mermaid description of the graph with:

ros2_graph your_node\n\n# or like with an output file\nros2_graph /turtlesim -o turtle_diagram.md\n\n# or multiple nodes\nros2_graph /turtlesim /teleop_turtle\n

You can then visualize these graphs with:

  • Mermaid Live Editor
  • Visual Studio Code extension mermaid preview
  • JetBrains IDEs with native support
"},{"location":"how-to-guides/others/debug-autoware/#using-ros2doctor","title":"Using ros2doctor","text":"

When your ROS 2 setup is not running as expected, you can check its settings with the ros2doctor tool.

ros2doctor checks all aspects of ROS 2, including platform, version, network, environment, running systems and more, and warns you about possible errors and reasons for issues.

It's as simple as just running ros2 doctor in your terminal.

It has the ability to list \"Subscribers without publishers\" for all topics in the system.

And this information can help you find if a necessary node isn't running.

For more details, see the following official documentation for Using ros2doctor to identify issues.

"},{"location":"how-to-guides/others/debug-autoware/#using-a-debugger-with-breakpoints","title":"Using a debugger with breakpoints","text":"

Many IDE(e.g. Visual Studio Code, CLion) supports debugging C/C++ executable with GBD on linux platform. The following lists some references for using the debugger:

  • https://code.visualstudio.com/docs/cpp/cpp-debug
  • https://www.jetbrains.com/help/clion/debugging-code.html#useful-debugger-shortcuts
"},{"location":"how-to-guides/others/determining-component-dependencies/","title":"Determining component dependencies","text":""},{"location":"how-to-guides/others/determining-component-dependencies/#determining-component-dependencies","title":"Determining component dependencies","text":"

For any developers who wish to try and deploy Autoware as a microservices architecture, it is necessary to understand the software dependencies, communication, and implemented features of each ROS package/node.

As an example, the commands necessary to determine the dependencies for the Perception component are shown below.

"},{"location":"how-to-guides/others/determining-component-dependencies/#perception-component-dependencies","title":"Perception component dependencies","text":"

To generate a graph of package dependencies, use the following colcon command:

colcon graph --dot --packages-up-to tier4_perception_launch | dot -Tpng -o graph.png\n

To generate a list of dependencies, use:

colcon list --packages-up-to tier4_perception_launch --names-only\n
colcon list output 
autoware_auto_geometry_msgs\nautoware_auto_mapping_msgs\nautoware_auto_perception_msgs\nautoware_auto_planning_msgs\nautoware_auto_vehicle_msgs\nautoware_cmake\nautoware_lint_common\nautoware_point_types\ncompare_map_segmentation\ndetected_object_feature_remover\ndetected_object_validation\ndetection_by_tracker\neuclidean_cluster\ngrid_map_cmake_helpers\ngrid_map_core\ngrid_map_cv\ngrid_map_msgs\ngrid_map_pcl\ngrid_map_ros\nground_segmentation\nimage_projection_based_fusion\nimage_transport_decompressor\ninterpolation\nkalman_filter\nlanelet2_extension\nlidar_apollo_instance_segmentation\nmap_based_prediction\nmulti_object_tracker\nmussp\nobject_merger\nobject_range_splitter\noccupancy_grid_map_outlier_filter\npointcloud_preprocessor\npointcloud_to_laserscan\nshape_estimation\ntensorrt_yolo\ntier4_autoware_utils\ntier4_debug_msgs\ntier4_pcl_extensions\ntier4_perception_launch\ntier4_perception_msgs\ntraffic_light_classifier\ntraffic_light_map_based_detector\ntraffic_light_ssd_fine_detector\ntraffic_light_visualization\nvehicle_info_util\n

Tip

To output a list of modules with their respective paths, run the command above without the --names-only parameter.

To see which ROS topics are being subscribed and published to, use rqt_graph as follows:

ros2 launch tier4_perception_launch perception.launch.xml mode:=lidar\nros2 run rqt_graph rqt_graph\n
"},{"location":"how-to-guides/others/eagleye-integration-guide/","title":"Using Eagleye with Autoware","text":""},{"location":"how-to-guides/others/eagleye-integration-guide/#using-eagleye-with-autoware","title":"Using Eagleye with Autoware","text":"

This page will show you how to set up Eagleye in order to use it with Autoware. For the details of the integration proposal, please refer to this Discussion.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#what-is-eagleye","title":"What is Eagleye?","text":"

Eagleye is an open-source GNSS/IMU-based localizer initially developed by MAP IV. Inc. It provides a cost-effective alternative to LiDAR and point cloud-based localization by using low-cost GNSS and IMU sensors to provide vehicle position, orientation, and altitude information. By integrating Eagleye into Autoware, users can choose between LiDAR and point cloud-based localization stacks or GNSS/IMU-based Eagleye localizer, depending on their specific needs and operating environment.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#architecture","title":"Architecture","text":"

Eagleye can be utilized in the Autoware localization stack in two ways:

  1. Feed only twist into the EKF localizer.

  2. Feed both twist and pose from Eagleye into the EKF localizer (twist can also be used with regular gyro_odometry).

Note that RTK positioning is only required for localization using the Eagleye pose. RTK positioning is not required for twist.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#requirements","title":"Requirements","text":"

GNSS/IMU/vehicle speed is required for Eagleye input.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#imu-topic","title":"IMU topic","text":"

sensor_msgs/msg/Imu are supported for IMU.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#vehicle-speed-topic","title":"Vehicle speed topic","text":"

geometry_msgs/msg/TwistStamped and geometry_msgs/msg/TwistWithCovarianceStamped are supported for the input vehicle speed.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#gnss-topic","title":"GNSS topic","text":"

Eagleye requires latitude/longitude height information and velocity information generated by the GNSS receiver. Your GNSS ROS driver must publish the following messages:

  • sensor_msgs/msg/NavSatFix: This message contains latitude, longitude, and height information.
  • geometry_msgs/msg/TwistWithCovarianceStamped: This message contains gnss doppler velocity information.

Eagleye has been tested with the following example GNSS ROS drivers: ublox_gps and septentrio_gnss_driver. The settings needed for each of these drivers are as follows:

  • ublox_gps: This ROS driver publishes sensor_msgs/msg/NavSatFix and geometry_msgs/msg/TwistWithCovarianceStamped required by Eagleye with default settings. Therefore, no additional settings are required.
  • septentrio_gnss_driver: Set publish.navsatfix and publish.twist in the config file gnss.yaml to true
"},{"location":"how-to-guides/others/eagleye-integration-guide/#eagleye-setup","title":"Eagleye Setup","text":""},{"location":"how-to-guides/others/eagleye-integration-guide/#install-dependencies","title":"Install dependencies","text":"

Clone the following three packages for Eagleye:

  1. Eagleye (autoware-main branch)
  2. RTKLIB ROS Bridge (ros2-v0.1.0 branch)
  3. LLH Converter (ros2 branch)
"},{"location":"how-to-guides/others/eagleye-integration-guide/#modifying-autoware-launch-files","title":"Modifying Autoware Launch files","text":"

You need to install Eagleye-related packages and change Autoware's launcher. Four files are required in the Autoware localization launcher to run Eagleye: eagleye_rt.launch.xml, eagleye_config.yaml, gnss_converter.launch.xml, and fix2pose.launch.xml.

You must correctly specify input topics for GNSS latitude, longitude, and height information, GNSS speed information, IMU information, and vehicle speed information in the eagleye_config.yaml.

# Topic\ntwist:\ntwist_type: 1 # TwistStamped : 0, TwistWithCovarianceStamped: 1\ntwist_topic: /sensing/vehicle_velocity_converter/twist_with_covariance\nimu_topic: /sensing/imu/tamagawa/imu_raw\ngnss:\nvelocity_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, ublox_msgs/NavPVT: 2, geometry_msgs/TwistWithCovarianceStamped: 3\nvelocity_source_topic: /sensing/gnss/ublox/navpvt\nllh_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, sensor_msgs/NavSatFix: 2\nllh_source_topic: /sensing/gnss/ublox/nav_sat_fix\n

Also, the frequency of GNSS and IMU must be set in eagleye_config.yaml

common:\nimu_rate: 50\ngnss_rate: 5\n

The basic parameters that do not need to be changed except those mentioned above, i.e., topic names and sensors' frequency, are described below here. Additionally, the parameters for converting sensor_msgs/msg/NavSatFix to geometry_msgs/msg/PoseWithCovarianceStamped is listed in fix2pose.yaml.

Please refer to map4_localization_launch in the autoware.universe package and map4_localization_component.launch.xml in autoware_launch package for information on how to modify the localization launch.

Eagleye has a function for position estimation and a function for twist estimation, namely pose_estimator and twist_estimator, respectively.

localization launch twist estimator pose estimator tier4_localization_launch gyro_odometry ndt_scan_matcher map4_localization_launch/eagleye_twist_localization_launch eagleye_rt(gyro/odom/gnss fusion) ndt_scan_matcher map4_localization_launch/eagleye_pose_twist_localization_launch eagleye_rt(gyro/odom/gnss fusion) eagleye_rt(gyro/odom/gnss fusion)

In Autoware, you can set the pose estimator to GNSS by setting pose_estimator_mode:=gnss in map4_localization_component.launch.xml in autoware_launch package. Note that the output position might not appear to be in the point cloud maps if you are using maps that are not properly georeferenced. In the case of a single GNSS antenna, initial position estimation (dynamic initialization) can take several seconds to complete after starting to run in an environment where GNSS positioning is available.

Alternatively, the twist estimator can be set to Eagleye and the pose estimator to NDT by specifying pose_estimator_mode:=lidar in the same launch file. Unlike Eagleye position estimation, Eagleye twist estimation first outputs uncorrected raw values when activated, and then outputs corrected twists as soon as static initialization is complete.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#executing-launch-files","title":"Executing Launch files","text":""},{"location":"how-to-guides/others/eagleye-integration-guide/#execution-command","title":"Execution command","text":"

Enable Eagleye in Autoware by switching the localization module in autoware.launch.xml and the pose_estimator_mode parameter in map4_localization_component.launch.xml in autoware.launch.xml.

When using Eagleye, comment out tier4_localization_component.launch.xml and start map4_localization_component.launch.xml in autoware.launch.xml.

  <!-- Localization -->\n<group if=\"$(var launch_localization)\">\n<!-- <include file=\"$(find-pkg-share autoware_launch)/launch/components/tier4_localization_component.launch.xml\"/> -->\n<include file=\"$(find-pkg-share autoware_launch)/launch/components/map4_localization_component.launch.xml\"/>\n</group>\n
"},{"location":"how-to-guides/others/eagleye-integration-guide/#notes-with-initialization","title":"Notes with initialization","text":"

Eagleye requires an initialization process for proper operation. Without initialization, the output for twist will be in the raw value, and the pose data will not be available.

The first step is static initialization, which involves allowing the Eagleye to remain stationary for approximately 5 seconds after startup to estimate the yaw-rate offset.

The next step is dynamic initialization, which involves running the Eagleye in a straight line for approximately 30 seconds. This process estimates the scale factor of wheel speed and azimuth angle. Once dynamic initialization is complete, the Eagleye will be able to provide corrected twist and pose data.

"},{"location":"how-to-guides/others/fixing-dependent-package-versions/","title":"Fixing dependent package versions","text":""},{"location":"how-to-guides/others/fixing-dependent-package-versions/#fixing-dependent-package-versions","title":"Fixing dependent package versions","text":"

Autoware manages dependent package versions in autoware.repos. For example, let's say you make a branch in autoware.universe and add new features. Suppose you update other dependencies with vcs pull after cutting a branch from autoware.universe. Then the version of autoware.universe you are developing and other dependencies will become inconsistent, and the entire Autoware build will fail. We recommend saving the dependent package versions by executing the following command when starting the development.

vcs export src --exact > my_autoware.repos\n
"},{"location":"how-to-guides/others/running-autoware-without-cuda/","title":"Running Autoware without CUDA","text":""},{"location":"how-to-guides/others/running-autoware-without-cuda/#running-autoware-without-cuda","title":"Running Autoware without CUDA","text":"

Although CUDA installation is recommended to achieve better performance for object detection and traffic light recognition in Autoware Universe, it is possible to run these algorithms without CUDA. The following subsections briefly explain how to run each algorithm in such an environment.

"},{"location":"how-to-guides/others/running-autoware-without-cuda/#running-2d3d-object-detection-without-cuda","title":"Running 2D/3D object detection without CUDA","text":"

Autoware Universe's object detection can be run using one of five possible configurations:

  • lidar_centerpoint
  • lidar_apollo_instance_segmentation
  • lidar-apollo + tensorrt_yolo
  • lidar-centerpoint + tensorrt_yolo
  • euclidean_cluster

Of these five configurations, only the last one (euclidean_cluster) can be run without CUDA. For more details, refer to the euclidean_cluster module's README file.

"},{"location":"how-to-guides/others/running-autoware-without-cuda/#running-traffic-light-detection-without-cuda","title":"Running traffic light detection without CUDA","text":"

For traffic light recognition (both detection and classification), there are two modules that require CUDA:

  • traffic_light_ssd_fine_detector
  • traffic_light_classifier

To run traffic light detection without CUDA, set enable_fine_detection to false in the traffic light launch file. Doing so disables the traffic_light_ssd_fine_detector such that traffic light detection is handled by the map_based_traffic_light_detector module instead.

To run traffic light classification without CUDA, set use_gpu to false in the traffic light classifier launch file. Doing so will force the traffic_light_classifier to use a different classification algorithm that does not require CUDA or a GPU.

"},{"location":"installation/","title":"Installation","text":""},{"location":"installation/#installation","title":"Installation","text":""},{"location":"installation/#target-platforms","title":"Target platforms","text":"

Autoware targets the platforms listed below. It may change in future versions of Autoware.

The Autoware Foundation provides no support on other platforms than those listed below.

"},{"location":"installation/#architecture","title":"Architecture","text":"
  • amd64
  • arm64
"},{"location":"installation/#minimum-hardware-requirements","title":"Minimum hardware requirements","text":"

Info

Autoware is scalable and can be customized to work with distributed or less powerful hardware. The minimum hardware requirements given below are just a general recommendation. However, performance will be improved with more cores, RAM and a higher-spec graphics card or GPU core.

  • CPU with 8 cores
  • 16GB RAM
  • [Optional] NVIDIA GPU (4GB RAM)

Although GPU is not required to run basic functionality, it is mandatory to enable the following neural network related functions:

  • LiDAR based object detection
  • Camera based object detection
  • Traffic light detection and classification

For details of how to enable object detection and traffic light detection/classification without a GPU, refer to the Running Autoware without CUDA.

"},{"location":"installation/#installing-autoware","title":"Installing Autoware","text":"

There are two ways to set up Autoware. Choose one according to your preference.

If any issues occur during installation, refer to the Support page.

"},{"location":"installation/#1-docker-installation","title":"1. Docker installation","text":"

Docker can ensure that all developers in a project have a common, consistent development environment. It is recommended for beginners, casual users, people who are unfamiliar with Ubuntu.

For more information, refer to the Docker installation guide.

"},{"location":"installation/#2-source-installation","title":"2. Source installation","text":"

Source installation is for the cases where more granular control of the installation environment is needed. It is recommended for experienced users or people who want to customize their environment. Note that some problems may occur depending on your local environment.

For more information, refer to the source installation guide.

"},{"location":"installation/#installing-related-tools","title":"Installing related tools","text":"

Some other tools are required depending on the evaluation you want to do. For example, to run an end-to-end simulation you need to install an appropriate simulator.

For more information, see here.

"},{"location":"installation/#additional-settings-for-developers","title":"Additional settings for developers","text":"

There are also tools and settings for developers, such as Shells or IDEs.

For more information, see here.

"},{"location":"installation/additional-settings-for-developers/","title":"Additional settings for developers","text":""},{"location":"installation/additional-settings-for-developers/#additional-settings-for-developers","title":"Additional settings for developers","text":""},{"location":"installation/additional-settings-for-developers/#console-settings-for-ros-2","title":"Console settings for ROS 2","text":""},{"location":"installation/additional-settings-for-developers/#colorizing-logger-output","title":"Colorizing logger output","text":"

By default, ROS 2 logger doesn't colorize the output. To colorize it, write the following in your .bashrc:

export RCUTILS_COLORIZED_OUTPUT=1\n
"},{"location":"installation/additional-settings-for-developers/#customizing-the-format-of-logger-output","title":"Customizing the format of logger output","text":"

By default, ROS 2 logger doesn't output detailed information such as file name, function name, or line number. To customize it, write the following in your .bashrc:

export RCUTILS_CONSOLE_OUTPUT_FORMAT=\"[{severity} {time}] [{name}]: {message} ({function_name}() at {file_name}:{line_number})\"\n

For more options, see here.

"},{"location":"installation/additional-settings-for-developers/#network-settings-for-ros-2","title":"Network settings for ROS 2","text":"

ROS 2 employs DDS, and the configuration of ROS 2 and DDS is described separately. For ROS 2 networking concepts, refer to the official documentation.

"},{"location":"installation/additional-settings-for-developers/#ros-2-network-setting","title":"ROS 2 network setting","text":"

ROS 2 multicasts data on the local network by default. Therefore, when you develop in an office, the data flows over the local network of your office. It may cause collisions of packets or increases in network traffic.

To avoid these, there are two options.

  • Localhost-only communication
  • Same domain only communication on the local network

Unless you plan to use multiple host computers on the local network, localhost-only communication is recommended. For details, refer to the sections below.

"},{"location":"installation/additional-settings-for-developers/#enabling-localhost-only-communication","title":"Enabling localhost-only communication","text":"

Write the following in your .bashrc: For more information, see the ROS 2 documentation.

export ROS_LOCALHOST_ONLY=1\n

If you export ROS_LOCALHOST_ONLY=1, MULTICAST must be enabled at the loopback address. To verify that MULTICAST is enabled, use the following command.

$ ip link show lo\n1: lo: <LOOPBACK,MULTICAST,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000\n

If the word MULTICAST is not printed, use the following command to enable it.

sudo ip link set lo multicast on\n
"},{"location":"installation/additional-settings-for-developers/#same-domain-only-communication-on-the-local-network","title":"Same domain only communication on the local network","text":"

ROS 2 uses ROS_DOMAIN_ID to create groups and communicate between machines in the groups. Since all ROS 2 nodes use domain ID 0 by default, it may cause unintended interference.

To avoid it, set a different domain ID for each group in your .bashrc:

# Replace X with the Domain ID you want to use\n# Domain ID should be a number in range [0, 101] (inclusive)\nexport ROS_DOMAIN_ID=X\n

Also confirm that ROS_LOCALHOST_ONLY is 0 by using the following command.

echo $ROS_LOCALHOST_ONLY # If the output is 1, localhost has priority.\n

For more information, see the ROS 2 Documentation.

"},{"location":"installation/additional-settings-for-developers/#dds-settings","title":"DDS settings","text":"

Autoware uses DDS for inter-node communication. ROS 2 documentation recommends users to tune DDS to utilize its capability. Especially, receive buffer size is the critical parameter for Autoware. If the parameter is not large enough, Autoware will failed in receiving large data like point cloud or image.

"},{"location":"installation/additional-settings-for-developers/#tuning-dds","title":"Tuning DDS","text":"

Unless customized, CycloneDDS is adopted by default. For example, to execute Autoware with CycloneDDS, prepare a config file. A sample config file is given below. Save it as cyclonedds_config.xml.

<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n<CycloneDDS xmlns=\"https://cdds.io/config\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd\">\n<Domain Id=\"any\">\n<General>\n<Interfaces>\n<NetworkInterface autodetermine=\"true\" priority=\"default\" multicast=\"default\" />\n</Interfaces>\n<AllowMulticast>default</AllowMulticast>\n<MaxMessageSize>65500B</MaxMessageSize>\n</General>\n<Internal>\n<SocketReceiveBufferSize min=\"10MB\"/>\n<Watermarks>\n<WhcHigh>500kB</WhcHigh>\n</Watermarks>\n</Internal>\n</Domain>\n</CycloneDDS>\n

This configuration is mostly taken from Eclipse Cyclone DDS:Run-time configuration documentation. You can see why each value is set as such under the documentation link.

Set the config file path and enlarge the Linux kernel maximum buffer size before launching Autoware.

export CYCLONEDDS_URI=file:///absolute/path/to/cyclonedds_config.xml\nsudo sysctl -w net.core.rmem_max=2147483647\n

For more information, Refer to ROS 2 documentation. Reading user guide for chosen DDS is helpful for more understanding.

"},{"location":"installation/additional-settings-for-developers/#tuning-dds-for-multiple-host-computers-for-advanced-users","title":"Tuning DDS for multiple host computers (for advanced users)","text":"

When Autoware runs on multiple host computers, IP Fragmentation should be taken into account. As ROS 2 documentation recommends, parameters for IP Fragmentation should be set as shown in the following example.

sudo sysctl -w net.ipv4.ipfrag_time=3\nsudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728     # (128 MB)\n
"},{"location":"installation/autoware/docker-installation-devel/","title":"Docker installation for development","text":""},{"location":"installation/autoware/docker-installation-devel/#docker-installation-for-development","title":"Docker installation for development","text":""},{"location":"installation/autoware/docker-installation-devel/#prerequisites","title":"Prerequisites","text":"
  • Git
  • For NVIDIA Jetson devices, install JetPack >= 5.0
"},{"location":"installation/autoware/docker-installation-devel/#how-to-set-up-a-development-environment","title":"How to set up a development environment","text":"

  1. Clone autowarefoundation/autoware and move to the directory.

    git clone https://github.com/autowarefoundation/autoware.git\ncd autoware\n

  2. You can install the dependencies either manually or using the provided Ansible script.

Note: Before installing NVIDIA libraries, confirm and agree with the licenses.

  • CUDA
"},{"location":"installation/autoware/docker-installation-devel/#installing-dependencies-manually","title":"Installing dependencies manually","text":"
  • Install Nvidia CUDA
  • Install Docker Engine
  • Install NVIDIA Container Toolkit
  • Install rocker
"},{"location":"installation/autoware/docker-installation-devel/#installing-dependencies-using-ansible","title":"Installing dependencies using Ansible","text":"

Be very careful with this method. Make sure you read and confirmed all the steps in the Ansible configuration before using it.

If you've manually installed the dependencies, you can skip this section.

./setup-dev-env.sh docker\n

You might need to log out and log back to make the current user able to use docker.

"},{"location":"installation/autoware/docker-installation-devel/#how-to-set-up-a-workspace","title":"How to set up a workspace","text":"

Warning

Before proceeding, confirm and agree with the NVIDIA Deep Learning Container license. By pulling and using the Autoware Universe images, you accept the terms and conditions of the license.

  1. Create the autoware_map directory for map data later.

    mkdir ~/autoware_map\n

  2. Pull the Docker image

    docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

  3. Launch a Docker container.

    • For amd64 architecture computers with NVIDIA GPU:

      rocker --nvidia --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

    • If you want to run container without using NVIDIA GPU, or for arm64 architecture computers:

      rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

      For detailed reason could be found here

    For more advanced usage, see here.

    After that, move to the workspace in the container:

    cd autoware\n

  4. Create the src directory and clone repositories into it.

    mkdir src\nvcs import src < autoware.repos\n

  5. Update dependent ROS packages.

    The dependency of Autoware may change after the Docker image was created. In that case, you need to run the following commands to update the dependency.

    sudo apt update\nrosdep update\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  6. Build the workspace.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

    If there is any build issue, refer to Troubleshooting.

"},{"location":"installation/autoware/docker-installation-devel/#how-to-update-a-workspace","title":"How to update a workspace","text":"

  1. Update the Docker image.

    docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

  2. Launch a Docker container.

    • For amd64 architecture computers:

      rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

    • If you want to run container without using NVIDIA GPU, or for arm64 architecture computers:

      rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

  3. Update the .repos file.

    cd autoware\ngit pull\n

  4. Update the repositories.

    vcs import src < autoware.repos\nvcs pull src\n

  5. Build the workspace.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"installation/autoware/docker-installation-prebuilt/","title":"Docker installation for quick start","text":""},{"location":"installation/autoware/docker-installation-prebuilt/#docker-installation-for-quick-start","title":"Docker installation for quick start","text":""},{"location":"installation/autoware/docker-installation-prebuilt/#how-to-set-up-a-development-environment","title":"How to set up a development environment","text":"

  1. Installing dependencies manually

    • Install Docker Engine
    • Install NVIDIA Container Toolkit
    • Install rocker
"},{"location":"installation/autoware/docker-installation-prebuilt/#how-to-set-up-a-workspace","title":"How to set up a workspace","text":"

  1. Create the autoware_map directory for map data later.

    mkdir ~/autoware_map\n

  2. Launch a Docker container.

    rocker --nvidia --x11 --user --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-prebuilt\n

    For more advanced usage, see here.

  3. Run Autoware simulator

    Inside the container, you can run the Autoware simulation by following this tutorial:

    planning simulation

    rosbag replay simulation.

"},{"location":"installation/autoware/docker-installation/","title":"Docker installation","text":""},{"location":"installation/autoware/docker-installation/#docker-installation","title":"Docker installation","text":"

Info

Since this page explains Docker-specific information, it is recommended to see Source installation as well if you need detailed information.

Here are two ways to install Autoware by docker:

  • The first way is to start Autoware with prebuilt image, this is a quick start, this way you can only run Autoware simulator and not develop Autoware, it is only suitable for beginners
  • The second way is to start Autoware with devel image, which supports developing and running Autoware using docker
"},{"location":"installation/autoware/docker-installation/#docker-installation-for-quick-start","title":"Docker installation for quick start","text":"

docker installation for quick start

"},{"location":"installation/autoware/docker-installation/#docker-installation-for-development","title":"Docker installation for development","text":"

docker installation for development

"},{"location":"installation/autoware/docker-installation/#troubleshooting","title":"Troubleshooting","text":"

Here are solutions for a few specific errors:

"},{"location":"installation/autoware/docker-installation/#cuda-error-forward-compatibility-was-attempted-on-non-supported-hw","title":"cuda error: forward compatibility was attempted on non supported hw","text":"

When starting Docker with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error:

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.\nERROR: Command return non-zero exit code (see above): 125\n

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.

"},{"location":"installation/autoware/docker-installation/#docker-with-nvidia-gpu-fails-to-start-autoware-on-arm64-devices","title":"Docker with NVIDIA gpu fails to start Autoware on arm64 devices","text":"

When starting Docker with GPU support enabled for NVIDIA graphics on arm64 devices, e.g. NVIDIA jetson AGX xavier, you may receive the following error:

nvidia@xavier:~$ rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64\n...\n\nCollecting staticx==0.12.3\nDownloading https://files.pythonhosted.org/packages/92/ff/d9960ea1f9db48d6044a24ee0f3d78d07bcaddf96eb0c0e8806f941fb7d3/staticx-0.12.3.tar.gz (68kB)\nComplete output from command python setup.py egg_info:\nTraceback (most recent call last):\nFile \"\", line 1, in\nFile \"/tmp/pip-install-m_nm8mya/staticx/setup.py\", line 4, in\nfrom wheel.bdist_wheel import bdist_wheel\nModuleNotFoundError: No module named 'wheel'\n\nCommand \"python setup.py egg_info\" failed with error code 1 in /tmp/pip-install-m_nm8mya/staticx/\n...\n

This error exists in current version of rocker tool, which relates to the os_detection function of rocker.

To fix this error, temporary modification of rocker source code is required, which is not recommended.

At current stage, it is recommended to run docker without NVIDIA gpu enabled for arm64 devices:

rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

This tutorial will be updated after official fix from rocker.

"},{"location":"installation/autoware/docker-installation/#tips","title":"Tips","text":""},{"location":"installation/autoware/docker-installation/#non-native-arm64-system","title":"Non-native arm64 System","text":"

This section describes a process to run arm64 systems on amd64 systems using qemu-user-static.

Initially, your system is usually incompatible with arm64 systems. To check that:

$ docker run --rm -t arm64v8/ubuntu uname -m\nWARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested\nstandard_init_linux.go:228: exec user process caused: exec format error\n

Installing qemu-user-static enables us to run arm64 images on amd64 systems.

$ sudo apt-get install qemu-user-static\n$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes\n$ docker run --rm -t arm64v8/ubuntu uname -m\nWARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested\naarch64\n

To run Autoware's Docker images of arm64 architecture, add the suffix -arm64.

$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64\nWARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested\nroot@5b71391ad50f:/autoware#\n
"},{"location":"installation/autoware/source-installation/","title":"Source installation","text":""},{"location":"installation/autoware/source-installation/#source-installation","title":"Source installation","text":""},{"location":"installation/autoware/source-installation/#prerequisites","title":"Prerequisites","text":"

  • OS

    • Ubuntu 22.04

  • ROS

    • ROS 2 Humble

    For ROS 2 system dependencies, refer to REP-2000.

  • Git
    • Registering SSH keys to GitHub is preferable.
sudo apt-get -y update\nsudo apt-get -y install git\n

Note: If you wish to use ROS 2 Galactic on Ubuntu 20.04, refer to installation instruction from galactic branch, but be aware that Galactic version of Autoware might not have latest features.

"},{"location":"installation/autoware/source-installation/#how-to-set-up-a-development-environment","title":"How to set up a development environment","text":"

  1. Clone autowarefoundation/autoware and move to the directory.

    git clone https://github.com/autowarefoundation/autoware.git\ncd autoware\n

  2. If you are installing Autoware for the first time, you can automatically install the dependencies by using the provided Ansible script.

    ./setup-dev-env.sh\n

    If you encounter any build issues, please consult the Troubleshooting section for assistance.

Info

Before installing NVIDIA libraries, please ensure that you have reviewed and agreed to the licenses.

  • CUDA
  • cuDNN
  • TensorRT

Note

The following items will be automatically installed. If the ansible script doesn't work or if you already have different versions of dependent libraries installed, please install the following items manually.

  • Install ROS 2
  • Install ROS 2 Dev Tools
  • Install the RMW Implementation
  • Install pacmod
  • Install Autoware Core dependencies
  • Install Autoware Universe dependencies
  • Install pre-commit dependencies
  • Install Nvidia CUDA
  • Install Nvidia cuDNN and TensorRT
"},{"location":"installation/autoware/source-installation/#how-to-set-up-a-workspace","title":"How to set up a workspace","text":"

  1. Create the src directory and clone repositories into it.

    Autoware uses vcstool to construct workspaces.

    cd autoware\nmkdir src\nvcs import src < autoware.repos\n

  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. You might need to run rosdep update before rosdep install.

    source /opt/ros/humble/setup.bash\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  3. Build the workspace.

    Autoware uses colcon to build workspaces. For more advanced options, refer to the documentation.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

    If there is any build issue, refer to Troubleshooting.

"},{"location":"installation/autoware/source-installation/#how-to-update-a-workspace","title":"How to update a workspace","text":"

  1. Update the .repos file.

    cd autoware\ngit pull\n

  2. Update the repositories.

    vcs import src < autoware.repos\nvcs pull src\n

    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.

    For more information, refer to the official documentation.

  3. Install dependent ROS packages.

    source /opt/ros/humble/setup.bash\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  4. Build the workspace.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"installation/related-tools/","title":"Installation of related tools","text":""},{"location":"installation/related-tools/#installation-of-related-tools","title":"Installation of related tools","text":"

Warning

Under Construction

"},{"location":"support/","title":"Support","text":""},{"location":"support/#support","title":"Support","text":"

This page explains several support resources.

  • Support guidelines pages explain the support mechanisms and guidelines.
  • Troubleshooting pages explain solutions for common issues.
  • Docs guide pages explain related documentation sites.
"},{"location":"support/docs-guide/","title":"Docs guide","text":""},{"location":"support/docs-guide/#docs-guide","title":"Docs guide","text":"

This page explains several documentation sites that are useful for Autoware and ROS development.

  • The Autoware Foundation is the official site of the Autoware Foundation. You can learn about the Autoware community here.
  • Autoware Documentation (this site) is the central documentation site for Autoware maintained by the Autoware community. General software-related information of Autoware is aggregated here.
  • Autoware Universe Documentation has READMEs and design documents of software components.
  • ROS Docs Guide explains the ROS 1 and ROS 2 documentation infrastructure.
"},{"location":"support/support-guidelines/","title":"Support guidelines","text":""},{"location":"support/support-guidelines/#support-guidelines","title":"Support guidelines","text":"

This page explains the support mechanisms we provide.

Warning

Before asking for help, search and read this documentation site carefully. Also, follow the discussion guidelines for discussions.

Choose appropriate resources depending on what kind of help you need and read the detailed description in the sections below.

  • Documentation sites
    • Various information
  • GitHub Discussions
    • Questions
    • Unconfirmed bugs
    • Feature requests
    • Design discussions
  • GitHub Issues
    • Confirmed bugs
  • Discord
    • Instant messaging between contributors
  • ROS Discourse
    • General topics that should be widely announced
"},{"location":"support/support-guidelines/#documentation-sites","title":"Documentation sites","text":"

Docs guide shows the list of useful documentation sites. Visit them and see if there is any information related to your problem.

Note that the documentation sites aren't always up-to-date and perfect. If you find out that some information is wrong, unclear, or missing in Autoware docs, feel free to submit a pull request following the contribution guidelines.

Warning

Since this documentation site is still under construction, there are some empty pages.

"},{"location":"support/support-guidelines/#github-discussions","title":"GitHub Discussions","text":"

If you encounter a problem with Autoware, check existing issues and questions and search for similar issues first.

  • Issues

    Note that Autoware has multiple repositories listed in autoware.repos. It is recommended to search across the repositories.

  • Questions

If no answer was found, create a new question thread here. If your question is not answered within a week, then @mention the maintainers to remind them.

Also, there are other discussion types such as feature requests or design discussions. Feel free to open or join such discussions.

If you don't know how to create a discussion, refer to GitHub Docs.

"},{"location":"support/support-guidelines/#github-issues","title":"GitHub Issues","text":"

If you have a problem and you have confirmed it is a bug, find the appropriate repository and create a new issue there. If you can't determine the appropriate repository, ask the maintainers for help by creating a new discussion in the Q&A category.

Warning

Do not create issues for questions or unconfirmed bugs. If such issues are created, maintainers will transfer them to GitHub Discussions.

If you want to fix the bug by yourself, discuss the approach with maintainers and submit a pull request.

"},{"location":"support/support-guidelines/#discord","title":"Discord","text":"

Autoware has a Discord server for casual communication between contributors.

The Autoware Discord server is a good place for the following activities:

  • Introduce yourself to the community.
  • Chat with contributors.
  • Take a quick straw poll.

Note that it is not the right place to get help for your issues.

"},{"location":"support/support-guidelines/#ros-discourse","title":"ROS Discourse","text":"

If you want to widely discuss a topic with the general Autoware and ROS community or ask a question not related to Autoware's bugs, post to the Autoware category on ROS Discourse.

Warning

Do not post questions about bugs to ROS Discourse!

"},{"location":"support/troubleshooting/","title":"Troubleshooting","text":""},{"location":"support/troubleshooting/#troubleshooting","title":"Troubleshooting","text":""},{"location":"support/troubleshooting/#setup-issues","title":"Setup issues","text":""},{"location":"support/troubleshooting/#cuda-related-errors","title":"CUDA-related errors","text":"

When installing CUDA, errors may occur because of version conflicts. To resolve these types of errors, try one of the following methods:

  • Unhold all CUDA-related libraries and rerun the setup script.

    sudo apt-mark unhold  \\\n\"cuda*\"             \\\n\"libcudnn*\"         \\\n\"libnvinfer*\"       \\\n\"libnvonnxparsers*\" \\\n\"libnvparsers*\"     \\\n\"tensorrt*\"         \\\n\"nvidia*\"\n\n./setup-dev-env.sh\n

  • Uninstall all CUDA-related libraries and rerun the setup script.

    sudo apt purge        \\\n\"cuda*\"             \\\n\"libcudnn*\"         \\\n\"libnvinfer*\"       \\\n\"libnvonnxparsers*\" \\\n\"libnvparsers*\"     \\\n\"tensorrt*\"         \\\n\"nvidia*\"\n\nsudo apt autoremove\n\n./setup-dev-env.sh\n

Warning

Note that this may break your system and run carefully.

  • Run the setup script without installing CUDA-related libraries.

    ./setup-dev-env.sh --no-nvidia\n

Warning

Note that some components in Autoware Universe require CUDA, and only the CUDA version in the env file is supported at this time. Autoware may work with other CUDA versions, but those versions are not supported and functionality is not guaranteed.

"},{"location":"support/troubleshooting/#build-issues","title":"Build issues","text":""},{"location":"support/troubleshooting/#insufficient-memory","title":"Insufficient memory","text":"

Building Autoware requires a lot of memory, and your machine can freeze or crash if memory runs out during a build. To avoid this problem, 16-32GB of swap should be configured.

# Optional: Check the current swapfile\nfree -h\n\n# Remove the current swapfile\nsudo swapoff /swapfile\nsudo rm /swapfile\n\n# Create a new swapfile\nsudo fallocate -l 32G /swapfile\nsudo chmod 600 /swapfile\nsudo mkswap /swapfile\nsudo swapon /swapfile\n\n# Optional: Check if the change is reflected\nfree -h\n

For more detailed configuration steps, along with an explanation of swap, refer to Digital Ocean's \"How To Add Swap Space on Ubuntu 20.04\" tutorial

If there are too many CPU cores (more than 64) in your machine, it might requires larger memory. A workaround here is to limit the job number while building.

MAKEFLAGS=\"-j4\" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

You can adjust -j4 to any number based on your system. For more details, see the manual page of GNU make.

By reducing the number of packages built in parallel, you can also reduce the amount of memory used. In the following example, the number of packages built in parallel is set to 1, and the number of jobs used by make is limited to 1.

MAKEFLAGS=\"-j1\" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --parallel-workers 1\n

Note

By lowering both the number of packages built in parallel and the number of jobs used by make, you can reduce the memory usage. However, this also means that the build process takes longer.

"},{"location":"support/troubleshooting/#errors-when-using-the-latest-version-of-autoware","title":"Errors when using the latest version of Autoware","text":"

If you are working with the latest version of Autoware, issues can occur due to out-of-date software or old build files.

To resolve these types of problems, first try cleaning your build artifacts and rebuilding:

rm -rf build/ install/ log/\ncolcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

If the error is not resolved, remove src/ and update your workspace according to installation type (Docker / source).

Warning

Before removing src/, confirm that there are no modifications in your local environment that you want to keep!

If errors still persist after trying the steps above, delete the entire workspace, clone the repository once again and restart the installation process.

rm -rf autoware/\ngit clone https://github.com/autowarefoundation/autoware.git\n
"},{"location":"support/troubleshooting/#errors-when-using-a-fixed-version-of-autoware","title":"Errors when using a fixed version of Autoware","text":"

In principle, errors should not occur when using a fixed version. That said, possible causes include:

  • ROS 2 has been updated with breaking changes.
    • For confirmation, check the Packaging and Release Management tag on ROS Discourse.
  • Your local environment is broken.
    • Confirm your .bashrc file, environment variables, and library versions.

In addition to the causes listed above, there are two common misunderstandings around the use of fixed versions.

  1. You used a fixed version for autowarefoundation/autoware only. All of the repository versions in the .repos file must be specified in order to use a completely fixed version.

  2. You didn't update the workspace after changing the branch of autowarefoundation/autoware. Changing the branch of autowarefoundation/autoware does not affect the files under src/. You have to run the vcs import command to update them.

"},{"location":"support/troubleshooting/#error-when-building-python-package","title":"Error when building python package","text":"

During building the following issue can occurs

pkg_resources.extern.packaging.version.InvalidVersion: Invalid version: '0.23ubuntu1'\n

The error is due to the fact that for versions between 66.0.0 and 67.5.0 setuptools enforces the python packages to be PEP-440 conformant. Since version 67.5.1 setuptools has a fallback that makes it possible to work with old packages again.

The solution is to update setuptools to the newest version with the following command

pip install --upgrade setuptools\n
"},{"location":"support/troubleshooting/#dockerrocker-issues","title":"Docker/rocker issues","text":"

If any errors occur when running Autoware with Docker or rocker, first confirm that your Docker installation is working correctly by running the following commands:

docker run --rm -it hello-world\ndocker run --rm -it ubuntu:latest\n

Next, confirm that you are able to access the base Autoware image that is stored on the GitHub Packages website

docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:latest\n
"},{"location":"support/troubleshooting/#runtime-issues","title":"Runtime issues","text":""},{"location":"support/troubleshooting/#performance-related-issues","title":"Performance related issues","text":"

Symptoms:

  • Autoware is running slower than expected
  • Messages show up late in RViz2
  • Point clouds are lagging
  • Camera images are lagging behind
  • Point clouds or markers flicker on RViz2
  • When multiple subscribers use the same publishers, the message rate drops

If you have any of these symptoms, please the Performance Troubleshooting page.

"},{"location":"support/troubleshooting/#map-does-not-display-when-running-the-planning-simulator","title":"Map does not display when running the Planning Simulator","text":"

When running the Planning Simulator, the most common reason for the map not being displayed in RViz is because the map path has not been specified correctly in the launch command. You can confirm if this is the case by searching for Could not find lanelet map under {path-to-map-dir}/lanelet2_map.osm errors in the log.

Another possible reason is that map loading is taking a long time due to poor DDS performance. For this, please visit the Performance Troubleshooting page.

"},{"location":"support/troubleshooting/performance-troubleshooting/","title":"Performance Troubleshooting","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#performance-troubleshooting","title":"Performance Troubleshooting","text":"

Overall symptoms:

  • Autoware is running slower than expected
  • Messages show up late in RViz2
  • Point clouds are lagging
  • Camera images are lagging behind
  • Point clouds or markers flicker on RViz2
  • When multiple subscribers use the same publishers, the message rate drops
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnostic-steps","title":"Diagnostic Steps","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#check-if-multicast-is-enabled","title":"Check if multicast is enabled","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms","title":"Target symptoms","text":"
  • When multiple subscribers use the same publishers, the message rate drops
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis","title":"Diagnosis","text":"

Make sure that the multicast is enabled for your interface.

For example when you run following:

source /opt/ros/humble/setup.bash\nros2 run demo_nodes_cpp talker\n

If you get the error message selected interface \"{your-interface-name}\" is not multicast-capable: disabling multicast, this should be fixed.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution","title":"Solution","text":"

Run the following command to allow multicast:

sudo ip link set multicast on {your-interface-name}\n

This way DDS will function as intended and multiple subscribers can receive data from a single publisher without any significant degradation in performance.

This is a temporary solution. And will be reverted once the computer restarts.

To make it permanent either,

  • Create a service to run this on startup (recommended)

  • OR put following lines to the ~/.bashrc file:

    if [ ! -e /tmp/multicast_is_set ]; then\nsudo ip link set lo multicast on\ntouch /tmp/multicast_is_set\nfi\n
    • This will probably ask for password on the terminal every time you restart the computer.
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-compilation-flags","title":"Check the compilation flags","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms_1","title":"Target symptoms","text":"
  • Autoware is running slower than expected
  • Point clouds are lagging
  • When multiple subscribers use the same publishers, the message rate drops even further
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_1","title":"Diagnosis","text":"

Check the ~/.bash_history file to see if there are any colcon build directives without -DCMAKE_BUILD_TYPE=Release or -DCMAKE_BUILD_TYPE=RelWithDebInfo flags at all.

Even if a build starts with these flags but same workspace gets compiled without these flags, it will still be a slow build in the end.

In addition, the nodes will run slow in general, especially the pointcloud_preprocessor nodes.

Example issue: issue2597

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_1","title":"Solution","text":"
  • Remove the build, install and optionally log folders in the main autoware folder.

  • Compile the Autoware with either Release or RelWithDebInfo tags:

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n# Or build with debug flags too (comparable performance but you can debug too)\ncolcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo\n
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-dds-settings","title":"Check the DDS settings","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms_2","title":"Target symptoms","text":"
  • Autoware is running slower than expected
  • Messages show up late in RViz2
  • Point clouds are lagging
  • Camera images are lagging behind
  • When multiple subscribers use the same publishers, the message rate drops
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-rmw-ros-middleware-implementation","title":"Check the RMW (ROS Middleware) implementation","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_2","title":"Diagnosis","text":"

Run following to check the middleware used:

echo $RMW_IMPLEMENTATION\n

The return line should be rmw_cyclonedds_cpp. If not, apply the solution.

If you are using a different DDS middleware, we might not have official support for it just yet.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_2","title":"Solution","text":"

Add export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp as a separate line in you ~/.bashrc file.

"},{"location":"support/troubleshooting/performance-troubleshooting/#check-if-the-cyclonedds-is-configured-correctly","title":"Check if the CycloneDDS is configured correctly","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_3","title":"Diagnosis","text":"

Run following to check the configuration .xml file of the CycloneDDS:

echo $CYCLONEDDS_URI\n

The return line should be a valid path pointing to an .xml file with CycloneDDS configuration.

Also check if the file is configured correctly:

cat !{echo $CYCLONEDDS_URI}\n

This should print the .xml file on the terminal.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_3","title":"Solution","text":"

Follow DDS settings:Tuning DDS documentation and make sure:

  • you have export CYCLONEDDS_URI=/absolute_path_to_your/cyclonedds_config.xml as a line on your ~/.bashrc file.
  • you have the cyclonedds_config.xml with the configuration provided in the documentation.
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-linux-kernel-maximum-buffer-size","title":"Check the Linux kernel maximum buffer size","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_4","title":"Diagnosis","text":"
  • Run: sysctl net.core.rmem_max, it should return at least net.core.rmem_max = 2147483647.
    • This parameter specifies the maximum size of the \"receive buffer\" for each network connection, which determines the maximum amount of data that can be held in memory at any given time. By increasing the maximum buffer size, the operating system can accommodate larger bursts of data, which can help prevent network congestion and reduce packet loss, resulting in faster and more reliable data transfers.
  • Run: sysctl net.ipv4.ipfrag_time, it should return around: net.ipv4.ipfrag_time = 3
    • The \"net.ipv4.ipfrag_time\" parameter specifies the maximum time in seconds that the kernel should retain partially fragmented IP packets before discarding them. The default value for this parameter is usually set to 30 seconds, but it may vary depending on the specific operating system and configuration.
    • By setting this parameter to a lower value, such as 3 seconds, the kernel can free up memory resources more quickly by discarding partially fragmented packets that are no longer needed, which can help improve the overall performance and stability of the system.
  • Run: sysctl net.ipv4.ipfrag_high_thresh, it should return at around: net.ipv4.ipfrag_high_thresh = 134217728
    • The \"net.ipv4.ipfrag_high_thresh\" parameter specifies the high watermark threshold for the number of partially fragmented packets allowed in the kernel IP packet reassembly queue. When the number of partially fragmented packets in the queue exceeds this threshold, the kernel will start to drop newly arrived packets until the number of partially fragmented packets drops below the threshold.
    • By setting this parameter to a higher value, such as 134217728 (128 MB), the kernel can accommodate a larger number of partially fragmented packets in the queue, which can help improve the performance of network applications that transfer large amounts of data, such as file transfer protocols and multimedia streaming applications.

More info on these values: Cross-vendor tuning

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_4","title":"Solution","text":"

Either:

  • Create the following file: sudo touch /etc/sysctl.d/10-cyclone-max.conf (recommended)

    • Edit the file to contain (sudo gedit /etc/sysctl.d/10-cyclone-max.conf):

      net.core.rmem_max=2147483647\nnet.ipv4.ipfrag_time=3\nnet.ipv4.ipfrag_high_thresh=134217728 # (128 MB)\n

      • Either restart the computer or run following to enable the changes:

        sudo sysctl -w net.core.rmem_max=2147483647\nsudo sysctl -w net.ipv4.ipfrag_time=3\nsudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728\n

  • OR put following lines to the ~/.bashrc file:

    if [ ! -e /tmp/kernel_network_conf_is_set ]; then\nsudo sysctl -w net.core.rmem_max=2147483647\nsudo sysctl -w net.ipv4.ipfrag_time=3\nsudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728 # (128 MB)\nfi\n
    • This will probably ask for password on the terminal every time you restart the computer.
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-if-ros-localhost-only-communication-is-enabled","title":"Check if ROS localhost only communication is enabled","text":"
  • If you are using multi computer setup, please skip this check.
  • Enabling ROS localhost only communication can help improve the performance of ROS by reducing network traffic and avoiding potential conflicts with other devices on the network.
  • Also check Enable localhost-only communication
"},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms_3","title":"Target symptoms","text":"
  • You see topics that shouldn't exist
  • You see point clouds that don't belong to your machine
    • They might be from another computer running ROS 2 on your network
  • Point clouds or markers flicker on RViz2
    • Another publisher (on another machine) may be publishing on the same topic as your node does.
    • Causing the flickering.
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_5","title":"Diagnosis","text":"

Run following to check it:

echo $ROS_LOCALHOST_ONLY\n

The return line should be 1. If not, apply the solution.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_5","title":"Solution","text":"
  • Add export $ROS_LOCALHOST_ONLY=1 as a separate line in you ~/.bashrc file.
    • This environment variable tells ROS to only use the loopback network interface (i.e., localhost) for communication, rather than using the network interface card (NIC) for Ethernet or Wi-Fi. This can reduce network traffic and potential conflicts with other devices on the network, resulting in better performance and stability.
"},{"location":"tutorials/","title":"Simulation tutorials","text":""},{"location":"tutorials/#simulation-tutorials","title":"Simulation tutorials","text":"

Simulations provide a way of verifying Autoware's functionality before field testing with an actual vehicle. There are three main types of simulation that can be run ad hoc or via a scenario runner.

"},{"location":"tutorials/#simulation-methods","title":"Simulation methods","text":""},{"location":"tutorials/#ad-hoc-simulation","title":"Ad hoc simulation","text":"

Ad hoc simulation is a flexible method for running basic simulations on your local machine, and is the recommended method for anyone new to Autoware.

"},{"location":"tutorials/#scenario-simulation","title":"Scenario simulation","text":"

Scenario simulation uses a scenario runner to run more complex simulations based on predefined scenarios. It is often run automatically for continuous integration purposes, but can also be run on a local machine.

"},{"location":"tutorials/#simulation-types","title":"Simulation types","text":""},{"location":"tutorials/#planning-simulation","title":"Planning simulation","text":"

Planning simulation uses simple dummy data to test the Planning and Control components - specifically path generation, path following and obstacle avoidance. It verifies that a vehicle can reach a goal destination while avoiding pedestrians and surrounding cars, and is another method for verifying the validity of Lanelet2 maps. It also allows for testing of traffic light handling.

"},{"location":"tutorials/#how-does-planning-simulation-work","title":"How does planning simulation work?","text":"
  1. Generate a path to the goal destination
  2. Control the car along the generated path
  3. Detect and avoid any humans or other vehicles on the way to the goal destination
"},{"location":"tutorials/#rosbag-replay-simulation","title":"Rosbag replay simulation","text":"

Rosbag replay simulation uses prerecorded rosbag data to test the following aspects of the Localization and Perception components:

  • Localization: Estimation of the vehicle's location on the map by matching sensor and vehicle feedback data to the map.
  • Perception: Using sensor data to detect, track and predict dynamic objects such as surrounding cars, pedestrians, and other objects

By repeatedly playing back the data, this simulation type can also be used for endurance testing.

"},{"location":"tutorials/#digital-twin-simulation","title":"Digital twin simulation","text":"

Digital twin simulation is a simulation type that is able to produce realistic data and simulate almost the entire system. It is also commonly referred to as end-to-end simulation.

"},{"location":"tutorials/ad-hoc-simulation/","title":"Ad hoc simulation","text":""},{"location":"tutorials/ad-hoc-simulation/#ad-hoc-simulation","title":"Ad hoc simulation","text":"

Warning

Under Construction

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/","title":"Planning simulation","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#planning-simulation","title":"Planning simulation","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#preparation","title":"Preparation","text":"

Download and unpack a sample map.

  • You can also download the map manually.
gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd'\nunzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip\n

Note

Sample map: Copyright 2020 TIER IV, Inc.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#basic-simulations","title":"Basic simulations","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#lane-driving-scenario","title":"Lane driving scenario","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#1-launch-autoware","title":"1. Launch Autoware","text":"
source ~/autoware/install/setup.bash\nros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/autoware_map/sample-map-planning vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit\n

Warning

Note that you cannot use ~ instead of $HOME here.

If ~ is used, the map will fail to load.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#2-set-an-initial-pose-for-the-ego-vehicle","title":"2. Set an initial pose for the ego vehicle","text":"

a) Click the 2D Pose estimate button in the toolbar, or hit the P key.

b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the initial pose. An image representing the vehicle should now be displayed.

Warning

Remember to set the initial pose of the car in the same direction as the lane.

To confirm the direction of the lane, check the arrowheads displayed on the map.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#3-set-a-goal-pose-for-the-ego-vehicle","title":"3. Set a goal pose for the ego vehicle","text":"

a) Click the 2D Goal Pose button in the toolbar, or hit the G key.

b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the goal pose. If done correctly, you will see a planned path from initial pose to goal pose.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#4-start-the-ego-vehicle","title":"4. Start the ego vehicle","text":"

Now you can start the ego vehicle driving by clicking the AUTO button on OperationMode in AutowareStatePanel. Alteratively, you can manually start the vehicle by running the following command:

source ~/autoware/install/setup.bash\nros2 service call /api/operation_mode/change_to_autonomous autoware_adapi_v1_msgs/srv/ChangeOperationMode {}\n

After that, you can see AUTONOMOUS sign on OperationMode and AUTO button is grayed out.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#parking-scenario","title":"Parking scenario","text":"

  1. Set an initial pose and a goal pose, and engage the ego vehicle.

  2. When the vehicle approaches the goal, it will switch from lane driving mode to parking mode.

  3. After that, the vehicle will reverse into the destination parking spot.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#advanced-simulations","title":"Advanced Simulations","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#placing-dummy-objects","title":"Placing dummy objects","text":"
  1. Click the 2D Dummy Car or 2D Dummy Pedestrian button in the toolbar.
  2. Set the pose of the dummy object by clicking and dragging on the map.

  3. Set the velocity of the object in Tool Properties -> 2D Dummy Car/Pedestrian panel.

    !!! note

    Changes to the velocity parameter will only affect objects placed after the parameter is changed.

  4. Delete any dummy objects placed in the view by clicking the Delete All Objects button in the toolbar.

  5. Click the Interactive button in the toolbar to make the dummy object interactive.

  6. For adding an interactive dummy object, press SHIFT and click the right click.

  7. For deleting an interactive dummy object, press ALT and click the right click.

  8. For moving an interactive dummy object, hold the right click drag and drop the object.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#traffic-light-recognition-simulation","title":"Traffic light recognition simulation","text":"

By default, traffic lights on the map are all treated as if they are set to green. As a result, when a path is created that passed through an intersection with a traffic light, the ego vehicle will drive through the intersection without stopping.

The following steps explain how to set and reset traffic lights in order to test how the Planning component will respond.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#set-traffic-light","title":"Set traffic light","text":"

  1. Go to Panels -> Add new panel, select TrafficLightPublishPanel, and then press OK.

  2. In TrafficLightPublishPanel, set the ID and color of the traffic light.

  3. Click the SET button.

  4. Finally, click the PUBLISH button to send the traffic light status to the simulator. Any planned path that goes past the selected traffic light will then change accordingly.

By default, Rviz should display the ID of each traffic light on the map. You can have a closer look at the IDs by zooming in the region or by changing the View type.

In case the IDs are not displayed, try the following troubleshooting steps:

a) In the Displays panel, find the traffic_light_id topic by toggling the triangle icons next to Map > Lanelet2VectorMap > Namespaces.

b) Check the traffic_light_id checkbox.

c) Reload the topic by clicking the Map checkbox twice.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#updatereset-traffic-light","title":"Update/Reset traffic light","text":"

You can update the color of the traffic light by selecting the next color (in the image it is GREEN) and clicking SET button. In the image the traffic light in front of the ego vehicle changed from RED to GREEN and the vehicle restarted.

To remove a traffic light from TrafficLightPublishPanel, click the RESET button.

Reference video tutorials

"},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/","title":"Rosbag replay simulation","text":""},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#rosbag-replay-simulation","title":"Rosbag replay simulation","text":""},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#steps","title":"Steps","text":"

  1. Download and unpack a sample map.

    • You can also download the map manually.
    gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI'\nunzip -d ~/autoware_map/ ~/autoware_map/sample-map-rosbag.zip\n

  2. Download the sample rosbag files.

    • You can also download the rosbag files manually.
    gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1VnwJx9tI3kI_cTLzP61ktuAJ1ChgygpG'\nunzip -d ~/autoware_map/ ~/autoware_map/sample-rosbag.zip\n
"},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#note","title":"Note","text":"
  • Sample map and rosbag: Copyright 2020 TIER IV, Inc.
  • Due to privacy concerns, the rosbag does not contain image data, which will cause:
    • Traffic light recognition functionality cannot be tested with this sample rosbag.
    • Object detection accuracy is decreased.
"},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#how-to-run-a-rosbag-replay-simulation","title":"How to run a rosbag replay simulation","text":"

  1. Launch Autoware.

    source ~/autoware/install/setup.bash\nros2 launch autoware_launch logging_simulator.launch.xml map_path:=$HOME/autoware_map/sample-map-rosbag vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit\n

    Note that you cannot use ~ instead of $HOME here.

  2. Play the sample rosbag file.

    source ~/autoware/install/setup.bash\nros2 bag play ~/autoware_map/sample-rosbag/sample.db3 -r 0.2 -s sqlite3\n

  3. To focus the view on the ego vehicle, change the Target Frame in the RViz Views panel from viewer to base_link.

  4. To switch the view to Third Person Follower etc, change the Type in the RViz Views panel.

Reference video tutorials

"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/","title":"MORAI Sim: Drive","text":""},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#morai-sim-drive","title":"MORAI Sim: Drive","text":"

Note

Any kind of for-profit activity with the trial version of the MORAI SIM:Drive is strictly prohibited.

"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#hardware-requirements","title":"Hardware requirements","text":"Minimum PC Specs OS Windows 10, Ubuntu 20.04, Ubuntu 18.04, Ubuntu 16.04 CPU Intel i5-9600KF or AMD Ryzen 5 3500X RAM DDR4 16GB GPU RTX2060 Super Required PC Specs OS Windows 10, Ubuntu 20.04, Ubuntu 18.04, Ubuntu 16.04 CPU Intel i9-9900K or AMD Ryzen 7 3700X (or higher) RAM DDR4 64GB (or higher) GPU RTX2080Ti or higher"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#application-and-download","title":"Application and Download","text":"

Only for AWF developers, trial license for 3 months can be issued. Download the application form and send to Hyeongseok Jeon

After the trial license is issued, you can login to MORAI Sim:Drive via Launchers (Windows/Ubuntu)

CAUTION: Do not use the Launchers in the following manual

"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#technical-documents","title":"Technical Documents","text":"

as Oct. 2022, our simulation version is ver.22.R3 but the english manual is under construction.

Be aware that the following manuals are for ver.22.R2

  • MORAI Sim:Drive Manual
  • ITRI BUS Odd tutorial
  • Tutorial for rosbag replay with Tacoma Airport
"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#technical-support","title":"Technical Support","text":"

Hyeongseok Jeon will give full technical support

  • hsjeon@morai.ai
  • Hyeongseok Jeon#2355 in Discord
"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial/","title":"AWSIM simulator","text":""},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial/#awsim-simulator","title":"AWSIM simulator","text":"

AWSIM is a simulator for Autoware development and testing. To get started, please follow the official instruction provided by TIER IV.

"},{"location":"tutorials/scenario-simulation/","title":"Scenario simulation","text":""},{"location":"tutorials/scenario-simulation/#scenario-simulation","title":"Scenario simulation","text":"

Warning

Under Construction

"},{"location":"tutorials/scenario-simulation/planning-simulation/installation/","title":"Installation","text":""},{"location":"tutorials/scenario-simulation/planning-simulation/installation/#installation","title":"Installation","text":"

This document contains step-by-step instruction on how to build AWF Autoware Core/Universe with scenario_simulator_v2.

"},{"location":"tutorials/scenario-simulation/planning-simulation/installation/#prerequisites","title":"Prerequisites","text":"
  1. Autoware has been built and installed
"},{"location":"tutorials/scenario-simulation/planning-simulation/installation/#how-to-build","title":"How to build","text":"

  1. Navigate to the Autoware workspace:

    cd autoware\n

  2. Import Simulator dependencies:

    vcs import src < simulator.repos\n

  3. Install dependent ROS packages:

    source /opt/ros/humble/setup.bash\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  4. Build the workspace:

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"tutorials/scenario-simulation/planning-simulation/random-test-simulation/","title":"Random test simulation","text":""},{"location":"tutorials/scenario-simulation/planning-simulation/random-test-simulation/#random-test-simulation","title":"Random test simulation","text":"

Note

Running the Scenario Simulator requires some additional steps on top of building and installing Autoware, so make sure that Scenario Simulator installation has been completed first before proceeding.

"},{"location":"tutorials/scenario-simulation/planning-simulation/random-test-simulation/#running-steps","title":"Running steps","text":"

  1. Move to the workspace directory where Autoware and the Scenario Simulator have been built.

  2. Source the workspace setup script:

    source install/setup.bash\n

  3. Run the simulation:

    ros2 launch random_test_runner random_test.launch.py \\\narchitecture_type:=awf/universe \\\nsensor_model:=sample_sensor_kit \\\nvehicle_model:=sample_vehicle\n

For more information about supported parameters, refer to the random_test_runner documentation.

"},{"location":"tutorials/scenario-simulation/planning-simulation/scenario-test-simulation/","title":"Scenario test simulation","text":""},{"location":"tutorials/scenario-simulation/planning-simulation/scenario-test-simulation/#scenario-test-simulation","title":"Scenario test simulation","text":"

Note

Running the Scenario Simulator requires some additional steps on top of building and installing Autoware, so make sure that Scenario Simulator installation has been completed first before proceeding.

"},{"location":"tutorials/scenario-simulation/planning-simulation/scenario-test-simulation/#running-steps","title":"Running steps","text":"

  1. Move to the workspace directory where Autoware and the Scenario Simulator have been built.

  2. Source the workspace setup script:

    source install/setup.bash\n

  3. Run the simulation:

    ros2 launch scenario_test_runner scenario_test_runner.launch.py \\\narchitecture_type:=awf/universe \\\nrecord:=false \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample.yaml' \\\nsensor_model:=sample_sensor_kit \\\nvehicle_model:=sample_vehicle\n

Reference video tutorials

"},{"location":"tutorials/scenario-simulation/rosbag-replay-simulation/driving-log-replayer/","title":"Driving Log Replayer","text":""},{"location":"tutorials/scenario-simulation/rosbag-replay-simulation/driving-log-replayer/#driving-log-replayer","title":"Driving Log Replayer","text":"

Driving Log Replayer is an evaluation tool for Autoware. To get started, follow the official instruction provided by TIER IV.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#autoware-documentation","title":"Autoware Documentation","text":""},{"location":"#about-autoware","title":"About Autoware","text":"

Autoware is the world\u2019s leading open-source software project for autonomous driving. Autoware is built on Robot Operating System (ROS) and enables commercial deployment of autonomous driving in a broad range of vehicles and applications.

Please see here for more details.

"},{"location":"#related-documentations","title":"Related Documentations","text":"

This Autoware Documentation is for Autoware's general information.

For detailed documents of Autoware Universe components, see Autoware Universe Documentation.

"},{"location":"#getting-started","title":"Getting started","text":"
  • Installation pages explain the installation steps of Autoware and related tools.
  • Tutorials pages explain several tutorials that you should try after installation.
  • How-to guides pages explain advanced topics that you should read after you get used to Autoware.
  • Design pages explain the design concept of Autoware.
  • Contributing pages explain how to contribute to Autoware.
  • Datasets pages contain information about datasets that can be used with Autoware.
  • Support pages explain several support resources.
"},{"location":"contributing/","title":"Contributing","text":""},{"location":"contributing/#contributing","title":"Contributing","text":"

Thank you for your interest in contributing! Autoware is supported by people like you, and all types and sizes of contribution are welcome.

As a contributor, here are the guidelines that we would like you to follow for Autoware and its associated repositories.

  • Code of Conduct
  • What should I know before I get started?
    • Autoware concepts
    • Contributing to open source projects
  • How can I get help?
  • How can I contribute?
    • Participate in discussions
    • Join a working group
    • Report bugs
    • Make a pull request

Like Autoware itself, these guidelines are being actively developed and suggestions for improvement are always welcome! Guideline changes can be proposed by creating a discussion in the Ideas category.

"},{"location":"contributing/#code-of-conduct","title":"Code of Conduct","text":"

To ensure the Autoware community stays open and inclusive, please follow the Code of Conduct.

If you believe that someone in the community has violated the Code of Conduct, please make a report by emailing conduct@autoware.org.

"},{"location":"contributing/#what-should-i-know-before-i-get-started","title":"What should I know before I get started?","text":""},{"location":"contributing/#autoware-concepts","title":"Autoware concepts","text":"

To gain a high-level understanding of Autoware's architecture and design, the following pages provide a brief overview:

  • Autoware architecture
  • Autoware concepts

For experienced developers, the Autoware interfaces and individual component pages should also be reviewed to understand the inputs and outputs for each component or module at a more detailed level.

"},{"location":"contributing/#contributing-to-open-source-projects","title":"Contributing to open source projects","text":"

If you are new to open source projects, we recommend reading GitHub's How to Contribute to Open Source guide for an overview of why people contribute to open source projects, what it means to contribute and much more besides.

"},{"location":"contributing/#how-can-i-get-help","title":"How can I get help?","text":"

Do not open issues for general support questions as we want to keep GitHub issues for confirmed bug reports. Instead, open a discussion in the Q&A category. For more details on the support mechanisms for Autoware, refer to the Support guidelines.

Note

Issues created for questions or unconfirmed bugs will be moved to GitHub discussions by the maintainers.

"},{"location":"contributing/#how-can-i-contribute","title":"How can I contribute?","text":""},{"location":"contributing/#discussions","title":"Discussions","text":"

You can contribute to Autoware by facilitating and participating in discussions, such as:

  • Proposing a new feature to enhance Autoware
  • Joining an existing discussion and expressing your opinion
  • Organizing discussions for other contributors
  • Answering questions and supporting other contributors
"},{"location":"contributing/#working-groups","title":"Working groups","text":"

The various working groups within the Autoware Foundation are responsible for accomplishing goals set by the Technical Steering Committee. These working groups are open to everyone, and joining a particular working group will allow you to gain an understanding of current projects, see how those projects are managed within each group and to contribute to issues that will help progress a particular project.

To see the schedule for upcoming working group meetings, refer to the Autoware Foundation events calendar.

"},{"location":"contributing/#bug-reports","title":"Bug reports","text":"

Before you report a bug, please search the issue tracker for the appropriate repository. It is possible that someone has already reported the same issue and that workarounds exist. If you can't determine the appropriate repository, ask the maintainers for help by creating a new discussion in the Q&A category.

When reporting a bug, you should provide a minimal set of instructions to reproduce the issue. Doing so allows us to quickly confirm and focus on the right problem.

If you want to fix the bug by yourself that will be appreciated, but you should discuss possible approaches with the maintainers in the issue before submitting a pull request.

Creating an issue is straightforward, but if you happen to experience any problems then create a Q&A discussion to ask for help.

"},{"location":"contributing/#pull-requests","title":"Pull requests","text":"

You can submit pull requests for small changes such as:

  • Minor documentation updates
  • Fixing spelling mistakes
  • Fixing CI failures
  • Fixing warnings detected by compilers or analysis tools
  • Making small changes to a single package

If your pull request is a large change, the following process should be followed:

  1. Create a GitHub Discussion to propose the change. Doing so allows you to get feedback from other members and the Autoware maintainers and to ensure that the proposed change is in line with Autoware's design philosophy and current development plans. If you're not sure where to have that conversation, then create a new Q&A discussion.

  2. Create an issue following consensus in the discussions

  3. Create a pull request to implement the changes that references the Issue created in step 2

  4. Create documentation for the new addition (if relevant)

Examples of large changes include:

  • Adding a new feature to Autoware
  • Adding a new documentation page or section

For more information on how to submit a good pull request, have a read of the pull request guidelines and don't forget to review the required license notations!

"},{"location":"contributing/license/","title":"License","text":""},{"location":"contributing/license/#license","title":"License","text":"

Autoware is licensed under Apache License 2.0. Thus all contributions will be licensed as such as per clause 5 of the Apache License 2.0:

5. Submission of Contributions. Unless You explicitly state otherwise,\n   any Contribution intentionally submitted for inclusion in the Work\n   by You to the Licensor shall be under the terms and conditions of\n   this License, without any additional terms or conditions.\n   Notwithstanding the above, nothing herein shall supersede or modify\n   the terms of any separate license agreement you may have executed\n   with Licensor regarding such Contributions.\n

Here is an example copyright header to add to the top of a new file:

Copyright [first year of contribution] The Autoware Contributors\nSPDX-License-Identifier: Apache-2.0\n

We don't write copyright notations of each contributor here. Instead, we place them in the NOTICE file like the following.

This product includes code developed by [company name].\nCopyright [first year of contribution] [company name]\n

Let us know if your legal department has a special request for the copyright notation.

Currently, the old formats explained here are also acceptable. Those old formats can be replaced by this new format if the original authors agree. Note that we won't write their copyrights to the NOTICE file unless they agree with the new format.

References:

  • https://opensource.google/docs/copyright/#the-year
  • https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/
  • https://www.apache.org/licenses/LICENSE-2.0
  • https://www.apache.org/legal/src-headers.html
  • https://www.apache.org/foundation/license-faq.html
  • https://infra.apache.org/licensing-howto.html
"},{"location":"contributing/coding-guidelines/","title":"Coding guidelines","text":""},{"location":"contributing/coding-guidelines/#coding-guidelines","title":"Coding guidelines","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/#common-guidelines","title":"Common guidelines","text":"

Refer to the following links for now:

  • https://docs.ros.org/en/humble/Contributing/Developer-Guide.html

Also, keep in mind the following concepts.

  • Keep things consistent.
  • Automate where possible, using simple checks for formatting, syntax, etc.
  • When it comes to code reviews, don't spend too much time on trivial disagreements. For details see:
    • https://en.wikipedia.org/wiki/Law_of_triviality
    • https://steemit.com/programming/@emrebeyler/code-reviews-and-parkinson-s-law-of-triviality
"},{"location":"contributing/coding-guidelines/languages/cmake/","title":"CMake","text":""},{"location":"contributing/coding-guidelines/languages/cmake/#cmake","title":"CMake","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.ros.org/en/humble/Contributing/Code-Style-Language-Versions.html#cmake
"},{"location":"contributing/coding-guidelines/languages/cmake/#use-the-autoware_package-macro","title":"Use the autoware_package macro","text":"

To reduce duplications in CMakeLists.txt, there is the autoware_package() macro. See the README and use it in your package.

"},{"location":"contributing/coding-guidelines/languages/cpp/","title":"C++","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#c","title":"C++","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/languages/cpp/#references","title":"References","text":"

Follow the guidelines below if a rule is not defined on this page.

  1. https://docs.ros.org/en/humble/Contributing/Code-Style-Language-Versions.html
  2. https://www.autosar.org/fileadmin/standards/adaptive/22-11/AUTOSAR_RS_CPP14Guidelines.pdf
  3. https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines

Also, it is encouraged to apply Clang-Tidy to each file. For the usage, see Applying Clang-Tidy to ROS packages.

Note that not all rules are covered by Clang-Tidy.

"},{"location":"contributing/coding-guidelines/languages/cpp/#style-rules","title":"Style rules","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#include-header-files-in-the-defined-order-required-partially-automated","title":"Include header files in the defined order (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale","title":"Rationale","text":"
  • Due to indirect dependencies, the include system of C++ makes different behaviors if the header order is different.
  • To reduce unintended bugs, local header files should come first.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference","title":"Reference","text":"
  • https://llvm.org/docs/CodingStandards.html#include-style
"},{"location":"contributing/coding-guidelines/languages/cpp/#example","title":"Example","text":"

Include the headers in the following order:

  • Main module header
  • Local package headers
  • Other package headers
  • Message headers
  • Boost headers
  • C system headers
  • C++ system headers
// Compliant\n#include \"my_header.hpp\"\n\n#include \"my_package/foo.hpp\"\n\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n

If you use \"\" and <> properly, ClangFormat in pre-commit sorts headers automatically.

Do not define macros between #include lines because it prevents automatic sorting.

// Non-compliant\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#define EIGEN_MPL2_ONLY\n#include \"my_header.hpp\"\n#include \"my_package/foo.hpp\"\n\n#include <Eigen/Core>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n

Instead, define macros before #include lines.

// Compliant\n#define EIGEN_MPL2_ONLY\n\n#include \"my_header.hpp\"\n\n#include \"my_package/foo.hpp\"\n\n#include <Eigen/Core>\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n

If there are any reasons for defining macros at a specific position, write a comment before the macro.

// Compliant\n#include \"my_header.hpp\"\n\n#include \"my_package/foo.hpp\"\n\n#include <package1/foo.hpp>\n#include <package2/bar.hpp>\n\n#include <std_msgs/msg/header.hpp>\n\n#include <iostream>\n#include <vector>\n\n// For the foo bar reason, the FOO_MACRO must be defined here.\n#define FOO_MACRO\n#include <foo/bar.hpp>\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#use-lower-snake-case-for-function-names-required-partially-automated","title":"Use lower snake case for function names (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_1","title":"Rationale","text":"
  • It is consistent with the C++ standard library.
  • It is consistent with other programming languages such as Python and Rust.
"},{"location":"contributing/coding-guidelines/languages/cpp/#exception","title":"Exception","text":"
  • For member functions of classes inherited from external project classes such as Qt, follow that naming convention.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_1","title":"Reference","text":"
  • https://docs.ros.org/en/humble/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html#function-and-method-naming
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_1","title":"Example","text":"
void function_name()\n{\n}\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#use-upper-camel-case-for-enum-names-required-partially-automated","title":"Use upper camel case for enum names (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_2","title":"Rationale","text":"
  • It is consistent with ROS 2 core packages.
"},{"location":"contributing/coding-guidelines/languages/cpp/#exception_1","title":"Exception","text":"
  • Enums defined in the rosidl file can use other naming conventions.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_2","title":"Reference","text":"
  • http://wiki.ros.org/CppStyleGuide (Refer to \"15. Enumerations\")
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_2","title":"Example","text":"
enum class Color\n{\nRed, Green, Blue\n}\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#use-lower-snake-case-for-constant-names-required-partially-automated","title":"Use lower snake case for constant names (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_3","title":"Rationale","text":"
  • It is consistent with ROS 2 core packages.
  • It is consistent with std::numbers.
"},{"location":"contributing/coding-guidelines/languages/cpp/#exception_2","title":"Exception","text":"
  • Constants defined in the rosidl file can use other naming conventions.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_3","title":"Reference","text":"
  • https://en.cppreference.com/w/cpp/numeric/constants
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_3","title":"Example","text":"
constexpr double gravity = 9.80665;\n
"},{"location":"contributing/coding-guidelines/languages/cpp/#count-acronyms-and-contractions-of-compound-words-as-one-word-required-partially-automated","title":"Count acronyms and contractions of compound words as one word (required, partially automated)","text":""},{"location":"contributing/coding-guidelines/languages/cpp/#rationale_4","title":"Rationale","text":"
  • To clarify the boundaries of words when acronyms are consecutive.
"},{"location":"contributing/coding-guidelines/languages/cpp/#reference_4","title":"Reference","text":"
  • https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case
"},{"location":"contributing/coding-guidelines/languages/cpp/#example_4","title":"Example","text":"
class RosApi;\nRosApi ros_api;\n
"},{"location":"contributing/coding-guidelines/languages/docker/","title":"Docker","text":""},{"location":"contributing/coding-guidelines/languages/docker/#docker","title":"Docker","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://github.com/hadolint/hadolint
"},{"location":"contributing/coding-guidelines/languages/github-actions/","title":"GitHub Actions","text":""},{"location":"contributing/coding-guidelines/languages/github-actions/#github-actions","title":"GitHub Actions","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.github.com/en/actions/guides
"},{"location":"contributing/coding-guidelines/languages/markdown/","title":"Markdown","text":""},{"location":"contributing/coding-guidelines/languages/markdown/#markdown","title":"Markdown","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.ros.org/en/foxy/Contributing/Code-Style-Language-Versions.html#markdown-restructured-text-docblocks
  • https://github.com/DavidAnson/markdownlint
"},{"location":"contributing/coding-guidelines/languages/package-xml/","title":"package.xml","text":""},{"location":"contributing/coding-guidelines/languages/package-xml/#packagexml","title":"package.xml","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://ros.org/reps/rep-0149.html
  • https://github.com/tier4/pre-commit-hooks-ros#prettier-package-xml
"},{"location":"contributing/coding-guidelines/languages/python/","title":"Python","text":""},{"location":"contributing/coding-guidelines/languages/python/#python","title":"Python","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.ros.org/en/foxy/Contributing/Code-Style-Language-Versions.html#python
  • https://github.com/psf/black
  • https://github.com/PyCQA/isort
"},{"location":"contributing/coding-guidelines/languages/shell-scripts/","title":"Shell scripts","text":""},{"location":"contributing/coding-guidelines/languages/shell-scripts/#shell-scripts","title":"Shell scripts","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://google.github.io/styleguide/shellguide.html
  • https://github.com/koalaman/shellcheck
  • https://github.com/mvdan/sh
"},{"location":"contributing/coding-guidelines/ros-nodes/class-design/","title":"Class design","text":""},{"location":"contributing/coding-guidelines/ros-nodes/class-design/#class-design","title":"Class design","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/","title":"Console logging","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#console-logging","title":"Console logging","text":"

ROS 2 logging is a powerful tool for understanding and debugging ROS nodes.

This page focuses on how to design console logging in Autoware and shows several practical examples. To comprehensively understand how ROS 2 logging works, refer to the logging documentation.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#logging-use-cases-in-autoware","title":"Logging use cases in Autoware","text":"
  • Developers debug code by seeing the console logs.
  • Vehicle operators take appropriate risk-avoiding actions depending on the console logs.
  • Log analysts analyze the console logs that are recorded in rosbag files.

To efficiently support these use cases, clean and highly visible logs are required. For that, several rules are defined below.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rules","title":"Rules","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#choose-appropriate-severity-levels-required-non-automated","title":"Choose appropriate severity levels (required, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale","title":"Rationale","text":"

It's confusing if severity levels are inappropriate as follows:

  • Useless messages are marked as FATAL.
  • Very important error messages are marked as INFO.
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example","title":"Example","text":"

Use the following criteria as a reference:

  • DEBUG: Use this level to show debug information for developers. Note that logs with this level is hidden by default.
  • INFO: Use this level to notify events (cyclic notifications during initialization, state changes, service responses, etc.) to operators.
  • WARN: Use this level when a node can continue working correctly, but unintended behaviors might happen.
    • For example, \"path optimization failed but the previous data can be used\", \"the localization score is low\", etc.
  • ERROR: Use this level when a node can't continue working correctly, and unintended behaviors would happen.
    • For example, \"path optimization failed and the path is empty\", \"the vehicle will trigger an emergency stop\", etc.
  • FATAL: Use this level when the entire system can't continue working correctly, and the system must be stopped.
    • For example, \"the vehicle control ECU doesn't respond\", \"the system storage crashed\", etc.
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#filter-out-unnecessary-logs-by-setting-logging-options-required-non-automated","title":"Filter out unnecessary logs by setting logging options (required, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale_1","title":"Rationale","text":"

Some third-party nodes such as drivers may not follow the Autoware's guidelines. If the logs are noisy, unnecessary logs should be filtered out.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example_1","title":"Example","text":"

Use the --log-level {level} option to change the minimum level of logs to be displayed:

<launch>\n<!-- This outputs only FATAL level logs. -->\n<node pkg=\"demo_nodes_cpp\" exec=\"talker\" ros_args=\"--log-level fatal\" />\n</launch>\n

If you want to disable only specific output targets, use the --disable-stdout-logs, --disable-rosout-logs, and/or --disable-external-lib-logs options:

<launch>\n<!-- This outputs to rosout and disk. -->\n<node pkg=\"demo_nodes_cpp\" exec=\"talker\" ros_args=\"--disable-stdout-logs\" />\n</launch>\n
<launch>\n<!-- This outputs to stdout. -->\n<node pkg=\"demo_nodes_cpp\" exec=\"talker\" ros_args=\"--disable-rosout-logs --disable-external-lib-logs\" />\n</launch>\n
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#use-throttled-logging-when-the-log-is-unnecessarily-shown-repeatedly-required-non-automated","title":"Use throttled logging when the log is unnecessarily shown repeatedly (required, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale_2","title":"Rationale","text":"

If tons of logs are shown on the console, people miss important message.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example_2","title":"Example","text":"

While waiting for some messages, throttled logs are usually enough. In such cases, wait about 5 seconds as a reference value.

// Compliant\nvoid FooNode::on_timer() {\nif (!current_pose_) {\nRCLCPP_ERROR_THROTTLE(get_logger(), *get_clock(), 5000, \"Waiting for current_pose_.\");\nreturn;\n}\n}\n\n// Non-compliant\nvoid FooNode::on_timer() {\nif (!current_pose_) {\nRCLCPP_ERROR(get_logger(), \"Waiting for current_pose_.\");\nreturn;\n}\n}\n
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#exception","title":"Exception","text":"

The following cases are acceptable even if it's not throttled.

  • The message is really worth displaying every time.
  • The message level is DEBUG.
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#do-not-depend-on-rclcppnode-in-core-library-classes-but-depend-only-on-rclcpplogginghpp-advisory-non-automated","title":"Do not depend on rclcpp::Node in core library classes but depend only on rclcpp/logging.hpp (advisory, non-automated)","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#rationale_3","title":"Rationale","text":"

Core library classes, which contain reusable algorithms, may also be used for non-ROS platforms. When porting libraries to other platforms, fewer dependencies are preferred.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#example_3","title":"Example","text":"
// Compliant\n#include <rclcpp/logging.hpp>\n\nclass FooCore {\npublic:\nexplicit FooCore(const rclcpp::Logger & logger) : logger_(logger) {}\n\nvoid process() {\nRCLCPP_INFO(logger_, \"message\");\n}\n\nprivate:\nrclcpp::Logger logger_;\n};\n\n// Compliant\n// Note that logs aren't published to `/rosout` if the logger name is different from the node name.\n#include <rclcpp/logging.hpp>\n\nclass FooCore {\nvoid process() {\nRCLCPP_INFO(rclcpp::get_logger(\"foo_core_logger\"), \"message\");\n}\n};\n\n\n// Non-compliant\n#include <rclcpp/node.hpp>\n\nclass FooCore {\npublic:\nexplicit FooCore(const rclcpp::NodeOptions & node_options) : node_(\"foo_core_node\", node_options) {}\n\nvoid process() {\nRCLCPP_INFO(node_.get_logger(), \"message\");\n}\n\nprivate:\nrclcpp::Node node_;\n};\n
"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#tips","title":"Tips","text":""},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#use-rqt_console-to-filter-logs","title":"Use rqt_console to filter logs","text":"

To filter logs, using rqt_console is useful:

ros2 run rqt_console rqt_console\n

For more details, refer to ROS 2 Documentation.

"},{"location":"contributing/coding-guidelines/ros-nodes/console-logging/#useful-marco-expressions","title":"Useful marco expressions","text":"

To debug program, sometimes you need to see which functions and lines of code are executed. In that case, you can use __FILE__, __LINE__ and __FUNCTION__ macro:

void FooNode::on_timer() {\nRCLCPP_DEBUG(get_logger(), \"file: %s, line: %s, function: %s\" __FILE__, __LINE__, __FUNCTION__);\n}\n

The example output is as follows:

[DEBUG] [1671720414.395456931] [foo]: file: /path/to/file.cpp, line: 100, function: on_timer

"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/","title":"Coordinate system","text":""},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#coordinate-system","title":"Coordinate system","text":""},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#overview","title":"Overview","text":"

The commonly used coordinate systems include the world coordinate system, the vehicle coordinate system, and the sensor coordinate system.

  • The world coordinate system is a fixed coordinate system that defines the physical space in the environment where the vehicle is located.
  • The vehicle coordinate system is the vehicle's own coordinate system, which defines the vehicle's position and orientation in the world coordinate system.
  • The sensor coordinate system is the sensor's own coordinate system, which is used to define the sensor's position and orientation in the vehicle coordinate system.
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#how-coordinates-are-used-in-autoware","title":"How coordinates are used in Autoware","text":"

In Autoware, coordinate systems are typically used to represent the position and movement of vehicles and obstacles in space. Coordinate systems are commonly used for path planning, perception and control, can help the vehicle decide how to avoid obstacles and to plan a safe and efficient path of travel.

  1. Transformation of sensor data

    In Autoware, each sensor has a unique coordinate system and their data is expressed in terms of the coordinates. In order to correlate the independent data between different sensors, we need to find the position relationship between each sensor and the vehicle body. Once the installation position of the sensor on the vehicle body is determined, it will remain fixed during running, so the offline calibration method can be used to determine the precise position of each sensor relative to the vehicle body.

  2. ROS TF2

    The TF2 system maintains a tree of coordinate transformations to represent the relationships between different coordinate systems. Each coordinate system is given a unique name and they are connected by coordinate transformations. How to use TF2, refer to the TF2 tutorial.

"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#tf-tree","title":"TF tree","text":"

In Autoware, a common coordinate system structure is shown below:

graph TD\n    /earth --> /map\n    /map --> /base_link\n    /base_link --> /imu\n    /base_link --> /lidar\n    /base_link --> /gnss\n    /base_link --> /radar\n    /base_link --> /camera_link\n    /camera_link --> /camera_optical_link
  • earth: earth coordinate system describe the position of any point on the earth in terms of geodetic longitude, latitude, and altitude. In Autoware, the earth frame is only used in the GnssInsPositionStamped message.
  • map: map coordinate system is used to represent the location of points on a local map. Geographical coordinate system are mapped into plane rectangular coordinate system using UTM or MGRS. The map frame`s axes point to the East, North, Up directions as explained in Coordinate Axes Conventions.
  • base_link: vehicle coordinate system, the origin of the coordinate system is the center of the rear axle of the vehicle.
  • imu, lidar, gnss, radar: these are sensor frames, transfer to vehicle coordinate system through mounting relationship.
  • camera_link: camera_link is ROS standard camera coordinate system .
  • camera_optical_link: camera_optical_link is image standard camera coordinate system.
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#estimating-the-base_link-frame-by-using-the-other-sensors","title":"Estimating the base_link frame by using the other sensors","text":"

Generally we don't have the localization sensors physically at the base_link frame. So various sensors localize with respect to their own frames, let's call it sensor frame.

We introduce a new frame naming convention: x_by_y:

x: estimated frame name\ny: localization method/source\n

We cannot directly get the sensor frame. Because we would need the EKF module to estimate the base_link frame first.

Without the EKF module the best we can do is to estimate Map[map] --> sensor_by_sensor --> base_link_by_sensor using this sensor.

"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#example-by-the-gnssins-sensor","title":"Example by the GNSS/INS sensor","text":"

For the integrated GNSS/INS we use the following frames:

flowchart LR\n    earth --> Map[map] --> gnss_ins_by_gnss_ins --> base_link_by_gnss_ins

The gnss_ins_by_gnss_ins frame is obtained by the coordinates from GNSS/INS sensor. The coordinates are converted to map frame using the gnss_poser node.

Finally gnss_ins_by_gnss_ins frame represents the position of the gnss_ins estimated by the gnss_ins sensor in the map.

Then by using the static transformation between gnss_ins and the base_link frame, we can obtain the base_link_by_gnss_ins frame. Which represents the base_link estimated by the gnss_ins sensor.

References:

  • https://www.ros.org/reps/rep-0105.html#earth
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#coordinate-axes-conventions","title":"Coordinate Axes Conventions","text":"

We are using East, North, Up (ENU) coordinate axes convention by default throughout the stack.

X+: East\nY+: North\nZ+: Up\n

The position, orientation, velocity, acceleration are all defined in the same axis convention.

Position by the GNSS/INS sensor is expected to be in earth frame.

Orientation, velocity, acceleration by the GNSS/INS sensor are expected to be in the sensor frame. Axes parallel to the map frame.

If roll, pitch, yaw is provided, they correspond to rotation around X, Y, Z axes respectively.

Rotation around:\nX+: roll\nY+: pitch\nZ+: yaw\n

References:

  • https://www.ros.org/reps/rep-0103.html#axis-orientation
"},{"location":"contributing/coding-guidelines/ros-nodes/coordinate-system/#how-they-can-be-created","title":"How they can be created","text":"

  1. Calibration of sensor

    The conversion relationship between every sensor coordinate system and base_link can be obtained through sensor calibration technology. How to calibrating your sensors refer to this link calibrating your sensors.

  2. Localization

    The relationship between the base_link coordinate system and the map coordinate system is determined by the position and orientation of the vehicle, and can be obtained from the vehicle localization result.

  3. Geo-referencing of map data

    The geo-referencing information can get the transformation relationship of earth coordinate system to local map coordinate system.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/","title":"Directory structure","text":""},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#directory-structure","title":"Directory structure","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#c-package","title":"C++ package","text":"
<package_name>\n\u251c\u2500 config\n\u2502   \u251c\u2500 foo_ros.param.yaml\n\u2502   \u2514\u2500 foo_non_ros.yaml\n\u251c\u2500 include\n\u2502   \u2514\u2500 <package_name>\n\u2502      \u2514\u2500 foo_public.hpp\n\u251c\u2500 launch\n\u2502   \u251c\u2500 foo.launch.xml\n\u2502   \u2514\u2500 foo.launch.py\n\u251c\u2500 src\n\u2502   \u251c\u2500 foo_node.cpp\n\u2502   \u251c\u2500 foo_node.hpp\n\u2502   \u2514\u2500 foo_private.hpp\n\u251c\u2500 test\n\u2502   \u2514\u2500 test_foo.cpp\n\u251c\u2500 package.xml\n\u2514\u2500 CMakeLists.txt\n
"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#config-directory","title":"config directory","text":"

Place configuration files such as node parameters.

For ROS parameters, use the extension .param.yaml. For non-ROS parameters, use the extension .yaml.

Rationale: Since ROS parameters files are type-sensitive, they should not be the target of some code formatters and linters. In order to distinguish the file type, we use different file extensions.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#include-directory","title":"include directory","text":"

Place header files exposed to other packages. Do not place files directly under the include directory, but place files under the directory with the package name. This directory is used for mostly library headers. Note that many headers do not need to be placed here. It is enough to place the headers under the src directory.

Reference: https://docs.ros.org/en/rolling/How-To-Guides/Ament-CMake-Documentation.html#adding-files-and-headers

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#launch-directory","title":"launch directory","text":"

Place launch files (.launch.xml and .launch.py).

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#src-directory","title":"src directory","text":"

Place source files and private header files.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#test-directory","title":"test directory","text":"

Place source files for testing.

"},{"location":"contributing/coding-guidelines/ros-nodes/directory-structure/#python-package","title":"Python package","text":"

T.B.D.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/","title":"Launch files","text":""},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#launch-files","title":"Launch files","text":""},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#overview","title":"Overview","text":"

Autoware use ROS2 launch system to startup the software. Please see the official documentation to get a basic understanding about ROS 2 Launch system if you are not familiar with it.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#guideline","title":"Guideline","text":""},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#the-organization-of-launch-files-in-autoware","title":"The organization of launch files in Autoware","text":"

Autoware mainly has two repositories related to launch file organization: the autoware.universe and the autoware_launch.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#autowareuniverse","title":"autoware.universe","text":"

the autoware.universe contains the code of the main Autoware modules, and its launch directory is responsible for launching the nodes of each module. Autoware software stack is organized based on the architecture, so you may find that we try to match the launch structure similar to the architecture (splitting of files, namespace). For example, the tier4_map_launch subdirectory corresponds to the map module, so do the other tier4_*_launch subdirectories.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#autoware_launch","title":"autoware_launch","text":"

The autoware_launch is a repository referring to autoware.universe. The mainly purpose of introducing this repository is to provide the general entrance to start the Autoware software stacks, i.e, calling the launch file of each module.

  • The autoware.launch.xml is the basic launch file for road driving scenarios.

    As can be seen from the content, the entire launch file is divided into several different modules, including Vehicle, System, Map, Sensing, Localization, Perception, Planning, Control, etc. By setting the launch_* argument equals to true or false , we can determine which modules to be loaded.

  • The logging_simulator.launch.xml is often used together with the recorded ROS bag to debug if the target module (e.g, Sensing, Localization or Perception) functions normally.
  • The planning_simulator.launch.xml is based on the Planning Simulator tool, mainly used for testing/validation of Planning module by simulating traffic rules, interactions with dynamic objects and control commands to the ego vehicle.
  • The e2e_simulator.launch.xml is the launcher for digital twin simulation environment.
graph LR\nA11[logging_simulator.launch.xml]-.->A10[autoware.launch.xml]\nA12[planning_simulator.launch.xml]-.->A10[autoware.launch.xml]\nA13[e2e_simulator.launch.xml]-.->A10[autoware.launch.xml]\n\nA10-->A21[tier4_map_component.launch.xml]\nA10-->A22[xxx.launch.py]\nA10-->A23[tier4_localization_component.launch.xml]\nA10-->A24[xxx.launch.xml]\nA10-->A25[tier4_sensing_component.launch.xml]\n\nA23-->A30[localization.launch.xml]\nA30-->A31[pose_estimator.launch.xml]\nA30-->A32[util.launch.xml]\nA30-->A33[pose_twist_fusion_filter.launch.xml]\nA30-->A34[xxx.launch.xml]\nA30-->A35[twist_estimator.launch.xml]\n\nA33-->A41[stop_filter.launch.xml]\nA33-->A42[ekf_localizer.launch.xml]\nA33-->A43[twist2accel.launch.xml]
"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#add-a-new-package-in-autoware","title":"Add a new package in Autoware","text":"

If a newly created package has executable node, we expect sample launch file and configuration within the package, just like the recommended structure shown in previous directory structure page.

In order to automatically load the newly added package when starting Autoware, you need to make some necessary changes to the corresponding launch file. For example, if using ICP instead of NDT as the pointcloud registration algorithm, you can modify the autoware.universe/launch/tier4_localization_launch/launch/pose_estimator/pose_estimator.launch.xml file to load the newly added ICP package.

"},{"location":"contributing/coding-guidelines/ros-nodes/launch-files/#parameter-management","title":"Parameter management","text":"

Another purpose of introducing the autoware_launch repository is to facilitate the parameter management of Autoware. Thinking about this situation: if we want to integrate Autoware to a specific vehicle and modify parameters, we have to fork autoware.universe which also has a lot of code other than parameters and is frequently updated by developers. By intergrating these parameters in autoware_launch, we can customize the Autoware parameters just by forking autoware_launch repository. Taking the localization module as an examples:

  1. all the \u201claunch parameters\u201d for localization component is listed in the files under autoware_launch/autoware_launch/config/localization.
  2. the \"launch parameters\" file paths are set in the autoware_launch/autoware_launch/launch/components/tier4_localization_component.launch.xml file.
  3. in autoware.universe/launch/tier4_localization_launch/launch, the launch files loads the \u201claunch parameters\u201d if the argument is given in the parameter configuration file. You can still use the default parameters in each packages to launch tier4_localization_launch within autoware.universe.
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/","title":"Message guidelines","text":""},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#message-guidelines","title":"Message guidelines","text":""},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#format","title":"Format","text":"

All messages should follow ROS message description specification.

The accepted formats are:

  • .msg
  • .srv
  • .action
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#naming","title":"Naming","text":"

Under Construction

Use Array as a suffix when creating a plural type of a message. This suffix is commonly used in common_interfaces.

"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#default-units","title":"Default units","text":"

All the fields by default have the following units depending on their types:

type default unit distance meter (m) angle radians (rad) time second (s) speed m/s velocity m/s acceleration m/s\u00b2 angular vel. rad/s angular accel. rad/s\u00b2

If a field in a message has any of these default units, don't add any suffix or prefix denoting the type.

"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#non-default-units","title":"Non-default units","text":"

For non-default units, use following suffixes:

type non-default unit suffix distance nanometer _nm distance micrometer _um distance millimeter _mm distance kilometer _km angle degree (deg) _deg time nanosecond _ns time microsecond _us time millisecond _ms time minute _min time hour (h) _hour velocity km/h _kmph

If a unit that you'd like to use doesn't exist here, create an issue/PR to add it to this list.

"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#message-field-types","title":"Message field types","text":"

For list of types supported by the ROS interfaces see here.

Also copied here for convenience:

Message Field Type C++ equivalent bool bool byte uint8_t char char float32 float float64 double int8 int8_t uint8 uint8_t int16 int16_t uint16 uint16_t int32 int32_t uint32 uint32_t int64 int64_t uint64 uint64_t string std::string wstring std::u16string"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#arrays","title":"Arrays","text":"

For arrays, use unbounded dynamic array type.

Example:

int32[] unbounded_integer_array\n
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#enumerations","title":"Enumerations","text":"

ROS 2 interfaces don't support enumerations directly.

It is possible to define integers constants and assign them to a non-constant integer parameter.

Constants are written in CONSTANT_CASE.

Assign a different value to each element of a constant.

Example from shape_msgs/msg/SolidPrimitive.msg

uint8 BOX=1\nuint8 SPHERE=2\nuint8 CYLINDER=3\nuint8 CONE=4\nuint8 PRISM=5\n\n# The type of the shape\nuint8 type\n
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#comments","title":"Comments","text":"

On top of the message, briefly explain what the message contains and/or what it is used for. For an example, see sensor_msgs/msg/Imu.msg.

If necessary, add line comments before the fields that explain the context and/or meaning.

For simple fields like x, y, z, w you might not need to add comments.

Even though it is not strictly checked, try not to pass 100 characters in a line.

Example:

# Number of times the vehicle performed an emergency brake\nuint32 count_emergency_brake\n\n# Seconds passed since the last emergency brake\nuint64 duration\n
"},{"location":"contributing/coding-guidelines/ros-nodes/message-guidelines/#example-usages","title":"Example usages","text":"
  • Don't use unit suffixes for default types:
    • Bad: float32 path_length_m
    • Good: float32 path_length
  • Don't prefix the units:
    • Bad: float32 kmph_velocity_vehicle
    • Good: float32 velocity_vehicle_kmph
  • Use recommended suffixes if they are available in the table:
    • Bad: float32 velocity_vehicle_km_h
    • Good: float32 velocity_vehicle_kmph
"},{"location":"contributing/coding-guidelines/ros-nodes/parameters/","title":"Parameters","text":""},{"location":"contributing/coding-guidelines/ros-nodes/parameters/#parameters","title":"Parameters","text":"

The ROS packages in Autoware have ROS parameters. You need to customize the parameters depending on your applications. It is recommended not to set default values when declaring ROS parameters to avoid unintended behaviors due to accidental use of default values. Instead, set parameters from configuration files named *.param.yaml.

For understanding ROS 2 parameters, also check out the official documentation Understanding parameters.

"},{"location":"contributing/coding-guidelines/ros-nodes/parameters/#parameter-files","title":"Parameter files","text":"

Autoware has the following two types of parameter files for ROS packages:

  • Node parameter file
    • Node parameter files store the default parameters provided for each package in Autoware.
      • For example, the parameter of behavior_path_planner
    • All nodes in Autoware must have a parameter file if one or more parameters that can be customized by the user are defined.
    • For FOO_package, the parameter is expected to be stored in FOO_package/config.
    • The launch file for individual packages must load node parameter by default:
<launch>\n<arg name=\"foo_node_param_path\" default=\"$(find-pkg-share FOO_package)/config/foo_node.param.yaml\" />\n\n<node pkg=\"FOO_package\" exec=\"foo_node\">\n...\n    <param from=\"$(var foo_node_param_path)\" />\n</node>\n</launch>\n
  • Launch parameter file
    • Launch parameter files store the customized parameters for user's vehicle.
      • For example, the customized parameter of behavior_path_planner stored under autoware_launch
    • Launch parameter files are stored under autoware_launch.

All the parameter files should have the .param.yaml suffix so that the auto-format can be applied properly.

"},{"location":"contributing/coding-guidelines/ros-nodes/task-scheduling/","title":"Task scheduling","text":""},{"location":"contributing/coding-guidelines/ros-nodes/task-scheduling/#task-scheduling","title":"Task scheduling","text":"

Warning

Under Construction

"},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/","title":"Topic namespaces","text":""},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#topic-namespaces","title":"Topic namespaces","text":""},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#overview","title":"Overview","text":"

ROS allows topics, parameters and nodes to be namespaced which provides the following benefits:

  • Multiple instances of the same node type will not cause naming clashes.
  • Topics published by a node can be automatically namespaced with the node's namespace providing a meaningful and easily-visible connection.
  • Keeps from cluttering the root namespace.
  • Helps to maintain separation-of-concerns.

This page focuses on how to use namespaces in Autoware and shows some useful examples. For basic information on topic namespaces, refer to this tutorial.

"},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#how-topics-should-be-named-in-node","title":"How topics should be named in node","text":"

Autoware divides the node into the following functional categories, and adds the start namespace for the nodes according to the categories.

  • localization
  • perception
  • planning
  • control
  • sensing
  • vehicle
  • map
  • system

When a node is run in a namespace, all topics which that node publishes are given that same namespace. All nodes in the Autoware stack must support namespaces by avoiding practices such as publishing topics in the global namespace.

In general, topics should be namespaced based on the function of the node which produces them and not the node (or nodes) which consume them.

Classify topics as input or output topics based on they are subscribed or published by the node. In the node, input topic is named input/topic_name and output topic is named output/topic_name.

Configure the topic in the node's launch file. Take the joy_controller node as an example, in the following example, set the input and output topics and remap topics in the joy_controller.launch.xml file.

<launch>\n<arg name=\"input_joy\" default=\"/joy\"/>\n<arg name=\"input_odometry\" default=\"/localization/kinematic_state\"/>\n\n<arg name=\"output_control_command\" default=\"/external/$(var external_cmd_source)/joy/control_cmd\"/>\n<arg name=\"output_external_control_command\" default=\"/api/external/set/command/$(var external_cmd_source)/control\"/>\n<arg name=\"output_shift\" default=\"/api/external/set/command/$(var external_cmd_source)/shift\"/>\n<arg name=\"output_turn_signal\" default=\"/api/external/set/command/$(var external_cmd_source)/turn_signal\"/>\n<arg name=\"output_heartbeat\" default=\"/api/external/set/command/$(var external_cmd_source)/heartbeat\"/>\n<arg name=\"output_gate_mode\" default=\"/control/gate_mode_cmd\"/>\n<arg name=\"output_vehicle_engage\" default=\"/vehicle/engage\"/>\n\n<node pkg=\"joy_controller\" exec=\"joy_controller\" name=\"joy_controller\" output=\"screen\">\n<remap from=\"input/joy\" to=\"$(var input_joy)\"/>\n<remap from=\"input/odometry\" to=\"$(var input_odometry)\"/>\n\n<remap from=\"output/control_command\" to=\"$(var output_control_command)\"/>\n<remap from=\"output/external_control_command\" to=\"$(var output_external_control_command)\"/>\n<remap from=\"output/shift\" to=\"$(var output_shift)\"/>\n<remap from=\"output/turn_signal\" to=\"$(var output_turn_signal)\"/>\n<remap from=\"output/gate_mode\" to=\"$(var output_gate_mode)\"/>\n<remap from=\"output/heartbeat\" to=\"$(var output_heartbeat)\"/>\n<remap from=\"output/vehicle_engage\" to=\"$(var output_vehicle_engage)\"/>\n</node>\n</launch>\n
"},{"location":"contributing/coding-guidelines/ros-nodes/topic-namespaces/#topic-names-in-the-code","title":"Topic names in the code","text":"

  1. Have ~ so that namespace in launch configuration is applied(should not start from root /).

  2. Have ~/input ~/output namespace before topic name used to communicate with other nodes.

    e.g., In node obstacle_avoidance_planner, using topic names of type ~/input/topic_name to subscribe to topics.

    objects_sub_ = create_subscription<PredictedObjects>(\n\"~/input/objects\", rclcpp::QoS{10},\nstd::bind(&ObstacleAvoidancePlanner::onObjects, this, std::placeholders::_1));\n

    e.g., In node obstacle_avoidance_planner, using topic names of type ~/output/topic_name to publish topic.

    traj_pub_ = create_publisher<Trajectory>(\"~/output/path\", 1);\n

  3. Visualization or debug purpose topics should have ~/debug/ namespace.

    e.g., In node obstacle_avoidance_planner, in order to debug or visualizing topics, using topic names of type ~/debug/topic_name to publish information.

    debug_markers_pub_ =\ncreate_publisher<visualization_msgs::msg::MarkerArray>(\"~/debug/marker\", durable_qos);\n\ndebug_msg_pub_ =\ncreate_publisher<tier4_debug_msgs::msg::StringStamped>(\"~/debug/calculation_time\", 1);\n

    The launch configured namespace will be add the topics before, so the topic names will be as following:

    /planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/marker /planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/calculation_time

  4. Rationale: we want to make topic names remapped and configurable from launch files.

"},{"location":"contributing/discussion-guidelines/","title":"Discussion guidelines","text":""},{"location":"contributing/discussion-guidelines/#discussion-guidelines","title":"Discussion guidelines","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://docs.github.com/en/discussions/guides/best-practices-for-community-conversations-on-github
  • https://opensource.guide/how-to-contribute/#communicating-effectively
"},{"location":"contributing/documentation-guidelines/","title":"Documentation guidelines","text":""},{"location":"contributing/documentation-guidelines/#documentation-guidelines","title":"Documentation guidelines","text":""},{"location":"contributing/documentation-guidelines/#workflow","title":"Workflow","text":"

Contributions to Autoware's documentation are welcome, and the same principles described in the contribution guidelines should be followed. Small, limited changes can be made by forking this repository and submitting a pull request, but larger changes should be discussed with the community and Autoware maintainers via GitHub Discussion first.

Examples of small changes include:

  • Fixing spelling or grammatical mistakes
  • Fixing broken links
  • Making an addition to an existing, well-defined page, such as the Troubleshooting guide.

Examples of larger changes include:

  • Adding new pages with a large amount of detail, such as a tutorial
  • Re-organization of the existing documentation structure
"},{"location":"contributing/documentation-guidelines/#style-guide","title":"Style guide","text":"

You should refer to the Google developer documentation style guide as much as possible. Reading the Highlights page of that guide is recommended, but if not then the key points below should be noted.

  • Use standard American English spelling and punctuation.
  • Use sentence case for document titles and section headings.
  • Use descriptive link text.
  • Write short sentences that are easy to understand and translate.
"},{"location":"contributing/documentation-guidelines/#tips","title":"Tips","text":""},{"location":"contributing/documentation-guidelines/#how-to-preview-your-modification","title":"How to preview your modification","text":"

There are two ways to preview your modification on a documentation website.

"},{"location":"contributing/documentation-guidelines/#1-using-github-actions-workflow","title":"1. Using GitHub Actions workflow","text":"

Follow the steps below.

  1. Create a pull request to the repository.
  2. Add the deploy-docs label from the sidebar (See below figure).
  3. Wait for a couple of minutes, and the github-actions bot will notify the URL for the pull request's preview.

"},{"location":"contributing/documentation-guidelines/#2-running-an-mkdocs-server-in-your-local-environment","title":"2. Running an MkDocs server in your local environment","text":"

Instead of creating a PR, you can use the mkdocs command to build Autoware's documentation websites on your local computer. Assuming that you are using Ubuntu OS, run the following to install the required libraries.

python3 -m pip install -U $(curl -fsSL https://raw.githubusercontent.com/autowarefoundation/autoware-github-actions/main/deploy-docs/mkdocs-requirements.txt)\n

Then, run mkdocs serve on your documentation directory.

cd /PATH/TO/YOUR-autoware-documentation\nmkdocs serve\n

It will launch the MkDocs server. Access http://127.0.0.1:8000/ to see the preview of the website.

"},{"location":"contributing/pull-request-guidelines/","title":"Pull request guidelines","text":""},{"location":"contributing/pull-request-guidelines/#pull-request-guidelines","title":"Pull request guidelines","text":""},{"location":"contributing/pull-request-guidelines/#general-pull-request-workflow","title":"General pull request workflow","text":"

Autoware uses the fork-and-pull model. For more details about the model, refer to GitHub Docs.

The following is a general example of the pull request workflow based on the fork-and-pull model. Use this workflow as a reference when you contribute to Autoware.

  1. Create an issue.
    • Discuss the approaches to the issue with maintainers.
    • Confirm the support guidelines before creating an issue.
    • Follow the discussion guidelines when you discuss with other contributors.
  2. Create a fork repository. (for the first time only)
  3. Write code in your fork repository according to the approach agreed upon in the issue.
    • Write the tests and documentation as appropriate.
    • Follow the coding guidelines guidelines when you write code.
    • Follow the Testing guidelines guidelines when you write tests.
    • Follow the Documentation guidelines guidelines when you write documentation.
    • Follow the commit guidelines when you commit your changes.
  4. Test the code.
    • It is recommended that you summarize the test results, because you will need to explain the test results in the later review process.
    • If you are not sure what tests should be done, discuss them with maintainers.
  5. Create a pull request.
    • Follow the pull request rules when you create a pull request.
  6. Wait for the pull request to be reviewed.
    • The reviewers will review your code following the review guidelines.
      • Not only the reviewers, but also the author is encouraged to understand the review guidelines.
    • If CI checks have failed, fix the errors.
  7. Address the review comments pointed out by the reviewers.
    • If you don't understand the meaning of a review comment, ask the reviewers until you understand it.
      • Fixing without understanding the reason is not recommended because the author should be responsible for the final content of their own pull request.
    • If you don't agree with a review comment, ask the reviewers for a rational reason.
      • The reviewers are obligated to make the author understand the meanings of each comment.
    • After you have done with the review comments, re-request a review to the reviewers and back to 6.
    • If there are no more new review comments, the reviewers will approve the pull request and proceed to 8.
  8. Merge the pull request.
    • Anyone with write access can merge the pull request if there is no special request from maintainers.
      • The author is encouraged to merge the pull request to feel responsible for their own pull request.
      • If the author does not have write access, ask the reviewers or maintainers.
"},{"location":"contributing/pull-request-guidelines/#pull-request-rules","title":"Pull request rules","text":""},{"location":"contributing/pull-request-guidelines/#use-an-appropriate-pull-request-template-required-non-automated","title":"Use an appropriate pull request template (required, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale","title":"Rationale","text":"
  • The unified style of descriptions by templates can make reviews efficient.
"},{"location":"contributing/pull-request-guidelines/#example","title":"Example","text":"

There are two types of templates. Select one based on the following condition.

  1. Standard change:
    • Complexity:
      • New features or significant updates.
      • Requires deeper understanding of the codebase.
    • Impact:
      • Affects multiple parts of the system.
      • Basically includes minor features, bug fixes and performance improvement.
      • Needs testing before merging.
  2. Small change:
    • Complexity:
      • Documentation, simple refactoring, or style adjustments.
      • Easy to understand and review.
    • Impact:
      • Minimal effect on the system.
      • Quicker merge with less testing needed.
"},{"location":"contributing/pull-request-guidelines/#steps-to-use-an-appropriate-pull-request-template","title":"Steps to use an appropriate pull request template","text":"
  1. Select the appropriate template, as shown in this video.
  2. Read the selected template carefully and fill the required content.
  3. Check the checkboxes during a review.
    • There are pre-review checklist and post-review checklist for the author.
"},{"location":"contributing/pull-request-guidelines/#set-appropriate-reviewers-after-creating-a-pull-request-required-partially-automated","title":"Set appropriate reviewers after creating a pull request (required, partially automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_1","title":"Rationale","text":"
  • Pull requests must be reviewed by appropriate reviewers to keep the quality of the codebase.
"},{"location":"contributing/pull-request-guidelines/#example_1","title":"Example","text":"
  • For most ROS packages, reviewers will be automatically assigned based on the maintainer information in package.xml.
  • If no reviewer is assigned automatically, assign reviewers manually following the instructions in GitHub Docs.
    • You can find the reviewers by seeing the .github/CODEOWNERS file of the repository.
  • If you are not sure the appropriate reviewers, ask @autoware-maintainers.
  • If you have no rights to assign reviewers, mention reviewers instead.
"},{"location":"contributing/pull-request-guidelines/#apply-conventional-commits-to-the-pull-request-title-required-automated","title":"Apply Conventional Commits to the pull request title (required, automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_2","title":"Rationale","text":"
  • Conventional Commits can generate categorized changelogs, for example using git-cliff.
"},{"location":"contributing/pull-request-guidelines/#example_2","title":"Example","text":"
feat(trajectory_follower): add an awesome feature\n

Note

You have to start the description part (here add an awesome feature) with a lowercase.

If your change breaks some interfaces, use the ! (breaking changes) mark as follows:

feat(trajectory_follower)!: remove package\nfeat(trajectory_follower)!: change parameter names\nfeat(planning)!: change topic names\nfeat(autoware_utils)!: change function names\n

For the repositories that contain code (most repositories), use the definition of conventional-commit-types for the type.

For documentation repositories such as autoware-documentation, use the following definition:

  • feat
    • Add new pages.
    • Add contents to the existing pages.
  • fix
    • Fix the contents in the existing pages.
  • refactor
    • Move contents to different pages.
  • docs
    • Update documentation for the documentation repository itself.
  • build
    • Update the settings of the documentation site builder.
  • ! (breaking changes)
    • Remove pages.
    • Change the URL of pages.

perf and test are generally unused. Other types have the same meaning as the code repositories.

"},{"location":"contributing/pull-request-guidelines/#add-the-related-component-names-to-the-scope-of-conventional-commits-advisory-non-automated","title":"Add the related component names to the scope of Conventional Commits (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_3","title":"Rationale","text":"
  • It helps contributors find pull requests that are relevant to them.
  • It makes the changelog clearer.
"},{"location":"contributing/pull-request-guidelines/#example_3","title":"Example","text":"

For ROS packages, adding the package name or component name is good.

feat(trajectory_follower): add an awesome feature\nrefactor(planning, control): use common utils\n
"},{"location":"contributing/pull-request-guidelines/#keep-a-pull-request-small-advisory-non-automated","title":"Keep a pull request small (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_4","title":"Rationale","text":"
  • Small pull requests are easy to understand for reviewers.
  • Small pull requests are easy to revert for maintainers.
"},{"location":"contributing/pull-request-guidelines/#exception","title":"Exception","text":"

It is acceptable if it is agreed with maintainers that there is no other way but to submit a big pull request.

"},{"location":"contributing/pull-request-guidelines/#example_4","title":"Example","text":"
  • Avoid developing two features in one pull request.
  • Avoid mixing different types (feat, fix, refactor, etc.) of changes in the same commit.
"},{"location":"contributing/pull-request-guidelines/#remind-reviewers-if-there-is-no-response-for-more-than-a-week-advisory-non-automated","title":"Remind reviewers if there is no response for more than a week (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/#rationale_5","title":"Rationale","text":"
  • It is the author's responsibility to care about their own pull request until it is merged.
"},{"location":"contributing/pull-request-guidelines/#example_5","title":"Example","text":"
@{some-of-developers} Would it be possible for you to review this PR?\n@autoware-maintainers friendly ping.\n
"},{"location":"contributing/pull-request-guidelines/ci-checks/","title":"CI checks","text":""},{"location":"contributing/pull-request-guidelines/ci-checks/#ci-checks","title":"CI checks","text":"

Autoware has several checks for a pull request. The results are shown at the bottom of the pull request page as below.

If the \u274c mark is shown, click the Details button and investigate the failure reason.

If the Required mark is shown, you cannot merge the pull request unless you resolve the error. If not, it is optional, but preferably it should be fixed.

The following sections explain about common CI checks in Autoware. Note that some repositories may have different settings.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#dco","title":"DCO","text":"

The Developer Certificate of Origin (DCO) is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project.

This workflow checks whether the pull request fulfills DCO. You need to confirm the required items and commit with git commit -s.

For more information, refer to the GitHub App page.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#semantic-pull-request","title":"semantic-pull-request","text":"

This workflow checks whether the pull request follows Conventional Commits.

For the detailed rules, see the pull request rules.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#pre-commit","title":"pre-commit","text":"

pre-commit is a tool to run formatters or linters when you commit.

This workflow checks whether the pull request has no error with pre-commit.

In the workflow pre-commit.ci - pr is enabled in the repository, it will automatically fix errors by pre-commit.ci as many as possible. If there are some errors remain, fix them manually.

You can run pre-commit in your local environment by the following command:

pre-commit run -a\n

Or you can install pre-commit to the repository and automatically run it before committing:

pre-commit install\n

Since it is difficult to detect errors with no false positives, some jobs are split into another config file and marked as optional. To check them, use the --config option:

pre-commit run -a --config .pre-commit-config-optional.yaml\n
"},{"location":"contributing/pull-request-guidelines/ci-checks/#spell-check-differential","title":"spell-check-differential","text":"

This workflow detects spelling mistakes using CSpell with our dictionary file. You can submit pull requests to tier4/autoware-spell-check-dict to update the dictionary.

Since it is difficult to detect errors with no false positives, it is an optional workflow, but it is preferable to remove spelling mistakes as many as possible.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#build-and-test-differential","title":"build-and-test-differential","text":"

This workflow checks colcon build and colcon test for the pull request. To make the CI faster, it doesn't check all packages but only modified packages and the dependencies.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#build-and-test-differential-self-hosted","title":"build-and-test-differential-self-hosted","text":"

This workflow is the ARM64 version of build-and-test-differential. You need to add the ARM64 label to run this workflow.

For reference information, since ARM machines are not supported by GitHub-hosted runners, we use self-hosted runners prepared by the AWF. For the details about self-hosted runners, refer to GitHub Docs.

"},{"location":"contributing/pull-request-guidelines/ci-checks/#deploy-docs","title":"deploy-docs","text":"

This workflow deploys the preview documentation site for the pull request. You need to add the deploy-docs label to run this workflow.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/","title":"Commit guidelines","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#commit-guidelines","title":"Commit guidelines","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#branch-rules","title":"Branch rules","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#start-branch-names-with-the-corresponding-issue-numbers-advisory-non-automated","title":"Start branch names with the corresponding issue numbers (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale","title":"Rationale","text":"
  • Developers can quickly find the corresponding issues.
  • It is helpful for tools.
  • It is consistent with GitHub's default behavior.
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#exception","title":"Exception","text":"

If there are no corresponding issues, you can ignore this rule.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example","title":"Example","text":"
123-add-feature\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#reference","title":"Reference","text":"
  • GitHub Docs
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#use-dash-case-for-the-separator-of-branch-names-advisory-non-automated","title":"Use dash-case for the separator of branch names (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale_1","title":"Rationale","text":"
  • It is consistent with GitHub's default behavior.
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example_1","title":"Example","text":"
123-add-feature\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#reference_1","title":"Reference","text":"
  • GitHub Docs
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#make-branch-names-descriptive-advisory-non-automated","title":"Make branch names descriptive (advisory, non-automated)","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale_2","title":"Rationale","text":"
  • It can avoid conflicts of names.
  • Developers can understand the purpose of the branch.
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#exception_1","title":"Exception","text":"

If you have already submitted a pull request, you do not have to change the branch name because you need to re-create a pull request, which is noisy and a waste of time. Be careful from the next time.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example_2","title":"Example","text":"

Usually it is good to start with a verb.

123-fix-memory-leak-of-trajectory-follower\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#commit-rules","title":"Commit rules","text":""},{"location":"contributing/pull-request-guidelines/commit-guidelines/#sign-off-your-commits-required-automated","title":"Sign-off your commits (required, automated)","text":"

Developers must certify that they wrote or otherwise have the right to submit the code they are contributing to the project.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#rationale_3","title":"Rationale","text":"

If not, it will lead to complex license problems.

"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#example_3","title":"Example","text":"
git commit -s\n
feat: add a feature\n\nSigned-off-by: Autoware <autoware@example.com>\n
"},{"location":"contributing/pull-request-guidelines/commit-guidelines/#reference_2","title":"Reference","text":"
  • GitHub Apps - DCO
"},{"location":"contributing/pull-request-guidelines/review-guidelines/","title":"Review guidelines","text":""},{"location":"contributing/pull-request-guidelines/review-guidelines/#review-guidelines","title":"Review guidelines","text":"

Warning

Under Construction

Refer to the following links for now:

  • https://google.github.io/eng-practices/review/
  • https://docs.gitlab.com/ee/development/code_review.html
  • https://www.swarmia.com/blog/a-complete-guide-to-code-reviews/
  • https://rewind.com/blog/best-practices-for-reviewing-pull-requests-in-github/
"},{"location":"contributing/pull-request-guidelines/review-tips/","title":"Review tips","text":""},{"location":"contributing/pull-request-guidelines/review-tips/#review-tips","title":"Review tips","text":""},{"location":"contributing/pull-request-guidelines/review-tips/#toggle-annotations-or-review-comments-in-the-diff-view","title":"Toggle annotations or review comments in the diff view","text":"

There might be some annotations or review comments in the diff view during your review.

To toggle annotations, press the A key.

Before:

After:

To toggle review comments, press the I key.

For other keyboard shortcuts, refer to GitHub Docs.

"},{"location":"contributing/pull-request-guidelines/review-tips/#view-code-in-the-web-based-visual-studio-code","title":"View code in the web-based Visual Studio Code","text":"

You can open Visual Studio Code from your browser to view code in a rich UI. To use it, press the . key on any repository or pull request.

For more detailed usage, refer to github/dev.

"},{"location":"contributing/pull-request-guidelines/review-tips/#check-out-the-branch-of-a-pull-request-quickly","title":"Check out the branch of a pull request quickly","text":"

If you want to check out the branch of a pull request, it's generally troublesome with the fork-and-pull model.

# Copy the user name and the fork URL.\ngit remote add {user-name} {fork-url}\ngit checkout {user-name}/{branch-name}\ngit remote rm {user-name} # To clean up\n

Instead, you can use GitHub CLI to simplify the steps, just run gh pr checkout {pr-number}.

You can copy the command from the top right of the pull request page.

"},{"location":"contributing/testing-guidelines/","title":"Testing guidelines","text":""},{"location":"contributing/testing-guidelines/#testing-guidelines","title":"Testing guidelines","text":""},{"location":"contributing/testing-guidelines/#unit-testing","title":"Unit testing","text":"

Unit testing is a software testing method that tests individual units of source code to determine whether they satisfy the specification.

For details, see the Unit testing guidelines.

"},{"location":"contributing/testing-guidelines/#integration-testing","title":"Integration testing","text":"

Integration testing combines and tests the individual software modules as a group, and is done after unit testing.

While performing integration testing, the following subtypes of tests are written:

  1. Fault injection testing
  2. Back-to-back comparison between a model and code
  3. Requirements-based testing
  4. Anomaly detection during integration testing
  5. Random input testing

For details, see the Integration testing guidelines.

"},{"location":"contributing/testing-guidelines/integration-testing/","title":"Integration testing","text":""},{"location":"contributing/testing-guidelines/integration-testing/#integration-testing","title":"Integration testing","text":"

An integration test is defined as the phase in software testing where individual software modules are combined and tested as a group. Integration tests occur after unit tests, and before validation tests.

The input to an integration test is a set of independent modules that have been unit tested. The set of modules is tested against the defined integration test plan, and the output is a set of properly integrated software modules that is ready for system testing.

"},{"location":"contributing/testing-guidelines/integration-testing/#value-of-integration-testing","title":"Value of integration testing","text":"

Integration tests determine if independently developed software modules work correctly when the modules are connected to each other. In ROS 2, the software modules are called nodes. Testing a single node is a special type of integration test that is commonly referred to as component testing.

Integration tests help to find the following types of errors:

  • Incompatible interactions between nodes, such as non-matching topics, different message types, or incompatible QoS settings.
  • Edge cases that were not touched by unit testing, such as a critical timing issue, network communication delays, disk I/O failures, and other such problems that can occur in production environments.
  • Issues that can occur while the system is under high CPU/memory load, such as malloc failures. This can be tested using tools like stress and udpreplay to test the performance of nodes with real data.

With ROS 2, it is possible to program complex autonomous-driving applications with a large number of nodes. Therefore, a lot of effort has been made to provide an integration-test framework that helps developers test the interaction of ROS 2 nodes.

"},{"location":"contributing/testing-guidelines/integration-testing/#integration-test-framework","title":"Integration-test framework","text":"

A typical integration-test framework has three parts:

  1. A series of executables with arguments that work together and generate outputs.
  2. A series of expected outputs that should match the output of the executables.
  3. A launcher that starts the tests, compares the outputs to the expected outputs, and determines if the test passes.

In Autoware, we use the launch_testing framework.

"},{"location":"contributing/testing-guidelines/integration-testing/#smoke-tests","title":"Smoke tests","text":"

Autoware has a dedicated API for smoke testing. To use this framework, in package.xml add:

<test_depend>autoware_testing</test_depend>\n

And in CMakeLists.txt add:

if(BUILD_TESTING)\nfind_package(autoware_testing REQUIRED)\nadd_smoke_test(${PROJECT_NAME} ${NODE_NAME})\nendif()\n

Doing so adds smoke tests that ensure that a node can be:

  1. Launched with a default parameter file.
  2. Terminated with a standard SIGTERM signal.

For the full API documentation, refer to the package design page.

Note

This API is not suitable for all smoke test cases. It cannot be used when a specific file location (eg: for a map) is required to be passed to the node, or if some preparation needs to be conducted before node launch. In such cases use the manual solution from the component test section below.

"},{"location":"contributing/testing-guidelines/integration-testing/#integration-test-with-a-single-node-component-test","title":"Integration test with a single node: component test","text":"

The simplest scenario is a single node. In this case, the integration test is commonly referred to as a component test.

To add a component test to an existing node, you can follow the example of the lanelet2_map_loader in the map_loader package (added in this PR).

In package.xml, add:

<test_depend>ros_testing</test_depend>\n

In CMakeLists.txt, add or modify the BUILD_TESTING section:

if(BUILD_TESTING)\nadd_ros_test(\ntest/lanelet2_map_loader_launch.test.py\nTIMEOUT \"30\"\n)\ninstall(DIRECTORY\ntest/data/\nDESTINATION share/${PROJECT_NAME}/test/data/\n)\nendif()\n

In addition to the command add_ros_test, we also install any data that is required by the test using the install command.

Note

  • The TIMEOUT argument is given in seconds; see the add_ros_test.cmake file for details.
  • The add_ros_test command will run the test in a unique ROS_DOMAIN_ID which avoids interference between tests running in parallel.

To create a test, either read the launch_testing quick-start example, or follow the steps below.

Taking test/lanelet2_map_loader_launch.test.py as an example, first dependencies are imported:

import os\nimport unittest\n\nfrom ament_index_python import get_package_share_directory\nimport launch\nfrom launch import LaunchDescription\nfrom launch_ros.actions import Node\nimport launch_testing\nimport pytest\n

Then a launch description is created to launch the node under test. Note that the test_map.osm file path is found and passed to the node, something that cannot be done with the smoke testing API:

@pytest.mark.launch_test\ndef generate_test_description():\n\n    lanelet2_map_path = os.path.join(\n        get_package_share_directory(\"map_loader\"), \"test/data/test_map.osm\"\n    )\n\n    lanelet2_map_loader = Node(\n        package=\"map_loader\",\n        executable=\"lanelet2_map_loader\",\n        parameters=[{\"lanelet2_map_path\": lanelet2_map_path}],\n    )\n\n    context = {}\n\n    return (\n        LaunchDescription(\n            [\n                lanelet2_map_loader,\n                # Start test after 1s - gives time for the map_loader to finish initialization\n                launch.actions.TimerAction(\n                    period=1.0, actions=[launch_testing.actions.ReadyToTest()]\n                ),\n            ]\n        ),\n        context,\n    )\n

Note

  • Since the node need time to process the input lanelet2 map, we use a TimerAction to delay the start of the test by 1s.
  • In the example above, the context is empty but it can be used to pass objects to the test cases.
  • You can find an example of using the context in the ROS 2 context_launch_test.py test example.

Finally, a test is executed after the node executable has been shut down (post_shutdown_test). Here we ensure that the node was launched without error and exited cleanly.

@launch_testing.post_shutdown_test()\nclass TestProcessOutput(unittest.TestCase):\n    def test_exit_code(self, proc_info):\n        # Check that process exits with code 0: no error\n        launch_testing.asserts.assertExitCodes(proc_info)\n
"},{"location":"contributing/testing-guidelines/integration-testing/#running-the-test","title":"Running the test","text":"

Continuing the example from above, first build your package:

colcon build --packages-up-to map_loader\nsource install/setup.bash\n

Then either execute the component test manually:

ros2 test src/universe/autoware.universe/map/map_loader/test/lanelet2_map_loader_launch.test.py\n

Or as part of testing the entire package:

colcon test --packages-select map_loader\n

Verify that the test is executed; e.g.

$ colcon test-result --all --verbose\n...\nbuild/map_loader/test_results/map_loader/test_lanelet2_map_loader_launch.test.py.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\n
"},{"location":"contributing/testing-guidelines/integration-testing/#next-steps","title":"Next steps","text":"

The simple test described in Integration test with a single node: component test can be extended in numerous directions, such as testing a node's output.

"},{"location":"contributing/testing-guidelines/integration-testing/#testing-the-output-of-a-node","title":"Testing the output of a node","text":"

To test while the node is running, create an active test by adding a subclass of Python's unittest.TestCase to *launch.test.py. Some boilerplate code is required to access output by creating a node and a subscription to a particular topic, e.g.

import unittest\n\nclass TestRunningDataPublisher(unittest.TestCase):\n\n    @classmethod\n    def setUpClass(cls):\n        cls.context = Context()\n        rclpy.init(context=cls.context)\n        cls.node = rclpy.create_node(\"test_node\", context=cls.context)\n\n    @classmethod\n    def tearDownClass(cls):\n        rclpy.shutdown(context=cls.context)\n\n    def setUp(self):\n        self.msgs = []\n        sub = self.node.create_subscription(\n            msg_type=my_msg_type,\n            topic=\"/info_test\",\n            callback=self._msg_received\n        )\n        self.addCleanup(self.node.destroy_subscription, sub)\n\n    def _msg_received(self, msg):\n        # Callback for ROS 2 subscriber used in the test\n        self.msgs.append(msg)\n\n    def get_message(self):\n        startlen = len(self.msgs)\n\n        executor = rclpy.executors.SingleThreadedExecutor(context=self.context)\n        executor.add_node(self.node)\n\n        try:\n            # Try up to 60 s to receive messages\n            end_time = time.time() + 60.0\n            while time.time() < end_time:\n                executor.spin_once(timeout_sec=0.1)\n                if startlen != len(self.msgs):\n                    break\n\n            self.assertNotEqual(startlen, len(self.msgs))\n            return self.msgs[-1]\n        finally:\n            executor.remove_node(self.node)\n\n    def test_message_content():\n        msg = self.get_message()\n        self.assertEqual(msg, \"Hello, world\")\n
"},{"location":"contributing/testing-guidelines/integration-testing/#references","title":"References","text":"
  • colcon is used to build and run tests.
  • launch testing launches nodes and runs tests.
  • Testing guidelines describes the different types of tests performed in Autoware and links to the corresponding guidelines.
"},{"location":"contributing/testing-guidelines/unit-testing/","title":"Unit testing","text":""},{"location":"contributing/testing-guidelines/unit-testing/#unit-testing","title":"Unit testing","text":"

Unit testing is the first phase of testing and is used to validate units of source code such as classes and functions. Typically, a unit of code is tested by validating its output for various inputs. Unit testing helps ensure that the code behaves as intended and prevents accidental changes of behavior.

Autoware uses the ament_cmake framework to build and run tests. The same framework is also used to analyze the test results.

ament_cmake provides several convenience functions to make it easy to register tests in a CMake-based package and to ensure that JUnit-compatible result files are generated. It currently supports a few different testing frameworks like pytest, gtest, and gmock.

In order to prevent tests running in parallel from interfering with each other when publishing and subscribing to ROS topics, it is recommended to use commands from ament_cmake_ros to run tests in isolation.

See below for an example of using ament_add_ros_isolated_gtest with colcon test. All other tests follow a similar pattern.

"},{"location":"contributing/testing-guidelines/unit-testing/#create-a-unit-test-with-gtest","title":"Create a unit test with gtest","text":"

In my_cool_pkg/test, create the gtest code file test_my_cool_pkg.cpp:

#include \"gtest/gtest.h\"\n#include \"my_cool_pkg/my_cool_pkg.hpp\"\nTEST(TestMyCoolPkg, TestHello) {\nEXPECT_EQ(my_cool_pkg::print_hello(), 0);\n}\n

In package.xml, add the following line:

<test_depend>ament_cmake_ros</test_depend>\n

Next add an entry under BUILD_TESTING in the CMakeLists.txt to compile the test source files:

if(BUILD_TESTING)\n\nament_add_ros_isolated_gtest(test_my_cool_pkg test/test_my_cool_pkg.cpp)\ntarget_link_libraries(test_my_cool_pkg ${PROJECT_NAME})\n...\nendif()\n

This automatically links the test with the default main function provided by gtest. The code under test is usually in a different CMake target (${PROJECT_NAME} in the example) and its shared object for linking needs to be added.

To register a new gtest item, wrap the test code with the macro TEST (). TEST () is a predefined macro that helps generate the final test code, and also registers a gtest item to be available for execution. The test case name should be in CamelCase, since gtest inserts an underscore between the fixture name and the class case name when creating the test executable.

gtest/gtest.h also contains predefined macros of gtest like ASSERT_TRUE(condition), ASSERT_FALSE(condition), ASSERT_EQ(val1,val2), ASSERT_STREQ(str1,str2), EXPECT_EQ(), etc. ASSERT_* will abort the test if the condition is not satisfied, while EXPECT_* will mark the test as failed but continue on to the next test condition.

Info

More information about gtest and its features can be found in the gtest repo.

In the demo CMakeLists.txt, ament_add_ros_isolated_gtest is a predefined macro in ament_cmake_ros that helps simplify adding gtest code. Details can be viewed in ament_add_gtest.cmake.

"},{"location":"contributing/testing-guidelines/unit-testing/#build-test","title":"Build test","text":"

By default, all necessary test files (ELF, CTestTestfile.cmake, etc.) are compiled by colcon:

cd ~/workspace/\ncolcon build --packages-select my_cool_pkg\n

Test files are generated under ~/workspace/build/my_cool_pkg.

"},{"location":"contributing/testing-guidelines/unit-testing/#run-test","title":"Run test","text":"

To run all tests for a specific package, call:

$ colcon test --packages-select my_cool_pkg\n\nStarting >>> my_cool_pkg\nFinished <<< my_cool_pkg [7.80s]\n\nSummary: 1 package finished [9.27s]\n

The test command output contains a brief report of all the test results.

To get job-wise information of all executed tests, call:

$ colcon test-result --all\n\nbuild/my_cool_pkg/test_results/my_cool_pkg/copyright.xunit.xml: 8 tests, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/cppcheck.xunit.xml: 6 tests, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/lint_cmake.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/my_cool_pkg_exe_integration_test.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml: 1 test, 0 errors, 0 failures, 0 skipped\nbuild/my_cool_pkg/test_results/my_cool_pkg/xmllint.xunit.xml: 1 test, 0 errors, 0 failures, 0 skipped\n\nSummary: 18 tests, 0 errors, 0 failures, 0 skipped\n

Look in the ~/workspace/log/test_<date>/<package_name> directory for all the raw test commands, std_out, and std_err. There is also the ~/workspace/log/latest_*/ directory containing symbolic links to the most recent package-level build and test output.

To print the tests' details while the tests are being run, use the --event-handlers console_cohesion+ option to print the details directly to the console:

$ colcon test --event-handlers console_cohesion+ --packages-select my_cool_pkg\n\n...\ntest 1\n    Start 1: test_my_cool_pkg\n\n1: Test command: /usr/bin/python3 \"-u\" \"~/workspace/install/share/ament_cmake_test/cmake/run_test.py\" \"~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml\" \"--package-name\" \"my_cool_pkg\" \"--output-file\" \"~/workspace/build/my_cool_pkg/ament_cmake_gtest/test_my_cool_pkg.txt\" \"--command\" \"~/workspace/build/my_cool_pkg/test_my_cool_pkg\" \"--gtest_output=xml:~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml\"\n1: Test timeout computed to be: 60\n1: -- run_test.py: invoking following command in '~/workspace/src/my_cool_pkg':\n1:  - ~/workspace/build/my_cool_pkg/test_my_cool_pkg --gtest_output=xml:~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml\n1: [==========] Running 1 test from 1 test case.\n1: [----------] Global test environment set-up.\n1: [----------] 1 test from test_my_cool_pkg\n1: [ RUN      ] test_my_cool_pkg.test_hello\n1: Hello World\n1: [       OK ] test_my_cool_pkg.test_hello (0 ms)\n1: [----------] 1 test from test_my_cool_pkg (0 ms total)\n1:\n1: [----------] Global test environment tear-down\n1: [==========] 1 test from 1 test case ran. (0 ms total)\n1: [  PASSED  ] 1 test.\n1: -- run_test.py: return code 0\n1: -- run_test.py: inject classname prefix into gtest result file '~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml'\n1: -- run_test.py: verify result file '~/workspace/build/my_cool_pkg/test_results/my_cool_pkg/test_my_cool_pkg.gtest.xml'\n1/5 Test #1: test_my_cool_pkg ...................   Passed    0.09 sec\n\n...\n\n100% tests passed, 0 tests failed out of 5\n\nLabel Time Summary:\ncopyright     =   0.49 sec*proc (1 test)\ncppcheck      =   0.20 sec*proc (1 test)\ngtest         =   0.05 sec*proc (1 test)\nlint_cmake    =   0.18 sec*proc (1 test)\nlinter        =   1.34 sec*proc (4 tests)\nxmllint       =   0.47 sec*proc (1 test)\n\nTotal Test time (real) =   7.91 sec\n...\n
"},{"location":"contributing/testing-guidelines/unit-testing/#code-coverage","title":"Code coverage","text":"

Loosely described, a code coverage metric is a measure of how much of the program code has been exercised (covered) during testing.

In the Autoware repositories, Codecov is used to automatically calculate coverage of any open pull request.

More details about the code coverage metrics can be found in the Codecov documentation.

"},{"location":"datasets/","title":"Datasets","text":""},{"location":"datasets/#datasets","title":"Datasets","text":"

Autoware partners provide datasets for testing and development. These datasets are available for download here.

"},{"location":"datasets/#bus-odd-operational-design-domain-datasets","title":"Bus-ODD (Operational Design Domain) datasets","text":""},{"location":"datasets/#leo-drive-isuzu-sensor-data","title":"Leo Drive - ISUZU sensor data","text":"

This dataset contains data from the Isuzu bus used in the Bus ODD project.

The data contains data from following sensors:

  • 1 x VLP16
  • 2 x VLP32C
  • 1 x Applanix POS LV 120 GNSS/INS
  • 3 x Lucid Vision Triton 5.4MP cameras (left, right, front)
  • Vehicle status report

It also contains /tf topic for static transformations between sensors.

"},{"location":"datasets/#required-message-types","title":"Required message types","text":"

The GNSS data is available in sensor_msgs/msg/NavSatFix message type.

But also the Applanix raw messages are also included in applanix_msgs/msg/NavigationPerformanceGsof50 and applanix_msgs/msg/NavigationSolutionGsof49 message types. In order to be able to play back these messages, you need to build and source the applanix_msgs package.

# Create a workspace and clone the repository\nmkdir -p ~/applanix_ws/src && cd \"$_\"\ngit clone https://github.com/autowarefoundation/applanix.git\ncd ..\n\n# Build the workspace\ncolcon build --symlink-install --packages-select applanix_msgs\n\n# Source the workspace\nsource ~/applanix_ws/install/setup.bash\n\n# Now you can play back the messages\n

Also make sure to source Autoware Universe workspace too.

"},{"location":"datasets/#download-instructions","title":"Download instructions","text":"
# Install awscli\n$ sudo apt update && sudo apt install awscli -y\n\n# This will download the entire dataset to the current directory.\n# (About 10.9GB of data)\n$ aws s3 sync s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/ ./2022-08-22_leo_drive_isuzu_bags  --no-sign-request\n\n# Optionally,\n# If you instead want to download a single bag file, you can get a list of the available files with following:\n$ aws s3 ls s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/ --no-sign-request\n   PRE all-sensors-bag1_compressed/\n   PRE all-sensors-bag2_compressed/\n   PRE all-sensors-bag3_compressed/\n   PRE all-sensors-bag4_compressed/\n   PRE all-sensors-bag5_compressed/\n   PRE all-sensors-bag6_compressed/\n   PRE driving_20_kmh_2022_06_10-16_01_55_compressed/\n   PRE driving_30_kmh_2022_06_10-15_47_42_compressed/\n\n# Then you can download a single bag file with the following:\naws s3 sync s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/all-sensors-bag1_compressed/ ./all-sensors-bag1_compressed  --no-sign-request\n
"},{"location":"datasets/#autocoreai-lidar-ros-2-bag-file-and-pcap","title":"AutoCore.ai - lidar ROS 2 bag file and pcap","text":"

This dataset contains pcap files and ros2 bag files from Ouster OS1-64 Lidar. The pcap file and ros2 bag file is recorded in the same time with slight difference in duration.

Click here to download (~553MB)

Reference Issue

"},{"location":"design/","title":"Autoware's Design","text":""},{"location":"design/#autowares-design","title":"Autoware's Design","text":""},{"location":"design/#architecture","title":"Architecture","text":"

Core and Universe.

Autoware provides the runtimes and technology components by open-source software. The runtimes are based on the Robot Operating System (ROS). The technology components are provided by contributors, which include, but are not limited to:

  • Sensing
    • Camera Component
    • LiDAR Component
    • RADAR Component
    • GNSS Component
  • Computing
    • Localization Component
    • Perception Component
    • Planning Component
    • Control Component
    • Logging Component
    • System Monitoring Component
  • Actuation
    • DBW Component
  • Tools
    • Simulator Component
    • Mapping Component
    • Remote Component
    • ML Component
    • Annotation Component
    • Calibration Component
"},{"location":"design/#concern-assumption-and-limitation","title":"Concern, Assumption, and Limitation","text":"

The downside of the microautonomy architecture is that the computational performance of end applications is sacrificed due to its data path overhead attributed to functional modularity. In other words, the trade-off characteristic of the microautonomy architecture exists between computational performance and functional modularity. This trade-off problem can be solved technically by introducing real-time capability. This is because autonomous driving systems are not really designed to be real-fast, that is, low-latency computing is nice-to-have but not must-have. The must-have feature for autonomous driving systems is that the latency of computing is predictable, that is, the systems are real-time. As a whole, we can compromise computational performance to an extent that is predictable enough to meet the given timing constraints of autonomous driving systems, often referred to as deadlines of computation.

"},{"location":"design/#design","title":"Design","text":"

Warning

Under Construction

"},{"location":"design/#autoware-concepts","title":"Autoware concepts","text":"

The Autoware concepts page describes the design philosophy of Autoware. Readers (service providers and all Autoware users) will learn the basic concepts underlying Autoware development, such as microautonomy and the Core/Universe architecture.

"},{"location":"design/#autoware-architecture","title":"Autoware architecture","text":"

The Autoware architecture page describes an overview of each module that makes up Autoware. Readers (all Autoware users) will gain a high-level picture of how each module that composes Autoware works.

"},{"location":"design/#autoware-interfaces","title":"Autoware interfaces","text":"

The Autoware interfaces page describes in detail the interface of each module that makes up Autoware. Readers (intermediate developers) will learn how to add new functionality to Autoware and how to integrate their own modules with Autoware.

"},{"location":"design/#configuration-management","title":"Configuration management","text":""},{"location":"design/#conclusion","title":"Conclusion","text":""},{"location":"design/autoware-architecture/","title":"Architecture overview","text":""},{"location":"design/autoware-architecture/#architecture-overview","title":"Architecture overview","text":"

This page describes the architecture of Autoware.

"},{"location":"design/autoware-architecture/#introduction","title":"Introduction","text":"

The current Autoware is defined to be a layered architecture that clarifies each module's role and simplifies the interface between them. By doing so:

  • Autoware's internal processing becomes more transparent.
  • Collaborative development is made easier because of the reduced interdependency between modules.
  • Users can easily replace an existing module (e.g. localization) with their own software component by simply wrapping their software to fit in with Autoware's interface.

Note that the initial focus of this architecture design was solely on driving capability, and so the following features were left as future work:

  • Fail safe
  • Human Machine Interface
  • Real-time processing
  • Redundant system
  • State monitoring system
"},{"location":"design/autoware-architecture/#high-level-architecture-design","title":"High-level architecture design","text":"

Autoware's architecture consists of the following six stacks. Each linked page contains a more detailed set of requirements and use cases specific to that stack:

  • Sensing design
  • Map design
  • Localization design
  • Perception design
  • Planning design
  • Control design
  • Vehicle Interface design
"},{"location":"design/autoware-architecture/#node-diagram","title":"Node diagram","text":"

A diagram showing Autoware's nodes in the default configuration can be found on the Node diagram page. Detailed documents for each node are available in the Autoware Universe docs.

Note that Autoware configurations are scalable / selectable and will vary depending on the environment and required use cases.

"},{"location":"design/autoware-architecture/#references","title":"References","text":"
  • The architecture presentation given to the AWF Technical Steering Committee, March 2020
"},{"location":"design/autoware-architecture/control/","title":"Control component design","text":""},{"location":"design/autoware-architecture/control/#control-component-design","title":"Control component design","text":""},{"location":"design/autoware-architecture/control/#abstract","title":"Abstract","text":"

This document presents the design concept of the Control Component. The content is as follows:

  • Autoware Control Design
    • Outlining the policy for Autoware's control, which deals with only general information for autonomous driving systems and provides generic control commands to the vehicle.
  • Vehicle Adaptation Design
    • Describing the policy for vehicle adaptation, which utilizes adapter mechanisms to standardize the characteristics of the vehicle's drive system and integrate it with Autoware.
  • Control Feature Design
    • Demonstrating the features provided by Autoware's control.
    • Presenting the approach towards the functions installed in the vehicle such as ABS.
"},{"location":"design/autoware-architecture/control/#autoware-control-design","title":"Autoware Control Design","text":"

The Control Component generates the control signal to which the Vehicle Component subscribes. The generated control signals are computed based on the reference trajectories from the Planning Component.

The Control Component consists of two modules. The trajectory_follower module generates a vehicle control command to follow the reference trajectory received from the planning module. The command includes, for example, the desired steering angle and target speed. The vehicle_command_gate is responsible for filtering the control command to prevent abnormal values and then sending it to the vehicle. This gate also allows switching between multiple sources such as the MRM (minimal risk maneuver) module or some remote control module, in addition to the trajectory follower.

The Autoware control system is designed as a platform for automated driving systems that can be compatible with a diverse range of vehicles.

The control process in Autoware uses general information (such as target acceleration and deceleration) and no vehicle-specific information (such as brake pressure) is used. Hence it can be adjusted independently of the vehicle's drive interface enabling easy integration or performance tuning.

Furthermore, significant differences that affect vehicle motion constraints, such as two-wheel steering or four-wheel steering, are addressed by switching the control vehicle model, achieving control specialized for each characteristic.

Autoware's control module outputs the necessary information to control the vehicle as a substitute for a human driver. For example, the control command from the control module looks like the following:

- Target steering angle\n- Target steering torque\n- Target speed\n- Target acceleration\n

Note that vehicle-specific values such as pedal positions and low-level information such as individual wheel rotation speeds are excluded from the command.

"},{"location":"design/autoware-architecture/control/#vehicle-adaptation-design","title":"Vehicle Adaptation Design","text":""},{"location":"design/autoware-architecture/control/#vehicle-interface-adapter","title":"Vehicle interface adapter","text":"

Autoware is designed to be an autonomous driving platform able to accommodate vehicles with various drivetrain types.

This is an explanation of how Autoware handles the standardization of systems with different vehicle drivetrains. The interfaces for vehicle drivetrains are diverse, including steering angle, steering angular velocity, steering torque, speed, accel/brake pedals, and brake pressure. To accommodate these differences, Autoware adds an adapter module between the control component and the vehicle interface. This module performs the conversion between the proprietary message types used by the vehicle (such as brake pressure) and the generic types used by Autoware (such as desired acceleration). By providing this conversion information, the differences in vehicle drivetrain can be accommodated.

If the information is not known in advance, an automatic calibration tool can be used. Calibration will occur within limited degrees of freedom, generating the information necessary for the drivetrain conversion automatically.

This configuration is summarized in the following diagram.

"},{"location":"design/autoware-architecture/control/#examples-of-several-vehicle-interfaces","title":"Examples of several vehicle interfaces","text":"

This is an example of the several drivetrain types in the vehicle interface.

Vehicle Lateral interface Longitudinal interface Note Lexus Steering angle Accel/brake pedal position Acceleration lookup table conversion for longitudinal JPN TAXI Steering angle Accel/brake pedal position Acceleration lookup table conversion for longitudinal GSM8 Steering EPS voltage Acceleration motor voltage, Deceleration brake hydraulic pressure lookup table and PID conversion for lateral and longitudinal YMC Golfcart Steering angle Velocity Logiees yaw rate Velocity F1 TENTH Steering angle Motor RPM interface code"},{"location":"design/autoware-architecture/control/#control-feature-design","title":"Control Feature Design","text":"

The following lists the features provided by Autoware's Control/Vehicle component, as well as the conditions and assumptions required to utilize them effectively.

The proper operation of the ODD is limited by factors such as whether the functions are enabled, delay time, calibration accuracy and degradation rate, and sensor accuracy.

Feature Description\u3000 Requirements/Assumptions Note \u3000Limitation for now Lateral Control Control the drivetrain system related to lateral vehicle motion Trying to increase the number of vehicle types that can be supported in the future. Only front-steering type is supported. Longitudinal Control Control the drivetrain system related to longitudinal vehicle motion Slope Compensation Supports precise vehicle motion control on slopes Gradient information can be obtained from maps or sensors attached to the chassis If gradient information is not available, the gradient is estimated from the vehicle's pitch angle. Delay Compensation Controls the drivetrain system appropriately in the presence of time delays The drivetrain delay information is provided in advance If there is no delay information, the drivetrain delay is estimated automatically (automatic calibration). However, the effect of delay cannot be completely eliminated, especially in scenarios with sudden changes in speed. Only fixed delay times can be set for longitudinal and lateral drivetrain systems separately. It does not accommodate different delay times for the accelerator and brake. Drivetrain IF Conversion (Lateral Control) Converts the drivetrain-specific information of the vehicle into the drivetrain information used by Autoware (e.g., target steering angular velocity \u2192 steering torque) The conversion information is provided in advance If there is no conversion information, the conversion map is estimated automatically (automatic calibration). The degree of freedom for conversion is limited (2D lookup table + PID FB). Drivetrain IF Conversion (Longitudinal Control) Converts the drivetrain-specific information of the vehicle into the drivetrain information used by Autoware (e.g., target acceleration \u2192 accelerator/brake pedal value) The conversion information is provided in advance If there is no conversion information, the conversion map is estimated automatically (automatic calibration). The degree of freedom for conversion is limited (2D lookup table + PID FB). Automatic Calibration Automatically estimates and applies values such as drivetrain IF conversion map and delay time. The drivetrain status can be obtained (must) Anomaly Detection Notifies when there is a discrepancy in the calibration or unexpected drivetrain behavior The drivetrain status can be obtained (must) Steering Zero Point Correction Corrects the midpoint of the steering to achieve appropriate steering control The drivetrain status can be obtained (must) Steering Deadzone Correction Corrects the deadzone of the steering to achieve appropriate steering control The steering deadzone parameter is provided in advance If the parameter is unknown, the deadzone parameter is estimated from driving information Not available now Steering Deadzone Estimation Dynamically estimates the steering deadzone from driving data Not available now Weight Compensation Performs appropriate vehicle control according to weight Weight information can be obtained from sensors If there is no weight sensor, estimate the weight from driving information. Currently not available Weight Estimation Dynamically estimates weight from driving data Currently not available

The list above does not cover wheel control systems such as ABS commonly used in vehicles. Regarding these features, the following considerations are taken into account.

"},{"location":"design/autoware-architecture/control/#integration-with-vehicle-side-functions","title":"Integration with vehicle-side functions","text":"

ABS (Anti-lock Brake System) and ESC (Electric Stability Control) are two functions that may be pre-installed on a vehicle, directly impacting its controllability. The control modules of Autoware assume that both ABS and ESC are installed on the vehicle and their absence may cause unreliable controls depending on the target ODD. For example, with low-velocity driving in a controlled environment, these functions are not necessary.

Also, note that this statement does not negate the development of ABS functionality in autonomous driving systems.

"},{"location":"design/autoware-architecture/control/#autoware-capabilities-and-vehicle-requirements","title":"Autoware Capabilities and Vehicle Requirements","text":"

As an alternative to human driving, autonomous driving systems essentially aim to handle tasks that humans can perform. This includes not only controlling the steering wheel, accel, and brake, but also automatically detecting issues such as poor brake response or a misaligned steering angle. However, this is a trade-off, as better vehicle performance will lead to superior system behavior, ultimately affecting the design of ODD.

On the other hand, for tasks that are not typically anticipated or cannot be handled by a human driver, processing in the vehicle ECU is expected. Examples of such scenarios include cases where the brake response is clearly delayed or when the vehicle rotates due to a single-side tire slipping. These tasks are typically handled by ABS or ESC.

"},{"location":"design/autoware-architecture/localization/","title":"Index","text":"

LOCALIZATION COMPONENT DESIGN DOC

"},{"location":"design/autoware-architecture/localization/#abstract","title":"Abstract","text":""},{"location":"design/autoware-architecture/localization/#1-requirements","title":"1. Requirements","text":"

Localization aims to estimate vehicle pose, velocity, and acceleration.

Goals:

  • Propose a system that can estimate vehicle pose, velocity, and acceleration for as long as possible.
  • Propose a system that can diagnose the stability of estimation and send a warning message to the error-monitoring system if the estimation result is unreliable.
  • Design a vehicle localization function that can work with various sensor configurations.

Non-goals:

  • This design document does not aim to develop a localization system that
    • is infallible in all environments
    • works outside of the pre-defined ODD (Operational Design Domain)
    • has better performance than is required for autonomous driving
"},{"location":"design/autoware-architecture/localization/#2-sensor-configuration-examples","title":"2. Sensor Configuration Examples","text":"

This section shows example sensor configurations and their expected performances. Each sensor has its own advantages and disadvantages, but overall performance can be improved by fusing multiple sensors.

"},{"location":"design/autoware-architecture/localization/#3d-lidar-pointcloud-map","title":"3D-LiDAR + PointCloud Map","text":""},{"location":"design/autoware-architecture/localization/#expected-situation","title":"Expected situation","text":"
  • The vehicle is located in a structure-rich environment, such as an urban area
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable","title":"Situations that can make the system unstable","text":"
  • The vehicle is placed in a structure-less environment, such as a rural landscape, highway, or tunnel
  • Environmental changes have occurred since the map was created, such as snow cover or the construction/destruction of buildings.
  • Surrounding objects are occluded
  • The car is surrounded by objects undetectable by LiDAR, e.g., glass windows, reflections, or absorption (dark objects)
  • The environment contains laser beams at the same frequency as the car's LiDAR sensor(s)
"},{"location":"design/autoware-architecture/localization/#functionality","title":"Functionality","text":"
  • The system can estimate the vehicle location on the point cloud map with the error of ~10cm.
  • The system is operable at night.
"},{"location":"design/autoware-architecture/localization/#3d-lidar-or-camera-vector-map","title":"3D-LiDAR or Camera + Vector Map","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_1","title":"Expected situation","text":"
  • Road with clear white lines and loose curvatures, such as a highway or an ordinary local road.
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_1","title":"Situations that can make the system unstable","text":"
  • White lines are scratchy or covered by rain or snow
  • Tight curvature such as intersections
  • Large reflection change of the road surface caused by rain or paint
"},{"location":"design/autoware-architecture/localization/#functionalities","title":"Functionalities","text":"
  • Correct vehicle positions along the lateral direction.
  • Pose correction along the longitudinal can be inaccurate, but can be resolved by fusing with GNSS.
"},{"location":"design/autoware-architecture/localization/#gnss","title":"GNSS","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_2","title":"Expected situation","text":"
  • The vehicle is placed in an open environment with few to no surrounding objects, such as a rural landscape.
"},{"location":"design/autoware-architecture/localization/#situation-that-can-make-the-system-unstable","title":"Situation that can make the system unstable","text":"
  • GNSS signals are blocked by surrounding objects, e.g., tunnels or buildings.
"},{"location":"design/autoware-architecture/localization/#functionality_1","title":"Functionality","text":"
  • The system can estimate vehicle position in the world coordinate within an error of ~10m.
  • With a RKT-GNSS (Real Time Kinematic Global Navigation Satellite System) attached, the accuracy can be improved to ~10cm.
  • A system with this configuration can work without environment maps (both point cloud and vector map types).
"},{"location":"design/autoware-architecture/localization/#camera-visual-odometry-visual-slam","title":"Camera (Visual Odometry, Visual SLAM)","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_3","title":"Expected situation","text":"
  • The vehicle is placed in an environment with rich visual features, such as an urban area.
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_2","title":"Situations that can make the system unstable","text":"
  • The vehicle is placed in a texture-less environment.
  • The vehicle is surrounded by other objects.
  • The camera observes significant illumination changes, such as those caused by sunshine, headlights from other vehicles or when approaching the exit of a tunnel.
  • The vehicle is placed in a dark environment.
"},{"location":"design/autoware-architecture/localization/#functionality_2","title":"Functionality","text":"
  • The system can estimate odometry by tracking visual features.
"},{"location":"design/autoware-architecture/localization/#wheel-speed-sensor","title":"Wheel speed sensor","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_4","title":"Expected situation","text":"
  • The vehicle is running on a flat and smooth road.
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_3","title":"Situations that can make the system unstable","text":"
  • The vehicle is running on a slippery or bumpy road, which can cause incorrect observations of wheel speed.
"},{"location":"design/autoware-architecture/localization/#functionality_3","title":"Functionality","text":"
  • The system can acquire the vehicle velocity and estimate distance traveled.
"},{"location":"design/autoware-architecture/localization/#imu","title":"IMU","text":""},{"location":"design/autoware-architecture/localization/#expected-environments","title":"Expected environments","text":"
  • Flat, smooth roads
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_4","title":"Situations that can make the system unstable","text":"
  • IMUs have a bias1 that is dependent on the surrounding temperature, and can cause incorrect sensor observation or odometry drift.
"},{"location":"design/autoware-architecture/localization/#functionality_4","title":"Functionality","text":"
  • The system can observe acceleration and angular velocity.
  • By integrating these observations, the system can estimate the local pose change and realize dead-reckoning
"},{"location":"design/autoware-architecture/localization/#geomagnetic-sensor","title":"Geomagnetic sensor","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_5","title":"Expected situation","text":"
  • The vehicle is placed in an environment with low magnetic noise
"},{"location":"design/autoware-architecture/localization/#situations-that-can-make-the-system-unstable_5","title":"Situations that can make the system unstable","text":"
  • The vehicle is placed in an environment with high magnetic noise, such as one containing buildings or structures with reinforced steel or other materials that generate electromagnetic waves.
"},{"location":"design/autoware-architecture/localization/#functionality_5","title":"Functionality","text":"
  • The system can estimate the vehicle's direction in the world coordinate system.
"},{"location":"design/autoware-architecture/localization/#magnetic-markers","title":"Magnetic markers","text":""},{"location":"design/autoware-architecture/localization/#expected-situation_6","title":"Expected situation","text":"
  • The car is placed in an environment with magnetic markers installed.
"},{"location":"design/autoware-architecture/localization/#situations-where-the-system-becomes-unstable","title":"Situations where the system becomes unstable","text":"
  • The markers are not maintained.
"},{"location":"design/autoware-architecture/localization/#functionality_6","title":"Functionality","text":"
  • Vehicle location can be obtained on the world coordinate by detecting the magnetic markers.
  • The system can work even if the road is covered with snow.
"},{"location":"design/autoware-architecture/localization/#3-requirements","title":"3. Requirements","text":"
  • By implementing different modules, various sensor configurations and algorithms can be used.
  • The localization system can start pose estimation from an ambiguous initial location.
  • The system can produce a reliable initial location estimation.
  • The system can manage the state of the initial location estimation (uninitialized, initializable, or non-initializable) and can report to the error monitor.
"},{"location":"design/autoware-architecture/localization/#4-architecture","title":"4. Architecture","text":""},{"location":"design/autoware-architecture/localization/#abstract_1","title":"Abstract","text":"

Two architectures are defined, \"Required\" and \"Recommended\". However, the \"Required\" architecture only contains the inputs and outputs necessary to accept various localization algorithms. To improve the reusability of each module, the required components are defined in the \"Recommended\" architecture section along with a more detailed explanation.

"},{"location":"design/autoware-architecture/localization/#required-architecture","title":"Required Architecture","text":""},{"location":"design/autoware-architecture/localization/#input","title":"Input","text":"
  • Sensor message
    • e.g., LiDAR, camera, GNSS, IMU, CAN Bus, etc.
    • Data types should be ROS primitives for reusability
  • Map data
    • e.g., point cloud map, lanelet2 map, feature map, etc.
    • The map format should be chosen based on use case and sensor configuration
    • Note that map data is not required for some specific cases (e.g., GNSS-only localization)
  • tf, static_tf
    • map frame
    • base_link frame
"},{"location":"design/autoware-architecture/localization/#output","title":"Output","text":"
  • Pose with covariance stamped
    • Vehicle pose, covariance, and timestamp on the map coordinate
    • 50Hz~ frequency (depending on the requirements of the Planning and Control components)
  • Twist with covariance stamped
    • Vehicle velocity, covariance, and timestamp on the base_link coordinate
    • 50Hz~ frequency
  • Accel with covariance stamped
    • Acceleration, covariance, and timestamp on the base_link coordinate
    • 50Hz~ frequency
  • Diagnostics
    • Diagnostics information that indicates if the localization module works properly
  • tf
    • tf of map to base_link
"},{"location":"design/autoware-architecture/localization/#recommended-architecture","title":"Recommended Architecture","text":""},{"location":"design/autoware-architecture/localization/#pose-estimator","title":"Pose Estimator","text":"
  • Estimates the vehicle pose on the map coordinate by matching external sensor observation to the map
  • Provides the obtained pose and its covariance to PoseTwistFusionFilter
"},{"location":"design/autoware-architecture/localization/#twist-accel-estimator","title":"Twist-Accel Estimator","text":"
  • Produces the vehicle velocity, angular velocity, acceleration, angular acceleration, and their covariances
    • It is possible to create a single module for both twist and acceleration or to create two separate modules - the choice of architecture is up to the developer
  • The twist estimator produces velocity and angular velocity from internal sensor observation
  • The accel estimator produces acceleration and angular acceleration from internal sensor observations
"},{"location":"design/autoware-architecture/localization/#kinematics-fusion-filter","title":"Kinematics Fusion Filter","text":"
  • Produces the likeliest pose, velocity, acceleration, and their covariances, computed by fusing two kinds of information:
    • The pose obtained from the pose estimator.
    • The velocity and acceleration obtained from the twist-accel estimator
  • Produces tf of map to base_link according to the pose estimation result
"},{"location":"design/autoware-architecture/localization/#localization-diagnostics","title":"Localization Diagnostics","text":"
  • Monitors and guarantees the stability and reliability of pose estimation by fusing information obtained from multiple localization modules
  • Reports error status to the error monitor
"},{"location":"design/autoware-architecture/localization/#tf-tree","title":"TF tree","text":"frame meaning earth ECEF (Earth Centered Earth Fixed\uff09 map Origin of the map coordinate (ex. MGRS origin) viewer User-defined frame for rviz base_link Reference pose of the ego-vehicle (projection of the rear-axle center onto the ground surface) sensor Reference pose of each sensor

Developers can optionally add other frames such as odom or base_footprint as long as the tf structure above is maintained.

"},{"location":"design/autoware-architecture/localization/#the-localization-modules-ideal-functionality","title":"The localization module's ideal functionality","text":"
  • The localization module should provide pose, velocity, and acceleration for control, planning, and perception.
  • Latency and stagger should be sufficiently small or adjustable such that the estimated values can be used for control within the ODD (Operational Design Domain).
  • The localization module should produce the pose on a fixed coordinate frame.
  • Sensors should be independent of each other so that they can be easily replaced.
  • The localization module should provide a status indicating whether or not the autonomous vehicle can operate with the self-contained function or map information.
  • Tools or manuals should describe how to set proper parameters for the localization module
  • Valid calibration parameters should be provided to align different frame or pose coordinates and sensor timestamps.
"},{"location":"design/autoware-architecture/localization/#kpi","title":"KPI","text":"

To maintain sufficient pose estimation performance for safe operation, the following metrics are considered:

  • Safety
    • The distance traveled within the ODD where pose estimation met the required accuracy, divided by the overall distance traveled within the ODD, as a percentage.
    • The anomaly detection rate for situations where the localization module cannot estimate pose within the ODD
    • The accuracy of detecting when the vehicle goes outside of the ODD, as a percentage.
  • Computational load
  • Latency
"},{"location":"design/autoware-architecture/localization/#5-interface-and-data-structure","title":"5. Interface and Data Structure","text":""},{"location":"design/autoware-architecture/localization/#6-concerns-assumptions-and-limitations","title":"6. Concerns, Assumptions, and Limitations","text":""},{"location":"design/autoware-architecture/localization/#prerequisites-of-sensors-and-inputs","title":"Prerequisites of sensors and inputs","text":""},{"location":"design/autoware-architecture/localization/#sensor-prerequisites","title":"Sensor prerequisites","text":"
  • Input data is not defective.
    • Internal sensor observation such as IMU continuously keeps the proper frequency.
  • Input data has correct and exact time stamps.
    • Estimated poses can be inaccurate or unstable if the timestamps are not exact.
  • Sensors are correctly mounted with exact positioning and accessible from TF.
    • If the sensor positions are inaccurate, estimation results may be incorrect or unstable.
    • A sensor calibration framework is required to properly obtain the sensor positions.
"},{"location":"design/autoware-architecture/localization/#map-prerequisites","title":"Map prerequisites","text":"
  • Sufficient information is contained within the map.
    • Pose estimation might be unstable if there is insufficient information in the map.
    • A testing framework is necessary to check if the map has adequate information for pose estimation.
  • Map does not differ greatly from the actual environment.
    • Pose estimation might be unstable if the actual environment has different objects from the map.
    • Maps need updates according to new objects and seasonal changes.
  • Maps must be aligned to a uniform coordinate, or an alignment framework is in place.
    • If multiple maps with different coordinate systems are used, the misalignment between them can affect the localization performance.
"},{"location":"design/autoware-architecture/localization/#computational-resources","title":"Computational resources","text":"
  • Sufficient computational resources should be provided to maintain accuracy and computation speed.

  1. For more details about bias, refer to the VectorNav IMU specifications page.\u00a0\u21a9

"},{"location":"design/autoware-architecture/map/","title":"Map component design","text":""},{"location":"design/autoware-architecture/map/#map-component-design","title":"Map component design","text":""},{"location":"design/autoware-architecture/map/#1-overview","title":"1. Overview","text":"

Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks such as localization, route planning, traffic light detection, and predicting the trajectories of pedestrians and other vehicles.

This document describes the design of map component of Autoware, including its requirements, architecture design, features, data formats, and interface to distribute map information to the rest of autonomous driving stack.

"},{"location":"design/autoware-architecture/map/#2-requirements","title":"2. Requirements","text":"

Map should provide two types of information to the rest of the stack:

  • Semantic information about roads as a vector map
  • Geometric information about the environment as a point cloud map (optional)

A vector map contains highly accurate information about a road network, lane geometry, and traffic lights. It is required for route planning, traffic light detection, and predicting the trajectories of other vehicles and pedestrians.

A 3D point cloud map is primarily used for LiDAR-based localization and part of perception in Autoware. In order to determine the current position and orientation of the vehicle, a live scan captured from one or more LiDAR units is matched against a pre-generated 3D point cloud map. Therefore, an accurate point cloud map is crucial for good localization results. However, if the vehicle has an alternate localization method with enough accuracy, for example using camera-based localization, point cloud map may not be required to use Autoware.

"},{"location":"design/autoware-architecture/map/#3-architecture","title":"3. Architecture","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/map/#4-features","title":"4. Features","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/map/#5-map-specification","title":"5. Map Specification","text":""},{"location":"design/autoware-architecture/map/#point-cloud-map","title":"Point Cloud Map","text":"

The point cloud map must be supplied as a file with the following requirements:

  • It must be in the PCD (Point Cloud Data) file format, but can be a single PCD file or divided into multiple PCD files.
  • Each point in the map must contain X, Y, and Z coordinates.
  • An intensity or RGB value for each point may be optionally included.
  • It must cover the entire operational area of the vehicle. It is also recommended to include an additional buffer zone according to the detection range of sensors attached to the vehicle.
  • Its resolution should be at least 0.2 m to yield reliable localization results.
  • It can be in either local or global coordinates, but must be in global coordinates (georeferenced) to use GNSS data for localization.

Note

Three global coordinate systems are currently supported by Autoware, including Military Grid Reference System (MGRS), Universal Transverse Mercator (UTM), and Japan Rectangular Coordinate System. However, MGRS is a preferred coordinate system for georeferenced maps. In a map with MGRS coordinate system, the X and Y coordinates of each point represent the point's location within the 100,000-meter square, while the Z coordinate represents the point's elevation.

If it is split into a single file, Autoware assumes the following directory structure by default.

sample-map-rosbag\n\u251c\u2500\u2500 lanelet2_map.osm\n\u251c\u2500\u2500 pointcloud_map.pcd\n

If it is split into multiple files, Autoware assumes the following directory structure by default.

sample-map-rosbag\n\u251c\u2500\u2500 lanelet2_map.osm\n\u251c\u2500\u2500 pointcloud_map\n\u251c\u2500\u2500 pcd_00.pcd\n\u251c\u2500\u2500 pcd_01.pcd\n\u251c\u2500\u2500 pcd_02.pcd\n\u251c\u2500\u2500 ...\n\u2514\u2500\u2500 pointcloud_map_metadata.yaml\n

Note that, if you split the map into multiple files, you must meet the following additional conditions:

  • It must be split by lines parallel to the x-y axis.
  • Additional metadata must be provided as well.

Metadata should look like as follows:

x_resolution: 100.0\ny_resolution: 150.0\nA.pcd: [1200, 2500] # -> 1200 < x < 1300, 2500 < y < 2650\nB.pcd: [1300, 2500] # -> 1300 < x < 1400, 2500 < y < 2650\nC.pcd: [1200, 2650] # -> 1200 < x < 1300, 2650 < y < 2800\nD.pcd: [1400, 2650] # -> 1400 < x < 1500, 2650 < y < 2800\n

You may use pointcloud_divider from MAP IV for dividing pointcloud map as well as generating the compatible metadata.yaml.

"},{"location":"design/autoware-architecture/map/#vector-map","title":"Vector Map","text":"

The vector cloud map must be supplied as a file with the following requirements:

  • It must be in Lanelet2 format, with additional modifications required by Autoware.
  • It must contain the shape and position information of lanes, traffic lights, stop lines, crosswalks, parking spaces, and parking lots.
  • Except at the beginning or end of a road, each lanelet in the map must be correctly connected to its predecessor, successors, left neighbor, and right neighbor.
  • Each lanelet in the map must contain traffic rule information including its speed limit, right of way, traffic direction, associated traffic lights, stop lines, and traffic signs.
  • It must cover the entire operational area of the vehicle.

Warning

Under Construction

"},{"location":"design/autoware-architecture/node-diagram/","title":"Node diagram","text":""},{"location":"design/autoware-architecture/node-diagram/#node-diagram","title":"Node diagram","text":"

This page depicts the node diagram designs for Autoware Core/Universe architecture.

"},{"location":"design/autoware-architecture/node-diagram/#autoware-core","title":"Autoware Core","text":"

TBD.

"},{"location":"design/autoware-architecture/node-diagram/#autoware-universe","title":"Autoware Universe","text":"

Open in draw.io for fullscreen

Note that the diagram is for reference. We are planning to update this diagram every release and may have old information between the releases. If you wish to check the latest node diagram use rqt_graph after launching the Autoware.

"},{"location":"design/autoware-architecture/perception/","title":"Perception Component Design","text":""},{"location":"design/autoware-architecture/perception/#perception-component-design","title":"Perception Component Design","text":""},{"location":"design/autoware-architecture/perception/#purpose-of-this-document","title":"Purpose of this document","text":"

This document outlines the high-level design strategies, goals and related rationales in the development of the Perception Component. Through this document, it is expected that all OSS developers will comprehend the design philosophy, goals and constraints under which the Perception Component is designed, and participate seamlessly in the development.

"},{"location":"design/autoware-architecture/perception/#overview","title":"Overview","text":"

The Perception Component receives inputs from Sensing, Localization, and Map components, and adds semantic information (e.g., Object Recognition, Obstacle Segmentation, Traffic Light Recognition, Occupancy Grid Map), which is then passed on to Planning Component. This component design follows the overarching philosophy of Autoware, defined as the microautonomy concept.

"},{"location":"design/autoware-architecture/perception/#goals-and-non-goals","title":"Goals and non-goals","text":"

The role of the Perception Component is to recognize the surrounding environment based on the data obtained through Sensing and acquire sufficient information (such as the presence of dynamic objects, stationary obstacles, blind spots, and traffic signal information) to enable autonomous driving.

In our overall design, we emphasize the concept of microautonomy architecture. This term refers to a design approach that focuses on the proper modularization of functions, clear definition of interfaces between these modules, and as a result, high expandability of the system. Given this context, the goal of the Perception Component is set not to solve every conceivable complex use case (although we do aim to support basic ones), but rather to provide a platform that can be customized to the user's needs and can facilitate the development of additional features.

To clarify the design concepts, the following points are listed as goals and non-goals.

Goals:

  • The basic functions are provided so that a simple ODD can be defined.
  • To achieve a design that can provide Perception functionality to every autonomous vehicle.
  • The capability is extensible with the third-party components.
  • The Perception Component is designed to provide a platform that enables Autoware users to develop the complete functionality and capability.
  • The Perception Component is designed to provide a platform that enables Autoware users to develop the autonomous driving system which always outperforms human drivers.
  • The Perception Component is designed to provide a platform that enables Autoware users to develop the autonomous driving system achieving \"zero overlooks\" or \"error-free recognition\".

Non-goals:

  • The Perception Component should not operate perfectly only in specific environments and be completely useless in other environments.
  • The Perception Component is not self-contained but can be extended with third parties.
  • The Perception Component is not aimed at the complete functionality and capability.
  • The Perception Component is not designed to always outperform human drivers.
  • The Perception Component is not capable of achieving \"zero overlooks\" or \"error-free recognition\".
"},{"location":"design/autoware-architecture/perception/#high-level-architecture","title":"High-level architecture","text":"

This diagram describes the high-level architecture of the Perception Component.

The Perception Component consists of the following sub-components:

  • Object Recognition: Recognizes dynamic objects surrounding the ego vehicle in the current frame and predicts their future trajectories.
  • Obstacle Segmentation: Identifies point clouds originating from obstacles(not only dynamic objects but also static obstacles that should be avoided, such as stationary obstacles) that the ego vehicle should avoid.
  • Occupancy Grid Map: Detects blind spots (areas where no information is available and where dynamic objects may jump out).
  • Traffic Light Recognition: Recognizes the colors of traffic lights and the directions of arrow signals.
"},{"location":"design/autoware-architecture/perception/#component-interface","title":"Component interface","text":"

The following describes the input/output concept between Perception Component and other components. See the Perception Component Interface (WIP) page for the current implementation.

"},{"location":"design/autoware-architecture/perception/#input-to-the-perception-component","title":"Input to the Perception Component","text":"
  • From Sensing: This input should provide real-time information about the environment.
    • Camera Image: Image data obtained from the camera.
    • Point Cloud: Point Cloud data obtained from LiDAR.
    • Radar Object: Object data obtained from radar.
  • From Localization: This input should provide real-time information about the ego vehicle.
    • Vehicle motion information: Includes the ego vehicle's position.
  • From Map: This input should provide real-time information about the static information about the environment.
    • Vector Map: Contains all static information about the environment, including lane aria information.
    • Point Cloud Map: Contains static point cloud maps, which should not include information about the dynamic objects.
  • From API:
    • V2X information: The information from V2X modules. For example, the information from traffic signals.
"},{"location":"design/autoware-architecture/perception/#output-from-the-perception-component","title":"Output from the Perception Component","text":"
  • To Planning
    • Dynamic Objects: Provides real-time information about objects that cannot be known in advance, such as pedestrians and other vehicles.
    • Obstacle Segmentation: Supplies real-time information about the location of obstacles, which is more primitive than Detected Object.
    • Occupancy Grid Map: Offers real-time information about the presence of occluded area information.
    • Traffic Light Recognition result: Provides the current state of each traffic light in real time.
"},{"location":"design/autoware-architecture/perception/#how-to-add-new-modules-wip","title":"How to add new modules (WIP)","text":"

As mentioned in the goal session, this perception module is designed to be extensible by third-party components. For specific instructions on how to add new modules and expand its functionality, please refer to the provided documentation or guidelines (WIP).

"},{"location":"design/autoware-architecture/perception/#supported-functions","title":"Supported Functions","text":"Feature Description Requirements LiDAR DNN based 3D detector This module takes point clouds as input and detects objects such as vehicles, trucks, buses, pedestrians, and bicycles. - Point Clouds Camera DNN based 2D detector This module takes camera images as input and detects objects such as vehicles, trucks, buses, pedestrians, and bicycles in the two-dimensional image space. It detects objects within image coordinates and providing 3D coordinate information is not mandatory. - Camera Images LiDAR Clustering This module performs clustering of point clouds and shape estimation to achieve object detection without labels. - Point Clouds Semi-rule based detector This module detects objects using information from both images and point clouds, and it consists of two components: LiDAR Clustering and Camera DNN based 2D detector. - Output from Camera DNN based 2D detector and LiDAR Clustering Object Merger This module integrates results from various detectors. - Detected Objects Interpolator This module stabilizes the object detection results by maintaining long-term detection results using Tracking results. - Detected Objects - Tracked Objects Tracking This module gives ID and estimate velocity to the detection results. - Detected Objects Prediction This module predicts the future paths (and their probabilities) of dynamic objects according to the shape of the map and the surrounding environment. - Tracked Objects - Vector Map Obstacle Segmentation This module identifies point clouds originating from obstacles that the ego vehicle should avoid. - Point Clouds - Point Cloud Map Occupancy Grid Map This module detects blind spots (areas where no information is available and where dynamic objects may jump out). - Point Clouds - Point Cloud Map Traffic Light Recognition This module detects the position and state of traffic signals. - Camera Images - Vector Map"},{"location":"design/autoware-architecture/perception/#reference-implementation","title":"Reference Implementation","text":"

When Autoware is launched, the default parameters are loaded, and the Reference Implementation is started. For more details, please refer to the Reference Implementation.

"},{"location":"design/autoware-architecture/perception/reference_implementation/","title":"Perception Component Reference Implementation Design","text":""},{"location":"design/autoware-architecture/perception/reference_implementation/#perception-component-reference-implementation-design","title":"Perception Component Reference Implementation Design","text":""},{"location":"design/autoware-architecture/perception/reference_implementation/#purpose-of-this-document","title":"Purpose of this document","text":"

This document outlines detailed design of the reference imprementations. This allows developers and users to understand what is currently available with the Perception Component, how to utilize, expand, or add to its features.

"},{"location":"design/autoware-architecture/perception/reference_implementation/#architecture","title":"Architecture","text":"

This diagram describes the architecture of the reference implementation.

The Perception component consists of the following sub-components:

  • Obstacle Segmentation: Identifies point clouds originating from obstacles(not only dynamic objects but also static obstacles that should be avoided, such as stationary obstacles) that the ego vehicle should avoid. For example, construction cones are recognized using this module.
  • Occupancy Grid Map: Detects blind spots (areas where no information is available and where dynamic objects may jump out).
  • Object Recognition: Recognizes dynamic objects surrounding the ego vehicle in the current frame and predicts their future trajectories.
    • Detection: Detects the pose and velocity of dynamic objects such as vehicles and pedestrians.
      • Detector: Triggers object detection processing frame by frame.
      • Interpolator: Maintains stable object detection. Even if the output from Detector suddenly becomes unavailable, Interpolator uses the output from the Tracking module to maintain the detection results without missing any objects.
    • Tracking: Associates detected results across multiple frames.
    • Prediction: Predicts trajectories of dynamic objects.
  • Traffic Light Recognition: Recognizes the colors of traffic lights and the directions of arrow signals.
"},{"location":"design/autoware-architecture/perception/reference_implementation/#internal-interface-in-the-perception-component","title":"Internal interface in the perception component","text":"
  • Obstacle Segmentation to Object Recognition
    • Point Cloud: A Point Cloud observed in the current frame, where the ground and outliers are removed.
  • Obstacle Segmentation to Occupancy Grid Map
    • Ground filtered Point Cloud: A Point Cloud observed in the current frame, where the ground is removed.
  • Occupancy Grid Map to Obstacle Segmentation
    • Occupancy Grid Map: This is used for filtering outlier.
"},{"location":"design/autoware-architecture/planning/","title":"Planning component design","text":""},{"location":"design/autoware-architecture/planning/#planning-component-design","title":"Planning component design","text":""},{"location":"design/autoware-architecture/planning/#overview","title":"Overview","text":"

The Planning component generates the trajectory message that will be subscribed to by the Control component based on the environmental state obtained from the Localization and the Perception components.

"},{"location":"design/autoware-architecture/planning/#requirements","title":"Requirements","text":"

The goal of the Planning component is to generate a trajectory (path and velocity) of the ego vehicle that is safe and well-regulated while satisfying the given mission.

Goals:

  • The basic functions are provided so that a simple ODD can be defined.
  • The functionality is modularized to accommodate the third-party components. That is, a complicated or realistic ODD needs not be defined by the basic functions provided by default.
  • The capability is extensible with the third-party components or the decision of human operators.
  • The mechanism and policy are separated to allow the system or operators to change the behavior of the ego vehicle. Ultimately speaking, the policy can be set to crash an obstacle and the mechanism always follows. Otherwise, the system is not safe from the design point of view.

Non-goals:

  • The Planning component is not self-contained but can be extended with third parties.
  • The Planning component is not aimed at the complete functionality and capability.
  • The Planning component is not designed to always outperform human drivers.
  • The Planning component is not capable of \u201cnever crashes\u201d.
"},{"location":"design/autoware-architecture/planning/#high-level-architecture","title":"High-level architecture","text":"

This diagram describes the high-level architecture of the Planning Component.

The Planning component consists of the following sub-components:

  • Mission Planning: Calculates the route based on the given goal and map information.
  • Scenario Planning: Determines the trajectory based on the current scenario, such as Lane Driving or Parking.
    • Lane Driving: Calculates the trajectory for driving within constructed lanes.
      • Behavior Planner: Calculates suitable trajectory based on safety considerations and traffic rules.
      • Motion Planner: Calculates suitable trajectory for the vehicle by taking into account safety factors, vehicle motion considerations, and instructions from the behavior planner.
    • Parking: Calculates the trajectory for parking in unstructured areas.
  • Validation: Verifies the safety of the trajectory.

Each component contains some modules that can be dynamically loaded and unloaded based on the situation. For instance, the Behavior Planning component includes modules such as lane change, intersection, and crosswalk modules.

Our planning components are built based on the microautonomy architecture with Autoware. We adopt a modular system framework where the tasks are implemented as modules that can be dynamically loaded and unloaded to achieve different features depending on the given use cases.

"},{"location":"design/autoware-architecture/planning/#component-interface","title":"Component interface","text":"

The following describes the input/output concept between Planning Component and other components. See the Planning Component Interface (WIP) page for the current implementation.

"},{"location":"design/autoware-architecture/planning/#input-to-the-planning-component","title":"Input to the planning component","text":"
  • From Map
    • Vector map: Contains all static information about the environment, including lane connection information for route planning, lane geometry for generating a reference path, and traffic rule-related information.
  • From Perception
    • Detected object information: Provides real-time information about objects that cannot be known in advance, such as pedestrians and other vehicles. The Planning Component plans maneuvers to avoid collisions with these objects.
    • Detected obstacle information: Supplies real-time information about the location of obstacles, which is more primitive than Detected Object and used for emergency stops and other safety measures.
    • Occupancy map information: Offers real-time information about the presence of pedestrians and other vehicles and occluded area information.
    • Traffic light recognition result: Provides the current state of each traffic light in real time. The Planning Component extracts relevant information for the planned path and determines whether to stop at intersections.
  • From Localization
    • Vehicle motion information: Includes the ego vehicle's position, velocity, acceleration, and other motion-related data.
  • From System
    • Operation mode: Indicates whether the vehicle is operating in Autonomous mode.
  • From Human Machine Interface (HMI)
    • Feature execution: Allows for executing/authorizing autonomous driving operations, such as lane changes or entering intersections, by human operators.
  • From API Layer
    • Goal: Represents the final position that the Planning Component aims to reach.
    • Checkpoint: Represents a midpoint along the route to the destination. This is used during route calculation.
    • Velocity limit: Sets the maximum speed limit for the vehicle.
"},{"location":"design/autoware-architecture/planning/#output-from-the-planning-component","title":"Output from the planning component","text":"
  • To Control
    • Trajectory: Provides a smooth sequence of pose, twist, and acceleration that the Control Component must follow. The trajectory is typically 10 seconds long with a 0.1-second resolution.
    • Turn Signals: Controls the vehicle's turn indicators, such as right, left, hazard, etc. based on the planned maneuvers.
  • To System
    • Diagnostics: Reports the state of the Planning Component, indicating whether the processing is running correctly and whether a safe plan is being generated.
  • To Human Machine Interface (HMI)
    • Feature execution availability: Indicates the status of operations that can be executed or are required, such as lane changes or entering intersections.
    • Trajectory candidate: Shows the potential trajectory that will be executed after the user's execution.
  • To API Layer
    • Planning factors: Provides information about the reasoning behind the current planning behavior. This may include the position of target objects to avoid, obstacles that led to the decision to stop, and other relevant information.
"},{"location":"design/autoware-architecture/planning/#internal-interface-in-the-planning-component","title":"Internal interface in the planning component","text":"
  • Mission Planning to Scenario Planning
    • Route: Offers guidance for the path that needs to be followed from the starting point to the destination. This path is determined based on information such as lane IDs defined on the map. At the route level, it doesn't explicitly indicate which specific lanes to take, and the route can contain multiple lanes.
  • Behavior Planning to Motion Planning
    • Path: Provides a rough position and velocity to be followed by the vehicle. These path points are usually defined with an interval of about 1 meter. Although other interval distances are possible, it may impact the precision or performance of the planning component.
    • Drivable area: Defines regions where the vehicle can drive, such as within lanes or physically drivable areas. It assumes that the motion planner will calculate the final trajectory within this defined area.
  • Scenario Planning to Validation
    • Trajectory: Defines the desired positions, velocities, and accelerations which the Control Component will try to follow. Trajectory points are defined at intervals of approximately 0.1 seconds based on the trajectory velocities.
  • Validation to Control Component
    • Trajectory: Same as above but with some additional safety considerations.
"},{"location":"design/autoware-architecture/planning/#how-to-add-new-modules-wip","title":"How to add new modules (WIP)","text":"

As mentioned in the goal session, this planning module is designed to be extensible by third-party components. For specific instructions on how to add new modules and expand its functionality, please refer to the provided documentation or guidelines (WIP).

"},{"location":"design/autoware-architecture/planning/#supported-functions","title":"Supported Functions","text":"Feature Description Requirements Figure Route Planning Plan route from the ego vehicle position to the destination. Reference implementation is in Mission Planner, enabled by launching the mission_planner node. - Lanelet map (driving lanelets) Path Planning from Route Plan path to be followed from the given route. Reference implementation is in Behavior Path Planner. - Lanelet map (driving lanelets) Obstacle Avoidance Plan path to avoid obstacles by steering operation. Reference implementation is in Avoidance, Obstacle Avoidance Planner. Enable flag in parameter: launch obstacle_avoidance_planner true - objects information Path Smoothing Plan path to achieve smooth steering. Reference implementation is in Obstacle Avoidance Planner. - Lanelet map (driving lanelet) Narrow Space Driving Plan path to drive within the drivable area. Furthermore, when it is not possible to drive within the drivable area, stop the vehicle to avoid exiting the drivable area. Reference implementation is in Obstacle Avoidance Planner. - Lanelet map (high-precision lane boundaries) Lane Change Plan path for lane change to reach the destination. Reference implementation is in Lane Change.. Enable flag in both parameters: - Lanelet map (driving lanelets) Pull Over Plan path for pull over to park at the road shoulder. Reference implementation is in Goal Planner. - Lanelet map (shoulder lane) Pull Out Plan path for pull over to start from the road shoulder. Reference implementation is in Pull Out Module. - Lanelet map (shoulder lane) Path Shift Plan path in lateral direction in response to external instructions. Reference implementation is in Side Shift Module. - None Obstacle Stop Plan velocity to stop for an obstacle on the path. Reference implementation is in Obstacle Stop Planner, Obstacle Cruise Planner. launch obstacle_stop_planner and enable flag: TODO, launch obstacle_cruise_planner and enable flag: TODO - objects information Obstacle Deceleration Plan velocity to decelerate for an obstacle located around the path. Reference implementation is in Obstacle Stop Planner, Obstacle Cruise Planner. - objects information Adaptive Cruise Control Plan velocity to follow the vehicle driving in front of the ego vehicle. Reference implementation is in Obstacle Stop Planner, Obstacle Cruise Planner. - objects information Decelerate for cut-in vehicles Plan velocity to avoid a risk for cutting-in vehicle to ego lane. Reference implementation is in Obstacle Cruise Planner. - objects information Surround Check at starting Plan velocity to prevent moving when an obstacle exists around the vehicle. Reference implementation is in Surround Obstacle Checker. - objects information Curve Deceleration Plan velocity to decelerate the speed on a curve. Reference implementation is in Motion Velocity Smoother. - None Curve Deceleration for Obstacle Plan velocity to decelerate the speed on a curve for a risk of obstacle collision around the path. Reference implementation is in Obstacle Velocity Limiter. - objects information - Lanelet map (static obstacle) Crosswalk Plan velocity to stop or decelerate for pedestrians approaching or walking on a crosswalk. Reference implementation is in Crosswalk Module. - objects information - Lanelet map (pedestrian crossing) Intersection Oncoming Vehicle Check Plan velocity for turning right/left at intersection to avoid a risk with oncoming other vehicles. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane and yield lane) Intersection Blind Spot Check Plan velocity for turning right/left at intersection to avoid a risk with other vehicles or motorcycles coming from behind blind spot. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane) Intersection Occlusion Check Plan velocity for turning right/left at intersection to avoid a risk with the possibility of coming vehicles from occlusion area. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane) WIP Intersection Traffic Jam Detection Plan velocity for intersection not to enter the intersection when a vehicle is stopped ahead for a traffic jam. Reference implementation is in Intersection Module. - objects information - Lanelet map (intersection lane) Traffic Light Plan velocity for intersection according to a traffic light signal. Reference implementation is in Traffic Light Module. - Traffic light color information Run-out Check Plan velocity to decelerate for the possibility of nearby objects running out into the path. Reference implementation is in Run Out Module. - objects information Stop Line Plan velocity to stop at a stop line. Reference implementation is in Stop Line Module. - Lanelet map (stop line) Occlusion Spot Check Plan velocity to decelerate for objects running out from occlusion area, for example, from behind a large vehicle. Reference implementation is in Occlusion Spot Module. - objects information - Lanelet map (private/public lane) No Stop Area Plan velocity not to stop in areas where stopping is prohibited, such as in front of the fire station entrance. Reference implementation is in No Stopping Area Module. - Lanelet map (no stopping area) Merge from Private Area to Public Road Plan velocity for entering the public road from a private driveway to avoid a risk of collision with pedestrians or other vehicles. Reference implementation is in Merge from Private Area Module. - objects information - Lanelet map (private/public lane) WIP Speed Bump Plan velocity to decelerate for speed bumps. Reference implementation is in Speed Bump Module. - Lanelet map (speed bump) WIP Detection Area Plan velocity to stop at the corresponding stop when an object exist in the designated detection area. Reference implementation is in Detection Area Module. - Lanelet map (detection area) Out of ODD area Plan velocity to stop before exiting the area designated by ODD (Operational Design Domain). Reference implementation is in (WIP). - Lanelet map (invalid lanelet) WIP Collision Detection when deviating from lane Plan velocity to avoid conflict with other vehicles driving in the another lane when the ego vehicle is deviating from own lane. Reference implementation is in Out of Lane Module. - objects information - Lanelet map (driving lane) WIP Parking Plan path and velocity for given goal in parking area. Reference implementation is in Free Space Planner. - objects information - Lanelet map (parking area) Autonomous Emergency Braking (AEB) Perform an emergency stop if a collision with an object ahead is anticipated. It is noted that this function is expected as a final safety layer, and this should work even in the event of failures in the Localization or Perception system. Reference implementation is in Out of Lane Module. - Primitive objects WIP Minimum Risk Maneuver (MRM) Provide appropriate MRM (Minimum Risk Maneuver) instructions when a hazardous event occurs. For example, when a sensor trouble found, send an instruction for emergency braking, moderate stop, or pulling over to the shoulder, depending on the severity of the situation. Reference implementation is in TODO - TODO WIP Trajectory Validation Check the planned trajectory is safe. If it is unsafe, take appropriate action, such as modify the trajectory, stop sending the trajectory or report to the autonomous driving system. Reference implementation is in Planning Validator. - None WIP Running Lane Map Generation Generate lane map from localization data recorded in manual driving. Reference implementation is in WIP - None WIP Running Lane Optimization Optimize the centerline (reference path) of the map to make it smooth considering the vehicle kinematics. Reference implementation is in Static Centerline Optimizer. - Lanelet map (driving lanes) WIP"},{"location":"design/autoware-architecture/planning/#reference-implementation","title":"Reference Implementation","text":"

The following diagram describes the reference implementation of the Planning component. By adding new modules or extending the functionalities, various ODDs can be supported.

Note that some implementation does not adhere to the high-level architecture design and require updating.

For more details, please refer to the design documents in each package.

  • mission_planner: calculate route from start to goal based on the map information.
  • behavior_path_planner: calculates path and drivable area based on the traffic rules.
    • lane_following
    • lane_change
    • avoidance
    • pull_over
    • pull_out
    • side_shift
  • behavior_velocity_planner: calculates max speed based on the traffic rules.
    • detection_area
    • blind_spot
    • cross_walk
    • stop_line
    • traffic_light
    • intersection
    • no_stopping_area
    • virtual_traffic_light
    • occlusion_spot
    • run_out
  • obstacle_avoidance_planner: calculate path shape under obstacle and drivable area constraints
  • surround_obstacle_checker: keeps the vehicle being stopped when there are obstacles around the ego-vehicle. It works only when the vehicle is stopped.
  • obstacle_stop_planner: When there are obstacles on or near the trajectory, it calculates the maximum velocity of the trajectory points depending on the situation: stopping, slowing down, or adaptive cruise (following the car).
    • stop
    • slow_down
    • adaptive_cruise
  • costmap_generator: generates a costmap for path generation from dynamic objects and lane information.
  • freespace_planner: calculates trajectory considering the feasibility (e.g. curvature) for the freespace scene. Algorithms are described here.
  • scenario_selector : chooses a trajectory according to the current scenario.
  • external_velocity_limit_selector: takes an appropriate velocity limit from multiple candidates.
  • motion_velocity_smoother: calculates final velocity considering velocity, acceleration, and jerk constraints.
"},{"location":"design/autoware-architecture/planning/#important-parameters","title":"Important Parameters","text":"Package Parameter Type Description obstacle_stop_planner stop_planner.stop_position.max_longitudinal_margin double distance between the ego and the front vehicle when stopping (when cruise_planner_type:=obstacle_stop_planner) obstacle_cruise_planner common.safe_distance_margin double distance between the ego and the front vehicle when stopping (when cruise_planner_type:=obstacle_cruise_planner) behavior_path_planner avoidance.avoidance.lateral.lateral_collision_margin double minimum lateral margin to obstacle on avoidance behavior_path_planner avoidance.avoidance.lateral.lateral_collision_safety_buffer double additional lateral margin to obstacle if possible on avoidance obstacle_avoidance_planner option.enable_outside_drivable_area_stop bool If set true, a stop point will be inserted before the path footprint is outside the drivable area."},{"location":"design/autoware-architecture/planning/#notation","title":"Notation","text":""},{"location":"design/autoware-architecture/planning/#1-self-crossing-road-and-overlapped","title":"[1] self-crossing road and overlapped","text":"

To support the self-crossing road and overlapped road in the opposite direction, each planning module has to meet the specifications

Currently, the supported modules are as follows.

  • lane_following (in behavior_path_planner)
  • detection_area (in behavior_velocity_planner)
  • stop_line (in behavior_velocity_planner)
  • virtual_traffic_light (in behavior_velocity_planner)
  • obstacle_avoidance_planner
  • obstacle_stop_planner
  • motion_velocity_smoother
"},{"location":"design/autoware-architecture/planning/#2-size-of-path-points","title":"[2] Size of Path Points","text":"

Some functions do not support paths with only one point. Therefore, each modules should generate the path with more than two path points.

"},{"location":"design/autoware-architecture/sensing/","title":"Sensing component design","text":""},{"location":"design/autoware-architecture/sensing/#sensing-component-design","title":"Sensing component design","text":""},{"location":"design/autoware-architecture/sensing/#overview","title":"Overview","text":"

Sensing component is a collection of modules that apply some primitive pre-processing to the raw sensor data.

The sensor input formats are defined in this component.

"},{"location":"design/autoware-architecture/sensing/#role","title":"Role","text":"
  • Abstraction of data formats to enable usage of sensors from various vendors
  • Perform common/primitive sensor data processing required by each component
"},{"location":"design/autoware-architecture/sensing/#inputs","title":"Inputs","text":""},{"location":"design/autoware-architecture/sensing/#input-types","title":"Input types","text":"Sensor Data Message Type Point cloud (Lidars, depth cameras, etc.) sensor_msgs/msg/PointCloud2.msg Image (RGB, monochrome, depth, etc. cameras) sensor_msgs/msg/Image.msg Radar scan radar_msgs/msg/RadarScan.msg Radar tracks radar_msgs/msg/RadarTracks.msg GNSS-INS position sensor_msgs/msg/NavSatFix.msg GNSS-INS orientation autoware_sensing_msgs/GnssInsOrientationStamped.msg GNSS-INS velocity geometry_msgs/msg/TwistWithCovarianceStamped.msg GNSS-INS acceleration geometry_msgs/msg/AccelWithCovarianceStamped.msg Ultrasonics sensor_msgs/msg/Range.msg"},{"location":"design/autoware-architecture/sensing/#design-by-data-types","title":"Design by data-types","text":"
  • GNSS/INS data pre-processing design
  • Image pre-processing design
  • Point cloud pre-processing design
  • Radar data pre-processing design
  • Ultrasonics data pre-processing design
"},{"location":"design/autoware-architecture/sensing/data-types/gnss-ins-data/","title":"GNSS/INS data pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/gnss-ins-data/#gnssins-data-pre-processing-design","title":"GNSS/INS data pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/sensing/data-types/image/","title":"Image pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/image/#image-pre-processing-design","title":"Image pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/","title":"Point cloud pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#point-cloud-pre-processing-design","title":"Point cloud pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#overview","title":"Overview","text":"

Point cloud pre-processing is a collection of modules that apply some primitive pre-processing to the raw sensor data.

This pipeline covers the flow of data from drivers to the perception stack.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#recommended-processing-pipeline","title":"Recommended processing pipeline","text":"
graph TD\n    Driver[\"Lidar Driver\"] -->|\"Cloud XYZIRCADT\"| FilterPR[\"Polygon Remover Filter / CropBox Filter\"]\n\n    subgraph \"sensing\"\n    FilterPR -->|\"Cloud XYZIRCADT\"| FilterDC[\"Motion Distortion Corrector Filter\"]\n    FilterDC -->|\"Cloud XYZIRCAD\"| FilterOF[\"Outlier Remover Filter\"]\n    FilterOF -->|\"Cloud XYZIRC\"| FilterDS[\"Downsampler Filter\"]\n    FilterDS -->|\"Cloud XYZIRC\"| FilterTrans[\"Cloud Transformer\"]\n    FilterTrans -->|\"Cloud XYZIRC\"| FilterC\n\n    FilterX[\"...\"] -->|\"Cloud XYZIRC (i)\"| FilterC[\"Cloud Concatenator\"]\n    end\n\n    FilterC -->|\"Cloud XYZIRC\"| SegGr[\"Ground Segmentation\"]
"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#list-of-modules","title":"List of modules","text":"

The modules used here are from pointcloud_preprocessor package.

For details about the modules, see the following table.

It is recommended that these modules are used in a single container as components. For details see ROS 2 Composition

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#point-cloud-fields","title":"Point cloud fields","text":"

In the ideal case, the driver is expected to output a point cloud with the PointXYZIRCADT point type.

name datatype derived description X FLOAT32 false X position Y FLOAT32 false Y position Z FLOAT32 false Z position I (intensity) UINT8 false Measured reflectivity, intensity of the point R (return type) UINT8 false Laser return type for dual return lidars C (channel) UINT16 false Vertical channel id of the laser that measured the point A (azimuth) FLOAT32 true atan2(Y, X), Horizontal angle from the front of the lidar to the point D (distance) FLOAT32 true hypot(X, Y, Z), Euclidean distance of the point to lidar T (time) UINT32 false Nanoseconds passed since the time of the header when this point was measured

Note

A (azimuth) and D (distance) fields are derived fields. They are provided by the driver to reduce the computational load on some parts of the perception stack.

Note

If the Motion Distortion Corrector Filter won't be used, the T (time) field can be omitted, PointXYZIRCAD point type can be used.

Warning

Autoware will support conversion from PointXYZI to PointXYZIRC or PointXYZIRCAD (with channel and return is set to 0) for prototyping purposes. However, this conversion is not recommended for production use since it's not efficient.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#intensity","title":"Intensity","text":"

We will use following ranges for intensity, compatible with the VLP16 User Manual:

Quoting from the VLP-16 User Manual:

For each laser measurement, a reflectivity byte is returned in addition to distance. Reflectivity byte values are segmented into two ranges, allowing software to distinguish diffuse reflectors (e.g. tree trunks, clothing) in the low range from retroreflectors (e.g. road signs, license plates) in the high range. A retroreflector reflects light back to its source with a minimum of scattering. The VLP-16 provides its own light, with negligible separation between transmitting laser and receiving detector, so retroreflecting surfaces pop with reflected IR light compared to diffuse reflectors that tend to scatter reflected energy.

  • Diffuse reflectors report values from 0 to 100 for reflectivities from 0% to 100%.
  • Retroreflectors report values from 101 to 255, where 255 represents an ideal reflection.

In a typical point cloud without retroreflectors, all intensity points will be between 0 and 100.

Retroreflective Gradient road sign, Image Source

But in a point cloud with retroreflectors, the intensity points will be between 0 and 255.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#intensity-mapping-for-other-lidar-brands","title":"Intensity mapping for other lidar brands","text":""},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#hesai-pandarxt16","title":"Hesai PandarXT16","text":"

Hesai Pandar XT16 User Manual

This lidar has 2 modes for reporting reflectivity:

  • Linear mapping
  • Non-linear mapping

If you are using linear mapping mode, you should map from [0, 255] to [0, 100] when constructing the point cloud.

If you are using non-linear mapping mode, you should map (hesai to autoware)

  • [0, 251] to [0, 100] and
  • [252, 254] to [101, 255]

when constructing the point cloud.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#livox-mid-70","title":"Livox Mid-70","text":"

Livox Mid-70 User Manual

This lidar has 2 modes for reporting reflectivity similar to Velodyne VLP-16, only the ranges are slightly different.

You should map (livox to autoware)

  • [0, 150] to [0, 100] and
  • [151, 255] to [101, 255]

when constructing the point cloud.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#robosense-rs-lidar-16","title":"RoboSense RS-LiDAR-16","text":"

RoboSense RS-LiDAR-16 User Manual

No mapping required, same as Velodyne VLP-16.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#ouster-os-1-64","title":"Ouster OS-1-64","text":"

Software User Manual v2.0.0 for all Ouster sensors

In the manual it is stated:

Reflectivity [16 bit unsigned int] - sensor Signal Photons measurements are scaled based on measured range and sensor sensitivity at that range, providing an indication of target reflectivity. Calibration of this measurement has not currently been rigorously implemented, but this will be updated in a future firmware release.

So it is advised to map the 16 bit reflectivity to [0, 100] range.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#leishen-ch64w","title":"Leishen CH64W","text":"

I couldn't get the english user manual, link of website

In a user manual I was able to find it says:

Byte 7 represents echo strength, and the value range is 0-255. (Echo strength can reflect the energy reflection characteristics of the measured object in the actual measurement environment. Therefore, the echo strength can be used to distinguish objects with different reflection characteristics.)

So it is advised to map the [0, 255] to [0, 100] range.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#return-type","title":"Return type","text":"

Various lidars support multiple return modes. Velodyne lidars support Strongest and Last return modes.

In the PointXYZIRCT and PointXYZIRC types, R field represents return mode with an UINT8.

R (return type) Description 0 Unknown / Not Marked 1 Strongest 2 Last"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#channel","title":"Channel","text":"

The channel field is used to identify the vertical channel of the laser that measured the point. In various lidar manuals or literature, it can also be called laser id, ring, laser line.

For Velodyne VLP-16, there are 16 channels. Default order of channels in drivers are generally in firing order.

In the PointXYZIRCT and PointXYZIRC types, C field represents the vertical channel id with an UINT16.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#solid-state-and-petal-pattern-lidars","title":"Solid state and petal pattern lidars","text":"

Warning

This section is subject to change. Following are suggestions and open for discussion.

For solid state lidars that have lines, assign row number as the channel id.

For petal pattern lidars, you can keep channel 0.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#time","title":"Time","text":"

In lidar point clouds, each point measurement can have its individual time stamp. This information can be used to eliminate the motion blur that is caused by the movement of the lidar during the scan.

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#point-cloud-header-time","title":"Point cloud header time","text":"

The header contains a Time field. The time field has 2 components:

Field Type Description sec int32 Unix time (seconds elapsed since January 1, 1970) nanosec uint32 Nanoseconds elapsed since the sec field

The header of the point cloud message is expected to have the time of the earliest point it has.

Note

The sec field is int32 in ROS 2 humble. The largest value it can represent is 2^31 seconds, it is subject to year 2038 problems. We will wait for actions on ROS 2 community side.

More info at: https://github.com/ros2/rcl_interfaces/issues/85

"},{"location":"design/autoware-architecture/sensing/data-types/point-cloud/#individual-point-time","title":"Individual point time","text":"

Each PointXYZIRCT point type has the T field for representing the nanoseconds passed since the first-shot point of the point cloud.

To calculate exact time each point was shot, the T nanoseconds are added to the header time.

Note

The T field is uint32 type. The largest value it can represent is 2^32 nanoseconds, which equates to roughly 4.29 seconds. Usual point clouds don't last more than 100ms for full cycle. So this field should be enough.

"},{"location":"design/autoware-architecture/sensing/data-types/radar-data/","title":"Radar data pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/radar-data/#radar-data-pre-processing-design","title":"Radar data pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/sensing/data-types/ultrasonics-data/","title":"Ultrasonics data pre-processing design","text":""},{"location":"design/autoware-architecture/sensing/data-types/ultrasonics-data/#ultrasonics-data-pre-processing-design","title":"Ultrasonics data pre-processing design","text":"

Warning

Under Construction

"},{"location":"design/autoware-architecture/vehicle/","title":"Vehicle Interface design","text":""},{"location":"design/autoware-architecture/vehicle/#vehicle-interface-design","title":"Vehicle Interface design","text":""},{"location":"design/autoware-architecture/vehicle/#abstract","title":"Abstract","text":"

The Vehicle Interface component provides an interface between Autoware and a vehicle that passes control signals to the vehicle\u2019s drive-by-wire system and receives vehicle information that is passed back to Autoware.

"},{"location":"design/autoware-architecture/vehicle/#1-requirements","title":"1. Requirements","text":"

Goals:

  • The Vehicle Interface component converts Autoware commands to a vehicle-specific format and converts vehicle status in a vehicle-specific format to Autoware messages.
  • The interface between Autoware and the Vehicle component is abstracted and independent of hardware.
  • The interface is extensible such that additional vehicle-specific commands can be easily added. For example, headlight control.

Non-goals:

  • Accuracy of responses from the vehicle will not be defined, but example accuracy requirements from reference designs are provided as examples.
  • Response speed will not be defined.
"},{"location":"design/autoware-architecture/vehicle/#2-architecture","title":"2. Architecture","text":"

The Vehicle Interface component consists of the following components:

  • A Raw Vehicle Command Converter component that will pass through vehicle commands from the Control component if velocity/acceleration control is supported by the drive-by-wire system. Otherwise, the Control commands will be modified according to the control method (eg: converting a target acceleration from the Control component to a vehicle specific accel/brake pedal value through the use of an acceleration map)
  • A Vehicle Interface component (vehicle specific) that acts as an interface between Autoware and a vehicle to communicate control signals and to obtain information about the vehicle (steer output, tyre angle etc)

Each component contains static nodes of Autoware, while each module can be dynamically loaded and unloaded (corresponding to C++ classes). The mechanism of the Vehicle Interface component is depicted by the following figures:

"},{"location":"design/autoware-architecture/vehicle/#3-features","title":"3. Features","text":"

The Vehicle Interface component can provide the following features in functionality and capability:

  • Basic functions

    • Converting Autoware control commands to vehicle specific command
    • Converting vehicle specific status information (velocity, steering) to Autoware status message
  • Diagnostics
    • List available features
    • Provide a warning if the Control component tries to use a feature that is not available in the Vehicle Interface component

Additional functionality and capability features may be added, depending on the vehicle hardware. Some example features are listed below:

  • Safety features
    • Disengage autonomous driving via manual intervention.
      • This can be done through the use of an emergency disengage button, or by a safety driver manually turning the steering wheel or pressing the brake
  • Optional controls
    • Turn indicator
    • Handbrake
    • Headlights
    • Hazard lights
    • Doors
    • Horn
    • Wipers
"},{"location":"design/autoware-architecture/vehicle/#4-interface-and-data-structure","title":"4. Interface and Data Structure","text":"

The interface of the Vehicle Interface component for other components running in the same process space to access the functionality and capability of the Vehicle Interface component is defined as follows.

From Control

  • Actuation Command
    • target acceleration, braking, and steering angle

From Planning

  • Vehicle Specific Commands (optional and a separate message for each type)
    • Shift
    • Door
    • Wiper
    • etc

From the vehicle

  • Vehicle status messages
    • Vehicle-specific format messages for conversion into Autoware-specific format messages
      • Velocity status
      • Steering status (optional)
      • Shift status (optional)
      • Turn signal status (optional)
      • Actuation status (optional)

The output interface of the Vehicle Interface component:

  • Vehicle control messages to the vehicle
    • Control signals to drive the vehicle
    • Depends on the vehicle type/protocol, but should include steering and velocity commands at a minimum
  • Vehicle status messages to Autoware
  • Actuation Status
    • Acceleration, brake, steering status
  • Vehicle odometry (output to Localization)
    • Vehicle twist information
  • Control mode
    • Information about whether the vehicle is under autonomous control or manual control
  • Shift status (optional)
    • Vehicle shift status
  • Turn signal status (optional)
    • Vehicle turn signal status

The data structure for the internal representation of semantics for the objects and trajectories used in the Vehicle Interface component is defined as follows:

"},{"location":"design/autoware-architecture/vehicle/#5-concerns-assumptions-and-limitations","title":"5. Concerns, Assumptions, and Limitations","text":"

Concerns

  • Architectural trade-offs and scalability

Assumptions

-

Limitations

"},{"location":"design/autoware-architecture/vehicle/#6-examples-of-accuracy-requirements-by-odd","title":"6. Examples of accuracy requirements by ODD","text":""},{"location":"design/autoware-concepts/","title":"Autoware concepts","text":""},{"location":"design/autoware-concepts/#autoware-concepts","title":"Autoware concepts","text":"

Autoware is the world\u2019s first open-source software for autonomous driving systems. Autoware provides value for both The technology developers of autonomous driving systems can create new components based on Autoware. The service operators of autonomous driving systems, on the other hand, can select appropriate technology components with Autoware. This is enabled by the microautonomy architecture that modularizes its software stack into the core and universe subsystems (modules).

"},{"location":"design/autoware-concepts/#microautonomy-architecture","title":"Microautonomy architecture","text":"

Autoware uses a pipeline architecture to enable the development of autonomous driving systems. The pipeline architecture used in Autoware consists of components similar to three-layer-architecture. And they run in parallel. There are 2 main modules: the Core and the Universe. The components in these modules are designed to be extensible and reusable. And we call it microautonomy architecture.

"},{"location":"design/autoware-concepts/#the-core-module","title":"The Core module","text":"

The Core module contains basic runtimes and technology components that satisfy the basic functionality and capability of sensing, computing, and actuation required for autonomous driving systems. AWF develops and maintains the Core module with their architects and leading members through their working groups. Anyone can contribute to the Core but the PR(Pull Request) acceptance criteria is more strict compared to the Universe.

"},{"location":"design/autoware-concepts/#the-universe-module","title":"The Universe module","text":"

The Universe modules are extensions to the Core module that can be provided by the technology developers to enhance the functionality and capability of sensing, computing, and actuation. AWF provides the base Universe module to extend from. A key feature of the microautonomy architecture is that the Universe modules can be contributed to by any organization and individual. That is, you can even create your Universe and make it available for the Autoware community and ecosystem. AWF is responsible for quality control of the Universe modules through their development process. As a result, there are multiple types of the Universe modules - some are verified and validated by AWF and others are not. It is up to the users of Autoware which Universe modules are selected and integrated to build their end applications.

"},{"location":"design/autoware-concepts/#interface-design","title":"Interface design","text":"

The interface design is the most essential piece of the microautonomy architecture, which is classified into internal and external interfaces. The component interface is designed for the components in a Universe module to communicate with those in other modules, including the Core module, within Autoware internally. The AD(Autonomous Driving) API, on the other hand, is designed for the applications of Autoware to access the technology components in the Core and Universe modules of Autoware externally. Designing solid interfaces, the microautonomy architecture is made possible with AWF's partners, and at the same time is made feasible for the partners.

"},{"location":"design/autoware-concepts/#challenges","title":"Challenges","text":"

A grand challenge of the microautonomy architecture is to achieve real-time capability, which guarantees all the technology components activated in the system to predictably meet timing constraints (given deadlines). In general, it is difficult, if not impossible, to tightly estimate the worst-case execution times (WCETs) of components.

In addition, it is also difficult, if not impossible, to tightly estimate the end-to-end latency of components connected by a DAG. Autonomous driving systems based on the microautonomy architecture, therefore, must be designed to be fail-safe but not never-fail. We accept that the timing constraints may be violated (the given deadlines may be missed) as far as the overrun is taken into account. The overrun handlers are two-fold: (i) platform-defined and (ii) user-defined. The platform-defined handler is implemented as part of the platform by default, while the user-defined handler can overwrite it or add a new handler to the system. This is what we call \u201cfail-safe\u201d on a timely basis.

"},{"location":"design/autoware-concepts/#requirements-and-roadmap","title":"Requirements and roadmap","text":"

Goals:

  • All open-source
  • Use case driven
  • Real-time (predictable) framework with overrun handling
  • Code quality
"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/","title":"How is Autoware Core/Universe different from Autoware.AI and Autoware.Auto?","text":""},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#how-is-autoware-coreuniverse-different-from-autowareai-and-autowareauto","title":"How is Autoware Core/Universe different from Autoware.AI and Autoware.Auto?","text":"

Autoware is the world's first \"all-in-one\" open-source software for self-driving vehicles. Since it was first released in 2015, there have been multiple releases made with differing underlying concepts, each one aimed at improving the software.

"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#autowareai","title":"Autoware.AI","text":"

Autoware.AI is the first distribution of Autoware that was released based on ROS 1. The repository contains a variety of packages covering different aspects of autonomous driving technologies - sensing, actuation, localization, mapping, perception and planning.

While it was successful in attracting many developers and contributions, it was difficult to improve Autoware.AI's capabilities for a number of reasons:

  • A lack of concrete architecture design leading to a lot of built-up technical debt, such as tight coupling between modules and unclear module responsibility.
  • Differing coding standards for each package, with very low test coverage.

Furthermore, there was no clear definition of the conditions under which an Autoware-enabled autonomous vehicle could operate, nor of the use cases or situations supported (eg: the ability to overtake a stationary vehicle).

From the lessons learned from Autoware.AI development, a different development process was taken for Autoware.Auto to develop a ROS 2 version of Autoware.

Warning

Autoware.AI is currently in maintenance mode and will reach end-of-life at the end of 2022.

"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#autowareauto","title":"Autoware.Auto","text":"

Autoware.Auto is the second distribution of Autoware that was released based on ROS 2. As part of the transition to ROS 2, it was decided to avoid simply porting Autoware.AI from ROS 1 to ROS 2. Instead, the codebase was rewritten from scratch with proper engineering practices, including defining target use cases and ODDs (eg: Autonomous Valet Parking [AVP], Cargo Delivery, etc.), designing a proper architecture, writing design documents and test code.

Autoware.Auto development seemed to work fine initially, but after completing the AVP and and Cargo Delivery ODD projects, we started to see the following issues:

  • The barrier to new engineers was too high.
    • A lot of work was required to merge new features into Autoware.Auto, and so it was difficult for researchers and students to contribute to development.
    • As a consequence, most Autoware.Auto developers were from companies in the Autoware Foundation and so there were very few people who were able to add state-of-the-art features from research papers.
  • Making large-scale architecture changes was too difficult.
    • To try out experimental architecture, there was a very large overhead involved in keeping the main branch stable whilst also making sure that every change satisfied the continuous integration requirements.
"},{"location":"design/autoware-concepts/difference-from-ai-and-auto/#autoware-coreuniverse","title":"Autoware Core/Universe","text":"

In order to address the issues with Autoware.Auto development, the Autoware Foundation decided to create a new architecture called Autoware Core/Universe.

Autoware Core carries over the original policy of Autoware.Auto to be a stable and well-tested codebase. Alongside Autoware Core is a new concept called Autoware Universe, which acts as an extension of Autoware Core with the following benefits:

  • Users can easily replace a Core component with a Universe equivalent in order to use more advanced features, such as a new Localization or Perception algorithm.
  • Code quality requirements for Universe are more relaxed to make it easier for new developers, students and researchers to contribute, but will still be stricter than the requirements for Autoware.AI.
  • Any advanced features added to Universe that are useful to the wider Autoware community will be reviewed and considered for potential inclusion in the main Autoware Core codebase.

This way, the primary requirement of having a stable and safe autonomous driving system can be achieved, whilst simultaneously enabling access to state-of-the-art features created by third-party contributors. For more details about the design of Autoware Core/Universe, refer to the Autoware concepts documentation page.

"},{"location":"design/autoware-interfaces/","title":"Autoware interface design","text":""},{"location":"design/autoware-interfaces/#autoware-interface-design","title":"Autoware interface design","text":""},{"location":"design/autoware-interfaces/#abstract","title":"Abstract","text":"

Autoware defines three categories of interfaces. The first one is Autoware AD API for operating the vehicle from outside the autonomous driving system such as the Fleet Management System (FMS) and Human Machine Interface (HMI) for operators or passengers. The second one is Autoware component interface for components to communicate with each other. The last one is the local interface used inside the component.

"},{"location":"design/autoware-interfaces/#concept","title":"Concept","text":"

  • Applications can operate multiple and various vehicles in a common way.

  • Applications are not affected by version updates and implementation changes.

  • Developers only need to know the interface to add new features and hardware.

"},{"location":"design/autoware-interfaces/#requirements","title":"Requirements","text":"

Goals:

  • AD API provides functionality to create the following applications:
    • Drive the vehicle on the route or drive to the requested positions in order.
    • Operate vehicle behavior such as starting and stopping.
    • Display or announce the vehicle status to operators, passengers, and people around.
    • Control vehicle devices such as doors.
    • Monitor the vehicle or drive it manually.
  • AD API provides stable and long-term specifications. This enables unified access to all vehicles.
  • AD API hides differences in version and implementation and absorbs the impact of changes.
  • AD API has a default implementation and can be applied to some simple ODDs with options.
  • The AD API implementation is extensible with the third-party components as long as it meets the specifications.
  • The component interface provides stable and medium-term specifications. This makes it easier to add components.
  • The component interface clarifies the public and private parts of a component and improves maintainability.
  • The component interface is extensible with the third-party design to improve the sub-components' reusability.

Non-goals:

  • AD API does not cover security. Use it with other reliable methods.
  • The component interface is just a specification, it does not include an implementation.
"},{"location":"design/autoware-interfaces/#architecture","title":"Architecture","text":"

The components of Autoware are connected via the component interface. Each component uses the interface to provide functionality and to access other components. AD API implementation is also a component. Since the functional elements required for AD API are defined as the component interface, other components do not need to consider AD API directly. Tools for evaluation and debugging, such as simulators, access both AD API and the component interface.

The component interface has a hierarchical specification. The top-level architecture consists of some components. Each component has some options of the next-level architecture. Developers select one of them when implementing the component. The simplest next-level architecture is monolithic. This is an all-in-one and black box implementation, and is suitable for small group development, prototyping, and very complex functions. Others are arbitrary architecture consists of sub-components and have advantages for large group development. A sub-component can be combined with others that adopt the same architecture. Third parties can define and publish their own architecture and interface for open source development. It is desirable to propose them for standardization if they are sufficiently evaluated.

"},{"location":"design/autoware-interfaces/#features","title":"Features","text":""},{"location":"design/autoware-interfaces/#communication-methods","title":"Communication methods","text":"

As shown in the table below, interfaces are classified into four communication methods to define their behavior. Function Call is a request-response communication and is used for processing that requires immediate results. The others are publish-subscribe communication. Notification is used to process data that changes with some event, typically a callback. Streams handle continuously changing data. Reliable Stream expects all data to arrive without loss, Realtime Stream expects the latest data to arrive with low delay.

Communication Method ROS Implementation Optional Implementation Function Call Service HTTP Notification Topic (reliable, transient_local) MQTT (QoS=2, retain) Reliable Stream Topic (reliable, volatile) MQTT (QoS=2) Realtime Stream Topic (best_effort, volatile) MQTT (QoS=0)

These methods are provided as services or topics of ROS since Autoware is developed using ROS and mainly communicates with its packages. On the other hand, FMS and HMI are often implemented without ROS, Autoware is also expected to communicate with applications that do not use ROS. It is wasteful for each of these applications to have an adapter for Autoware, and a more suitable means of communication is required. HTTP and MQTT are suggested as additional options because these protocols are widely used and can substitute the behavior of services and topics. In that case, text formats such as JSON where field names are repeated in an array of objects, are inefficient and it is necessary to consider the serialization.

"},{"location":"design/autoware-interfaces/#naming-convention","title":"Naming convention","text":"

The name of the interface must be /<component name>/api/<interface name>, where <component name> is the name of the component. For an AD API component, omit this part and start with /api. The <interface name> is an arbitrary string separated by slashes. Note that this rule causes a restriction that the namespace api must not be used as a name other than AD API and the component interface.

The following are examples of correct interface names for AD API and the component interface:

  • /api/autoware/state
  • /api/autoware/engage
  • /planning/api/route/set
  • /vehicle/api/status

The following are examples of incorrect interface names for AD API and the component interface:

  • /ad_api/autoware/state
  • /autoware/engage
  • /planning/route/set/api
  • /vehicle/my_api/status
"},{"location":"design/autoware-interfaces/#logging","title":"Logging","text":"

It is recommended to log the interface for analysis of vehicle behavior. If logging is needed, rosbag is available for topics, and use logger in rclcpp or rclpy for services. Typically, create a wrapper for service and client classes that logs when a service is called.

"},{"location":"design/autoware-interfaces/#restrictions","title":"Restrictions","text":"

For each API, consider the restrictions such as following and describe them if necessary.

Services:

  • response time
  • pre-condition
  • post-condition
  • execution order
  • concurrent execution

Topics:

  • recommended delay range
  • maximum delay
  • recommended frequency range
  • minimum frequency
  • default frequency
"},{"location":"design/autoware-interfaces/#data-structure","title":"Data structure","text":""},{"location":"design/autoware-interfaces/#data-type-definition","title":"Data type definition","text":"

Do not share the types in AD API unless they are obviously the same to avoid changes in one API affecting another. Also, implementation-dependent types, including the component interface, should not be used in AD API for the same reason. Use the type in AD API in implementation, or create the same type and copy the data to convert the type.

"},{"location":"design/autoware-interfaces/#constants-and-enumeration","title":"Constants and enumeration","text":"

Since ROS don't support enumeration, use constants instead. The default value of type such as zero and empty string should not be used to detect that a variable is unassigned. Alternatively, assign it a dedicated name to indicate that it is undefined. If one type has multiple enumerations, comment on the correspondence between constants and variables. Do not use enumeration values directly, as assignments are subject to change when the version is updated.

"},{"location":"design/autoware-interfaces/#time-stamp","title":"Time stamp","text":"

Clarify what the timestamp indicates. for example, send time, measurement time, update time, etc. Consider having multiple timestamps if necessary. Use std_msgs/msg/Header when using ROS transform. Also consider whether the header is common to all data, independent for each data, or additional timestamp is required.

"},{"location":"design/autoware-interfaces/#request-header","title":"Request header","text":"

Currently, there is no required header.

"},{"location":"design/autoware-interfaces/#response-status","title":"Response status","text":"

The interfaces whose communication method is Function Call use a common response status to unify the error format. These interfaces should include a variable of ResponseStatus with the name status in the response. See autoware_adapi_v1_msgs/msg/ResponseStatus for details.

"},{"location":"design/autoware-interfaces/#concerns-assumptions-and-limitations","title":"Concerns, assumptions and limitations","text":"
  • The applications use the version information provided by AD API to check compatibility. Unknown versions are also treated as available as long as the major versions match (excluding major version 0). Compatibility between AD API and the component interface is assumed to be maintained by the version management system.
  • If an unintended behavior of AD API is detected, the application should take appropriate action. Autoware tries to keep working as long as possible, but it is not guaranteed to be safe. Safety should be considered for the entire system, including the applications.
"},{"location":"design/autoware-interfaces/ad-api/","title":"AD API","text":""},{"location":"design/autoware-interfaces/ad-api/#ad-api","title":"AD API","text":"

Warning

Under Construction

See here for an overview.

"},{"location":"design/autoware-interfaces/ad-api/list/","title":"List of Autoware AD API","text":""},{"location":"design/autoware-interfaces/ad-api/list/#list-of-autoware-ad-api","title":"List of Autoware AD API","text":"
  • Interface
  • Operation Mode
  • Routing
  • Localization
  • Motion
  • Planning
  • Fail-safe
"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/","title":"Fail-safe API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#fail-safe-api","title":"Fail-safe API","text":"
  • /api/fail_safe/mrm_state
"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#description","title":"Description","text":"

This API manages the behavior related to the abnormality of the vehicle. It provides the state of Request to Intervene (RTI), Minimal Risk Maneuver (MRM) and Minimal Risk Condition (MRC). As shown below, Autoware has the gate to switch between the command during normal operation and the command during abnormal operation. For safety, Autoware switches the operation to MRM when an abnormality is detected. Since the required behavior differs depending on the situation, MRM is implemented in various places as a specific mode in a normal module or as an independent module. The fail-safe module selects the behavior of MRM according to the abnormality and switches the gate output to that command.

"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#states","title":"States","text":"

The MRM state indicates whether MRM is operating. This state also provides success or failure. Generally, MRM will switch to another behavior if it fails.

State Description NONE MRM is not operating. OPERATING MRM is operating because an abnormality has been detected. SUCCEEDED MRM succeeded. The vehicle is in a safe condition. FAILED MRM failed. The vehicle is still in an unsafe condition."},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/#behavior","title":"Behavior","text":"

There is a dependency between MRM behaviors. For example, it switches from a comfortable stop to a emergency stop, but not the other way around. This is service dependent. Autoware supports the following transitions by default.

State Description NONE MRM is not operating or is operating but no special behavior is required. COMFORTABLE_STOP The vehicle will stop quickly with a comfortable deceleration. EMERGENCY_STOP The vehicle will stop immediately with as much deceleration as possible."},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/","title":"Mrm state","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/#apifail_safemrm_state","title":"/api/fail_safe/mrm_state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/MrmState
"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/#description","title":"Description","text":"

Get the MRM state. For details, see the fail-safe.

"},{"location":"design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state/#message","title":"Message","text":"Name Type Description state uint16 The state of MRM operation. behavior uint16 The currently selected behavior of MRM."},{"location":"design/autoware-interfaces/ad-api/list/api/interface/","title":"Interface API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/interface/#interface-api","title":"Interface API","text":"
  • /api/interface/version
"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/#description","title":"Description","text":"

This API provides the interface version of the set of AD APIs. It follows Semantic Versioning in order to provide an intuitive understanding of the changes between versions.

"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/","title":"Version","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#apiinterfaceversion","title":"/api/interface/version","text":"
  • Method: function call
  • Type: autoware_adapi_version_msgs/srv/InterfaceVersion
"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#description","title":"Description","text":"

Get the interface version. The version follows Semantic Versioning.

"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/interface/version/#response","title":"Response","text":"Name Type Description major uint16 major version minor uint16 minor version patch uint16 patch version"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/","title":"Localization API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/localization/#localization-api","title":"Localization API","text":"
  • /api/localization/initialization_state
  • /api/localization/initialize
"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/#description","title":"Description","text":"

This API manages the initialization of localization. Autoware requires a global pose as the initial guess for localization.

"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/#states","title":"States","text":"State Description UNINITIALIZED Localization is not initialized. Waiting for a global pose as the initial guess. INITIALIZING Localization is initializing. INITIALIZED Localization is initialized. Initialization can be requested again if necessary."},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/","title":"Initialization state","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/#apilocalizationinitialization_state","title":"/api/localization/initialization_state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/LocalizationInitializationState
"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/#description","title":"Description","text":"

Get the initialization state of localization. For details, see the localization initialization state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialization_state/#message","title":"Message","text":"Name Type Description state uint16 A value of the localization initialization state."},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/","title":"Initialize","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#apilocalizationinitialize","title":"/api/localization/initialize","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/InitializeLocalization
"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#description","title":"Description","text":"

Request to initialize localization. For details, see the pose state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#request","title":"Request","text":"Name Type Description pose geometry_msgs/msg/PoseWithCovarianceStamped[<=1] A global pose as the initial guess. If omitted, the GNSS pose will be used."},{"location":"design/autoware-interfaces/ad-api/list/api/localization/initialize/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/","title":"Motion API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/motion/#motion-api","title":"Motion API","text":"
  • /api/motion/state
  • /api/motion/accept_start
"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/#description","title":"Description","text":"

This API manages the current behavior of the vehicle. Applications can notify the vehicle behavior to the people around and visualize it for operator and passengers.

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/#states","title":"States","text":"

The motion state manages the stop and start of the vehicle. Once the vehicle has stopped, the state will be STOPPED. After this, when the vehicle tries to start (is still stopped), the state will be STARTING. In this state, calling the start API changes the state to MOVING and the vehicle starts. This mechanism can add processing such as announcements before the vehicle starts. Depending on the configuration, the state may transition directly from STOPPED to MOVING.

State Description STOPPED The vehicle is stopped. STARTING The vehicle is stopped, but is trying to start. MOVING The vehicle is moving. BRAKING (T.B.D.) The vehicle is decelerating strongly."},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/","title":"Accept start","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#apimotionaccept_start","title":"/api/motion/accept_start","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/AcceptStart
"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#description","title":"Description","text":"

Accept the vehicle to start. This API can be used when the motion state is STARTING.

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/accept_start/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/","title":"State","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/#apimotionstate","title":"/api/motion/state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/MotionState
"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/#description","title":"Description","text":"

Get the motion state. For details, see the motion state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/motion/state/#message","title":"Message","text":"Name Type Description state uint16 A value of the motion state."},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/","title":"Operation Mode API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#operation-mode-api","title":"Operation Mode API","text":"
  • /api/operation_mode/state
  • /api/operation_mode/change_to_autonomous
  • /api/operation_mode/change_to_stop
  • /api/operation_mode/change_to_local
  • /api/operation_mode/change_to_remote
  • /api/operation_mode/enable_autoware_control
  • /api/operation_mode/disable_autoware_control
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#description","title":"Description","text":"

As shown below, Autoware assumes that the vehicle interface has two modes, Autoware control and direct control. In direct control mode, the vehicle is operated using devices such as steering and pedals. If the vehicle does not support direct control mode, it is always treated as Autoware control mode. Autoware control mode has four operation modes.

Mode Description Stop Keep the vehicle stopped. Autonomous Autonomously control the vehicle. Local Manually control the vehicle from nearby with some device such as a joystick. Remote Manually control the vehicle from a web application on the cloud.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#states","title":"States","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#autoware-control-flag","title":"Autoware control flag","text":"

The flag is_autoware_control_enabled indicates if the vehicle is controlled by Autoware. The enable and disable APIs can be used if the control can be switched by software. These APIs will always fail if the vehicle does not support mode switching or is switched by hardware.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#operation-mode-and-change-flags","title":"Operation mode and change flags","text":"

The state operation_mode indicates what command is used when Autoware control is enabled. The flags change_to_* can be used to check if it is possible to transition to each mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/#transition-flag","title":"Transition flag","text":"

Since Autoware may not be able to guarantee safety, such as switching to autonomous mode during overspeed. There is the flag is_in_transition for this situation and it will be true when changing modes. The operator who changed the mode should ensure safety while this flag is true. The flag will be false when the mode change is complete.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/","title":"Change to autonomous","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#apioperation_modechange_to_autonomous","title":"/api/operation_mode/change_to_autonomous","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#description","title":"Description","text":"

Change the operation mode to autonomous. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/","title":"Change to local","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#apioperation_modechange_to_local","title":"/api/operation_mode/change_to_local","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#description","title":"Description","text":"

Change the operation mode to local. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/","title":"Change to remote","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#apioperation_modechange_to_remote","title":"/api/operation_mode/change_to_remote","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#description","title":"Description","text":"

Change the operation mode to remote. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/","title":"Change to stop","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#apioperation_modechange_to_stop","title":"/api/operation_mode/change_to_stop","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#description","title":"Description","text":"

Change the operation mode to stop. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/","title":"Disable autoware control","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#apioperation_modedisable_autoware_control","title":"/api/operation_mode/disable_autoware_control","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#description","title":"Description","text":"

Disable vehicle control by Autoware. For details, see the operation mode. This API fails if the vehicle does not support mode change by software.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/","title":"Enable autoware control","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#apioperation_modeenable_autoware_control","title":"/api/operation_mode/enable_autoware_control","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ChangeOperationMode
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#description","title":"Description","text":"

Enable vehicle control by Autoware. For details, see the operation mode. This API fails if the vehicle does not support mode change by software.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/","title":"State","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/#apioperation_modestate","title":"/api/operation_mode/state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/OperationModeState
"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/#description","title":"Description","text":"

Get the operation mode state. For details, see the operation mode.

"},{"location":"design/autoware-interfaces/ad-api/list/api/operation_mode/state/#message","title":"Message","text":"Name Type Description mode uint8 The selected command for Autoware control. is_autoware_control_enabled bool True if vehicle control by Autoware is enabled. is_in_transition bool True if the operation mode is in transition. is_stop_mode_available bool True if the operation mode can be changed to stop. is_autonomous_mode_available bool True if the operation mode can be changed to autonomous. is_local_mode_available bool True if the operation mode can be changed to local. is_remote_mode_available bool True if the operation mode can be changed to remote."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/","title":"Planning API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#planning-api","title":"Planning API","text":"
  • /api/planning/velocity_factors
  • /api/planning/steering_factors
"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#description","title":"Description","text":"

This API manages the planned behavior of the vehicle. Applications can notify the vehicle behavior to the people around and visualize it for operator and passengers.

"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#velocity-factors","title":"Velocity factors","text":"

The velocity factors is an array of information on the behavior that the vehicle stops (or slows down). Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type. As the vehicle approaches the stop position, this factor appears with a status of APPROACHING. And when the vehicle reaches that position and stops, the status will be STOPPED. The pose indicates the stop position or the base link if the stop position cannot be calculated.

Factor Type Description SURROUNDING_OBSTACLE There are obstacles immediately around the vehicle. ROUTE_OBSTACLE There are obstacles along the route ahead. INTERSECTION There are obstacles in other lanes in the path. CROSSWALK There are obstacles on the crosswalk. REAR_CHECK There are obstacles behind that would be in a human driver's blind spot. USER_DEFINED_DETECTION_AREA There are obstacles in the predefined detection area. NO_STOPPING_AREA There is not enough space beyond the no stopping area. STOP_SIGN A stop by a stop sign. TRAFFIC_SIGNAL A stop by a traffic signal. V2I_GATE_CONTROL_ENTER A stop by a V2I gate entering. V2I_GATE_CONTROL_LEAVE A stop by a V2I gate leaving. MERGE A stop before merging lanes. SIDEWALK A stop before crossing the sidewalk. LANE_CHANGE A lane change. AVOIDANCE A path change to avoid an obstacle in the current lane. EMERGENCY_OPERATION A stop by emergency instruction from the operator."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/#steering-factors","title":"Steering factors","text":"

The steering factors is an array of information on the maneuver that requires use of turn indicators, such as turning left or right. Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type. As the vehicle approaches the position to start steering, this factor appears with a status of APPROACHING. And when the vehicle reaches that position, the status will be TURNING. The pose indicates the start position when APPROACHING and the end position when TURNING.

In cases such as lane change and avoidance, the vehicle will start steering at any position in the range depending on the situation. As the vehicle approaches the start position of the range, this factor appears with a status of APPROACHING. And when the vehicle reaches that position, the status will be TRYING. Then, when it is possible, the vehicle will start steering and the status will be TURNING. The pose indicates the start of the range (A) when APPROACHING and the end of the range (B) when TRYING. The position to end steering (C to D) for TURNING depends on the position to start steering.

Factor Type Description INTERSECTION A turning left or right at an intersection. LANE_CHANGE A lane change. AVOIDANCE_PATH_CHANGE A path change to avoid an obstacle in the current lane. AVOIDANCE_PATH_RETURN A path change to return to the original lane after avoiding an obstacle. STATION T.B.D. (bus stop) PULL_OUT T.B.D. PULL_OVER T.B.D. EMERGENCY_OPERATION A path change by emergency instruction from the operator."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/","title":"Steering factors","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/#apiplanningsteering_factors","title":"/api/planning/steering_factors","text":"
  • Method: realtime stream
  • Type: autoware_adapi_v1_msgs/msg/SteeringFactorArray
"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/#description","title":"Description","text":"

Get the steering factors, sorted in ascending order of distance. For details, see the planning.

"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/steering_factors/#message","title":"Message","text":"Name Type Description factors.pose geometry_msgs/msg/Pose[2] The base link pose related to the steering factor. factors.distance float32[2] The distance from the base link to the above pose. factors.type uint16 The type of the steering factor. factors.direction uint16 The direction of the steering factor. factors.status uint16 The status of the steering factor. factors.detail string The additional information of the steering factor."},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/","title":"Velocity factors","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/#apiplanningvelocity_factors","title":"/api/planning/velocity_factors","text":"
  • Method: realtime stream
  • Type: autoware_adapi_v1_msgs/msg/VelocityFactorArray
"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/#description","title":"Description","text":"

Get the velocity factors, sorted in ascending order of distance. For details, see the planning.

"},{"location":"design/autoware-interfaces/ad-api/list/api/planning/velocity_factors/#message","title":"Message","text":"Name Type Description factors.pose geometry_msgs/msg/Pose The base link pose related to the velocity factor. factors.distance float32 The distance from the base link to the above pose. factors.type uint16 The type of the velocity factor. factors.status uint16 The status of the velocity factor. factors.detail string The additional information of the velocity factor."},{"location":"design/autoware-interfaces/ad-api/list/api/routing/","title":"Route API","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/#route-api","title":"Route API","text":"
  • /api/routing/state
  • /api/routing/route
  • /api/routing/set_route_points
  • /api/routing/set_route
  • /api/routing/clear_route
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/#description","title":"Description","text":"

This API manages destination and waypoints. Note that waypoints are not like stops and just points passing through. In other words, Autoware does not support the route with multiple stops, the application needs to split it up and switch them. There are two ways to set the route. The one is a generic method that uses pose, another is a map-dependent.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/#states","title":"States","text":"State Description UNSET The route is not set. Waiting for a route request. SET The route is set. ARRIVED The vehicle has arrived at the destination. CHANGING Trying to change the route. Not implemented yet."},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/","title":"Clear route","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#apiroutingclear_route","title":"/api/routing/clear_route","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/ClearRoute
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#description","title":"Description","text":"

Clear the route.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#request","title":"Request","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/clear_route/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/","title":"Route","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/#apiroutingroute","title":"/api/routing/route","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/Route
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/#description","title":"Description","text":"

Get the route with the waypoint segments in lanelet format. It is empty if route is not set.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/route/#message","title":"Message","text":"Name Type Description header std_msgs/msg/Header header for pose transformation data autoware_adapi_v1_msgs/msg/RouteData[<=1] The route in lanelet format"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/","title":"Set route","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#apiroutingset_route","title":"/api/routing/set_route","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/SetRoute
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#description","title":"Description","text":"

Set the route with the waypoint segments in lanelet format. If start pose is not specified, the current pose will be used.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#request","title":"Request","text":"Name Type Description header std_msgs/msg/Header header for pose transformation goal geometry_msgs/msg/Pose goal pose segments autoware_adapi_v1_msgs/msg/RouteSegment[] waypoint segments in lanelet format"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/","title":"Set route points","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#apiroutingset_route_points","title":"/api/routing/set_route_points","text":"
  • Method: function call
  • Type: autoware_adapi_v1_msgs/srv/SetRoutePoints
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#description","title":"Description","text":"

Set the route with the waypoint poses. If start pose is not specified, the current pose will be used.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#request","title":"Request","text":"Name Type Description header std_msgs/msg/Header header for pose transformation goal geometry_msgs/msg/Pose goal pose waypoints geometry_msgs/msg/Pose[] waypoint poses"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/set_route_points/#response","title":"Response","text":"Name Type Description status autoware_adapi_v1_msgs/msg/ResponseStatus response status"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/","title":"State","text":""},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/#apiroutingstate","title":"/api/routing/state","text":"
  • Method: notification
  • Type: autoware_adapi_v1_msgs/msg/RouteState
"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/#description","title":"Description","text":"

Get the route state. For details, see the route state.

"},{"location":"design/autoware-interfaces/ad-api/list/api/routing/state/#message","title":"Message","text":"Name Type Description state uint16 A value of the route state."},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/","title":"Localization initialization state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#autoware_adapi_v1_msgsmsglocalizationinitializationstate","title":"autoware_adapi_v1_msgs/msg/LocalizationInitializationState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#definition","title":"Definition","text":"
uint16 UNKNOWN = 0\nuint16 UNINITIALIZED = 1\nuint16 INITIALIZING = 2\nuint16 INITIALIZED = 3\n\nbuiltin_interfaces/Time stamp\nuint16 state\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/localization_initialization_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/","title":"Motion state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#autoware_adapi_v1_msgsmsgmotionstate","title":"autoware_adapi_v1_msgs/msg/MotionState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#definition","title":"Definition","text":"
uint16 UNKNOWN = 0\nuint16 STOPPED = 1\nuint16 STARTING = 2\nuint16 MOVING = 3\n\nbuiltin_interfaces/Time stamp\nuint16 state\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/motion_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/","title":"Mrm state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#autoware_adapi_v1_msgsmsgmrmstate","title":"autoware_adapi_v1_msgs/msg/MrmState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#definition","title":"Definition","text":"
builtin_interfaces/Time stamp\n\n# For common use\nuint16 UNKNOWN = 0\n\n# For state\nuint16 NORMAL = 1\nuint16 MRM_OPERATING = 2\nuint16 MRM_SUCCEEDED = 3\nuint16 MRM_FAILED = 4\n\n# For behavior\nuint16 NONE = 1\nuint16 EMERGENCY_STOP = 2\nuint16 COMFORTABLE_STOP = 3\n\nuint16 state\nuint16 behavior\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/mrm_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/","title":"Operation mode state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#autoware_adapi_v1_msgsmsgoperationmodestate","title":"autoware_adapi_v1_msgs/msg/OperationModeState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#definition","title":"Definition","text":"
# constants for mode\nuint8 UNKNOWN = 0\nuint8 STOP = 1\nuint8 AUTONOMOUS = 2\nuint8 LOCAL = 3\nuint8 REMOTE = 4\n\n# variables\nbuiltin_interfaces/Time stamp\nuint8 mode\nbool is_autoware_control_enabled\nbool is_in_transition\nbool is_stop_mode_available\nbool is_autonomous_mode_available\nbool is_local_mode_available\nbool is_remote_mode_available\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/operation_mode_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/","title":"Response status","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#autoware_adapi_v1_msgsmsgresponsestatus","title":"autoware_adapi_v1_msgs/msg/ResponseStatus","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#definition","title":"Definition","text":"
# error code\nuint16 UNKNOWN = 50000\nuint16 SERVICE_UNREADY = 50001\nuint16 SERVICE_TIMEOUT = 50002\nuint16 TRANSFORM_ERROR = 50003\nuint16 PARAMETER_ERROR = 50004\n\n# warning code\nuint16 DEPRECATED = 60000\nuint16 NO_EFFECT = 60001\n\n# variables\nbool   success\nuint16 code\nstring message\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/response_status/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/srv/AcceptStart
  • autoware_adapi_v1_msgs/srv/ChangeOperationMode
  • autoware_adapi_v1_msgs/srv/ClearRoute
  • autoware_adapi_v1_msgs/srv/InitializeLocalization
  • autoware_adapi_v1_msgs/srv/SetRoute
  • autoware_adapi_v1_msgs/srv/SetRoutePoints
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/","title":"Route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#autoware_adapi_v1_msgsmsgroute","title":"autoware_adapi_v1_msgs/msg/Route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#definition","title":"Definition","text":"
std_msgs/Header header\nautoware_adapi_v1_msgs/RouteData[<=1] data\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/RouteData
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/","title":"Route data","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#autoware_adapi_v1_msgsmsgroutedata","title":"autoware_adapi_v1_msgs/msg/RouteData","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#definition","title":"Definition","text":"
geometry_msgs/Pose start\ngeometry_msgs/Pose goal\nautoware_adapi_v1_msgs/RouteSegment[] segments\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/RouteSegment
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_data/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/Route
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/","title":"Route primitive","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#autoware_adapi_v1_msgsmsgrouteprimitive","title":"autoware_adapi_v1_msgs/msg/RoutePrimitive","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#definition","title":"Definition","text":"
int64 id\nstring type  # The same id may be used for each type.\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_primitive/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/RouteSegment
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/","title":"Route segment","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#autoware_adapi_v1_msgsmsgroutesegment","title":"autoware_adapi_v1_msgs/msg/RouteSegment","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#definition","title":"Definition","text":"
autoware_adapi_v1_msgs/RoutePrimitive   preferred\nautoware_adapi_v1_msgs/RoutePrimitive[] alternatives  # Does not include the preferred primitive.\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/RoutePrimitive
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_segment/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/RouteData
  • autoware_adapi_v1_msgs/srv/SetRoute
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/","title":"Route state","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#autoware_adapi_v1_msgsmsgroutestate","title":"autoware_adapi_v1_msgs/msg/RouteState","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#definition","title":"Definition","text":"
uint16 UNKNOWN = 0\nuint16 UNSET = 1\nuint16 SET = 2\nuint16 ARRIVED = 3\nuint16 CHANGING = 4\n\nbuiltin_interfaces/Time stamp\nuint16 state\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/route_state/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/","title":"Steering factor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#autoware_adapi_v1_msgsmsgsteeringfactor","title":"autoware_adapi_v1_msgs/msg/SteeringFactor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#definition","title":"Definition","text":"
# constants for common use\nuint16 UNKNOWN = 0\n\n# constants for type\nuint16 INTERSECTION = 1\nuint16 LANE_CHANGE = 2\nuint16 AVOIDANCE_PATH_CHANGE = 3\nuint16 AVOIDANCE_PATH_RETURN = 4\nuint16 STATION = 5\nuint16 PULL_OUT = 6\nuint16 PULL_OVER = 7\nuint16 EMERGENCY_OPERATION = 8\n\n# constants for direction\nuint16 LEFT = 1\nuint16 RIGHT = 2\nuint16 STRAIGHT = 3\n\n# constants for status\nuint16 APPROACHING = 1\nuint16 TRYING = 2\nuint16 TURNING = 3\n\n# variables\ngeometry_msgs/Pose[2] pose\nfloat32[2] distance\nuint16 type\nuint16 direction\nuint16 status\nstring detail\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/SteeringFactorArray
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/","title":"Steering factor array","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#autoware_adapi_v1_msgsmsgsteeringfactorarray","title":"autoware_adapi_v1_msgs/msg/SteeringFactorArray","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#definition","title":"Definition","text":"
std_msgs/Header header\nautoware_adapi_v1_msgs/SteeringFactor[] factors\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/SteeringFactor
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/steering_factor_array/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/","title":"Velocity factor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#autoware_adapi_v1_msgsmsgvelocityfactor","title":"autoware_adapi_v1_msgs/msg/VelocityFactor","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#definition","title":"Definition","text":"
# constants for common use\nuint16 UNKNOWN = 0\n\n# constants for type\nuint16 SURROUNDING_OBSTACLE = 1\nuint16 ROUTE_OBSTACLE = 2\nuint16 INTERSECTION = 3\nuint16 CROSSWALK = 4\nuint16 REAR_CHECK = 5\nuint16 USER_DEFINED_DETECTION_AREA = 6\nuint16 NO_STOPPING_AREA = 7\nuint16 STOP_SIGN = 8\nuint16 TRAFFIC_SIGNAL = 9\nuint16 V2I_GATE_CONTROL_ENTER = 10\nuint16 V2I_GATE_CONTROL_LEAVE = 11\nuint16 MERGE = 12\nuint16 SIDEWALK = 13\nuint16 LANE_CHANGE = 14\nuint16 AVOIDANCE = 15\nuint16 EMERGENCY_STOP_OPERATION = 16\n\n# constants for status\nuint16 APPROACHING = 1\nuint16 STOPPED = 2\n\n# variables\ngeometry_msgs/Pose pose\nfloat32 distance\nuint16 type\nuint16 status\nstring detail\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor/#this-type-is-used-by","title":"This type is used by","text":"
  • autoware_adapi_v1_msgs/msg/VelocityFactorArray
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/","title":"Velocity factor array","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#autoware_adapi_v1_msgsmsgvelocityfactorarray","title":"autoware_adapi_v1_msgs/msg/VelocityFactorArray","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#definition","title":"Definition","text":"
std_msgs/Header header\nautoware_adapi_v1_msgs/VelocityFactor[] factors\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/VelocityFactor
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/velocity_factor_array/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/","title":"Accept start","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#autoware_adapi_v1_msgssrvacceptstart","title":"autoware_adapi_v1_msgs/srv/AcceptStart","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#definition","title":"Definition","text":"
---\nuint16 ERROR_NOT_STARTING = 1\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/accept_start/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/","title":"Change operation mode","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#autoware_adapi_v1_msgssrvchangeoperationmode","title":"autoware_adapi_v1_msgs/srv/ChangeOperationMode","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#definition","title":"Definition","text":"
---\nuint16 ERROR_NOT_AVAILABLE = 1\nuint16 ERROR_IN_TRANSITION = 2\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/change_operation_mode/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/","title":"Clear route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#autoware_adapi_v1_msgssrvclearroute","title":"autoware_adapi_v1_msgs/srv/ClearRoute","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#definition","title":"Definition","text":"
---\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/clear_route/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/","title":"Initialize localization","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#autoware_adapi_v1_msgssrvinitializelocalization","title":"autoware_adapi_v1_msgs/srv/InitializeLocalization","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#definition","title":"Definition","text":"
geometry_msgs/PoseWithCovarianceStamped[<=1] pose\n---\nuint16 ERROR_UNSAFE = 1\nuint16 ERROR_GNSS_SUPPORT = 2\nuint16 ERROR_GNSS = 3\nuint16 ERROR_ESTIMATION = 4\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/initialize_localization/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/","title":"Set route","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#autoware_adapi_v1_msgssrvsetroute","title":"autoware_adapi_v1_msgs/srv/SetRoute","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#definition","title":"Definition","text":"
std_msgs/Header header\ngeometry_msgs/Pose goal\nautoware_adapi_v1_msgs/RouteSegment[] segments\n---\nuint16 ERROR_ROUTE_EXISTS = 1\nuint16 ERROR_PLANNER_UNREADY = 2\nuint16 ERROR_PLANNER_FAILED = 3\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
  • autoware_adapi_v1_msgs/msg/RouteSegment
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/","title":"Set route points","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#autoware_adapi_v1_msgssrvsetroutepoints","title":"autoware_adapi_v1_msgs/srv/SetRoutePoints","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#definition","title":"Definition","text":"
std_msgs/Header header\ngeometry_msgs/Pose goal\ngeometry_msgs/Pose[] waypoints\n---\nuint16 ERROR_ROUTE_EXISTS = 1\nuint16 ERROR_PLANNER_UNREADY = 2\nuint16 ERROR_PLANNER_FAILED = 3\nautoware_adapi_v1_msgs/ResponseStatus status\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#this-type-uses","title":"This type uses","text":"
  • autoware_adapi_v1_msgs/msg/ResponseStatus
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/set_route_points/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/","title":"Interface version","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#autoware_adapi_version_msgssrvinterfaceversion","title":"autoware_adapi_version_msgs/srv/InterfaceVersion","text":""},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#definition","title":"Definition","text":"
---\nuint16 major\nuint16 minor\nuint16 patch\n
"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#this-type-uses","title":"This type uses","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/interface_version/#this-type-is-used-by","title":"This type is used by","text":"

None

"},{"location":"design/autoware-interfaces/ad-api/use-cases/","title":"Use cases of Autoware AD API","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/#use-cases-of-autoware-ad-api","title":"Use cases of Autoware AD API","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/#user-stories","title":"User stories","text":"

The user stories are service scenarios that AD API assumes. AD API is designed based on these scenarios. Each scenario is realized by a combination of use cases described later. If there are scenarios that cannot be covered, please discuss adding a user story.

  • Bus service
  • Taxi service
"},{"location":"design/autoware-interfaces/ad-api/use-cases/#use-cases","title":"Use cases","text":"

Use cases are partial scenarios derived from the user story and generically designed. Service providers can combine these use cases to define user stories and check if AD API can be applied to their own scenarios.

  • Launch and terminate
  • Initialize the pose
  • Change the operation mode
  • Drive to the designated position
  • Get on and get off
"},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/#user-story-of-bus-service","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/#overview","title":"Overview","text":"

This user story is a bus service that goes around the designated stops.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/bus-service/#scenario","title":"Scenario","text":"Step Operation Use Case 1 Startup the autonomous driving system. Launch and terminate 2 Drive the vehicle from the garage to the waiting position. Change the operation mode 3 Enable autonomous control. Change the operation mode 4 Drive the vehicle to the next bus stop. Drive to the designated position 5 Get on and off the vehicle. Get on and get off 6 Return to step 4 unless it's the last bus stop. 7 Drive the vehicle to the waiting position. Drive to the designated position 8 Drive the vehicle from the waiting position to the garage. Change the operation mode 9 Shutdown the autonomous driving system. Launch and terminate"},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/","title":"Change the operation mode","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/#change-the-operation-mode","title":"Change the operation mode","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/#related-api","title":"Related API","text":"
  • Operation mode
"},{"location":"design/autoware-interfaces/ad-api/use-cases/change-operation-mode/#sequence","title":"Sequence","text":"

  • Change the mode with software switch.

  • Change the mode with hardware switch.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/","title":"Drive to the designated position","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/#drive-to-the-designated-position","title":"Drive to the designated position","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/#related-api","title":"Related API","text":"
  • Driving
  • Route
"},{"location":"design/autoware-interfaces/ad-api/use-cases/drive-designated-position/#sequence","title":"Sequence","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/","title":"Get on and get off","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/#get-on-and-get-off","title":"Get on and get off","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/#related-api","title":"Related API","text":"
  • Door
"},{"location":"design/autoware-interfaces/ad-api/use-cases/get-on-off/#sequence","title":"Sequence","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/","title":"Initialize the pose","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/#initialize-the-pose","title":"Initialize the pose","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/#related-api","title":"Related API","text":"
  • Pose
"},{"location":"design/autoware-interfaces/ad-api/use-cases/initialize-pose/#sequence","title":"Sequence","text":"

  • Initialization of the pose using input.

  • Initialization of the pose using GNSS.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/","title":"Launch and terminate","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/#launch-and-terminate","title":"Launch and terminate","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/#related-api","title":"Related API","text":"
  • Interface
  • Launcher
"},{"location":"design/autoware-interfaces/ad-api/use-cases/launch-terminate/#sequence","title":"Sequence","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/#user-story-of-bus-service","title":"User story of bus service","text":""},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/#overview","title":"Overview","text":"

This user story is a taxi service that picks up passengers and drives them to their destination.

"},{"location":"design/autoware-interfaces/ad-api/use-cases/taxi-service/#scenario","title":"Scenario","text":"Step Operation Use Case 1 Startup the autonomous driving system. Launch and terminate 2 Drive the vehicle from the garage to the waiting position. Change the operation mode 3 Enable autonomous control. Change the operation mode 4 Drive the vehicle to the position to pick up. Drive to the designated position 5 Get on the vehicle. Get on and get off 6 Drive the vehicle to the destination. Drive to the designated position 7 Get off the vehicle. Get on and get off 8 Drive the vehicle to the waiting position. Drive to the designated position 9 Return to step 4 if there is another request. 10 Drive the vehicle from the waiting position to the garage. Change the operation mode 11 Shutdown the autonomous driving system. Launch and terminate"},{"location":"design/autoware-interfaces/components/","title":"Component interfaces","text":""},{"location":"design/autoware-interfaces/components/#component-interfaces","title":"Component interfaces","text":"

Warning

Under Construction

See here for an overview.

"},{"location":"design/autoware-interfaces/components/control/","title":"Control","text":""},{"location":"design/autoware-interfaces/components/control/#control","title":"Control","text":""},{"location":"design/autoware-interfaces/components/control/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/control/#vehicle-kinematic-state","title":"Vehicle kinematic state","text":"

Current position and orientation of ego. Published by the Localization module.

  • nav_msgs/Odometry
    • std_msgs/Header header
    • string child_frame_id
    • geometry_msgs/PoseWithCovariance pose
    • geometry_msgs/TwistWithCovariance twist
"},{"location":"design/autoware-interfaces/components/control/#trajectory","title":"Trajectory","text":"

trajectory to be followed by the controller. See Outputs of Planning.

"},{"location":"design/autoware-interfaces/components/control/#steering-status","title":"Steering Status","text":"

Current steering of the ego vehicle. Published by the Vehicle Interface.

  • Steering message (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 steering_angle
"},{"location":"design/autoware-interfaces/components/control/#actuation-status","title":"Actuation Status","text":"

Actuation status of the ego vehicle for acceleration, steering, and brake.

TODO This represents the reported physical efforts exerted by the vehicle actuators. Published by the Vehicle Interface.

  • ActuationStatus (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 acceleration
    • float32 steering
"},{"location":"design/autoware-interfaces/components/control/#output","title":"Output","text":""},{"location":"design/autoware-interfaces/components/control/#vehicle-control-command","title":"Vehicle Control Command","text":"

A motion signal to drive the vehicle, achieved by the low-level controller in the vehicle layer. Used by the Vehicle Interface.

  • autoware_auto_control_msgs/AckermannControlCommand
    • builtin_interfaces::msg::Time stamp
    • autoware_auto_control_msgs/AckermannLateralCommand lateral
      • builtin_interfaces::msg::Time stamp
      • float steering_tire_angle
      • float steering_tire_rotation_rate
    • autoware_auto_control_msgs/LongitudinalCommand longitudinal
      • builtin_interfaces::msg::Time stamp
      • builtin_interfaces::msg::Duration duration
      • builtin_interfaces::msg::Duration time_step
      • float[] speeds
      • float[] accelerations
      • float[] jerks
"},{"location":"design/autoware-interfaces/components/localization/","title":"Localization","text":""},{"location":"design/autoware-interfaces/components/localization/#localization","title":"Localization","text":""},{"location":"design/autoware-interfaces/components/localization/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/localization/#pointcloud-map","title":"Pointcloud Map","text":"

Environment map created with point cloud, published by the map server.

  • sensor_msgs/msg/PointCloud2

A 3d point cloud map is used for LiDAR-based localization in Autoware.

"},{"location":"design/autoware-interfaces/components/localization/#manual-initial-pose","title":"Manual Initial Pose","text":"

Start pose of ego, published by the user interface.

  • geometry_msgs/msg/PoseWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msgs/msg/PoseWithCovariance pose
      • geometry_msgs/msg/Pose pose
        • geometry_msgs/msg/Point position
        • geometry_msg/msg/Quaternion orientation
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#3d-lidar-scanning","title":"3D-LiDAR Scanning","text":"

LiDAR scanning for NDT matching, published by the LiDAR sensor.

  • sensor_msgs/msg/PointCloud2

The raw 3D-LiDAR data needs to be processed by the point cloud pre-processing modules before being used for localization.

"},{"location":"design/autoware-interfaces/components/localization/#automatic-initial-pose","title":"Automatic Initial pose","text":"

Start pose of ego, calculated from INS(Inertial navigation sensor) sensing data.

  • geometry_msgs/msg/PoseWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msgs/msg/PoseWithCovariance pose
      • geometry_msgs/msg/Pose pose
        • geometry_msgs/msg/Point position
        • geometry_msg/msg/Quaternion orientation
      • double[36] covariance

When the initial pose is not set manually, the message can be used for automatic pose initialization.

Current Geographic coordinate of the ego, published by the GNSS sensor.

  • sensor_msgs/msg/NavSatFix
    • std_msgs/msg/Header header
    • sensor_msgs/msg/NavSatStatus status
    • double latitude
    • double longitude
    • double altitude
    • double[9] position_covariance
    • unit8 position_covariance_type

Current orientation of the ego, published by the GNSS-INS.

  • autoware_sensing_msgs/msg/GnssInsOrientationStamped
    • std_msgs/Header header
    • autoware_sensing_msgs/msg/GnssInsOrientation orientation
      • geometry_msgs/Quaternion orientation
      • float32 rmse_rotation_x
      • float32 rmse_rotation_y
      • float32 rmse_rotation_z
"},{"location":"design/autoware-interfaces/components/localization/#imu-data","title":"IMU Data","text":"

Current orientation, angular velocity and linear acceleration of ego, calculated from IMU sensing data.

  • sensor_msgs/msg/Imu
    • std_msgs/msg/Header header
    • geometry_msgs/msg/Quaternion orientation
    • double[9] orientation_covariance
    • geometry_msgs/msg/Vector3 angular_velocity
    • double[9] angular_velocity_covariance
    • geometry_msgs/msg/Vector3 linear_acceleration
    • double[9] linear_acceleration_covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-velocity-status","title":"Vehicle Velocity Status","text":"

Current velocity of the ego vehicle, published by the vehicle interface.

  • autoware_auto_vehicle_msgs/msg/VelocityReport
    • std_msgs/msg/Header header;
    • float longitudinal_velocity;
    • float lateral_velocity;
    • float heading_rate;

Before the velocity input localization interface, module vehicle_velocity_converter converts message type autoware_auto_vehicle_msgs/msg/VelocityReport to geometry_msgs/msg/TwistWithCovarianceStamped.

"},{"location":"design/autoware-interfaces/components/localization/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/localization/#vehicle-pose","title":"Vehicle pose","text":"

Current pose of ego, calculated from localization interface.

  • geometry_msgs/msg/PoseWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msg/PoseWithCovariance pose
      • geometry_msgs/msg/Pose pose
        • geometry_msgs/msg/Point position
        • geometry_msgs/msg/Quaternion orientation
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-velocity","title":"Vehicle velocity","text":"

Current velocity of ego, calculated from localization interface.

  • geometry_msgs/msg/TwistWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msg/TwistWithCovariance twist
      • geometry_msgs/msg/Twist twist
        • geometry_msgs/msg/Vector3 linear
        • geometry_msgs/msg/Vector3 angular
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-acceleration","title":"Vehicle acceleration","text":"

Current acceleration of ego, calculated from localization interface.

  • geometry_msgs/msg/AccelWithCovarianceStamped
    • std_msgs/msg/Header header
    • geometry_msg/AccelWithCovariance accel
      • geometry_msgs/msg/Accel accel
        • geometry_msgs/msg/Vector3 linear
        • geometry_msgs/msg/Vector3 angular
      • double[36] covariance
"},{"location":"design/autoware-interfaces/components/localization/#vehicle-kinematic-state","title":"Vehicle kinematic state","text":"

Current pose, velocity and acceleration of ego, calculated from localization interface.

Note: Kinematic state contains pose, velocity and acceleration. In the future, pose, velocity and acceleration will not be used as output for localization.

  • autoware_msgs/autoware_localization_msgs/msg/KinematicState
    • std_msgs/msg/Header header
    • string child_frame_id
    • geometry_msgs/PoseWithCovariance pose_with_covariance
    • geometry_msgs/TwistWithCovariance twist_with_covariance
    • geometry_msgs/AccelWithCovariance accel_with_covariance

The message will be subscribed by the planning and control module.

"},{"location":"design/autoware-interfaces/components/localization/#localization-accuracy","title":"Localization Accuracy","text":"

Diagnostics information that indicates if the localization module works properly.

TBD.

"},{"location":"design/autoware-interfaces/components/map/","title":"Map","text":""},{"location":"design/autoware-interfaces/components/map/#map","title":"Map","text":""},{"location":"design/autoware-interfaces/components/map/#overview","title":"Overview","text":"

Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks. Before launching Autoware, you need to load the pre-created map files.

"},{"location":"design/autoware-interfaces/components/map/#inputs","title":"Inputs","text":"
  • Point cloud maps (.pcd)
  • Lanelet2 maps (.osm)

Refer to Creating maps on how to create maps.

"},{"location":"design/autoware-interfaces/components/map/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/map/#point-cloud-map","title":"Point cloud map","text":"

It loads point cloud files and publishes the maps to the other Autoware nodes in various configurations. Currently, it supports the following types:

  • Raw point cloud map (sensor_msgs/msg/PointCloud2)
  • Downsampled point cloud map (sensor_msgs/msg/PointCloud2)
  • Partial point cloud map loading via ROS service (autoware_map_msgs/srv/GetPartialPointCloudMap)
  • Differential point cloud map loading via ROS service (autoware_map_msgs/srv/GetDifferentialPointCloudMap)
"},{"location":"design/autoware-interfaces/components/map/#lanelet2-map","title":"Lanelet2 map","text":"

It loads a Lanelet2 file and publishes the map data as autoware_auto_mapping_msgs/msg/HADMapBin message. The lan/lon coordinates are projected onto the MGRS coordinates.

  • autoware_auto_mapping_msgs/msg/HADMapBin
    • std_msgs/Header header
    • string version_map_format
    • string version_map
    • string name_map
    • uint8[] data
"},{"location":"design/autoware-interfaces/components/map/#lanelet2-map-visualization","title":"Lanelet2 map visualization","text":"

Visualize autoware_auto_mapping_msgs/HADMapBin messages in Rviz.

  • visualization_msgs/msg/MarkerArray
"},{"location":"design/autoware-interfaces/components/perception/","title":"Perception","text":""},{"location":"design/autoware-interfaces/components/perception/#perception","title":"Perception","text":"

Warning

Under Construction

This page provides specific specifications about the Interface of the Perception Component. Please refer to the perception architecture reference implementation design document for concepts and data flow.

"},{"location":"design/autoware-interfaces/components/perception/#input","title":"Input","text":""},{"location":"design/autoware-interfaces/components/perception/#from-map-component","title":"From Map Component","text":"Name Topic / Service Type Description Vector Map /map/vector_map autoware_auto_mapping_msgs/msg/HADMapBin HD Map including the information about lanes Point Cloud Map /service/get_differential_pcd_map autoware_map_msgs/srv/GetDifferentialPointCloudMap Point Cloud Map

Notes:

  • Point Cloud Map
    • input can be both topic or service, but we highly recommend to use service because since this interface enables processing without being constrained by map file size limits.
"},{"location":"design/autoware-interfaces/components/perception/#from-sensing-component","title":"From Sensing Component","text":"Name Topic Type Description Camera Image /sensing/camera/camera*/image_rect_color sensor_msgs/Image Camera image data, processed with Lens Distortion Correction (LDC) Camera Image /sensing/camera/camera*/image_raw sensor_msgs/Image Camera image data, not processed with Lens Distortion Correction (LDC) Point Cloud /sensing/lidar/concatenated/pointcloud sensor_msgs/PointCloud2 Concatenated point cloud from multiple LiDAR sources Radar Object /sensing/radar/detected_objects autoware_auto_perception_msgs/msg/DetectedObject Radar objects"},{"location":"design/autoware-interfaces/components/perception/#from-localization-component","title":"From Localization Component","text":"Name Topic Type Description Vehicle Odometry /localization/kinematic_state nav_msgs/msg/Odometry Ego vehicle odometry topic"},{"location":"design/autoware-interfaces/components/perception/#from-api","title":"From API","text":"Name Topic Type Description External Traffic Signals /external/traffic_signals autoware_perception_msgs::msg::TrafficSignalArray The traffic signals from an external system"},{"location":"design/autoware-interfaces/components/perception/#output","title":"Output","text":""},{"location":"design/autoware-interfaces/components/perception/#to-planning","title":"To Planning","text":"Name Topic Type Description Dynamic Objects /perception/object_recognition/objects autoware_auto_perception_msgs/msg/PredictedObjects Set of dynamic objects with information such as a object class and a shape of the objects Obstacles /perception/obstacle_segmentation/pointcloud sensor_msgs/PointCloud2 Obstacles, which includes dynamic objects and static objetcs Occupancy Grid Map /perception/occupancy_grid_map/map nav_msgs/msg/OccupancyGrid The map with the imformation about the presence of obstacles and blind spot Traffic Signal /perception/traffic_light_recognition/traffic_signals autoware_perception_msgs::msg::TrafficSignalArray The traffic signal information such as a color (green, yellow, read) and an arrow (right, left, straight)"},{"location":"design/autoware-interfaces/components/planning/","title":"Planning","text":""},{"location":"design/autoware-interfaces/components/planning/#planning","title":"Planning","text":""},{"location":"design/autoware-interfaces/components/planning/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/planning/#3d-object-predictions","title":"3D Object Predictions","text":"

set of perceived objects around ego that need to be avoided when planning a trajectory. Published by the Perception module.

  • autoware_auto_perception_msgs/msg/PredictedObjects
    • std_msgs/Header header
    • sequence<autoware_auto_perception_msgs::msg::PredictedObject> objects
      • unique_identifier_msgs::msg::UUID uuid
      • float existence_probability
      • sequence<autoware_auto_perception_msgs::msg::ObjectClassification> classification
        • uint8 classification
        • float probability
      • autoware_auto_perception_msgs::msg::PredictedObjectKinematics kinematics
        • geometry_msgs::msg::PoseWithCovariance initial_pose
        • geometry_msgs::msg::TwistWithCovariance
        • geometry_msgs::msg::AccelWithCovariance initial_acceleration
        • sequence<autoware_auto_perception_msgs::msg::PredictedPath, 10> predicted_paths
          • sequence<geometry_msgs::msg::Pose, 100> path
          • builtin_interfaces::msg::Duration time_step
          • float confidence
      • sequence<autoware_auto_perception_msgs::msg::Shape, 5> shape
        • geometry_msgs::msg::Polygon polygon
        • float height
"},{"location":"design/autoware-interfaces/components/planning/#traffic-light-response","title":"Traffic Light Response","text":"

Service response with traffic light information. The message definition is under discussion.

  • TrafficLightResponse
    • uint64 traffic_light_id
    • uint8 traffic_light_state

With the traffic_light_state being one of the following

  • GREEN = 1
  • GREEN_BLINKING = 2
  • YELLOW = 3
  • YELLOW_BLINKING = 4
  • RED = 5
  • RED_BLINKING = 6
  • OFF = 7
  • UNKNOWN = 8
"},{"location":"design/autoware-interfaces/components/planning/#vehicle-kinematic-state","title":"Vehicle kinematic state","text":"

current position and orientation of ego. Published by the Localization module.

  • VehicleKinematicState
    • nav_msgs/Odometry
    • std_msgs/Header header
    • string child_frame_id
    • geometry_msgs/PoseWithCovariance pose
    • geometry_msgs/TwistWithCovariance twist
"},{"location":"design/autoware-interfaces/components/planning/#lanelet2-map","title":"Lanelet2 Map","text":"

map of the environment where the planning takes place. Published by the Map Server.

  • autoware_auto_mapping_msgs/msg/HADMapBin
    • std_msgs::msg::Header header
    • uint8 map_format
    • string format_version
    • string map_version
    • sequence < uint8 > data
"},{"location":"design/autoware-interfaces/components/planning/#goal-pose","title":"Goal Pose","text":"

target pose of ego. Published by the User Interface.

  • geometry_msgs/PoseStamped
"},{"location":"design/autoware-interfaces/components/planning/#engagement-response","title":"Engagement Response","text":"

TBD.

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#error-status","title":"Error status","text":"

a status corresponding to the current state of Autoware. Used by the Vehicle Interface to switch between different modes in case of emergency. Published by the Diagnostic Manager.

  • autoware_auto_system_msgs/msg/EmergencyState
    • builtin_interfaces::msg::Time stamp
    • uint8 state

With the state being one of the following:

  • NORMAL = 1
  • OVERRIDE_REQUESTING = 2
  • MRM_OPERATING = 3
  • MRM_SUCCEEDED = 4
  • MRM_FAILED = 5

[TODO] original design for these messages: diagnostic manager also publishes an overriding emergency control command (Add the monitoring system related messages - Autoware.Auto). Possible new design: gate of the vehicle interface switches to the emergency control command (generated by another controller) when receiving an OVERRIDE_REQUESTING message.

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/planning/#traffic-light-query","title":"Traffic Light Query","text":"

service request for the state of a specific traffic light. Sent to the Perception module.

  • uint64 traffic_light_id

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#trajectory","title":"Trajectory","text":"

A sequence of space and velocity points to be followed by the controller.

  • autoware_auto_planning_msgs/Trajectory
    • std_msgs/Header header
    • sequence<autoware_auto_planning_msgs::msg::TrajectoryPoint, 100> points
      • builtin_interfaces::msg::Duration time_from_start
      • geometry_msgs::msg::Pose pose
      • float longitudinal_velocity_mps
      • float lateral_velocity_mps
      • float acceleration_mps2
      • float heading_rate_rps
      • float front_wheel_angle_rad
      • float rear_wheel_angle_rad
"},{"location":"design/autoware-interfaces/components/planning/#vehicle-signal-commands","title":"Vehicle Signal Commands","text":"

Commands for various elements of the vehicle unrelated to motion. Sent to the Vehicle Interface. (For the definition, see autoware_auto_vehicle_msgs.)

  • HandBrake Command
  • Hazard Lights Command
  • Headlights Command
  • Horn Command
  • Stationary Locking Command
  • Turn Indicator Command
  • Wipers Command
"},{"location":"design/autoware-interfaces/components/planning/#missions-status","title":"Missions Status","text":"

TBD.

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/planning/#engagement-request","title":"Engagement Request","text":"

TBD,

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/","title":"Vehicle dimensions","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle-dimensions","title":"Vehicle dimensions","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle-axes-and-base_link","title":"Vehicle axes and base_link","text":"

The base_link frame is used very frequently throughout the Autoware stack, and is a projection of the rear-axle center onto the ground surface.

  • Localization module outputs the map to base_link transformation.
  • Planning module plans the poses for where the base_link frame should be in the future.
  • Control module tries to fit base_link to incoming poses.
"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle-dimensions_1","title":"Vehicle dimensions","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheelbase","title":"wheelbase","text":"

The distance between front and rear axles.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#track_width","title":"track_width","text":"

The distance between left and right wheels.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#overhangs","title":"Overhangs","text":"

Overhangs are part of the minimum safety box calculation.

When measuring overhangs, side mirrors, protruding sensors and wheels should be taken into consideration.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#left_overhang","title":"left_overhang","text":"

The distance between the axis centers of the left wheels and the left-most point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#right_overhang","title":"right_overhang","text":"

The distance between the axis centers of the right wheels and the right-most point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#front_overhang","title":"front_overhang","text":"

The distance between the front axle and the foremost point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#rear_overhang","title":"rear_overhang","text":"

The distance between the rear axle and the rear-most point of the vehicle.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle_length","title":"vehicle_length","text":"

Total length of the vehicle. Calculated by front_overhang + wheelbase + rear_overhang

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#vehicle_width","title":"vehicle_width","text":"

Total width of the vehicle. Calculated by left_overhang + track_width + right_overhang

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel-parameters","title":"Wheel parameters","text":""},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel_width","title":"wheel_width","text":"

The lateral width of a wheel tire, primarily used for dead reckoning.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel_radius","title":"wheel_radius","text":"

The radius of the wheel, primarily used for dead reckoning.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#polygon_footprint","title":"polygon_footprint","text":"

The polygon defines the minimum collision area for the vehicle.

The points should be ordered clockwise, with the origin on the base_link.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#wheel-orientations","title":"Wheel orientations","text":"

If the vehicle is going forward, a positive wheel angle will result in the vehicle turning left.

Autoware assumes the rear wheels don't turn on z axis.

"},{"location":"design/autoware-interfaces/components/vehicle-dimensions/#notice","title":"Notice","text":"

The vehicle used in the illustrations was created by xvlblo22 and is from https://www.turbosquid.com/3d-models/modular-sedan-3d-model-1590886.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/","title":"Vehicle Interface","text":""},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-interface","title":"Vehicle Interface","text":"

The Vehicle Interface receives the Vehicle Signal Commands and Vehicle Control Commands and publishes the vehicle status. It also communicates with vehicle by the vehicle-specific protocol.

The Gate switches multiple Vehicle Control Commands. These signals include autonomous diving command, joystick, remote control, and emergency operation, etc. The Adapter converts generalized control command (target steering, steering rate, velocity, acceleration, jerk) into vehicle-specific control values (steering-torque, wheel-torque, voltage, pressure, accel pedal position, etc).

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#inputs","title":"Inputs","text":""},{"location":"design/autoware-interfaces/components/vehicle-interface/#error-status","title":"Error status","text":"

(See Inputs of Planning.)

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-control-command","title":"Vehicle Control Command","text":"

(See Output of Control.)

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-signals-commands","title":"Vehicle Signals Commands","text":"

Commands for various elements of the vehicle unrelated to motion. Published by the Planning module.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#outputs","title":"Outputs","text":""},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-signal-reports","title":"Vehicle Signal Reports","text":"

Reports for various elements of the vehicle unrelated to motion. Published by the Vehicle Interface.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-odometry","title":"Vehicle Odometry","text":"

Odometry of the vehicle. Used by the Localization module to update the pose of the vehicle in the map.

  • geometry_msgs/TwistWithCovarianceStamped odometry
"},{"location":"design/autoware-interfaces/components/vehicle-interface/#steering-status","title":"Steering Status","text":"

Steering of the ego vehicle. Published by the Vehicle Interface.

  • Steering message (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 steering_angle
"},{"location":"design/autoware-interfaces/components/vehicle-interface/#actuation-status","title":"Actuation Status","text":"

Actuation status of the ego vehicle for acceleration, steering, and brake. This represents the reported physical efforts exerted by the vehicle actuators. Published by the Vehicle Interface.

  • ActuationStatus (github discussion).
    • builtin_interfaces::msg::Time stamp
    • float32 acceleration
    • float32 steering
    • float32 brake

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#actuation-command","title":"Actuation Command","text":"

Actuation command sent to the ego vehicle. This represents the requested physical efforts to be exerted by the vehicle actuators. Published by the Vehicle Interface as generated by the adapter.

  • ActuationCommand (github discussion.)
    • builtin_interfaces::msg::Time stamp
    • float32 acceleration
    • float32 steering
    • float32 brake

The message definition is under discussion.

"},{"location":"design/autoware-interfaces/components/vehicle-interface/#vehicle-communication","title":"Vehicle Communication","text":"

Vehicle specific messages protocol like CAN (Controller Area Network).

"},{"location":"design/configuration-management/","title":"Configuration management","text":""},{"location":"design/configuration-management/#configuration-management","title":"Configuration management","text":"

Warning

Under Construction

"},{"location":"design/configuration-management/development-process/","title":"Development process","text":""},{"location":"design/configuration-management/development-process/#development-process","title":"Development process","text":"

Warning

Under Construction

"},{"location":"design/configuration-management/release-process/","title":"Release process","text":""},{"location":"design/configuration-management/release-process/#release-process","title":"Release process","text":"

Warning

Under Construction

"},{"location":"design/configuration-management/repository-structure/","title":"Repository structure","text":""},{"location":"design/configuration-management/repository-structure/#repository-structure","title":"Repository structure","text":"

Warning

Under Construction

"},{"location":"how-to-guides/","title":"How-to guides","text":""},{"location":"how-to-guides/#how-to-guides","title":"How-to guides","text":""},{"location":"how-to-guides/#integrating-autoware","title":"Integrating Autoware","text":"
  • Overview
"},{"location":"how-to-guides/#others","title":"Others","text":"
  • Debug Autoware
  • Running Autoware without CUDA
  • Fixing dependent package versions
  • Add a custom ROS message
  • Determining component dependencies
  • Advanced usage of colcon
  • Applying Clang-Tidy to ROS packages
  • Using Eagleye in Autoware

TODO: Write the following contents.

  • Create an Autoware package
  • etc.
"},{"location":"how-to-guides/integrating-autoware/creating-your-autoware-meta-repository/","title":"1. Creating your Autoware meta repository","text":""},{"location":"how-to-guides/integrating-autoware/creating-your-autoware-meta-repository/#creating-your-autoware-meta-repository","title":"Creating your Autoware meta repository","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/launch-autoware/","title":"5. Launch Autoware","text":""},{"location":"how-to-guides/integrating-autoware/launch-autoware/#launch-autoware","title":"Launch Autoware","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/overview/","title":"Overview","text":""},{"location":"how-to-guides/integrating-autoware/overview/#overview","title":"Overview","text":""},{"location":"how-to-guides/integrating-autoware/overview/#requirement-prepare-your-real-vehicle-hardware","title":"Requirement: prepare your real vehicle hardware","text":"

Prerequisites for the vehicle:

  • An onboard computer that satisfies the Autoware installation prerequisites
  • The following devices attached
    • Drive-by-wire interface
    • LiDAR
    • Optional: Inertial measurement unit
    • Optional: Camera
    • Optional: GNSS
"},{"location":"how-to-guides/integrating-autoware/overview/#1-creating-your-autoware-meta-repository","title":"1. Creating your Autoware meta-repository","text":"

Create your Autoware meta-repository. One easy way is to fork autowarefoundation/autoware and clone it. For how to fork a repository, refer to GitHub Docs.

git clone https://github.com/YOUR_NAME/autoware.git\n

If you set up multiple types of vehicles, adding a suffix like \"autoware.vehicle_A\" or \"autoware.vehicle_B\" is recommended.

"},{"location":"how-to-guides/integrating-autoware/overview/#2-creating-the-your-vehicle-and-sensor-description","title":"2. Creating the your vehicle and sensor description","text":"

Next, you need to create description packages that define the vehicle and sensor configuration of your vehicle.

Create the following two packages:

  • YOUR_VEHICLE_launch (see here for example)
  • YOUR_SENSOR_KIT_launch (see here for example)

Once created, you need to update the autoware.repos file of your cloned Autoware repository to refer to these two description packages.

-  # sensor_kit\n-  sensor_kit/sample_sensor_kit_launch:\n-    type: git\n-    url: https://github.com/autowarefoundation/sample_sensor_kit_launch.git\n-    version: main\n-  # vehicle\n-  vehicle/sample_vehicle_launch:\n-    type: git\n-    url: https://github.com/autowarefoundation/sample_vehicle_launch.git\n-    version: main\n+  # sensor_kit\n+  sensor_kit/YOUR_SENSOR_KIT_launch:\n+    type: git\n+    url: https://github.com/YOUR_NAME/YOUR_SENSOR_KIT_launch.git\n+    version: main\n+  # vehicle\n+  vehicle/YOUR_VEHICLE_launch:\n+    type: git\n+    url: https://github.com/YOUR_NAME/YOUR_VEHICLE_launch.git\n+    version: main\n
"},{"location":"how-to-guides/integrating-autoware/overview/#adapt-your_vehicle_launch-for-autoware-launching-system","title":"Adapt YOUR_VEHICLE_launch for autoware launching system","text":""},{"location":"how-to-guides/integrating-autoware/overview/#at-your_vehicle_description","title":"At YOUR_VEHICLE_description","text":"

Define URDF and parameters in the vehicle description package (refer to the sample vehicle description package for an example).

"},{"location":"how-to-guides/integrating-autoware/overview/#at-your_vehicle_launch","title":"At YOUR_VEHICLE_launch","text":"

Create a launch file (refer to the sample vehicle launch package for example). If you have multiple vehicles with the same hardware setup, you can specify vehicle_id to distinguish them.

"},{"location":"how-to-guides/integrating-autoware/overview/#adapt-your_sensor_kit_description-for-autoware-launching-system","title":"Adapt YOUR_SENSOR_KIT_description for autoware launching system","text":""},{"location":"how-to-guides/integrating-autoware/overview/#at-your_sensor_kit_description","title":"At YOUR_SENSOR_KIT_description","text":"

Define URDF and extrinsic parameters for all the sensors here (refer to the sample sensor kit description package for example). Note that you need to calibrate extrinsic parameters for all the sensors beforehand.

"},{"location":"how-to-guides/integrating-autoware/overview/#at-your_sensor_kit_launch","title":"At YOUR_SENSOR_KIT_launch","text":"

Create launch/sensing.launch.xml that launches the interfaces of all the sensors on the vehicle. (refer to the sample sensor kit launch package for example).

Note

At this point, you are now able to run Autoware's Planning Simulator to do a basic test of your vehicle and sensing packages. To do so, you need to build and install Autoware using your cloned repository. Follow the steps for either Docker or source installation (starting from the dependency installation step) and then run the following command:

ros2 launch autoware_launch planning_simulator.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP\n
"},{"location":"how-to-guides/integrating-autoware/overview/#3-create-a-vehicle_interface-package","title":"3. Create a vehicle_interface package","text":"

You need to create an interface package for your vehicle. The package is expected to provide the following two functions.

  1. Receive command messages from vehicle_cmd_gate and drive the vehicle accordingly
  2. Send vehicle status information to Autoware

You can find detailed information about the requirements of the vehicle_interface package in the Vehicle Interface design documentation. You can also refer to TIER IV's pacmod_interface repository as an example of a vehicle interface package.

"},{"location":"how-to-guides/integrating-autoware/overview/#4-create-maps","title":"4. Create maps","text":"

You need both a pointcloud map and a vector map in order to use Autoware. For more information on map design, please click here.

"},{"location":"how-to-guides/integrating-autoware/overview/#create-a-pointcloud-map","title":"Create a pointcloud map","text":"

Use third-party tools such as a LiDAR-based SLAM (Simultaneous Localization And Mapping) package to create a pointcloud map in the .pcd format. For more information, please click here.

"},{"location":"how-to-guides/integrating-autoware/overview/#create-vector-map","title":"Create vector map","text":"

Use third-party tools such as TIER IV's Vector Map Builder to create a Lanelet2 format .osm file.

"},{"location":"how-to-guides/integrating-autoware/overview/#5-launch-autoware","title":"5. Launch Autoware","text":"

This section briefly explains how to run your vehicle with Autoware.

"},{"location":"how-to-guides/integrating-autoware/overview/#install-autoware","title":"Install Autoware","text":"

Follow the installation steps of Autoware.

"},{"location":"how-to-guides/integrating-autoware/overview/#launch-autoware","title":"Launch Autoware","text":"

Launch Autoware with the following command:

ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP\n
"},{"location":"how-to-guides/integrating-autoware/overview/#set-initial-pose","title":"Set initial pose","text":"

If GNSS is available, Autoware automatically initializes the vehicle's pose.

If not, you need to set the initial pose using the RViz GUI.

  1. Click the 2D Pose estimate button in the toolbar, or hit the P key
  2. In the 3D View pane, click and hold the left mouse button, and then drag to set the direction for the initial pose.
"},{"location":"how-to-guides/integrating-autoware/overview/#set-goal-pose","title":"Set goal pose","text":"

Set a goal pose for the ego vehicle.

  1. Click the 2D Nav Goal button in the toolbar, or hit the G key
  2. In the 3D View pane, click and hold the left mouse button, and then drag to set the direction for the goal pose. If successful, you will see the calculated planning path on RViz.
"},{"location":"how-to-guides/integrating-autoware/overview/#engage","title":"Engage","text":"

In your terminal, execute the following command.

source ~/autoware.YOURS/install/setup.bash\nros2 topic pub /autoware.YOURS/engage autoware_auto_vehicle_msgs/msg/Engage \"engage: true\" -1\n

You can also engage via RViz with \"AutowareStatePanel\". The panel can be found in Panels > Add New Panel > tier4_state_rviz_plugin > AutowareStatePanel.

Now the vehicle should drive along the calculated path!

"},{"location":"how-to-guides/integrating-autoware/overview/#6-tune-parameters-for-your-vehicle-environment","title":"6. Tune parameters for your vehicle & environment","text":"

You may need to tune your parameters depending on the domain in which you will operate your vehicle.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/","title":"Creating maps","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/#creating-maps","title":"Creating maps","text":"

Autoware requires a pointcloud map and a vector map for the vehicle's operating environment. (Check the map design documentation page for the detailed specification).

This page explains how users can create maps that can be used for Autoware.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/#creating-a-point-cloud-map","title":"Creating a point cloud map","text":"

Traditionally, a Mobile Mapping System (MMS) is used in order to create highly accurate large-scale point cloud maps. However, since a MMS requires high-end sensors for precise positioning, its operational cost can be very expensive and may not be suitable for a relatively small driving environment. Alternatively, a Simultaneous Localization And Mapping (SLAM) algorithm can be used to create a point cloud map from recorded LiDAR scans. Some of the useful open-source SLAM implementations are listed in this page.

If you prefer proprietary software that is easy to use, you can try a fully automatic mapping tool from MAP IV, Inc., MapIV Engine. They currently provide a trial license for Autoware users free of charge.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/#creating-a-vector-map","title":"Creating a vector map","text":"

The easiest way to create an Autoware-compatible vector map is to use Vector Map Builder, a free web-based tool provided by TIER IV, Inc.. Vector Map Builder allows you to create lanes and add additional regulatory elements such as stop signs or traffic lights using a point cloud map as a reference.

For open-source software options, MapToolbox is a plugin for Unity specifically designed to create Lanelet2 maps for Autoware. Although JOSM is another open-source tool that can be used to create Lanelet2 maps, be aware that a number of modifications must be done manually to make the map compatible with Autoware. This process can be tedious and time-consuming, so the use of JOSM is not recommended.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/#autoware-compatible-map-providers","title":"Autoware-compatible map providers","text":"

If it is not possible to create HD maps yourself, you can use a mapping service from the following Autoware-compatible map providers instead:

  • MAP IV, Inc.
  • AISAN TECHNOLOGY CO., LTD.
  • TomTom

The table below shows each company's mapping technology and the types of HD maps they support.

Company Mapping technology Available maps MAP IV, Inc. SLAM Point cloud and vector maps AISAN TECHNOLOGY CO., LTD. MMS Point cloud and vector maps TomTom MMS Vector map*

Note

Maps provided by TomTom use their proprietary AutoStream format, not Lanelet2. The open-source AutoStreamForAutoware tool can be used to convert an AutoStream map to a Lanelet2 map. However, the converter is still in its early stages and has some known limitations.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/","title":"Available Open Source SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#available-open-source-slam","title":"Available Open Source SLAM","text":"

This page provides the list of available open source Simultaneous Localization And Mapping (SLAM) implementation that can be used to generete a point cloud (.pcd) map file.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#selecting-which-implementation-to-use","title":"Selecting which implementation to use","text":"

Lidar odometry drifts accumulatively as time goes by and there is solutions to solve that problem such as graph optimization, loop closure and using gps sensor to decrease accumulative drift error. Because of that, a SLAM algorithm should have loop closure feature, graph optimization and should use gps sensor. Additionally, some of the algorithms are using IMU sensor to add another factor to graph for decreasing drift error. While some of the algorithms requires 9-axis IMU sensor strictly, some of them requires only 6-axis IMU sensor or not even using the IMU sensor. Before choosing an algorithm to create maps for Autoware please consider these factors depends on your sensor setup or expected quality of generated map.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#tips","title":"Tips","text":"

Commonly used open-source SLAM implementations are lidarslam-ros2 (LiDAR, IMU*) and LIO-SAM (LiDAR, IMU, GNSS). The required sensor data for each algorithm is specified in the parentheses, where an asterisk (*) indicates that such sensor data is optional. For supported LiDAR models, please check the Github repository of each algorithm. While these ROS 2-based SLAM implementations can be easily installed and used directly on the same machine that runs Autoware, it is important to note that they may not be as well-tested or as mature as ROS 1-based alternatives.

The notable open-source SLAM implementations that are based on ROS 1 include hdl-graph-slam (LiDAR, IMU*, GNSS*), LeGO-LOAM (LiDAR, IMU*), LeGO-LOAM-BOR (LiDAR), and LIO-SAM (LiDAR, IMU, GNSS).

Most of these algorithms already have a built-in loop-closure and pose graph optimization. However, if the built-in, automatic loop-closure fails or does not work correctly, you can use Interactive SLAM to adjust and optimize a pose graph manually.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/#list-of-third-party-slam-implementations","title":"List of Third Party SLAM Implementations","text":"Package Name Explanation Repository Link Loop Closure Sensors ROS Version Dependencies FAST-LIO-LC A computationally efficient and robust LiDAR-inertial odometry package with loop closure module and graph optimization https://github.com/yanliang-wang/FAST_LIO_LC &check; LidarIMUGPS [Optional] ROS1 ROS MelodicPCL >= 1.8Eigen >= 3.3.4GTSAM >= 4.0.0 FAST_LIO_SLAM FAST_LIO_SLAM is the integration of FAST_LIO and SC-PGO which is scan context based loop detection and GTSAM based pose-graph optimization https://github.com/gisbi-kim/FAST_LIO_SLAM &check; LidarIMUGPS [Optional] ROS1 PCL >= 1.8Eigen >= 3.3.4 FD-SLAM FD_SLAM is Feature&Distribution-based 3D LiDAR SLAM method based on Surface Representation Refinement. In this algorithm novel feature-based Lidar odometry used for fast scan-matching, and used a proposed UGICP method for keyframe matching https://github.com/SLAMWang/FD-SLAM &check; LidarIMU [Optional]GPS ROS1 PCLg2oSuitesparse hdl_graph_slam An open source ROS package for real-time 6DOF SLAM using a 3D LIDAR. It is based on 3D Graph SLAM with NDT scan matching-based odometry estimation and loop detection. It also supports several graph constraints, such as GPS, IMU acceleration (gravity vector), IMU orientation (magnetic sensor), and floor plane (detected in a point cloud) https://github.com/koide3/hdl_graph_slam &check; LidarIMU [Optional]GPS [Optional] ROS1 PCLg2oOpenMP IA-LIO-SAM IA_LIO_SLAM is created for data acquisition in unstructured environment and it is a framework for Intensity and Ambient Enhanced Lidar Inertial Odometry via Smoothing and Mapping that achieves highly accurate robot trajectories and mapping https://github.com/minwoo0611/IA_LIO_SAM &check; LidarIMUGPS ROS1 GTSAM ISCLOAM ISCLOAM presents a robust loop closure detection approach by integrating both geometry and intensity information https://github.com/wh200720041/iscloam &check; Lidar ROS1 Ubuntu 18.04ROS MelodicCeresPCLGTSAMOpenCV LeGO-LOAM-BOR LeGO-LOAM-BOR is improved version of the LeGO-LOAM by improving quality of the code, making it more readable and consistent. Also, performance is improved by converting processes to multi-threaded approach https://github.com/facontidavide/LeGO-LOAM-BOR &check; LidarIMU ROS1 ROS MelodicPCLGTSAM LIO_SAM A framework that achieves highly accurate, real-time mobile robot trajectory estimation and map-building. It formulates lidar-inertial odometry atop a factor graph, allowing a multitude of relative and absolute measurements, including loop closures, to be incorporated from different sources as factors into the system https://github.com/TixiaoShan/LIO-SAM &check; LidarIMUGPS [Optional] ROS1ROS2 PCLGTSAM Optimized-SC-F-LOAM An improved version of F-LOAM and uses an adaptive threshold to further judge the loop closure detection results and reducing false loop closure detections. Also it uses feature point-based matching to calculate the constraints between a pair of loop closure frame point clouds and decreases time consumption of constructing loop frame constraints https://github.com/SlamCabbage/Optimized-SC-F-LOAM &check; Lidar ROS1 PCLGTSAMCeres SC-A-LOAM A real-time LiDAR SLAM package that integrates A-LOAM and ScanContext. https://github.com/gisbi-kim/SC-A-LOAM &check; Lidar ROS1 GTSAM >= 4.0 SC-LeGO-LOAM SC-LeGO-LOAM integrated LeGO-LOAM for lidar odometry and 2 different loop closure methods: ScanContext and Radius search based loop closure. While ScanContext is correcting large drifts, radius search based method is good for fine-stitching https://github.com/irapkaist/SC-LeGO-LOAM &check; LidarIMU ROS1 PCLGTSAM"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/","title":"FAST_LIO_LC","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#fast_lio_lc","title":"FAST_LIO_LC","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#what-is-fast_lio_lc","title":"What is FAST_LIO_LC?","text":"
  • A computationally efficient and robust LiDAR-inertial odometry package with loop closure module and graph optimization.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#original-repository-link","title":"Original Repository link","text":"

https://github.com/yanliang-wang/FAST_LIO_LC

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne, Ouster, Livox]
  • IMU [6-AXIS, 9-AXIS]
  • GPS [Optional]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#dependencies","title":"Dependencies","text":"
  • Ubuntu 18.04
  • ROS Melodic
  • PCL >= 1.8, Follow PCL Installation.
  • Eigen >= 3.3.4, Follow Eigen Installation.
  • GTSAM >= 4.0.0, Follow GTSAM Installation.
  wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\n  cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\n  cd ~/Downloads/gtsam-4.0.0-alpha2/\n  mkdir build && cd build\n  cmake ..\n  sudo make install\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#1-build","title":"1) Build","text":"
    mkdir -p ~/ws_fastlio_lc/src\n    cd ~/ws_fastlio_lc/src\n    git clone https://github.com/gisbi-kim/FAST_LIO_SLAM.git\n    git clone https://github.com/Livox-SDK/livox_ros_driver\n    cd ..\n    catkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#2-set-parameters","title":"2) Set parameters","text":"
  • After downloading the repository, change topic and sensor settings on the config file (workspace/src/FAST_LIO_LC/FAST_LIO/config/ouster64_mulran.yaml) with the lidar topic name in your bag file.
  • For imu-lidar compatibility, extrinsic matrices from calibration must be changed.
  • To enable auto-save, pcd_save_enable must be 1 from the launch file (workspace/src/FAST_LIO_LC/FAST_LIO/launch/mapping_ouster64_mulran.launch).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#3-run","title":"3) Run","text":"
  • For Ouster OS1-64
    # open new terminal: run FAST-LIO\nroslaunch fast_lio mapping_ouster64.launch\n\n# open the other terminal tab: run SC-PGO\nroslaunch aloam_velodyne fastlio_ouster64.launch\n\n# play bag file in the other terminal\nrosbag play RECORDED_BAG.bag --clock\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#other-examples","title":"Other Examples","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#example-dataset","title":"Example dataset","text":"

Check original repository link for example dataset.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#contact","title":"Contact","text":"
  • Maintainer: Yanliang Wang (wyl410922@qq.com)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/#acknowledgements","title":"Acknowledgements","text":"
  • Thanks for FAST_LIO authors.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/","title":"FAST_LIO_SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#fast_lio_slam","title":"FAST_LIO_SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#what-is-fast_lio_slam","title":"What is FAST_LIO_SLAM?","text":"
  • FAST_LIO_SLAM is the integration of FAST_LIO and SC-PGO which is scan context based loop detection and GTSAM based pose-graph optimization.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/gisbi-kim/FAST_LIO_SLAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Livox, Velodyne, Ouster]
  • IMU [6-AXIS, 9-AXIS]
  • GPS [OPTIONAL]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • Gtsam
wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.0-alpha2/\nmkdir build && cd build\ncmake ..\nsudo make install\n
  • PCL >= 1.8, Follow PCL Installation.
  • Eigen >= 3.3.4, Follow Eigen Installation.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#1-build","title":"1) Build","text":"
    mkdir -p ~/catkin_fastlio_slam/src\n    cd ~/catkin_fastlio_slam/src\n    git clone https://github.com/gisbi-kim/FAST_LIO_SLAM.git\n    git clone https://github.com/Livox-SDK/livox_ros_driver\n    cd ..\n    catkin_make\n    source devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#2-set-parameters","title":"2) Set parameters","text":"
  • Set imu and lidar topic on Fast_LIO/config/ouster64.yaml
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#3-run","title":"3) Run","text":"
    # terminal 1: run FAST-LIO2\nroslaunch fast_lio mapping_ouster64.launch\n\n    # open the other terminal tab: run SC-PGO\ncd ~/catkin_fastlio_slam\n    source devel/setup.bash\n    roslaunch aloam_velodyne fastlio_ouster64.launch\n\n    # play bag file in the other terminal\nrosbag play xxx.bag -- clock --pause\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#other-examples","title":"Other Examples","text":"

  • Tutorial video 1 (using KAIST 03 sequence of MulRan dataset)

    • Example result captures

    • download the KAIST03 pcd map made by FAST-LIO-SLAM, 500MB
  • Example Video 2 (Riverside 02 sequence of MulRan dataset)
    • Example result captures

    • download the Riverisde02 pcd map made by FAST-LIO-SLAM, 400MB
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/#acknowledgements","title":"Acknowledgements","text":"
  • Thanks for FAST_LIO authors.
  • You may have an interest in this version of FAST-LIO + Loop closure, implemented by yanliang-wang
  • Maintainer: Giseop Kim (paulgkim@kaist.ac.kr)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/","title":"FD-SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#fd-slam","title":"FD-SLAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#what-is-fd-slam","title":"What is FD-SLAM?","text":"
  • FD_SLAM is Feature&Distribution-based 3D LiDAR SLAM method based on Surface Representation Refinement. In this algorithm novel feature-based Lidar odometry used for fast scan-matching, and used a proposed UGICP method for keyframe matching.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#repository-information","title":"Repository Information","text":"

This is an open source ROS package for real-time 6DOF SLAM using a 3D LIDAR.

It is based on hdl_graph_slam and the steps to run our system are same with hdl-graph-slam.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/SLAMWang/FD-SLAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR[VLP-16, HDL-32, HDL-64, OS1-64]
  • GPS
  • IMU [Optional]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • g2o
  • Suitesparse

The following ROS packages are required:

  • geodesy
  • nmea_msgs
  • pcl_ros
  • ndt_omp
  • U_gicp This is modified based on fast_gicp by us. We use UGICP for keyframe matching.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/SLAMWang/FD-SLAM.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#2-services","title":"2) Services","text":"
/hdl_graph_slam/dump  (hdl_graph_slam/DumpGraph)\n- save all the internal data (point clouds, floor coeffs, odoms, and pose graph) to a directory.\n\n/hdl_graph_slam/save_map (hdl_graph_slam/SaveMap)\n- save the generated map as a PCD file.\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#3-set-parameters","title":"3) Set parameters","text":"
  • All the configurable parameters are listed in launch/****.launch as ros params.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/#4-run","title":"4) Run","text":"
source devel/setup.bash\nroslaunch hdl_graph_slam hdl_graph_slam_400_ours.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/","title":"hdl_graph_slam","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#hdl_graph_slam","title":"hdl_graph_slam","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#what-is-hdl_graph_slam","title":"What is hdl_graph_slam?","text":"
  • An open source ROS package for real-time 6DOF SLAM using a 3D LIDAR. It is based on 3D Graph SLAM with NDT scan matching-based odometry estimation and loop detection. It also supports several graph constraints, such as GPS, IMU acceleration (gravity vector), IMU orientation (magnetic sensor), and floor plane (detected in a point cloud).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/koide3/hdl_graph_slam

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne, Ouster, RoboSense]
  • IMU [6-AXIS, 9-AXIS] [OPTIONAL]
  • GPS [OPTIONAL]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • g2o
  • OpenMP

The following ROS packages are required:

  • geodesy
  • nmea_msgs
  • pcl_ros
  • ndt_omp
  • fast_gicp
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#1-build","title":"1) Build","text":"
# for melodic\nsudo apt-get install ros-melodic-geodesy ros-melodic-pcl-ros ros-melodic-nmea-msgs ros-melodic-libg2o\ncd catkin_ws/src\ngit clone https://github.com/koide3/ndt_omp.git -b melodic\ngit clone https://github.com/SMRT-AIST/fast_gicp.git --recursive\ngit clone https://github.com/koide3/hdl_graph_slam\n\ncd .. && catkin_make -DCMAKE_BUILD_TYPE=Release\n\n# for noetic\nsudo apt-get install ros-noetic-geodesy ros-noetic-pcl-ros ros-noetic-nmea-msgs ros-noetic-libg2o\n\ncd catkin_ws/src\ngit clone https://github.com/koide3/ndt_omp.git\ngit clone https://github.com/SMRT-AIST/fast_gicp.git --recursive\ngit clone https://github.com/koide3/hdl_graph_slam\n\ncd .. && catkin_make -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#2-set-parameter","title":"2) Set parameter","text":"
  • Set lidar topic on launch/hdl_graph_slam_400.launch
  • Set registration settings on launch/hdl_graph_slam_400.launch
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#3-run","title":"3) Run","text":"
rosparam set use_sim_time true\nroslaunch hdl_graph_slam hdl_graph_slam_400.launch\n
roscd hdl_graph_slam/rviz\nrviz -d hdl_graph_slam.rviz\n
rosbag play --clock hdl_400.bag\n

Save the generated map by:

rosservice call /hdl_graph_slam/save_map \"resolution: 0.05\ndestination: '/full_path_directory/map.pcd'\"\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#example2-outdoor","title":"Example2 (Outdoor)","text":"

Bag file (recorded in an outdoor environment):

  • hdl_400.bag.tar.gz (raw data, about 900MB)
rosparam set use_sim_time true\nroslaunch hdl_graph_slam hdl_graph_slam_400.launch\n
roscd hdl_graph_slam/rviz\nrviz -d hdl_graph_slam.rviz\n
rosbag play --clock dataset.bag\n

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#papers","title":"Papers","text":"

Kenji Koide, Jun Miura, and Emanuele Menegatti, A Portable 3D LIDAR-based System for Long-term and Wide-area People Behavior Measurement, Advanced Robotic Systems, 2019 [link].

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/#contact","title":"Contact","text":"

Kenji Koide, k.koide@aist.go.jp, https://staff.aist.go.jp/k.koide

[Active Intelligent Systems Laboratory, Toyohashi University of Technology, Japan] [Mobile Robotics Research Team, National Institute of Advanced Industrial Science and Technology (AIST), Japan]

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/","title":"IA-LIO-SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#ia-lio-sam","title":"IA-LIO-SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#what-is-ia-lio-sam","title":"What is IA-LIO-SAM?","text":"
  • IA_LIO_SLAM is created for data acquisition in unstructured environment and it is a framework for Intensity and Ambient Enhanced Lidar Inertial Odometry via Smoothing and Mapping that achieves highly accurate robot trajectories and mapping.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/minwoo0611/IA_LIO_SAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne, Ouster]
  • IMU [9-AXIS]
  • GNSS
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#dependencies","title":"Dependencies","text":"

  • ROS (tested with Kinetic and Melodic)

    • for ROS melodic:

      sudo apt-get install -y ros-melodic-navigation\nsudo apt-get install -y ros-melodic-robot-localization\nsudo apt-get install -y ros-melodic-robot-state-publisher\n

    • for ROS kinetic:

      sudo apt-get install -y ros-kinetic-navigation\nsudo apt-get install -y ros-kinetic-robot-localization\nsudo apt-get install -y ros-kinetic-robot-state-publisher\n

  • GTSAM (Georgia Tech Smoothing and Mapping library)

    wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.2/\nmkdir build && cd build\ncmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF ..\nsudo make install -j8\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#1-build","title":"1) Build","text":"
    mkdir -p ~/catkin_ia_lio/src\n    cd ~/catkin_ia_lio/src\n    git clone https://github.com/minwoo0611/IA_LIO_SAM\n    cd ..\n    catkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#2-set-parameters","title":"2) Set parameters","text":"
  • After downloading the repository, change topic and sensor settings on the config file (workspace/src/IA_LIO_SAM/config/params.yaml)
  • For imu-lidar compatibility, extrinsic matrices from calibration must be changed.
  • To enable autosave, savePCD must be true on the params.yaml file (workspace/src/IA_LIO_SAM/config/params.yaml).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#3-run","title":"3) Run","text":"
  # open new terminal: run IA_LIO\n  source devel/setup.bash\n  roslaunch lio_sam mapping_ouster64.launch\n\n  # play bag file in the other terminal\n  rosbag play RECORDED_BAG.bag --clock\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#sample-dataset-images","title":"Sample dataset images","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#example-dataset","title":"Example dataset","text":"

Check original repo link for example dataset.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#contact","title":"Contact","text":"
  • Maintainer: Kevin Jung (Github: minwoo0611)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#paper","title":"Paper","text":"

Thank you for citing IA-LIO-SAM(./config/doc/KRS-2021-17.pdf) if you use any of this code.

Part of the code is adapted from LIO-SAM (IROS-2020).

@inproceedings{legoloam2018shan,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Shan, Tixiao and Englot, Brendan},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/#acknowledgements","title":"Acknowledgements","text":"
  • IA-LIO-SAM is based on LIO-SAM (T. Shan, B. Englot, D. Meyers, W. Wang, C. Ratti, and D. Rus. LIO-SAM: Tightly-coupled Lidar Inertial Odometry via Smoothing and Mapping).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/","title":"ISCLOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#iscloam","title":"ISCLOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#what-is-iscloam","title":"What is ISCLOAM?","text":"
  • ISCLOAM presents a robust loop closure detection approach by integrating both geometry and intensity information.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/wh200720041/iscloam

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Velodyne]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#dependencies","title":"Dependencies","text":"
  • Ubuntu 64-bit 18.04
  • ROS Melodic ROS Installation
  • Ceres Solver Ceres Installation
  • PCL PCL Installation
  • Gtsam GTSAM Installation
  • OpenCV OPENCV Installation
  • Trajectory visualization

For visualization purpose, this package uses hector trajectory sever, you may install the package by

sudo apt-get install ros-melodic-hector-trajectory-server\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#build-and-run","title":"Build and Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#1-clone-repository","title":"1. Clone repository","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/wh200720041/iscloam.git\ncd ..\ncatkin_make -j1\nsource ~/catkin_ws/devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#2-set-parameter","title":"2. Set Parameter","text":"

Change the bag location and sensor parameters on launch files.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#3-launch","title":"3. Launch","text":"
roslaunch iscloam iscloam.launch\n

if you would like to generate the map of environment at the same time, you can run

roslaunch iscloam iscloam_mapping.launch\n

Note that the global map can be very large, so it may takes a while to perform global optimization, some lag is expected between trajectory and map since they are running in separate thread. More CPU usage will happen when loop closure is identified.

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#example-result","title":"Example Result","text":"

Watch demo video at Video Link

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#ground-truth-comparison","title":"Ground Truth Comparison","text":"

Green: ISCLOAM Red: Ground Truth

                  KITTI sequence 00                                  KITTI sequence 05\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#citation","title":"Citation","text":"

If you use this work for your research, you may want to cite the paper below, your citation will be appreciated

@inproceedings{wang2020intensity,\n  author={H. {Wang} and C. {Wang} and L. {Xie}},\n  booktitle={2020 IEEE International Conference on Robotics and Automation (ICRA)},\n  title={Intensity Scan Context: Coding Intensity and Geometry Relations for Loop Closure Detection},\n  year={2020},\n  volume={},\n  number={},\n  pages={2095-2101},\n  doi={10.1109/ICRA40945.2020.9196764}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/#acknowledgements","title":"Acknowledgements","text":"

Thanks for A-LOAM and LOAM(J. Zhang and S. Singh. LOAM: Lidar Odometry and Mapping in Real-time) and LOAM_NOTED.

Author: Wang Han, Nanyang Technological University, Singapore

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/","title":"LeGO-LOAM-BOR","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#lego-loam-bor","title":"LeGO-LOAM-BOR","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#what-is-lego-loam-bor","title":"What is LeGO-LOAM-BOR?","text":"
  • LeGO-LOAM-BOR is improved version of the LeGO-LOAM by improving quality of the code, making it more readable and consistent. Also, performance is improved by converting processes to multi-threaded approach.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#original-repository-link","title":"Original Repository link","text":"

https://github.com/facontidavide/LeGO-LOAM-BOR

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16]
  • IMU [9-AXIS]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#dependencies","title":"Dependencies","text":"
  • ROS Melodic ROS Installation
  • PCL PCL Installation
  • Gtsam GTSAM Installation
wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.0-alpha2/\nmkdir build && cd build\ncmake ..\nsudo make install\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/facontidavide/LeGO-LOAM-BOR.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#2-set-parameters","title":"2) Set parameters","text":"
  • Set parameters on LeGo-LOAM/loam_config.yaml
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#3-run","title":"3) Run","text":"
source devel/setup.bash\nroslaunch lego_loam_bor run.launch rosbag:=/path/to/your/rosbag lidar_topic:=/velodyne_points\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/#cite-lego-loam","title":"Cite LeGO-LOAM","text":"

Thank you for citing our LeGO-LOAM paper if you use any of this code:

@inproceedings{legoloam2018,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Tixiao Shan and Brendan Englot},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/","title":"LIO_SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#lio_sam","title":"LIO_SAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#what-is-lio_sam","title":"What is LIO_SAM?","text":"
  • A framework that achieves highly accurate, real-time mobile robot trajectory estimation and map-building. It formulates lidar-inertial odometry atop a factor graph, allowing a multitude of relative and absolute measurements, including loop closures, to be incorporated from different sources as factors into the system
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/TixiaoShan/LIO-SAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [Livox, Velodyne, Ouster]
  • IMU [9-AXIS]
  • GPS [OPTIONAL]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
  • For ROS 2
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL

  • Gtsam (Georgia Tech Smoothing and Mapping library)

    sudo add-apt-repository ppa:borglab/gtsam-release-4.0\nsudo apt install libgtsam-dev libgtsam-unstable-dev\n
  sudo apt-get install -y ros-melodic-navigation\n  sudo apt-get install -y ros-melodic-robot-localization\n  sudo apt-get install -y ros-melodic-robot-state-publisher\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#1-build","title":"1) Build","text":"
    mkdir -p ~/catkin_lio_sam/src\n    cd ~/catkin_lio_sam/src\n    git clone https://github.com/TixiaoShan/LIO-SAM.git\n    cd ..\n    catkin_make\n    source devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#2-set-parameters","title":"2) Set parameters","text":"
  • Set topics and sensor settings on lio_sam/config/params.yaml
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#3-run","title":"3) Run","text":"
    # Run the Launch File\nroslaunch lio_sam run.launch\n\n    # Play bag file in the other terminal\nrosbag play xxx.bag --clock\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#paper","title":"Paper","text":"

Thank you for citing LIO-SAM (IROS-2020) if you use any of this code.

@inproceedings{liosam2020shan,\n  title={LIO-SAM: Tightly-coupled Lidar Inertial Odometry via Smoothing and Mapping},\n  author={Shan, Tixiao and Englot, Brendan and Meyers, Drew and Wang, Wei and Ratti, Carlo and Rus Daniela},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={5135-5142},\n  year={2020},\n  organization={IEEE}\n}\n

Part of the code is adapted from LeGO-LOAM.

@inproceedings{legoloam2018shan,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Shan, Tixiao and Englot, Brendan},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/#acknowledgements","title":"Acknowledgements","text":"
  • LIO-SAM is based on LOAM (J. Zhang and S. Singh. LOAM: Lidar Odometry and Mapping in Real-time).
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/","title":"Optimized-SC-F-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#optimized-sc-f-loam","title":"Optimized-SC-F-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#what-is-optimized-sc-f-loam","title":"What is Optimized-SC-F-LOAM?","text":"
  • An improved version of F-LOAM and uses an adaptive threshold to further judge the loop closure detection results and reducing false loop closure detections. Also it uses feature point-based matching to calculate the constraints between a pair of loop closure frame point clouds and decreases time consumption of constructing loop frame constraints.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/SlamCabbage/Optimized-SC-F-LOAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16, HDL-32, HDL-64]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • Gtsam
  • Ceres Solver
  • For visualization purpose, this package uses hector trajectory sever, you may install the package by
sudo apt-get install ros-noetic-hector-trajectory-server\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/SlamCabbage/Optimized-SC-F-LOAM.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#2-create-message-file","title":"2) Create message file","text":"

In this folder, Ground Truth information, optimized pose information, F-LOAM pose information and time information are stored

mkdir -p ~/message/Scans\n\nChange line 383 in the laserLoopOptimizationNode.cpp to your own \"message\" folder path\n

(Do not forget to rebuild your package)

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#3-set-parameters","title":"3) Set parameters","text":"
  • Set LIDAR topic and LIDAR properties on 'sc_f_loam_mapping.launch'
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#4-run","title":"4) Run","text":"
source devel/setup.bash\nroslaunch optimized_sc_f_loam optimized_sc_f_loam_mapping.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#results-on-kitti-sequence-00-and-sequence-05","title":"Results on KITTI Sequence 00 and Sequence 05","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#comparison-of-trajectories-on-kitti-dataset","title":"Comparison of trajectories on KITTI dataset","text":"

Test on KITTI sequence You can download the sequence 00 and 05 datasets from the KITTI official website and convert them into bag files using the kitti2bag open source method.

00: 2011_10_03_drive_0027 000000 004540

05: 2011_09_30_drive_0018 000000 002760

See the link: https://github.com/ethz-asl/kitti_to_rosbag

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#acknowledgements","title":"Acknowledgements","text":"

Thanks for SC-A-LOAM(Scan context: Egocentric spatial descriptor for place recognition within 3d point cloud map) and F-LOAM(F-LOAM : Fast LiDAR Odometry and Mapping).

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/#citation","title":"Citation","text":"
@misc{https://doi.org/10.48550/arxiv.2204.04932,\n  doi = {10.48550/ARXIV.2204.04932},\n\n  url = {https://arxiv.org/abs/2204.04932},\n\n  author = {Liao, Lizhou and Fu, Chunyun and Feng, Binbin and Su, Tian},\n\n  keywords = {Robotics (cs.RO), FOS: Computer and information sciences, FOS: Computer and information sciences},\n\n  title = {Optimized SC-F-LOAM: Optimized Fast LiDAR Odometry and Mapping Using Scan Context},\n\n  publisher = {arXiv},\n\n  year = {2022},\n\n  copyright = {arXiv.org perpetual, non-exclusive license}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/","title":"SC-A-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#sc-a-loam","title":"SC-A-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#what-is-sc-a-loam","title":"What is SC-A-LOAM?","text":"
  • A real-time LiDAR SLAM package that integrates A-LOAM and ScanContext.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/gisbi-kim/SC-A-LOAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16, HDL-32, HDL-64, Ouster OS1-64]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#prerequisites-dependencies","title":"Prerequisites (dependencies)","text":"
  • ROS
  • GTSAM version 4.x.

  • If GTSAM is not installed, follow the steps below.

      wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.2.zip\n  cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\n  cd ~/Downloads/gtsam-4.0.2/\n  mkdir build && cd build\n  cmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF ..\n  sudo make install -j8\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#1-build","title":"1) Build","text":"

  • First, install the abovementioned dependencies and follow below lines.

     mkdir -p ~/catkin_scaloam_ws/src\n cd ~/catkin_scaloam_ws/src\n git clone https://github.com/gisbi-kim/SC-A-LOAM.git\n cd ../\n catkin_make\n source ~/catkin_scaloam_ws/devel/setup.bash\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#2-set-parameters","title":"2) Set parameters","text":"
  • After downloading the repository, change topic and sensor settings on the launch files.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#scan-context-parameters","title":"Scan Context parameters","text":"
  • If encountering ghosting error or loop is not closed, change the scan context parameters.
  • Adjust the scan context settings with the parameters in the marked area.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#3-run","title":"3) Run","text":"
roslaunch aloam_velodyne aloam_mulran.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#4-saving-as-pcd-file","title":"4) Saving as PCD file","text":"
  rosrun pcl_ros pointcloud_to_pcd input:=/aft_pgo_map\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#example-results","title":"Example Results","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#riverside-01-mulran-dataset","title":"Riverside 01, MulRan dataset","text":"
  • The MulRan dataset provides lidar scans (Ouster OS1-64, horizontally mounted, 10Hz) and consumer level gps (U-Blox EVK-7P, 4Hz) data.
  • About how to use (publishing data) data: see here https://github.com/irapkaist/file_player_mulran

  • example videos on Riverside 01 sequence.

    1. with consumer level GPS-based altitude stabilization: https://youtu.be/FwAVX5TVm04\n2. without the z stabilization: https://youtu.be/okML_zNadhY\n

  • example result:

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#kitti-05","title":"KITTI 05","text":"

  • For KITTI (HDL-64 sensor), run using the command

    roslaunch aloam_velodyne aloam_velodyne_HDL_64.launch # for KITTI dataset setting\n
  • To publish KITTI scans, you can use mini-kitti publisher, a simple python script: https://github.com/gisbi-kim/mini-kitti-publisher
  • example video (no GPS used here): https://youtu.be/hk3Xx8SKkv4

  • example result:

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/#contact","title":"Contact","text":"
  • Maintainer: paulgkim@kaist.ac.kr
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/","title":"SC-LeGO-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#sc-lego-loam","title":"SC-LeGO-LOAM","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#what-is-sc-lego-loam","title":"What is SC-LeGO-LOAM?","text":"
  • SC-LeGO-LOAM integrated LeGO-LOAM for lidar odometry and 2 different loop closure methods: ScanContext and Radius search based loop closure. While ScanContext is correcting large drifts, radius search based method is good for fine-stitching.
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#repository-information","title":"Repository Information","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#original-repository-link","title":"Original Repository link","text":"

https://github.com/irapkaist/SC-LeGO-LOAM

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#required-sensors","title":"Required Sensors","text":"
  • LIDAR [VLP-16, HDL-32E, VLS-128, Ouster OS1-16, Ouster OS1-64]
  • IMU [9-AXIS]
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#ros-compatibility","title":"ROS Compatibility","text":"
  • ROS 1
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#dependencies","title":"Dependencies","text":"
  • ROS
  • PCL
  • Gtsam
wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip\ncd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/\ncd ~/Downloads/gtsam-4.0.0-alpha2/\nmkdir build && cd build\ncmake ..\nsudo make install\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#build-run","title":"Build & Run","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#1-build","title":"1) Build","text":"
cd ~/catkin_ws/src\ngit clone https://github.com/irapkaist/SC-LeGO-LOAM.git\ncd ..\ncatkin_make\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#2-set-parameters","title":"2) Set parameters","text":"
  • Set imu and lidar topic on include/utility.h
  • Set lidar properties on include/utility.h
  • Set scancontex settings on include/Scancontext.h

(Do not forget to rebuild after setting parameters.)

"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#3-run","title":"3) Run","text":"
source devel/setup.bash\nroslaunch lego_loam run.launch\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#example-result","title":"Example Result","text":""},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#other-examples","title":"Other Examples","text":"
  • Video 1: DCC (MulRan dataset)
  • Video 2: Riverside (MulRan dataset)
  • Video 3: KAIST (MulRan dataset)
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#mulran-dataset","title":"MulRan dataset","text":"
  • If you want to reproduce the results as the above video, you can download the MulRan dataset and use the ROS topic publishing tool .
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#cite-sc-lego-loam","title":"Cite SC-LeGO-LOAM","text":"
@INPROCEEDINGS { gkim-2018-iros,\n  author = {Kim, Giseop and Kim, Ayoung},\n  title = { Scan Context: Egocentric Spatial Descriptor for Place Recognition within {3D} Point Cloud Map },\n  booktitle = { Proceedings of the IEEE/RSJ International Conference on Intelligent Robots and Systems },\n  year = { 2018 },\n  month = { Oct. },\n  address = { Madrid }\n}\n

and

@inproceedings{legoloam2018,\n  title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},\n  author={Shan, Tixiao and Englot, Brendan},\n  booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n  pages={4758-4765},\n  year={2018},\n  organization={IEEE}\n}\n
"},{"location":"how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/#contact","title":"Contact","text":"
  • Maintainer: Giseop Kim (paulgkim@kaist.ac.kr)
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/","title":"Calibrating your sensors","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#calibrating-your-sensors","title":"Calibrating your sensors","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#overview","title":"Overview","text":"

Autoware expects to have multiple sensors attached to the vehicle as input to perception, localization, and planning stack. These sensors must be calibrated correctly and their positions must be defined using either urdf files (as in sample_sensor_kit) or as tf launch files.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#camera-calibration","title":"Camera calibration","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#intrinsic-calibration","title":"Intrinsic Calibration","text":"
  • Navigation2 provides a good tutorial for camera internal calibration.
  • AutoCore provides a light-weight tool.
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-lidar-calibration","title":"Lidar-lidar calibration","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-lidar-calibration-tool-from-autocore","title":"Lidar-Lidar Calibration tool from Autocore","text":"

LL-Calib on Github, provided by AutoCore, is a lightweight toolkit for online/offline 3D LiDAR to LiDAR calibration. It's based on local mapping and \"GICP\" method to derive the relation between main and sub lidar. Information on how to use the tool, troubleshooting tips and example rosbags can be found at the above link.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-camera-calibration","title":"Lidar-camera calibration","text":"

Developed by MathWorks, The Lidar Camera Calibrator app enables you to interactively estimate the rigid transformation between a lidar sensor and a camera.

https://ww2.mathworks.cn/help/lidar/ug/get-started-lidar-camera-calibrator.html

SensorsCalibration toolbox v0.1: One more open source method for Lidar-camera calibration. This is a project for LiDAR to camera calibration,including automatic calibration and manual calibration

https://github.com/PJLab-ADG/SensorsCalibration/blob/master/lidar2camera/README.md

Developed by AutoCore, an easy-to-use lightweight toolkit for Lidar-camera-calibration is proposed. Only in three steps, a fully automatic calibration will be done.

https://github.com/autocore-ai/calibration_tools/tree/main/lidar-cam-calib-related

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors/#lidar-imu-calibration","title":"Lidar-IMU calibration","text":"

Developed by APRIL Lab at Zhejiang University in China, the LI-Calib calibration tool is a toolkit for calibrating the 6DoF rigid transformation and the time offset between a 3D LiDAR and an IMU, based on continuous-time batch optimization. IMU-based cost and LiDAR point-to-surfel (surfel = surface element) distance are minimized jointly, which renders the calibration problem well-constrained in general scenarios.

AutoCore has forked the original LI-Calib tool and overwritten the Lidar input for more general usage. Information on how to use the tool, troubleshooting tips and example rosbags can be found at the LI-Calib fork on Github.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description/","title":"Creating vehicle and sensor description","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description/#creating-vehicle-and-sensor-description","title":"Creating vehicle and sensor description","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model/","title":"Creating vehicle interface for ackerman kinematic model","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model/#creating-vehicle-interface-for-ackerman-kinematic-model","title":"Creating vehicle interface for ackerman kinematic model","text":"

Warning

Under Construction

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/","title":"Customizing for differential drive vehicle","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#customizing-for-differential-drive-vehicle","title":"Customizing for differential drive vehicle","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#1-introduction","title":"1. Introduction","text":"

Currently, Autoware assumes that vehicles use an Ackermann kinematic model with Ackermann steering. Thus, Autoware adopts the Ackermann command format for the Control module's output (see the AckermannDrive ROS message definition for an overview of Ackermann commands, and the AckermannControlCommands struct used in Autoware for more details).

However, it is possible to integrate Autoware with a vehicle that follows a differential drive kinematic model, as commonly used by small mobile robots.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#2-procedure","title":"2. Procedure","text":"

One simple way of using Autoware with a differential drive vehicle is to create a vehicle_interface package that translates Ackermann commands to differential drive commands. Here are two points that you need to consider:

  • Create vehicle_interface package for differential drive vehicle
  • Set an appropriate wheel_base
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#21-create-a-vehicle_interface-package-for-differential-drive-vehicle","title":"2.1 Create a vehicle_interface package for differential drive vehicle","text":"

An Ackermann command in Autoware consists of two main control inputs:

  • steering angle (\\omega)
  • velocity (v)

Conversely, a typical differential drive command consists of the following inputs:

  • left wheel velocity (v_l)
  • right wheel velocity (v_r)

So, one way in which an Ackermann command can be converted to a differential drive command is by using the following equations:

v_l = v - \\frac{l\\omega}{2}, v_r = v + \\frac{l\\omega}{2}

where l denotes wheel tread.

For information about other factors that need to be considered when creating a vehicle_interface package, refer to the vehicle_interface component page.

"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#22-set-an-appropriate-wheel_base","title":"2.2 Set an appropriate wheel_base","text":"

A differential drive robot does not necessarily have front and rear wheels, which means that the wheelbase (the horizontal distance between the axles of the front and rear wheels) cannot be defined. However, Autoware expects wheel_base to be set in vehicle_info.param.yaml with some value. Thus, you need to set a pseudo value for wheel_base.

The appropriate pseudo value for wheel_base depends on the size of your vehicle. Setting it to be the same value as wheel_tread is one possible choice.

Warning

  • If the wheel_base value is set too small then the vehicle may behave unexpectedly. For example, the vehicle may drive beyond the bounds of a calculated path.
  • Conversely, if wheel_base is set too large, the vehicle's range of motion will be restricted. The reason being that Autoware's Planning module will calculate an overly conservative trajectory based on the assumed vehicle length.
"},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#3-known-issues","title":"3. Known issues","text":""},{"location":"how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/#motion-model-incompatibility","title":"Motion model incompatibility","text":"

Since Autoware assumes that vehicles use a steering system, it is not possible to take advantage of the flexibility of a differential drive system's motion model.

For example, when planning a parking maneuver with the freespace_planner module, Autoware may drive the differential drive vehicle forward and backward, even if the vehicle can be parked with a simpler trajectory that uses pure rotational movement.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/","title":"Evaluating the controller performance","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#evaluating-the-controller-performance","title":"Evaluating the controller performance","text":"

This page shows how to use control_performance_analysis package to evaluate the controllers.

control_performance_analysis is the package to analyze the tracking performance of a control module and monitor the driving status of the vehicle.

If you need more detailed information about package, refer to the control_performance_analysis.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#how-to-use","title":"How to use","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#before-driving","title":"Before Driving","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#1-firstly-you-need-to-launch-autoware-you-can-also-use-this-tool-with-real-vehicle-driving","title":"1. Firstly you need to launch Autoware. You can also use this tool with real vehicle driving","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#2-initialize-the-vehicle-and-send-goal-position-to-create-route","title":"2. Initialize the vehicle and send goal position to create route","text":"
  • If you have any problem with launching Autoware, please see the tutorials page.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#3-launch-the-control_performance_analysis-package","title":"3. Launch the control_performance_analysis package","text":"
ros2 launch control_performance_analysis controller_performance_analysis.launch.xml\n
  • After this command, you should be able to see the driving monitor and error variables in topics.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#4-run-the-plotjuggler-in-sourced-terminal","title":"4. Run the PlotJuggler in sourced terminal","text":"
source ~/autoware/install/setup.bash\n
ros2 run plotjuggler plotjuggler\n
  • If you do not have PlotJuggler in your computer, please refer here for installation guideline.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#5-increase-the-buffer-size-maximum-is-100-and-import-the-layout-from-autowareuniversecontrolcontrol_performance_analysisconfigcontroller_monitorxml","title":"5. Increase the buffer size (maximum is 100), and import the layout from /autoware.universe/control/control_performance_analysis/config/controller_monitor.xml","text":"
  • After import the layout, please specify the topics that are listed below.
  • /localization/kinematic_state
  • /vehicle/status/steering_status
  • /control_performance/driving_status
  • /control_performance/performance_vars
  • Please mark the If present, use the timestamp in the field [header.stamp] box, then select the OK.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#6-now-you-can-start-to-driving-you-should-see-all-the-performance-and-driving-variables-in-plotjuggler","title":"6. Now, you can start to driving. You should see all the performance and driving variables in PlotJuggler","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#after-driving","title":"After Driving","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#1-you-can-export-the-statistical-output-and-all-data-to-compare-and-later-usage","title":"1. You can export the statistical output and all data to compare and later usage","text":"
  • With statistical data, you can export the all statistical values like (min, max, average) to compare the controllers.
  • You can also export all data to later use. To investigate them again, after launch PlotJuggler, import the .cvs file from data section.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance/#tips","title":"Tips","text":"
  • You can plot the vehicle position. Select the two curve (keeping CTRL key pressed) and Drag & Drop them using the RIGHT Mouse button. Please visit the Help -> Cheatsheet in PlotJuggler to see more tips about it.
  • If you see too much noised curve in plots, you can adjust the odom_interval and low_pass_filter_gain from here to avoid noised data.
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/","title":"Evaluating real-time performance","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#evaluating-real-time-performance","title":"Evaluating real-time performance","text":""},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#introduction","title":"Introduction","text":"

Autoware should be real-time system when integrated to a service. Therefore, the response time of each callback should be as small as possible. If Autoware appears to be slow, it is imperative to conduct performance measurements and implement improvements based on the analysis. However, Autoware is a complex software system comprising numerous ROS 2 nodes, potentially complicating the process of identifying bottlenecks. To address this challenge, we will discuss methods for conducting detailed performance measurements for Autoware and provide case studies. It is worth noting that multiple factors can contribute to poor performance, such as scheduling and memory allocation in the OS layer, but our focus in this page will be on user code bottlenecks. The outline of this section is as follows:

  • Performance measurement
    • Single node execution
    • Prepare separated cores
    • Run single node separately
    • Measurement and visualization
  • Case studies
    • Sensing component
    • Planning component
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#performance-measurement","title":"Performance measurement","text":"

Improvement is impossible without precise measurements. To measure the performance of the application code, it is essential to eliminate any external influences. Such influences include interference from the operating system and CPU frequency fluctuations. Scheduling effects also occur when core resources are shared by multiple threads. This section outlines a technique for accurately measuring the performance of the application code for a specific node. Though this section only discusses the case of Linux on Intel CPUs, similar considerations should be made in other environments.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#single-node-execution","title":"Single node execution","text":"

To eliminate the influence of scheduling, the node being measured should operate independently, using the same logic as when the entire Autoware system is running. To accomplish this, record all input topics of the node to be measured while the whole Autoware system is running. To achieve this objective, a tool called ros2_single_node_replayer has been prepared.

Details on how to use the tool can be found in the README. This tool records the input topics of a specific node during the entire Autoware operation and replays it in a single node with the same logic. The tool relies on the ros2 bag record command, and the recording of service/action is not supported as of ROS 2 Humble, so nodes that use service/action as their main logic may not work well.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#prepare-separated-cores","title":"Prepare separated cores","text":"

Isolated cores running the node to be measured must meet the following conditions.

  • Fix CPU frequency and disable turbo boost
  • Minimize timer interruptions
  • Offload RCU (Read Copy Update) callback
  • Isolate the paired core if hyper-threading enabled

To fulfill these conditions on Linux, a custom kernel build with the following kernel configurations is required. You can find many resources to instruct you on how to build a custom Linux kernel (like this one). Note that even if full tickless is enabled, timer interrupts are generated for scheduling if more than two tasks exist in one core.

# Enable CONFIG_NO_HZ_FULL\n-> General setup\n-> Timers subsystem\n-> Timer tick handling (Full dynticks system (tickless))\n(X) Full dynticks system (tickless)\n\n# Allows RCU callback processing to be offloaded from selected CPUs\n# (CONFIG_RCU_NOCB_CPU=y)\n-> General setup\n-> RCU Subsystem\n-*- Offload RCU callback processing from boot-selected CPUs\n

Additionally, the kernel boot parameters need to be set as follows.

GRUB_CMDLINE_LINUX_DEFAULT=\n  \"... isolcpus=2,8 rcu_nocbs=2,8 rcu_nocb_poll nohz_full=2,8 intel_pstate=disable\u201d\n

In the above configuration, for example, the node to be measured is assumed to run on core 2, and core 8, which is a hyper-threading pair, is also being isolated. Appropriate decisions on which cores to run the measurement target and which nodes to isolate need to be made based on the cache and core layout of the measurement machine. You can easily check if it is properly configured by running cat /proc/softirqs. Since intel_pstate=disable is specified in the kernel boot parameter, userspace can be specified in the scaling governor.

cat /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor // ondemand\nsudo sh -c \"echo userspace > /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor\"\n

This allows you to freely set the desired frequency within a defined range.

sudo sh -c \"echo <freq(kz)> > /sys/devices/system/cpu/cpu2/cpufreq/scaling_setspeed\"\n

Turbo Boost needs to be switched off on Intel CPUs, which is often overlooked.

sudo sh -c \"echo 0 > /sys/devices/system/cpu/cpufreq/boost\"\n
"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#run-single-node-separately","title":"Run single node separately","text":"

Following the instructions in the ros2_single_node_replayer README, start the node and play the dedicated rosbag created by the tool. Before playing the rosbag, appropriately set the CPU affinity of the thread on which the node runs, so it is placed on the isolated core prepared.

taskset --cpu-list -p <target cpu> <pid>\n

To avoid interference in the last level cache, minimize the number of other applications running during the measurement.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#measurement-and-visualization","title":"Measurement and visualization","text":"

To visualize the performance of the measurement target, embed code for logging timestamps and performance counter values in the target source code. To achieve this objective, a tool called pmu_analyzer has been prepared.

Details on how to use the tool can be found in the README. This tool can measure the turnaround time of any section in the source code, as well as various performance counters.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#case-studies","title":"Case studies","text":"

In this section, we will present several case studies that demonstrate the performance improvements. These examples not only showcase our commitment to enhancing the system's efficiency but also serve as a valuable resource for developers who may face similar challenges in their own projects. The performance improvements discussed here span various components of the Autoware system, including sensing modules and planning modules. There are tendencies for each component regarding which points are becoming bottlenecks. By examining the methods, techniques, and tools employed in these case studies, readers can gain a better understanding of the practical aspects of optimizing complex software systems like Autoware.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#sensing-component","title":"Sensing component","text":"

First, we will explain the procedure for performance improvement, taking the node ring_outlier_filter as an example. Refer to the Pull Request for details.

The following figure is a time-series plot of the turnaround time of the main processing part of ring_outlier_filter, analyzed as described in the \"Performance Measurement\" section above.

The horizontal axis indicates the number of callbacks called (i.e., callback index), and the vertical axis indicates the turnaround time.

When analyzing the performance of the sensing module from the viewpoint of performance counter, pay attention to instructions, LLC-load-misses, LLC-store-misses, cache-misses, and minor-faults.

Analysis of the performance counter shows that the largest fluctuations come from minor-faults (i.e., soft page faults), the second largest from LLC-store-misses and LLC-load-misses (i.e., cache misses in the last level cache), and the slowest fluctuations come from instructions (i.e., message data size fluctuations). For example, when we plot minor-faults on the horizontal axis and turnaround time on the vertical axis, we can see the following dominant proportional relationship.

To achieve zero soft page faults, heap allocations must only be made from areas that have been first touched in advance. We have developed a library called heaphook to avoid soft page faults while running Autoware callback. If you are interested, refer to the GitHub discussion and the issue.

To reduce LLC misses, it is necessary to reduce the working set and to use cache-efficient access patterns.

In the sensing component, which handles large message data such as LiDAR point cloud data, minimizing copying is important. A callback that takes sensor data message types as input and output should be written in an in-place algorithm as much as possible. This means that in the following pseudocode, when generating output_msg from input_msg, it is crucial to avoid using buffers as much as possible to reduce the number of memory copies.

void callback(const PointCloudMsg &input_msg) {\nauto output_msg = allocate_msg<PointCloudMsg>(output_size);\nfill(input_msg, output_msg);\npublish(std::move(output_msg));\n}\n

To improve cache efficiency, implement an in-place style as much as possible, instead of touching memory areas sporadically. In ROS applications using PCL, the code shown below is often seen.

void callback(const sensor_msgs::PointCloud2ConstPtr &input_msg) {\npcl::PointCloud<PointT>::Ptr input_pcl(new pcl::PointCloud<PointT>);\npcl::fromROSMsg(*input_msg, *input_pcl);\n\n// Algorithm is described for point cloud type of pcl\npcl::PointCloud<PointT>::Ptr output_pcl(new pcl::PointCloud<PointT>);\nfill_pcl(*input_pcl, *output_pcl);\n\nauto output_msg = allocate_msg<sensor_msgs::PointCloud2>(output_size);\npcl::toROSMsg(*output_pcl, *output_msg);\npublish(std::move(output_msg));\n}\n

To use the PCL library, fromROSMsg() and toROSMsg() are used to perform message type conversion at the beginning and end of the callback. This is a wasteful copying process and should be avoided. We should eliminate unnecessary type conversions by removing dependencies on PCL (e.g., https://github.com/tier4/velodyne_vls/pull/39). For large message types such as map data, there should be only one instance in the entire system in terms of physical memory.

"},{"location":"how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance/#planning-component","title":"Planning component","text":"

First, we will pick up detection_area module in behavior_velocity_planner node, which tends to have long turnaround time. We have followed the performance analysis steps above to obtain the following graph. Axises are the same as the graphs in the sensing case study.

Using pmu_analyzer tool to further identify the bottleneck, we have found that the following multiple loops were taking up a lot of processing time:

for ( area : detection_areas )\nfor ( point : point_clouds )\nif ( boost::geometry::within(point, area) )\n// do something with O(1)\n

It checks whether each point cloud is contained in each detection area. Let N be the size of point_clouds and M be the size of detection_areas, then the computational complexity of this program is O(N^2 * M), since the complexity of within is O(N). Here, given that most of the point clouds are located far away from a certain detection area, a certain optimization can be achieved. First, calculate the minimum enclosing circle that completely covers the detection area, and then check whether the points are contained in that circle. Most of the point clouds can be quickly ruled out by this method, we don\u2019t have to call the within function in most cases. Below is the pseudocode after optimization.

for ( area : detection_areas )\ncircle = calc_minimum_enclosing_circle(area)\nfor ( point : point_clouds )\nif ( point is in circle )\nif ( boost::geometry::within(point, area) )\n// do something with O(1)\n

By using O(N) algorithm for minimum enclosing circle, the computational complexity of this program is reduced to almost O(N * (N + M)) (note that the exact computational complexity does not really change). If you are interested, refer to the Pull Request.

Similar to this example, in the planning component, we take into consideration thousands to tens of thousands of point clouds, thousands of points in a path representing our own route, and polygons representing obstacles and detection areas in the surroundings, and we repeatedly create paths based on them. Therefore, we access the contents of the point clouds and paths multiple times using for-loops. In most cases, the bottleneck lies in these naive for-loops. Here, understanding Big O notation and reducing the order of computational complexity directly leads to performance improvements.

"},{"location":"how-to-guides/others/add-a-custom-ros-message/","title":"Add a custom ROS message","text":""},{"location":"how-to-guides/others/add-a-custom-ros-message/#add-a-custom-ros-message","title":"Add a custom ROS message","text":""},{"location":"how-to-guides/others/add-a-custom-ros-message/#overview","title":"Overview","text":"

During the Autoware development, you will probably need to define your own messages. Read the following instructions before adding a custom message.

  1. Message in autoware_msgs define interfaces of Autoware Core.

    • If a contributor wishes to make changes or add new messages to autoware_msgs, they should first create a new discussion post under the Design category.

  2. Any other minor or proposal messages used for internal communication within a component(such as planning) should be defined in another repository.

    • tier4_autoware_msgs is an example of that.

The following is a simple tutorial of adding a message package to autoware_msgs. For the general ROS2 tutorial, see Create custom msg and srv files.

"},{"location":"how-to-guides/others/add-a-custom-ros-message/#how-to-create-custom-message","title":"How to create custom message","text":"

Make sure you are in the Autoware workspace, and then run the following command to create a new package. As an example, let's create a package to define sensor messages.

  1. Create a package

    cd ./src/core/autoware_msgs\nros2 pkg create --build-type ament_cmake autoware_sensing_msgs\n

  2. Create custom messages

    You should create .msg files and place them in the msg directory.

    NOTE: The initial letters of the .msg and .srv files must be capitalized.

    As an example, let's make .msg files GnssInsOrientation.msg and GnssInsOrientationStamped.msg to define GNSS/INS orientation messages:

    mkdir msg\ncd msg\ntouch GnssInsOrientation.msg\ntouch GnssInsOrientationStamped.msg\n

    Edit GnssInsOrientation.msg with your editor to be the following content:

    geometry_msgs/Quaternion orientation\nfloat32 rmse_rotation_x\nfloat32 rmse_rotation_y\nfloat32 rmse_rotation_z\n

    In this case, the custom message uses a message from another message package geometry_msgs/Quaternion.

    Edit GnssInsOrientationStamped.msg with your editor to be the following content:

    std_msgs/Header header\nGnssInsOrientation orientation\n

    In this case, the custom message uses a message from another message package std_msgs/Header.

  3. Edit CMakeLists.txt

    In order to use this custom message in C++ or Python languages, we need to add the following lines to CMakeList.txt:

    rosidl_generate_interfaces(${PROJECT_NAME}\n\"msg/GnssInsOrientation.msg\"\n\"msg/GnssInsOrientationStamped.msg\"\nDEPENDENCIES\ngeometry_msgs\nstd_msgs\nADD_LINTER_TESTS\n)\n

    The ament_cmake_auto tool is very useful and is more widely used in Autoware, so we recommend using ament_cmake_auto instead of ament_cmake.

    We need to replace

    find_package(ament_cmake REQUIRED)\n\nament_package()\n

    with

    find_package(ament_cmake_auto REQUIRED)\n\nament_auto_package()\n

  4. Edit package.xml

    We need to declare relevant dependencies in package.xml. For the above example we need to add the following content:

    <buildtool_depend>rosidl_default_generators</buildtool_depend>\n\n<exec_depend>rosidl_default_runtime</exec_depend>\n\n<depend>geometry_msgs</depend>\n<depend>std_msgs</depend>\n\n<member_of_group>rosidl_interface_packages</member_of_group>\n

    We need to replace <buildtool_depend>ament_cmake</buildtool_depend> with <buildtool_depend>ament_cmake_auto</buildtool_depend> in the package.xml file.

  5. Build the custom message package

    You can build the package in the root of your workspace, for example by running the following command:

    colcon build --packages-select autoware_sensing_msgs\n

    Now the GnssInsOrientationStamped message will be discoverable by other packages in Autoware.

"},{"location":"how-to-guides/others/add-a-custom-ros-message/#how-to-use-custom-messages-in-autoware","title":"How to use custom messages in Autoware","text":"

You can use the custom messages in Autoware by following these steps:

  • Add dependency in package.xml.
    • For example, <depend>autoware_sensing_msgs</depend>.
  • Include the .hpp file of the relevant message in the code.
    • For example, #include <autoware_sensing_msgs/msg/gnss_ins_orientation_stamped.hpp>.
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/","title":"Advanced usage of colcon","text":""},{"location":"how-to-guides/others/advanced-usage-of-colcon/#advanced-usage-of-colcon","title":"Advanced usage of colcon","text":"

This page shows some advanced and useful usage of colcon. If you need more detailed information, refer to the colcon documentation.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#common-mistakes","title":"Common mistakes","text":""},{"location":"how-to-guides/others/advanced-usage-of-colcon/#do-not-run-from-other-than-the-workspace-root","title":"Do not run from other than the workspace root","text":"

It is important that you always run colcon build from the workspace root because colcon builds only under the current directory. If you have mistakenly built in a wrong directory, run rm -rf build/ install/ log/ to clean the generated files.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#do-not-unnecessarily-overlay-workspaces","title":"Do not unnecessarily overlay workspaces","text":"

colcon overlays workspaces if you have sourced the setup.bash of other workspaces before building a workspace. You should take care of this especially when you have multiple workspaces.

Run echo $COLCON_PREFIX_PATH to check whether workspaces are overlaid. If you find some workspaces are unnecessarily overlaid, remove all built files, restart the terminal to clean environment variables, and re-build the workspace.

For more details about workspace overlaying, refer to the ROS 2 documentation.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#cleaning-up-the-build-artifacts","title":"Cleaning up the build artifacts","text":"

colcon sometimes causes errors of because of the old cache. To remove the cache and rebuild the workspace, run the following command:

rm -rf build/ install/\n

In case you know what packages to remove:

rm -rf {build,install}/{package_a,package_b}\n
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#selecting-packages-to-build","title":"Selecting packages to build","text":"

To just build specified packages:

colcon build --packages-select <package_name1> <package_name2> ...\n

To build specified packages and their dependencies recursively:

colcon build --packages-up-to <package_name1> <package_name2> ...\n

You can also use these options for colcon test.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#changing-the-optimization-level","title":"Changing the optimization level","text":"

Set DCMAKE_BUILD_TYPE to change the optimization level.

Warning

If you specify DCMAKE_BUILD_TYPE=Debug or no DCMAKE_BUILD_TYPE is given for building the entire Autoware, it may be too slow to use.

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug\n
colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo\n
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#changing-the-default-configuration-of-colcon","title":"Changing the default configuration of colcon","text":"

Create $COLCON_HOME/defaults.yaml to change the default configuration.

mkdir -p ~/.colcon\ncat << EOS > ~/.colcon/defaults.yaml\n{\n\"build\": {\n\"symlink-install\": true\n}\n}\n

For more details, see here.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#generating-compile_commandsjson","title":"Generating compile_commands.json","text":"

compile_commands.json is used by IDEs/tools to analyze the build dependencies and symbol relationships.

You can generate it with the flag DCMAKE_EXPORT_COMPILE_COMMANDS=1:

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1\n
"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#seeing-compiler-commands","title":"Seeing compiler commands","text":"

To see the compiler and linker invocations for a package, use VERBOSE=1 and --event-handlers console_cohesion+:

VERBOSE=1 colcon build --packages-up-to <package_name> --event-handlers console_cohesion+\n

For other options, see here.

"},{"location":"how-to-guides/others/advanced-usage-of-colcon/#using-ccache","title":"Using Ccache","text":"

Ccache can speed up recompilation. It is recommended to use it to save your time unless you have a specific reason not to do so.

  1. Install Ccache:

    sudo apt update && sudo apt install ccache\n

  2. Write the following in your .bashrc:

    export CC=\"/usr/lib/ccache/gcc\"\nexport CXX=\"/usr/lib/ccache/g++\"\n
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/","title":"Applying Clang-Tidy to ROS packages","text":""},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#applying-clang-tidy-to-ros-packages","title":"Applying Clang-Tidy to ROS packages","text":"

Clang-Tidy is a powerful C++ linter.

"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#preparation","title":"Preparation","text":"

You need to generate build/compile_commands.json before using Clang-Tidy.

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1\n
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#usage","title":"Usage","text":"
clang-tidy -p build/ path/to/file1 path/to/file2 ...\n

If you want to apply Clang-Tidy to all files in a package, using the fd command is useful. To install fd, see the installation manual.

clang-tidy -p build/ $(fd -e cpp -e hpp --full-path \"/autoware_utils/\")\n
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#ide-integration","title":"IDE integration","text":""},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#clion","title":"CLion","text":"

Refer to the CLion Documentation.

"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#visual-studio-code","title":"Visual Studio Code","text":"

Use either one of the following extensions:

  • C/C++
  • clangd
"},{"location":"how-to-guides/others/applying-clang-tidy-to-ros-packages/#troubleshooting","title":"Troubleshooting","text":"

If you encounter clang-diagnostic-error, try installing libomp-dev.

Related: https://github.com/autowarefoundation/autoware-github-actions/pull/172

"},{"location":"how-to-guides/others/debug-autoware/","title":"Debug Autoware","text":""},{"location":"how-to-guides/others/debug-autoware/#debug-autoware","title":"Debug Autoware","text":"

This page provides some methods for debugging Autoware.

"},{"location":"how-to-guides/others/debug-autoware/#print-debug-messages","title":"Print debug messages","text":"

The essential thing for debug is to print the program information clearly, which can quickly judge the program operation and locate the problem. Autoware uses ROS 2 logging tool to print debug messages, how to design console logging refer to tutorial Console logging.

"},{"location":"how-to-guides/others/debug-autoware/#using-ros-tools-debug-autoware","title":"Using ROS tools debug Autoware","text":""},{"location":"how-to-guides/others/debug-autoware/#using-command-line-tools","title":"Using command line tools","text":"

ROS 2 includes a suite of command-line tools for introspecting a ROS 2 system. The main entry point for the tools is the command ros2, which itself has various sub-commands for introspecting and working with nodes, topics, services, and more. How to use the ROS 2 command line tool refer to tutorial CLI tools.

"},{"location":"how-to-guides/others/debug-autoware/#using-rviz2","title":"Using rviz2","text":"

Rviz2 is a port of Rviz to ROS 2. It provides a graphical interface for users to view their robot, sensor data, maps, and more. You can run Rviz2 tool easily by:

rviz2\n

When Autoware launch the simulators, the Rviz2 tool is opened by default to visualize the autopilot graphic information.

"},{"location":"how-to-guides/others/debug-autoware/#using-rqt-tools","title":"Using rqt tools","text":"

RQt is a graphical user interface framework that implements various tools and interfaces in the form of plugins. You can run any RQt tools/plugins easily by:

rqt\n

This GUI allows you to choose any available plugins on your system. You can also run plugins in standalone windows. For example, RQt Console:

ros2 run rqt_console rqt_console\n
"},{"location":"how-to-guides/others/debug-autoware/#common-rqt-tools","title":"Common RQt tools","text":"

  1. rqt_graph: view node interaction

    In complex applications, it may be helpful to get a visual representation of the ROS node interactions.

    ros2 run rqt_graph rqt_graph\n

  2. rqt_console: view messages

    rqt_console is a great gui for viewing ROS topics.

    ros2 run rqt_console rqt_console\n

  3. rqt_plot: view data plots

    rqt_plot is an easy way to plot ROS data in real time.

    ros2 run rqt_plot rqt_plot\n
"},{"location":"how-to-guides/others/debug-autoware/#using-ros2_graph","title":"Using ros2_graph","text":"

ros2_graph can be used to generate mermaid description of ROS 2 graphs to add on your markdown files.

It can also be used as a colorful alternative to rqt_graph even though it would require some tool to render the generated mermaid diagram.

It can be installed with:

pip install ros2-graph\n

Then you can generate a mermaid description of the graph with:

ros2_graph your_node\n\n# or like with an output file\nros2_graph /turtlesim -o turtle_diagram.md\n\n# or multiple nodes\nros2_graph /turtlesim /teleop_turtle\n

You can then visualize these graphs with:

  • Mermaid Live Editor
  • Visual Studio Code extension mermaid preview
  • JetBrains IDEs with native support
"},{"location":"how-to-guides/others/debug-autoware/#using-ros2doctor","title":"Using ros2doctor","text":"

When your ROS 2 setup is not running as expected, you can check its settings with the ros2doctor tool.

ros2doctor checks all aspects of ROS 2, including platform, version, network, environment, running systems and more, and warns you about possible errors and reasons for issues.

It's as simple as just running ros2 doctor in your terminal.

It has the ability to list \"Subscribers without publishers\" for all topics in the system.

And this information can help you find if a necessary node isn't running.

For more details, see the following official documentation for Using ros2doctor to identify issues.

"},{"location":"how-to-guides/others/debug-autoware/#using-a-debugger-with-breakpoints","title":"Using a debugger with breakpoints","text":"

Many IDE(e.g. Visual Studio Code, CLion) supports debugging C/C++ executable with GBD on linux platform. The following lists some references for using the debugger:

  • https://code.visualstudio.com/docs/cpp/cpp-debug
  • https://www.jetbrains.com/help/clion/debugging-code.html#useful-debugger-shortcuts
"},{"location":"how-to-guides/others/determining-component-dependencies/","title":"Determining component dependencies","text":""},{"location":"how-to-guides/others/determining-component-dependencies/#determining-component-dependencies","title":"Determining component dependencies","text":"

For any developers who wish to try and deploy Autoware as a microservices architecture, it is necessary to understand the software dependencies, communication, and implemented features of each ROS package/node.

As an example, the commands necessary to determine the dependencies for the Perception component are shown below.

"},{"location":"how-to-guides/others/determining-component-dependencies/#perception-component-dependencies","title":"Perception component dependencies","text":"

To generate a graph of package dependencies, use the following colcon command:

colcon graph --dot --packages-up-to tier4_perception_launch | dot -Tpng -o graph.png\n

To generate a list of dependencies, use:

colcon list --packages-up-to tier4_perception_launch --names-only\n
colcon list output 
autoware_auto_geometry_msgs\nautoware_auto_mapping_msgs\nautoware_auto_perception_msgs\nautoware_auto_planning_msgs\nautoware_auto_vehicle_msgs\nautoware_cmake\nautoware_lint_common\nautoware_point_types\ncompare_map_segmentation\ndetected_object_feature_remover\ndetected_object_validation\ndetection_by_tracker\neuclidean_cluster\ngrid_map_cmake_helpers\ngrid_map_core\ngrid_map_cv\ngrid_map_msgs\ngrid_map_pcl\ngrid_map_ros\nground_segmentation\nimage_projection_based_fusion\nimage_transport_decompressor\ninterpolation\nkalman_filter\nlanelet2_extension\nlidar_apollo_instance_segmentation\nmap_based_prediction\nmulti_object_tracker\nmussp\nobject_merger\nobject_range_splitter\noccupancy_grid_map_outlier_filter\npointcloud_preprocessor\npointcloud_to_laserscan\nshape_estimation\ntensorrt_yolo\ntier4_autoware_utils\ntier4_debug_msgs\ntier4_pcl_extensions\ntier4_perception_launch\ntier4_perception_msgs\ntraffic_light_classifier\ntraffic_light_map_based_detector\ntraffic_light_ssd_fine_detector\ntraffic_light_visualization\nvehicle_info_util\n

Tip

To output a list of modules with their respective paths, run the command above without the --names-only parameter.

To see which ROS topics are being subscribed and published to, use rqt_graph as follows:

ros2 launch tier4_perception_launch perception.launch.xml mode:=lidar\nros2 run rqt_graph rqt_graph\n
"},{"location":"how-to-guides/others/eagleye-integration-guide/","title":"Using Eagleye with Autoware","text":""},{"location":"how-to-guides/others/eagleye-integration-guide/#using-eagleye-with-autoware","title":"Using Eagleye with Autoware","text":"

This page will show you how to set up Eagleye in order to use it with Autoware. For the details of the integration proposal, please refer to this Discussion.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#what-is-eagleye","title":"What is Eagleye?","text":"

Eagleye is an open-source GNSS/IMU-based localizer initially developed by MAP IV. Inc. It provides a cost-effective alternative to LiDAR and point cloud-based localization by using low-cost GNSS and IMU sensors to provide vehicle position, orientation, and altitude information. By integrating Eagleye into Autoware, users can choose between LiDAR and point cloud-based localization stacks or GNSS/IMU-based Eagleye localizer, depending on their specific needs and operating environment.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#architecture","title":"Architecture","text":"

Eagleye can be utilized in the Autoware localization stack in two ways:

  1. Feed only twist into the EKF localizer.

  2. Feed both twist and pose from Eagleye into the EKF localizer (twist can also be used with regular gyro_odometry).

Note that RTK positioning is only required for localization using the Eagleye pose. RTK positioning is not required for twist.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#requirements","title":"Requirements","text":"

GNSS/IMU/vehicle speed is required for Eagleye input.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#imu-topic","title":"IMU topic","text":"

sensor_msgs/msg/Imu are supported for IMU.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#vehicle-speed-topic","title":"Vehicle speed topic","text":"

geometry_msgs/msg/TwistStamped and geometry_msgs/msg/TwistWithCovarianceStamped are supported for the input vehicle speed.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#gnss-topic","title":"GNSS topic","text":"

Eagleye requires latitude/longitude height information and velocity information generated by the GNSS receiver. Your GNSS ROS driver must publish the following messages:

  • sensor_msgs/msg/NavSatFix: This message contains latitude, longitude, and height information.
  • geometry_msgs/msg/TwistWithCovarianceStamped: This message contains gnss doppler velocity information.

Eagleye has been tested with the following example GNSS ROS drivers: ublox_gps and septentrio_gnss_driver. The settings needed for each of these drivers are as follows:

  • ublox_gps: This ROS driver publishes sensor_msgs/msg/NavSatFix and geometry_msgs/msg/TwistWithCovarianceStamped required by Eagleye with default settings. Therefore, no additional settings are required.
  • septentrio_gnss_driver: Set publish.navsatfix and publish.twist in the config file gnss.yaml to true
"},{"location":"how-to-guides/others/eagleye-integration-guide/#eagleye-setup","title":"Eagleye Setup","text":""},{"location":"how-to-guides/others/eagleye-integration-guide/#install-dependencies","title":"Install dependencies","text":"

Clone the following three packages for Eagleye:

  1. Eagleye (autoware-main branch)
  2. RTKLIB ROS Bridge (ros2-v0.1.0 branch)
  3. LLH Converter (ros2 branch)
"},{"location":"how-to-guides/others/eagleye-integration-guide/#modifying-autoware-launch-files","title":"Modifying Autoware Launch files","text":"

You need to install Eagleye-related packages and change Autoware's launcher. Four files are required in the Autoware localization launcher to run Eagleye: eagleye_rt.launch.xml, eagleye_config.yaml, gnss_converter.launch.xml, and fix2pose.launch.xml.

You must correctly specify input topics for GNSS latitude, longitude, and height information, GNSS speed information, IMU information, and vehicle speed information in the eagleye_config.yaml.

# Topic\ntwist:\ntwist_type: 1 # TwistStamped : 0, TwistWithCovarianceStamped: 1\ntwist_topic: /sensing/vehicle_velocity_converter/twist_with_covariance\nimu_topic: /sensing/imu/tamagawa/imu_raw\ngnss:\nvelocity_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, ublox_msgs/NavPVT: 2, geometry_msgs/TwistWithCovarianceStamped: 3\nvelocity_source_topic: /sensing/gnss/ublox/navpvt\nllh_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, sensor_msgs/NavSatFix: 2\nllh_source_topic: /sensing/gnss/ublox/nav_sat_fix\n

Also, the frequency of GNSS and IMU must be set in eagleye_config.yaml

common:\nimu_rate: 50\ngnss_rate: 5\n

The basic parameters that do not need to be changed except those mentioned above, i.e., topic names and sensors' frequency, are described below here. Additionally, the parameters for converting sensor_msgs/msg/NavSatFix to geometry_msgs/msg/PoseWithCovarianceStamped is listed in fix2pose.yaml.

Please refer to map4_localization_launch in the autoware.universe package and map4_localization_component.launch.xml in autoware_launch package for information on how to modify the localization launch.

Eagleye has a function for position estimation and a function for twist estimation, namely pose_estimator and twist_estimator, respectively.

localization launch twist estimator pose estimator tier4_localization_launch gyro_odometry ndt_scan_matcher map4_localization_launch/eagleye_twist_localization_launch eagleye_rt(gyro/odom/gnss fusion) ndt_scan_matcher map4_localization_launch/eagleye_pose_twist_localization_launch eagleye_rt(gyro/odom/gnss fusion) eagleye_rt(gyro/odom/gnss fusion)

In Autoware, you can set the pose estimator to GNSS by setting pose_estimator_mode:=gnss in map4_localization_component.launch.xml in autoware_launch package. Note that the output position might not appear to be in the point cloud maps if you are using maps that are not properly georeferenced. In the case of a single GNSS antenna, initial position estimation (dynamic initialization) can take several seconds to complete after starting to run in an environment where GNSS positioning is available.

Alternatively, the twist estimator can be set to Eagleye and the pose estimator to NDT by specifying pose_estimator_mode:=lidar in the same launch file. Unlike Eagleye position estimation, Eagleye twist estimation first outputs uncorrected raw values when activated, and then outputs corrected twists as soon as static initialization is complete.

"},{"location":"how-to-guides/others/eagleye-integration-guide/#executing-launch-files","title":"Executing Launch files","text":""},{"location":"how-to-guides/others/eagleye-integration-guide/#execution-command","title":"Execution command","text":"

Enable Eagleye in Autoware by switching the localization module in autoware.launch.xml and the pose_estimator_mode parameter in map4_localization_component.launch.xml in autoware.launch.xml.

When using Eagleye, comment out tier4_localization_component.launch.xml and start map4_localization_component.launch.xml in autoware.launch.xml.

  <!-- Localization -->\n<group if=\"$(var launch_localization)\">\n<!-- <include file=\"$(find-pkg-share autoware_launch)/launch/components/tier4_localization_component.launch.xml\"/> -->\n<include file=\"$(find-pkg-share autoware_launch)/launch/components/map4_localization_component.launch.xml\"/>\n</group>\n
"},{"location":"how-to-guides/others/eagleye-integration-guide/#notes-with-initialization","title":"Notes with initialization","text":"

Eagleye requires an initialization process for proper operation. Without initialization, the output for twist will be in the raw value, and the pose data will not be available.

The first step is static initialization, which involves allowing the Eagleye to remain stationary for approximately 5 seconds after startup to estimate the yaw-rate offset.

The next step is dynamic initialization, which involves running the Eagleye in a straight line for approximately 30 seconds. This process estimates the scale factor of wheel speed and azimuth angle. Once dynamic initialization is complete, the Eagleye will be able to provide corrected twist and pose data.

"},{"location":"how-to-guides/others/fixing-dependent-package-versions/","title":"Fixing dependent package versions","text":""},{"location":"how-to-guides/others/fixing-dependent-package-versions/#fixing-dependent-package-versions","title":"Fixing dependent package versions","text":"

Autoware manages dependent package versions in autoware.repos. For example, let's say you make a branch in autoware.universe and add new features. Suppose you update other dependencies with vcs pull after cutting a branch from autoware.universe. Then the version of autoware.universe you are developing and other dependencies will become inconsistent, and the entire Autoware build will fail. We recommend saving the dependent package versions by executing the following command when starting the development.

vcs export src --exact > my_autoware.repos\n
"},{"location":"how-to-guides/others/running-autoware-without-cuda/","title":"Running Autoware without CUDA","text":""},{"location":"how-to-guides/others/running-autoware-without-cuda/#running-autoware-without-cuda","title":"Running Autoware without CUDA","text":"

Although CUDA installation is recommended to achieve better performance for object detection and traffic light recognition in Autoware Universe, it is possible to run these algorithms without CUDA. The following subsections briefly explain how to run each algorithm in such an environment.

"},{"location":"how-to-guides/others/running-autoware-without-cuda/#running-2d3d-object-detection-without-cuda","title":"Running 2D/3D object detection without CUDA","text":"

Autoware Universe's object detection can be run using one of five possible configurations:

  • lidar_centerpoint
  • lidar_apollo_instance_segmentation
  • lidar-apollo + tensorrt_yolo
  • lidar-centerpoint + tensorrt_yolo
  • euclidean_cluster

Of these five configurations, only the last one (euclidean_cluster) can be run without CUDA. For more details, refer to the euclidean_cluster module's README file.

"},{"location":"how-to-guides/others/running-autoware-without-cuda/#running-traffic-light-detection-without-cuda","title":"Running traffic light detection without CUDA","text":"

For traffic light recognition (both detection and classification), there are two modules that require CUDA:

  • traffic_light_ssd_fine_detector
  • traffic_light_classifier

To run traffic light detection without CUDA, set enable_fine_detection to false in the traffic light launch file. Doing so disables the traffic_light_ssd_fine_detector such that traffic light detection is handled by the map_based_traffic_light_detector module instead.

To run traffic light classification without CUDA, set use_gpu to false in the traffic light classifier launch file. Doing so will force the traffic_light_classifier to use a different classification algorithm that does not require CUDA or a GPU.

"},{"location":"installation/","title":"Installation","text":""},{"location":"installation/#installation","title":"Installation","text":""},{"location":"installation/#target-platforms","title":"Target platforms","text":"

Autoware targets the platforms listed below. It may change in future versions of Autoware.

The Autoware Foundation provides no support on other platforms than those listed below.

"},{"location":"installation/#architecture","title":"Architecture","text":"
  • amd64
  • arm64
"},{"location":"installation/#minimum-hardware-requirements","title":"Minimum hardware requirements","text":"

Info

Autoware is scalable and can be customized to work with distributed or less powerful hardware. The minimum hardware requirements given below are just a general recommendation. However, performance will be improved with more cores, RAM and a higher-spec graphics card or GPU core.

  • CPU with 8 cores
  • 16GB RAM
  • [Optional] NVIDIA GPU (4GB RAM)

Although GPU is not required to run basic functionality, it is mandatory to enable the following neural network related functions:

  • LiDAR based object detection
  • Camera based object detection
  • Traffic light detection and classification

For details of how to enable object detection and traffic light detection/classification without a GPU, refer to the Running Autoware without CUDA.

"},{"location":"installation/#installing-autoware","title":"Installing Autoware","text":"

There are two ways to set up Autoware. Choose one according to your preference.

If any issues occur during installation, refer to the Support page.

"},{"location":"installation/#1-docker-installation","title":"1. Docker installation","text":"

Docker can ensure that all developers in a project have a common, consistent development environment. It is recommended for beginners, casual users, people who are unfamiliar with Ubuntu.

For more information, refer to the Docker installation guide.

"},{"location":"installation/#2-source-installation","title":"2. Source installation","text":"

Source installation is for the cases where more granular control of the installation environment is needed. It is recommended for experienced users or people who want to customize their environment. Note that some problems may occur depending on your local environment.

For more information, refer to the source installation guide.

"},{"location":"installation/#installing-related-tools","title":"Installing related tools","text":"

Some other tools are required depending on the evaluation you want to do. For example, to run an end-to-end simulation you need to install an appropriate simulator.

For more information, see here.

"},{"location":"installation/#additional-settings-for-developers","title":"Additional settings for developers","text":"

There are also tools and settings for developers, such as Shells or IDEs.

For more information, see here.

"},{"location":"installation/additional-settings-for-developers/","title":"Additional settings for developers","text":""},{"location":"installation/additional-settings-for-developers/#additional-settings-for-developers","title":"Additional settings for developers","text":""},{"location":"installation/additional-settings-for-developers/#console-settings-for-ros-2","title":"Console settings for ROS 2","text":""},{"location":"installation/additional-settings-for-developers/#colorizing-logger-output","title":"Colorizing logger output","text":"

By default, ROS 2 logger doesn't colorize the output. To colorize it, write the following in your .bashrc:

export RCUTILS_COLORIZED_OUTPUT=1\n
"},{"location":"installation/additional-settings-for-developers/#customizing-the-format-of-logger-output","title":"Customizing the format of logger output","text":"

By default, ROS 2 logger doesn't output detailed information such as file name, function name, or line number. To customize it, write the following in your .bashrc:

export RCUTILS_CONSOLE_OUTPUT_FORMAT=\"[{severity} {time}] [{name}]: {message} ({function_name}() at {file_name}:{line_number})\"\n

For more options, see here.

"},{"location":"installation/additional-settings-for-developers/#network-settings-for-ros-2","title":"Network settings for ROS 2","text":"

ROS 2 employs DDS, and the configuration of ROS 2 and DDS is described separately. For ROS 2 networking concepts, refer to the official documentation.

"},{"location":"installation/additional-settings-for-developers/#ros-2-network-setting","title":"ROS 2 network setting","text":"

ROS 2 multicasts data on the local network by default. Therefore, when you develop in an office, the data flows over the local network of your office. It may cause collisions of packets or increases in network traffic.

To avoid these, there are two options.

  • Localhost-only communication
  • Same domain only communication on the local network

Unless you plan to use multiple host computers on the local network, localhost-only communication is recommended. For details, refer to the sections below.

"},{"location":"installation/additional-settings-for-developers/#enabling-localhost-only-communication","title":"Enabling localhost-only communication","text":"

Write the following in your .bashrc: For more information, see the ROS 2 documentation.

export ROS_LOCALHOST_ONLY=1\n

If you export ROS_LOCALHOST_ONLY=1, MULTICAST must be enabled at the loopback address. To verify that MULTICAST is enabled, use the following command.

$ ip link show lo\n1: lo: <LOOPBACK,MULTICAST,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000\n

If the word MULTICAST is not printed, use the following command to enable it.

sudo ip link set lo multicast on\n
"},{"location":"installation/additional-settings-for-developers/#same-domain-only-communication-on-the-local-network","title":"Same domain only communication on the local network","text":"

ROS 2 uses ROS_DOMAIN_ID to create groups and communicate between machines in the groups. Since all ROS 2 nodes use domain ID 0 by default, it may cause unintended interference.

To avoid it, set a different domain ID for each group in your .bashrc:

# Replace X with the Domain ID you want to use\n# Domain ID should be a number in range [0, 101] (inclusive)\nexport ROS_DOMAIN_ID=X\n

Also confirm that ROS_LOCALHOST_ONLY is 0 by using the following command.

echo $ROS_LOCALHOST_ONLY # If the output is 1, localhost has priority.\n

For more information, see the ROS 2 Documentation.

"},{"location":"installation/additional-settings-for-developers/#dds-settings","title":"DDS settings","text":"

Autoware uses DDS for inter-node communication. ROS 2 documentation recommends users to tune DDS to utilize its capability. Especially, receive buffer size is the critical parameter for Autoware. If the parameter is not large enough, Autoware will failed in receiving large data like point cloud or image.

"},{"location":"installation/additional-settings-for-developers/#tuning-dds","title":"Tuning DDS","text":"

Unless customized, CycloneDDS is adopted by default. For example, to execute Autoware with CycloneDDS, prepare a config file. A sample config file is given below. Save it as cyclonedds_config.xml.

<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n<CycloneDDS xmlns=\"https://cdds.io/config\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd\">\n<Domain Id=\"any\">\n<General>\n<Interfaces>\n<NetworkInterface autodetermine=\"true\" priority=\"default\" multicast=\"default\" />\n</Interfaces>\n<AllowMulticast>default</AllowMulticast>\n<MaxMessageSize>65500B</MaxMessageSize>\n</General>\n<Internal>\n<SocketReceiveBufferSize min=\"10MB\"/>\n<Watermarks>\n<WhcHigh>500kB</WhcHigh>\n</Watermarks>\n</Internal>\n</Domain>\n</CycloneDDS>\n

This configuration is mostly taken from Eclipse Cyclone DDS:Run-time configuration documentation. You can see why each value is set as such under the documentation link.

Set the config file path and enlarge the Linux kernel maximum buffer size before launching Autoware.

export CYCLONEDDS_URI=file:///absolute/path/to/cyclonedds_config.xml\nsudo sysctl -w net.core.rmem_max=2147483647\n

For more information, Refer to ROS 2 documentation. Reading user guide for chosen DDS is helpful for more understanding.

"},{"location":"installation/additional-settings-for-developers/#tuning-dds-for-multiple-host-computers-for-advanced-users","title":"Tuning DDS for multiple host computers (for advanced users)","text":"

When Autoware runs on multiple host computers, IP Fragmentation should be taken into account. As ROS 2 documentation recommends, parameters for IP Fragmentation should be set as shown in the following example.

sudo sysctl -w net.ipv4.ipfrag_time=3\nsudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728     # (128 MB)\n
"},{"location":"installation/autoware/docker-installation-devel/","title":"Docker installation for development","text":""},{"location":"installation/autoware/docker-installation-devel/#docker-installation-for-development","title":"Docker installation for development","text":""},{"location":"installation/autoware/docker-installation-devel/#prerequisites","title":"Prerequisites","text":"
  • Git
  • For NVIDIA Jetson devices, install JetPack >= 5.0
"},{"location":"installation/autoware/docker-installation-devel/#how-to-set-up-a-development-environment","title":"How to set up a development environment","text":"

  1. Clone autowarefoundation/autoware and move to the directory.

    git clone https://github.com/autowarefoundation/autoware.git\ncd autoware\n

  2. You can install the dependencies either manually or using the provided Ansible script.

Note: Before installing NVIDIA libraries, confirm and agree with the licenses.

  • CUDA
"},{"location":"installation/autoware/docker-installation-devel/#installing-dependencies-manually","title":"Installing dependencies manually","text":"
  • Install Nvidia CUDA
  • Install Docker Engine
  • Install NVIDIA Container Toolkit
  • Install rocker
"},{"location":"installation/autoware/docker-installation-devel/#installing-dependencies-using-ansible","title":"Installing dependencies using Ansible","text":"

Be very careful with this method. Make sure you read and confirmed all the steps in the Ansible configuration before using it.

If you've manually installed the dependencies, you can skip this section.

./setup-dev-env.sh docker\n

You might need to log out and log back to make the current user able to use docker.

"},{"location":"installation/autoware/docker-installation-devel/#how-to-set-up-a-workspace","title":"How to set up a workspace","text":"

Warning

Before proceeding, confirm and agree with the NVIDIA Deep Learning Container license. By pulling and using the Autoware Universe images, you accept the terms and conditions of the license.

  1. Create the autoware_map directory for map data later.

    mkdir ~/autoware_map\n

  2. Pull the Docker image

    docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

  3. Launch a Docker container.

    • For amd64 architecture computers with NVIDIA GPU:

      rocker --nvidia --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

    • If you want to run container without using NVIDIA GPU, or for arm64 architecture computers:

      rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

      For detailed reason could be found here

    For more advanced usage, see here.

    After that, move to the workspace in the container:

    cd autoware\n

  4. Create the src directory and clone repositories into it.

    mkdir src\nvcs import src < autoware.repos\n

  5. Update dependent ROS packages.

    The dependency of Autoware may change after the Docker image was created. In that case, you need to run the following commands to update the dependency.

    sudo apt update\nrosdep update\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  6. Build the workspace.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

    If there is any build issue, refer to Troubleshooting.

"},{"location":"installation/autoware/docker-installation-devel/#how-to-update-a-workspace","title":"How to update a workspace","text":"

  1. Update the Docker image.

    docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

  2. Launch a Docker container.

    • For amd64 architecture computers:

      rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

    • If you want to run container without using NVIDIA GPU, or for arm64 architecture computers:

      rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

  3. Update the .repos file.

    cd autoware\ngit pull\n

  4. Update the repositories.

    vcs import src < autoware.repos\nvcs pull src\n

  5. Build the workspace.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"installation/autoware/docker-installation-prebuilt/","title":"Docker installation for quick start","text":""},{"location":"installation/autoware/docker-installation-prebuilt/#docker-installation-for-quick-start","title":"Docker installation for quick start","text":""},{"location":"installation/autoware/docker-installation-prebuilt/#how-to-set-up-a-development-environment","title":"How to set up a development environment","text":"

  1. Installing dependencies manually

    • Install Docker Engine
    • Install NVIDIA Container Toolkit
    • Install rocker
"},{"location":"installation/autoware/docker-installation-prebuilt/#how-to-set-up-a-workspace","title":"How to set up a workspace","text":"

  1. Create the autoware_map directory for map data later.

    mkdir ~/autoware_map\n

  2. Launch a Docker container.

    rocker --nvidia --x11 --user --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-prebuilt\n

    For more advanced usage, see here.

  3. Run Autoware simulator

    Inside the container, you can run the Autoware simulation by following this tutorial:

    planning simulation

    rosbag replay simulation.

"},{"location":"installation/autoware/docker-installation/","title":"Docker installation","text":""},{"location":"installation/autoware/docker-installation/#docker-installation","title":"Docker installation","text":"

Info

Since this page explains Docker-specific information, it is recommended to see Source installation as well if you need detailed information.

Here are two ways to install Autoware by docker:

  • The first way is to start Autoware with prebuilt image, this is a quick start, this way you can only run Autoware simulator and not develop Autoware, it is only suitable for beginners
  • The second way is to start Autoware with devel image, which supports developing and running Autoware using docker
"},{"location":"installation/autoware/docker-installation/#docker-installation-for-quick-start","title":"Docker installation for quick start","text":"

docker installation for quick start

"},{"location":"installation/autoware/docker-installation/#docker-installation-for-development","title":"Docker installation for development","text":"

docker installation for development

"},{"location":"installation/autoware/docker-installation/#troubleshooting","title":"Troubleshooting","text":"

Here are solutions for a few specific errors:

"},{"location":"installation/autoware/docker-installation/#cuda-error-forward-compatibility-was-attempted-on-non-supported-hw","title":"cuda error: forward compatibility was attempted on non supported hw","text":"

When starting Docker with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error:

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.\nERROR: Command return non-zero exit code (see above): 125\n

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.

"},{"location":"installation/autoware/docker-installation/#docker-with-nvidia-gpu-fails-to-start-autoware-on-arm64-devices","title":"Docker with NVIDIA gpu fails to start Autoware on arm64 devices","text":"

When starting Docker with GPU support enabled for NVIDIA graphics on arm64 devices, e.g. NVIDIA jetson AGX xavier, you may receive the following error:

nvidia@xavier:~$ rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64\n...\n\nCollecting staticx==0.12.3\nDownloading https://files.pythonhosted.org/packages/92/ff/d9960ea1f9db48d6044a24ee0f3d78d07bcaddf96eb0c0e8806f941fb7d3/staticx-0.12.3.tar.gz (68kB)\nComplete output from command python setup.py egg_info:\nTraceback (most recent call last):\nFile \"\", line 1, in\nFile \"/tmp/pip-install-m_nm8mya/staticx/setup.py\", line 4, in\nfrom wheel.bdist_wheel import bdist_wheel\nModuleNotFoundError: No module named 'wheel'\n\nCommand \"python setup.py egg_info\" failed with error code 1 in /tmp/pip-install-m_nm8mya/staticx/\n...\n

This error exists in current version of rocker tool, which relates to the os_detection function of rocker.

To fix this error, temporary modification of rocker source code is required, which is not recommended.

At current stage, it is recommended to run docker without NVIDIA gpu enabled for arm64 devices:

rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda\n

This tutorial will be updated after official fix from rocker.

"},{"location":"installation/autoware/docker-installation/#tips","title":"Tips","text":""},{"location":"installation/autoware/docker-installation/#non-native-arm64-system","title":"Non-native arm64 System","text":"

This section describes a process to run arm64 systems on amd64 systems using qemu-user-static.

Initially, your system is usually incompatible with arm64 systems. To check that:

$ docker run --rm -t arm64v8/ubuntu uname -m\nWARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested\nstandard_init_linux.go:228: exec user process caused: exec format error\n

Installing qemu-user-static enables us to run arm64 images on amd64 systems.

$ sudo apt-get install qemu-user-static\n$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes\n$ docker run --rm -t arm64v8/ubuntu uname -m\nWARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested\naarch64\n

To run Autoware's Docker images of arm64 architecture, add the suffix -arm64.

$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64\nWARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested\nroot@5b71391ad50f:/autoware#\n
"},{"location":"installation/autoware/source-installation/","title":"Source installation","text":""},{"location":"installation/autoware/source-installation/#source-installation","title":"Source installation","text":""},{"location":"installation/autoware/source-installation/#prerequisites","title":"Prerequisites","text":"

  • OS

    • Ubuntu 22.04

  • ROS

    • ROS 2 Humble

    For ROS 2 system dependencies, refer to REP-2000.

  • Git
    • Registering SSH keys to GitHub is preferable.
sudo apt-get -y update\nsudo apt-get -y install git\n

Note: If you wish to use ROS 2 Galactic on Ubuntu 20.04, refer to installation instruction from galactic branch, but be aware that Galactic version of Autoware might not have latest features.

"},{"location":"installation/autoware/source-installation/#how-to-set-up-a-development-environment","title":"How to set up a development environment","text":"

  1. Clone autowarefoundation/autoware and move to the directory.

    git clone https://github.com/autowarefoundation/autoware.git\ncd autoware\n

  2. If you are installing Autoware for the first time, you can automatically install the dependencies by using the provided Ansible script.

    ./setup-dev-env.sh\n

    If you encounter any build issues, please consult the Troubleshooting section for assistance.

Info

Before installing NVIDIA libraries, please ensure that you have reviewed and agreed to the licenses.

  • CUDA
  • cuDNN
  • TensorRT

Note

The following items will be automatically installed. If the ansible script doesn't work or if you already have different versions of dependent libraries installed, please install the following items manually.

  • Install ROS 2
  • Install ROS 2 Dev Tools
  • Install the RMW Implementation
  • Install pacmod
  • Install Autoware Core dependencies
  • Install Autoware Universe dependencies
  • Install pre-commit dependencies
  • Install Nvidia CUDA
  • Install Nvidia cuDNN and TensorRT
"},{"location":"installation/autoware/source-installation/#how-to-set-up-a-workspace","title":"How to set up a workspace","text":"

  1. Create the src directory and clone repositories into it.

    Autoware uses vcstool to construct workspaces.

    cd autoware\nmkdir src\nvcs import src < autoware.repos\n

  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. You might need to run rosdep update before rosdep install.

    source /opt/ros/humble/setup.bash\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  3. Build the workspace.

    Autoware uses colcon to build workspaces. For more advanced options, refer to the documentation.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

    If there is any build issue, refer to Troubleshooting.

"},{"location":"installation/autoware/source-installation/#how-to-update-a-workspace","title":"How to update a workspace","text":"

  1. Update the .repos file.

    cd autoware\ngit pull\n

  2. Update the repositories.

    vcs import src < autoware.repos\nvcs pull src\n

    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.

    For more information, refer to the official documentation.

  3. Install dependent ROS packages.

    source /opt/ros/humble/setup.bash\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  4. Build the workspace.

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"installation/related-tools/","title":"Installation of related tools","text":""},{"location":"installation/related-tools/#installation-of-related-tools","title":"Installation of related tools","text":"

Warning

Under Construction

"},{"location":"support/","title":"Support","text":""},{"location":"support/#support","title":"Support","text":"

This page explains several support resources.

  • Support guidelines pages explain the support mechanisms and guidelines.
  • Troubleshooting pages explain solutions for common issues.
  • Docs guide pages explain related documentation sites.
"},{"location":"support/docs-guide/","title":"Docs guide","text":""},{"location":"support/docs-guide/#docs-guide","title":"Docs guide","text":"

This page explains several documentation sites that are useful for Autoware and ROS development.

  • The Autoware Foundation is the official site of the Autoware Foundation. You can learn about the Autoware community here.
  • Autoware Documentation (this site) is the central documentation site for Autoware maintained by the Autoware community. General software-related information of Autoware is aggregated here.
  • Autoware Universe Documentation has READMEs and design documents of software components.
  • ROS Docs Guide explains the ROS 1 and ROS 2 documentation infrastructure.
"},{"location":"support/support-guidelines/","title":"Support guidelines","text":""},{"location":"support/support-guidelines/#support-guidelines","title":"Support guidelines","text":"

This page explains the support mechanisms we provide.

Warning

Before asking for help, search and read this documentation site carefully. Also, follow the discussion guidelines for discussions.

Choose appropriate resources depending on what kind of help you need and read the detailed description in the sections below.

  • Documentation sites
    • Various information
  • GitHub Discussions
    • Questions
    • Unconfirmed bugs
    • Feature requests
    • Design discussions
  • GitHub Issues
    • Confirmed bugs
  • Discord
    • Instant messaging between contributors
  • ROS Discourse
    • General topics that should be widely announced
"},{"location":"support/support-guidelines/#documentation-sites","title":"Documentation sites","text":"

Docs guide shows the list of useful documentation sites. Visit them and see if there is any information related to your problem.

Note that the documentation sites aren't always up-to-date and perfect. If you find out that some information is wrong, unclear, or missing in Autoware docs, feel free to submit a pull request following the contribution guidelines.

Warning

Since this documentation site is still under construction, there are some empty pages.

"},{"location":"support/support-guidelines/#github-discussions","title":"GitHub Discussions","text":"

If you encounter a problem with Autoware, check existing issues and questions and search for similar issues first.

  • Issues

    Note that Autoware has multiple repositories listed in autoware.repos. It is recommended to search across the repositories.

  • Questions

If no answer was found, create a new question thread here. If your question is not answered within a week, then @mention the maintainers to remind them.

Also, there are other discussion types such as feature requests or design discussions. Feel free to open or join such discussions.

If you don't know how to create a discussion, refer to GitHub Docs.

"},{"location":"support/support-guidelines/#github-issues","title":"GitHub Issues","text":"

If you have a problem and you have confirmed it is a bug, find the appropriate repository and create a new issue there. If you can't determine the appropriate repository, ask the maintainers for help by creating a new discussion in the Q&A category.

Warning

Do not create issues for questions or unconfirmed bugs. If such issues are created, maintainers will transfer them to GitHub Discussions.

If you want to fix the bug by yourself, discuss the approach with maintainers and submit a pull request.

"},{"location":"support/support-guidelines/#discord","title":"Discord","text":"

Autoware has a Discord server for casual communication between contributors.

The Autoware Discord server is a good place for the following activities:

  • Introduce yourself to the community.
  • Chat with contributors.
  • Take a quick straw poll.

Note that it is not the right place to get help for your issues.

"},{"location":"support/support-guidelines/#ros-discourse","title":"ROS Discourse","text":"

If you want to widely discuss a topic with the general Autoware and ROS community or ask a question not related to Autoware's bugs, post to the Autoware category on ROS Discourse.

Warning

Do not post questions about bugs to ROS Discourse!

"},{"location":"support/troubleshooting/","title":"Troubleshooting","text":""},{"location":"support/troubleshooting/#troubleshooting","title":"Troubleshooting","text":""},{"location":"support/troubleshooting/#setup-issues","title":"Setup issues","text":""},{"location":"support/troubleshooting/#cuda-related-errors","title":"CUDA-related errors","text":"

When installing CUDA, errors may occur because of version conflicts. To resolve these types of errors, try one of the following methods:

  • Unhold all CUDA-related libraries and rerun the setup script.

    sudo apt-mark unhold  \\\n\"cuda*\"             \\\n\"libcudnn*\"         \\\n\"libnvinfer*\"       \\\n\"libnvonnxparsers*\" \\\n\"libnvparsers*\"     \\\n\"tensorrt*\"         \\\n\"nvidia*\"\n\n./setup-dev-env.sh\n

  • Uninstall all CUDA-related libraries and rerun the setup script.

    sudo apt purge        \\\n\"cuda*\"             \\\n\"libcudnn*\"         \\\n\"libnvinfer*\"       \\\n\"libnvonnxparsers*\" \\\n\"libnvparsers*\"     \\\n\"tensorrt*\"         \\\n\"nvidia*\"\n\nsudo apt autoremove\n\n./setup-dev-env.sh\n

Warning

Note that this may break your system and run carefully.

  • Run the setup script without installing CUDA-related libraries.

    ./setup-dev-env.sh --no-nvidia\n

Warning

Note that some components in Autoware Universe require CUDA, and only the CUDA version in the env file is supported at this time. Autoware may work with other CUDA versions, but those versions are not supported and functionality is not guaranteed.

"},{"location":"support/troubleshooting/#build-issues","title":"Build issues","text":""},{"location":"support/troubleshooting/#insufficient-memory","title":"Insufficient memory","text":"

Building Autoware requires a lot of memory, and your machine can freeze or crash if memory runs out during a build. To avoid this problem, 16-32GB of swap should be configured.

# Optional: Check the current swapfile\nfree -h\n\n# Remove the current swapfile\nsudo swapoff /swapfile\nsudo rm /swapfile\n\n# Create a new swapfile\nsudo fallocate -l 32G /swapfile\nsudo chmod 600 /swapfile\nsudo mkswap /swapfile\nsudo swapon /swapfile\n\n# Optional: Check if the change is reflected\nfree -h\n

For more detailed configuration steps, along with an explanation of swap, refer to Digital Ocean's \"How To Add Swap Space on Ubuntu 20.04\" tutorial

If there are too many CPU cores (more than 64) in your machine, it might requires larger memory. A workaround here is to limit the job number while building.

MAKEFLAGS=\"-j4\" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

You can adjust -j4 to any number based on your system. For more details, see the manual page of GNU make.

By reducing the number of packages built in parallel, you can also reduce the amount of memory used. In the following example, the number of packages built in parallel is set to 1, and the number of jobs used by make is limited to 1.

MAKEFLAGS=\"-j1\" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --parallel-workers 1\n

Note

By lowering both the number of packages built in parallel and the number of jobs used by make, you can reduce the memory usage. However, this also means that the build process takes longer.

"},{"location":"support/troubleshooting/#errors-when-using-the-latest-version-of-autoware","title":"Errors when using the latest version of Autoware","text":"

If you are working with the latest version of Autoware, issues can occur due to out-of-date software or old build files.

To resolve these types of problems, first try cleaning your build artifacts and rebuilding:

rm -rf build/ install/ log/\ncolcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n

If the error is not resolved, remove src/ and update your workspace according to installation type (Docker / source).

Warning

Before removing src/, confirm that there are no modifications in your local environment that you want to keep!

If errors still persist after trying the steps above, delete the entire workspace, clone the repository once again and restart the installation process.

rm -rf autoware/\ngit clone https://github.com/autowarefoundation/autoware.git\n
"},{"location":"support/troubleshooting/#errors-when-using-a-fixed-version-of-autoware","title":"Errors when using a fixed version of Autoware","text":"

In principle, errors should not occur when using a fixed version. That said, possible causes include:

  • ROS 2 has been updated with breaking changes.
    • For confirmation, check the Packaging and Release Management tag on ROS Discourse.
  • Your local environment is broken.
    • Confirm your .bashrc file, environment variables, and library versions.

In addition to the causes listed above, there are two common misunderstandings around the use of fixed versions.

  1. You used a fixed version for autowarefoundation/autoware only. All of the repository versions in the .repos file must be specified in order to use a completely fixed version.

  2. You didn't update the workspace after changing the branch of autowarefoundation/autoware. Changing the branch of autowarefoundation/autoware does not affect the files under src/. You have to run the vcs import command to update them.

"},{"location":"support/troubleshooting/#error-when-building-python-package","title":"Error when building python package","text":"

During building the following issue can occurs

pkg_resources.extern.packaging.version.InvalidVersion: Invalid version: '0.23ubuntu1'\n

The error is due to the fact that for versions between 66.0.0 and 67.5.0 setuptools enforces the python packages to be PEP-440 conformant. Since version 67.5.1 setuptools has a fallback that makes it possible to work with old packages again.

The solution is to update setuptools to the newest version with the following command

pip install --upgrade setuptools\n
"},{"location":"support/troubleshooting/#dockerrocker-issues","title":"Docker/rocker issues","text":"

If any errors occur when running Autoware with Docker or rocker, first confirm that your Docker installation is working correctly by running the following commands:

docker run --rm -it hello-world\ndocker run --rm -it ubuntu:latest\n

Next, confirm that you are able to access the base Autoware image that is stored on the GitHub Packages website

docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:latest\n
"},{"location":"support/troubleshooting/#runtime-issues","title":"Runtime issues","text":""},{"location":"support/troubleshooting/#performance-related-issues","title":"Performance related issues","text":"

Symptoms:

  • Autoware is running slower than expected
  • Messages show up late in RViz2
  • Point clouds are lagging
  • Camera images are lagging behind
  • Point clouds or markers flicker on RViz2
  • When multiple subscribers use the same publishers, the message rate drops

If you have any of these symptoms, please the Performance Troubleshooting page.

"},{"location":"support/troubleshooting/#map-does-not-display-when-running-the-planning-simulator","title":"Map does not display when running the Planning Simulator","text":"

When running the Planning Simulator, the most common reason for the map not being displayed in RViz is because the map path has not been specified correctly in the launch command. You can confirm if this is the case by searching for Could not find lanelet map under {path-to-map-dir}/lanelet2_map.osm errors in the log.

Another possible reason is that map loading is taking a long time due to poor DDS performance. For this, please visit the Performance Troubleshooting page.

"},{"location":"support/troubleshooting/performance-troubleshooting/","title":"Performance Troubleshooting","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#performance-troubleshooting","title":"Performance Troubleshooting","text":"

Overall symptoms:

  • Autoware is running slower than expected
  • Messages show up late in RViz2
  • Point clouds are lagging
  • Camera images are lagging behind
  • Point clouds or markers flicker on RViz2
  • When multiple subscribers use the same publishers, the message rate drops
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnostic-steps","title":"Diagnostic Steps","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#check-if-multicast-is-enabled","title":"Check if multicast is enabled","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms","title":"Target symptoms","text":"
  • When multiple subscribers use the same publishers, the message rate drops
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis","title":"Diagnosis","text":"

Make sure that the multicast is enabled for your interface.

For example when you run following:

source /opt/ros/humble/setup.bash\nros2 run demo_nodes_cpp talker\n

If you get the error message selected interface \"{your-interface-name}\" is not multicast-capable: disabling multicast, this should be fixed.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution","title":"Solution","text":"

Run the following command to allow multicast:

sudo ip link set multicast on {your-interface-name}\n

This way DDS will function as intended and multiple subscribers can receive data from a single publisher without any significant degradation in performance.

This is a temporary solution. And will be reverted once the computer restarts.

To make it permanent either,

  • Create a service to run this on startup (recommended)

  • OR put following lines to the ~/.bashrc file:

    if [ ! -e /tmp/multicast_is_set ]; then\nsudo ip link set lo multicast on\ntouch /tmp/multicast_is_set\nfi\n
    • This will probably ask for password on the terminal every time you restart the computer.
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-compilation-flags","title":"Check the compilation flags","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms_1","title":"Target symptoms","text":"
  • Autoware is running slower than expected
  • Point clouds are lagging
  • When multiple subscribers use the same publishers, the message rate drops even further
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_1","title":"Diagnosis","text":"

Check the ~/.bash_history file to see if there are any colcon build directives without -DCMAKE_BUILD_TYPE=Release or -DCMAKE_BUILD_TYPE=RelWithDebInfo flags at all.

Even if a build starts with these flags but same workspace gets compiled without these flags, it will still be a slow build in the end.

In addition, the nodes will run slow in general, especially the pointcloud_preprocessor nodes.

Example issue: issue2597

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_1","title":"Solution","text":"
  • Remove the build, install and optionally log folders in the main autoware folder.

  • Compile the Autoware with either Release or RelWithDebInfo tags:

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n# Or build with debug flags too (comparable performance but you can debug too)\ncolcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo\n
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-dds-settings","title":"Check the DDS settings","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms_2","title":"Target symptoms","text":"
  • Autoware is running slower than expected
  • Messages show up late in RViz2
  • Point clouds are lagging
  • Camera images are lagging behind
  • When multiple subscribers use the same publishers, the message rate drops
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-rmw-ros-middleware-implementation","title":"Check the RMW (ROS Middleware) implementation","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_2","title":"Diagnosis","text":"

Run following to check the middleware used:

echo $RMW_IMPLEMENTATION\n

The return line should be rmw_cyclonedds_cpp. If not, apply the solution.

If you are using a different DDS middleware, we might not have official support for it just yet.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_2","title":"Solution","text":"

Add export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp as a separate line in you ~/.bashrc file.

"},{"location":"support/troubleshooting/performance-troubleshooting/#check-if-the-cyclonedds-is-configured-correctly","title":"Check if the CycloneDDS is configured correctly","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_3","title":"Diagnosis","text":"

Run following to check the configuration .xml file of the CycloneDDS:

echo $CYCLONEDDS_URI\n

The return line should be a valid path pointing to an .xml file with CycloneDDS configuration.

Also check if the file is configured correctly:

cat !{echo $CYCLONEDDS_URI}\n

This should print the .xml file on the terminal.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_3","title":"Solution","text":"

Follow DDS settings:Tuning DDS documentation and make sure:

  • you have export CYCLONEDDS_URI=/absolute_path_to_your/cyclonedds_config.xml as a line on your ~/.bashrc file.
  • you have the cyclonedds_config.xml with the configuration provided in the documentation.
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-the-linux-kernel-maximum-buffer-size","title":"Check the Linux kernel maximum buffer size","text":""},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_4","title":"Diagnosis","text":"
  • Run: sysctl net.core.rmem_max, it should return at least net.core.rmem_max = 2147483647.
    • This parameter specifies the maximum size of the \"receive buffer\" for each network connection, which determines the maximum amount of data that can be held in memory at any given time. By increasing the maximum buffer size, the operating system can accommodate larger bursts of data, which can help prevent network congestion and reduce packet loss, resulting in faster and more reliable data transfers.
  • Run: sysctl net.ipv4.ipfrag_time, it should return around: net.ipv4.ipfrag_time = 3
    • The \"net.ipv4.ipfrag_time\" parameter specifies the maximum time in seconds that the kernel should retain partially fragmented IP packets before discarding them. The default value for this parameter is usually set to 30 seconds, but it may vary depending on the specific operating system and configuration.
    • By setting this parameter to a lower value, such as 3 seconds, the kernel can free up memory resources more quickly by discarding partially fragmented packets that are no longer needed, which can help improve the overall performance and stability of the system.
  • Run: sysctl net.ipv4.ipfrag_high_thresh, it should return at around: net.ipv4.ipfrag_high_thresh = 134217728
    • The \"net.ipv4.ipfrag_high_thresh\" parameter specifies the high watermark threshold for the number of partially fragmented packets allowed in the kernel IP packet reassembly queue. When the number of partially fragmented packets in the queue exceeds this threshold, the kernel will start to drop newly arrived packets until the number of partially fragmented packets drops below the threshold.
    • By setting this parameter to a higher value, such as 134217728 (128 MB), the kernel can accommodate a larger number of partially fragmented packets in the queue, which can help improve the performance of network applications that transfer large amounts of data, such as file transfer protocols and multimedia streaming applications.

More info on these values: Cross-vendor tuning

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_4","title":"Solution","text":"

Either:

  • Create the following file: sudo touch /etc/sysctl.d/10-cyclone-max.conf (recommended)

    • Edit the file to contain (sudo gedit /etc/sysctl.d/10-cyclone-max.conf):

      net.core.rmem_max=2147483647\nnet.ipv4.ipfrag_time=3\nnet.ipv4.ipfrag_high_thresh=134217728 # (128 MB)\n

      • Either restart the computer or run following to enable the changes:

        sudo sysctl -w net.core.rmem_max=2147483647\nsudo sysctl -w net.ipv4.ipfrag_time=3\nsudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728\n

  • OR put following lines to the ~/.bashrc file:

    if [ ! -e /tmp/kernel_network_conf_is_set ]; then\nsudo sysctl -w net.core.rmem_max=2147483647\nsudo sysctl -w net.ipv4.ipfrag_time=3\nsudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728 # (128 MB)\nfi\n
    • This will probably ask for password on the terminal every time you restart the computer.
"},{"location":"support/troubleshooting/performance-troubleshooting/#check-if-ros-localhost-only-communication-is-enabled","title":"Check if ROS localhost only communication is enabled","text":"
  • If you are using multi computer setup, please skip this check.
  • Enabling ROS localhost only communication can help improve the performance of ROS by reducing network traffic and avoiding potential conflicts with other devices on the network.
  • Also check Enable localhost-only communication
"},{"location":"support/troubleshooting/performance-troubleshooting/#target-symptoms_3","title":"Target symptoms","text":"
  • You see topics that shouldn't exist
  • You see point clouds that don't belong to your machine
    • They might be from another computer running ROS 2 on your network
  • Point clouds or markers flicker on RViz2
    • Another publisher (on another machine) may be publishing on the same topic as your node does.
    • Causing the flickering.
"},{"location":"support/troubleshooting/performance-troubleshooting/#diagnosis_5","title":"Diagnosis","text":"

Run following to check it:

echo $ROS_LOCALHOST_ONLY\n

The return line should be 1. If not, apply the solution.

"},{"location":"support/troubleshooting/performance-troubleshooting/#solution_5","title":"Solution","text":"
  • Add export $ROS_LOCALHOST_ONLY=1 as a separate line in you ~/.bashrc file.
    • This environment variable tells ROS to only use the loopback network interface (i.e., localhost) for communication, rather than using the network interface card (NIC) for Ethernet or Wi-Fi. This can reduce network traffic and potential conflicts with other devices on the network, resulting in better performance and stability.
"},{"location":"tutorials/","title":"Simulation tutorials","text":""},{"location":"tutorials/#simulation-tutorials","title":"Simulation tutorials","text":"

Simulations provide a way of verifying Autoware's functionality before field testing with an actual vehicle. There are three main types of simulation that can be run ad hoc or via a scenario runner.

"},{"location":"tutorials/#simulation-methods","title":"Simulation methods","text":""},{"location":"tutorials/#ad-hoc-simulation","title":"Ad hoc simulation","text":"

Ad hoc simulation is a flexible method for running basic simulations on your local machine, and is the recommended method for anyone new to Autoware.

"},{"location":"tutorials/#scenario-simulation","title":"Scenario simulation","text":"

Scenario simulation uses a scenario runner to run more complex simulations based on predefined scenarios. It is often run automatically for continuous integration purposes, but can also be run on a local machine.

"},{"location":"tutorials/#simulation-types","title":"Simulation types","text":""},{"location":"tutorials/#planning-simulation","title":"Planning simulation","text":"

Planning simulation uses simple dummy data to test the Planning and Control components - specifically path generation, path following and obstacle avoidance. It verifies that a vehicle can reach a goal destination while avoiding pedestrians and surrounding cars, and is another method for verifying the validity of Lanelet2 maps. It also allows for testing of traffic light handling.

"},{"location":"tutorials/#how-does-planning-simulation-work","title":"How does planning simulation work?","text":"
  1. Generate a path to the goal destination
  2. Control the car along the generated path
  3. Detect and avoid any humans or other vehicles on the way to the goal destination
"},{"location":"tutorials/#rosbag-replay-simulation","title":"Rosbag replay simulation","text":"

Rosbag replay simulation uses prerecorded rosbag data to test the following aspects of the Localization and Perception components:

  • Localization: Estimation of the vehicle's location on the map by matching sensor and vehicle feedback data to the map.
  • Perception: Using sensor data to detect, track and predict dynamic objects such as surrounding cars, pedestrians, and other objects

By repeatedly playing back the data, this simulation type can also be used for endurance testing.

"},{"location":"tutorials/#digital-twin-simulation","title":"Digital twin simulation","text":"

Digital twin simulation is a simulation type that is able to produce realistic data and simulate almost the entire system. It is also commonly referred to as end-to-end simulation.

"},{"location":"tutorials/ad-hoc-simulation/","title":"Ad hoc simulation","text":""},{"location":"tutorials/ad-hoc-simulation/#ad-hoc-simulation","title":"Ad hoc simulation","text":"

Warning

Under Construction

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/","title":"Planning simulation","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#planning-simulation","title":"Planning simulation","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#preparation","title":"Preparation","text":"

Download and unpack a sample map.

  • You can also download the map manually.
gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd'\nunzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip\n

Note

Sample map: Copyright 2020 TIER IV, Inc.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#basic-simulations","title":"Basic simulations","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#lane-driving-scenario","title":"Lane driving scenario","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#1-launch-autoware","title":"1. Launch Autoware","text":"
source ~/autoware/install/setup.bash\nros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/autoware_map/sample-map-planning vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit\n

Warning

Note that you cannot use ~ instead of $HOME here.

If ~ is used, the map will fail to load.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#2-set-an-initial-pose-for-the-ego-vehicle","title":"2. Set an initial pose for the ego vehicle","text":"

a) Click the 2D Pose estimate button in the toolbar, or hit the P key.

b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the initial pose. An image representing the vehicle should now be displayed.

Warning

Remember to set the initial pose of the car in the same direction as the lane.

To confirm the direction of the lane, check the arrowheads displayed on the map.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#3-set-a-goal-pose-for-the-ego-vehicle","title":"3. Set a goal pose for the ego vehicle","text":"

a) Click the 2D Goal Pose button in the toolbar, or hit the G key.

b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the goal pose. If done correctly, you will see a planned path from initial pose to goal pose.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#4-start-the-ego-vehicle","title":"4. Start the ego vehicle","text":"

Now you can start the ego vehicle driving by clicking the AUTO button on OperationMode in AutowareStatePanel. Alteratively, you can manually start the vehicle by running the following command:

source ~/autoware/install/setup.bash\nros2 service call /api/operation_mode/change_to_autonomous autoware_adapi_v1_msgs/srv/ChangeOperationMode {}\n

After that, you can see AUTONOMOUS sign on OperationMode and AUTO button is grayed out.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#parking-scenario","title":"Parking scenario","text":"

  1. Set an initial pose and a goal pose, and engage the ego vehicle.

  2. When the vehicle approaches the goal, it will switch from lane driving mode to parking mode.

  3. After that, the vehicle will reverse into the destination parking spot.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#advanced-simulations","title":"Advanced Simulations","text":""},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#placing-dummy-objects","title":"Placing dummy objects","text":"
  1. Click the 2D Dummy Car or 2D Dummy Pedestrian button in the toolbar.
  2. Set the pose of the dummy object by clicking and dragging on the map.

  3. Set the velocity of the object in Tool Properties -> 2D Dummy Car/Pedestrian panel.

    !!! note

    Changes to the velocity parameter will only affect objects placed after the parameter is changed.

  4. Delete any dummy objects placed in the view by clicking the Delete All Objects button in the toolbar.

  5. Click the Interactive button in the toolbar to make the dummy object interactive.

  6. For adding an interactive dummy object, press SHIFT and click the right click.

  7. For deleting an interactive dummy object, press ALT and click the right click.

  8. For moving an interactive dummy object, hold the right click drag and drop the object.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#traffic-light-recognition-simulation","title":"Traffic light recognition simulation","text":"

By default, traffic lights on the map are all treated as if they are set to green. As a result, when a path is created that passed through an intersection with a traffic light, the ego vehicle will drive through the intersection without stopping.

The following steps explain how to set and reset traffic lights in order to test how the Planning component will respond.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#set-traffic-light","title":"Set traffic light","text":"

  1. Go to Panels -> Add new panel, select TrafficLightPublishPanel, and then press OK.

  2. In TrafficLightPublishPanel, set the ID and color of the traffic light.

  3. Click the SET button.

  4. Finally, click the PUBLISH button to send the traffic light status to the simulator. Any planned path that goes past the selected traffic light will then change accordingly.

By default, Rviz should display the ID of each traffic light on the map. You can have a closer look at the IDs by zooming in the region or by changing the View type.

In case the IDs are not displayed, try the following troubleshooting steps:

a) In the Displays panel, find the traffic_light_id topic by toggling the triangle icons next to Map > Lanelet2VectorMap > Namespaces.

b) Check the traffic_light_id checkbox.

c) Reload the topic by clicking the Map checkbox twice.

"},{"location":"tutorials/ad-hoc-simulation/planning-simulation/#updatereset-traffic-light","title":"Update/Reset traffic light","text":"

You can update the color of the traffic light by selecting the next color (in the image it is GREEN) and clicking SET button. In the image the traffic light in front of the ego vehicle changed from RED to GREEN and the vehicle restarted.

To remove a traffic light from TrafficLightPublishPanel, click the RESET button.

Reference video tutorials

"},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/","title":"Rosbag replay simulation","text":""},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#rosbag-replay-simulation","title":"Rosbag replay simulation","text":""},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#steps","title":"Steps","text":"

  1. Download and unpack a sample map.

    • You can also download the map manually.
    gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI'\nunzip -d ~/autoware_map/ ~/autoware_map/sample-map-rosbag.zip\n

  2. Download the sample rosbag files.

    • You can also download the rosbag files manually.
    gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1VnwJx9tI3kI_cTLzP61ktuAJ1ChgygpG'\nunzip -d ~/autoware_map/ ~/autoware_map/sample-rosbag.zip\n
"},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#note","title":"Note","text":"
  • Sample map and rosbag: Copyright 2020 TIER IV, Inc.
  • Due to privacy concerns, the rosbag does not contain image data, which will cause:
    • Traffic light recognition functionality cannot be tested with this sample rosbag.
    • Object detection accuracy is decreased.
"},{"location":"tutorials/ad-hoc-simulation/rosbag-replay-simulation/#how-to-run-a-rosbag-replay-simulation","title":"How to run a rosbag replay simulation","text":"

  1. Launch Autoware.

    source ~/autoware/install/setup.bash\nros2 launch autoware_launch logging_simulator.launch.xml map_path:=$HOME/autoware_map/sample-map-rosbag vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit\n

    Note that you cannot use ~ instead of $HOME here.

  2. Play the sample rosbag file.

    source ~/autoware/install/setup.bash\nros2 bag play ~/autoware_map/sample-rosbag/sample.db3 -r 0.2 -s sqlite3\n

  3. To focus the view on the ego vehicle, change the Target Frame in the RViz Views panel from viewer to base_link.

  4. To switch the view to Third Person Follower etc, change the Type in the RViz Views panel.

Reference video tutorials

"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/","title":"MORAI Sim: Drive","text":""},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#morai-sim-drive","title":"MORAI Sim: Drive","text":"

Note

Any kind of for-profit activity with the trial version of the MORAI SIM:Drive is strictly prohibited.

"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#hardware-requirements","title":"Hardware requirements","text":"Minimum PC Specs OS Windows 10, Ubuntu 20.04, Ubuntu 18.04, Ubuntu 16.04 CPU Intel i5-9600KF or AMD Ryzen 5 3500X RAM DDR4 16GB GPU RTX2060 Super Required PC Specs OS Windows 10, Ubuntu 20.04, Ubuntu 18.04, Ubuntu 16.04 CPU Intel i9-9900K or AMD Ryzen 7 3700X (or higher) RAM DDR4 64GB (or higher) GPU RTX2080Ti or higher"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#application-and-download","title":"Application and Download","text":"

Only for AWF developers, trial license for 3 months can be issued. Download the application form and send to Hyeongseok Jeon

After the trial license is issued, you can login to MORAI Sim:Drive via Launchers (Windows/Ubuntu)

CAUTION: Do not use the Launchers in the following manual

"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#technical-documents","title":"Technical Documents","text":"

as Oct. 2022, our simulation version is ver.22.R3 but the english manual is under construction.

Be aware that the following manuals are for ver.22.R2

  • MORAI Sim:Drive Manual
  • ITRI BUS Odd tutorial
  • Tutorial for rosbag replay with Tacoma Airport
"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial/#technical-support","title":"Technical Support","text":"

Hyeongseok Jeon will give full technical support

  • hsjeon@morai.ai
  • Hyeongseok Jeon#2355 in Discord
"},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial/","title":"AWSIM simulator","text":""},{"location":"tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial/#awsim-simulator","title":"AWSIM simulator","text":"

AWSIM is a simulator for Autoware development and testing. To get started, please follow the official instruction provided by TIER IV.

"},{"location":"tutorials/scenario-simulation/","title":"Scenario simulation","text":""},{"location":"tutorials/scenario-simulation/#scenario-simulation","title":"Scenario simulation","text":"

Warning

Under Construction

"},{"location":"tutorials/scenario-simulation/planning-simulation/installation/","title":"Installation","text":""},{"location":"tutorials/scenario-simulation/planning-simulation/installation/#installation","title":"Installation","text":"

This document contains step-by-step instruction on how to build AWF Autoware Core/Universe with scenario_simulator_v2.

"},{"location":"tutorials/scenario-simulation/planning-simulation/installation/#prerequisites","title":"Prerequisites","text":"
  1. Autoware has been built and installed
"},{"location":"tutorials/scenario-simulation/planning-simulation/installation/#how-to-build","title":"How to build","text":"

  1. Navigate to the Autoware workspace:

    cd autoware\n

  2. Import Simulator dependencies:

    vcs import src < simulator.repos\n

  3. Install dependent ROS packages:

    source /opt/ros/humble/setup.bash\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n

  4. Build the workspace:

    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release\n
"},{"location":"tutorials/scenario-simulation/planning-simulation/random-test-simulation/","title":"Random test simulation","text":""},{"location":"tutorials/scenario-simulation/planning-simulation/random-test-simulation/#random-test-simulation","title":"Random test simulation","text":"

Note

Running the Scenario Simulator requires some additional steps on top of building and installing Autoware, so make sure that Scenario Simulator installation has been completed first before proceeding.

"},{"location":"tutorials/scenario-simulation/planning-simulation/random-test-simulation/#running-steps","title":"Running steps","text":"

  1. Move to the workspace directory where Autoware and the Scenario Simulator have been built.

  2. Source the workspace setup script:

    source install/setup.bash\n

  3. Run the simulation:

    ros2 launch random_test_runner random_test.launch.py \\\narchitecture_type:=awf/universe \\\nsensor_model:=sample_sensor_kit \\\nvehicle_model:=sample_vehicle\n

For more information about supported parameters, refer to the random_test_runner documentation.

"},{"location":"tutorials/scenario-simulation/planning-simulation/scenario-test-simulation/","title":"Scenario test simulation","text":""},{"location":"tutorials/scenario-simulation/planning-simulation/scenario-test-simulation/#scenario-test-simulation","title":"Scenario test simulation","text":"

Note

Running the Scenario Simulator requires some additional steps on top of building and installing Autoware, so make sure that Scenario Simulator installation has been completed first before proceeding.

"},{"location":"tutorials/scenario-simulation/planning-simulation/scenario-test-simulation/#running-steps","title":"Running steps","text":"

  1. Move to the workspace directory where Autoware and the Scenario Simulator have been built.

  2. Source the workspace setup script:

    source install/setup.bash\n

  3. Run the simulation:

    ros2 launch scenario_test_runner scenario_test_runner.launch.py \\\narchitecture_type:=awf/universe \\\nrecord:=false \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample.yaml' \\\nsensor_model:=sample_sensor_kit \\\nvehicle_model:=sample_vehicle\n

Reference video tutorials

"},{"location":"tutorials/scenario-simulation/rosbag-replay-simulation/driving-log-replayer/","title":"Driving Log Replayer","text":""},{"location":"tutorials/scenario-simulation/rosbag-replay-simulation/driving-log-replayer/#driving-log-replayer","title":"Driving Log Replayer","text":"

Driving Log Replayer is an evaluation tool for Autoware. To get started, follow the official instruction provided by TIER IV.

"}]} \ No newline at end of file diff --git a/pr-385/sitemap.xml.gz b/pr-385/sitemap.xml.gz index a53117459e9e1c99200493feeb3544af92fb1d64..7c7b0d797c5b34b10c5483cdbcf31d75481ba94d 100644 GIT binary patch delta 15 WcmaFN_n41OzMF$XZpKEoSatv?Wdw8p delta 15 WcmaFN_n41OzMF&N=#-6YvFrdWI|Ua2