diff --git a/.github/sync-files.yaml b/.github/sync-files.yaml index 2d3cf84f184..8c8b67efe79 100644 --- a/.github/sync-files.yaml +++ b/.github/sync-files.yaml @@ -15,8 +15,23 @@ - source: .github/workflows/spell-check-differential.yaml - source: .github/workflows/sync-files.yaml - source: .markdown-link-check.json + pre-commands: | + sd -s -- \ + ' "pattern": "^http://localhost"' \ + ' "pattern": "^https://www\\.autosar\\.org/*" + }, + { + "pattern": "^http://localhost"' \ + {source} - source: .markdownlint.yaml - source: .pre-commit-config-optional.yaml - source: .prettierignore - source: .prettierrc.yaml - source: .yamllint.yaml + +- repository: autowarefoundation/autoware-documentation + files: + - source: mkdocs-base.yaml + dest: mkdocs.yaml + pre-commands: | + sd " - macros" " - macros:\n include_yaml:\n - autoware_interfaces: yaml/autoware-interfaces.yaml" {source} diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml index 27b80781403..5f2d09d4148 100644 --- a/.github/workflows/deploy-docs.yaml +++ b/.github/workflows/deploy-docs.yaml @@ -4,6 +4,7 @@ on: push: branches: - main + - galactic paths: - mkdocs.yaml - "**/*.md" @@ -21,7 +22,7 @@ jobs: prevent-no-label-execution: uses: autowarefoundation/autoware-github-actions/.github/workflows/prevent-no-label-execution.yaml@v1 with: - label: documentation + label: deploy-docs deploy-docs: needs: prevent-no-label-execution diff --git a/.github/workflows/github-release.yaml b/.github/workflows/github-release.yaml index 19e1e9c12e5..95ebb8725f6 100644 --- a/.github/workflows/github-release.yaml +++ b/.github/workflows/github-release.yaml @@ -26,8 +26,8 @@ jobs: REF_NAME="${{ github.ref_name }}" fi - echo ::set-output name=ref-name::"$REF_NAME" - echo ::set-output name=tag-name::"${REF_NAME#beta/}" + echo "ref-name=$REF_NAME" >> $GITHUB_OUTPUT + echo "tag-name=${REF_NAME#beta/}" >> $GITHUB_OUTPUT - name: Check out repository uses: actions/checkout@v3 @@ -39,7 +39,7 @@ jobs: id: set-target-name run: | if [[ "${{ steps.set-tag-name.outputs.ref-name }}" =~ "beta/" ]]; then - echo ::set-output name=target-name::"${{ steps.set-tag-name.outputs.ref-name }}" + echo "target-name=${{ steps.set-tag-name.outputs.ref-name }}" >> $GITHUB_OUTPUT fi - name: Create a local tag for beta branches @@ -62,7 +62,7 @@ jobs: verb=edit fi - echo ::set-output name=verb::"$verb" + echo "verb=$verb" >> $GITHUB_OUTPUT env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/pre-commit-optional.yaml b/.github/workflows/pre-commit-optional.yaml index 93e05dc2c79..e754ecab24f 100644 --- a/.github/workflows/pre-commit-optional.yaml +++ b/.github/workflows/pre-commit-optional.yaml @@ -9,8 +9,11 @@ jobs: steps: - name: Check out repository uses: actions/checkout@v3 + with: + fetch-depth: 0 - name: Run pre-commit uses: autowarefoundation/autoware-github-actions/pre-commit@v1 with: pre-commit-config: .pre-commit-config-optional.yaml + base-branch: origin/${{ github.base_ref }} diff --git a/.github/workflows/pre-commit.yaml b/.github/workflows/pre-commit.yaml index 7fd1cc90fe9..b231dbda879 100644 --- a/.github/workflows/pre-commit.yaml +++ b/.github/workflows/pre-commit.yaml @@ -5,7 +5,7 @@ on: jobs: pre-commit: - if: ${{ github.event.repository.private }} + if: ${{ github.event.repository.private }} # Use pre-commit.ci for public repositories runs-on: ubuntu-latest steps: - name: Generate token @@ -20,11 +20,6 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} - - name: Set git config - uses: autowarefoundation/autoware-github-actions/set-git-config@v1 - with: - token: ${{ steps.generate-token.outputs.token }} - - name: Run pre-commit uses: autowarefoundation/autoware-github-actions/pre-commit@v1 with: diff --git a/.markdown-link-check.json b/.markdown-link-check.json index dec3db1ad1c..1c743d60343 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -1,9 +1,15 @@ { "aliveStatusCodes": [200, 206, 403], "ignorePatterns": [ + { + "pattern": "^https://www\\.autosar\\.org/*" + }, { "pattern": "^http://localhost" }, + { + "pattern": "^http://127\\.0\\.0\\.1" + }, { "pattern": "^https://github.com/.*/discussions/new" } diff --git a/.markdownlint.yaml b/.markdownlint.yaml index df1f518dc0d..babaaa1f158 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -3,6 +3,8 @@ default: true MD013: false MD024: siblings_only: true +MD029: + style: ordered MD033: false MD041: false MD046: false diff --git a/.pre-commit-config-optional.yaml b/.pre-commit-config-optional.yaml index a805f1201c4..3b43f9ae113 100644 --- a/.pre-commit-config-optional.yaml +++ b/.pre-commit-config-optional.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/tcort/markdown-link-check - rev: v3.10.0 + rev: v3.11.2 hooks: - id: markdown-link-check - args: [--config=.markdown-link-check.json] + args: [--quiet, --config=.markdown-link-check.json] diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 312cc00d5e4..df39989a6c0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,10 +1,10 @@ ci: - autofix_commit_msg: "ci(pre-commit): autofix" + autofix_commit_msg: "style(pre-commit): autofix" autoupdate_commit_msg: "ci(pre-commit): autoupdate" repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.3.0 + rev: v4.4.0 hooks: - id: check-json - id: check-merge-conflict @@ -19,29 +19,29 @@ repos: args: [--markdown-linebreak-ext=md] - repo: https://github.com/igorshubovych/markdownlint-cli - rev: v0.32.1 + rev: v0.32.2 hooks: - id: markdownlint args: [-c, .markdownlint.yaml, --fix] - repo: https://github.com/pre-commit/mirrors-prettier - rev: v2.7.1 + rev: v3.0.0-alpha.4 hooks: - id: prettier - repo: https://github.com/adrienverge/yamllint - rev: v1.27.1 + rev: v1.28.0 hooks: - id: yamllint exclude: .*.param.yaml - repo: https://github.com/shellcheck-py/shellcheck-py - rev: v0.8.0.4 + rev: v0.9.0.2 hooks: - id: shellcheck - repo: https://github.com/scop/pre-commit-shfmt - rev: v3.5.1-1 + rev: v3.6.0-1 hooks: - id: shfmt args: [-w, -s, -i=4] diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c493cad4da5..8dbcfb8510a 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -60,7 +60,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -conduct@autoware.org. +. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the diff --git a/README.md b/README.md index 516fd776393..7a8c9aab60b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ -# autoware-documentation +# Autoware documentation - This repository contains the [MkDocs](https://www.mkdocs.org/) source files for the [Autoware documentation hosted on GitHub Pages](https://autowarefoundation.github.io/autoware-documentation/main/). - Since Autoware is made up of [multiple repositories](https://github.com/autowarefoundation/), a central documentation repository is important to make information accessible from a single place. - For more information about Autoware and its related repositories, refer to the [Autoware Foundation's organization profile](https://github.com/autowarefoundation/.github/blob/main/profile/README.md). + +## Contributions + +To contribute to this repository, see the [documentation guidelines](https://autowarefoundation.github.io/autoware-documentation/main/contributing/documentation-guidelines/). diff --git a/docs/.pages b/docs/.pages index 8b862c4651d..918e5a02a8f 100644 --- a/docs/.pages +++ b/docs/.pages @@ -4,6 +4,8 @@ nav: - tutorials - how-to-guides - design + - Reference HW: reference-hw - contributing - datasets - support + - Competitions: autoware-competitions diff --git a/docs/assets/images/detection_area_turnaround_time.png b/docs/assets/images/detection_area_turnaround_time.png new file mode 100644 index 00000000000..f42d74ba267 Binary files /dev/null and b/docs/assets/images/detection_area_turnaround_time.png differ diff --git a/docs/assets/images/ring_outlier_filter_minor_faults.png b/docs/assets/images/ring_outlier_filter_minor_faults.png new file mode 100644 index 00000000000..b64b3746cad Binary files /dev/null and b/docs/assets/images/ring_outlier_filter_minor_faults.png differ diff --git a/docs/assets/images/ring_outlier_filter_turnaround_time.png b/docs/assets/images/ring_outlier_filter_turnaround_time.png new file mode 100644 index 00000000000..496e68f21fa Binary files /dev/null and b/docs/assets/images/ring_outlier_filter_turnaround_time.png differ diff --git a/docs/assets/js/mathjax.js b/docs/assets/js/mathjax.js new file mode 100644 index 00000000000..117b04607f2 --- /dev/null +++ b/docs/assets/js/mathjax.js @@ -0,0 +1,16 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true, + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex", + }, +}; + +document$.subscribe(() => { + MathJax.typesetPromise(); +}); diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/.pages b/docs/autoware-competitions/.pages similarity index 100% rename from docs/design/autoware-interfaces/ad-api/use-cases/.pages rename to docs/autoware-competitions/.pages diff --git a/docs/autoware-competitions/images/ai_challenge_2023.png b/docs/autoware-competitions/images/ai_challenge_2023.png new file mode 100644 index 00000000000..7cde3090545 Binary files /dev/null and b/docs/autoware-competitions/images/ai_challenge_2023.png differ diff --git a/docs/autoware-competitions/images/autoware_challenge_2023.png b/docs/autoware-competitions/images/autoware_challenge_2023.png new file mode 100644 index 00000000000..ed7d0c317be Binary files /dev/null and b/docs/autoware-competitions/images/autoware_challenge_2023.png differ diff --git a/docs/autoware-competitions/index.md b/docs/autoware-competitions/index.md new file mode 100644 index 00000000000..641e7617967 --- /dev/null +++ b/docs/autoware-competitions/index.md @@ -0,0 +1,12 @@ +# Autoware Competitions + +This page is a collection of the links to the competitions that are related to the Autoware Foundation. + +| Title | Status | Description | +| :-----------------------------------------------------------: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | Ongoing | **[Autoware / TIER IV Challenge 2023](https://autoware.org/autoware-challenge-2023)**
**Date:** May 15, 2023 - Nov. 1st, 2023

As one of the main contributors of Autoware, TIER IV has been facing many difficult challenges through development, and TIER IV would like to sponsor a challenge to solve such engineering challenges. Any researchers, students, individuals or organizations are welcome to participate and submit their solution to any of the challenges we propose. | +| | Ongoing | **[Japan Automotive AI Challenge 2023](https://www.jsae.or.jp/jaaic/)**
**Registration:** June 5, 2023 - July 14, 2023
**Qualifiers:** July 3, 2023 - Aug. 31, 2023
**Finals:** Nov. 12, 2023

In this competition, we focus on challenging tasks posed by autonomous driving in factory environments and aim to develop Autoware-based AD software that can overcome them. The qualifiers use the [digital twin autonomous driving simulator AWSIM](https://tier4.github.io/AWSIM/) to complete specific tasks within a virtual environment. Teams that make it to the finals have the opportunity to run their software on actual vehicles in a test course in Japan. | + +## Proposing New Competition + +If you want add a new competition to this page, please propose it in a TSC meeting and get confirmation from the AWF. diff --git a/docs/contributing/coding-guidelines/languages/cpp.md b/docs/contributing/coding-guidelines/languages/cpp.md index 5138f59a8bb..ab4d39e4cbf 100644 --- a/docs/contributing/coding-guidelines/languages/cpp.md +++ b/docs/contributing/coding-guidelines/languages/cpp.md @@ -4,8 +4,201 @@ Under Construction -Refer to the following links for now: +## References -- -- -- +Follow the guidelines below if a rule is not defined on this page. + +1. +2. +3. + +Also, it is encouraged to apply Clang-Tidy to each file. +For the usage, see [Applying Clang-Tidy to ROS packages](../../../how-to-guides/others/applying-clang-tidy-to-ros-packages.md). + +Note that not all rules are covered by Clang-Tidy. + +## Style rules + +### Include header files in the defined order (required, partially automated) + +#### Rationale + +- 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. + +#### Reference + +- + +#### Example + +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 + +```cpp +// Compliant +#include "my_header.hpp" + +#include "my_package/foo.hpp" + +#include +#include + +#include + +#include +#include +``` + +If you use `""` and `<>` properly, `ClangFormat` in `pre-commit` sorts headers automatically. + +Do not define macros between `#include` lines because it prevents automatic sorting. + +```cpp +// Non-compliant +#include +#include + +#define EIGEN_MPL2_ONLY +#include "my_header.hpp" +#include "my_package/foo.hpp" + +#include + +#include + +#include +#include +``` + +Instead, define macros before `#include` lines. + +```cpp +// Compliant +#define EIGEN_MPL2_ONLY + +#include "my_header.hpp" + +#include "my_package/foo.hpp" + +#include +#include +#include + +#include + +#include +#include +``` + +If there are any reasons for defining macros at a specific position, write a comment before the macro. + +```cpp +// Compliant +#include "my_header.hpp" + +#include "my_package/foo.hpp" + +#include +#include + +#include + +#include +#include + +// For the foo bar reason, the FOO_MACRO must be defined here. +#define FOO_MACRO +#include +``` + +### Use lower snake case for function names (required, partially automated) + +#### Rationale + +- It is consistent with the C++ standard library. +- It is consistent with other programming languages such as Python and Rust. + +#### Exception + +- For member functions of classes inherited from external project classes such as Qt, follow that naming convention. + +#### Reference + +- + +#### Example + +```cpp +void function_name() +{ +} +``` + +### Use upper camel case for enum names (required, partially automated) + +#### Rationale + +- It is consistent with ROS 2 core packages. + +#### Exception + +- Enums defined in the `rosidl` file can use other naming conventions. + +#### Reference + +- (Refer to "15. Enumerations") + +#### Example + +```cpp +enum class Color +{ + Red, Green, Blue +} +``` + +### Use lower snake case for constant names (required, partially automated) + +#### Rationale + +- It is consistent with ROS 2 core packages. +- It is consistent with `std::numbers`. + +#### Exception + +- Constants defined in the `rosidl` file can use other naming conventions. + +#### Reference + +- + +#### Example + +```cpp +constexpr double gravity = 9.80665; +``` + +### Count acronyms and contractions of compound words as one word (required, partially automated) + +#### Rationale + +- To clarify the boundaries of words when acronyms are consecutive. + +#### Reference + +- + +#### Example + +```cpp +class RosApi; +RosApi ros_api; +``` diff --git a/docs/contributing/coding-guidelines/ros-nodes/.pages b/docs/contributing/coding-guidelines/ros-nodes/.pages index 797e85cadc6..e446c5224d5 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/.pages +++ b/docs/contributing/coding-guidelines/ros-nodes/.pages @@ -5,7 +5,6 @@ nav: - directory-structure.md - launch-files.md - message-guidelines.md - - naming.md - parameters.md - task-scheduling.md - topic-namespaces.md diff --git a/docs/contributing/coding-guidelines/ros-nodes/console-logging.md b/docs/contributing/coding-guidelines/ros-nodes/console-logging.md index e76373d1b1e..aa052d82527 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/console-logging.md +++ b/docs/contributing/coding-guidelines/ros-nodes/console-logging.md @@ -1,5 +1,188 @@ # Console logging -!!! warning +ROS 2 logging is a powerful tool for understanding and debugging ROS nodes. - Under Construction +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](https://docs.ros.org/en/humble/Concepts/About-Logging.html). + +## Logging use cases in Autoware + +- 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. + +## Rules + +### Choose appropriate severity levels (required, non-automated) + +#### Rationale + +It's confusing if severity levels are inappropriate as follows: + +- Useless messages are marked as `FATAL`. +- Very important error messages are marked as `INFO`. + +#### Example + +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. + +### Filter out unnecessary logs by setting logging options (required, non-automated) + +#### Rationale + +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. + +#### Example + +Use the `--log-level {level}` option to change the minimum level of logs to be displayed: + +```xml + + + + +``` + +If you want to disable only specific output targets, use the `--disable-stdout-logs`, `--disable-rosout-logs`, and/or `--disable-external-lib-logs` options: + +```xml + + + + +``` + +```xml + + + + +``` + +### Use throttled logging when the log is unnecessarily shown repeatedly (required, non-automated) + +#### Rationale + +If tons of logs are shown on the console, people miss important message. + +#### Example + +While waiting for some messages, throttled logs are usually enough. +In such cases, wait about 5 seconds as a reference value. + +```cpp +// Compliant +void FooNode::on_timer() { + if (!current_pose_) { + RCLCPP_ERROR_THROTTLE(get_logger(), *get_clock(), 5000, "Waiting for current_pose_."); + return; + } +} + +// Non-compliant +void FooNode::on_timer() { + if (!current_pose_) { + RCLCPP_ERROR(get_logger(), "Waiting for current_pose_."); + return; + } +} +``` + +#### Exception + +The following cases are acceptable even if it's not throttled. + +- The message is really worth displaying every time. +- The message level is DEBUG. + +### Do not depend on rclcpp::Node in core library classes but depend only on rclcpp/logging.hpp (advisory, non-automated) + +#### Rationale + +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. + +#### Example + +```cpp +// Compliant +#include + +class FooCore { +public: + explicit FooCore(const rclcpp::Logger & logger) : logger_(logger) {} + + void process() { + RCLCPP_INFO(logger_, "message"); + } + +private: + rclcpp::Logger logger_; +}; + +// Compliant +// Note that logs aren't published to `/rosout` if the logger name is different from the node name. +#include + +class FooCore { + void process() { + RCLCPP_INFO(rclcpp::get_logger("foo_core_logger"), "message"); + } +}; + + +// Non-compliant +#include + +class FooCore { +public: + explicit FooCore(const rclcpp::NodeOptions & node_options) : node_("foo_core_node", node_options) {} + + void process() { + RCLCPP_INFO(node_.get_logger(), "message"); + } + +private: + rclcpp::Node node_; +}; +``` + +## Tips + +### Use rqt_console to filter logs + +To filter logs, using `rqt_console` is useful: + +```bash +ros2 run rqt_console rqt_console +``` + +For more details, refer to [ROS 2 Documentation](https://docs.ros.org/en/rolling/Tutorials/Beginner-CLI-Tools/Using-Rqt-Console/Using-Rqt-Console.html). + +### Useful marco expressions + +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: + +```cpp +void FooNode::on_timer() { + RCLCPP_DEBUG(get_logger(), "file: %s, line: %s, function: %s" __FILE__, __LINE__, __FUNCTION__); +} +``` + +The example output is as follows: + +> [DEBUG] [1671720414.395456931] [foo]: file: /path/to/file.cpp, line: 100, function: on_timer diff --git a/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md b/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md index c298da9bedf..29c1252bd52 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md +++ b/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md @@ -1,5 +1,128 @@ # Coordinate system -!!! warning +## Overview - Under Construction +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. + +## How coordinates are used in Autoware + +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](http://docs.ros.org/en/galactic/Concepts/About-Tf2.html). + +## TF tree + +In Autoware, a common coordinate system structure is shown below: + +```mermaid +graph TD + /earth --> /map + /map --> /base_link + /base_link --> /imu + /base_link --> /lidar + /base_link --> /gnss + /base_link --> /radar + /base_link --> /camera_link + /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](#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. + +### Estimating the `base_link` frame by using the other sensors + +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`: + +```yaml +x: estimated frame name +y: localization method/source +``` + +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. + +#### Example by the GNSS/INS sensor + +For the integrated GNSS/INS we use the following frames: + +```mermaid +flowchart LR + 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: + +- + +### Coordinate Axes Conventions + +We are using East, North, Up (ENU) coordinate axes convention by default throughout the stack. + +```yaml +X+: East +Y+: North +Z+: Up +``` + +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. + +```yaml +Rotation around: + X+: roll + Y+: pitch + Z+: yaw +``` + +References: + +- + +## How they can be created + +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](../../../how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md). + +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. diff --git a/docs/contributing/coding-guidelines/ros-nodes/directory-structure.md b/docs/contributing/coding-guidelines/ros-nodes/directory-structure.md index 64f845dd056..3e4de9866a0 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/directory-structure.md +++ b/docs/contributing/coding-guidelines/ros-nodes/directory-structure.md @@ -3,3 +3,73 @@ !!! warning Under Construction + +## C++ package + +```txt + +├─ config +│ ├─ foo_ros.param.yaml +│ └─ foo_non_ros.yaml +├─ doc +│ ├─ foo_document.md +│ └─ foo_diagram.svg +├─ include +│ └─ +│ └─ foo_public.hpp +├─ launch +│ ├─ foo.launch.xml +│ └─ foo.launch.py +├─ schema +│ └─ foo_node.schema.json +├─ src +│ ├─ foo_node.cpp +│ ├─ foo_node.hpp +│ └─ foo_private.hpp +├─ test +│ └─ test_foo.cpp +├─ package.xml +├─ CMakeLists.txt +└─ README.md +``` + +### Directory descriptions + +#### `config` + +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. + +#### `doc` + +Place document files and link from README. + +#### `include` + +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: + +#### `launch` + +Place launch files (`.launch.xml` and `.launch.py`). + +#### `schema` + +Place parameter definition files. See [parameters](./parameters.md) for details. + +#### `src` + +Place source files and private header files. + +#### `test` + +Place source files for testing. See [unit testing](../../testing-guidelines/unit-testing.md) for details. + +## Python package + +T.B.D. diff --git a/docs/contributing/coding-guidelines/ros-nodes/launch-files.md b/docs/contributing/coding-guidelines/ros-nodes/launch-files.md index c39bd75e891..be31983a9f2 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/launch-files.md +++ b/docs/contributing/coding-guidelines/ros-nodes/launch-files.md @@ -1,5 +1,67 @@ # Launch files -!!! warning +## Overview - Under Construction +Autoware use ROS 2 launch system to startup the software. Please see the [official documentation](https://docs.ros.org/en/humble/Tutorials/Intermediate/Launch/Launch-Main.html) to get a basic understanding about ROS 2 Launch system if you are not familiar with it. + +## Guideline + +### The organization of launch files in Autoware + +Autoware mainly has two repositories related to launch file organization: the [autoware.universe](https://github.com/autowarefoundation/autoware.universe) and the [autoware_launch](https://github.com/autowarefoundation/autoware_launch). + +#### autoware.universe + +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](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture/#high-level-architecture-design), 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. + +#### autoware_launch + +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. + +```mermaid +graph LR +A11[logging_simulator.launch.xml]-.->A10[autoware.launch.xml] +A12[planning_simulator.launch.xml]-.->A10[autoware.launch.xml] +A13[e2e_simulator.launch.xml]-.->A10[autoware.launch.xml] + +A10-->A21[tier4_map_component.launch.xml] +A10-->A22[xxx.launch.py] +A10-->A23[tier4_localization_component.launch.xml] +A10-->A24[xxx.launch.xml] +A10-->A25[tier4_sensing_component.launch.xml] + +A23-->A30[localization.launch.xml] +A30-->A31[pose_estimator.launch.xml] +A30-->A32[util.launch.xml] +A30-->A33[pose_twist_fusion_filter.launch.xml] +A30-->A34[xxx.launch.xml] +A30-->A35[twist_estimator.launch.xml] + +A33-->A41[stop_filter.launch.xml] +A33-->A42[ekf_localizer.launch.xml] +A33-->A43[twist2accel.launch.xml] +``` + +### Add a new package in Autoware + +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](https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/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. + +## Parameter management + +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 integrating 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 “launch parameters” 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 “launch parameters” 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`. diff --git a/docs/contributing/coding-guidelines/ros-nodes/message-guidelines.md b/docs/contributing/coding-guidelines/ros-nodes/message-guidelines.md index cf17ac2beea..7417cd5b972 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/message-guidelines.md +++ b/docs/contributing/coding-guidelines/ros-nodes/message-guidelines.md @@ -2,7 +2,7 @@ ## Format -All messages should follow [ROS message description specification](https://docs.ros.org/en/galactic/Concepts/About-ROS-Interfaces.html#background). +All messages should follow [ROS message description specification](https://docs.ros.org/en/humble/Concepts/About-ROS-Interfaces.html#background). The accepted formats are: @@ -10,6 +10,14 @@ The accepted formats are: - `.srv` - `.action` +## Naming + +!!! warning "" + + Under Construction + +Use `Array` as a suffix when creating a plural type of a message. This suffix is commonly used in [common_interfaces](https://github.com/ros2/common_interfaces). + ## Default units All the fields by default have the following units depending on their types: @@ -53,7 +61,7 @@ For non-default units, use following suffixes: ## Message field types -For list of types supported by the ROS interfaces [see here](https://docs.ros.org/en/galactic/Concepts/About-ROS-Interfaces.html#field-types). +For list of types supported by the ROS interfaces [see here](https://docs.ros.org/en/humble/Concepts/About-ROS-Interfaces.html#field-types). Also copied here for convenience: diff --git a/docs/contributing/coding-guidelines/ros-nodes/parameters.md b/docs/contributing/coding-guidelines/ros-nodes/parameters.md index f04837d6753..53f5f058da2 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/parameters.md +++ b/docs/contributing/coding-guidelines/ros-nodes/parameters.md @@ -1,5 +1,173 @@ # Parameters -!!! warning +Autoware ROS nodes have declared parameters which values are provided during the node start up in the form of a parameter file. All the expected parameters with corresponding values should exist in the parameter file. Depending on the application, the parameter values might need to be modified. - Under Construction +Find more information on parameters from the official ROS documentation: + +- [Understanding ROS 2 Parameters](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html) +- [About ROS 2 Parameters](https://docs.ros.org/en/humble/Concepts/About-ROS-2-Parameters.html) + +## Workflow + +A ROS package which uses the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function should: + +- use the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) with out a default value +- create a parameter file +- create a schema file + +The rationale behind this workflow is to have a verified single source of truth to pass to the ROS node and to be used in the web documentation. The approach reduces the risk of using invalid parameter values and makes maintenance of documentation easier. This is achieved by: + +- [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) throws an exception if an expected parameter is missing in the parameter file +- the schema validates the parameter file in the CI and renders a parameter table, as depicted in the graphics below + + ```mermaid + flowchart TD + NodeSchema[Schema file: *.schema.json] + ParameterFile[Parameter file: *.param.yaml] + WebDocumentation[Web documentation table] + + NodeSchema -->|Validation| ParameterFile + NodeSchema -->|Generate| WebDocumentation + ``` + +Note: a parameter value can still be modified and bypass the validation, as there is no validation during runtime. + +## Declare Parameter Function + +It is the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function which sets the parameter values during a node startup. + +```cpp +declare_parameter("INSERT_PARAMETER_1_NAME"), +declare_parameter("INSERT_PARAMETER_N_NAME") +``` + +As there is no _default_value_ provided, the function throws an exception if a parameter were to be missing in the provided `*.param.yaml` file. Use a type from the _C++ Type_ column in the table below for the [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) function, replacing _INSERT_TYPE_. + +| ParameterType Enum | C++ Type | +| ------------------------- | -------------------------- | +| `PARAMETER_BOOL` | `bool` | +| `PARAMETER_INTEGER` | `int64_t` | +| `PARAMETER_DOUBLE` | `double` | +| `PARAMETER_STRING` | `std::string` | +| `PARAMETER_BYTE_ARRAY` | `std::vector` | +| `PARAMETER_BOOL_ARRAY` | `std::vector` | +| `PARAMETER_INTEGER_ARRAY` | `std::vector` | +| `PARAMETER_DOUBLE_ARRAY` | `std::vector` | +| `PARAMETER_STRING_ARRAY` | `std::vector` | + +The table has been derived from [Parameter Type](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterType.msg) and [Parameter Value](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/ParameterValue.msg). + +See example: _Lidar Apollo Segmentation TVM Nodes_ [declare function](https://github.com/autowarefoundation/autoware.universe/blob/f85c90b56ed4c7d6b52e787570e590cff786b28b/perception/lidar_apollo_segmentation_tvm_nodes/src/lidar_apollo_segmentation_tvm_node.cpp#L38) + +## Parameter File + +The parameter file is minimal as there is no need to provide the user with additional information, e.g., description or type. This is because the associated schema file provides the additional information. Use the template below as a starting point for a ROS node. + +```yaml +/**: + ros__parameters: + INSERT_PARAMETER_1_NAME: INSERT_PARAMETER_1_VALUE + INSERT_PARAMETER_N_NAME: INSERT_PARAMETER_N_VALUE +``` + +The parameter file path is `INSERT_PATH_TO_PACKAGE/config/` and parameter file name is `INSERT_NODE_NAME.param.yaml`. To adapt the template to the ROS node, replace each `INSERT_PARAMETER_..._NAME` and `INSERT_PARAMETER_..._VALUE` for all parameters. Each [declare_parameter(...)](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/classrclcpp_1_1Node.html#_CPPv4N6rclcpp4Node17declare_parameterERKNSt6stringERKN6rclcpp14ParameterValueERKN14rcl_interfaces3msg19ParameterDescriptorEb) takes one parameter as input. + +See example: _Lidar Apollo Segmentation TVM Nodes_ [parameter file](https://github.com/autowarefoundation/autoware.universe/blob/main/perception/lidar_apollo_segmentation_tvm_nodes/config/lidar_apollo_segmentation_tvm_nodes.param.yaml) + +Note: `/**` is used instead of the explicit node namespace, this allows the parameter file to be passed to a ROS node which has been [remapped](https://design.ros2.org/articles/static_remapping.html). + +## 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`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config) + - Launch parameter files are stored under `autoware_launch`. + +## JSON Schema + +[JSON Schema](https://json-schema.org/understanding-json-schema/index.html) is used the validate the parameter file(s) ensuring that it has the correct structure and content. Using JSON Schema for this purpose is considered best practice for cloud-native development. The schema template below shall be used as a starting point when defining the schema for a ROS node. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "INSERT_TITLE", + "type": "object", + "definitions": { + "INSERT_ROS_NODE_NAME": { + "type": "object", + "properties": { + "INSERT_PARAMETER_1_NAME": { + "type": "INSERT_TYPE", + "description": "INSERT_DESCRIPTION", + "default": "INSERT_DEFAULT", + "INSERT_BOUND_CONDITION(S)": "INSERT_BOUND_VALUE(S)" + }, + "INSERT_PARAMETER_N_NAME": { + "type": "INSERT_TYPE", + "description": "INSERT_DESCRIPTION", + "default": "INSERT_DEFAULT", + "INSERT_BOUND_CONDITION(S)": "INSERT_BOUND_VALUE(S)" + } + }, + "required": ["INSERT_PARAMETER_1_NAME", "INSERT_PARAMETER_N_NAME"] + } + }, + "properties": { + "/**": { + "type": "object", + "properties": { + "ros__parameters": { + "$ref": "#/definitions/INSERT_ROS_NODE_NAME" + } + }, + "required": ["ros__parameters"] + } + }, + "required": ["/**"] +} +``` + +The schema file path is `INSERT_PATH_TO_PACKAGE/schema/` and the schema file name is `INSERT_NODE_NAME.schema.json`. To adapt the template to the ROS node, replace each `INSERT_...` and add all parameters `1..N`. + +See example: _Lidar Apollo Segmentation TVM Nodes_ [schema](https://github.com/autowarefoundation/autoware.universe/blob/main/perception/lidar_apollo_segmentation_tvm_nodes/schema/lidar_apollo_segmentation_tvm_nodes.schema.json) + +### Attributes + +Parameters have several attributes, some are required and some optional. The optional attributes are highly encouraged when applicable, as they provide useful information about a parameter and can ensure the value of the parameter is within its bounds. + +#### Required + +- name +- type + - see [JSON Schema types](http://json-schema.org/understanding-json-schema/reference/type.html) +- description + +#### Optional + +- default + - a tested and verified value, see [JSON Schema default](https://json-schema.org/understanding-json-schema/reference/generic.html) +- bound(s) + - type dependent, e.g., [integer](https://json-schema.org/understanding-json-schema/reference/numeric.html#integer), [range](https://json-schema.org/understanding-json-schema/reference/numeric.html#range) and [size](https://json-schema.org/understanding-json-schema/reference/object.html#size) + +## Tips and Tricks + +Using well established standards enables the use of conventional tooling. Below is an example of how to link a schema to the parameter file(s) using VS Code. This enables a developer with convenient features such as auto-complete and parameter bound validation. + +In the root directory of where the project is hosted, create a `.vscode` folder with two files; `extensions.json` containing + +```json +{ + "recommendations": ["redhat.vscode-yaml"] +} +``` + +and `settings.json` containing + +```json +{ + "yaml.schemas": { + "./INSERT_PATH_TO_PACKAGE/schema/INSERT_NODE_NAME.schema.json": "**/INSERT_NODE_NAME/config/*.param.yaml" + } +} +``` + +The RedHat YAML extension enables validation of YAML files using JSON Schema and the `"yaml.schemas"` setting associates the `*.schema.json` file with all `*.param.yaml` files in the `config/` folder. diff --git a/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md b/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md index 6873692fef7..93756186da9 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md +++ b/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md @@ -1,5 +1,99 @@ # Topic namespaces -!!! warning +## Overview - Under Construction +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](https://design.ros2.org/articles/topic_and_service_names.html). + +## How topics should be named in node + +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. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +## Topic names in the code + +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. + + ```cpp + objects_sub_ = create_subscription( + "~/input/objects", rclcpp::QoS{10}, + std::bind(&ObstacleAvoidancePlanner::onObjects, this, std::placeholders::_1)); + ``` + + e.g., In node `obstacle_avoidance_planner`, using topic names of type `~/output/topic_name` to publish topic. + + ```cpp + traj_pub_ = create_publisher("~/output/path", 1); + ``` + +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. + + ```cpp + debug_markers_pub_ = + create_publisher("~/debug/marker", durable_qos); + + debug_msg_pub_ = + create_publisher("~/debug/calculation_time", 1); + ``` + + 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. diff --git a/docs/contributing/documentation-guidelines/images/deploy-docs-label-for-pull-request.png b/docs/contributing/documentation-guidelines/images/deploy-docs-label-for-pull-request.png new file mode 100644 index 00000000000..bc9c3793dee Binary files /dev/null and b/docs/contributing/documentation-guidelines/images/deploy-docs-label-for-pull-request.png differ diff --git a/docs/contributing/documentation-guidelines/index.md b/docs/contributing/documentation-guidelines/index.md index 5c652c561fa..6933135115b 100644 --- a/docs/contributing/documentation-guidelines/index.md +++ b/docs/contributing/documentation-guidelines/index.md @@ -1,21 +1,59 @@ # Documentation guidelines +## Workflow + Contributions to Autoware's documentation are welcome, and the same principles [described in the contribution guidelines](../index.md#pull-requests) 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](../../support/troubleshooting.md) guide. +- Making an addition to an existing, well-defined page, such as the [Troubleshooting](../../support/troubleshooting/index.md) 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 -In terms of style, you should refer to the [Google developer documentation style guide](https://developers.google.com/style) as much as possible. Reading the [Highlights page](https://developers.google.com/style/highlights) of that guide is recommended, but if not then the key points below should be noted. +## Style guide + +You should refer to the [Google developer documentation style guide](https://developers.google.com/style) as much as possible. Reading the [Highlights page](https://developers.google.com/style/highlights) of that guide is recommended, but if not then the key points below should be noted. - [Use standard American English spelling](https://developers.google.com/style/spelling) and punctuation. - [Use sentence case](https://developers.google.com/style/capitalization) for document titles and section headings. - [Use descriptive link text](https://developers.google.com/style/link-text). - [Write short sentences](https://developers.google.com/style/translation#write-short,-clear,-and-precise-sentences) that are easy to understand and translate. + +## Tips + +### How to preview your modification + +There are two ways to preview your modification on a documentation website. + +#### 1. Using GitHub Actions workflow + +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. + +![deploy-docs-label](images/deploy-docs-label-for-pull-request.png){ width="800" } + +#### 2. Running an MkDocs server in your local environment + +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. + +```bash +python3 -m pip install -U $(curl -fsSL https://raw.githubusercontent.com/autowarefoundation/autoware-github-actions/main/deploy-docs/mkdocs-requirements.txt) +``` + +Then, run `mkdocs serve` on your documentation directory. + +```bash +cd /PATH/TO/YOUR-autoware-documentation +mkdocs serve +``` + +It will launch the MkDocs server. Access [http://127.0.0.1:8000/](http://127.0.0.1:8000/) to see the preview of the website. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index ef7bc2d177f..dbc72cceb16 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -29,10 +29,10 @@ If you believe that someone in the community has violated the Code of Conduct, p To gain a high-level understanding of Autoware's architecture and design, the following pages provide a brief overview: -- [Autoware architecture](https://autowarefoundation.github.io/autoware-documentation/main/design/) -- [Autoware concepts](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-concepts/) +- [Autoware architecture](../design/) +- [Autoware concepts](../design/autoware-concepts/) -For experienced developers, the [Autoware interfaces](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/) and [individual component pages](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/) should also be reviewed to understand the inputs and outputs for each component or module at a more detailed level. +For experienced developers, the [Autoware interfaces](../design/autoware-interfaces/) and [individual component pages](../design/autoware-interfaces/components/) should also be reviewed to understand the inputs and outputs for each component or module at a more detailed level. ### Contributing to open source projects diff --git a/docs/contributing/pull-request-guidelines/ci-checks.md b/docs/contributing/pull-request-guidelines/ci-checks.md index 0c3394245c1..d09e4a17b00 100644 --- a/docs/contributing/pull-request-guidelines/ci-checks.md +++ b/docs/contributing/pull-request-guidelines/ci-checks.md @@ -79,4 +79,4 @@ For the details about self-hosted runners, refer to [GitHub Docs](https://docs.g ## deploy-docs This workflow deploys the preview documentation site for the pull request. -You need to add the `documentation` label to run this workflow. +You need to add the `deploy-docs` label to run this workflow. diff --git a/docs/contributing/pull-request-guidelines/index.md b/docs/contributing/pull-request-guidelines/index.md index 670d7115b95..a38a3618535 100644 --- a/docs/contributing/pull-request-guidelines/index.md +++ b/docs/contributing/pull-request-guidelines/index.md @@ -50,6 +50,26 @@ Use this workflow as a reference when you contribute to Autoware. #### Example +There are two types of templates. Select one based on the following condition. + +1. [Standard change](https://github.com/autowarefoundation/autoware/blob/main/.github/PULL_REQUEST_TEMPLATE/standard-change.md): + - 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](https://github.com/autowarefoundation/autoware/blob/main/.github/PULL_REQUEST_TEMPLATE/small-change.md): + - Complexity: + - Documentation, simple refactoring, or style adjustments. + - Easy to understand and review. + - Impact: + - Minimal effect on the system. + - Quicker merge with less testing needed. + +##### Steps to use an appropriate pull request template + 1. Select the appropriate template, as shown in [this video](https://user-images.githubusercontent.com/31987104/184344710-2adee239-799f-4fdf-bfab-be76345bfac1.mp4). 2. Read the selected template carefully and fill the required content. 3. Check the checkboxes during a review. diff --git a/docs/contributing/testing-guidelines/unit-testing.md b/docs/contributing/testing-guidelines/unit-testing.md index 7adc7d9cad5..61c650ac5d4 100644 --- a/docs/contributing/testing-guidelines/unit-testing.md +++ b/docs/contributing/testing-guidelines/unit-testing.md @@ -41,12 +41,14 @@ if(BUILD_TESTING) ament_add_ros_isolated_gtest(test_my_cool_pkg test/test_my_cool_pkg.cpp) target_link_libraries(test_my_cool_pkg ${PROJECT_NAME}) + target_include_directories(test_my_cool_pkg PRIVATE src) # For private headers. ... endif() ``` 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. +If the test source files include private headers from the `src` directory, the directory needs to be added to the include path using `target_include_directories()` function. 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, diff --git a/docs/datasets/index.md b/docs/datasets/index.md index 9504df74e06..475c999a76a 100644 --- a/docs/datasets/index.md +++ b/docs/datasets/index.md @@ -68,7 +68,7 @@ $ aws s3 ls s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/ aws 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 ``` -### AutoCore.ai - lidar ROS2 bag file and pcap +### AutoCore.ai - lidar ROS 2 bag file and pcap 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. diff --git a/docs/design/autoware-architecture/control/image/control-component.drawio.svg b/docs/design/autoware-architecture/control/image/control-component.drawio.svg new file mode 100644 index 00000000000..f028e9325c1 --- /dev/null +++ b/docs/design/autoware-architecture/control/image/control-component.drawio.svg @@ -0,0 +1,145 @@ + + + + + + + +
+
+
+
+ + Control + +
+
+
+ + + Control + + + + + + + +
+
+
+ Trajectory Follower +
+
+
+ + + Trajectory Follower + + + + + + + +
+
+
+ Vehicle Cmd Gate +
+
+
+ + + Vehicle Cmd Gate + + + + + + + + + + + +
+
+
+ Control Command +
+
+
+ + + Control Command + + + + + + + +
+
+
+ Control Command +
+
+
+ + + Control Command + + + + + + + + + +
+
+
+ Reference Trajectory +
+
+
+ + + Reference Trajectory + + + + + + + + + +
+
+
+ External +
+ Control Commands +
+
+
+ + + External... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/control/image/vehicle-interface-hw-abstraction.drawio.svg b/docs/design/autoware-architecture/control/image/vehicle-interface-hw-abstraction.drawio.svg new file mode 100644 index 00000000000..a09e8fce71d --- /dev/null +++ b/docs/design/autoware-architecture/control/image/vehicle-interface-hw-abstraction.drawio.svg @@ -0,0 +1,528 @@ + + + + + + + +
+
+
+
+ + + Vehicle +
+
+
+ + + Vehicle + + + + + + + +
+
+
+
+ Application +
+
+
+ + + Application + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + + + +
+
+
+ Steering Voltage +
+ Engine Torque +
+ Brake Pressure +
+
+
+ + + Steering Voltage... + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + + + +
+
+
+ Steering Angle +
+ Accel Pedal +
+ Brake Pedal +
+
+
+ + + Steering Angle... + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + + + +
+
+
+ Yaw Rate +
+ Velocity +
+
+
+ + + Yaw Rate... + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + + + + +
+
+
+ Adapter +
+
+
+ + + Adapter + + + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + +
+
+
+ Lateral Actuation +
+ Acceleration Actuation +
+ Deceleration Actuation +
+
+
+ + + Lateral Actuation... + + + + + + + +
+
+
+ Vehicle Driver +
+
+
+ + + Vehicle Driver + + + + + + + + + + +
+
+
+ vehicle +
+ configuration +
+
+
+ + + vehicle... + + + + + + + + + +
+
+
+ Control Component +
+
+
+ + + Control Component + + + + + + + +
+
+
+ ControlCommand: +
+ - Steering Angle +
+ - Steering Rate +
+ - Steering Torque +
+ - Velocity +
+ - Acceleration +
+
+
+ + + ControlCommand:... + + + + + + + +
+
+
+ ActuationCommand: +
+ - Lateral Actuation +
+ - Acceleration Actuation +
+ - Deceleration Actuation +
+
+
+ + + ActuationCommand:... + + + + + + + +
+
+
+ + ... + +
+
+
+ + + ... + + + + + + + + + + +
+
+
+ Auto Calibration +
+ Tools +
+
+
+ + + Auto Calibration... + + + + + + + +
+
+
+ Provided by OEMs or made/updated by calibration tools +
+
+
+ + + Provided by OEMs or made/update... + + + + + + + + + + + + + +
+
+
+ Generate generic control commands. +
+
+
+ + + Generate generic control commands. + + + + + + + +
+
+
+ Generate vehicle-specific control commands from generic control commands based on given configuration information. +
+
+
+ + + Generate vehicle-specific control comman... + + + + + + + +
+
+
+ Send control commands with vehicle-specific communication protocol. +
+
+
+ + + Send control commands with vehicle-speci... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/control/index.md b/docs/design/autoware-architecture/control/index.md index a91185f72ee..684878fac82 100644 --- a/docs/design/autoware-architecture/control/index.md +++ b/docs/design/autoware-architecture/control/index.md @@ -1,5 +1,102 @@ # Control component design -!!! warning +## Abstract - Under Construction +This document presents the design concept of the Control Component. The content is as follows: + +- [Autoware Control Design](#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](#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](#control-feature-design) + - Demonstrating the features provided by Autoware's control. + - Presenting the approach towards the functions installed in the vehicle such as ABS. + +## Autoware Control Design + +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. + +![control-component](image/control-component.drawio.svg) + +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: + +```msg +- Target steering angle +- Target steering torque +- Target speed +- Target acceleration +``` + +Note that vehicle-specific values such as pedal positions and low-level information such as individual wheel rotation speeds are excluded from the command. + +## Vehicle Adaptation Design + +### Vehicle interface adapter + +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 drivetrain. The interfaces for vehicle drivetrain 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. + +![vehicle-abstraction](image/vehicle-interface-hw-abstraction.drawio.svg) + +### Examples of several vehicle interfaces + +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 | | +| Logiee | yaw rate | Velocity | | +| F1 TENTH | Steering angle | Motor RPM | [interface code](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/src/drivers/vesc_interface/src/vesc_interface.cpp) | + +## Control Feature Design + +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　 | Requirements/Assumptions | Note | 　Limitation 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 → 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 → 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. + +### Integration with vehicle-side functions + +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. + +### Autoware Capabilities and Vehicle Requirements + +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. diff --git a/docs/design/autoware-architecture/map/index.md b/docs/design/autoware-architecture/map/index.md index 6912823c9cf..42dacfc0da8 100644 --- a/docs/design/autoware-architecture/map/index.md +++ b/docs/design/autoware-architecture/map/index.md @@ -1,5 +1,65 @@ # Map component design +## 1. Overview + +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. + +## 2. Requirements + +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. + +## 3. Architecture + +!!! warning + + Under Construction + +## 4. Features + +!!! warning + + Under Construction + +## 5. Map Specification + +### Point Cloud Map + +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](https://pointclouds.org/documentation/tutorials/pcd_file_format.html), 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. + +For more details on divided map format, please refer to [the Readme of `map_loader` in Autoware Universe](https://github.com/autowarefoundation/autoware.universe/blob/main/map/map_loader/README.md). + +!!! note + + Three global coordinate systems are currently supported by Autoware, including [Military Grid Reference System (MGRS)](https://en.wikipedia.org/wiki/Military_Grid_Reference_System), [Universal Transverse Mercator (UTM)](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system), and [Japan Rectangular Coordinate System](https://ja.wikipedia.org/wiki/%E5%B9%B3%E9%9D%A2%E7%9B%B4%E8%A7%92%E5%BA%A7%E6%A8%99%E7%B3%BB). + 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. + +#### Vector Map + +The vector cloud map must be supplied as a file with the following requirements: + +- It must be in [Lanelet2](https://github.com/fzi-forschungszentrum-informatik/Lanelet2) format, with [additional modifications required by Autoware](https://github.com/autowarefoundation/autoware_common/blob/main/tmp/lanelet2_extension/docs/lanelet2_format_extension.md). +- 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 diff --git a/docs/design/autoware-architecture/node-diagram/index.md b/docs/design/autoware-architecture/node-diagram/index.md index bb643823b6b..d3e1361f581 100644 --- a/docs/design/autoware-architecture/node-diagram/index.md +++ b/docs/design/autoware-architecture/node-diagram/index.md @@ -9,6 +9,8 @@ TBD. ## Autoware Universe ![Node diagram](overall-node-diagram-autoware-universe.drawio.svg) + +[Open in draw.io for fullscreen]({{ "/design/autoware-architecture/node-diagram/overall-node-diagram-autoware-universe.drawio.svg" | drawio }}) + 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. -[Open in draw.io for fullscreen](https://app.diagrams.net/?lightbox=1#Uhttps%3A%2F%2Fautowarefoundation.github.io%2Fautoware-documentation%2Flatest%2Fdesign%2Fautoware-architecture%2Fnode-diagram%2Foverall-node-diagram-autoware-universe.drawio.svg) diff --git a/docs/design/autoware-architecture/node-diagram/overall-node-diagram-autoware-universe.drawio.svg b/docs/design/autoware-architecture/node-diagram/overall-node-diagram-autoware-universe.drawio.svg index 59b63a266a1..7023f2d0c67 100644 --- a/docs/design/autoware-architecture/node-diagram/overall-node-diagram-autoware-universe.drawio.svg +++ b/docs/design/autoware-architecture/node-diagram/overall-node-diagram-autoware-universe.drawio.svg @@ -1,4420 +1,4 @@ - - - - - - - -
-
-
-
- /perception/traffic_light_recognition/ -
-
-
-
-
- - - /perception/traffic_light_... - - - - - - - -
-
-
-
- /perception/occupancy_grid_map/ -
-
-
-
-
- - - /perception/occupancy_grid_map/ - - - - - - - -
-
-
-
- /perception/obstacle_segmentation/ -
-
-
-
-
- - - /perception/obstacle_segmentation/ - - - - - - - -
-
-
-
- /perception/object_recognition/ -
-
-
-
-
- - - /perception/object_recognition/ - - - - - - - -
-
-
-
- /perception/object_recognition/detection/euclidean/ -
-
-
-
-
- - - /perception/object_recognition/detection/euclidean/ - - - - - - - -
-
-
- trajectory_follower -
-
-
- - - trajectory_follower - - - - - - - -
-
-
- Planning -
-
-
- - - Planning - - - - - - - -
-
-
- Control -
-
-
- - - Control - - - - - - - -
-
-
- Perception -
-
-
- - - Perception - - - - - - - -
-
-
- Vehicle -
-
-
- - - Vehicle - - - - - - - -
-
-
- Sensing -
-
-
- - - Sensing - - - - - - - -
-
-
- VehicleInterface -
-
-
- - - VehicleInterface - - - - - - - -
-
-
- Localization -
-
-
- - - Localization - - - - - - - -
-
-
- System -
-
-
- - - System - - - - - - - - -
-
-
- /diagnostics -
-
-
- - - /diagnostics - - - - - - - -
-
-
- XX1 -
-
-
- - - XX1 - - - - - - - -
-
-
- X2 -
-
-
- - - X2 - - - - - - - -
-
-
- X1 -
-
-
- - - X1 - - - - - - - -
-
-
- S1 -
-
-
- - - S1 - - - - - - - - -
-
-
- /initialpose -
-
-
- - - /initialpose - - - - - - - - -
-
-
- /vehicle/status/velocity_report -
-
-
- - - /vehicle/status/velocity_report - - - - - - - -
-
-
- <pose_initializer_srv> -
-
-
- - - <pose_initializer_srv> - - - - - - - - -
-
-
-
- /autoware/engage [Engage] -
-
- /current_gate_mode [GateMode] -
-
-
-
- - - /autoware/engage [Engage]... - - - - - - - -
-
-
- <Parking> -
-
-
- - - <Parking> - - - - - - - - -
-
-
- vehicle_velocity_converter/ -
- twist_with_covariance -
-
-
- - - vehicle_velocity_converter/... - - - - - - - - -
-
-
- /planning/turn_indicators_cmd [TurnIndicatorsCommand] -
- /planning/hazard_lights_cmd [HazardLightsCommand] -
-
-
- - - /... - - - - - - - - -
-
-
- /planning/scenario_planning/max_velocity_candidates -
- [tier4_planning_msgs/msg/VelocityLimit] -
-
-
- - - /planning/scenario_planning/max_velocity_candidates... - - - - - - - - -
-
-
- - parking/trajectory [Trajectory] - -
-
-
- - - parking/trajectory [Trajectory] - - - - - - - - - -
-
-
- HMI -
-
-
- - - HMI - - - - - - - -
-
-
- HMI -
-
-
- - - HMI - - - - - - - -
-
-
- HMI -
-
-
- - - HMI - - - - - - - -
-
-
- HMI -
-
-
- - - HMI - - - - - - - - -
-
-
- - /api/external/set/command/remote/control: [tier4_external_api_msgs/msg/ControlCommandStamped] - -
- - /api/external/set/command/remote/heartbeat: [tier4_external_api_msgs/msg/Heartbeat] - -
- - /api/external/set/command/remote/shift: [tier4_external_api_msgs/msg/GearShiftStamped] - -
- - /api/external/set/command/remote/turn_signal: [tier4_external_api_msgs/msg/TurnSignalStamped] - -
-
-
- - - /... - - - - - - - -
-
-
- HMI -
-
-
- - - HMI - - - - - - - - - -
-
-
- accel_map_calibrator -
-
-
- - - accel_map_calibrator - - - - - - - - - - - - -
-
-
-
- - /api/external/set/command/remote/control -
- -
-
- - [tier4_external_api_msgs/msg/ControlCommandStamped] - -
-
- - /api/external/set/command/remote/shift - -
-
- - [tier4_external_api_msgs/msg/GearShiftStamped] - -
-
- - /api/external/set/command/remote/turn_signal - -
-
- - [tier4_external_api_msgs/msg/TurnSignalStamped] - -
-
-
-
- - - /... - - - - - - - - -
-
-
-
- /api/external/get/command/selected/control -
- [tier4_external_api_msgs/msg/ControlCommandStamped] -
-
-
- - - /... - - - - - - - - - - -
-
-
- /vehicle/engage -
-
-
- - - /vehicle/engage - - - - - - - -
-
-
- HMI -
-
-
- - - HMI - - - - - - - - - -
-
-
-
- - /perception/ - - - object_recognition/ - - - detection/ - -
-
- - euclidean/clustering/ - -
-
-
-
-
- - - /perception/object_recognition/detection/... - - - - - - - - -
-
-
- euclidean/clustering/downsampled/pointcloud -
-
-
- - - euclidean/clustering/downsampled/pointcloud - - - - - - - -
-
-
- voxel_grid_filter -
-
-
- - - voxel_grid_filter - - - - - - - - -
-
-
- euclidean/clustering/outlier_filter/pointcloud -
-
-
- - - euclidean/clustering/outlier_filter/pointcloud - - - - - - - -
-
-
- outlier_filter -
-
-
- - - outlier_filter - - - - - - - - -
-
-
- /lidar/cluster -
-
-
- - - /lidar/cluster - - - - - - - -
-
-
- euclidean_cluster -
-
-
- - - euclidean_cluster - - - - - - - - -
-
-
- /perception/obstacle_segmentation/pointcloud -
-
-
- - - /perceptio... - - - - - - - - -
-
-
- /rois* -
-
-
- - - /rois* - - - - - - - - -
-
-
- detection_by_tracker/objects -
-
-
- - - detection_by_tracker/objects - - - - - - - -
-
-
- detection_by_ -
- tracker_node -
-
-
- - - detection_by_... - - - - - - - - - - - - - - - - -
-
-
- no_ground/oneshot/pointcloud -
-
-
- - - no_ground/oneshot/pointcloud - - - - - - - - -
-
-
- range_cropped/pointcloud -
-
-
- - - range_cropped/pointcloud - - - - - - - - -
-
-
- common_ -
- ground_filter -
-
-
- - - common_... - - - - - - - - - - - -
-
-
- pointcloud_to_ -
- laserscan -
-
-
- - - pointcloud_to_... - - - - - - - - - -
-
-
- occupancy_grid -
-
-
- - - o... - - - - - - - - -
-
-
- /perception/occupancy_grid_map/map -
-
-
- - - /perception/occupancy_grid_map/map - - - - - - - - -
-
-
- laserscan_to_ -
- occupancy_grid_map -
-
-
- - - laserscan_to_... - - - - - - - - - -
-
-
- occupancy_grid_ -
- map_based_outlier_filter -
-
-
- - - occupancy_grid_... - - - - - - - - - -
-
-
- /perception/obstacle_segmentation/pointcloud -
-
-
- - - /perception/obstacle_segmentation/pointcloud - - - - - - - -
-
-
- crop_box_filter -
-
-
- - - crop_box_filter - - - - - - - - -
-
-
- /concatenated/pointcloud -
-
-
- - - /concatena... - - - - - - - - - - -
-
-
- /autoware/state -
-
-
- - - /autoware/state - - - - - - - - -
-
-
- /autoware/engage -
-
-
- - - /autoware/engage - - - - - - - - -
-
-
- /diagnostics -
-
-
- - - /... - - - - - - - - -
-
-
- ad_service_ -
- state_monitor -
-
-
- - - ad_service_... - - - - - - - - - -
-
-
-
- - /control/current_gate_mode - -
-
- - /vehicle/status/control_mode - -
-
- - /autoware/state - -
-
-
-
- - - /control/c... - - - - - - - - -
-
-
- /diagnostics_err -
-
-
- - - /diagnostics_err - - - - - - - - -
-
-
- /control/command/control_cmd -
- /control/trajectory_follower/control_cmd -
- /initialpose2d -
- /localization/kinematic_state -
- /map/pointcloud_map -
- /map/vector_map -
- /perception/object_recognition/objects -
- /planning/mission_planning/route -
- /planning/scenario_planning/trajectory -
- /system/emergency/control_cmd -
- /vehicle/status/control_mode -
- /vehicle/status/steering_status -
- /vehicle/status/velocity_status -
-
-
- - - /contr... - - - - - - - -
-
-
- Control -
-
-
- - - Control - - - - - - - - -
-
-
- latlon_muxer -
-
-
- - - latlon_muxer - - - - - - - - - -
-
-
-
- /control/trajectory_follower/lateral/control_cmd -
-
- [AckermannLateralControlCommand] -
-
-
-
-
-
-
- - - /control/trajectory_follower/lateral/control_cmd... - - - - - - - - -
-
-
- /control/trajectory_follower/longitudinal/control_cmd -
- [LongitudinalControlCommand] -
-
-
- - - /control/trajectory_follower/longitudinal/control_cmd... - - - - - - - - -
-
-
-
- /control/trajectory_follower/control_cmd -
-
- [AckermannControlCommand] -
-
-
-
-
-
-
- - - /control/trajectory_follower/control_cmd... - - - - - - - - -
-
-
- lateral_controller -
-
-
- - - lateral_controller - - - - - - - - - -
-
-
- longitudinal_controller -
-
-
- - - longitudinal_controller - - - - - - - - - -
-
-
- vehicle_cmd_gate -
-
-
- - - vehicle_cmd_gate - - - - - - - - - -
-
-
- control/command/control_cmd -
- [AckermannControlCommand] -
-
-
- - - c... - - - - - - - - -
-
-
- /control/shift_decider/gear_cmd -
- [GearCommand] -
-
-
- - - /control/shift_decider/gear_cmd... - - - - - - - - -
-
-
- shift_decider -
-
-
- - - shift_decider - - - - - - - - - -
-
-
- external_cmd_ -
- converter -
-
-
- - - external_cmd_... - - - - - - - - - - - -
-
-
- /diagnostics -
-
-
- - - /diagnostics - - - - - - - - -
-
-
- lane_departure_ -
- checker -
-
-
- - - lane_departure_... - - - - - - - - - -
-
-
- predicted_trajectory -
-
-
- - - predicted_trajectory - - - - - - - - -
-
-
- /external/selected/external_control_cmd -
- [tier4_external_api_msgs/msg/ControlCommandStamped] -
-
-
- - - /external/selected/external_control_cmd... - - - - - - - - -
-
-
- external_cmd_ -
- selector -
-
-
- - - external_cmd_... - - - - - - - - - -
-
-
- /current_gate_mode [GateMode] -
- /gear_cmd [GearCommand] -
-
- /turn_indicators_cmd  [TurnIndicatorCommand] -
-
-
- /hazard_lights_cmd  [HazardLightsCommand] -
-
-
- /vehicle_emergency_cmd [VehicleEmergencyStamped] -
-
-
-
- - - /current_gate_mode [GateMode]... - - - - - - - - -
-
-
- behavior_velocity_planner -
-
-
- - - behavior_velocity_planner - - - - - - - - -
-
-
- Planning -
-
-
- - - Planning - - - - - - - - -
-
-
- /planning/scenario_planning/trajectory [Trajectory] -
-
-
- - - /planning/scenario_planning/trajectory [Trajectory] - - - - - - - - - - -
-
-
- motion_planning/obstacle_avoidance_planner/trajectory [Trajectory] -
-
-
- - - motion_planning/obstacle_avoidance_planner/trajectory [Trajectory] - - - - - - - - -
-
-
- obstacle_ -
- avoidance_planner -
-
-
- - - obstacle_... - - - - - - - - - -
-
-
- motion_planning/surround_obstacle_checker/trajectory [Trajectory] -
-
-
- - - motion_planning/surround_obstacle_checker/trajectory [Trajectory] - - - - - - - - -
-
-
- surround_ -
- obstacle_checker -
-
-
- - - surround_... - - - - - - - - - -
-
-
- obstacle_stop_ -
- planner -
-
-
- - - obstacle_stop_... - - - - - - - - - -
-
-
- costmap_generator -
-
-
- - - costmap_generator - - - - - - - - - -
-
-
- external_velocity_ -
- limit_selector -
-
-
- - - external_velocity_... - - - - - - - - - -
-
-
- /planning/scenario_planning/max_velocity -
- [tier4_planning_msgs/msg/VelocityLimit] -
-
-
- - - /planning/scenario_planning/max_velocity... - - - - - - - - -
-
-
- /planning/scenario_planning/max_velocity_candidates -
- [tier4_planning_msgs/msg/VelocityLimit] -
-
-
- - - /planning/scenario_planning/max_velocity_candidates... - - - - - - - - -
-
-
- lane_driving/trajectory [Trajectory] -
-
-
- - - lane_driving/trajectory [Trajectory] - - - - - - - - -
-
-
- trajectory [Trajectory] -
-
-
- - - trajectory [Trajectory] - - - - - - - - -
-
-
- scenario_selector -
-
-
- - - scenario_selector - - - - - - - - - -
-
-
- motion_velocity_ -
- smoother -
-
-
- - - motion_velocity_... - - - - - - - - - - - -
-
-
- behavior_path_planner -
-
-
- - - behavior_path_planner - - - - - - - - -
-
-
- obstacle_avoidance -
-
-
- - - obstacle_avoidance - - - - - - - -
-
-
- pull_over/out -
-
-
- - - pull_over/out - - - - - - - -
-
-
- side_shift -
-
-
- - - side_shift - - - - - - - -
-
-
- lane_change -
-
-
- - - lane_change - - - - - - - -
-
-
- lane_following -
-
-
- - - lane_following - - - - - - - -
-
-
- <Lane Driving> -
-
-
- - - <Lane Driving> - - - - - - - -
-
-
- no_stopping_area -
-
-
- - - no_stopping_area - - - - - - - -
-
-
- occlusion_spot -
-
-
- - - occlusion_spot - - - - - - - -
-
-
- intersection -
-
-
- - - intersection - - - - - - - -
-
-
- traffic_light -
-
-
- - - traffic_light - - - - - - - -
-
-
- cross_walk -
-
-
- - - cross_walk - - - - - - - -
-
-
- blind_spot -
-
-
- - - blind_spot - - - - - - - -
-
-
- detection_area -
-
-
- - - detection_area - - - - - - - -
-
-
- stop_line -
-
-
- - - stop_line - - - - - - - - - - -
-
-
- /planning/mission_planning/route -
- [autoware_auto_planning_msgs/HADMapRoute] -
-
-
- - - /planning/mission_planning/route... - - - - - - - - -
-
-
- mission_planner -
-
-
- - - mission_planner - - - - - - - - - -
-
-
- behavior_planning/path_with_lane_id -
-
-
- - - behavior_planning/path_with_lane_id - - - - - - - - -
-
-
- behavior_planning/path -
-
-
- - - behavior_planning/path - - - - - - - - -
-
-
- freespace_planner -
-
-
- - - freespace_planner - - - - - - - - - - -
-
-
- costmap_generator/occupancy_grid -
-
-
- - - costmap_generator/occupancy_grid - - - - - - - - -
-
-
- goal -
-
-
- - - goal - - - - - - - -
-
-
- virtual_stop_line -
-
-
- - - virtual_stop_line - - - - - - - -
-
-
- Perception -
-
-
- - - Perception - - - - - - - - -
-
-
- centerpoint/objects -
-
-
- - - centerpoint/objects - - - - - - - - -
-
-
- lidar_centerpoint -
-
-
- - - lidar_centerpoint - - - - - - - - - -
-
-
- /perception/object_recognition/objects -
-
-
- - - /perception/object_recognition/objects - - - - - - - - -
-
-
- map_based_ -
- prediction -
-
-
- - - map_based_... - - - - - - - - - -
-
-
- traffic_light_detection/rough/rois -
-
-
- - - traffic_light_detection/rough/rois - - - - - - - - -
-
-
- traffic_light_map_ -
- based_detector -
-
-
- - - traffic_light_map_... - - - - - - - - - -
-
-
- detection/objects -
-
-
- - - detection/objects - - - - - - - - -
-
-
- traffic_light_ -
- classifier -
-
-
- - - traffic_light_... - - - - - - - - - -
-
-
- traffic_light_ -
- ssd_fine_detector -
-
-
- - - traffic_light_... - - - - - - - - - -
-
-
- tracking/objects -
-
-
- - - tracking/objects - - - - - - - - -
-
-
- route, -
- vector_map -
-
-
- - - route,... - - - - - - - - -
-
-
- multi_object_ -
- tracker -
-
-
- - - multi_object_... - - - - - - - - - -
-
-
- traffic_light_states -
-
-
- - - traffic_light_states - - - - - - - - -
-
-
- tensorrt_yolo -
-
-
- - - tensorrt_yolo - - - - - - - - - - - -
-
-
- roi_cluster_fusion -
-
-
- - - roi_cluster_fusion - - - - - - - - - -
-
-
- object_association -
- _merger -
-
-
- - - object_association... - - - - - - - - - -
-
-
- camera_lidar_fusion/objects -
-
-
- - - c... - - - - - - - - -
-
-
- object_range_splitter -
-
-
- - - object_range_splitter - - - - - - - - - - - -
-
-
- shape_estimation -
-
-
- - - shape_estimation - - - - - - - - -
-
-
- vehicle_interface -
-
-
- - - vehicle_interface - - - - - - - -
-
-
- g30_interface -
-
-
- - - g30_interface - - - - - - - - -
-
-
- raw_vehicle_cmd_ -
- converter -
-
-
- - - raw_vehicle_cmd_... - - - - - - - - - -
-
-
- /vehicle/command/actuation_cmd -
-
-
- - - /vehicle/command/actuation_cmd - - - - - - - - -
-
-
- pacmod_interface -
-
-
- - - pacmod_interface - - - - - - - - -
-
-
- VehicleInterface -
-
-
- - - VehicleInterface - - - - - - - - -
-
-
- /vehicle/status/velocity_status -
- /vehicle/status/steering_status -
- /vehicle/status/turn_indicators_status -
- /vehicle/status/gear_status -
- /vehicle/status/control_mode -
- /vehicle/status/ - - actuation_status - -
-
-
- - - /vehicle/s... - - - - - - - - - -
-
-
- /pacmod/** -
-
-
- - - /pacmod/** - - - - - - - -
-
-
- Vehicle -
-
-
- - - Vehicle - - - - - - - - -
-
-
- <CAN> -
-
-
- - - <CAN> - - - - - - - -
-
-
- JapanTaxi -
-
-
- - - JapanTaxi - - - - - - - - -
-
-
- pacmod3 -
-
-
- - - pacmod3 - - - - - - - - -
-
-
- YMC GolfCart -
-
-
- - - YMC GolfCart - - - - - - - - -
-
-
- top/velodyne_packets -
-
-
- - - top/velodyne_packets - - - - - - - -
-
-
- lidar_driver -
-
-
- - - lidar_driver - - - - - - - - -
-
-
- top/rectified/pointcloud -
-
-
- - - top/rectified/pointcloud - - - - - - - - -
-
-
- fix_distortion -
-
-
- - - fix_distortion - - - - - - - - - -
-
-
- top/pointcloud_raw -
-
-
- - - top/pointcloud_raw - - - - - - - -
-
-
- packets_to_ -
- pointcloud -
-
-
- - - packets_to_... - - - - - - - - -
-
-
- top/self_cropped/pointcloud -
-
-
- - - top/self_cropped/pointcloud - - - - - - - - -
-
-
- crop_box_ -
- filter_self -
-
-
- - - crop_box_... - - - - - - - - - -
-
-
- top/mirror_cropped/pointcloud -
-
-
- - - top/mirror_cropped/pointcloud - - - - - - - - -
-
-
- crop_box_ -
- filter_mirror -
-
-
- - - crop_box_... - - - - - - - - - -
-
-
- ring_outlier_filter -
-
-
- - - ring_outlier_filter - - - - - - - - - -
-
-
- lidar/*/velodyne_packets -
-
-
- - - lidar/*/velodyne_packets - - - - - - - -
-
-
- lidar_drivers -
- (left,right,front_right, front_left,rear) -
-
-
- - - lidar_drivers... - - - - - - - - -
-
-
- - */rectified/pointcloud - -
-
-
- - - */rectified/pointcloud - - - - - - - - -
-
-
- fix_distortion -
-
-
- - - fix_distortion - - - - - - - - - -
-
-
- - */pointcloud_raw - -
-
-
- - - */pointcloud_raw - - - - - - - -
-
-
- packets_to_ -
- pointcloud -
-
-
- - - packets_to_... - - - - - - - - -
-
-
- - */self_cropped/pointcloud - -
-
-
- - - */self_cropped/pointcloud - - - - - - - - -
-
-
- crop_box_ -
- filter_self -
-
-
- - - crop_box_... - - - - - - - - - -
-
-
- - */mirror_cropped/pointcloud - -
-
-
- - - */mirror_cropped/pointcloud - - - - - - - - -
-
-
- crop_box_ -
- filter_mirror -
-
-
- - - crop_box_... - - - - - - - - - -
-
-
- ring_outlier_filter -
-
-
- - - ring_outlier_filter - - - - - - - - - -
-
-
- concatenated/pointcloud -
-
-
- - - concatenated/pointcloud - - - - - - - - -
-
-
- concat_filter -
-
-
- - - concat_filter - - - - - - - - - - - - - -
-
-
- gnss_poser -
-
-
- - - gnss_poser - - - - - - - - - - -
-
-
- gnss_driver -
-
-
- - - gnss_driver - - - - - - - -
-
-
- imu_driver -
-
-
- - - imu_driver - - - - - - - - -
-
-
- /sensing/imu/imu_raw -
-
-
- - - /sensing/imu/imu_raw - - - - - - - - -
-
-
- /sensing/lidar/pointcloud -
-
-
- - - /sensing/lidar/pointcloud - - - - - - - - -
-
-
- - /sensing/top/rectified/pointcloud - -
-
-
- - - /sensing/top/rectified/pointcloud - - - - - - - - -
-
-
- /sensing/gnss/ -
- pose_with_covariance -
-
-
- - - /sensing/gnss/... - - - - - - - - -
-
-
- imu_corrector -
-
-
- - - imu_corrector - - - - - - - - - -
-
-
- /sensing/imu/imu_data -
-
-
- - - /sensing/imu/imu_data - - - - - - - -
-
-
- Sensing -
-
-
- - - Sensing - - - - - - - -
-
-
- Localization -
-
-
- - - Localization - - - - - - - - -
-
-
- voxel_grid_downsample/pointcloud -
-
-
- - - voxel_grid_downsample/pointcloud - - - - - - - -
-
-
- voxel_grid_ -
- downsample_filter -
-
-
- - - voxel_grid_... - - - - - - - - -
-
-
- pose_twist_fusion_filter/ -
- pose_with_covariance_ -
- no_yawbias -
-
-
- - - pose_twist_fusion_filter/... - - - - - - - - -
-
-
- ekf_localizer -
-
-
- - - ekf_localizer - - - - - - - - - -
-
-
- pose_estimator/ -
- pose_with_covariance -
-
-
- - - pose_estimator/... - - - - - - - - -
-
-
- ndt_scan_matcher -
-
-
- - - ndt_scan_matcher - - - - - - - - - -
-
-
- downsample/pointcloud -
-
-
- - - downsample/pointcloud - - - - - - - -
-
-
- random_ -
- downsample_filter -
-
-
- - - random_... - - - - - - - - -
-
-
- /initialpose3d -
-
-
- - - /initialpose3d - - - - - - - - -
-
-
- pose_initializer -
-
-
- - - pose_initializer - - - - - - - - - -
-
-
- twist_estimator/twist_with_covariance -
-
-
- - - twist_estimator/twist_with_covariance - - - - - - - - -
-
-
- gyro_odometer -
-
-
- - - gyro_odometer - - - - - - - - - -
-
-
- measurement_range/pointcloud -
-
-
- - - measurement_range/pointcloud - - - - - - - -
-
-
- crop_box_filter_ -
- measurement_range -
-
-
- - - crop_box_filter_... - - - - - - - -
-
-
- vehicle_velocity_converter -
-
-
- - - vehicle_velocity_converter - - - - - - - - -
-
-
- /tf -
- (map to base_link) -
-
-
- - - /tf... - - - - - - - - -
-
-
- /localization/kinematic_state -
- [nav_msgs/msg/Odometry] -
-
-
- - - /localization/kinematic_state... - - - - - - - -
-
-
- stop_filter -
-
-
- - - stop_filter - - - - - - - -
-
-
- localization_error_monitor -
-
-
- - - localization_error_monitor - - - - - - - - -
-
-
- pose_twist_fusion_filter/ -
- pose_with_covariance -
-
-
- - - pose_twist_fusion_filter/... - - - - - - - - -
-
-
- /diagnostics -
-
-
- - - /diagnostics - - - - - - - - -
-
-
- pose_twist_fusion_filter/ -
- kinematic_state -
-
-
- - - pose_twist_fusion_filter/... - - - - - - - - -
-
-
- system_monitors -
-
-
- - - system_monitors - - - - - - - - -
-
-
- System -
-
-
- - - System - - - - - - - -
-
-
- autoware_process_ -
- monitor -
-
-
- - - autoware_process_... - - - - - - - -
-
-
- autoware_gpu_ -
- monitor -
-
-
- - - autoware_gpu_... - - - - - - - -
-
-
- autoware_mem_ -
- monitor -
-
-
- - - autoware_mem_... - - - - - - - -
-
-
- autoware_hdd_ -
- monitor -
-
-
- - - autoware_hdd_... - - - - - - - -
-
-
- autoware_net_ -
- monitor -
-
-
- - - autoware_net_... - - - - - - - -
-
-
- autoware_ntp_ -
- monitor -
-
-
- - - autoware_ntp_... - - - - - - - - -
-
-
- /system/emergency/hazard_status -
-
-
- - - /system/emergency/hazard_status - - - - - - - - -
-
-
- autoware_error_ -
- monitor -
-
-
- - - autoware_error_... - - - - - - - - - -
-
-
-
- /system/emergency/control_cmd [AckermannControlCommand] -
-
- /system/emergency/gear_cmd [GearCommand] -
-
- /system/emergency/hazard_lights_cmd [HazardLightsCommand] -
- /system/emergency/emergency_state [EmergencyStateStamped] -
-
-
- - - /system/emergency/control_cmd [AckermannControlCommand]... - - - - - - - - -
-
-
- emergency_handler -
-
-
- - - emergency_handler - - - - - - - - - - Viewer does not support full SVG 1.1 - - - - + + + +
Planning
Planning
Control
Control
Perception
Perception
Vehicle
Vehicle
Sensing
Sensing
VehicleInterface
VehicleInterface
Localization
Localization
System
System
/diagnostics
/diagnostics
XX1
XX1
X2
X2
X1
X1
S1
S1
/vehicle/status/velocity_report
/vehicle/status/velocity_report
/autoware/engage [Engage]
/current_gate_mode [GateMode]
/autoware/engage [Engage]...
/planning/turn_indicators_cmd [TurnIndicatorsCommand]
/planning/hazard_lights_cmd [HazardLightsCommand]
/planning/turn_indicators_cmd [TurnIndicatorsCommand]...
/planning/scenario_planning/max_velocity_candidates
[tier4_planning_msgs/msg/VelocityLimit]
/planning/scenario_planning/max_velocity_candidates...
HMI
HMI
HMI
HMI
HMI
HMI
/api/external/set/command/remote/control: [tier4_external_api_msgs/msg/ControlCommandStamped]
/api/external/set/command/remote/heartbeat: [tier4_external_api_msgs/msg/Heartbeat]
/api/external/set/command/remote/shift: [tier4_external_api_msgs/msg/GearShiftStamped]
/api/external/set/command/remote/turn_signal: [tier4_external_api_msgs/msg/TurnSignalStamped]
/api/external/set/command/remote/control: [tier4_external_api_msgs/msg/ControlCommandStamped]...
HMI
HMI
/vehicle/engage
/vehicle/engage
HMI
HMI
/diagnostics_err
/diagnostics_err
/initialpose
/initialpose
<pose_initializer_srv>
<pose_initializer_srv>
vehicle_velocity_converter/
twist_with_covariance
vehicle_velocity_converter/...
HMI
HMI
pointcloud_map_
loader
pointcloud_map_...
<differential_map_loader_srv>
<differential_map_loader_srv>
<partial_map_loader_srv>
<partial_map_loader_srv>
voxel_grid_downsample/pointcloud
voxel_grid_downsample/pointcloud立体格子の点群密度が一様になるように点群を間引く。点群密度が正規化されるため、NDTのロバスト化に一役買っている。立体格子の点群密度が一様になるように点群を間引く。点群密度が正規化されるため、NDTのロバスト化に一役買っている。
voxel_grid_
downsample_filter
voxel_grid_...
pose_twist_fusion_filter/
pose_with_covariance_
no_yawbias
pose_twist_fusion_filter/...Estimate ego vehicle's position, orientation, and velocity by EKF algorithm.Estimate ego vehicle's position, orientation, and velocity by EKF algorithm.
ekf_localizer
ekf_localizer
pose_estimator/
pose_with_covariance
pose_estimator/...LiDARの点群とpointcloud_mapとのマッチングを行い、自己位置を計算するLiDARの点群とpointcloud_mapとのマッチングを行い、自己位置を計算する
ndt_scan_matcher
ndt_scan_matcher
downsample/pointcloud
downsample/pointcloud点群数が一定以下になるようにランダムに間引く。基本的にはvoxel grid filterで丁度いいくらい点群数になるように調整してあり、点群数のlimiter的な立ち位置が強い 点群数が一定以下になるようにランダムに間引く。基本的にはvoxel grid filterで丁度いいくらい点群数になるように調整してあり、点群数のlimiter的な立ち位置が強い
random_
downsample_filter
random_...
/initialpose3d
/initialpose3dGNSS / Userからラフな初期位置を受け取り、NDT+モンテカルロ法で正確な自己位置を推定して出力する。NDTとはserviceでやり取りする。GNSS / Userからラフな初期位置を受け取り、NDT+モンテカルロ法で正確な自己位置を推定して出力する。NDTとはserviceでやり取りする。
pose_initializer
pose_initializer
twist_estimator/twist_with_covariance
twist_estimator/twist_with_covariance車両速度とimuを統合する。いまは確か、ただ単にvx=vehicle, wz=imuだった気がする。車両速度とimuを統合する。いまは確か、ただ単にvx=vehicle, wz=imuだった気がする。
gyro_odometer
gyro_odometer
measurement_range/pointcloud
measurement_range/pointcloud一定範囲内のLiDAR点群のみを切り取って出力する。ホントは遠くまで見たいけど、歪みの影響が大きくなったり、そもそも遠方の点群地図がなかったりするので、近くだけを見てる。一定範囲内のLiDAR点群のみを切り取って出力する。ホントは遠くまで見たいけど、歪みの影響が大きくなったり、そもそも遠方の点群地図がなかったりするので、近くだけを見てる。
crop_box_filter_
measurement_range
crop_box_filter_...車両速度とimuを統合する。いまは確か、ただ単にvx=vehicle, wz=imuだった気がする。車両速度とimuを統合する。いまは確か、ただ単にvx=vehicle, wz=imuだった気がする。
vehicle_velocity_converter
vehicle_velocity_converter
/tf
(map to base_link)
/tf...
/localization/kinematic_state
[nav_msgs/msg/Odometry]
/localization/kinematic_state...Overwrite vx=0 and wz=0 when the vehicle wheel speed is zero to indicate the stop condition.Overwrite vx=0 and wz=0 when the vehicle wheel speed is zero to indicate the stop condition.
stop_filter
stop_filter
localization_error_monitor
localization_error_monitor
pose_twist_fusion_filter/
pose_with_covariance
pose_twist_fusion_filter/...
/diagnostics
/diagnostics
pose_twist_fusion_filter/
kinematic_state
pose_twist_fusion_filter/...
Map
Map Check the trajectory and stop publishing it if it is unsafe.Check the trajectory and stop publishing it if it is unsafe.
planning_validator
planning_validator規定された停止線で一時停止を行います規定された停止線で一時停止を行います
invalid_lanelet
invalid_lanelet
Perception
Perception
/perception/object_recognition/objects
/perception/object_recognition/objects
traffic_light_states
traffic_light_states
/perception/traffic_light_recognition/
/perception/traffic_light_...
/perception/object_recognition/
/perception/object_recognition/
/perception/object_recognition/detection/
/perception/object_recognition/detectio...
clustering/clusters
clustering/clusters
euclidean_cluster
euclidean_cluster
pointcloud_map_filtered/pointcloud
pointcloud...

detection_by
_tracker/objects

detection_by...
centerpoint/validation/objects
centerpoint/validation/objectsDNNベースでLiDAR点群に物体のクラス情報を付与するDNNベースでLiDAR点群に物体のクラス情報を付与する
lidar_centerpoint
lidar_centerpoint高精度地図情報を用いて、trackingされた動物体情報の移動経路予測を行う高精度地図情報を用いて、trackingされた動物体情報の移動経路予測を行う
map_based_
prediction
map_based_...
traffic_light_detection/rough/rois
traffic_light_detection/rough/rois自己位置および高精度地図情報、自身の走行ルート情報から、信号機のおおよその位置を計算する自己位置および高精度地図情報、自身の走行ルート情報から、信号機のおおよその位置を計算する
traffic_light_map_
based_detector
traffic_light_map_...
detection/objects
detection/objects画像に含まれる信号機の色を識別する画像に含まれる信号機の色を識別する
traffic_light_
classifier
traffic_light_...画像処理を用いて信号機の正確な位置を計算する画像処理を用いて信号機の正確な位置を計算する
traffic_light_
ssd_fine_detector
traffic_light_...
route,
vector_map
route,...クラス＋位置＋形状情報に対してtrackingを行う。（最近上流が速度情報も出せるようになってきたらしい）クラス＋位置＋形状情報に対してtrackingを行う。（最近上流が速度情報も出せるようになってきたらしい）
multi_object_
tracker
multi_object_...detection同士のassignmentを取り，confidenceが高い方を採用する．overlapしたunknown objectはmergeするdetection同士のassignmentを取り，confidenceが高い方を採用する．overlapしたunknown objectはmergeする
object_association
_merger
object_association...clustering結果の形状を推定するclustering結果の形状を推定する
shape_estimation
shape_estimation
/perception/occupancy_grid_map/
/perception/occupancy_grid_map/
/perception/obstacle_segmentation/
/perception/obstacle_segmentation/
no_ground/oneshot/pointcloud
no_ground/oneshot/pointcloud
range_cropped/pointcloud
range_cropped/pointcloudアルゴリズムを使って点群から地面を除去します。アルゴリズムを使って点群から地面を除去します。
common_
ground_filter
common_...
occupancy_grid
occupancy_grid
/perception/occupancy_grid_map/map
/perception/occupancy_grid_map/map全点群データ、地面除去済み点群、occupancy gridの情報を総合的に見て、障害物が存在するかどうかの確率をoccupancy gridマップの形式で計算します。全点群データ、地面除去済み点群、occupancy gridの情報を総合的に見て、障害物が存在するかどうかの確率をoccupancy gridマップの形式で計算します。
probabilistic_
occupancy_grid_map
probabilistic_...occupancy gridで与えられる障害物存在確率マップの情報をもとに、障害物点群をフィルタリングします。occupancy gridで与えられる障害物存在確率マップの情報をもとに、障害物点群をフィルタリングします。
occupancy_grid_
map_based_outlier_filter
occupancy_grid_...
/perception/obstacle_segmentation/pointcloud
/perception/obstacle_segmentation/pointcloud
crop_box_filter
crop_box_filter
/concatenated/pointcloud
/concatena...BBox内に存在するobstacle_segmentation後の点群数を用いて，false positiveを除くBBox内に存在するobstacle_segmentation後の点群数を用いて，false positiveを除く
obstacle_pointcloud _based_validator
obstacle_pointcloud _ba...detection同士のassignmentを取り，confidenceが高い方を採用する．overlapしたunknown objectはmergeするdetection同士のassignmentを取り，confidenceが高い方を採用する．overlapしたunknown objectはmergeする
object_association
_merger
object_association...DNNベースで画像に物体のクラス情報を付与するDNNベースで画像に物体のクラス情報を付与する
tensorrt_yolo
tensorrt_yolo
/perception/obstacle_segmentation/pointcloud
/perception/obstacle_segmentation/pointcloudclustering結果に画像のdetection結果をprojectionしてlabelを付与するclustering結果に画像のdetection結果をprojectionしてlabelを付与する
roi_cluster_fusion
roi_cluster_fusion
/rois*
/rois*clustering結果の形状を推定するclustering結果の形状を推定する
shape_estimation
shape_estimationtracker内部のclusterをマージし，shape fittingしたbboxを出力するtracker内部のclusterをマージし，shape fittingしたbboxを出力する
detection_by_
tracker_node
detection_by_...
clustering/camera_lidar_fusion
/objects
clustering/camera_lidar_fusion...
/sensing/camera/
camera*/image_rect_color
/sensing/camera/...vector mapの情報を用いて，unknown objectをfilterする．lane内のunknown objectのみを残す．vector mapの情報を用いて，unknown objectをfilterする．lane内のunknown objectのみを残す．
object_lanelet_filter
object_lanelet_filter
/map/vector_map
/map/vector_map
/map/vector_map
/map/vector_map
compare_map_filter
compare_map_filter
/perception/obstacle_segmentation/pointcloud
/perception/obstacle_segmentation/pointcloud
map
map交通ルールをもとに、経路上の最大速度を決定します。各モジュールは、自身の計算した最大速度と上段の結果を比較し、小さい速度を経路上に書き込みます。交通ルールをもとに、経路上の最大速度を決定します。各モジュールは、自身の計算した最大速度と上段の結果を比較し、小さい速度を経路上に書き込みます。
behavior_velocity_planner
behavior_velocity_planner
Planning
Planning
/planning/scenario_planning/trajectory [Trajectory]
/planning/scenario_planning/trajectory [Trajectory]
motion_planning/obstacle_avoidance_planner/trajectory [Trajectory]
motion_planning/obstacle_avoidance_planner/trajectory [Trajectory]車両形状や走行可能領域を考慮して、経路の平滑化を行う。障害物も避けるが、long historyで最近は回避機能はoffになっています。車両形状や走行可能領域を考慮して、経路の平滑化を行う。障害物も避けるが、long historyで最近は回避機能はoffになっています。
obstacle_
avoidance_planner
obstacle_...
motion_planning/obstacle_velocity_limiter/trajectory [Trajectory]
motion_planning/obstacle_velocity_limiter/trajectory [Trajectory]自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。
obstacle_velocity_limiter
obstacle_velocity_limit...障害物停止・前車追従・近傍障害物減速の複数の機能を持ち、機能に応じて経路上に速度を埋め込む。 目標経路上に障害物点がある場合は停止、経路近くに障害物点群がある場合は減速、前方に車両が居る場合は前車追従。障害物停止・前車追従・近傍障害物減速の複数の機能を持ち、機能に応じて経路上に速度を埋め込む。 目標経路上に障害物点がある場合は停止、経路近くに障害物点群がある場合は減速、前方に車両が居る場合は前車追従。
obstacle_stop_
planner
obstacle_stop_...障害物点群や地図の走行可能エリアの情報から、駐車プランナー用のコストマップを生成する。障害物点群や地図の走行可能エリアの情報から、駐車プランナー用のコストマップを生成する。
costmap_generator
costmap_generatorapiとautoware.iv内部から送られてくる制約付き減速指示を受け取り、整合性をとるapiとautoware.iv内部から送られてくる制約付き減速指示を受け取り、整合性をとる
external_velocity_
limit_selector
external_velocity_...
/planning/scenario_planning/max_velocity
[tier4_planning_msgs/msg/VelocityLimit]
/planning/scenario_planning/max_velocity...
/planning/scenario_planning/max_velocity_candidates
[tier4_planning_msgs/msg/VelocityLimit]
/planning/scenario_planning/max_velocity_candidates...
lane_driving/trajectory [Trajectory]
lane_driving/trajectory [Trajectory]
trajectory [Trajectory]
trajectory [Trajectory]いまのrouteおよび地図情報から、LaneDriving / Parkingのシナリオを判断し、どちらの経路を使うかを切り替える。いまのrouteおよび地図情報から、LaneDriving / Parkingのシナリオを判断し、どちらの経路を使うかを切り替える。
scenario_selector
scenario_selector
/planning/scenario_planning/motion_velocity_smoother/trajectory [Trajectory]
/planning/scenario_planning/motion_velocity_smoother/trajectory [Trajectory]経路に埋め込まれた最大速度を超過しないように、うまい具合で速度を平滑化する。カーブでの減速もここで行う。経路に埋め込まれた最大速度を超過しないように、うまい具合で速度を平滑化する。カーブでの減速もここで行う。
motion_velocity_
smoother
motion_velocity_...交通ルールをもとに、経路上の最大速度を決定します。各モジュールは、自身の計算した最大速度と上段の結果を比較し、小さい速度を経路上に書き込みます。交通ルールをもとに、経路上の最大速度を決定します。各モジュールは、自身の計算した最大速度と上段の結果を比較し、小さい速度を経路上に書き込みます。
behavior_path_planner
behavior_path_plannerルート情報や障害物情報をもとに、障害物回避を実行します。ルート情報や障害物情報をもとに、障害物回避を実行します。
obstacle_avoidance
obstacle_avoidanceルート情報をもとに路肩への幅寄せ、路肩からの発進を行います。ルート情報をもとに路肩への幅寄せ、路肩からの発進を行います。
pull_over/out
pull_over/out遠隔からの司令をもとに幅寄せを行います。遠隔からの司令をもとに幅寄せを行います。
side_shift
side_shiftルート情報や障害物情報をもとに、レーンチェンジを実行します。ルート情報や障害物情報をもとに、レーンチェンジを実行します。
lane_change
lane_changeルート情報をもとに走行経路を作成します。ルート情報をもとに走行経路を作成します。
lane_following
lane_following
<Lane Driving>
<Lane Driving>停止禁止区域内で停止しないように、区域手前での進行・停止判断を行います。停止禁止区域内で停止しないように、区域手前での進行・停止判断を行います。
no_stopping_area
no_stopping_area地図情報および動物体情報から、死角手前での減速を行います。地図情報および動物体情報から、死角手前での減速を行います。
occlusion_spot
occlusion_spot地図情報および動物体情報から、交差点での停止/発進の判定を行います。地図情報および動物体情報から、交差点での停止/発進の判定を行います。
intersection
intersection信号の色に応じて停止/発進の指示をします信号の色に応じて停止/発進の指示をします
traffic_light
traffic_light横断歩道に人が居る、もしくは侵入しようとしてきている場合に、横断歩道手前で停止します。近くに人が居る場合は徐行します。横断歩道に人が居る、もしくは侵入しようとしてきている場合に、横断歩道手前で停止します。近くに人が居る場合は徐行します。
cross_walk
cross_walk右左折時に車両後方の巻き込み確認を行い、衝突の危険がある場合は停止します。右左折時に車両後方の巻き込み確認を行い、衝突の危険がある場合は停止します。
blind_spot
blind_spot規定エリア内の障害物点群がある場合に、対応する位置で停止します規定エリア内の障害物点群がある場合に、対応する位置で停止します
detection_area
detection_area規定された停止線で一時停止を行います規定された停止線で一時停止を行います
stop_line
stop_line
/planning/mission_planning/route
[autoware_auto_planning_msgs/HADMapRoute]
/planning/mission_planning/route...高精度地図情報をもとに、自己位置からゴールまでのルートを計算します。高精度地図情報をもとに、自己位置からゴールまでのルートを計算します。
mission_planner
mission_planner
behavior_planning/path_with_lane_id
behavior_planning/path_with_lane_id
behavior_planning/path
behavior_planning/pathコストマップとゴールから、自車の走行ルートを計算する。いまはHA*を使ってる。コストマップとゴールから、自車の走行ルートを計算する。いまはHA*を使ってる。
freespace_planner
freespace_planner
costmap_generator/occupancy_grid
costmap_generator/occupancy_grid
goal
goal規定された停止線で一時停止を行います規定された停止線で一時停止を行います
no_drivable_lane
no_drivable_lane
<Parking>
<Parking>
parking/trajectory [Trajectory]
parking/trajectory [Trajectory]自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。
surround_obstacle_checker
surround_obstacle_checker規定された停止線で一時停止を行います規定された停止線で一時停止を行います
run_out
run_out信号の色に応じて停止/発進の指示をします信号の色に応じて停止/発進の指示をします
virtual_traffic_light
virtual_traffic_light規定された停止線で一時停止を行います規定された停止線で一時停止を行います
speed_bump
speed_bump
trajectory_follower
trajectory_follower
Control
Control縦横を分けて計算された制御コマンドを統合して出力します縦横を分けて計算された制御コマンドを統合して出力します
latlon_muxer
latlon_muxer
 /control/trajectory_follower/lateral/control_cmd
 [AckermannLateralControlCommand]

/control/trajectory_follower/lateral/control_cmd...
/control/trajectory_follower/longitudinal/control_cmd
[LongitudinalControlCommand]
/control/trajectory_follower/longitudinal/control_cmd...
/control/trajectory_follower/control_cmd
 [AckermannControlCommand]

/control/trajectory_follower/control_cmd...経路追従のための目標ステア角とステア角速度を計算します。目標速度と加速度は経路に埋め込まれた値をそのまま出力します。経路追従のための目標ステア角とステア角速度を計算します。目標速度と加速度は経路に埋め込まれた値をそのまま出力します。
lateral_controller
lateral_controller経路の目標速度に沿うための目標加速度を計算します。遅延補正や停止時のブレーキ抜き操作も行います。経路の目標速度に沿うための目標加速度を計算します。遅延補正や停止時のブレーキ抜き操作も行います。
longitudinal_controller
longitudinal_controller指示モードに応じて、複数のコマンドの中から後段に渡すコマンドを選択します。指示モードに応じて、複数のコマンドの中から後段に渡すコマンドを選択します。
vehicle_cmd_gate
vehicle_cmd_gate
control/command/control_cmd
 [AckermannControlCommand]
control/command/control_cmd...
/control/shift_decider/gear_cmd
[GearCommand]
/control/shift_decider/gear_cmd...制御出力に応じてギア変更のコマンドを出力します制御出力に応じてギア変更のコマンドを出力します
shift_decider
shift_decider遠隔から来たコマンド（アクセル/ブレーキ）を目標速度/加速度の信号に変換します遠隔から来たコマンド（アクセル/ブレーキ）を目標速度/加速度の信号に変換します
external_cmd_
converter
external_cmd_...
/diagnostics
/diagnosticsMPCの出す予測経路と、laneletのレーン情報を用いて、車両がレーン外に出ようとしているかどうかを判定する。diag出力をerror_monitorに送り、逸脱判断字は停止する（option）MPCの出す予測経路と、laneletのレーン情報を用いて、車両がレーン外に出ようとしているかどうかを判定する。diag出力をerror_monitorに送り、逸脱判断字は停止する（option）
lane_departure_
checker
lane_departure_...
predicted_trajectory
predicted_trajectory
/external/selected/external_control_cmd
 [tier4_external_api_msgs/msg/ControlCommandStamped]
/external/selected/external_control_cmd...
external_cmd_
selector
external_cmd_...
/api/external/set/command/remote/control 
   [tier4_external_api_msgs/msg/ControlCommandStamped]
/api/external/set/command/remote/shift
   [tier4_external_api_msgs/msg/GearShiftStamped]
/api/external/set/command/remote/turn_signal
   [tier4_external_api_msgs/msg/TurnSignalStamped]
/api/external/set/command/remote/control...
z
z
/current_gate_mode [GateMode]
/gear_cmd [GearCommand]
/turn_indicators_cmd  [TurnIndicatorCommand]
/hazard_lights_cmd  [HazardLightsCommand]
/vehicle_emergency_cmd [VehicleEmergencyStamped]
/current_gate_mode [GateMode]...ヤマハのGCとのインターフェースヤマハのGCとのインターフェース
g30_interface
g30_interface速度・加速度の目標値を、車両特有の制御信号（アクセル/ブレーキ等）に変換します速度・加速度の目標値を、車両特有の制御信号（アクセル/ブレーキ等）に変換します
raw_vehicle_cmd_
converter
raw_vehicle_cmd_...
/vehicle/command/actuation_cmd
/vehicle/command/actuation_cmdpacmodとのinterfaced。LexusとかJapanTaxiとか。pacmodとのinterfaced。LexusとかJapanTaxiとか。
pacmod_interface
pacmod_interface
VehicleInterface
VehicleInterface
/vehicle/status/velocity_status
/vehicle/status/steering_status
/vehicle/status/turn_indicators_status
/vehicle/status/gear_status
/vehicle/status/control_mode
/vehicle/status/actuation_status
/vehicle/s...Autowareと車両のinterfaceです。データの変換が主なタスクです。Autowareと車両のinterfaceです。データの変換が主なタスクです。
    vehicle_interface
    vehicle_interface
accel_map_calibrator
accel_map_calibrator
/pacmod/**
/pacmod/**
Vehicle
Vehicle
<CAN>
<CAN>ASといろいろあったよASといろいろあったよ
JapanTaxi
JapanTaxi
pacmod3
pacmod3ゴルフカート！！ゴルフカート！！
YMC GolfCart
YMC GolfCart
top/velodyne_packets
top/velodyne_packetsvelodyneのdriverです。VLP16, VLP32, VLS128, Livoxなどなど、たくさん種類があります。velodyneのdriverです。VLP16, VLP32, VLS128, Livoxなどなど、たくさん種類があります。
lidar_driver
lidar_driver
top/rectified/pointcloud
top/rectified/pointcloud自車の回転によって生じたLiDAR点群の歪みを補正する。（リンクこれで合ってるっけ？）自車の回転によって生じたLiDAR点群の歪みを補正する。（リンクこれで合ってるっけ？）
fix_distortion
fix_distortion
top/pointcloud_raw
top/pointcloud_rawvelodyneのpacketをpointcloud型に変更するvelodyneのpacketをpointcloud型に変更する
packets_to_
pointcloud
packets_to_...
top/self_cropped/pointcloud
top/self_cropped/pointcloud自車の領域内にある点群を除去する。自車の領域内にある点群を除去する。
crop_box_
filter_self
crop_box_...
top/mirror_cropped/pointcloud
top/mirror_cropped/pointcloud自車のサイドミラーの部分に当たった点群を除去する自車のサイドミラーの部分に当たった点群を除去する
crop_box_
filter_mirror
crop_box_...点群のノイズ処理を行う （同一リングから得られたLiDARの点をクラスタリングし、点群数の少ないクラスタに属する点群はノイズとして除去される）点群のノイズ処理を行う （同一リングから得られたLiDARの点をクラスタリングし、点群数の少ないクラスタに属する点群はノイズとして除去される）
ring_outlier_filter
ring_outlier_filter
lidar/*/velodyne_packets
lidar/*/velodyne_packets
lidar_drivers
(left,right,front_right, front_left,rear)
lidar_drivers...
*/rectified/pointcloud
*/rectified/pointcloud自車の回転によって生じたLiDAR点群の歪みを補正する。（リンクこれで合ってるっけ？）自車の回転によって生じたLiDAR点群の歪みを補正する。（リンクこれで合ってるっけ？）
fix_distortion
fix_distortion
*/pointcloud_raw
*/pointcloud_rawvelodyneのpacketをpointcloud型に変更するvelodyneのpacketをpointcloud型に変更する
packets_to_
pointcloud
packets_to_...
*/self_cropped/pointcloud
*/self_cropped/pointcloud自車の領域内にある点群を除去する。自車の領域内にある点群を除去する。
crop_box_
filter_self
crop_box_...
*/mirror_cropped/pointcloud
*/mirror_cropped/pointcloud自車のサイドミラーの部分に当たった点群を除去する自車のサイドミラーの部分に当たった点群を除去する
crop_box_
filter_mirror
crop_box_...点群のノイズ処理を行う （同一リングから得られたLiDARの点をクラスタリングし、点群数の少ないクラスタに属する点群はノイズとして除去される）点群のノイズ処理を行う （同一リングから得られたLiDARの点をクラスタリングし、点群数の少ないクラスタに属する点群はノイズとして除去される）
ring_outlier_filter
ring_outlier_filter
concatenated/pointcloud
concatenated/pointcloud複数のLiDAR点群をまとめて1つにする複数のLiDAR点群をまとめて1つにする
concat_filter
concat_filterMGRS座標系への変換MGRS座標系への変換
gnss_poser
gnss_posergnssのdriverですgnssのdriverです
gnss_driver
gnss_driverimuのdriverですimuのdriverです
imu_driver
imu_driver
/sensing/imu/imu_raw
/sensing/imu/imu_raw
/sensing/lidar/pointcloud
/sensing/lidar/pointcloud
/sensing/lidar/
concatenated/pointcloud
/sensing/lidar/...
/sensing/gnss/
pose_with_covariance
/sensing/gnss/...ヨーレートのバイアス除去とかをするノードヨーレートのバイアス除去とかをするノード
imu_corrector
imu_corrector
/sensing/imu/imu_data
/sensing/imu/imu_data
Sensing
Sensing
Localization
Localization各々データを監視し、異常があればdiagで通知します各々データを監視し、異常があればdiagで通知します
system_monitors
system_monitors
System
System
autoware_process_
monitor
autoware_process_...
autoware_gpu_
monitor
autoware_gpu_...
autoware_mem_
monitor
autoware_mem_...
autoware_hdd_
monitor
autoware_hdd_...
autoware_net_
monitor
autoware_net_...
autoware_ntp_
monitor
autoware_ntp_...
/system/emergency/hazard_status
/system/emergency/hazard_status
system_error_
monitor
system_error_...
/system/emergency/control_cmd [AckermannControlCommand]
/system/emergency/gear_cmd [GearCommand]
/system/emergency/hazard_lights_cmd [HazardLightsCommand]
/system/emergency/emergency_state [EmergencyStateStamped]
/system/emergency/control_cmd [AckermannControlCommand]...なにかしてますなにかしてます
emergency_handler
emergency_handler
/autoware/state
/autoware/state
/diagnostics
/diagnosticsなにかしてますなにかしてます
ad_service_
state_monitor
ad_service_...
/control/current_gate_mode
/vehicle/status/control_mode
/autoware/state
/control/c...
    /control/command/control_cmd
    /control/trajectory_follower/control_cmd
    /initialpose2d
    /localization/kinematic_state
    /map/pointcloud_map
    /map/vector_map
    /perception/object_recognition/objects
    /planning/mission_planning/route
    /planning/scenario_planning/trajectory
    /system/emergency/control_cmd
    /vehicle/status/control_mode
    /vehicle/status/steering_status
    /vehicle/status/velocity_status
/contr...
/autoware/engage
/autoware/engageText is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-adaptive-cruise.drawio.svg b/docs/design/autoware-architecture/planning/image/features-adaptive-cruise.drawio.svg new file mode 100644 index 00000000000..a02e0088582 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-adaptive-cruise.drawio.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-aeb.drawio.svg b/docs/design/autoware-architecture/planning/image/features-aeb.drawio.svg new file mode 100644 index 00000000000..edb0b1f334d --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-aeb.drawio.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + +
+
+
+ + + ! + + +
+
+
+ + + ! + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-avoidance.drawio.svg b/docs/design/autoware-architecture/planning/image/features-avoidance.drawio.svg new file mode 100644 index 00000000000..9720c34ce03 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-avoidance.drawio.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-blind-spot.drawio.svg b/docs/design/autoware-architecture/planning/image/features-blind-spot.drawio.svg new file mode 100644 index 00000000000..0dc0e3865e1 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-blind-spot.drawio.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-crosswalk.drawio.svg b/docs/design/autoware-architecture/planning/image/features-crosswalk.drawio.svg new file mode 100644 index 00000000000..17d9452f8a8 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-crosswalk.drawio.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-cut-in.drawio.svg b/docs/design/autoware-architecture/planning/image/features-cut-in.drawio.svg new file mode 100644 index 00000000000..094ffc7baad --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-cut-in.drawio.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-decel-on-curve-obstacles.drawio.svg b/docs/design/autoware-architecture/planning/image/features-decel-on-curve-obstacles.drawio.svg new file mode 100644 index 00000000000..328fd0c5319 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-decel-on-curve-obstacles.drawio.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-decel-on-curve.drawio.svg b/docs/design/autoware-architecture/planning/image/features-decel-on-curve.drawio.svg new file mode 100644 index 00000000000..a36583390e4 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-decel-on-curve.drawio.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-detection-area.drawio.svg b/docs/design/autoware-architecture/planning/image/features-detection-area.drawio.svg new file mode 100644 index 00000000000..aa0656bc169 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-detection-area.drawio.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-intersection-occlusion.drawio.svg b/docs/design/autoware-architecture/planning/image/features-intersection-occlusion.drawio.svg new file mode 100644 index 00000000000..a7fb42961e3 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-intersection-occlusion.drawio.svg @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-intersection-traffic-jam.drawio.svg b/docs/design/autoware-architecture/planning/image/features-intersection-traffic-jam.drawio.svg new file mode 100644 index 00000000000..10177591fd4 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-intersection-traffic-jam.drawio.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-intersection.drawio.svg b/docs/design/autoware-architecture/planning/image/features-intersection.drawio.svg new file mode 100644 index 00000000000..80de7420572 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-intersection.drawio.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-lane-change.drawio.svg b/docs/design/autoware-architecture/planning/image/features-lane-change.drawio.svg new file mode 100644 index 00000000000..20f7b98fe88 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-lane-change.drawio.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-lane-follow.drawio.svg b/docs/design/autoware-architecture/planning/image/features-lane-follow.drawio.svg new file mode 100644 index 00000000000..324e3862333 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-lane-follow.drawio.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-narrow-space-driving.drawio.svg b/docs/design/autoware-architecture/planning/image/features-narrow-space-driving.drawio.svg new file mode 100644 index 00000000000..ee55fd69109 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-narrow-space-driving.drawio.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-no-drivable-lane.drawio.svg b/docs/design/autoware-architecture/planning/image/features-no-drivable-lane.drawio.svg new file mode 100644 index 00000000000..927b621336c --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-no-drivable-lane.drawio.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-no-stopping-area.drawio.svg b/docs/design/autoware-architecture/planning/image/features-no-stopping-area.drawio.svg new file mode 100644 index 00000000000..7159aed2202 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-no-stopping-area.drawio.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-obstacle-decel.drawio.svg b/docs/design/autoware-architecture/planning/image/features-obstacle-decel.drawio.svg new file mode 100644 index 00000000000..c48e529b9c6 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-obstacle-decel.drawio.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-obstacle-stop.drawio.svg b/docs/design/autoware-architecture/planning/image/features-obstacle-stop.drawio.svg new file mode 100644 index 00000000000..6e9595cf515 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-obstacle-stop.drawio.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-occlusion-spot.drawio.svg b/docs/design/autoware-architecture/planning/image/features-occlusion-spot.drawio.svg new file mode 100644 index 00000000000..c8f2ab3c123 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-occlusion-spot.drawio.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-parking.drawio.svg b/docs/design/autoware-architecture/planning/image/features-parking.drawio.svg new file mode 100644 index 00000000000..4fa74d36225 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-parking.drawio.svg @@ -0,0 +1,29 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-path-smoothing.drawio.svg b/docs/design/autoware-architecture/planning/image/features-path-smoothing.drawio.svg new file mode 100644 index 00000000000..6eaded25545 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-path-smoothing.drawio.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-pull-out.drawio.svg b/docs/design/autoware-architecture/planning/image/features-pull-out.drawio.svg new file mode 100644 index 00000000000..8c67f0a8605 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-pull-out.drawio.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-pull-over.drawio.svg b/docs/design/autoware-architecture/planning/image/features-pull-over.drawio.svg new file mode 100644 index 00000000000..696d069d507 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-pull-over.drawio.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-route-planning.drawio.svg b/docs/design/autoware-architecture/planning/image/features-route-planning.drawio.svg new file mode 100644 index 00000000000..972c23fafac --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-route-planning.drawio.svg @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + +
+
+
+ + start + +
+
+
+ + + start + + + + + + +
+
+
+ + check +
+ point 1 + +
+
+
+ + + check... + + + + + + +
+
+
+ + check point 2 + +
+
+
+ + + check p... + + + + + + +
+
+
+ + goal + +
+
+
+ + + goal + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-run-out.drawio.svg b/docs/design/autoware-architecture/planning/image/features-run-out.drawio.svg new file mode 100644 index 00000000000..783cb364852 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-run-out.drawio.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-side-shift.drawio.svg b/docs/design/autoware-architecture/planning/image/features-side-shift.drawio.svg new file mode 100644 index 00000000000..0317f5abb28 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-side-shift.drawio.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-speed-bump.drawio.svg b/docs/design/autoware-architecture/planning/image/features-speed-bump.drawio.svg new file mode 100644 index 00000000000..b56136dd9ec --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-speed-bump.drawio.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-stop-line.drawio.svg b/docs/design/autoware-architecture/planning/image/features-stop-line.drawio.svg new file mode 100644 index 00000000000..6c7fe0cc020 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-stop-line.drawio.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + +
+
+
+ + + STOP + + +
+
+
+ + + STOP + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-surround-check.drawio.svg b/docs/design/autoware-architecture/planning/image/features-surround-check.drawio.svg new file mode 100644 index 00000000000..a698da0add1 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-surround-check.drawio.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-traffic-light.drawio.svg b/docs/design/autoware-architecture/planning/image/features-traffic-light.drawio.svg new file mode 100644 index 00000000000..39cd9d0e0c9 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-traffic-light.drawio.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-trajectory-validation.drawio.svg b/docs/design/autoware-architecture/planning/image/features-trajectory-validation.drawio.svg new file mode 100644 index 00000000000..2f999a6e78e --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-trajectory-validation.drawio.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-velocity-smoothing.drawio.svg b/docs/design/autoware-architecture/planning/image/features-velocity-smoothing.drawio.svg new file mode 100644 index 00000000000..3c239429c1f --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-velocity-smoothing.drawio.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + speed limit + +
+ + 50 + + +
+
+
+ + + speed li... + + + + + + + + + + + + +
+
+
+ + + speed limit + +
+ + 30 + + +
+
+
+ + + speed li... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/high-level-planning-diagram.drawio.svg b/docs/design/autoware-architecture/planning/image/high-level-planning-diagram.drawio.svg new file mode 100644 index 00000000000..bbf860704b2 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/high-level-planning-diagram.drawio.svg @@ -0,0 +1,582 @@ + + + + + + + + + +
+
+
+
+ Localization +
+
+ Component +
+
+
+
+ + + Localization... + + + + + + + +
+
+
+ Perception +
+ Component +
+
+
+ + + Perception... + + + + + + + + + +
+
+
+ Human +
+ Machine +
+ Interface +
+
+
+ + + Human... + + + + + + + +
+
+
+ API Layer +
+
+
+ + + API Layer + + + + + + + + + + + + +
+
+
+ + Mission Planning + +
+
+
+ + + Mission Planning + + + + + + + +
+
+
+ +
+ Scenario Planning + +
+
+
+ + + Scenario Planning + + + + + + + +
+
+
+ +
+ Lane Driving Scenario + +
+
+
+ + + Lane Driving Scenario + + + + + + + + + +
+
+
+ +
+ Parking Scenario + +
+
+
+ + + Parking Scenario + + + + + + + + + +
+
+
+ + Behavior Planning + +
+
+
+ + + Behavior Planning + + + + + + + + + +
+
+
+ + Motion Planning + +
+
+
+ + + Motion Planning + + + + + + + + + +
+
+
+ + Validation + +
+
+
+ + + Validation + + + + + + + +
+
+
+ Control Component +
+
+
+ + + Control Component + + + + + + + + +
+
+
+ + Planning Component + +
+
+
+ + + Planning Component + + + + + + + + + +
+
+
+
+ System +
+
+ Component +
+
+
+
+ + + System... + + + + + + + + + +
+
+
+ Map +
+ Component +
+
+
+ + + Map... + + + + + + + +
+
+
+
+ Lane Change +
+
+
+
+ + + Lane Change + + + + + + + +
+
+
+
+ Intersection +
+
+
+
+ + + Intersection + + + + + + + +
+
+
+
+ Crosswalk +
+
+
+
+ + + Crosswalk + + + + + + + +
+
+
+
+ etc... +
+
+
+
+ + + etc... + + + + + + + +
+
+
+
+ Path Smooth +
+
+
+
+ + + Path Smooth + + + + + + + +
+
+
+
+ Velocity Smooth +
+
+
+
+ + + Velocity Smooth + + + + + + + +
+
+
+
+ Collision Check +
+
+
+
+ + + Collision Check + + + + + + + +
+
+
+
+ etc... +
+
+
+
+ + + etc... + + + + + + + +
+
+
+
+ Free Space +
+
+
+
+ + + Free Space + + + + + + + +
+
+
+
+ Cost map +
+
+
+
+ + + Cost map + + + + + + + +
+
+
+
+ etc... +
+
+
+
+ + + etc... + + + + + + + + + + + + + + + +
+
+
+
+ Trajectory Validation +
+
+
+
+ + + Trajectory Validation + + + + + + + +
+
+
+
+ Route Planning +
+
+
+
+ + + Route Planning + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg b/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg index 82d79d3c297..bde7965b6fc 100644 --- a/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg +++ b/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg @@ -1,1357 +1,4 @@ - - - - - - - - - - - - -
-
-
- Parking Scenario -
-
-
- - - Parking Scenario - - - - - - - - - - -
-
-
- route -
-
-
- - - route - - - - - - - - -
-
-
- mission_planner -
-
-
- - - mission_planner - - - - - - - - - -
-
-
- path_with_lane_id -
-
-
- - - path_with_lane_id - - - - - - - - - - - -
-
-
- path -
-
-
- - - path - - - - - - - - - - - -
-
-
- Trajectory -
-
-
- - - Trajectory - - - - - - - - -
-
-
- obstacle_ -
- avoidance_planner -
-
-
- - - obstacle_... - - - - - - - - - -
-
-
- Trajectory -
-
-
- - - Trajectory - - - - - - - - -
-
-
- surround_ -
- obstacle_checker -
-
-
- - - surround_... - - - - - - - - - -
-
-
- Trajectory -
-
-
- - - Trajectory - - - - - - - - - - - -
-
-
- Trajectory -
-
-
- - - Trajectory - - - - - - - - -
-
-
- scenario_selector -
-
-
- - - scenario_selector - - - - - - - - - -
-
-
- - Trajectory - -
-
-
- - - Trajectory - - - - - - - - -
-
-
- motion_velocity_ -
- smoother -
-
-
- - - motion_velocity_... - - - - - - - - - -
-
-
- Trajectory -
-
-
- - - Trajectory - - - - - - - - -
-
-
- freespace_planner -
-
-
- - - freespace_planner - - - - - - - - - -
-
-
- occupancy_grid -
-
-
- - - occupancy_grid - - - - - - - - -
-
-
- costmap_generator -
-
-
- - - costmap_generator - - - - - - - - -
-
-
- behavior -
- velocity -
- planner -
-
-
- - - behavior... - - - - - - - -
-
-
- behavior -
- path -
- planner -
-
-
- - - behavior... - - - - - - - - -
-
-
- goal -
-
-
- - - goal - - - - - - - - - -
-
-
- obstacle -
- stop -
- planner -
-
-
- - - obstacle... - - - - - - - -
-
-
- slow_down -
-
-
- - - slow_down - - - - - - - -
-
-
- adaptive_cruise -
-
-
- - - adaptive_cruise - - - - - - - -
-
-
- stop -
-
-
- - - stop - - - - - - - -
-
-
- LaneDriving Scenario -
-
-
- - - LaneDriving Sce... - - - - - - - -
-
-
- - - Behavior Planning - - -
-
-
- - - Behavior Planning - - - - - - - -
-
-
- - - Motion Planning - - -
-
-
- - - Motion Planning - - - - - - - - - - -
-
-
- vector_map -
-
-
- - - vector_map - - - - - - - -
-
-
- To Control -
-
-
- - - To Control - - - - - - - - -
-
-
- vector_map -
-
-
- - - vector_map - - - - - - - - -
-
-
- Dynamic Objects -
-
-
- - - Dynamic Objects - - - - - - - - -
-
-
- Dynamic Objects -
-
-
- - - Dynamic Objects - - - - - - - - -
-
-
- Dynamic Objects -
-
-
- - - Dynamic Objects - - - - - - - - -
-
-
- Dynamic Objects -
-
-
- - - Dynamic Objects - - - - - - - - -
-
-
- Obstacle Points -
-
-
- - - Obstacle Points - - - - - - - - -
-
-
- Obstacle Points -
-
-
- - - Obstacle Points - - - - - - - - -
-
-
- Dynamic Objects -
-
-
- - - Dynamic Objects - - - - - - - - -
-
-
- Obstacle Points -
-
-
- - - Obstacle Points - - - - - - - - -
-
-
- route (from mission_planner) -
-
-
- - - route (from mission_planner) - - - - - - - - -
-
-
- map -
-
-
- - - map - - - - - - - - - - -
-
-
- map -
-
-
- - - map - - - - - - - - -
-
-
- vehicle_state -
- TF (map to baselink) -
-
-
- - - vehicle_state... - - - - - - - -
-
-
-
- Localization -
-
-
-
- - - Localization - - - - - - - - -
-
-
- approval, -
- force_approval -
-
-
- - - approval,... - - - - - - - - -
-
-
- external_crosswalk_states, -
- external_intersection_states, -
- external_traffic_light_states -
-
-
- - - external_crosswalk_states,... - - - - - - - -
-
-
- Planning -
-
-
- - - Planning - - - - - - - - -
-
-
- Traffic Light States -
-
-
- - - Traffic Light States - - - - - - - - -
-
-
- expand_stop_range -
-
-
- - - expand_stop_range - - - - - - - -
-
-
- Perception -
-
-
- - - Perception - - - - - - - - -
-
-
- velocity_limit -
- (from external modules) -
-
-
- - - velocity_limit... - - - - - - - -
-
-
- Human -
- Machine -
- Interface -
-
-
- - - Human... - - - - - - - - - -
-
-
- Perception -
-
-
- - - Perception - - - - - - - - - -
-
-
- external_velocity -
- _limit_selector -
-
-
- - - external_velocity... - - - - - - - - -
-
-
- velocity_limit -
- (from other planning modules) -
-
-
- - - velocity_l... - - - - - - - -
-
-
- avoidance -
-
-
- - - avoidance - - - - - - - -
-
-
- side_shift -
-
-
- - - side_shift - - - - - - - -
-
-
- lane_change -
-
-
- - - lane_change - - - - - - - -
-
-
- lane_following -
-
-
- - - lane_following - - - - - - - -
-
-
- pull_over -
-
-
- - - pull_over - - - - - - - -
-
-
- pull_out -
-
-
- - - pull_out - - - - - - - -
-
-
- blind_spot -
-
-
- - - blind_spot - - - - - - - -
-
-
- cross_walk -
-
-
- - - cross_walk - - - - - - - -
-
-
- stop_line -
-
-
- - - stop_line - - - - - - - -
-
-
- traffic_light -
-
-
- - - traffic_light - - - - - - - -
-
-
- intersection -
-
-
- - - intersection - - - - - - - -
-
-
- detection_area -
-
-
- - - detection_area - - - - - - - -
-
-
- no_stopping_area -
-
-
- - - no_stopping_area - - - - - - - -
-
-
- virtual_traffic_light -
-
-
- - - virtual_traffic_light - - - - - - - -
-
-
- occlusion_spot -
-
-
- - - occlusion_spot - - - - - - - -
-
-
- run_out -
-
-
- - - run_out - - - - - - - - -
-
-
- check_point -
-
-
- - - check_point - - - - - - - - - Viewer does not support full SVG 1.1 - - - - + + + +
Parking Scenario
Parking Scenario
route
route高精度地図情報をもとに、自己位置からゴールまでのルートを計算します。高精度地図情報をもとに、自己位置からゴールまでのルートを計算します。
mission_planner
mission_planner
path_with_lane_id
path_with_lane_idルート情報や障害物情報をもとに、レーンチェンジを実行します。
path
path交通ルールをもとに、経路上の最大速度を決定します。各モジュールは、自身の計算した最大速度と上段の結果を比較し、小さい速度を経路上に書き込みます。
Trajectory
Trajectory車両形状や走行可能領域を考慮して、経路の平滑化を行う。障害物も避けるが、long historyで最近は回避機能はoffになっています。車両形状や走行可能領域を考慮して、経路の平滑化を行う。障害物も避けるが、long historyで最近は回避機能はoffになっています。
obstacle_
avoidance_planner
obstacle_...
Trajectory
Trajectory自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。
obstacle_velocity_limiter
obstacle_velocity_limiter
Trajectory
Trajectory障害物停止・前車追従・近傍障害物減速の複数の機能を持ち、機能に応じて経路上に速度を埋め込む。 目標経路上に障害物点がある場合は停止、経路近くに障害物点群がある場合は減速、前方に車両が居る場合は前車追従。
Trajectory
Trajectoryいまのrouteおよび地図情報から、LaneDriving / Parkingのシナリオを判断し、どちらの経路を使うかを切り替える。いまのrouteおよび地図情報から、LaneDriving / Parkingのシナリオを判断し、どちらの経路を使うかを切り替える。
scenario_selector
scenario_selector
Trajectory
Trajectory経路に埋め込まれた最大速度を超過しないように、うまい具合で速度を平滑化する。カーブでの減速もここで行う。経路に埋め込まれた最大速度を超過しないように、うまい具合で速度を平滑化する。カーブでの減速もここで行う。
motion_velocity_
smoother
motion_velocity_...
Trajectory
Trajectoryコストマップとゴールから、自車の走行ルートを計算する。いまはHA*を使ってる。コストマップとゴールから、自車の走行ルートを計算する。いまはHA*を使ってる。
freespace_planner
freespace_planner
occupancy_grid
occupancy_grid障害物点群や地図の走行可能エリアの情報から、駐車プランナー用のコストマップを生成する。障害物点群や地図の走行可能エリアの情報から、駐車プランナー用のコストマップを生成する。
costmap_generator
costmap_generator
behavior
velocity
planner
behavior...
behavior
path
planner
behavior...
goal
goal
obstacle
stop
planner
obstacle...障害物回避の可否判定と実行障害物回避の可否判定と実行
slow_down
slow_down入力シフト量に応じて経路を横方向にシフトさせる入力シフト量に応じて経路を横方向にシフトさせる
adaptive_cruise
adaptive_cruiseレーンチェンジの可否判定と実行レーンチェンジの可否判定と実行
stop
stop
LaneDriving Scenario
LaneDriving Sce...
Behavior Planning
Behavior Planning
Motion Planning
Motion Planning
vector_map
vector_map
To Control
To Control
vector_map
vector_map
Dynamic Objects
Dynamic Objects
Dynamic Objects
Dynamic Objects
Dynamic Objects
Dynamic Objects
Dynamic Objects
Dynamic Objects
Obstacle Points
Obstacle Points
Obstacle Points
Obstacle Points
Dynamic Objects
Dynamic Objects
Obstacle Points
Obstacle Points
route (from mission_planner)
route (from mission_planner)
map
map
map
map
vehicle_state
vehicle_state
Localization
Localization
approval,
force_approval
approval,...
external_crosswalk_states,
external_intersection_states,
external_traffic_light_states
external_crosswalk_states,...
Planning
Planning
Traffic Light States
Traffic Light States
expand_stop_range
expand_stop_range
Perception
Perception
velocity_limit
(from external modules)
velocity_limit...
Human
Machine
Interface
Human...
Perception
Perception
external_velocity
_limit_selector
external_velocity...
velocity_limit
velocity_l...障害物回避の可否判定と実行障害物回避の可否判定と実行
avoidance
avoidance入力シフト量に応じて経路を横方向にシフトさせる入力シフト量に応じて経路を横方向にシフトさせる
side_shift
side_shiftレーンチェンジの可否判定と実行レーンチェンジの可否判定と実行
lane_change
lane_change通常走行通常走行
lane_following
lane_following
pull_over
pull_over
pull_out
pull_out右左折時に車両後方の巻き込み確認を行い、衝突の危険がある場合は停止します。右左折時に車両後方の巻き込み確認を行い、衝突の危険がある場合は停止します。
blind_spot
blind_spot横断歩道に人が居る、もしくは侵入しようとしてきている場合に、横断歩道手前で停止します。近くに人が居る場合は徐行します。横断歩道に人が居る、もしくは侵入しようとしてきている場合に、横断歩道手前で停止します。近くに人が居る場合は徐行します。
cross_walk
cross_walk規定された停止線で一時停止を行います規定された停止線で一時停止を行います
stop_line
stop_line信号の色に応じて停止/発進の指示をします信号の色に応じて停止/発進の指示をします
traffic_light
traffic_light地図情報および動物体情報から、交差点での停止/発進の判定を行います。地図情報および動物体情報から、交差点での停止/発進の判定を行います。
intersection
intersection規定エリア内の障害物点群がある場合に、対応する位置で停止します規定エリア内の障害物点群がある場合に、対応する位置で停止します
detection_area
detection_area
no_stopping_area
no_stopping_area
virtual_traffic_light
virtual_traffic_light
occlusion_spot
occlusion_spot
run_out
run_out
check_point
check_point
vector_map
vector_map自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。自車が停止しているときに、周囲の障害物を確認し、近くに障害物がいる場合は車両を発進させない。
surround_obstacle_checker
surround_obstacle_checker
(from other planning modules)
(from othe...
Obstacle Points
Obstacle Points
Dynamic Objects
Dynamic Objects
Trajectory
TrajectoryCheck the trajectory and stop publishing it if it is unsafe.Check the trajectory and stop publishing it if it is unsafe.
planning_validator
planning_validator
no_drivable_lane
no_drivable_laneText is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/index.md b/docs/design/autoware-architecture/planning/index.md index 484c154846a..1cfbd97c1a2 100644 --- a/docs/design/autoware-architecture/planning/index.md +++ b/docs/design/autoware-architecture/planning/index.md @@ -2,47 +2,148 @@ ## Overview -Planning stack acts as the “brain” of autonomous driving. It uses all the results from Localization, Perception, and Map stacks to decide its maneuver and gives final trajectory to Control stack. +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. -## Role +## Requirements -These are high-level roles of Planning stack: +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. -- Calculates route that navigates to desired goal -- Plans trajectory to follow the route - - Make sure that vehicle does not collide with obstacles, including pedestrians and other vehicles - - Make sure that the vehicle follows traffic rules during the navigation. This includes following traffic light, stopping at stoplines, stopping at crosswalks, etc. -- Plan sequences of trajectories that is feasible for the vehicle. (e.g. no sharp turns that is kinematically impossible) +**Goals:** -## Input +- 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. -The table below summarizes the overall input into Planning stack: +**Non-goals:** -| Input | Topic Name(Data Type) | Explanation | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Vehicle Pose | `/tf (map->base_link)`
(_tf::tfMessage_) | Planning requires vehicle pose in map frame, which is the frame where all planning takes place. | -| Vehicle Kinematics | `/localization/kinematic_state`
(_nav_msgs/msg/Odometry_) | This includes vehicle's pose and velocity information. It is used to predict future pose on trajectory to detect collision with other objects. | -| Map data | `/map/vector_map`
(_autoware_auto_mapping_msgs/msg/HADMapBin_) | This includes all static information about the environment, such as:
  • Lane connection information used for route planning from starting position to goal position
  • Lane geometry to generate reference path used to calculate trajectory
  • All information related to traffic rules
| -| Detected Object Information | `/perception/object_recognition/objects`
(_autoware_auto_perception_msgs/msg/PredictedObjects_) | This includes information that cannot be known beforehand such as pedestrians and other vehicles. Planning stack will plan maneuvers to avoid collision with such objects. | -| Detected Obstacle Information | `/perception/obstacle_segmentation/pointcloud`
(_sensor_msgs/msg/PointCloud2_) | This includes information on the location of obstacles. This is more primitive information and is used for emergency stops, etc. | -| Occupancy Map Information | `/perception/occupancy_grid_map/map`
(_nav_msgs/msg/OccupancyGrid_) | This includes information that cannot be known beforehand such as pedestrians and other vehicles. Planning stack will plan maneuvers to avoid collision with such objects. | -| TrafficLight recognition result | `/perception/traffic_light_recognition/traffic_signals`
(_autoware_auto_perception_msgs/msg/TrafficSignalArray_) | This is the real time information about the state of each traffic light. Planning stack will extract the one that is relevant to planned path and use it to decide whether to stop at intersections. | -| Goal position | `/planning/mission_planning/goal`
(_geometry_msgs::PoseStamped_) | This is the final pose that Planning stack will try to achieve. | -| Check point position | `/planning/mission_planning/check_point`
(_geometry_msgs::PoseStamped_) | This is the midpoint that Planning will try to go at on the way to the destination. This is used when calculating the route. | +- 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 “never crashes”. -## Output +## High-level architecture -The table below summarizes the final output from Planning stack: +This diagram describes the high-level architecture of the Planning Component. -| Output | Topic(Data Type) | Explanation | -| ------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Trajectory | `/planning/trajectory`
(_autoware_auto_planning_msgs/msg/Trajectory_) | This is the sequence of pose, twist and acceleration that Control stack must follow. This must be smooth, and kinematically possible to follow by the Control stack. By default, the trajectory is 10 seconds long at 0.1 second resolution. | -| Turn Signal | `/planning/turn_indicators_cmd`
(_autoware_auto_vehicle_msgs/msg/TurnIndicatorsCommand_) | This is the output to control turn signals of the vehicle. Planning stack will make sure that turn signal will be turned on according to planned maneuver. | -| Hazard Signal | `/planning/hazard_lights_cmd`
(_autoware_auto_vehicle_msgs/msg/HazardLightsCommand_) | This is the output to control hazard signals of the vehicle. Planning stack will make sure that hazard signal will be turned on according to planned maneuver. | +![overall-planning-architecture](image/high-level-planning-diagram.drawio.svg) -## Implementation +The Planning component consists of the following sub-components: -The implementation of the planning module in the latest version is shown as below. +- **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 path 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. + +## Component interface + +This section describes the inputs and outputs of the Planning Component and of its internal modules. See the [Planning Component Interface](../../autoware-interfaces/components/planning.md) page for the current implementation. + +### Input to the planning component + +- **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. + +### Output from the planning component + +- **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. + +### Internal interface in the planning component + +- **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. + +## How to add new modules (WIP) + +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). + +## Supported Functions + +| Feature | Description | Requirements | Figure | +| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Route Planning | Plan route from the ego vehicle position to the destination.

Reference implementation is in [Mission Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/mission_planner/), enabled by launching the `mission_planner` node. | - Lanelet map (driving lanelets) | ![route-planning](image/features-route-planning.drawio.svg) | +| Path Planning from Route | Plan path to be followed from the given route.

Reference implementation is in [Behavior Path Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/). | - Lanelet map (driving lanelets) | ![lane-follow](image/features-lane-follow.drawio.svg) | +| Obstacle Avoidance | Plan path to avoid obstacles by steering operation.

Reference implementation is in [Avoidance](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_avoidance_design/), [Obstacle Avoidance Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_avoidance_planner/). Enable flag in parameter: `launch obstacle_avoidance_planner true`

[Demonstration Video](https://youtu.be/A_V9yvfKZ4E)
[![Demonstration Video](https://img.youtube.com/vi/A_V9yvfKZ4E/0.jpg)](https://www.youtube.com/watch?v=A_V9yvfKZ4E) | - objects information | ![obstacle-avoidance](image/features-avoidance.drawio.svg) | +| Path Smoothing | Plan path to achieve smooth steering.

Reference implementation is in [Obstacle Avoidance Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_avoidance_planner/).

[Demonstration Video](https://youtu.be/RhyAF26Ppzs)
[![Demonstration Video](https://img.youtube.com/vi/RhyAF26Ppzs/0.jpg)](https://www.youtube.com/watch?v=RhyAF26Ppzs) | - Lanelet map (driving lanelet) | ![path-smoothing](image/features-path-smoothing.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_avoidance_planner/).

[Demonstration Video](https://youtu.be/URzcLO2E1vY)
[![Demonstration Video](https://img.youtube.com/vi/URzcLO2E1vY/0.jpg)](https://www.youtube.com/watch?v=URzcLO2E1vY) | - Lanelet map (high-precision lane boundaries) | ![narrow-space-driving](image/features-narrow-space-driving.drawio.svg) | +| Lane Change | Plan path for lane change to reach the destination.

Reference implementation is in [Lane Change](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_lane_change_design/).

[Demonstration Video](https://youtu.be/0jRDGQ84cD4)
[![Demonstration Video](https://img.youtube.com/vi/0jRDGQ84cD4/0.jpg)](https://www.youtube.com/watch?v=0jRDGQ84cD4) | - Lanelet map (driving lanelets) | ![lane-change](image/features-lane-change.drawio.svg) | +| Pull Over | Plan path for pull over to park at the road shoulder.

Reference implementation is in [Goal Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_goal_planner_design/).

Demonstration Videos:
[Simple Pull Over](https://youtu.be/r3-kAmTb4hc)
[![Demonstration Video](https://img.youtube.com/vi/r3-kAmTb4hc/0.jpg)](https://www.youtube.com/watch?v=r3-kAmTb4hc)
[Arc Forward Pull Over](https://youtu.be/ornbzkWxRWU)
[![Demonstration Video](https://img.youtube.com/vi/ornbzkWxRWU/0.jpg)](https://www.youtube.com/watch?v=ornbzkWxRWU)
[Arc Backward Pull Over](https://youtu.be/if-0tG3AkLo)
[![Demonstration Video](https://img.youtube.com/vi/if-0tG3AkLo/0.jpg)](https://www.youtube.com/watch?v=if-0tG3AkLo) | - Lanelet map (shoulder lane) | ![pull-over](image/features-pull-over.drawio.svg) | +| Pull Out | Plan path for pull over to start from the road shoulder.

Reference implementation is in [Pull Out Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_start_planner_design/#:~:text=WIP-,Path%20Generation,-%23).

Demonstration Video:
[Simple Pull Out](https://youtu.be/xOjnPqoHup4)
[![Demonstration Video](https://img.youtube.com/vi/xOjnPqoHup4/0.jpg)](https://www.youtube.com/watch?v=xOjnPqoHup4)
[Backward Pull Out](https://youtu.be/iGieijPcPcQ)
[![Demonstration Video](https://img.youtube.com/vi/iGieijPcPcQ/0.jpg)](https://www.youtube.com/watch?v=iGieijPcPcQ) | - Lanelet map (shoulder lane) | ![pull-out](image/features-pull-out.drawio.svg) | +| Path Shift | Plan path in lateral direction in response to external instructions.

Reference implementation is in [Side Shift Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_side_shift_design/). | - None | ![side-shift](image/features-side-shift.drawio.svg) | +| Obstacle Stop | Plan velocity to stop for an obstacle on the path.

Reference implementation is in [Obstacle Stop Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_stop_planner/), [Obstacle Cruise Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/). `launch obstacle_stop_planner` and enable flag: `TODO`, `launch obstacle_cruise_planner` and enable flag: `TODO`

[Demonstration Video](https://youtu.be/d8IRW_xArcE)
[![Demonstration Video](https://img.youtube.com/vi/d8IRW_xArcE/0.jpg)](https://www.youtube.com/watch?v=d8IRW_xArcE) | - objects information | ![obstacle-stop](image/features-obstacle-stop.drawio.svg) | +| Obstacle Deceleration | Plan velocity to decelerate for an obstacle located around the path.

Reference implementation is in [Obstacle Stop Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_stop_planner/), [Obstacle Cruise Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/).

[Demonstration Video](https://youtu.be/gvN1otgeaaw)
[![Demonstration Video](https://img.youtube.com/vi/gvN1otgeaaw/0.jpg)](https://www.youtube.com/watch?v=gvN1otgeaaw) | - objects information | ![obstacle-decel](image/features-obstacle-decel.drawio.svg) | +| Adaptive Cruise Control | Plan velocity to follow the vehicle driving in front of the ego vehicle.

Reference implementation is in [Obstacle Stop Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_stop_planner/), [Obstacle Cruise Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/). | - objects information | ![adaptive-cruise](image/features-adaptive-cruise.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/). | - objects information | ![cut-in](image/features-cut-in.drawio.svg) | +| Surround Check at starting | Plan velocity to prevent moving when an obstacle exists around the vehicle.

Reference implementation is in [Surround Obstacle Checker](https://autowarefoundation.github.io/autoware.universe/main/planning/surround_obstacle_checker/). Enable flag in parameter: `use_surround_obstacle_check true` in [tier4_planning_component.launch.xml](https://github.com/autowarefoundation/autoware_launch/blob/2850d7f4e20b173fde2183d5323debbe0067a990/autoware_launch/launch/components/tier4_planning_component.launch.xml#L8)

[Demonstration Video](https://youtu.be/bbGgtXN3lC4)
[![Demonstration Video](https://img.youtube.com/vi/bbGgtXN3lC4/0.jpg)](https://www.youtube.com/watch?v=bbGgtXN3lC4) | - objects information | ![surround-check](image/features-surround-check.drawio.svg) | +| Curve Deceleration | Plan velocity to decelerate the speed on a curve.

Reference implementation is in [Motion Velocity Smoother](https://autowarefoundation.github.io/autoware.universe/main/planning/motion_velocity_smoother/). | - None | ![decel-on-curve](image/features-decel-on-curve.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_velocity_limiter/).

[Demonstration Video](https://youtu.be/I-oFgG6kIAs)
[![Demonstration Video](https://img.youtube.com/vi/I-oFgG6kIAs/0.jpg)](https://www.youtube.com/watch?v=I-oFgG6kIAs) | - objects information
- Lanelet map (static obstacle) | ![decel-on-curve-obstacles](image/features-decel-on-curve-obstacles.drawio.svg) | +| Crosswalk | Plan velocity to stop or decelerate for pedestrians approaching or walking on a crosswalk.

Reference implementation is in [Crosswalk Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_crosswalk_module/).

[Demonstration Video](https://youtu.be/tUvthyIL2W8)
[![Demonstration Video](https://img.youtube.com/vi/tUvthyIL2W8/0.jpg)](https://www.youtube.com/watch?v=tUvthyIL2W8) | - objects information
- Lanelet map (pedestrian crossing) | ![crosswalk](image/features-crosswalk.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_intersection_module/).

[Demonstration Video](https://youtu.be/SGD07Hqg4Hk)
[![Demonstration Video](https://img.youtube.com/vi/SGD07Hqg4Hk/0.jpg)](https://www.youtube.com/watch?v=SGD07Hqg4Hk) | - objects information
- Lanelet map (intersection lane and yield lane) | ![intersection](image/features-intersection.drawio.svg) | +| 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 [Blind Spot Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_blind_spot_module/).

[Demonstration Video](https://youtu.be/oaTCJRafDGA)
[![Demonstration Video](https://img.youtube.com/vi/oaTCJRafDGA/0.jpg)](https://www.youtube.com/watch?v=oaTCJRafDGA) | - objects information
- Lanelet map (intersection lane) | ![blind-spot](image/features-blind-spot.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_intersection_module/).

[Demonstration Video](https://youtu.be/bAHXMB7kbFc)
[![Demonstration Video](https://img.youtube.com/vi/bAHXMB7kbFc/0.jpg)](https://www.youtube.com/watch?v=bAHXMB7kbFc) | - objects information
- Lanelet map (intersection lane) | ![intersection-occlusion](image/features-intersection-occlusion.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_intersection_module/).

[Demonstration Video](https://youtu.be/negK4VbrC5o)
[![Demonstration Video](https://img.youtube.com/vi/negK4VbrC5o/0.jpg)](https://www.youtube.com/watch?v=negK4VbrC5o) | - objects information
- Lanelet map (intersection lane) | ![intersection-traffic-jam](image/features-intersection-traffic-jam.drawio.svg) | +| Traffic Light | Plan velocity for intersection according to a traffic light signal.

Reference implementation is in [Traffic Light Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_traffic_light_module/).

[Demonstration Video](https://youtu.be/lGA53KljQrM)
[![Demonstration Video](https://img.youtube.com/vi/lGA53KljQrM/0.jpg)](https://www.youtube.com/watch?v=lGA53KljQrM) | - Traffic light color information | ![traffic-light](image/features-traffic-light.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_run_out_module/).

[Demonstration Video](https://youtu.be/9IDggldT2t0)
[![Demonstration Video](https://img.youtube.com/vi/9IDggldT2t0/0.jpg)](https://www.youtube.com/watch?v=9IDggldT2t0) | - objects information | ![run-out](image/features-run-out.drawio.svg) | +| Stop Line | Plan velocity to stop at a stop line.

Reference implementation is in [Stop Line Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_stop_line_module/).

[Demonstration Video](https://youtu.be/eej9jYt-GSE)
[![Demonstration Video](https://img.youtube.com/vi/eej9jYt-GSE/0.jpg)](https://www.youtube.com/watch?v=eej9jYt-GSE) | - Lanelet map (stop line) | ![stop-line](image/features-stop-line.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_occlusion_spot_module/).

[Demonstration Video](https://youtu.be/3qs8Ivjh1fs)
[![Demonstration Video](https://img.youtube.com/vi/3qs8Ivjh1fs/0.jpg)](https://www.youtube.com/watch?v=3qs8Ivjh1fs) | - objects information
- Lanelet map (private/public lane) | ![occlusion-spot](image/features-occlusion-spot.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_no_stopping_area_module/). | - Lanelet map (no stopping area) | ![no-stopping-area](image/features-no-stopping-area.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_intersection_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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_speed_bump_module/).

[Demonstration Video](https://youtu.be/FpX3q3YaaCw)
[![Demonstration Video](https://img.youtube.com/vi/FpX3q3YaaCw/0.jpg)](https://www.youtube.com/watch?v=FpX3q3YaaCw) | - Lanelet map (speed bump) | ![speed-bump](image/features-speed-bump.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_detection_area_module/).

[Demonstration Video](https://youtu.be/YzXF4U69lJs)
[![Demonstration Video](https://img.youtube.com/vi/YzXF4U69lJs/0.jpg)](https://www.youtube.com/watch?v=YzXF4U69lJs) | - Lanelet map (detection area) | ![detection-area](image/features-detection-area.drawio.svg) | +| No Drivable Lane | Plan velocity to stop before exiting the area designated by ODD (Operational Design Domain) or stop the vehicle if autonomous mode started in out of ODD lane.

Reference implementation is in [No Drivable Lane Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_no_drivable_lane_module/). | - Lanelet map (no drivable lane) | ![no-drivable-lane](image/features-no-drivable-lane.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_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](https://autowarefoundation.github.io/autoware.universe/main/planning/freespace_planner/).

[Demonstration Video](https://youtu.be/rAIYmwpNWfA)
[![Demonstration Video](https://img.youtube.com/vi/rAIYmwpNWfA/0.jpg)](https://www.youtube.com/watch?v=rAIYmwpNWfA) | - objects information
- Lanelet map (parking area) | ![parking](image/features-parking.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_out_of_lane_module/). | - Primitive objects | ![aeb](image/features-aeb.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/planning_validator/). | - None | ![trajectory-validation](image/features-trajectory-validation.drawio.svg) | +| 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](https://autowarefoundation.github.io/autoware.universe/main/planning/static_centerline_optimizer/). | - Lanelet map (driving lanes) | WIP | + + + +## Reference Implementation + +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._ ![reference-implementation](image/planning-diagram.drawio.svg) @@ -57,16 +158,17 @@ For more details, please refer to the design documents in each package. - [_pull_out_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/#pull-out) - _side_shift_ - [_behavior_velocity_planner_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/): calculates max speed based on the traffic rules. - - [_detection_area_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/detection-area-design/) - - [_blind_spot_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/blind-spot-design/) - - [_cross_walk_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/crosswalk-design/) - - [_stop_line_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/stop-line-design/) - - [_traffic_light_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/traffic-light-design/) - - [_intersection_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/intersection-design/) - - [_no_stopping_area_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/no-stopping-area-design/) - - [_virtual_traffic_light_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/virtual-traffic-light-design/) - - [_occlusion_spot_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/occlusion-spot-design/) - - [_run_out_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/run-out-design/) + - [_detection_area_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_detection_area_module/) + - [_blind_spot_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_blind_spot_module/) + - [_cross_walk_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_crosswalk_module/) + - [_stop_line_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_stop_line_module/) + - [_traffic_light_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_traffic_light_module/) + - [_intersection_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_intersection_module/) + - [_no_stopping_area_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_no_stopping_area_module/) + - [_virtual_traffic_light_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_virtual_traffic_light_module/) + - [_occlusion_spot_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_occlusion_spot_module/) + - [_run_out_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_run_out_module/) + - [_no_drivable_lane_](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_no_drivable_lane_module) - [_obstacle_avoidance_planner_](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_avoidance_planner/): calculate path shape under obstacle and drivable area constraints - [_surround_obstacle_checker_](https://autowarefoundation.github.io/autoware.universe/main/planning/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_](https://autowarefoundation.github.io/autoware.universe/main/planning/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). @@ -79,13 +181,21 @@ For more details, please refer to the design documents in each package. - [_external_velocity_limit_selector_](https://autowarefoundation.github.io/autoware.universe/main/planning/external_velocity_limit_selector/): takes an appropriate velocity limit from multiple candidates. - [_motion_velocity_smoother_](https://autowarefoundation.github.io/autoware.universe/main/planning/motion_velocity_smoother/): calculates final velocity considering velocity, acceleration, and jerk constraints. -## Supported Functions +### Important Parameters + +| 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. | -![supported-functions](image/planning-functions.drawio.svg) +### Notation -## Notation +#### [1] self-crossing road and overlapped -[1] To support the self-crossing road and overlapped road in the opposite direction, each planning module has to meet the [specifications](https://autowarefoundation.github.io/autoware.universe/main/common/motion_utils/) +To support the self-crossing road and overlapped road in the opposite direction, each planning module has to meet the [specifications](https://autowarefoundation.github.io/autoware.universe/main/common/motion_utils/) Currently, the supported modules are as follows. @@ -96,3 +206,7 @@ Currently, the supported modules are as follows. - obstacle_avoidance_planner - obstacle_stop_planner - motion_velocity_smoother + +#### [2] Size of Path Points + +Some functions do not support paths with only one point. Therefore, each modules should generate the path with more than two path points. diff --git a/docs/design/autoware-architecture/sensing/data-types/gnss-ins-data.md b/docs/design/autoware-architecture/sensing/data-types/gnss-ins-data.md new file mode 100644 index 00000000000..528a841cd88 --- /dev/null +++ b/docs/design/autoware-architecture/sensing/data-types/gnss-ins-data.md @@ -0,0 +1,5 @@ +# GNSS/INS data pre-processing design + +!!! warning + + Under Construction diff --git a/docs/tutorials/scenario-simulation/rosbag-replay-simulation.md b/docs/design/autoware-architecture/sensing/data-types/image.md similarity index 55% rename from docs/tutorials/scenario-simulation/rosbag-replay-simulation.md rename to docs/design/autoware-architecture/sensing/data-types/image.md index 9fdf4319c16..e654b4cea58 100644 --- a/docs/tutorials/scenario-simulation/rosbag-replay-simulation.md +++ b/docs/design/autoware-architecture/sensing/data-types/image.md @@ -1,4 +1,4 @@ -# Rosbag replay simulation +# Image pre-processing design !!! warning diff --git a/docs/design/autoware-architecture/sensing/data-types/point-cloud.md b/docs/design/autoware-architecture/sensing/data-types/point-cloud.md new file mode 100644 index 00000000000..7c44603b7de --- /dev/null +++ b/docs/design/autoware-architecture/sensing/data-types/point-cloud.md @@ -0,0 +1,216 @@ +# Point cloud pre-processing design + +## Overview + +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. + +## Recommended processing pipeline + +```mermaid +graph TD + Driver["Lidar Driver"] -->|"Cloud XYZIRCADT"| FilterPR["Polygon Remover Filter / CropBox Filter"] + + subgraph "sensing" + FilterPR -->|"Cloud XYZIRCADT"| FilterDC["Motion Distortion Corrector Filter"] + FilterDC -->|"Cloud XYZIRCAD"| FilterOF["Outlier Remover Filter"] + FilterOF -->|"Cloud XYZIRC"| FilterDS["Downsampler Filter"] + FilterDS -->|"Cloud XYZIRC"| FilterTrans["Cloud Transformer"] + FilterTrans -->|"Cloud XYZIRC"| FilterC + + FilterX["..."] -->|"Cloud XYZIRC (i)"| FilterC["Cloud Concatenator"] + end + + FilterC -->|"Cloud XYZIRC"| SegGr["Ground Segmentation"] +``` + +## List of modules + +The modules used here are from [pointcloud_preprocessor package](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/pointcloud_preprocessor). + +For details about the modules, see [the following table](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/pointcloud_preprocessor#inner-workings--algorithms). + +It is recommended that these modules are used in a single container as components. For details see [ROS 2 Composition](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Composition.html) + +## Point cloud fields + +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. + +### Intensity + +We will use following ranges for intensity, compatible with [the VLP16 User Manual](https://usermanual.wiki/Pdf/VLP16Manual.1719942037/view): + +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](https://commons.wikimedia.org/wiki/File:Retroreflective_Gradient_road_sign.jpg) + +But in a point cloud with retroreflectors, the intensity points will be between 0 and 255. + +#### Intensity mapping for other lidar brands + +##### Hesai PandarXT16 + +[Hesai Pandar XT16 User Manual](https://www.oxts.com/wp-content/uploads/2021/01/Hesai-PandarXT16_User_Manual.pdf) + +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. + +##### Livox Mid-70 + +[Livox Mid-70 User Manual](https://terra-1-g.djicdn.com/65c028cd298f4669a7f0e40e50ba1131/Download/Mid-70/new/Livox%20Mid-70%20User%20Manual_EN_v1.2.pdf) + +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. + +##### RoboSense RS-LiDAR-16 + +[RoboSense RS-LiDAR-16 User Manual](https://cdn.robosense.cn/20200723161715_42428.pdf) + +No mapping required, same as Velodyne VLP-16. + +##### Ouster OS-1-64 + +[Software User Manual v2.0.0 for all Ouster sensors](https://data.ouster.io/downloads/software-user-manual/software-user-manual-v2p0.pdf) + +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. + +##### Leishen CH64W + +[I couldn't get the english user manual, link of website](http://www.lslidar.com/en/down) + +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. + +### Return type + +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 | + +### Channel + +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`. + +#### Solid state and petal pattern lidars + +!!! 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. + +### Time + +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. + +#### Point cloud header time + +The header contains a [Time field](https://github.com/ros2/rcl_interfaces/blob/rolling/builtin_interfaces/msg/Time.msg). +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 + +#### Individual point time + +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. diff --git a/docs/design/autoware-architecture/sensing/data-types/radar-data.md b/docs/design/autoware-architecture/sensing/data-types/radar-data.md new file mode 100644 index 00000000000..25d7bb0ac54 --- /dev/null +++ b/docs/design/autoware-architecture/sensing/data-types/radar-data.md @@ -0,0 +1,5 @@ +# Radar data pre-processing design + +!!! warning + + Under Construction diff --git a/docs/design/autoware-architecture/sensing/data-types/ultrasonics-data.md b/docs/design/autoware-architecture/sensing/data-types/ultrasonics-data.md new file mode 100644 index 00000000000..25bb1b966b4 --- /dev/null +++ b/docs/design/autoware-architecture/sensing/data-types/ultrasonics-data.md @@ -0,0 +1,5 @@ +# Ultrasonics data pre-processing design + +!!! warning + + Under Construction diff --git a/docs/design/autoware-architecture/sensing/index.md b/docs/design/autoware-architecture/sensing/index.md index 5a883b14420..c6632ad04a9 100644 --- a/docs/design/autoware-architecture/sensing/index.md +++ b/docs/design/autoware-architecture/sensing/index.md @@ -1,5 +1,36 @@ # Sensing component design -!!! warning +## Overview - Under Construction +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. + +## Role + +- Abstraction of data formats to enable usage of sensors from various vendors +- Perform common/primitive sensor data processing required by each component + +## Inputs + +### Input types + +| Sensor Data | Message Type | +| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Point cloud (Lidars, depth cameras, etc.) | [sensor_msgs/msg/PointCloud2.msg](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/PointCloud2.msg) | +| Image (RGB, monochrome, depth, etc. cameras) | [sensor_msgs/msg/Image.msg](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Image.msg) | +| Radar scan | [radar_msgs/msg/RadarScan.msg](https://github.com/ros-perception/radar_msgs/blob/ros2/msg/RadarScan.msg) | +| Radar tracks | [radar_msgs/msg/RadarTracks.msg](https://github.com/ros-perception/radar_msgs/blob/ros2/msg/RadarTracks.msg) | +| GNSS-INS position | [sensor_msgs/msg/NavSatFix.msg](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/NavSatFix.msg) | +| GNSS-INS orientation | [autoware_sensing_msgs/GnssInsOrientationStamped.msg](https://github.com/autowarefoundation/autoware_msgs/blob/main/autoware_sensing_msgs/msg/GnssInsOrientationStamped.msg) | +| GNSS-INS velocity | [geometry_msgs/msg/TwistWithCovarianceStamped.msg](https://github.com/ros2/common_interfaces/blob/rolling/geometry_msgs/msg/TwistWithCovarianceStamped.msg) | +| GNSS-INS acceleration | [geometry_msgs/msg/AccelWithCovarianceStamped.msg](https://github.com/ros2/common_interfaces/blob/rolling/geometry_msgs/msg/AccelWithCovarianceStamped.msg) | +| Ultrasonics | [sensor_msgs/msg/Range.msg](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Range.msg) | + +## Design by data-types + +- [GNSS/INS data pre-processing design](data-types/gnss-ins-data.md) +- [Image pre-processing design](data-types/image.md) +- [Point cloud pre-processing design](data-types/point-cloud.md) +- [Radar data pre-processing design](data-types/radar-data.md) +- [Ultrasonics data pre-processing design](data-types/ultrasonics-data.md) diff --git a/docs/design/autoware-concepts/difference-from-ai-and-auto.md b/docs/design/autoware-concepts/difference-from-ai-and-auto.md index 330c859dc39..fa372e1536e 100644 --- a/docs/design/autoware-concepts/difference-from-ai-and-auto.md +++ b/docs/design/autoware-concepts/difference-from-ai-and-auto.md @@ -42,4 +42,4 @@ Autoware Core carries over the original policy of Autoware.Auto to be a stable a - 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](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-concepts/). +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](../autoware-concepts/). diff --git a/docs/design/autoware-interfaces/ad-api/.pages b/docs/design/autoware-interfaces/ad-api/.pages index bba6450af8c..5e2a85e21fc 100644 --- a/docs/design/autoware-interfaces/ad-api/.pages +++ b/docs/design/autoware-interfaces/ad-api/.pages @@ -1,4 +1,5 @@ nav: - index.md - - use-cases + - features - list + - types diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/index.md b/docs/design/autoware-interfaces/ad-api/features/fail-safe.md similarity index 91% rename from docs/design/autoware-interfaces/ad-api/list/api/fail_safe/index.md rename to docs/design/autoware-interfaces/ad-api/features/fail-safe.md index 58b14a9c060..355c402bac8 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/index.md +++ b/docs/design/autoware-interfaces/ad-api/features/fail-safe.md @@ -1,4 +1,6 @@ -# Fail-safe API +# Fail-safe + +## Related API - {{ link_ad_api('/api/fail_safe/mrm_state') }} @@ -11,14 +13,14 @@ For safety, Autoware switches the operation to MRM when an abnormality is detect 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. -![fail-safe-architecture](./architecture.drawio.svg) +![fail-safe-architecture](./fail-safe/architecture.drawio.svg) ## States 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. -![mrm-state](./mrm-state.drawio.svg) +![mrm-state](./fail-safe/mrm-state.drawio.svg) | State | Description | | --------- | ---------------------------------------------------------- | @@ -32,7 +34,7 @@ Generally, MRM will switch to another behavior if it fails. 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. -![mrm-behavior](./mrm-behavior.drawio.svg) +![mrm-behavior](./fail-safe/mrm-behavior.drawio.svg) | State | Description | | ---------------- | ------------------------------------------------------------------------- | diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/architecture.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/fail-safe/architecture.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/fail_safe/architecture.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/fail-safe/architecture.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm-behavior.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/fail-safe/mrm-behavior.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm-behavior.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/fail-safe/mrm-behavior.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm-state.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/fail-safe/mrm-state.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm-state.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/fail-safe/mrm-state.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/interface/index.md b/docs/design/autoware-interfaces/ad-api/features/interface.md similarity index 91% rename from docs/design/autoware-interfaces/ad-api/list/api/interface/index.md rename to docs/design/autoware-interfaces/ad-api/features/interface.md index 186fa2bf3f2..c472bdd3737 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/interface/index.md +++ b/docs/design/autoware-interfaces/ad-api/features/interface.md @@ -1,4 +1,6 @@ -# Interface API +# Interface + +## Related API - {{ link_ad_api('/api/interface/version') }} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/localization/index.md b/docs/design/autoware-interfaces/ad-api/features/localization.md similarity index 88% rename from docs/design/autoware-interfaces/ad-api/list/api/localization/index.md rename to docs/design/autoware-interfaces/ad-api/features/localization.md index fc61883a989..dab03f6c843 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/localization/index.md +++ b/docs/design/autoware-interfaces/ad-api/features/localization.md @@ -1,4 +1,6 @@ -# Pose API +# Localization + +## Related API - {{ link_ad_api('/api/localization/initialization_state') }} - {{ link_ad_api('/api/localization/initialize') }} @@ -9,7 +11,7 @@ This API manages the initialization of localization. Autoware requires a global ## States -![localization-initialization_state-state](./state.drawio.svg) +![localization-initialization-state](./localization/state.drawio.svg) | State | Description | | ------------- | -------------------------------------------------------------------------------- | diff --git a/docs/design/autoware-interfaces/ad-api/list/api/localization/state.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/localization/state.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/localization/state.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/localization/state.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/motion/index.md b/docs/design/autoware-interfaces/ad-api/features/motion.md similarity index 94% rename from docs/design/autoware-interfaces/ad-api/list/api/motion/index.md rename to docs/design/autoware-interfaces/ad-api/features/motion.md index 42dcd2800f4..5edf6631df5 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/motion/index.md +++ b/docs/design/autoware-interfaces/ad-api/features/motion.md @@ -1,4 +1,6 @@ -# Planning API +# Motion + +## Related API - {{ link_ad_api('/api/motion/state') }} - {{ link_ad_api('/api/motion/accept_start') }} @@ -17,7 +19,7 @@ In this state, calling the start API changes the state to MOVING and the vehicle 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. -![motion-state](./docs/state.drawio.svg) +![motion-state](./motion/state.drawio.svg) | State | Description | | ---------------- | ----------------------------------------------- | diff --git a/docs/design/autoware-interfaces/ad-api/list/api/motion/docs/state.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/motion/state.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/motion/docs/state.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/motion/state.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/index.md b/docs/design/autoware-interfaces/ad-api/features/operation_mode.md similarity index 95% rename from docs/design/autoware-interfaces/ad-api/list/api/operation_mode/index.md rename to docs/design/autoware-interfaces/ad-api/features/operation_mode.md index 994279af73e..d8337692be8 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/index.md +++ b/docs/design/autoware-interfaces/ad-api/features/operation_mode.md @@ -1,4 +1,6 @@ -# Operation Mode +# Operation mode + +## Related API - {{ link_ad_api('/api/operation_mode/state') }} - {{ link_ad_api('/api/operation_mode/change_to_autonomous') }} @@ -22,7 +24,7 @@ Autoware control mode has four operation modes. | 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. | -![operation-mode-architecture](./architecture.drawio.svg) +![operation-mode-architecture](./operation_mode/architecture.drawio.svg) ## States diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/architecture.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/operation_mode/architecture.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/operation_mode/architecture.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/operation_mode/architecture.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/features/perception.md b/docs/design/autoware-interfaces/ad-api/features/perception.md new file mode 100644 index 00000000000..6cc4a6c3b2b --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/features/perception.md @@ -0,0 +1,9 @@ +# Perception + +## Related API + +- {{ link_ad_api('/api/perception/objects') }} + +## Description + +API for perception related topic. diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/index.md b/docs/design/autoware-interfaces/ad-api/features/planning-factors.md similarity index 88% rename from docs/design/autoware-interfaces/ad-api/list/api/planning/index.md rename to docs/design/autoware-interfaces/ad-api/features/planning-factors.md index ebef833a690..eff614ae230 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/planning/index.md +++ b/docs/design/autoware-interfaces/ad-api/features/planning-factors.md @@ -1,4 +1,6 @@ -# Planning API +# Planning factors + +## Related API - {{ link_ad_api('/api/planning/velocity_factors') }} - {{ link_ad_api('/api/planning/steering_factors') }} @@ -11,12 +13,12 @@ Applications can notify the vehicle behavior to the people around and visualize ## Velocity factors 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, distance from the vehicle head to that pose, status, and detailed data depending on its type. +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 vehicle head if the stop position cannot be calculated. +The pose indicates the stop position or the base link if the stop position cannot be calculated. -![velocity-factors](./docs/velocity-factors.drawio.svg) +![velocity-factors](./planning-factors/velocity-factors.drawio.svg) | Factor Type | Description | | --------------------------- | ------------------------------------------------------------------------ | @@ -40,12 +42,12 @@ The pose indicates the stop position or the vehicle head if the stop position ca ## Steering factors 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, distance from the vehicle head to that pose, status, and detailed data depending on its type. +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. -![steering-factors-1](./docs/steering-factors-1.drawio.svg) +![steering-factors-1](./planning-factors/steering-factors-1.drawio.svg) 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. @@ -54,7 +56,7 @@ Then, when it is possible, the vehicle will start steering and the status will b 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. -![steering-factors-2](./docs/steering-factors-2.drawio.svg) +![steering-factors-2](./planning-factors/steering-factors-2.drawio.svg) | Factor Type | Description | | --------------------- | ------------------------------------------------------------------------ | diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/docs/steering-factors-1.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-1.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/planning/docs/steering-factors-1.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-1.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/docs/steering-factors-2.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-2.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/planning/docs/steering-factors-2.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/planning-factors/steering-factors-2.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/docs/velocity-factors.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/planning-factors/velocity-factors.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/planning/docs/velocity-factors.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/planning-factors/velocity-factors.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/list/api/routing/index.md b/docs/design/autoware-interfaces/ad-api/features/routing.md similarity index 58% rename from docs/design/autoware-interfaces/ad-api/list/api/routing/index.md rename to docs/design/autoware-interfaces/ad-api/features/routing.md index 5e7c39a0ba0..bc13a4dabd6 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/routing/index.md +++ b/docs/design/autoware-interfaces/ad-api/features/routing.md @@ -1,4 +1,6 @@ -# Route API +# Routing + +## Related API - {{ link_ad_api('/api/routing/state') }} - {{ link_ad_api('/api/routing/route') }} @@ -14,11 +16,19 @@ There are two ways to set the route. The one is a generic method that uses pose, ## States -![route-state](./state.drawio.svg) +![route-state](./routing/state.drawio.svg) | State | Description | | -------- | -------------------------------------------------- | -| WAITING | The route is not set. Waiting for a route request. | +| 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. | + +## Goal modification + +Autoware tries to look for an alternate goal when goal is unreachable (e.g., when there is an obstacle on the given goal). When setting a route from the API, applications can choose whether they allow Autoware to adjust goal pose in such situation. When set false, Autoware may get stuck until the given goal becomes reachable. + +| Option | Description | +| ----------------------- | --------------------------------- | +| allow_goal_modification | If true, allow goal modification. | diff --git a/docs/design/autoware-interfaces/ad-api/list/api/routing/state.drawio.svg b/docs/design/autoware-interfaces/ad-api/features/routing/state.drawio.svg similarity index 100% rename from docs/design/autoware-interfaces/ad-api/list/api/routing/state.drawio.svg rename to docs/design/autoware-interfaces/ad-api/features/routing/state.drawio.svg diff --git a/docs/design/autoware-interfaces/ad-api/features/vehicle-doors.md b/docs/design/autoware-interfaces/ad-api/features/vehicle-doors.md new file mode 100644 index 00000000000..9079a3c0eb7 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/features/vehicle-doors.md @@ -0,0 +1,38 @@ +# Vehicle doors + +## Related API + +- {{ link_ad_api('/api/vehicle/doors/layout') }} +- {{ link_ad_api('/api/vehicle/doors/status') }} +- {{ link_ad_api('/api/vehicle/doors/command') }} + +## Description + +This feature is available if the vehicle provides a software interface for the doors. +It can be used to create user interfaces for passengers or to control sequences at bus stops. + +## Layout + +Each door in a vehicle is assigned an array index. This assignment is vehicle dependent. +The layout API returns this information. +The description field is a string to display in the user interface, etc. +This is an arbitrary string and is not recommended to use for processing in applications. +Use the roles field to know doors for getting on and off. +Below is an example of the information returned by the layout API. + +| Index | Description | Roles | +| ----- | ----------- | --------------- | +| 0 | front right | - | +| 1 | front left | GET_ON | +| 2 | rear right | GET_OFF | +| 3 | rear left | GET_ON, GET_OFF | + +## Status + +The status API provides an array of door status. This array order is consistent with the layout API. + +## Control + +Use the command API to control doors. +Unlike the status and layout APIs, array index do not correspond to doors. +The command has a field to specify the target door index. diff --git a/docs/design/autoware-interfaces/ad-api/features/vehicle-status.md b/docs/design/autoware-interfaces/ad-api/features/vehicle-status.md new file mode 100644 index 00000000000..306429a1de4 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/features/vehicle-status.md @@ -0,0 +1,21 @@ +# Vehicle status + +## Related API + +- {{ link_ad_api('/api/vehicle/kinematics') }} +- {{ link_ad_api('/api/vehicle/status') }} +- {{ link_ad_api('/api/vehicle/dimensions') }} + +## Kinematics + +This is an estimate of the vehicle kinematics. The vehicle position is necessary for applications to schedule dispatches. +Also, using velocity and acceleration, applications can find vehicles that need operator assistance, such as stuck or brake suddenly. + +## Status + +This is the status provided by the vehicle. The indicators and steering are mainly used for visualization and remote control. +The remaining energy can be also used for vehicle scheduling. + +## Dimensions + +The vehicle dimensions are used to know the actual distance between the vehicle and objects because the vehicle position in kinematics is the coordinates of the base link. This is necessary for visualization when supporting vehicles remotely. diff --git a/docs/design/autoware-interfaces/ad-api/index.md b/docs/design/autoware-interfaces/ad-api/index.md index 91e28c21d10..d530255f586 100644 --- a/docs/design/autoware-interfaces/ad-api/index.md +++ b/docs/design/autoware-interfaces/ad-api/index.md @@ -1,5 +1,41 @@ -# AD API +# Autoware AD API -!!! warning +## Overview - Under Construction +Autoware AD API is the interface for operating the vehicle from outside the autonomous driving system. +[See here for the overall interface design of Autoware.](../index.md) + +## User stories + +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](./stories/bus-service.md) +- [Taxi service](./stories/taxi-service.md) + +## Use cases + +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](./use-cases/launch-terminate.md) +- [Initialize the pose](./use-cases/initialize-pose.md) +- [Change the operation mode](./use-cases/change-operation-mode.md) +- [Drive to the designated position](./use-cases/drive-designated-position.md) +- [Get on and get off](./use-cases/get-on-off.md) +- [Vehicle monitoring](./use-cases/vehicle-monitoring.md) +- [Request to cooperate](./use-cases/request-to-cooperate.md) + +## Features + +- [Interface](./features/interface.md) +- [Operation Mode](./features/operation_mode.md) +- [Routing](./features/routing.md) +- [Localization](./features/localization.md) +- [Motion](./features/motion.md) +- [Planning](./features/planning-factors.md) +- [Perception](./features/perception.md) +- [Fail-safe](./features/fail-safe.md) +- [Vehicle status](./features/vehicle-status.md) +- [Vehicle doors](./features/vehicle-doors.md) diff --git a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state.md b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state.md index 25931cd4626..55fde2bc529 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state.md @@ -1,15 +1,18 @@ -# /api/fail_safe/mrm_state +--- +title: /api/fail_safe/mrm_state +status: not released +method: notification +type: + name: autoware_adapi_v1_msgs/msg/MrmState + msg: + - name: state + text: The state of MRM operation. + - name: behavior + text: The currently selected behavior of MRM. +--- -- Method: notification -- Type: [autoware_ad_api_msgs/msg/MrmState](../../../types/autoware_ad_api_msgs/msg/mrm_state.md) - -## Description - -Get the MRM state. For details, see the [fail-safe](./index.md). - -## Message - -| Name | Type | Description | -| -------- | ------ | --------------------------------------- | -| state | uint16 | The state of MRM operation. | -| behavior | uint16 | The currently selected behavior of MRM. | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the MRM state. +For details, see the [fail-safe](../../../features/fail-safe.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/interface/version.md b/docs/design/autoware-interfaces/ad-api/list/api/interface/version.md index 322b129cca6..f61f18ef487 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/interface/version.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/interface/version.md @@ -1,20 +1,19 @@ -# /api/interface/version - -- Method: function call -- Type: [autoware_ad_api_msgs/srv/InterfaceVersion](../../../types/autoware_ad_api_msgs/srv/interface_version.md) - -## Description +--- +title: /api/interface/version +status: v1.0.0 +method: function call +type: + name: autoware_adapi_version_msgs/srv/InterfaceVersion + res: + - name: major + text: major version + - name: minor + text: minor version + - name: patch + text: patch version +--- +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} Get the interface version. The version follows Semantic Versioning. - -## Request - -None - -## Response - -| Name | Type | Description | -| ----- | ------ | ------------- | -| major | uint16 | major version | -| minor | uint16 | minor version | -| patch | uint16 | patch version | +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/localization/initialization_state.md b/docs/design/autoware-interfaces/ad-api/list/api/localization/initialization_state.md index 19290ea596a..1cfebed297e 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/localization/initialization_state.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/localization/initialization_state.md @@ -1,14 +1,16 @@ -# /api/localization/initialization_state +--- +title: /api/localization/initialization_state +status: v1.0.0 +method: notification +type: + name: autoware_adapi_v1_msgs/msg/LocalizationInitializationState + msg: + - name: state + text: A value of the localization initialization state. +--- -- Method: notification -- Type: [autoware_ad_api_msgs/msg/LocalizationInitializationState](../../../types/autoware_ad_api_msgs/msg/localization_initialization_state.md) - -## Description - -Get the initialization state of localization. For details, see the [localization initialization state](./index.md). - -## Message - -| Name | Type | Description | -| ----- | ------ | --------------------------------------------------------------- | -| state | uint16 | A value of the [localization initialization state](./index.md). | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the initialization state of localization. +For details, see the [localization](../../../features/localization.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/localization/initialize.md b/docs/design/autoware-interfaces/ad-api/list/api/localization/initialize.md index 84f0b87ba15..167dd033a56 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/localization/initialize.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/localization/initialize.md @@ -1,20 +1,19 @@ -# /api/localization/initialize +--- +title: /api/localization/initialize +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/InitializeLocalization + req: + - name: pose + text: A global pose as the initial guess. If omitted, the GNSS pose will be used. + res: + - name: status + text: response status +--- -- Method: function call -- Type: [autoware_ad_api_msgs/srv/InitializeLocalization](../../../types/autoware_ad_api_msgs/srv/initialize_localization.md) - -## Description - -Request to initialize localization. For details, see the [pose state](./index.md). - -## Request - -| Name | Type | Description | -| ---- | ------------------------------------------------ | --------------------------------------------------------------------------- | -| pose | geometry_msgs/msg/PoseWithCovarianceStamped[<=1] | A global pose as the initial guess. If omitted, the GNSS pose will be used. | - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Request to initialize localization. +For details, see the [localization](../../../features/localization.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/motion/accept_start.md b/docs/design/autoware-interfaces/ad-api/list/api/motion/accept_start.md index 71997a05e20..896cb9f6bbb 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/motion/accept_start.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/motion/accept_start.md @@ -1,18 +1,15 @@ -# /api/motion/accept_start - -- Method: function call -- Type: [autoware_ad_api_msgs/srv/AcceptStart](../../../types/autoware_ad_api_msgs/srv/accept_start.md) - -## Description - -Accept the vehicle to start. This API can be used when the [motion state](./index.md) is STARTING. - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +--- +title: /api/motion/accept_start +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/AcceptStart + res: + - name: status + text: response status +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Accept the vehicle to start. This API can be used when the [motion state](../../../features/motion.md) is STARTING. +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/motion/state.md b/docs/design/autoware-interfaces/ad-api/list/api/motion/state.md index 7520aed9e58..80e4f6715d6 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/motion/state.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/motion/state.md @@ -1,14 +1,16 @@ -# /api/motion/state +--- +title: /api/motion/state +status: not released +method: notification +type: + name: autoware_adapi_v1_msgs/msg/MotionState + msg: + - name: state + text: A value of the motion state. +--- -- Method: notification -- Type: [autoware_ad_api_msgs/msg/MotionState](../../../types/autoware_ad_api_msgs/msg/motion_state.md) - -## Description - -Get the motion state. For details, see the [motion state](./index.md). - -## Message - -| Name | Type | Description | -| ----- | ------ | ---------------------------- | -| state | uint16 | A value of the motion state. | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the motion state. +For details, see the [motion state](../../../features/motion.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous.md b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous.md index 43870ddaeed..12921080c04 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous.md @@ -1,18 +1,16 @@ -# /api/operation_mode/change_to_autonomous +--- +title: /api/operation_mode/change_to_autonomous +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ChangeOperationMode + res: + - name: status + text: response status +--- -- Method: function call -- Type: [autoware_ad_api_msgs/srv/ChangeOperationMode](../../../types/autoware_ad_api_msgs/srv/change_operation_mode.md) - -## Description - -Change the operation mode to autonomous. For details, see the [operation mode](./index.md). - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Change the operation mode to autonomous. +For details, see the [operation mode](../../../features/operation_mode.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local.md b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local.md index 5a53ad51c86..f908f58b939 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local.md @@ -1,18 +1,16 @@ -# /api/operation_mode/change_to_local +--- +title: /api/operation_mode/change_to_local +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ChangeOperationMode + res: + - name: status + text: response status +--- -- Method: function call -- Type: [autoware_ad_api_msgs/srv/ChangeOperationMode](../../../types/autoware_ad_api_msgs/srv/change_operation_mode.md) - -## Description - -Change the operation mode to local. For details, see the [operation mode](./index.md). - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Change the operation mode to local. +For details, see the [operation mode](../../../features/operation_mode.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote.md b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote.md index 66bb18b2f1d..e3dd05974f5 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote.md @@ -1,18 +1,16 @@ -# /api/operation_mode/change_to_remote +--- +title: /api/operation_mode/change_to_remote +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ChangeOperationMode + res: + - name: status + text: response status +--- -- Method: function call -- Type: [autoware_ad_api_msgs/srv/ChangeOperationMode](../../../types/autoware_ad_api_msgs/srv/change_operation_mode.md) - -## Description - -Change the operation mode to remote. For details, see the [operation mode](./index.md). - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Change the operation mode to remote. +For details, see the [operation mode](../../../features/operation_mode.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop.md b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop.md index b0eda5e4d76..919f571b010 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop.md @@ -1,18 +1,16 @@ -# /api/operation_mode/change_to_stop +--- +title: /api/operation_mode/change_to_stop +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ChangeOperationMode + res: + - name: status + text: response status +--- -- Method: function call -- Type: [autoware_ad_api_msgs/srv/ChangeOperationMode](../../../types/autoware_ad_api_msgs/srv/change_operation_mode.md) - -## Description - -Change the operation mode to stop. For details, see the [operation mode](./index.md). - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Change the operation mode to stop. +For details, see the [operation mode](../../../features/operation_mode.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control.md b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control.md index e639106e542..bcf12b52602 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control.md @@ -1,19 +1,17 @@ -# /api/operation_mode/disable_autoware_control +--- +title: /api/operation_mode/disable_autoware_control +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ChangeOperationMode + res: + - name: status + text: response status +--- -- Method: function call -- Type: [autoware_ad_api_msgs/srv/ChangeOperationMode](../../../types/autoware_ad_api_msgs/srv/change_operation_mode.md) - -## Description - -Disable vehicle control by Autoware. For details, see the [operation mode](./index.md). +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Disable vehicle control by Autoware. +For details, see the [operation mode](../../../features/operation_mode.md). This API fails if the vehicle does not support mode change by software. - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control.md b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control.md index cc5d0d835af..2c83455d30a 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control.md @@ -1,19 +1,17 @@ -# /api/operation_mode/enable_autoware_control +--- +title: /api/operation_mode/enable_autoware_control +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ChangeOperationMode + res: + - name: status + text: response status +--- -- Method: function call -- Type: [autoware_ad_api_msgs/srv/ChangeOperationMode](../../../types/autoware_ad_api_msgs/srv/change_operation_mode.md) - -## Description - -Enable vehicle control by Autoware. For details, see the [operation mode](./index.md). +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Enable vehicle control by Autoware. +For details, see the [operation mode](../../../features/operation_mode.md). This API fails if the vehicle does not support mode change by software. - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/state.md b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/state.md index 38c4d4184da..d1e39bb4522 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/state.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/operation_mode/state.md @@ -1,20 +1,28 @@ -# /api/operation_mode/state +--- +title: /api/operation_mode/state +status: v1.0.0 +method: notification +type: + name: autoware_adapi_v1_msgs/msg/OperationModeState + msg: + - name: mode + text: The selected command for Autoware control. + - name: is_autoware_control_enabled + text: True if vehicle control by Autoware is enabled. + - name: is_in_transition + text: True if the operation mode is in transition. + - name: is_stop_mode_available + text: True if the operation mode can be changed to stop. + - name: is_autonomous_mode_available + text: True if the operation mode can be changed to autonomous. + - name: is_local_mode_available + text: True if the operation mode can be changed to local. + - name: is_remote_mode_available + text: True if the operation mode can be changed to remote. +--- -- Method: notification -- Type: [autoware_ad_api_msgs/msg/OperationModeState](../../../types/autoware_ad_api_msgs/msg/operation_mode_state.md) - -## Description - -Get the operation mode state. For details, see the [operation mode](./index.md). - -## Message - -| Name | Type | Description | -| --------------------------- | ------ | -------------------------------------------------------- | -| operation_mode | uint16 | 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. | -| change_to_stop | bool | True if the operation mode can be changed to stop. | -| change_to_autonomous | bool | True if the operation mode can be changed to autonomous. | -| change_to_local | bool | True if the operation mode can be changed to local. | -| change_to_remote | bool | True if the operation mode can be changed to remote. | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the operation mode state. +For details, see the [operation mode](../../../features/operation_mode.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/perception/objects.md b/docs/design/autoware-interfaces/ad-api/list/api/perception/objects.md new file mode 100644 index 00000000000..ee0e27d414a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/perception/objects.md @@ -0,0 +1,24 @@ +--- +title: /api/perception/objects +status: v1.0.0 +method: realtime stream +type: + name: autoware_adapi_v1_msgs/msg/DynamicObjectArray + msg: + - name: objects.id + text: The UUID of each object + - name: objects.existence_probability + text: The probability of the object exits + - name: objects.classification + text: The type of the object recognized and the confidence level + - name: objects.kinematics + text: Consist of the object pose, twist, acceleration and the predicted_paths + - name: objects.shape + text: escribe the shape of the object with dimension, and polygon +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the recognized objects array with label, shape, current position and predicted path +For details, see the [perception](../../../features/perception.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md b/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md index 946b2ef57f8..55afd3720b0 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/planning/steering_factors.md @@ -1,20 +1,26 @@ -# /api/planning/steering_factors - -- Method: realtime stream -- Type: [autoware_ad_api_msgs/msg/SteeringFactorArray](../../../types/autoware_ad_api_msgs/msg/steering_factor_array.md) - -## Description +--- +title: /api/planning/steering_factors +status: not released +method: realtime stream +type: + name: autoware_adapi_v1_msgs/msg/SteeringFactorArray + msg: + - name: factors.pose + text: The base link pose related to the steering factor. + - name: factors.distance + text: The distance from the base link to the above pose. + - name: factors.type + text: The type of the steering factor. + - name: factors.direction + text: The direction of the steering factor. + - name: factors.status + text: The status of the steering factor. + - name: factors.detail + text: The additional information of the steering factor. +--- +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} Get the steering factors, sorted in ascending order of distance. -For details, see the [planning](./index.md). - -## Message - -| Name | Type | Description | -| ----------------- | ---------------------- | ----------------------------------------------------- | -| factors.pose | geometry_msgs/msg/Pose | The pose related to the steering factor. | -| factors.distance | float32 | The distance from the vehicle head 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. | +For details, see the [planning factors](../../../features/planning-factors.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md b/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md index ac375acb216..8758e6016e5 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/planning/velocity_factors.md @@ -1,19 +1,24 @@ -# /api/planning/velocity_factors - -- Method: realtime stream -- Type: [autoware_ad_api_msgs/msg/VelocityFactorArray](../../../types/autoware_ad_api_msgs/msg/velocity_factor_array.md) - -## Description +--- +title: /api/planning/velocity_factors +status: not released +method: realtime stream +type: + name: autoware_adapi_v1_msgs/msg/VelocityFactorArray + msg: + - name: factors.pose + text: The base link pose related to the velocity factor. + - name: factors.distance + text: The distance from the base link to the above pose. + - name: factors.type + text: The type of the velocity factor. + - name: factors.status + text: The status of the velocity factor. + - name: factors.detail + text: The additional information of the velocity factor. +--- +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} Get the velocity factors, sorted in ascending order of distance. -For details, see the [planning](./index.md). - -## Message - -| Name | Type | Description | -| ---------------- | ---------------------- | ----------------------------------------------------- | -| factors.pose | geometry_msgs/msg/Pose | The pose related to the velocity factor. | -| factors.distance | float32 | The distance from the vehicle head 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. | +For details, see the [planning factors](../../../features/planning-factors.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/routing/clear_route.md b/docs/design/autoware-interfaces/ad-api/list/api/routing/clear_route.md index 61ba5690c44..7648b5b5a09 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/routing/clear_route.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/routing/clear_route.md @@ -1,18 +1,15 @@ -# /api/routing/clear_route - -- Method: function call -- Type: [autoware_ad_api_msgs/srv/ClearRoute](../../../types/autoware_ad_api_msgs/srv/clear_route.md) - -## Description - +--- +title: /api/routing/clear_route +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/ClearRoute + res: + - name: status + text: response status +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} Clear the route. - -## Request - -None - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/routing/route.md b/docs/design/autoware-interfaces/ad-api/list/api/routing/route.md index 7a7c771c7ef..840ca4ae9ef 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/routing/route.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/routing/route.md @@ -1,14 +1,17 @@ -# /api/routing/route - -- Method: notification -- Type: [autoware_ad_api_msgs/msg/RouteOptional](../../../types/autoware_ad_api_msgs/msg/route_optional.md) - -## Description +--- +title: /api/routing/route +status: v1.0.0 +method: notification +type: + name: autoware_adapi_v1_msgs/msg/Route + msg: + - name: header + text: header for pose transformation + - name: data + text: The route in lanelet format +--- +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} Get the route with the waypoint segments in lanelet format. It is empty if route is not set. - -## Message - -| Name | Type | Description | -| ----- | ----------------------------------- | --------------------------- | -| route | autoware_ad_api_msgs/msg/Route[<=1] | The route in lanelet format | +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route.md b/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route.md index 85181ee7834..d80b8ac5138 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route.md @@ -1,23 +1,22 @@ -# /api/routing/set_route - -- Method: function call -- Type: [autoware_ad_api_msgs/srv/SetRoute](../../../types/autoware_ad_api_msgs/srv/set_route.md) - -## Description +--- +title: /api/routing/set_route +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/SetRoute + req: + - name: header + text: header for pose transformation + - name: goal + text: goal pose + - name: segments + text: waypoint segments in lanelet format + res: + - name: status + text: response status +--- +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} Set the route with the waypoint segments in lanelet format. If start pose is not specified, the current pose will be used. - -## Request - -| Name | Type | Description | -| -------- | --------------------------------------- | ----------------------------------- | -| header | std_msgs/msg/Header | header for pose transformation | -| start | geometry_msgs/msg/Pose[<=1] | start pose | -| goal | geometry_msgs/msg/Pose | goal pose | -| segments | autoware_ad_api_msgs/msg/RouteSegment[] | waypoint segments in lanelet format | - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route_points.md b/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route_points.md index 6200c910fff..0b80cf71ecd 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route_points.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/routing/set_route_points.md @@ -1,23 +1,22 @@ -# /api/routing/set_route_points - -- Method: function call -- Type: [autoware_ad_api_msgs/srv/SetRoutePoints](../../../types/autoware_ad_api_msgs/srv/set_route_points.md) - -## Description +--- +title: /api/routing/set_route_points +status: v1.0.0 +method: function call +type: + name: autoware_adapi_v1_msgs/srv/SetRoutePoints + req: + - name: header + text: header for pose transformation + - name: goal + text: goal pose + - name: waypoints + text: waypoint poses + res: + - name: status + text: response status +--- +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} Set the route with the waypoint poses. If start pose is not specified, the current pose will be used. - -## Request - -| Name | Type | Description | -| --------- | --------------------------- | ------------------------------ | -| header | std_msgs/msg/Header | header for pose transformation | -| start | geometry_msgs/msg/Pose[<=1] | start pose | -| goal | geometry_msgs/msg/Pose | goal pose | -| waypoints | geometry_msgs/msg/Pose[] | waypoint poses | - -## Response - -| Name | Type | Description | -| ------ | --------------------------------------- | --------------- | -| status | autoware_ad_api_msgs/msg/ResponseStatus | response status | +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/routing/state.md b/docs/design/autoware-interfaces/ad-api/list/api/routing/state.md index 97d06910edf..c73952ce2ea 100644 --- a/docs/design/autoware-interfaces/ad-api/list/api/routing/state.md +++ b/docs/design/autoware-interfaces/ad-api/list/api/routing/state.md @@ -1,14 +1,16 @@ -# /api/routing/state +--- +title: /api/routing/state +status: v1.0.0 +method: notification +type: + name: autoware_adapi_v1_msgs/msg/RouteState + msg: + - name: state + text: A value of the route state. +--- -- Method: notification -- Type: [autoware_ad_api_msgs/msg/RouteState](../../../types/autoware_ad_api_msgs/msg/route_state.md) - -## Description - -Get the route state. For details, see the [route state](./index.md). - -## Message - -| Name | Type | Description | -| ----- | ------ | ----------------------------------------- | -| state | uint16 | A value of the [route state](./index.md). | +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the route state. +For details, see the [routing](../../../features/routing.md). +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/dimensions.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/dimensions.md new file mode 100644 index 00000000000..e4f1d37c52b --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/dimensions.md @@ -0,0 +1,17 @@ +--- +title: /api/vehicle/dimensions +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/GetVehicleDimensions + res: + - name: status + text: response status + - name: dimensions + text: vehicle dimensions +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the vehicle dimensions. See [here](../../../../components/vehicle-dimensions.md) for the definition of each value. +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/command.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/command.md new file mode 100644 index 00000000000..c623615032a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/command.md @@ -0,0 +1,20 @@ +--- +title: /api/vehicle/doors/command +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/SetDoorCommand + req: + - name: doors.index + text: The index of the target door. + - name: doors.command + text: The command for the target door. + res: + - name: status + text: response status +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Set the door command. This API is only available if the vehicle supports software door control. +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/layout.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/layout.md new file mode 100644 index 00000000000..df2ccb5b6f9 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/layout.md @@ -0,0 +1,19 @@ +--- +title: /api/vehicle/doors/layout +status: not released +method: function call +type: + name: autoware_adapi_v1_msgs/srv/GetDoorLayout + res: + - name: status + text: response status + - name: doors.roles + text: The roles of the door in the service the vehicle provides. + - name: doors.description + text: The description of the door for display in the interface. +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Get the door layout. It is an array of roles and descriptions for each door. +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/status.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/status.md new file mode 100644 index 00000000000..cd64a3da0f1 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/doors/status.md @@ -0,0 +1,15 @@ +--- +title: /api/vehicle/doors/status +status: not released +method: notification +type: + name: autoware_adapi_v1_msgs/msg/DoorStatusArray + msg: + - name: doors.status + text: current door status +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +The status of each door such as opened or closed. +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/kinematics.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/kinematics.md new file mode 100644 index 00000000000..62513339560 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/kinematics.md @@ -0,0 +1,21 @@ +--- +title: /api/vehicle/kinematics +status: not released +method: realtime stream +type: + name: autoware_adapi_v1_msgs/msg/VehicleKinematics + msg: + - name: geographic_pose + text: The longitude and latitude of the vehicle. If the map uses local coordinates, it will not be available. + - name: pose + text: The pose with covariance from the base link. + - name: twist + text: Vehicle current twist with covariance. + - name: accel + text: Vehicle current acceleration with covariance. +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Publish vehicle kinematics. +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/api/vehicle/status.md b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/status.md new file mode 100644 index 00000000000..0f3e22f7bb4 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/list/api/vehicle/status.md @@ -0,0 +1,23 @@ +--- +title: /api/vehicle/status +status: not released +method: notification +type: + name: autoware_adapi_v1_msgs/msg/VehicleStatus + msg: + - name: gear + text: Gear status. + - name: turn_indicators + text: Turn indicators status, only either left or right will be enabled. + - name: hazard_lights + text: Hazard lights status. + - name: steering_tire_angle + text: Vehicle current tire angle in radian. + - name: energy_percentage + text: Battery percentage or fuel percentage, it will depends on the vehicle. +--- + +{% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %} +{% block description %} +Publish vehicle state information. +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/list/index.md b/docs/design/autoware-interfaces/ad-api/list/index.md index 65ee7e0efd7..9005e34f5ad 100644 --- a/docs/design/autoware-interfaces/ad-api/list/index.md +++ b/docs/design/autoware-interfaces/ad-api/list/index.md @@ -1,9 +1,29 @@ # List of Autoware AD API -- [Interface](./api/interface/index.md) -- [Operation Mode](./api/operation_mode/index.md) -- [Routing](./api/routing/index.md) -- [Localization](./api/localization/index.md) -- [Motion](./api/motion/index.md) -- [Planning](./api/planning/index.md) -- [Fail-safe](./api/fail_safe/index.md) +- [/api/fail_safe/mrm_state](./api/fail_safe/mrm_state.md) +- [/api/interface/version](./api/interface/version.md) +- [/api/localization/initialization_state](./api/localization/initialization_state.md) +- [/api/localization/initialize](./api/localization/initialize.md) +- [/api/motion/accept_start](./api/motion/accept_start.md) +- [/api/motion/state](./api/motion/state.md) +- [/api/operation_mode/change_to_autonomous](./api/operation_mode/change_to_autonomous.md) +- [/api/operation_mode/change_to_local](./api/operation_mode/change_to_local.md) +- [/api/operation_mode/change_to_remote](./api/operation_mode/change_to_remote.md) +- [/api/operation_mode/change_to_stop](./api/operation_mode/change_to_stop.md) +- [/api/operation_mode/disable_autoware_control](./api/operation_mode/disable_autoware_control.md) +- [/api/operation_mode/enable_autoware_control](./api/operation_mode/enable_autoware_control.md) +- [/api/operation_mode/state](./api/operation_mode/state.md) +- [/api/perception/objects](./api/perception/objects.md) +- [/api/planning/steering_factors](./api/planning/steering_factors.md) +- [/api/planning/velocity_factors](./api/planning/velocity_factors.md) +- [/api/routing/clear_route](./api/routing/clear_route.md) +- [/api/routing/route](./api/routing/route.md) +- [/api/routing/set_route](./api/routing/set_route.md) +- [/api/routing/set_route_points](./api/routing/set_route_points.md) +- [/api/routing/state](./api/routing/state.md) +- [/api/vehicle/dimensions](./api/vehicle/dimensions.md) +- [/api/vehicle/doors/command](./api/vehicle/doors/command.md) +- [/api/vehicle/doors/layout](./api/vehicle/doors/layout.md) +- [/api/vehicle/doors/status](./api/vehicle/doors/status.md) +- [/api/vehicle/kinematics](./api/vehicle/kinematics.md) +- [/api/vehicle/status](./api/vehicle/status.md) diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/bus-service.md b/docs/design/autoware-interfaces/ad-api/stories/bus-service.md similarity index 57% rename from docs/design/autoware-interfaces/ad-api/use-cases/bus-service.md rename to docs/design/autoware-interfaces/ad-api/stories/bus-service.md index a222a2335bb..77e091befaa 100644 --- a/docs/design/autoware-interfaces/ad-api/use-cases/bus-service.md +++ b/docs/design/autoware-interfaces/ad-api/stories/bus-service.md @@ -6,14 +6,14 @@ This user story is a bus service that goes around the designated stops. ## Scenario -| Step | Operation | Use Case | -| ---- | ---------------------------------------------------------- | ---------------------------------------------------------------- | -| 1 | Startup the autonomous driving system. | [Launch and terminate](launch-terminate.md) | -| 2 | Drive the vehicle from the garage to the waiting position. | [Change the operation mode](change-operation-mode.md) | -| 3 | Enable autonomous control. | [Change the operation mode](change-operation-mode.md) | -| 4 | Drive the vehicle to the next bus stop. | [Drive to the designated position](drive-designated-position.md) | -| 5 | Get on and off the vehicle. | [Get on and get off](get-on-off.md) | -| 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](drive-designated-position.md) | -| 8 | Drive the vehicle from the waiting position to the garage. | [Change the operation mode](change-operation-mode.md) | -| 9 | Shutdown the autonomous driving system. | [Launch and terminate](launch-terminate.md) | +| Step | Operation | Use Case | +| ---- | ---------------------------------------------------------- | ----------------------------------------------------------------------------- | +| 1 | Startup the autonomous driving system. | [Launch and terminate](../use-cases/launch-terminate.md) | +| 2 | Drive the vehicle from the garage to the waiting position. | [Change the operation mode](../use-cases/change-operation-mode.md) | +| 3 | Enable autonomous control. | [Change the operation mode](../use-cases/change-operation-mode.md) | +| 4 | Drive the vehicle to the next bus stop. | [Drive to the designated position](../use-cases/drive-designated-position.md) | +| 5 | Get on and off the vehicle. | [Get on and get off](../use-cases/get-on-off.md) | +| 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](../use-cases/drive-designated-position.md) | +| 8 | Drive the vehicle from the waiting position to the garage. | [Change the operation mode](../use-cases/change-operation-mode.md) | +| 9 | Shutdown the autonomous driving system. | [Launch and terminate](../use-cases/launch-terminate.md) | diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/taxi-service.md b/docs/design/autoware-interfaces/ad-api/stories/taxi-service.md similarity index 55% rename from docs/design/autoware-interfaces/ad-api/use-cases/taxi-service.md rename to docs/design/autoware-interfaces/ad-api/stories/taxi-service.md index b1d1a543eb1..4ce34d63866 100644 --- a/docs/design/autoware-interfaces/ad-api/use-cases/taxi-service.md +++ b/docs/design/autoware-interfaces/ad-api/stories/taxi-service.md @@ -6,16 +6,16 @@ This user story is a taxi service that picks up passengers and drives them to th ## Scenario -| Step | Operation | Use Case | -| ---- | ---------------------------------------------------------- | ---------------------------------------------------------------- | -| 1 | Startup the autonomous driving system. | [Launch and terminate](launch-terminate.md) | -| 2 | Drive the vehicle from the garage to the waiting position. | [Change the operation mode](change-operation-mode.md) | -| 3 | Enable autonomous control. | [Change the operation mode](change-operation-mode.md) | -| 4 | Drive the vehicle to the position to pick up. | [Drive to the designated position](drive-designated-position.md) | -| 5 | Get on the vehicle. | [Get on and get off](get-on-off.md) | -| 6 | Drive the vehicle to the destination. | [Drive to the designated position](drive-designated-position.md) | -| 7 | Get off the vehicle. | [Get on and get off](get-on-off.md) | -| 8 | Drive the vehicle to the waiting position. | [Drive to the designated position](drive-designated-position.md) | -| 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](change-operation-mode.md) | -| 11 | Shutdown the autonomous driving system. | [Launch and terminate](launch-terminate.md) | +| Step | Operation | Use Case | +| ---- | ---------------------------------------------------------- | ----------------------------------------------------------------------------- | +| 1 | Startup the autonomous driving system. | [Launch and terminate](../use-cases/launch-terminate.md) | +| 2 | Drive the vehicle from the garage to the waiting position. | [Change the operation mode](../use-cases/change-operation-mode.md) | +| 3 | Enable autonomous control. | [Change the operation mode](../use-cases/change-operation-mode.md) | +| 4 | Drive the vehicle to the position to pick up. | [Drive to the designated position](../use-cases/drive-designated-position.md) | +| 5 | Get on the vehicle. | [Get on and get off](../use-cases/get-on-off.md) | +| 6 | Drive the vehicle to the destination. | [Drive to the designated position](../use-cases/drive-designated-position.md) | +| 7 | Get off the vehicle. | [Get on and get off](../use-cases/get-on-off.md) | +| 8 | Drive the vehicle to the waiting position. | [Drive to the designated position](../use-cases/drive-designated-position.md) | +| 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](../use-cases/change-operation-mode.md) | +| 11 | Shutdown the autonomous driving system. | [Launch and terminate](../use-cases/launch-terminate.md) | diff --git a/docs/design/autoware-interfaces/ad-api/types/.pages b/docs/design/autoware-interfaces/ad-api/types/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/localization_initialization_state.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/localization_initialization_state.md deleted file mode 100644 index 5a4afbe5b8d..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/localization_initialization_state.md +++ /dev/null @@ -1,16 +0,0 @@ -# autoware_ad_api_msgs/msg/LocalizationInitializationState - -## Definition - -```txt -uint16 UNKNOWN = 0 -uint16 UNINITIALIZED = 1 -uint16 INITIALIZING = 2 -uint16 INITIALIZED = 3 - -uint16 state -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/motion_state.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/motion_state.md deleted file mode 100644 index 0168c06ef7b..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/motion_state.md +++ /dev/null @@ -1,17 +0,0 @@ -# autoware_ad_api_msgs/msg/MotionState - -## Definition - -```txt -uint16 UNKNOWN = 0 -uint16 STOPPED = 1 -uint16 STARTING = 2 -uint16 MOVING = 3 - -builtin_interfaces/Time stamp -uint16 state -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/mrm_state.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/mrm_state.md deleted file mode 100644 index 39cdad3096c..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/mrm_state.md +++ /dev/null @@ -1,28 +0,0 @@ -# autoware_ad_api_msgs/msg/MrmState - -## Definition - -```txt -# constants for both -uint16 UNKNOWN = 0 - -# constants for stamp -uint16 NONE = 1 -uint16 OPERATING = 2 -uint16 SUCCEEDED = 3 -uint16 FAILED = 4 - -# constants for behavior -uint16 NONE = 101 -uint16 EMERGENCY_STOP = 102 -uint16 COMFORTABLE_STOP = 103 - -# variables -builtin_interfaces/Time stamp -uint16 state -uint16 behavior -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/operation_mode_state.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/operation_mode_state.md deleted file mode 100644 index 11eb8658ddb..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/operation_mode_state.md +++ /dev/null @@ -1,25 +0,0 @@ -# autoware_ad_api_msgs/msg/OperationModeState - -## Definition - -```txt -# constants for operation_mode -uint16 UNKNOWN = 0 -uint16 STOP = 1 -uint16 AUTONOMOUS = 2 -uint16 LOCAL = 3 -uint16 REMOTE = 4 - -# variables -uint16 operation_mode -bool is_autoware_control_enabled -bool is_in_transition -bool change_to_stop -bool change_to_autonomous -bool change_to_local -bool change_to_remote -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/response_status.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/response_status.md deleted file mode 100644 index 7ed93770795..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/response_status.md +++ /dev/null @@ -1,19 +0,0 @@ -# autoware_ad_api_msgs/msg/ResponseStatus - -## Definition - -```txt -# constants for code -uint16 DEPRECATED = 50000 -uint16 SERVICE_UNREADY = 50001 -uint16 SERVICE_TIMEOUT = 50002 - -# variables -bool success -uint16 code -string message -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route.md deleted file mode 100644 index ed7d1eba592..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route.md +++ /dev/null @@ -1,14 +0,0 @@ -# autoware_ad_api_msgs/msg/Route - -## Definition - -```txt -std_msgs/Header header -geometry_msgs/Pose start -geometry_msgs/Pose goal -autoware_ad_api_msgs/RouteSegment[] segments -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/RouteSegment](../../autoware_ad_api_msgs/msg/route_segment.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_optional.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_optional.md deleted file mode 100644 index 1d14b1076ba..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_optional.md +++ /dev/null @@ -1,11 +0,0 @@ -# autoware_ad_api_msgs/msg/RouteOptional - -## Definition - -```txt -autoware_ad_api_msgs/Route[<=1] route -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/Route](../../autoware_ad_api_msgs/msg/route.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_primitive.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_primitive.md deleted file mode 100644 index 9146bdf4f4a..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_primitive.md +++ /dev/null @@ -1,12 +0,0 @@ -# autoware_ad_api_msgs/msg/RoutePrimitive - -## Definition - -```txt -int64 id -string type # The same id may be used for each type. -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_segment.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_segment.md deleted file mode 100644 index af02d76b05b..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_segment.md +++ /dev/null @@ -1,12 +0,0 @@ -# autoware_ad_api_msgs/msg/RouteSegment - -## Definition - -```txt -autoware_ad_api_msgs/RoutePrimitive[] preferred -autoware_ad_api_msgs/RoutePrimitive[] alternatives -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/RoutePrimitive](../../autoware_ad_api_msgs/msg/route_primitive.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_state.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_state.md deleted file mode 100644 index 8ffa6309cb9..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/route_state.md +++ /dev/null @@ -1,17 +0,0 @@ -# autoware_ad_api_msgs/msg/RouteState - -## Definition - -```txt -uint16 UNKNOWN = 0 -uint16 UNSET = 1 -uint16 SET = 2 -uint16 ARRIVED = 3 -uint16 CHANGING = 4 - -uint16 state -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/steering_factor_array.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/steering_factor_array.md deleted file mode 100644 index c9124e016d5..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/steering_factor_array.md +++ /dev/null @@ -1,12 +0,0 @@ -# autoware_ad_api_msgs/msg/SteeringFactorArray - -## Definition - -```txt -std_msgs/Header header -autoware_ad_api_msgs/SteeringFactor[] factors -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/SteeringFactor](../../autoware_ad_api_msgs/msg/steering_factor.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/velocity_factor_array.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/velocity_factor_array.md deleted file mode 100644 index b99af560e84..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/velocity_factor_array.md +++ /dev/null @@ -1,12 +0,0 @@ -# autoware_ad_api_msgs/msg/VelocityFactorArray - -## Definition - -```txt -std_msgs/Header header -autoware_ad_api_msgs/VelocityFactor[] factors -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/VelocityFactor](../../autoware_ad_api_msgs/msg/velocity_factor.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/accept_start.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/accept_start.md deleted file mode 100644 index 53d7f5540c2..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/accept_start.md +++ /dev/null @@ -1,12 +0,0 @@ -# autoware_ad_api_msgs/srv/AcceptStart - -## Definition - -```txt ---- -autoware_ad_api_msgs/ResponseStatus status -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/ResponseStatus](../../autoware_ad_api_msgs/msg/response_status.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/change_operation_mode.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/change_operation_mode.md deleted file mode 100644 index 6d81494ad4f..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/change_operation_mode.md +++ /dev/null @@ -1,12 +0,0 @@ -# autoware_ad_api_msgs/srv/ChangeOperationMode - -## Definition - -```txt ---- -autoware_ad_api_msgs/ResponseStatus status -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/ResponseStatus](../../autoware_ad_api_msgs/msg/response_status.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/clear_route.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/clear_route.md deleted file mode 100644 index 7bfa62a8708..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/clear_route.md +++ /dev/null @@ -1,12 +0,0 @@ -# autoware_ad_api_msgs/srv/ClearRoute - -## Definition - -```txt ---- -autoware_ad_api_msgs/ResponseStatus status -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/ResponseStatus](../../autoware_ad_api_msgs/msg/response_status.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/initialize_localization.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/initialize_localization.md deleted file mode 100644 index ffb2dc8ae3d..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/initialize_localization.md +++ /dev/null @@ -1,13 +0,0 @@ -# autoware_ad_api_msgs/srv/InitializeLocalization - -## Definition - -```txt -geometry_msgs/PoseWithCovarianceStamped[<=1] pose ---- -autoware_ad_api_msgs/ResponseStatus status -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/ResponseStatus](../../autoware_ad_api_msgs/msg/response_status.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/interface_version.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/interface_version.md deleted file mode 100644 index 76b87af9c1d..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/interface_version.md +++ /dev/null @@ -1,14 +0,0 @@ -# autoware_ad_api_msgs/srv/InterfaceVersion - -## Definition - -```txt ---- -uint16 major -uint16 minor -uint16 patch -``` - -## This type uses - -None diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/set_route.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/set_route.md deleted file mode 100644 index 1650bc1dce5..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/set_route.md +++ /dev/null @@ -1,17 +0,0 @@ -# autoware_ad_api_msgs/srv/SetRoute - -## Definition - -```txt -std_msgs/Header header -geometry_msgs/Pose[<=1] start -geometry_msgs/Pose goal -autoware_ad_api_msgs/RouteSegment[] segments ---- -autoware_ad_api_msgs/ResponseStatus status -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/ResponseStatus](../../autoware_ad_api_msgs/msg/response_status.md) -- [autoware_ad_api_msgs/msg/RouteSegment](../../autoware_ad_api_msgs/msg/route_segment.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/set_route_points.md b/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/set_route_points.md deleted file mode 100644 index fa96d7e9f4b..00000000000 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/srv/set_route_points.md +++ /dev/null @@ -1,16 +0,0 @@ -# autoware_ad_api_msgs/srv/SetRoutePoints - -## Definition - -```txt -std_msgs/Header header -geometry_msgs/Pose[<=1] start -geometry_msgs/Pose goal -geometry_msgs/Pose[] waypoints ---- -autoware_ad_api_msgs/ResponseStatus status -``` - -## This type uses - -- [autoware_ad_api_msgs/msg/ResponseStatus](../../autoware_ad_api_msgs/msg/response_status.md) diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorCommand.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorCommand.md new file mode 100644 index 00000000000..63978ac936e --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorCommand.md @@ -0,0 +1,19 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DoorCommand +used: + - autoware_adapi_v1_msgs/srv/SetDoorCommand +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint8 OPEN = 1 +uint8 CLOSE = 2 + +uint32 index +uint8 command +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorLayout.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorLayout.md new file mode 100644 index 00000000000..dbcc95c097a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorLayout.md @@ -0,0 +1,19 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DoorLayout +used: + - autoware_adapi_v1_msgs/srv/GetDoorLayout +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint8 GET_ON = 1 +uint8 GET_OFF = 2 + +uint8[] roles +string description +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatus.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatus.md new file mode 100644 index 00000000000..4cb91fad785 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatus.md @@ -0,0 +1,22 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DoorStatus +used: + - autoware_adapi_v1_msgs/msg/DoorStatusArray +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint8 UNKNOWN = 0 +uint8 NOT_AVAILABLE = 1 +uint8 OPENED = 2 +uint8 CLOSED = 3 +uint8 OPENING = 4 +uint8 CLOSING = 5 + +uint8 status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatusArray.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatusArray.md new file mode 100644 index 00000000000..cd83a4b8950 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DoorStatusArray.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DoorStatusArray +uses: + - autoware_adapi_v1_msgs/msg/DoorStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +builtin_interfaces/Time stamp +autoware_adapi_v1_msgs/DoorStatus[] doors +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObject.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObject.md new file mode 100644 index 00000000000..08e665e2973 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObject.md @@ -0,0 +1,22 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DynamicObject +used: + - autoware_adapi_v1_msgs/msg/DynamicObjectArray +uses: + - autoware_adapi_v1_msgs/msg/DynamicObjectKinematics + - autoware_adapi_v1_msgs/msg/ObjectClassification +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +unique_identifier_msgs/UUID id +float64 existence_probability +autoware_adapi_v1_msgs/ObjectClassification[] classification +autoware_adapi_v1_msgs/DynamicObjectKinematics kinematics +shape_msgs/SolidPrimitive shape +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectArray.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectArray.md new file mode 100644 index 00000000000..1b56045ef3a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectArray.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DynamicObjectArray +uses: + - autoware_adapi_v1_msgs/msg/DynamicObject +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +std_msgs/Header header +autoware_adapi_v1_msgs/DynamicObject[] objects +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectKinematics.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectKinematics.md new file mode 100644 index 00000000000..c6081500574 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectKinematics.md @@ -0,0 +1,21 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DynamicObjectKinematics +used: + - autoware_adapi_v1_msgs/msg/DynamicObject +uses: + - autoware_adapi_v1_msgs/msg/DynamicObjectPath +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +geometry_msgs/Pose pose +geometry_msgs/Twist twist +geometry_msgs/Accel accel + +autoware_adapi_v1_msgs/DynamicObjectPath[] predicted_paths +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectPath.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectPath.md new file mode 100644 index 00000000000..7978dc32263 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/DynamicObjectPath.md @@ -0,0 +1,17 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/DynamicObjectPath +used: + - autoware_adapi_v1_msgs/msg/DynamicObjectKinematics +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +geometry_msgs/Pose[] path +builtin_interfaces/Duration time_step +float64 confidence +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/Gear.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/Gear.md new file mode 100644 index 00000000000..6c79186e63c --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/Gear.md @@ -0,0 +1,23 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/Gear +used: + - autoware_adapi_v1_msgs/msg/VehicleStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +# constants +uint8 UNKNOWN = 0 +uint8 NEUTRAL = 1 +uint8 DRIVE = 2 +uint8 REVERSE = 3 +uint8 PARK = 4 +uint8 LOW = 5 + +uint8 status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/HazardLights.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/HazardLights.md new file mode 100644 index 00000000000..b7d3846de04 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/HazardLights.md @@ -0,0 +1,20 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/HazardLights +used: + - autoware_adapi_v1_msgs/msg/VehicleStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +# constants +uint8 UNKNOWN = 0 +uint8 DISABLE = 1 +uint8 ENABLE = 2 + +uint8 status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/LocalizationInitializationState.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/LocalizationInitializationState.md new file mode 100644 index 00000000000..504b192dea9 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/LocalizationInitializationState.md @@ -0,0 +1,19 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/LocalizationInitializationState +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint16 UNKNOWN = 0 +uint16 UNINITIALIZED = 1 +uint16 INITIALIZING = 2 +uint16 INITIALIZED = 3 + +builtin_interfaces/Time stamp +uint16 state +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MotionState.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MotionState.md new file mode 100644 index 00000000000..05a9f4f18cd --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MotionState.md @@ -0,0 +1,19 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/MotionState +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint16 UNKNOWN = 0 +uint16 STOPPED = 1 +uint16 STARTING = 2 +uint16 MOVING = 3 + +builtin_interfaces/Time stamp +uint16 state +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmState.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmState.md new file mode 100644 index 00000000000..992090f6cfb --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/MrmState.md @@ -0,0 +1,30 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/MrmState +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +builtin_interfaces/Time stamp + +# For common use +uint16 UNKNOWN = 0 + +# For state +uint16 NORMAL = 1 +uint16 MRM_OPERATING = 2 +uint16 MRM_SUCCEEDED = 3 +uint16 MRM_FAILED = 4 + +# For behavior +uint16 NONE = 1 +uint16 EMERGENCY_STOP = 2 +uint16 COMFORTABLE_STOP = 3 + +uint16 state +uint16 behavior +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ObjectClassification.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ObjectClassification.md new file mode 100644 index 00000000000..69a66623c32 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ObjectClassification.md @@ -0,0 +1,25 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/ObjectClassification +used: + - autoware_adapi_v1_msgs/msg/DynamicObject +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint8 UNKNOWN=0 +uint8 CAR=1 +uint8 TRUCK=2 +uint8 BUS=3 +uint8 TRAILER = 4 +uint8 MOTORCYCLE = 5 +uint8 BICYCLE = 6 +uint8 PEDESTRIAN = 7 + +uint8 label +float64 probability +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/OperationModeState.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/OperationModeState.md new file mode 100644 index 00000000000..ea56c87c38b --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/OperationModeState.md @@ -0,0 +1,28 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/OperationModeState +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +# constants for mode +uint8 UNKNOWN = 0 +uint8 STOP = 1 +uint8 AUTONOMOUS = 2 +uint8 LOCAL = 3 +uint8 REMOTE = 4 + +# variables +builtin_interfaces/Time stamp +uint8 mode +bool is_autoware_control_enabled +bool is_in_transition +bool is_stop_mode_available +bool is_autonomous_mode_available +bool is_local_mode_available +bool is_remote_mode_available +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md new file mode 100644 index 00000000000..9918fa9323a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/ResponseStatus.md @@ -0,0 +1,37 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/ResponseStatus +used: + - autoware_adapi_v1_msgs/srv/AcceptStart + - autoware_adapi_v1_msgs/srv/ChangeOperationMode + - autoware_adapi_v1_msgs/srv/ClearRoute + - autoware_adapi_v1_msgs/srv/GetDoorLayout + - autoware_adapi_v1_msgs/srv/GetVehicleDimensions + - autoware_adapi_v1_msgs/srv/InitializeLocalization + - autoware_adapi_v1_msgs/srv/SetDoorCommand + - autoware_adapi_v1_msgs/srv/SetRoute + - autoware_adapi_v1_msgs/srv/SetRoutePoints +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +# error code +uint16 UNKNOWN = 50000 +uint16 SERVICE_UNREADY = 50001 +uint16 SERVICE_TIMEOUT = 50002 +uint16 TRANSFORM_ERROR = 50003 +uint16 PARAMETER_ERROR = 50004 + +# warning code +uint16 DEPRECATED = 60000 +uint16 NO_EFFECT = 60001 + +# variables +bool success +uint16 code +string message +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/Route.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/Route.md new file mode 100644 index 00000000000..f4455b42ccf --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/Route.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/Route +uses: + - autoware_adapi_v1_msgs/msg/RouteData +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +std_msgs/Header header +autoware_adapi_v1_msgs/RouteData[<=1] data +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteData.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteData.md new file mode 100644 index 00000000000..1e27e8aa4da --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteData.md @@ -0,0 +1,19 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/RouteData +used: + - autoware_adapi_v1_msgs/msg/Route +uses: + - autoware_adapi_v1_msgs/msg/RouteSegment +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +geometry_msgs/Pose start +geometry_msgs/Pose goal +autoware_adapi_v1_msgs/RouteSegment[] segments +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteOption.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteOption.md new file mode 100644 index 00000000000..25deed8faf8 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteOption.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/RouteOption +used: + - autoware_adapi_v1_msgs/srv/SetRoute + - autoware_adapi_v1_msgs/srv/SetRoutePoints +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +bool allow_goal_modification +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RoutePrimitive.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RoutePrimitive.md new file mode 100644 index 00000000000..cc3b5bae5b0 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RoutePrimitive.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/RoutePrimitive +used: + - autoware_adapi_v1_msgs/msg/RouteSegment +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +int64 id +string type # The same id may be used for each type. +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteSegment.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteSegment.md new file mode 100644 index 00000000000..c4171c24b87 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteSegment.md @@ -0,0 +1,19 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/RouteSegment +used: + - autoware_adapi_v1_msgs/msg/RouteData + - autoware_adapi_v1_msgs/srv/SetRoute +uses: + - autoware_adapi_v1_msgs/msg/RoutePrimitive +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +autoware_adapi_v1_msgs/RoutePrimitive preferred +autoware_adapi_v1_msgs/RoutePrimitive[] alternatives # Does not include the preferred primitive. +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteState.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteState.md new file mode 100644 index 00000000000..d4985ebe361 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/RouteState.md @@ -0,0 +1,20 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/RouteState +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +uint16 UNKNOWN = 0 +uint16 UNSET = 1 +uint16 SET = 2 +uint16 ARRIVED = 3 +uint16 CHANGING = 4 + +builtin_interfaces/Time stamp +uint16 state +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/steering_factor.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactor.md similarity index 53% rename from docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/steering_factor.md rename to docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactor.md index 8731cd62cfe..1b35ddeb8a3 100644 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/steering_factor.md +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactor.md @@ -1,6 +1,12 @@ -# autoware_ad_api_msgs/msg/SteeringFactor +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/SteeringFactor +used: + - autoware_adapi_v1_msgs/msg/SteeringFactorArray +--- -## Definition +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} ```txt # constants for common use @@ -12,8 +18,10 @@ uint16 LANE_CHANGE = 2 uint16 AVOIDANCE_PATH_CHANGE = 3 uint16 AVOIDANCE_PATH_RETURN = 4 uint16 STATION = 5 -uint16 PULL_OUT = 6 -uint16 PULL_OVER = 7 +uint16 PULL_OUT = 6 # Deprecated. Use START_PLANNER. +uint16 START_PLANNER = 6 +uint16 PULL_OVER = 7 # Deprecated. Use GOAL_PLANNER. +uint16 GOAL_PLANNER = 7 uint16 EMERGENCY_OPERATION = 8 # constants for direction @@ -35,6 +43,4 @@ uint16 status string detail ``` -## This type uses - -None +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactorArray.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactorArray.md new file mode 100644 index 00000000000..ceafe541958 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/SteeringFactorArray.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/SteeringFactorArray +uses: + - autoware_adapi_v1_msgs/msg/SteeringFactor +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +std_msgs/Header header +autoware_adapi_v1_msgs/SteeringFactor[] factors +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/TurnIndicators.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/TurnIndicators.md new file mode 100644 index 00000000000..f27fb2c2f0f --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/TurnIndicators.md @@ -0,0 +1,21 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/TurnIndicators +used: + - autoware_adapi_v1_msgs/msg/VehicleStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +# constants +uint8 UNKNOWN = 0 +uint8 DISABLE = 1 +uint8 LEFT = 2 +uint8 RIGHT = 3 + +uint8 status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleDimensions.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleDimensions.md new file mode 100644 index 00000000000..ec69bf6e741 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleDimensions.md @@ -0,0 +1,24 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/VehicleDimensions +used: + - autoware_adapi_v1_msgs/srv/GetVehicleDimensions +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +float32 wheel_radius +float32 wheel_width +float32 wheel_base +float32 wheel_tread +float32 front_overhang +float32 rear_overhang +float32 left_overhang +float32 right_overhang +float32 height +geometry_msgs/Polygon footprint +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleKinematics.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleKinematics.md new file mode 100644 index 00000000000..b82e24735bc --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleKinematics.md @@ -0,0 +1,20 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/VehicleKinematics +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +# Geographic point, using the WGS 84 reference ellipsoid. +# This data will be invalid If Autoware does not provide projection information between geographic coordinates and local coordinates. +geographic_msgs/GeoPointStamped geographic_pose + +# Local coordinate from the autoware +geometry_msgs/PoseWithCovarianceStamped pose +geometry_msgs/TwistWithCovarianceStamped twist +geometry_msgs/AccelWithCovarianceStamped accel +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleStatus.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleStatus.md new file mode 100644 index 00000000000..224f1999d1a --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VehicleStatus.md @@ -0,0 +1,22 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/VehicleStatus +uses: + - autoware_adapi_v1_msgs/msg/Gear + - autoware_adapi_v1_msgs/msg/HazardLights + - autoware_adapi_v1_msgs/msg/TurnIndicators +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +builtin_interfaces/Time stamp +autoware_adapi_v1_msgs/Gear gear +autoware_adapi_v1_msgs/TurnIndicators turn_indicators +autoware_adapi_v1_msgs/HazardLights hazard_lights +float64 steering_tire_angle +float32 energy_percentage # Battery percentage or fuel percentage, it will depends on the vehicle. +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/velocity_factor.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md similarity index 67% rename from docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/velocity_factor.md rename to docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md index 322f34a4107..7cb4125992f 100644 --- a/docs/design/autoware-interfaces/ad-api/types/autoware_ad_api_msgs/msg/velocity_factor.md +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactor.md @@ -1,6 +1,12 @@ -# autoware_ad_api_msgs/msg/VelocityFactor +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/VelocityFactor +used: + - autoware_adapi_v1_msgs/msg/VelocityFactorArray +--- -## Definition +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} ```txt # constants for common use @@ -23,6 +29,7 @@ uint16 SIDEWALK = 13 uint16 LANE_CHANGE = 14 uint16 AVOIDANCE = 15 uint16 EMERGENCY_STOP_OPERATION = 16 +uint16 NO_DRIVABLE_LANE = 17 # constants for status uint16 APPROACHING = 1 @@ -36,6 +43,4 @@ uint16 status string detail ``` -## This type uses - -None +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactorArray.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactorArray.md new file mode 100644 index 00000000000..da90bfa1280 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/msg/VelocityFactorArray.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/msg/VelocityFactorArray +uses: + - autoware_adapi_v1_msgs/msg/VelocityFactor +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +std_msgs/Header header +autoware_adapi_v1_msgs/VelocityFactor[] factors +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/AcceptStart.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/AcceptStart.md new file mode 100644 index 00000000000..e80d4e780f5 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/AcceptStart.md @@ -0,0 +1,17 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/AcceptStart +uses: + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +--- +uint16 ERROR_NOT_STARTING = 1 +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ChangeOperationMode.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ChangeOperationMode.md new file mode 100644 index 00000000000..e16cbda7eec --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ChangeOperationMode.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/ChangeOperationMode +uses: + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +--- +uint16 ERROR_NOT_AVAILABLE = 1 +uint16 ERROR_IN_TRANSITION = 2 +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ClearRoute.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ClearRoute.md new file mode 100644 index 00000000000..e7d10672b0d --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/ClearRoute.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/ClearRoute +uses: + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +--- +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetDoorLayout.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetDoorLayout.md new file mode 100644 index 00000000000..aebb1b2dc77 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetDoorLayout.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/GetDoorLayout +uses: + - autoware_adapi_v1_msgs/msg/DoorLayout + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +--- +autoware_adapi_v1_msgs/ResponseStatus status +autoware_adapi_v1_msgs/DoorLayout[] doors +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetVehicleDimensions.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetVehicleDimensions.md new file mode 100644 index 00000000000..5e5884a823d --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/GetVehicleDimensions.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/GetVehicleDimensions +uses: + - autoware_adapi_v1_msgs/msg/ResponseStatus + - autoware_adapi_v1_msgs/msg/VehicleDimensions +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +--- +autoware_adapi_v1_msgs/ResponseStatus status +autoware_adapi_v1_msgs/VehicleDimensions dimensions +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/InitializeLocalization.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/InitializeLocalization.md new file mode 100644 index 00000000000..a43875336bd --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/InitializeLocalization.md @@ -0,0 +1,21 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/InitializeLocalization +uses: + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +geometry_msgs/PoseWithCovarianceStamped[<=1] pose +--- +uint16 ERROR_UNSAFE = 1 +uint16 ERROR_GNSS_SUPPORT = 2 +uint16 ERROR_GNSS = 3 +uint16 ERROR_ESTIMATION = 4 +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetDoorCommand.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetDoorCommand.md new file mode 100644 index 00000000000..2879fa223bb --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetDoorCommand.md @@ -0,0 +1,18 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/SetDoorCommand +uses: + - autoware_adapi_v1_msgs/msg/DoorCommand + - autoware_adapi_v1_msgs/msg/ResponseStatus +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +autoware_adapi_v1_msgs/DoorCommand[] doors +--- +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetRoute.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetRoute.md new file mode 100644 index 00000000000..8a61fa7a7ee --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetRoute.md @@ -0,0 +1,27 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/SetRoute +uses: + - autoware_adapi_v1_msgs/msg/ResponseStatus + - autoware_adapi_v1_msgs/msg/RouteOption + - autoware_adapi_v1_msgs/msg/RouteSegment +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +std_msgs/Header header +autoware_adapi_v1_msgs/RouteOption option +geometry_msgs/Pose goal +autoware_adapi_v1_msgs/RouteSegment[] segments +--- +uint16 ERROR_ROUTE_EXISTS = 1 # Deprecated. Use ERROR_INVALID_STATE. +uint16 ERROR_INVALID_STATE = 1 +uint16 ERROR_PLANNER_UNREADY = 2 +uint16 ERROR_PLANNER_FAILED = 3 +uint16 ERROR_REROUTE_FAILED = 4 +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetRoutePoints.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetRoutePoints.md new file mode 100644 index 00000000000..e73b86b62f4 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_v1_msgs/srv/SetRoutePoints.md @@ -0,0 +1,26 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_v1_msgs/srv/SetRoutePoints +uses: + - autoware_adapi_v1_msgs/msg/ResponseStatus + - autoware_adapi_v1_msgs/msg/RouteOption +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +std_msgs/Header header +autoware_adapi_v1_msgs/RouteOption option +geometry_msgs/Pose goal +geometry_msgs/Pose[] waypoints +--- +uint16 ERROR_ROUTE_EXISTS = 1 # Deprecated. Use ERROR_INVALID_STATE. +uint16 ERROR_INVALID_STATE = 1 +uint16 ERROR_PLANNER_UNREADY = 2 +uint16 ERROR_PLANNER_FAILED = 3 +uint16 ERROR_REROUTE_FAILED = 4 +autoware_adapi_v1_msgs/ResponseStatus status +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/InterfaceVersion.md b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/InterfaceVersion.md new file mode 100644 index 00000000000..7caf613d6ed --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/autoware_adapi_version_msgs/srv/InterfaceVersion.md @@ -0,0 +1,16 @@ +--- +# This file is generated by tools/autoware-interfaces/generate.py +title: autoware_adapi_version_msgs/srv/InterfaceVersion +--- + +{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %} +{% block definition %} + +```txt +--- +uint16 major +uint16 minor +uint16 patch +``` + +{% endblock %} diff --git a/docs/design/autoware-interfaces/ad-api/types/index.md b/docs/design/autoware-interfaces/ad-api/types/index.md new file mode 100644 index 00000000000..fc2a043a3ac --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/types/index.md @@ -0,0 +1,42 @@ +# Types of Autoware AD API + +- [autoware_adapi_v1_msgs/msg/DoorCommand](./autoware_adapi_v1_msgs/msg/DoorCommand.md) +- [autoware_adapi_v1_msgs/msg/DoorLayout](./autoware_adapi_v1_msgs/msg/DoorLayout.md) +- [autoware_adapi_v1_msgs/msg/DoorStatus](./autoware_adapi_v1_msgs/msg/DoorStatus.md) +- [autoware_adapi_v1_msgs/msg/DoorStatusArray](./autoware_adapi_v1_msgs/msg/DoorStatusArray.md) +- [autoware_adapi_v1_msgs/msg/DynamicObject](./autoware_adapi_v1_msgs/msg/DynamicObject.md) +- [autoware_adapi_v1_msgs/msg/DynamicObjectArray](./autoware_adapi_v1_msgs/msg/DynamicObjectArray.md) +- [autoware_adapi_v1_msgs/msg/DynamicObjectKinematics](./autoware_adapi_v1_msgs/msg/DynamicObjectKinematics.md) +- [autoware_adapi_v1_msgs/msg/DynamicObjectPath](./autoware_adapi_v1_msgs/msg/DynamicObjectPath.md) +- [autoware_adapi_v1_msgs/msg/Gear](./autoware_adapi_v1_msgs/msg/Gear.md) +- [autoware_adapi_v1_msgs/msg/HazardLights](./autoware_adapi_v1_msgs/msg/HazardLights.md) +- [autoware_adapi_v1_msgs/msg/LocalizationInitializationState](./autoware_adapi_v1_msgs/msg/LocalizationInitializationState.md) +- [autoware_adapi_v1_msgs/msg/MotionState](./autoware_adapi_v1_msgs/msg/MotionState.md) +- [autoware_adapi_v1_msgs/msg/MrmState](./autoware_adapi_v1_msgs/msg/MrmState.md) +- [autoware_adapi_v1_msgs/msg/ObjectClassification](./autoware_adapi_v1_msgs/msg/ObjectClassification.md) +- [autoware_adapi_v1_msgs/msg/OperationModeState](./autoware_adapi_v1_msgs/msg/OperationModeState.md) +- [autoware_adapi_v1_msgs/msg/ResponseStatus](./autoware_adapi_v1_msgs/msg/ResponseStatus.md) +- [autoware_adapi_v1_msgs/msg/Route](./autoware_adapi_v1_msgs/msg/Route.md) +- [autoware_adapi_v1_msgs/msg/RouteData](./autoware_adapi_v1_msgs/msg/RouteData.md) +- [autoware_adapi_v1_msgs/msg/RouteOption](./autoware_adapi_v1_msgs/msg/RouteOption.md) +- [autoware_adapi_v1_msgs/msg/RoutePrimitive](./autoware_adapi_v1_msgs/msg/RoutePrimitive.md) +- [autoware_adapi_v1_msgs/msg/RouteSegment](./autoware_adapi_v1_msgs/msg/RouteSegment.md) +- [autoware_adapi_v1_msgs/msg/RouteState](./autoware_adapi_v1_msgs/msg/RouteState.md) +- [autoware_adapi_v1_msgs/msg/SteeringFactor](./autoware_adapi_v1_msgs/msg/SteeringFactor.md) +- [autoware_adapi_v1_msgs/msg/SteeringFactorArray](./autoware_adapi_v1_msgs/msg/SteeringFactorArray.md) +- [autoware_adapi_v1_msgs/msg/TurnIndicators](./autoware_adapi_v1_msgs/msg/TurnIndicators.md) +- [autoware_adapi_v1_msgs/msg/VehicleDimensions](./autoware_adapi_v1_msgs/msg/VehicleDimensions.md) +- [autoware_adapi_v1_msgs/msg/VehicleKinematics](./autoware_adapi_v1_msgs/msg/VehicleKinematics.md) +- [autoware_adapi_v1_msgs/msg/VehicleStatus](./autoware_adapi_v1_msgs/msg/VehicleStatus.md) +- [autoware_adapi_v1_msgs/msg/VelocityFactor](./autoware_adapi_v1_msgs/msg/VelocityFactor.md) +- [autoware_adapi_v1_msgs/msg/VelocityFactorArray](./autoware_adapi_v1_msgs/msg/VelocityFactorArray.md) +- [autoware_adapi_v1_msgs/srv/AcceptStart](./autoware_adapi_v1_msgs/srv/AcceptStart.md) +- [autoware_adapi_v1_msgs/srv/ChangeOperationMode](./autoware_adapi_v1_msgs/srv/ChangeOperationMode.md) +- [autoware_adapi_v1_msgs/srv/ClearRoute](./autoware_adapi_v1_msgs/srv/ClearRoute.md) +- [autoware_adapi_v1_msgs/srv/GetDoorLayout](./autoware_adapi_v1_msgs/srv/GetDoorLayout.md) +- [autoware_adapi_v1_msgs/srv/GetVehicleDimensions](./autoware_adapi_v1_msgs/srv/GetVehicleDimensions.md) +- [autoware_adapi_v1_msgs/srv/InitializeLocalization](./autoware_adapi_v1_msgs/srv/InitializeLocalization.md) +- [autoware_adapi_v1_msgs/srv/SetDoorCommand](./autoware_adapi_v1_msgs/srv/SetDoorCommand.md) +- [autoware_adapi_v1_msgs/srv/SetRoute](./autoware_adapi_v1_msgs/srv/SetRoute.md) +- [autoware_adapi_v1_msgs/srv/SetRoutePoints](./autoware_adapi_v1_msgs/srv/SetRoutePoints.md) +- [autoware_adapi_version_msgs/srv/InterfaceVersion](./autoware_adapi_version_msgs/srv/InterfaceVersion.md) diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/index.md b/docs/design/autoware-interfaces/ad-api/use-cases/index.md deleted file mode 100644 index 96dfb0f9536..00000000000 --- a/docs/design/autoware-interfaces/ad-api/use-cases/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# Use cases of Autoware AD API - -## User stories - -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](bus-service.md) -- [Taxi service](taxi-service.md) - -## Use cases - -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](launch-terminate.md) -- [Initialize the pose](initialize-pose.md) -- [Change the operation mode](change-operation-mode.md) -- [Drive to the designated position](drive-designated-position.md) -- [Get on and get off](get-on-off.md) diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/request-to-cooperate.md b/docs/design/autoware-interfaces/ad-api/use-cases/request-to-cooperate.md new file mode 100644 index 00000000000..7b0dc2385d3 --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/use-cases/request-to-cooperate.md @@ -0,0 +1,7 @@ +# Request to cooperate + +!!! warning + + Under Construction + +AD API supports operator cooperation for vehicle decisions. diff --git a/docs/design/autoware-interfaces/ad-api/use-cases/vehicle-monitoring.md b/docs/design/autoware-interfaces/ad-api/use-cases/vehicle-monitoring.md new file mode 100644 index 00000000000..b3c5795f88e --- /dev/null +++ b/docs/design/autoware-interfaces/ad-api/use-cases/vehicle-monitoring.md @@ -0,0 +1,21 @@ +# Vehicle monitoring + +AD API provides current vehicle status for remote monitoring, visualization for passengers, etc. +Use the API below depending on the data you want to monitor. + +## Vehicle status + +The [vehicle status](../features/vehicle-status.md) provides basic information such as kinematics, indicators, and dimensions. +This allows a remote operator to know the position and velocity of the vehicle. +For applications such as FMS, it can help find vehicles that need assistance, such as vehicles that are stuck or brake suddenly. +It is also possible to determine the actual distance to an object from the vehicle dimensions. + +## Planning factors + +The [planning factors](../features/planning-factors.md) provides the planning status of the vehicle. +HMI can use this to warn of sudden movements of the vehicle, and to share the stop reason with passengers for comfortable driving. + +## Detected objects + +The [perception](../features/perception.md) provides the objects detected by Autoware. +HMI can use this to visualize objects around the vehicle. diff --git a/docs/design/autoware-interfaces/components/.pages b/docs/design/autoware-interfaces/components/.pages index e1830c8e4d6..e06a4052a0e 100644 --- a/docs/design/autoware-interfaces/components/.pages +++ b/docs/design/autoware-interfaces/components/.pages @@ -2,5 +2,7 @@ nav: - index.md - planning.md - control.md + - localization.md + - map.md - vehicle-interface.md - vehicle-dimensions.md diff --git a/docs/design/autoware-interfaces/components/control.md b/docs/design/autoware-interfaces/components/control.md index 3afb865f254..0f2ee2ebbda 100644 --- a/docs/design/autoware-interfaces/components/control.md +++ b/docs/design/autoware-interfaces/components/control.md @@ -43,7 +43,7 @@ TODO This represents the reported physical efforts exerted by the vehicle actuat 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]( +- [autoware_auto_control_msgs/AckermannControlCommand](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/AckermannControlCommand.idl) - builtin_interfaces::msg::Time stamp - [autoware_auto_control_msgs/AckermannLateralCommand](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/AckermannLateralCommand.idl) lateral - builtin_interfaces::msg::Time stamp diff --git a/docs/design/autoware-interfaces/components/images/Localization-Bus-ODD-Architecture.drawio.svg b/docs/design/autoware-interfaces/components/images/Localization-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..d51e205fa97 --- /dev/null +++ b/docs/design/autoware-interfaces/components/images/Localization-Bus-ODD-Architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Manual Inital Pose
Manual Inital Pose
geometry_msgs/msg/
PoseWithCovarianceStamped
geometry_msgs/msg/...
Localization
Localization
User Interface
User Interface
Planning
Planning
Map Server
Map Server
Pointcloud Map
Pointcloud Map
sensor_msgs/msg/PointCloud2
sensor_msgs/msg/PointCloud2
Control
Control
Sensing
Sensing
 Automatic Initial Pose
 Automatic Initial Pose
geometry_msgs/msg/
PoseWithCovarianceStamped
geometry_msgs/msg/...
IMU Data
IMU Data
sensor_msgs/msg/Imu
sensor_msgs/msg/Imu
Vehicle Interface
Vehicle Interface
Velocity Status
Velocity Status
autoware_auto_vehicle_msgs/
msg/VelocityReport
autoware_auto_vehicle_msgs/...
LiDAR Scanning
LiDAR Scanning
sensor_msgs/msg/PointCloud2
sensor_msgs/msg/PointCloud2
Vehicle Control Command
Vehicle Control Command
autoware_auto_vehicle_msgs/
msg/AckermannControlCommand
autoware_auto_vehicle_msgs/...
Trajectory
Trajectory
autoware_auto_planning_msgs/
msg/Trajectory
autoware_auto_planning_msgs/...
Vehicle Acceleration
Vehicle Acceleration
geometry_msgs/msg/
AccelWithCovarianceStamped
geometry_msgs/msg/...
Vehicle Kinematic State
Vehicle Kinematic State
autoware_msgs/autoware_localization_msgs/
msg/KinematicState
autoware_msgs/autoware_localization_msgs/...
Diagnostic Manager
Diagnostic Manager
LocalizationAccuracy
LocalizationAccuracy
Vehicle Twist
Vehicle Twist
geoTwistmetry_msgs/msg/
WithCovarianceStamped
geoTwistmetry_msgs/msg/...
Vehicle Pose
Vehicle Pose
geometry_msgs/msg/
PoseWithCovarianceStamped
geometry_msgs/msg/...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/autoware-interfaces/components/images/Map-Bus-ODD-Architecture.drawio.svg b/docs/design/autoware-interfaces/components/images/Map-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..c6d679c4802 --- /dev/null +++ b/docs/design/autoware-interfaces/components/images/Map-Bus-ODD-Architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Map Server
Map Server
Lanelet2 Map Marker
Lanelet2 Map Marker
visualization_msgs/msg/MarkerArray
visualization_msgs/msg/MarkerArray
Pointcloud Map
Pointcloud Map
sensor_msgs/msg/PointCloud2
sensor_msgs/msg/PointCloud2
Lanelet2 Map
Lanelet2 Map
autoware_auto_mapping_msgs/msg/
HADMapBin
autoware_auto_mapping_msgs/msg/...
Localization
Localization
Planning
Planning
Vehicle Kinematic State
Vehicle Kinematic State
nav_msg/msg/Odometry
nav_msg/msg/Odometry
Trajectory
Trajectory
autoware_auto_planning_msgs/msg/
Trajectory
autoware_auto_planning_msgs/msg/...
3D object Predictions
3D object Predictions
autoware_auto_perception_msgs/msg/
PredictedObjects
autoware_auto_perception_msgs/msg/...
Perception
Perception
Traffic Light Response
Traffic Light ResponseText is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/autoware-interfaces/components/images/planning-interface-input.drawio.svg b/docs/design/autoware-interfaces/components/images/planning-interface-input.drawio.svg new file mode 100644 index 00000000000..621ede46902 --- /dev/null +++ b/docs/design/autoware-interfaces/components/images/planning-interface-input.drawio.svg @@ -0,0 +1,72 @@ + + + + + + + +
+
+
+ + Planning Component + +
+
+
+ + + Planning Component + + + + + + + + + +
+
+
+ + Other Components + +
+
+
+ + + Other Components + + + + + + + +
+
+
+ + Other Components + +
+
+
+ + + Other Components + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-interfaces/components/images/planning-interface-internal.drawio.svg b/docs/design/autoware-interfaces/components/images/planning-interface-internal.drawio.svg new file mode 100644 index 00000000000..9a06d1b1506 --- /dev/null +++ b/docs/design/autoware-interfaces/components/images/planning-interface-internal.drawio.svg @@ -0,0 +1,114 @@ + + + + + + + +
+
+
+ + Planning Component +
+
+
+
+ +
+
+
+ + + Planning Component... + + + + + + + +
+
+
+ + Other Components + +
+
+
+ + + Other Components + + + + + + + +
+
+
+ + Other Components + +
+
+
+ + + Other Components + + + + + + + + + +
+
+
+ + Module + +
+
+
+ + + Module + + + + + + + +
+
+
+ + Module + +
+
+
+ + + Module + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-interfaces/components/images/planning-interface-output.drawio.svg b/docs/design/autoware-interfaces/components/images/planning-interface-output.drawio.svg new file mode 100644 index 00000000000..11a4ecb2780 --- /dev/null +++ b/docs/design/autoware-interfaces/components/images/planning-interface-output.drawio.svg @@ -0,0 +1,72 @@ + + + + + + + + + +
+
+
+ + Planning Component + +
+
+
+ + + Planning Component + + + + + + + +
+
+
+ + Other Components + +
+
+
+ + + Other Components + + + + + + + +
+
+
+ + Other Components + +
+
+
+ + + Other Components + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-interfaces/components/index.md b/docs/design/autoware-interfaces/components/index.md index d3170ab4fdc..3c0550cff93 100644 --- a/docs/design/autoware-interfaces/components/index.md +++ b/docs/design/autoware-interfaces/components/index.md @@ -3,3 +3,5 @@ !!! warning Under Construction + +See [here](../index.md) for an overview. diff --git a/docs/design/autoware-interfaces/components/localization.md b/docs/design/autoware-interfaces/components/localization.md new file mode 100644 index 00000000000..3c50e2b1eb2 --- /dev/null +++ b/docs/design/autoware-interfaces/components/localization.md @@ -0,0 +1,152 @@ +# Localization + +![Node diagram](images/Localization-Bus-ODD-Architecture.drawio.svg) + +## Inputs + +### Pointcloud Map + +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. + +### Manual Initial Pose + +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 + +### 3D-LiDAR Scanning + +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](../../autoware-architecture/sensing/data-types/point-cloud.md) before being used for localization. + +### Automatic Initial pose + +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 + +### IMU Data + +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 + +### Vehicle Velocity Status + +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`. + +## Outputs + +### Vehicle pose + +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 + +### Vehicle velocity + +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 + +### Vehicle acceleration + +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 + +### Vehicle kinematic state + +Current pose, velocity and acceleration of ego, calculated from localization interface. + +**Note:** Kinematic state contains pose, velocity and acceleration. In the future, [pose](#vehicle-pose), [velocity](#vehicle-velocity) and [acceleration](#vehicle-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. + +### Localization Accuracy + +Diagnostics information that indicates if the localization module works properly. + +TBD. diff --git a/docs/design/autoware-interfaces/components/map.md b/docs/design/autoware-interfaces/components/map.md new file mode 100644 index 00000000000..578981ad963 --- /dev/null +++ b/docs/design/autoware-interfaces/components/map.md @@ -0,0 +1,42 @@ +# Map + +![Node diagram](./images/Map-Bus-ODD-Architecture.drawio.svg) + +## Overview + +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. + +## Inputs + +- Point cloud maps (`.pcd`) +- Lanelet2 maps (`.osm`) + +Refer to [Creating maps](../../../how-to-guides/integrating-autoware/creating-maps/index.md) on how to create maps. + +## Outputs + +### Point cloud map + +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) + +### Lanelet2 map + +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 + +### Lanelet2 map visualization + +Visualize `autoware_auto_mapping_msgs/HADMapBin` messages in `Rviz`. + +- visualization_msgs/msg/MarkerArray diff --git a/docs/design/autoware-interfaces/components/sensing.md b/docs/design/autoware-interfaces/components/sensing.md new file mode 100644 index 00000000000..b1f71d233fc --- /dev/null +++ b/docs/design/autoware-interfaces/components/sensing.md @@ -0,0 +1,191 @@ +# Sensing + +```mermaid +graph TD + cmp_drv("Drivers"):::cls_drv + cmp_loc("Localization"):::cls_loc + cmp_per("Perception"):::cls_per + cmp_sen("Preprocessors"):::cls_sen + msg_ult("Ultrasonics + sensor_msgs/Range"):::cls_drv + msg_img("Camera Image + sensor_msgs/Image"):::cls_drv + msg_ldr("Lidar Point Cloud + sensor_msgs/PointCloud2"):::cls_drv + msg_rdr_t("Radar Tracks + radar_msgs/RadarTracks"):::cls_drv + msg_rdr_s("Radar Scan + radar_msgs/RadarScan"):::cls_drv + msg_gnss("GNSS-INS Position + sensor_msgs/NavSatFix"):::cls_drv + msg_gnssori("GNSS-INS Orientation + autoware_sensing_msgs/GnssInsOrientationStamped"):::cls_drv + msg_gnssvel("GNSS Velocity + geometry_msgs/TwistWithCovarianceStamped"):::cls_drv + msg_gnssacc("GNSS Acceleration + geometry_msgs/AccelWithCovarianceStamped"):::cls_drv + msg_ult_sen("Ultrasonics + sensor_msgs/Range"):::cls_sen + msg_img_sen("Camera Image + sensor_msgs/Image"):::cls_sen + msg_pc_combined_rdr("Combined Radar Tracks + radar_msgs/RadarTracks"):::cls_sen + msg_pc_rdr("Radar Pointcloud + radar_msgs/RadarScan"):::cls_sen + msg_pc_combined_ldr("Combined Lidar Point Cloud + sensor_msgs/PointCloud2"):::cls_sen + msg_pose_gnss("GNSS-INS Pose + geometry_msgs/PoseWithCovarianceStamped"):::cls_sen + msg_gnssori_sen("GNSS-INS Orientation + sensor_msgs/Imu"):::cls_sen + msg_gnssvel_sen("GNSS Velocity + geometry_msgs/TwistWithCovarianceStamped"):::cls_sen + msg_gnssacc_sen("GNSS-INS Acceleration + geometry_msgs/AccelWithCovarianceStamped"):::cls_sen + + cmp_drv --> msg_ult --> cmp_sen + cmp_drv --> msg_img --> cmp_sen + cmp_drv --> msg_rdr_t --> cmp_sen + cmp_drv --> msg_rdr_s --> cmp_sen + cmp_drv --> msg_ldr --> cmp_sen + cmp_drv --> msg_gnss --> cmp_sen + cmp_drv --> msg_gnssori --> cmp_sen + cmp_drv --> msg_gnssvel --> cmp_sen + cmp_drv --> msg_gnssacc --> cmp_sen + + cmp_sen --> msg_ult_sen + cmp_sen --> msg_img_sen + cmp_sen --> msg_gnssori_sen + cmp_sen --> msg_gnssvel_sen + cmp_sen --> msg_pc_combined_rdr + cmp_sen --> msg_pc_rdr + cmp_sen --> msg_pc_combined_ldr + cmp_sen --> msg_pose_gnss + cmp_sen --> msg_gnssacc_sen + msg_ult_sen --> cmp_per + msg_img_sen --> cmp_per + msg_pc_combined_rdr --> cmp_per + msg_pc_rdr --> cmp_per + msg_pc_combined_ldr --> cmp_per + msg_pc_combined_ldr --> cmp_loc + msg_pose_gnss --> cmp_loc + msg_gnssori_sen --> cmp_loc + msg_gnssvel_sen --> cmp_loc + msg_gnssacc_sen --> cmp_loc +classDef cls_drv fill:#F8CECC,stroke:#999,stroke-width:1px; +classDef cls_loc fill:#D5E8D4,stroke:#999,stroke-width:1px; +classDef cls_per fill:#FFF2CC,stroke:#999,stroke-width:1px; +classDef cls_sen fill:#FFE6CC,stroke:#999,stroke-width:1px; +``` + +## Inputs + +### Ultrasonics + +Distance data from ultrasonic radar driver. + +- [sensor_msgs/Range](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Range.msg) + +### Camera Image + +Image data from camera driver. + +- [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Image.msg) + +### Radar Tracks + +Tracks from radar driver. + +- [radar_msgs/RadarTracks](https://github.com/ros-perception/radar_msgs/blob/ros2/msg/RadarTracks.msg) + +### Radar Scan + +Scan from radar driver. + +- [radar_msgs/RadarScan](https://github.com/ros-perception/radar_msgs/blob/ros2/msg/RadarScan.msg) + +### Lidar Point Cloud + +Pointcloud from lidar driver. + +- [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/PointCloud2.msg) + +### GNSS-INS Position + +Initial pose from GNSS driver. + +- [geometry_msgs/NavSatFix](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/NavSatFix.msg) + +### GNSS-INS Orientation + +Initial orientation from GNSS driver. + +- [autoware_sensing_msgs/GnssInsOrientationStamped](https://github.com/autowarefoundation/autoware_msgs/blob/main/autoware_sensing_msgs/msg/GnssInsOrientationStamped.msg) + +### GNSS Velocity + +Initial velocity from GNSS driver. + +- [geometry_msgs/TwistWithCovarianceStamped](https://github.com/ros2/common_interfaces/blob/rolling/geometry_msgs/msg/TwistWithCovarianceStamped.msg) + +### GNSS Acceleration + +Initial acceleration from GNSS driver. + +- [geometry_msgs/AccelWithCovarianceStamped](https://github.com/ros2/common_interfaces/blob/rolling/geometry_msgs/msg/AccelWithCovarianceStamped.msg) + +## Output + +### Ultrasonics + +Distance data from ultrasonic radar. Used by the Perception. + +- [sensor_msgs/Range](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Range.msg) + +### Camera Image + +Image data from camera. Used by the Perception. + +- [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Image.msg) + +### Combined Radar Tracks + +Radar tracks from radar. Used by the Perception. + +- [radar_msgs/RadarTracks.msg](https://github.com/ros-perception/radar_msgs/blob/ros2/msg/RadarTracks.msg) + +### Radar Point Cloud + +Pointcloud from radar. Used by the Perception. + +- [radar_msgs/RadarScan.msg](https://github.com/ros-perception/radar_msgs/blob/ros2/msg/RadarScan.msg) + +### Combined Lidar Point Cloud + +Lidar pointcloud after preprocessing. Used by the Perception and Localization. + +- [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/PointCloud2.msg) + +### GNSS-INS pose + +Initial pose of the ego vehicle from GNSS. Used by the Localization. + +- [geometry_msgs/PoseWithCovarianceStamped](https://github.com/ros2/common_interfaces/blob/rolling/geometry_msgs/msg/PoseWithCovarianceStamped.msg) + +### GNSS-INS Orientation + +Orientation info from GNSS. Used by the Localization. + +- [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Imu.msg) + +### GNSS velocity + +Velocity of the ego vehicle from GNSS. Used by the Localization. + +- [geometry_msgs/TwistWithCovarianceStamped](https://github.com/ros2/common_interfaces/blob/rolling/geometry_msgs/msg/TwistWithCovarianceStamped.msg) + +### GNSS Acceleration + +Acceleration of the ego vehicle from GNSS. Used by the Localization. + +- [geometry_msgs/AccelWithCovarianceStamped](https://github.com/ros2/common_interfaces/blob/rolling/geometry_msgs/msg/AccelWithCovarianceStamped.msg) diff --git a/docs/design/autoware-interfaces/components/vehicle-dimensions.md b/docs/design/autoware-interfaces/components/vehicle-dimensions.md index 70677c6a300..8fca5ae1436 100644 --- a/docs/design/autoware-interfaces/components/vehicle-dimensions.md +++ b/docs/design/autoware-interfaces/components/vehicle-dimensions.md @@ -80,4 +80,6 @@ Autoware assumes the rear wheels don't turn on `z` axis. ## Notice + + The vehicle used in the illustrations was created by xvlblo22 and is from . diff --git a/docs/design/autoware-interfaces/index.md b/docs/design/autoware-interfaces/index.md index 370f46effc2..43804657bbc 100644 --- a/docs/design/autoware-interfaces/index.md +++ b/docs/design/autoware-interfaces/index.md @@ -145,7 +145,6 @@ 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. -Assign unique values to all constants so that it can be distinguished from other enumerations. Do not use enumeration values directly, as assignments are subject to change when the version is updated. ### Time stamp @@ -162,7 +161,7 @@ Currently, there is no required header. 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_ad_api_msgs/msg/ResponseStatus](https://github.com/autowarefoundation/autoware.universe/blob/main/common/autoware_ad_api_msgs/README.md#responsestatus) for details. +See [autoware_adapi_v1_msgs/msg/ResponseStatus](https://github.com/autowarefoundation/autoware_adapi_msgs/tree/main/autoware_adapi_v1_msgs#responsestatus) for details. ## Concerns, assumptions and limitations diff --git a/docs/design/autoware-interfaces/templates/autoware-data-type.jinja2 b/docs/design/autoware-interfaces/templates/autoware-data-type.jinja2 new file mode 100644 index 00000000000..3acf494d8e1 --- /dev/null +++ b/docs/design/autoware-interfaces/templates/autoware-data-type.jinja2 @@ -0,0 +1,26 @@ +# {{ title }} + +## Definition + +{%- block definition %} +{%- endblock %} + +## This type uses + +{%- if uses %} +{%- for name in uses %} +- {{ create_relative_link(name, 'design/autoware-interfaces/ad-api/types/' + name) }} +{%- endfor %} +{%- else %} +- None +{%- endif %} + +## This type is used by + +{%- if used %} +{%- for name in used %} +- {{ create_relative_link(name, 'design/autoware-interfaces/ad-api/types/' + name) }} +{%- endfor %} +{%- else %} +- None +{%- endif %} diff --git a/docs/design/autoware-interfaces/templates/autoware-interface.jinja2 b/docs/design/autoware-interfaces/templates/autoware-interface.jinja2 new file mode 100644 index 00000000000..f57daa463d5 --- /dev/null +++ b/docs/design/autoware-interfaces/templates/autoware-interface.jinja2 @@ -0,0 +1,49 @@ +# {{ title }} + +## Status + +- Latest Version: {{ status }} +- Method: {{ method }} +- Data Type: {{ create_relative_link(type.name, 'design/autoware-interfaces/ad-api/types/' + type.name) }} + +## Description + +{%- block description %} +{%- endblock %} + +{%- if method != 'function call' %} +## Message +{%- if type.msg %} +| Name | Type | Description | +| ---- | ---- | ----------- | +{%- for field in type.msg %} +| {{ field.name }} | {{ resolve_msg_field(type.name, field.name, 'msg') }} | {{ field.text }} | +{%- endfor %} +{%- else %} +None +{%- endif %} +{%- endif %} + +{%- if method == 'function call' %} +## Request +{%- if type.req %} +| Name | Type | Description | +| ---- | ---- | ----------- | +{%- for field in type.req %} +| {{ field.name }} | {{ resolve_msg_field(type.name, field.name, 'req') }} | {{ field.text }} | +{%- endfor %} +{%- else %} +None +{%- endif %} + +## Response +{%- if type.res %} +| Name | Type | Description | +| ---- | ---- | ----------- | +{%- for field in type.res %} +| {{ field.name }} | {{ resolve_msg_field(type.name, field.name, 'res') }} | {{ field.text }} | +{%- endfor %} +{%- else %} +None +{%- endif %} +{%- endif %} diff --git a/docs/how-to-guides/.pages b/docs/how-to-guides/.pages index 6e29a73869a..e4f75c009f9 100644 --- a/docs/how-to-guides/.pages +++ b/docs/how-to-guides/.pages @@ -1,9 +1,4 @@ nav: - index.md - - advanced-usage-of-colcon.md - - creating-maps-for-autoware.md - - determining-component-dependencies.md - - integrating-autoware-with-your-vehicle.md - - integrating-autoware-with-a-diff-drive-vehicle.md - - running-autoware-without-cuda.md - - calibrating-your-sensors.md + - Integrating Autoware: integrating-autoware + - others diff --git a/docs/how-to-guides/creating-maps-for-autoware.md b/docs/how-to-guides/creating-maps-for-autoware.md deleted file mode 100644 index 2dd313c55b7..00000000000 --- a/docs/how-to-guides/creating-maps-for-autoware.md +++ /dev/null @@ -1,80 +0,0 @@ -# Creating maps for Autoware - -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. - -The specifications for point cloud and vector maps required by Autoware are given below, along with examples of both open-source and proprietary software that you can use to create them. - -## Point cloud maps - -A 3D point cloud map is primarily used for LiDAR-based localization 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. - -### Point cloud map specifications - -- It must cover the entire operational area of the vehicle and should include an additional buffer zone of at least 200 m in all directions. -- It must be saved using the [PCD (Point Cloud Data) file format](https://pointclouds.org/documentation/tutorials/pcd_file_format.html), 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. -- Its file size must be smaller than 1 GB, [as per the current ROS message size limit](https://github.com/ros/ros_comm/issues/902). -- 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 supported by Autoware, including [Military Grid Reference System (MGRS)](https://en.wikipedia.org/wiki/Military_Grid_Reference_System), [Universal Transverse Mercator (UTM)](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system), and [Japan Rectangular Coordinate System](https://ja.wikipedia.org/wiki/%E5%B9%B3%E9%9D%A2%E7%9B%B4%E8%A7%92%E5%BA%A7%E6%A8%99%E7%B3%BB). - 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. - -### Creating a point cloud map - -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. - -Commonly used open-source SLAM implementations are [lidarslam-ros2](https://github.com/rsasaki0109/lidarslam_ros2) (LiDAR, IMU\*) and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM/tree/ros2) (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](https://github.com/koide3/hdl_graph_slam) (LiDAR, IMU\*, GNSS\*), [LeGO-LOAM](https://github.com/facontidavide/LeGO-LOAM-BOR) (LiDAR, IMU\*), [LeGO-LOAM-BOR](https://github.com/RobustFieldAutonomyLab/LeGO-LOAM) (LiDAR), and [LIO-SAM](https://github.com/TixiaoShan/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](https://github.com/SMRT-AIST/interactive_slam) to adjust and optimize a pose graph manually. - -Since Autoware is based on ROS 2, it could be problematic if you want to install ROS 1-based SLAM implementations on the same machine. To avoid this problem, you can use [Docker](https://www.docker.com/) or simply install them on a different machine. Another problem is the ROSBAG version; these SLAM implementations require ROSBAG 1 instead of ROSBAG 2 used by Autoware. For the ROSBAG version problem, you may use this [stand-alone converter](https://gitlab.com/MapIV/rosbags) to convert a ROSBAG 2 file to a ROSBAG 1 file and vice versa. - -If you prefer proprietary software that is easy to use, you can try a fully automatic mapping tool from [MAP IV, Inc.](https://www.map4.jp/), [_MapIV Engine_](https://www.map4.jp/map4_engine_en). They currently provide a trial license for Autoware users free of charge. - -## Vector maps - -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. - -### Vector map specifications - -- It must cover the entire operational area of the vehicle and should include an additional buffer zone of at least 200 m in all directions. -- It must be in [Lanelet2](https://github.com/fzi-forschungszentrum-informatik/Lanelet2) format, with [additional modifications required by Autoware](https://github.com/autowarefoundation/autoware_common/blob/main/tmp/lanelet2_extension/docs/lanelet2_format_extension.md). -- It must contain the shape and position information of lanes, traffic lights, stop lines, crosswalks, parking spaces, and parking lots. -- Each lanelet in the map must contain information regarding its right of way, speed limit, traffic direction, associated traffic lights, stop lines, and traffic signs. -- 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. - -### Creating a vector map - -The easiest way to create an Autoware-compatible vector map is to use [Vector Map Builder](https://tools.tier4.jp/feature/vector_map_builder_ll2/), a free web-based tool provided by [TIER IV, Inc.](https://www.tier4.jp/). -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](https://github.com/autocore-ai/MapToolbox) is a plugin for [Unity](https://unity.com/) specifically designed to create Lanelet2 maps for Autoware. -Although [JOSM](https://josm.openstreetmap.de/) 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. - -## Autoware-compatible map providers - -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.](https://www.map4.jp/) -- [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) -- [TomTom](https://www.tomtom.com/) - -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.](https://www.map4.jp/) | SLAM | Point cloud and vector maps | -| [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) | MMS | Point cloud and vector maps | -| [TomTom](https://www.tomtom.com/) | MMS | Vector map\* | - -!!! note - - Maps provided by TomTom use their proprietary AutoStream format, not Lanelet2. - The open-source [AutoStreamForAutoware tool](https://github.com/tomtom-international/AutoStreamForAutoware) 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](https://github.com/tomtom-international/AutoStreamForAutoware/blob/main/docs/known-issues.md). diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 8f15e28ed72..dc05cd725cb 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -1,16 +1,22 @@ # How-to guides -- [Advanced usage of colcon](advanced-usage-of-colcon.md) -- [Creating maps for Autoware](creating-maps-for-autoware.md) -- [Determining component dependencies](determining-component-dependencies.md) -- [Integrating Autoware with your vehicle](integrating-autoware-with-your-vehicle.md) -- [Integrating Autoware with a differential drive vehicle](integrating-autoware-with-a-diff-drive-vehicle.md) -- [Running Autoware without CUDA](running-autoware-without-cuda.md) -- [Calibrating your sensors](calibrating-your-sensors.md) +## Integrating Autoware + +- [Overview](integrating-autoware/overview.md) + +## Others + +- [Debug Autoware](others/debug-autoware.md) +- [Running Autoware without CUDA](others/running-autoware-without-cuda.md) +- [Fixing dependent package versions](others/fixing-dependent-package-versions.md) +- [Add a custom ROS message](others/add-a-custom-ros-message.md) +- [Determining component dependencies](others/determining-component-dependencies.md) +- [Advanced usage of colcon](others/advanced-usage-of-colcon.md) +- [Applying Clang-Tidy to ROS packages](others/applying-clang-tidy-to-ros-packages.md) +- [Defining temporal performance metrics on components](others/defining-temporal-performance-metrics.md) +- [An example procedure for adding and evaluating a new node](others/an-example-procedure-for-adding-and-evaluating-a-new-node.md) TODO: Write the following contents. - Create an Autoware package -- Add a custom ROS message -- Debug Autoware - etc. diff --git a/docs/how-to-guides/integrating-autoware/.pages b/docs/how-to-guides/integrating-autoware/.pages new file mode 100644 index 00000000000..29eb42aa464 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/.pages @@ -0,0 +1,8 @@ +nav: + - overview.md + - 1. Creating your Autoware meta repository: creating-your-autoware-meta-repository + - 2. Creating vehicle and sensor description: creating-vehicle-and-sensor-description + - 3. Creating vehicle interface: creating-vehicle-interface-package + - 4. Creating maps: creating-maps + - 5. Launch Autoware: launch-autoware + - 6. Tuning parameters and performance: tuning-parameters-and-performance diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/.pages new file mode 100644 index 00000000000..f38a00ca8fc --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/.pages @@ -0,0 +1,3 @@ +nav: + - index.md + - Open-source SLAM algorithms: open-source-slam diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/index.md new file mode 100644 index 00000000000..2421c2a8662 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/index.md @@ -0,0 +1,41 @@ +# Creating maps + +Autoware requires a pointcloud map and a vector map for the vehicle's operating environment. (Check the [map design documentation page](../../../design/autoware-architecture/map/index.md) for the detailed specification). + +This page explains how users can create maps that can be used for Autoware. + +## Creating a point cloud map + +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](open-source-slam/index.md). + +If you prefer proprietary software that is easy to use, you can try a fully automatic mapping tool from [MAP IV, Inc.](https://www.map4.jp/), [_MapIV Engine_](https://www.map4.jp/solutions/mapping_localization/map4engine/). They currently provide a trial license for Autoware users free of charge. + +## Creating a vector map + +The easiest way to create an Autoware-compatible vector map is to use [Vector Map Builder](https://tools.tier4.jp/feature/vector_map_builder_ll2/), a free web-based tool provided by [TIER IV, Inc.](https://www.tier4.jp/). +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](https://github.com/autocore-ai/MapToolbox) is a plugin for [Unity](https://unity.com/) specifically designed to create Lanelet2 maps for Autoware. +Although [JOSM](https://josm.openstreetmap.de/) 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. + +## Autoware-compatible map providers + +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.](https://www.map4.jp/) +- [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) +- [TomTom](https://www.tomtom.com/) + +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.](https://www.map4.jp/) | SLAM | Point cloud and vector maps | +| [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) | MMS | Point cloud and vector maps | +| [TomTom](https://www.tomtom.com/) | MMS | Vector map\* | + +!!! note + + Maps provided by TomTom use their proprietary AutoStream format, not Lanelet2. + The open-source [AutoStreamForAutoware tool](https://github.com/tomtom-international/AutoStreamForAutoware) 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](https://github.com/tomtom-international/AutoStreamForAutoware/blob/main/docs/known-issues.md). diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/.pages new file mode 100644 index 00000000000..0303bafdb65 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/.pages @@ -0,0 +1,13 @@ +nav: + - index.md + - FAST-LIO-LC: fast-lio-lc + - FAST_LIO_SLAM: fast-lio-slam + - FD-SLAM: fd-slam + - hdl_graph_slam: hdl-graph-slam + - IA_LIO_SAM: ia-lio-slam + - iscloam: iscloam + - LeGO-LOAM-BOR: lego-loam-bor + - LIO-SAM: lio-sam + - Optimized-SC-F-LOAM: optimized-sc-f-loam + - SC-A-LOAM: sc-a-loam + - SC-LeGO-LOAM: sc-lego-loam diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/config_info.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/config_info.png new file mode 100644 index 00000000000..ff8858d7889 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/config_info.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/extrinsic.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/extrinsic.png new file mode 100644 index 00000000000..e8d56e11374 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/extrinsic.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-example1.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-example1.png new file mode 100644 index 00000000000..e92c7ff4177 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-example1.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-example2.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-example2.png new file mode 100644 index 00000000000..f1498c62577 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-example2.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-output.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-output.png new file mode 100644 index 00000000000..5099477fde6 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-output.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/launch.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/launch.png new file mode 100644 index 00000000000..c35c1259d8a Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/launch.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/index.md new file mode 100644 index 00000000000..fee8f784d83 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/index.md @@ -0,0 +1,109 @@ +# FAST_LIO_LC + +## What is FAST_LIO_LC? + +- A computationally efficient and robust LiDAR-inertial odometry package with loop closure module and graph optimization. + +## Repository Information + +### Original Repository link + +[https://github.com/yanliang-wang/FAST_LIO_LC](https://github.com/yanliang-wang/FAST_LIO_LC) + +### Required Sensors + +- LIDAR [Velodyne, Ouster, Livox] +- IMU [6-AXIS, 9-AXIS] +- GPS [Optional] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- Ubuntu 18.04 +- ROS Melodic +- PCL >= 1.8, Follow [PCL Installation](https://pointclouds.org/downloads/#linux). +- Eigen >= 3.3.4, Follow [Eigen Installation](http://eigen.tuxfamily.org/index.php?title=Main_Page). +- GTSAM >= 4.0.0, Follow [GTSAM Installation](https://gtsam.org/get_started). + +```bash + wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip + cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/ + cd ~/Downloads/gtsam-4.0.0-alpha2/ + mkdir build && cd build + cmake .. + sudo make install +``` + +## Build & Run + +### 1) Build + +```bash + mkdir -p ~/ws_fastlio_lc/src + cd ~/ws_fastlio_lc/src + git clone https://github.com/gisbi-kim/FAST_LIO_SLAM.git + git clone https://github.com/Livox-SDK/livox_ros_driver + cd .. + catkin_make +``` + +### 2) Set parameters + + + +- 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. + +

Extrinsic Matrices

+ +- 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`). + +### 3) Run + + + +- For Ouster OS1-64 + + # open new terminal: run FAST-LIO + roslaunch fast_lio mapping_ouster64.launch + + # open the other terminal tab: run SC-PGO + roslaunch aloam_velodyne fastlio_ouster64.launch + + # play bag file in the other terminal + rosbag play RECORDED_BAG.bag --clock + +

launch

+ +## Example Result + +

example_results1

+

example_results2

+ +## Other Examples + +

example_results

+ +## Example dataset + +Check original repository link for example dataset. + +## Contact + + + +- Maintainer: Yanliang Wang (`wyl410922@qq.com`) + +## Acknowledgements + +- Thanks for [FAST_LIO](https://github.com/hku-mars/FAST_LIO) authors. + + diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/fast_lio_slam.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/fast_lio_slam.png new file mode 100644 index 00000000000..4819ebb1d74 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/fast_lio_slam.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/kaist03.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/kaist03.png new file mode 100644 index 00000000000..1e121946b71 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/kaist03.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/riverside02.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/riverside02.png new file mode 100644 index 00000000000..2b781cdf579 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/riverside02.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/topic_name.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/topic_name.png new file mode 100644 index 00000000000..79f9c977631 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/topic_name.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/video.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/video.png new file mode 100644 index 00000000000..9ed550d31b2 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/video.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/index.md new file mode 100644 index 00000000000..d9f3d919eb3 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/index.md @@ -0,0 +1,99 @@ +# FAST_LIO_SLAM + +## What is 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. + +## Repository Information + +### Original Repository link + +[https://github.com/gisbi-kim/FAST_LIO_SLAM](https://github.com/gisbi-kim/FAST_LIO_SLAM) + +### Required Sensors + +- LIDAR [Livox, Velodyne, Ouster] +- IMU [6-AXIS, 9-AXIS] +- GPS [OPTIONAL] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- ROS +- PCL +- GTSAM + +```bash +wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip +cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/ +cd ~/Downloads/gtsam-4.0.0-alpha2/ +mkdir build && cd build +cmake .. +sudo make install +``` + +- PCL >= 1.8, Follow [PCL Installation](https://pointclouds.org/downloads/#linux). +- Eigen >= 3.3.4, Follow [Eigen Installation](http://eigen.tuxfamily.org/index.php?title=Main_Page). + +## Build & Run + +### 1) Build + +```bash + mkdir -p ~/catkin_fastlio_slam/src + cd ~/catkin_fastlio_slam/src + git clone https://github.com/gisbi-kim/FAST_LIO_SLAM.git + git clone https://github.com/Livox-SDK/livox_ros_driver + cd .. + catkin_make + source devel/setup.bash +``` + +### 2) Set parameters + +- Set imu and lidar topic on `Fast_LIO/config/ouster64.yaml` + +### 3) Run + +```bash + # terminal 1: run FAST-LIO2 + roslaunch fast_lio mapping_ouster64.launch + + # open the other terminal tab: run SC-PGO + cd ~/catkin_fastlio_slam + source devel/setup.bash + roslaunch aloam_velodyne fastlio_ouster64.launch + + # play bag file in the other terminal + rosbag play xxx.bag -- clock --pause +``` + +## Example Result + +

+ +

+ +## Other Examples + +- [Tutorial video 1](https://youtu.be/nu8j4yaBMnw) (using KAIST 03 sequence of [MulRan dataset](https://sites.google.com/view/mulran-pr/dataset)) + + - Example result captures +

+ - [download the KAIST 03 pcd map](https://www.dropbox.com/s/w599ozdg7h6215q/KAIST03.pcd?dl=0) made by FAST-LIO-SLAM, 500MB + +- [Example Video 2](https://youtu.be/94mC05PesvQ) (Riverside 02 sequence of [MulRan dataset](https://sites.google.com/view/mulran-pr/dataset)) + - Example result captures +

+ - [download the Riverside 02 pcd map](https://www.dropbox.com/s/1aolth7ry4odxo4/Riverside02.pcd?dl=0) made by FAST-LIO-SLAM, 400MB + +## Acknowledgements + + + +- Thanks for [FAST_LIO](https://github.com/hku-mars/FAST_LIO) authors. +- You may have an interest in [this version of FAST-LIO + Loop closure](https://github.com/yanliang-wang/FAST_LIO_LC), implemented by [yanliang-wang](https://github.com/yanliang-wang) +- Maintainer: Giseop Kim (`paulgkim@kaist.ac.kr`) diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/index.md new file mode 100644 index 00000000000..37137e7483b --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/index.md @@ -0,0 +1,74 @@ +# FD-SLAM + +## What is 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. + +## Repository Information + +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. + +### Original Repository link + +[https://github.com/SLAMWang/FD-SLAM](https://github.com/SLAMWang/FD-SLAM) + +### Required Sensors + +- LIDAR[VLP-16, HDL-32, HDL-64, OS1-64] +- GPS +- IMU [Optional] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- [ROS](http://wiki.ros.org/noetic/Installation/Ubuntu) +- [PCL](https://pointclouds.org/downloads/#linux) +- [g2o](http://wiki.ros.org/g2o) +- [Suitesparse](https://github.com/ethz-asl/suitesparse) + +The following ROS packages are required: + +- geodesy +- nmea_msgs +- pcl_ros +- [ndt_omp](https://github.com/koide3/ndt_omp) +- [U_gicp](https://github.com/SLAMWang/UGICP) This is modified based on [fast_gicp](https://github.com/SMRT-AIST/fast_gicp) by us. We use UGICP for keyframe matching. + +## Build & Run + +### 1) Build + +```bash +cd ~/catkin_ws/src +git clone https://github.com/SLAMWang/FD-SLAM.git +cd .. +catkin_make +``` + +### 2) Services + +```bash +/hdl_graph_slam/dump (hdl_graph_slam/DumpGraph) + - save all the internal data (point clouds, floor coeffs, odoms, and pose graph) to a directory. + +/hdl_graph_slam/save_map (hdl_graph_slam/SaveMap) + - save the generated map as a PCD file. +``` + +### 3) Set parameters + +- All the configurable parameters are listed in _launch/\*\*\*\*.launch_ as ros params. + +### 4) Run + +```bash +source devel/setup.bash +roslaunch hdl_graph_slam hdl_graph_slam_400_ours.launch +``` diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_1.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_1.png new file mode 100644 index 00000000000..5b0f2956466 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_1.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_2.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_2.png new file mode 100644 index 00000000000..e94d37a2fc6 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_2.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_graph.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_graph.png new file mode 100644 index 00000000000..14f5840b5c7 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_graph.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_points.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_points.png new file mode 100644 index 00000000000..3d08a199169 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_points.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_graph_slam.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_graph_slam.png new file mode 100644 index 00000000000..04c226c9093 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_graph_slam.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/lidar_topic.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/lidar_topic.png new file mode 100644 index 00000000000..1e462784f26 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/lidar_topic.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/reg_params.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/reg_params.png new file mode 100644 index 00000000000..c7be8176f6f Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/reg_params.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/index.md new file mode 100644 index 00000000000..bf294c93a2f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/index.md @@ -0,0 +1,133 @@ +# hdl_graph_slam + +## What is 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). + +## Repository Information + +### Original Repository link + +[https://github.com/koide3/hdl_graph_slam](https://github.com/koide3/hdl_graph_slam) + +### Required Sensors + +- LIDAR [Velodyne, Ouster, RoboSense] +- IMU [6-AXIS, 9-AXIS] [OPTIONAL] +- GPS [OPTIONAL] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- ROS +- PCL +- g2o +- OpenMP + +The following ROS packages are required: + +- geodesy +- nmea_msgs +- pcl_ros +- [ndt_omp](https://github.com/koide3/ndt_omp) +- [fast_gicp](https://github.com/SMRT-AIST/fast_gicp) + +## Build & Run + +### 1) Build + +```bash +# for melodic +sudo apt-get install ros-melodic-geodesy ros-melodic-pcl-ros ros-melodic-nmea-msgs ros-melodic-libg2o +cd catkin_ws/src +git clone https://github.com/koide3/ndt_omp.git -b melodic +git clone https://github.com/SMRT-AIST/fast_gicp.git --recursive +git clone https://github.com/koide3/hdl_graph_slam + +cd .. && catkin_make -DCMAKE_BUILD_TYPE=Release + +# for noetic +sudo apt-get install ros-noetic-geodesy ros-noetic-pcl-ros ros-noetic-nmea-msgs ros-noetic-libg2o + +cd catkin_ws/src +git clone https://github.com/koide3/ndt_omp.git +git clone https://github.com/SMRT-AIST/fast_gicp.git --recursive +git clone https://github.com/koide3/hdl_graph_slam + +cd .. && catkin_make -DCMAKE_BUILD_TYPE=Release +``` + +### 2) Set parameter + +- Set lidar topic on `launch/hdl_graph_slam_400.launch` + + + +- Set registration settings on `launch/hdl_graph_slam_400.launch` + + + +### 3) Run + +```bash +rosparam set use_sim_time true +roslaunch hdl_graph_slam hdl_graph_slam_400.launch +``` + +```bash +roscd hdl_graph_slam/rviz +rviz -d hdl_graph_slam.rviz +``` + +```bash +rosbag play --clock hdl_400.bag +``` + +Save the generated map by: + +```bash +rosservice call /hdl_graph_slam/save_map "resolution: 0.05 +destination: '/full_path_directory/map.pcd'" +``` + +## Example Result + + + +## Example2 (Outdoor) + +Bag file (recorded in an outdoor environment): + +- [hdl_400.bag.tar.gz](http://www.aisl.cs.tut.ac.jp/databases/hdl_graph_slam/hdl_400.bag.tar.gz) (raw data, about 900MB) + +```bash +rosparam set use_sim_time true +roslaunch hdl_graph_slam hdl_graph_slam_400.launch +``` + +```bash +roscd hdl_graph_slam/rviz +rviz -d hdl_graph_slam.rviz +``` + +```bash +rosbag play --clock dataset.bag +``` + + + + + +## Papers + +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]](https://www.researchgate.net/publication/331283709_A_portable_three-dimensional_LIDAR-based_system_for_long-term_and_wide-area_people_behavior_measurement). + +## Contact + +Kenji Koide, k.koide@aist.go.jp, [https://staff.aist.go.jp/k.koide](https://staff.aist.go.jp/k.koide) + +[[Active Intelligent Systems Laboratory, Toyohashi University of Technology, Japan]](http://www.aisl.cs.tut.ac.jp) +[[Mobile Robotics Research Team, National Institute of Advanced Industrial Science and Technology (AIST), Japan]](https://unit.aist.go.jp/hcmrc/mr-rt/contact.html) diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data.png new file mode 100644 index 00000000000..b46e049cb34 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data_lio_ai_lio.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data_lio_ai_lio.png new file mode 100644 index 00000000000..070fdf0187b Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data_lio_ai_lio.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Seq2.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Seq2.png new file mode 100644 index 00000000000..de52927fb37 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Seq2.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/config_info.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/config_info.png new file mode 100644 index 00000000000..eccb3881dec Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/config_info.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/extrinsic.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/extrinsic.png new file mode 100644 index 00000000000..e8d56e11374 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/extrinsic.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example1.gif b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example1.gif new file mode 100644 index 00000000000..b5adc4fb721 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example1.gif differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example2.gif b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example2.gif new file mode 100644 index 00000000000..84fb317629c Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example2.gif differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/index.md new file mode 100644 index 00000000000..626a46db732 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/index.md @@ -0,0 +1,124 @@ +# IA-LIO-SAM + +## What is 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. + +## Repository Information + +### Original Repository link + +[https://github.com/minwoo0611/IA_LIO_SAM](https://github.com/minwoo0611/IA_LIO_SAM) + +### Required Sensors + +- LIDAR [Velodyne, Ouster] +- IMU [9-AXIS] +- GNSS + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- [ROS](http://wiki.ros.org/ROS/Installation) (tested with Kinetic and Melodic) + + - `for ROS melodic:` + + ```bash + sudo apt-get install -y ros-melodic-navigation + sudo apt-get install -y ros-melodic-robot-localization + sudo apt-get install -y ros-melodic-robot-state-publisher + ``` + + - `for ROS kinetic:` + + ```bash + sudo apt-get install -y ros-kinetic-navigation + sudo apt-get install -y ros-kinetic-robot-localization + sudo apt-get install -y ros-kinetic-robot-state-publisher + ``` + +- [GTSAM](https://github.com/borglab/gtsam/releases) (Georgia Tech Smoothing and Mapping library) + + ```bash + wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.2.zip + cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/ + cd ~/Downloads/gtsam-4.0.2/ + mkdir build && cd build + cmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF .. + sudo make install -j8 + ``` + +## Build & Run + +### 1) Build + +```bash + mkdir -p ~/catkin_ia_lio/src + cd ~/catkin_ia_lio/src + git clone https://github.com/minwoo0611/IA_LIO_SAM + cd .. + catkin_make +``` + +### 2) Set parameters + +- 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. + +

Extrinsic Matrices

+ +- To enable autosave, `savePCD` must be `true` on the `params.yaml` file (`workspace/src/IA_LIO_SAM/config/params.yaml`). + +### 3) Run + + # open new terminal: run IA_LIO + source devel/setup.bash + roslaunch lio_sam mapping_ouster64.launch + + # play bag file in the other terminal + rosbag play RECORDED_BAG.bag --clock + +## Sample dataset images + +

+ drawing + drawing + drawing +

+ +## Example dataset + +Check original repo link for example dataset. + +## Contact + + + +- Maintainer: Kevin Jung (`GitHub: minwoo0611`) + +## Paper + +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)](https://github.com/TixiaoShan/LIO-SAM). + +```bash +@inproceedings{legoloam2018shan, + title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain}, + author={Shan, Tixiao and Englot, Brendan}, + booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}, + pages={4758-4765}, + year={2018}, + organization={IEEE} +} +``` + +## Acknowledgements + + + +- 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). diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/index.md new file mode 100644 index 00000000000..1c4a8a5bf78 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/index.md @@ -0,0 +1,36 @@ +# Available Open Source SLAM + +This page provides the list of available open source Simultaneous Localization And Mapping (SLAM) implementation that can be used to generate a point cloud (.pcd) map file. + +## Selecting which implementation to use + +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. + +## Tips + +Commonly used open-source SLAM implementations are [lidarslam-ros2](https://github.com/rsasaki0109/lidarslam_ros2) (LiDAR, IMU\*) and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM/tree/ros2) (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](https://github.com/koide3/hdl_graph_slam) (LiDAR, IMU\*, GNSS\*), [LeGO-LOAM](https://github.com/facontidavide/LeGO-LOAM-BOR) (LiDAR, IMU\*), [LeGO-LOAM-BOR](https://github.com/RobustFieldAutonomyLab/LeGO-LOAM) (LiDAR), and [LIO-SAM](https://github.com/TixiaoShan/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](https://github.com/SMRT-AIST/interactive_slam) to adjust and optimize a pose graph manually. + +## List of Third Party SLAM Implementations + + + +
+
+ +| 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](https://github.com/yanliang-wang/FAST_LIO_LC) | ✓ | Lidar
IMU
GPS [Optional] | ROS 1 | ROS Melodic
PCL >= 1.8
Eigen >= 3.3.4
GTSAM >= 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](https://github.com/gisbi-kim/FAST_LIO_SLAM) | ✓ | Lidar
IMU
GPS [Optional] | ROS 1 | PCL >= 1.8
Eigen >= 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](https://github.com/SLAMWang/FD-SLAM) | ✓ | Lidar
IMU [Optional]
GPS | ROS 1 | PCL
g2o
Suitesparse | +| 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](https://github.com/koide3/hdl_graph_slam) | ✓ | Lidar
IMU [Optional]
GPS [Optional] | ROS 1 | PCL
g2o
OpenMP | +| 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](https://github.com/minwoo0611/IA_LIO_SAM) | ✓ | Lidar
IMU
GPS | ROS 1 | GTSAM | +| ISCLOAM | ISCLOAM presents a robust loop closure detection approach by integrating both geometry and intensity information | [https://github.com/wh200720041/iscloam](https://github.com/wh200720041/iscloam) | ✓ | Lidar | ROS 1 | Ubuntu 18.04
ROS Melodic
Ceres
PCL
GTSAM
OpenCV | +| 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](https://github.com/facontidavide/LeGO-LOAM-BOR) | ✓ | Lidar
IMU | ROS 1 | ROS Melodic
PCL
GTSAM | +| 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](https://github.com/TixiaoShan/LIO-SAM) | ✓ | Lidar
IMU
GPS [Optional] | ROS 1
ROS 2 | PCL
GTSAM | +| 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](https://github.com/SlamCabbage/Optimized-SC-F-LOAM) | ✓ | Lidar | ROS 1 | PCL
GTSAM
Ceres | +| SC-A-LOAM | A real-time LiDAR SLAM package that integrates A-LOAM and ScanContext. | [https://github.com/gisbi-kim/SC-A-LOAM](https://github.com/gisbi-kim/SC-A-LOAM) | ✓ | Lidar | ROS 1 | 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](https://github.com/irapkaist/SC-LeGO-LOAM) | ✓ | Lidar
IMU | ROS 1 | PCL
GTSAM | diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/00.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/00.png new file mode 100644 index 00000000000..e7906d3538a Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/00.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/05.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/05.png new file mode 100644 index 00000000000..490fe9bf471 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/05.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/bag_name.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/bag_name.png new file mode 100644 index 00000000000..a9af9ec13db Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/bag_name.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/index.md new file mode 100644 index 00000000000..6274ebf87ab --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/index.md @@ -0,0 +1,107 @@ + + +# ISCLOAM + +## What is ISCLOAM? + +- ISCLOAM presents a robust loop closure detection approach by integrating both geometry and intensity information. + +## Repository Information + +### Original Repository link + +[https://github.com/wh200720041/iscloam](https://github.com/wh200720041/iscloam) + +### Required Sensors + +- LIDAR [Velodyne] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- Ubuntu 64-bit 18.04 +- ROS Melodic [ROS Installation](http://wiki.ros.org/ROS/Installation) +- Ceres Solver [Ceres Installation](http://ceres-solver.org/installation.html) +- PCL [PCL Installation](https://pointclouds.org/downloads/) +- Gtsam [GTSAM Installation](https://gtsam.org/get_started/) +- OpenCV [OPENCV Installation](https://opencv.org/releases/) +- Trajectory visualization + +For visualization purpose, this package uses hector trajectory sever, you may install the package by + +```bash +sudo apt-get install ros-melodic-hector-trajectory-server +``` + +## Build and Run + +### 1. Clone repository + +```bash +cd ~/catkin_ws/src +git clone https://github.com/wh200720041/iscloam.git +cd .. +catkin_make -j1 +source ~/catkin_ws/devel/setup.bash +``` + +### 2. Set Parameter + +Change the bag location and sensor parameters on launch files. + +

+ +### 3. Launch + +```bash +roslaunch iscloam iscloam.launch +``` + +if you would like to generate the map of environment at the same time, you can run + +```bash +roslaunch iscloam iscloam_mapping.launch +``` + +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. + +## Example Result + +Watch demo video at [Video Link](https://youtu.be/Kfi6CFK4Ke4) + +### Ground Truth Comparison + +Green: ISCLOAM Red: Ground Truth + +

+ + +

+ + KITTI sequence 00 KITTI sequence 05 + +## Citation + +If you use this work for your research, you may want to cite the paper below, your citation will be appreciated + +```bash +@inproceedings{wang2020intensity, + author={H. {Wang} and C. {Wang} and L. {Xie}}, + booktitle={2020 IEEE International Conference on Robotics and Automation (ICRA)}, + title={Intensity Scan Context: Coding Intensity and Geometry Relations for Loop Closure Detection}, + year={2020}, + volume={}, + number={}, + pages={2095-2101}, + doi={10.1109/ICRA40945.2020.9196764} +} +``` + +## Acknowledgements + +Thanks for [A-LOAM](https://github.com/HKUST-Aerial-Robotics/A-LOAM) and LOAM(J. Zhang and S. Singh. LOAM: Lidar Odometry and Mapping in Real-time) and [LOAM_NOTED](https://github.com/cuitaixiang/LOAM_NOTED). + +**Author:** [Wang Han](http://wanghan.pro), Nanyang Technological University, Singapore diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/block.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/block.png new file mode 100644 index 00000000000..ebefa8aec24 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/block.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/dataset-demo.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/dataset-demo.png new file mode 100644 index 00000000000..9355997d8ab Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/dataset-demo.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/demo.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/demo.png new file mode 100644 index 00000000000..542030c85eb Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/demo.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/google-earth.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/google-earth.png new file mode 100644 index 00000000000..b0e4b66cd43 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/google-earth.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/jackal-label.jpg b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/jackal-label.jpg new file mode 100644 index 00000000000..d020b1b15a0 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/jackal-label.jpg differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/odometry.jpg b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/odometry.jpg new file mode 100644 index 00000000000..41dd23702fa Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/odometry.jpg differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/seg-total.jpg b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/seg-total.jpg new file mode 100644 index 00000000000..eb2bb170331 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/seg-total.jpg differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/index.md new file mode 100644 index 00000000000..e0d51360ab1 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/index.md @@ -0,0 +1,80 @@ +# LeGO-LOAM-BOR + +## What is 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. + +## Repository Information + +### Original Repository link + +[https://github.com/facontidavide/LeGO-LOAM-BOR](https://github.com/facontidavide/LeGO-LOAM-BOR) + +### Required Sensors + +- LIDAR [VLP-16] +- IMU [9-AXIS] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- ROS Melodic [ROS Installation](http://wiki.ros.org/ROS/Installation) +- PCL [PCL Installation](https://pointclouds.org/downloads/) +- Gtsam [GTSAM Installation](https://gtsam.org/get_started/) + +```bash +wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip +cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/ +cd ~/Downloads/gtsam-4.0.0-alpha2/ +mkdir build && cd build +cmake .. +sudo make install +``` + +## Build & Run + +### 1) Build + +```bash +cd ~/catkin_ws/src +git clone https://github.com/facontidavide/LeGO-LOAM-BOR.git +cd .. +catkin_make +``` + +### 2) Set parameters + +- Set parameters on `LeGo-LOAM/loam_config.yaml` + +### 3) Run + +```bash +source devel/setup.bash +roslaunch lego_loam_bor run.launch rosbag:=/path/to/your/rosbag lidar_topic:=/velodyne_points +``` + +## Example Result + +

+ +

+ +

+ +## Cite _LeGO-LOAM_ + +Thank you for citing our _LeGO-LOAM_ paper if you use any of this code: + +```bash +@inproceedings{legoloam2018, + title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain}, + author={Tixiao Shan and Brendan Englot}, + booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}, + pages={4758-4765}, + year={2018}, + organization={IEEE} +} +``` diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/pcd-map.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/pcd-map.png new file mode 100644 index 00000000000..d134d1dbaa6 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/pcd-map.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/system.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/system.png new file mode 100644 index 00000000000..43d1d997862 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/system.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/index.md new file mode 100644 index 00000000000..c8854637498 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/index.md @@ -0,0 +1,104 @@ +# LIO_SAM + +## What is 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 + +## Repository Information + +### Original Repository link + +[https://github.com/TixiaoShan/LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) + +### Required Sensors + +- LIDAR [Livox, Velodyne, Ouster] +- IMU [9-AXIS] +- GPS [OPTIONAL] + +

drawing

+ +### ROS Compatibility + +- ROS 1 +- [For ROS 2](https://github.com/TixiaoShan/LIO-SAM/tree/ros2) + +### Dependencies + +- ROS +- PCL +- [GTSAM](https://gtsam.org/get_started/) (Georgia Tech Smoothing and Mapping library) + + ```bash + sudo add-apt-repository ppa:borglab/gtsam-release-4.0 + sudo apt install libgtsam-dev libgtsam-unstable-dev + ``` + +```bash + sudo apt-get install -y ros-melodic-navigation + sudo apt-get install -y ros-melodic-robot-localization + sudo apt-get install -y ros-melodic-robot-state-publisher +``` + +## Build & Run + +### 1) Build + +```bash + mkdir -p ~/catkin_lio_sam/src + cd ~/catkin_lio_sam/src + git clone https://github.com/TixiaoShan/LIO-SAM.git + cd .. + catkin_make + source devel/setup.bash +``` + +### 2) Set parameters + +- Set topics and sensor settings on `lio_sam/config/params.yaml` + +### 3) Run + +```bash + # Run the Launch File + roslaunch lio_sam run.launch + + # Play bag file in the other terminal + rosbag play xxx.bag --clock +``` + +## Example Result + +

drawing

+ +## Paper + +Thank you for citing LIO-SAM (IROS-2020) if you use any of this code. + +```bash +@inproceedings{liosam2020shan, + title={LIO-SAM: Tightly-coupled Lidar Inertial Odometry via Smoothing and Mapping}, + author={Shan, Tixiao and Englot, Brendan and Meyers, Drew and Wang, Wei and Ratti, Carlo and Rus Daniela}, + booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}, + pages={5135-5142}, + year={2020}, + organization={IEEE} +} +``` + +Part of the code is adapted from [LeGO-LOAM](https://github.com/RobustFieldAutonomyLab/LeGO-LOAM). + +```bash +@inproceedings{legoloam2018shan, + title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain}, + author={Shan, Tixiao and Englot, Brendan}, + booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}, + pages={4758-4765}, + year={2018}, + organization={IEEE} +} +``` + +## Acknowledgements + +- LIO-SAM is based on LOAM (J. Zhang and S. Singh. LOAM: Lidar Odometry and Mapping in Real-time). diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/index.md new file mode 100644 index 00000000000..eb4a0228310 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/index.md @@ -0,0 +1,112 @@ +# Optimized-SC-F-LOAM + +## What is 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. + +## Repository Information + +### Original Repository link + +[https://github.com/SlamCabbage/Optimized-SC-F-LOAM](https://github.com/SlamCabbage/Optimized-SC-F-LOAM) + +### Required Sensors + +- LIDAR [VLP-16, HDL-32, HDL-64] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- [ROS](http://wiki.ros.org/noetic/Installation/Ubuntu) +- [PCL](https://pointclouds.org/downloads/#linux) +- [GTSAM](https://gtsam.org/get_started/) +- [Ceres Solver](http://www.ceres-solver.org/installation.html) +- For visualization purpose, this package uses hector trajectory sever, you may install the package by + +```bash +sudo apt-get install ros-noetic-hector-trajectory-server +``` + +## Build & Run + +### 1) Build + +```bash +cd ~/catkin_ws/src +git clone https://github.com/SlamCabbage/Optimized-SC-F-LOAM.git +cd .. +catkin_make +``` + +### 2) Create message file + +In this folder, Ground Truth information, optimized pose information, F-LOAM pose information and time information are stored + +```bash +mkdir -p ~/message/Scans + +Change line 383 in the laserLoopOptimizationNode.cpp to your own "message" folder path +``` + +(Do not forget to rebuild your package) + +### 3) Set parameters + +- Set LIDAR topic and LIDAR properties on 'sc_f_loam_mapping.launch' + +### 4) Run + +```bash +source devel/setup.bash +roslaunch optimized_sc_f_loam optimized_sc_f_loam_mapping.launch +``` + +## Example Result + +![image](https://user-images.githubusercontent.com/95751923/155124889-934ea649-3b03-4e8d-84af-608753f34c93.png) + +### Results on KITTI Sequence 00 and Sequence 05 + +![image](https://user-images.githubusercontent.com/95751923/155125294-980e6a3d-6e76-4a23-9771-493ba278677e.png) + +### Comparison of trajectories on KITTI dataset + +![image](https://user-images.githubusercontent.com/95751923/155125478-a361762f-f18e-4161-b892-6f5080f5681f.png) + +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](https://github.com/ethz-asl/kitti_to_rosbag) + +## Acknowledgements + +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). + +## Citation + +```bash +@misc{https://doi.org/10.48550/arxiv.2204.04932, + doi = {10.48550/ARXIV.2204.04932}, + + url = {https://arxiv.org/abs/2204.04932}, + + author = {Liao, Lizhou and Fu, Chunyun and Feng, Binbin and Su, Tian}, + + keywords = {Robotics (cs.RO), FOS: Computer and information sciences, FOS: Computer and information sciences}, + + title = {Optimized SC-F-LOAM: Optimized Fast LiDAR Odometry and Mapping Using Scan Context}, + + publisher = {arXiv}, + + year = {2022}, + + copyright = {arXiv.org perpetual, non-exclusive license} +} +``` diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/kitti05.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/kitti05.png new file mode 100644 index 00000000000..2585651a6f2 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/kitti05.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/loop.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/loop.png new file mode 100644 index 00000000000..d21fa6a8716 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/loop.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/riverside01.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/riverside01.png new file mode 100644 index 00000000000..9eb8b91e37d Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/riverside01.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/scan_context.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/scan_context.png new file mode 100644 index 00000000000..6df3c3ebf35 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/scan_context.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/index.md new file mode 100644 index 00000000000..7b4b330406e --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/index.md @@ -0,0 +1,113 @@ +# SC-A-LOAM + +## What is SC-A-LOAM? + +- A real-time LiDAR SLAM package that integrates A-LOAM and ScanContext. + +## Repository Information + +### Original Repository link + +[https://github.com/gisbi-kim/SC-A-LOAM](https://github.com/gisbi-kim/SC-A-LOAM) + +### Required Sensors + +- LIDAR [VLP-16, HDL-32, HDL-64, Ouster OS1-64] + +### Prerequisites (dependencies) + +- ROS +- GTSAM version 4.x. + +- If GTSAM is not installed, follow the steps below. + + ```bash + wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.2.zip + cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/ + cd ~/Downloads/gtsam-4.0.2/ + mkdir build && cd build + cmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF .. + sudo make install -j8 + ``` + +### ROS Compatibility + +- ROS 1 + +## Build & Run + +### 1) Build + +- First, install the above mentioned dependencies and follow below lines. + + + ```bash + mkdir -p ~/catkin_scaloam_ws/src + cd ~/catkin_scaloam_ws/src + git clone https://github.com/gisbi-kim/SC-A-LOAM.git + cd ../ + catkin_make + source ~/catkin_scaloam_ws/devel/setup.bash + + ``` + +### 2) Set parameters + +- After downloading the repository, change topic and sensor settings on the launch files. + +### Scan Context parameters + +- 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. + +

+ +### 3) Run + +```bash +roslaunch aloam_velodyne aloam_mulran.launch +``` + +## 4) Saving as PCD file + +```bash + rosrun pcl_ros pointcloud_to_pcd input:=/aft_pgo_map +``` + +## Example Results + +

+ +### Riverside 01, MulRan dataset + +- 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](https://github.com/irapkaist/file_player_mulran) +- example videos on Riverside 01 sequence. + + ```bash + 1. with consumer level GPS-based altitude stabilization: https://youtu.be/FwAVX5TVm04 + 2. without the z stabilization: https://youtu.be/okML_zNadhY + ``` + +- example result: + +

+ +### KITTI 05 + +- For KITTI (HDL-64 sensor), run using the command + + + ```bash + roslaunch aloam_velodyne aloam_velodyne_HDL_64.launch # for KITTI dataset setting + ``` + +- To publish KITTI scans, you can use mini-kitti publisher, a simple python script: [https://github.com/gisbi-kim/mini-kitti-publisher](https://github.com/gisbi-kim/mini-kitti-publisher) +- example video (no GPS used here): [https://youtu.be/hk3Xx8SKkv4](https://youtu.be/hk3Xx8SKkv4) +- example result: + +

+ +## Contact + +- Maintainer: paulgkim@kaist.ac.kr diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/DCC.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/DCC.png new file mode 100644 index 00000000000..32bf89207bb Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/DCC.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/KAIST.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/KAIST.png new file mode 100644 index 00000000000..89a25c45351 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/KAIST.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/MulRan_merged.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/MulRan_merged.png new file mode 100644 index 00000000000..f8648bb1bb1 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/MulRan_merged.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/Riverside.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/Riverside.png new file mode 100644 index 00000000000..0c741fa492b Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/Riverside.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/output.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/output.png new file mode 100644 index 00000000000..a3e533b546b Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/output.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo.png new file mode 100644 index 00000000000..831f311842b Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo_merged.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo_merged.png new file mode 100644 index 00000000000..316ddb8d590 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo_merged.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/index.md new file mode 100644 index 00000000000..791bfb8dea6 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/index.md @@ -0,0 +1,112 @@ +# SC-LeGO-LOAM + +## What is 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. + +## Repository Information + +### Original Repository link + +[https://github.com/irapkaist/SC-LeGO-LOAM](https://github.com/irapkaist/SC-LeGO-LOAM) + +### Required Sensors + +- LIDAR [VLP-16, HDL-32E, VLS-128, Ouster OS1-16, Ouster OS1-64] +- IMU [9-AXIS] + +### ROS Compatibility + +- ROS 1 + +### Dependencies + +- ROS +- PCL +- GTSAM + +```bash +wget -O ~/Downloads/gtsam.zip https://github.com/borglab/gtsam/archive/4.0.0-alpha2.zip +cd ~/Downloads/ && unzip gtsam.zip -d ~/Downloads/ +cd ~/Downloads/gtsam-4.0.0-alpha2/ +mkdir build && cd build +cmake .. +sudo make install +``` + +## Build & Run + +### 1) Build + +```bash +cd ~/catkin_ws/src +git clone https://github.com/irapkaist/SC-LeGO-LOAM.git +cd .. +catkin_make +``` + +### 2) Set parameters + + + +- Set imu and lidar topic on `include/utility.h` +- Set lidar properties on `include/utility.h` +- Set scan context settings on `include/Scancontext.h` + +(Do not forget to rebuild after setting parameters.) + +### 3) Run + +```bash +source devel/setup.bash +roslaunch lego_loam run.launch +``` + +## Example Result + +

+ +## Other Examples + +- Video 1: DCC (MulRan dataset) +- Video 2: Riverside (MulRan dataset) +- Video 3: KAIST (MulRan dataset) + +

+

+ +## MulRan dataset + +- If you want to reproduce the results as the above video, you can download the MulRan dataset and use the ROS topic publishing tool . + +## Cite SC-LeGO-LOAM + +```bash +@INPROCEEDINGS { gkim-2018-iros, + author = {Kim, Giseop and Kim, Ayoung}, + title = { Scan Context: Egocentric Spatial Descriptor for Place Recognition within {3D} Point Cloud Map }, + booktitle = { Proceedings of the IEEE/RSJ International Conference on Intelligent Robots and Systems }, + year = { 2018 }, + month = { Oct. }, + address = { Madrid } +} +``` + +and + +```bash +@inproceedings{legoloam2018, + title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain}, + author={Shan, Tixiao and Englot, Brendan}, + booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}, + pages={4758-4765}, + year={2018}, + organization={IEEE} +} +``` + +## Contact + + + +- Maintainer: Giseop Kim (`paulgkim@kaist.ac.kr`) diff --git a/docs/how-to-guides/calibrating-your-sensors.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md similarity index 57% rename from docs/how-to-guides/calibrating-your-sensors.md rename to docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md index 363780530db..57d0a868011 100644 --- a/docs/how-to-guides/calibrating-your-sensors.md +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md @@ -6,21 +6,35 @@ Autoware expects to have multiple sensors attached to the vehicle as input to pe ## Camera calibration -Navigation2 provides a [good tutorial for camera internal calibration](https://navigation.ros.org/tutorials/docs/camera_calibration.html). +### Intrinsic Calibration + +- Navigation2 provides a [good tutorial for camera internal calibration](https://navigation.ros.org/tutorials/docs/camera_calibration.html). +- [AutoCore](https://autocore.ai/) provides a [light-weight tool](https://github.com/autocore-ai/calibration_tools/tree/main/camera_intrinsic_calib). ## Lidar-lidar calibration ### Lidar-Lidar Calibration tool from Autocore -[LL-Calib on Github](https://github.com/autocore-ai/calibration_tools/tree/main/lidar-lidar-calib), provided by [AutoCore](https://autocore.ai/), 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. +[LL-Calib on GitHub](https://github.com/autocore-ai/calibration_tools/tree/main/lidar-lidar-calib), provided by [AutoCore](https://autocore.ai/), 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. ## Lidar-camera calibration -TBD +Developed by MathWorks, The Lidar Camera Calibrator app enables you to interactively estimate the rigid transformation between a lidar sensor and a camera. + + + +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 + + + +Developed by [AutoCore](https://autocore.ai/), an easy-to-use lightweight toolkit for Lidar-camera-calibration is proposed. Only in three steps, a fully automatic calibration will be done. + + ## Lidar-IMU calibration Developed by [APRIL Lab](https://github.com/APRIL-ZJU) 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](https://autocore.ai/) 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](https://github.com/autocore-ai/calibration_tools/tree/main/li_calib). +[AutoCore](https://autocore.ai/) 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](https://github.com/autocore-ai/calibration_tools/tree/main/li_calib). diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md new file mode 100644 index 00000000000..ab1b801fe54 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md @@ -0,0 +1,204 @@ +# Creating vehicle and sensor description + +## Introduction + +This page introduce following topics. + +1. YOUR_VEHICLE_description +2. YOUR_SENSOR_KIT_description +3. individual_parameter +4. YOUR_VEHICLE_launch +5. YOUR_SENSOR_KIT_launch + +## 1. YOUR_VEHICLE_description + +In `YOUR_VEHICLE_description`, the following configurations are set: + +1. vehicle_info.param.yaml (must be changed) +2. mesh file (\*.dae) +3. mirror.param.yaml(must be changed) +4. simulator_model.param.yaml +5. vehicle.xacro + +### 1. vehicle_info.param.yaml + +Defines the vehicle dimensions. For more details on each parameter, please click [here](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-dimensions). + +### 2. mesh file + +A 3D model file used for visualization in rviz. + +### 3. mirror.param.yaml + +Set according to the vehicle dimensions. Used in the [crop-box-filter](https://autowarefoundation.github.io/autoware.universe/main/sensing/pointcloud_preprocessor/docs/crop-box-filter) of [PointCloudPreprocessor](../../../design/autoware-architecture/sensing/data-types/point-cloud.md). + +### 4. simulator_model.param.yaml + +Configuration file for the [simulator environment](https://autowarefoundation.github.io/autoware.universe/main/simulator/simple_planning_simulator/design/simple_planning_simulator-design/). + +### 5. vehicle.xacro + +The entry point file that defines the entire URDF of the vehicle. It refers to `sensors.xacro`, which specifies the sensor mounting positions. + +## 2. YOUR_SENSOR_KIT_description + +In sensor_kit_description, the following files are configured: + +1. sensors.xacro (must be changed) +2. sensor_kit.xacro (must be changed) + +### 1. sensors.xacro + +Resolves the positions of sensors with `base_link` as the parent frame and defines the positions and orientations based on `sensors_calibration.yaml` in individual_params. + +> In Autoware, `/config/sensors_calibration.yaml` is not used. + +#### About sensor_kit_base_link + +A `sensor_kit` refers to a subset that includes multiple sensors, and `sensor_kit_base_link` is the name of its frame. +The positions and orientations within the kit are defined in `sensor_kit.xacro`. + +### 2. sensor_kit.xacro + +Resolves the positions of sensors with `sensor_kit_base_link` as the parent and defines the positions and orientations based on `sensor_kit_calibration.yaml` in individual_params. + +> In Autoware, `/config/sensor_kit_calibration.yaml` is not used. + +## 3. individual_parameter + +The `individual_parameter` is where parameters referenced by `sensors.xacro` and `sensor_kit.xacro` are stored. As the name imply, it is intended to manage parameters for multiple individual instances. + +### Introduction to Various Parameters + +1. sensors_calibration.yaml (must be changed) +2. sensor_kit_calibration.yaml (must be changed) +3. imu_corrector.param.yaml + +### 1. sensors_calibration.yaml + +A file that defines the mounting positions and orientations of sensors with `base_link` as the parent frame. + +### 2. sensor_kit_calibration.yaml + +A file that defines the mounting positions and orientations of sensors with `sensor_kit_base_link` as the parent frame. + +### 3. imu_corrector.param.yaml + +A file used by `imu_corrector`. + +### 4. Folder Structure + +Below is the default directory structure. + +```diff +individual_params/ +└─ config/ + └─ default/ + └─ sample_sensor_kit/ + ├─ imu_corrector.param.yaml + ├─ sensor_kit_calibration.yaml + └─ sensors_calibration.yaml +``` + +Copy and create a folder based on your `YOUR_SENSOR_KIT` name. + +```diff +individual_params/ +└─ config/ + └─ default/ +- └─ sample_sensor_kit/ ++ └─ / + ├─ imu_corrector.param.yaml + ├─ sensor_kit_calibration.yaml + └─ sensors_calibration.yaml +``` + +#### 4.1 Sample Usage + +Here is an example of managing parameters for multiple instances. +Add a `` directory and switch parameters using options at startup. + +```bash +# example1 (do not set vehicle_id) +$ ros2 launch autoware_launch autoware.launch.xml sensor_model:= vehicle_mode:= +# example2 (set vehicle_id as VEHICLE_1) +$ ros2 launch autoware_launch autoware.launch.xml sensor_model:= vehicle_mode:= vehicle_id:=VEHICLE_1 +# example3 (set vehicle_id as VEHICLE_2) +$ ros2 launch autoware_launch autoware.launch.xml sensor_model:= vehicle_mode:= vehicle_id:=VEHICLE_2 +``` + +##### Sample Directory Structure + +```diff +individual_params/ +└─ config/ + ├─ default/ + │ └─ / # example1 + │ ├─ imu_corrector.param.yaml + │ ├─ sensor_kit_calibration.yaml + │ └─ sensors_calibration.yaml ++ ├─ VEHICLE_1/ ++ │ └─ / # example2 ++ │ ├─ imu_corrector.param.yaml ++ │ ├─ sensor_kit_calibration.yaml ++ │ └─ sensors_calibration.yaml ++ └─ VEHICLE_2/ ++ └─ / # example3 ++ ├─ imu_corrector.param.yaml ++ ├─ sensor_kit_calibration.yaml ++ └─ sensors_calibration.yaml +``` + +## 4.YOUR_VEHICLE_launch + +`YOUR_VEHICLE_launch` is where the launch file for starting the drive system devices is stored. + +1. vehicle_interface.launch.xml (must be changed) + +### 1. vehicle_interface.launch.xml + +`vehicle_interface.launch.xml` is the launch file related to the drive system. Please modify it according to the configuration of your vehicle's drive system. + +If you are operating multiple vehicles, use the `vehicle_id` to switch to the corresponding configuration for each vehicle. + +## 5. YOUR_SENSOR_KIT_launch + +`YOUR_SENSOR_KIT_launch` is where the launch files related to sensor startup are stored. + +1. sensing.launch.xml (must be changed) +2. lidar.launch.xml (must be changed) +3. camera.launch.xml +4. imu.launch.xml (must be changed) +5. gnss.launch.xml +6. pointcloud_preprocessor.launch.py (must be changed) + +### 1. sensing.launch.xml + +`sensing.launch.xml` is the entry point that calls the launch files for all sensors. Modify it according to your sensor configuration. + +### 2. lidar.launch.xml + +`lidar.launch.xml` is the launch file related to starting the LiDAR driver. Modify it according to your LiDAR configuration. + +> In Autoware's initial configuration, it assumes converting the acquired data using `pointcloud_preprocessor.launch.py`. + +#### Example Configuration Items + +- Setting the frame_id defined in `YOUR_SENSOR_KIT_description`. +- Connection information for each device. + +### 3. camera.launch.xml + +`camera.launch.xml` is the launch file related to starting the camera driver. + +### 4. imu.launch.xml + +`imu.launch.xml` is the launch file related to starting the IMU driver. + +### 5. gnss.launch.xml + +`gnss.launch.xml` is the launch file related to starting the GNSS driver. + +### 6. pointcloud_preprocessor.launch.py + +`pointcloud_preprocessor.launch.py` is the launch file to convert the raw sensor data. For more information, please click [here](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture/sensing/data-types/point-cloud/). diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/.pages b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/.pages new file mode 100644 index 00000000000..b8ce748b7cf --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/.pages @@ -0,0 +1,3 @@ +nav: + - Creating a vehicle interface for an Ackermann kinematic model: creating-a-vehicle-interface-for-an-ackermann-kinematic-model.md + - customizing-for-differential-drive-model.md diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-a-vehicle-interface-for-an-ackermann-kinematic-model.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-a-vehicle-interface-for-an-ackermann-kinematic-model.md new file mode 100644 index 00000000000..58eb276071f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-a-vehicle-interface-for-an-ackermann-kinematic-model.md @@ -0,0 +1,244 @@ +# Creating a vehicle interface for an Ackermann kinematic model + +This page introduces a module vehicle interface and explains how to implement it. + +## What is a vehicle interface + +Vehicle interface is an interface that connects the control commands and your vehicle's control device. +Autoware publishes control commands such as: + +- Velocity control +- Steering control +- Car light commands + +Then, the vehicle interface converts these commands into actuation such like: + +- Motor and brake activation +- Steering wheel operation +- Lighting control + +So think of the vehicle interface as a module that runs the vehicle's control device to realize the input commands provided by Autoware. + +
+ ![vehicle_interface_IO](images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg){ align=center } +
+ An example of inputs and outputs for vehicle interface +
+
+ +This page shows you a brief explanation how to implement your vehicle interface, but [you can see further information of vehicle interface in the "design" page](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-interface/). + +**Note that there is no package named "vehicle interface" prepared in Autoware.** +**It is a necessary package to actuate your vehicle, but you have to create one by yourself since it is very specific to your vehicle's control device.** + +For example, if you are using a by-wire kit [PACMod](https://autonomoustuff.com/platform/pacmod), a vehicle interface named [`pacmod_interface` published by TIER IV, Inc.](https://github.com/tier4/pacmod_interface/tree/main) is available. +However, if you have constructed something original and haven't found an open source vehicle interface applicable, you have to implement your own vehicle interface from scratch. + +--- + +## How to implement a vehicle interface + +The following instructions describe how to create a vehicle interface. + +### 1. Create a directory for vehicle interface + +It is recommended to create your vehicle interface at `/src/vehicle/external` + +```bash +cd /src/vehicle/external +``` + +### 2. Install or implement your own vehicle interface + +If there is an already complete vehicle interface package (like [`pacmod_interface`](https://github.com/tier4/pacmod_interface/tree/main)), you can install it to your environment. +If not, you have to implement your own vehicle interface by yourself. +Let's create a new package by `ros2 pkg create`. +The following example will show you how to create a vehicle interface package named `my_vehicle_interface`. + +```bash +ros2 pkg create --build-type ament_cmake my_vehicle_interface +``` + +Then, you should write your implementation of vehicle interface in `my_vehicle_interface/src`. +Again, since this implementation is so specific to the control device of your vehicle, it is beyond the scope of this document to describe how to implement your vehicle interface in detail. +Here are some factors that might be considered. + +- Subscription of control command topics from Autoware +- Communication between the vehicle interface and your vehicle's control device +- Modification of control values if needed + +### 3. Prepare a launch file + +After you implement your vehicle interface or you want to debug it by launching it, create a launch file of your vehicle interface, and include it to `vehicle_interface.launch.xml`. + +Do not get confused. First, you need to create a launch file for your own vehicle interface module (like `my_vehicle_interface.launch.xml`) **and then include that to `vehicle_interface.launch.xml` which exists in another directory.** Here are the details. + +1. Add a `launch` directory in the `my_vehicle_interface` directory, and create a launch file of your own vehicle interface in it. Take a look at [Creating a launch file](https://docs.ros.org/en/humble/Tutorials/Intermediate/Launch/Launch-Main.html) in the ROS 2 documentation. + +2. Next, go to `/src/vehicle`, copy the directory `/sample_vehicle_launch/`, and paste it to the same place (which means it should be lined up with `external` and `sample_vehicle_launch`). + +3. You have to rename each "sample_vehicle" to something else. For example, if you want to rename "sample_vehicle" to "my_vehicle_name", you need to change the following. Note that it is restricted to keep the "\_launch" and "\_description" part. + + - **Rename the directories** + - `sample_vehicle_launch` → `my_vehicle_name_launch` + - `my_vehicle_name_launch/sample_vehicle_launch` → `my_vehicle_name_launch/my_vehicle_name_launch` + - `my_vehicle_name_launch/sample_vehicle_description` → `my_vehicle_name_launch/my_vehicle_name_description` + - **After you rename your directories, rename each "sample_vehicle" to "my_vehicle_name" in the source code.** + - `my_vehicle_name_description/CMakeLists.txt` + - `my_vehicle_name_description/package.xml` + - `my_vehicle_name_description/urdf/vehicle.xacro` (there are two parts) + - `my_vehicle_name_launch/CMakeLists.txt` + - `my_vehicle_name_launch/package.xml` + - `README.md` + +4. Include your launch file to `my_vehicle_name_launch/my_vehicle_name_launch/launch/vehicle_interface.launch.xml` by opening it and add the include terms like below. + +```xml title="vehicle_interface.launch.xml" + + + + + + + +``` + +Finally, your directory structure may look like below. + Most of the files are omitted for clarity, but the files shown here needs modification as said in the previous and current process. + +```diff +/ +└─ src/ + └─ vehicle/ + ├─ external/ ++ │ └─ my_vehicle_interface/ ++ │ ├─ src/ ++ │ └─ launch/ ++ │ └─ my_vehicle_interface.launch.xml + ├─ sample_vehicle_launch/ ++ └─ my_vehicle_name_launch/ (COPIED FROM sample_vehicle_launch) ++ ├─ my_vehicle_name_launch/ ++ │ ├─ launch/ ++ │ │ └─ vehicle_interface.launch.xml ++ │ ├─ CMakeLists.txt ++ │ └─ package.xml ++ ├─ my_vehicle_name_description/ ++ │ ├─ config/ ++ │ ├─ mesh/ ++ │ ├─ urdf/ ++ │ │ └─ vehicle.xacro ++ │ ├─ CMakeLists.txt ++ │ └─ package.xml ++ └─ README.md +``` + +### 4. Build the vehicle interface package and the launch package + +Build three packages `my_vehicle_interface`, `my_vehicle_name_launch` and `my_vehicle_name_description` by `colcon build`, or you can just build the entire Autoware if you have done other things. + +```bash +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-select my_vehicle_interface my_vehicle_name_launch my_vehicle_name_description +``` + +### 5. When you launch Autoware + +Finally, you are done implementing your vehicle interface module! Be careful that you need to launch Autoware with the proper `vehicle_model` option like the example below. This example is launching planning simulator. + +```bash +ros2 launch autoware_launch planning.launch.xml map_path:=$HOME/autoware_map/sample-map-planning vehicle_model:=my_vehicle_name sensor_model:=sample_sensor_kit +``` + +### Tips + +There are some tips that may help you. + +- You can subdivide your vehicle interface into smaller packages if you want. Then your directory structure may look like below (not the only way though). Do not forget to launch all packages in `my_vehicle_interface.launch.xml`. + + ```diff + / + └─ src/ + └─ vehicle/ + ├─ external/ + │ └─ my_vehicle_interface/ + │ ├─ src/ + │ │ ├─ package1/ + │ │ ├─ package2/ + │ │ └─ package3/ + │ └─ launch/ + │ └─ my_vehicle_interface.launch.xml + ├─ sample_vehicle_launch/ + └─ my_vehicle_name_launch/ + ``` + +- If you are using a vehicle interface and launch package from a open git repository, or created your own as a git repository, it is highly recommended to add those repositories to your `autoware.repos` file which is located to directly under your autoware folder like the example below. You can specify the branch or commit hash by the version tag. + + ```yaml title="autoware.repos" + # vehicle (this section should be somewhere in autoware.repos and add the below) + vehicle/my_vehicle_name_launch: + type: git + url: https://github.com//my_vehicle_name_launch.git + version: main + vehicle/external/my_vehicle_interface: + type: git + url: https://github.com//my_vehicle_interface.git + version: main + ``` + + Then you can import your entire environment easily to another local device by using the `vcs import` command. (See [the source installation guide](https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/#how-to-set-up-a-workspace)) + +--- + +## Ackermann kinematic model + +Autoware now supports control inputs for vehicles based on an Ackermann kinematic model. +This section introduces you a brief concept of Ackermann kinematic model and explains how Autoware controls it. + +- If your vehicle does not suit the Ackermann kinematic model, you have to modified the control commands. [Another document gives you an example how to convert your Ackermann kinematic model control inputs into a differential drive model.](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/) + +### Geometry + +The basic style of Ackermann kinematic model has four wheels with an Ackermann link on the front, and it is powered by the rear wheels. +The key point of Ackermann kinematic model is that the axes of all wheels intersect at a same point, which means all wheels will trace a circular trajectory with a different radii but a common center point (See the figure below). +Therefore, this model has a great advantage that it minimizes the slippage of the wheels, and prevent tires to get worn soon. + +In general, Ackermann kinematic model accepts the longitudinal speed $v$ and the steering angle $\phi$ as inputs. +In autoware, $\phi$ is positive if it is steered counter clockwise, so the steering angle in the figure below is actually negative. + +
+ ![ackermann_link](images/Ackermann_WB.png){ align=center } +
+ The basic style of an Ackermann kinematic model. The left figure shows a vehicle facing straight forward, while the right figure shows a vehicle steering to the right. +
+
+ +### Control + +Autoware publishes a ROS 2 topic named `control_cmd` from several types of publishers. +A `control_cmd` topic is a [`AckermannControlCommand`](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/AckermannControlCommand.idl) type message that contains + +```bash title="AckermannControlCommand" + builtin_interfaces/Time stamp + autoware_auto_control_msgs/AckermannLateralCommand lateral + autoware_auto_control_msgs/LongitudinalCommand longitudinal +``` + +where, + +```bash title="AckermannLateralCommand" + builtin_interfaces/Time stamp + float32 steering_tire_angle + float32 steering_tire_rotation_rate +``` + +```bash title="LongitudinalCommand" + builtin_interfaces/Time stamp + float32 speed + float32 accelaration + float32 jerk +``` + +See the [AckermannLateralCommand.idl](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/AckermannLateralCommand.idl) and [LongitudinalCommand.idl](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/LongitudinalCommand.idl) for details. + +The vehicle interface should realize these control commands through your vehicle's control device. + +Moreover, Autoware also provides brake commands, light commands, and more (see [vehicle interface design](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-interface/)), so the vehicle interface module should be applicable to these commands as long as there are devices available to handle them. diff --git a/docs/how-to-guides/integrating-autoware-with-a-diff-drive-vehicle.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model.md similarity index 93% rename from docs/how-to-guides/integrating-autoware-with-a-diff-drive-vehicle.md rename to docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model.md index 95049cad01d..fd833f3cf50 100644 --- a/docs/how-to-guides/integrating-autoware-with-a-diff-drive-vehicle.md +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model.md @@ -1,4 +1,4 @@ -# Integrating Autoware with a differential drive vehicle +# Customizing for differential drive vehicle ## 1. Introduction @@ -36,7 +36,7 @@ $$ 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](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-interface/). +For information about other factors that need to be considered when creating a `vehicle_interface` package, refer to the [`vehicle_interface` component page](../../../design/autoware-interfaces/components/vehicle-interface.md). ### 2.2 Set an appropriate `wheel_base` diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/images/Ackermann_WB.png b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/images/Ackermann_WB.png new file mode 100644 index 00000000000..fb810380493 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/images/Ackermann_WB.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..ab30e1c47c0 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Planning
Planning
Localization
Localization
Control
Control
Vehicle Interface
Vehicle InterfaceTrajectoryautoware_auto_planning_msgs/TrajectoryVehicle Signal Commandsautoware_auto_vehicle_msgs/- HandBrakeCommand- HazardLightsCommand- HeadlightsCommand- HornCommand- StationaryLockingCommand- TurnIndicatorsCommand- WipersCommandVehicle Control Commandautoware_auto_vehicle_msgs/AckermannControlCommandVehicle Signal Reportsautoware_auto_vehicle_msgs/- GearReport- HandBrakeReport- HazardLightsReport- HeadlightsReport- HornReport- TurnIndicatorsReport- WipersReportVehicle Odometrygeometry_msgs/TwistWithCovarianceStamped
Diagnostics Manager
Diagnostics ManagerError StatusActuation Status
acceleration, brake, steering
acceleration, brake, steeringVehicle CommunicationVehicle Specific Protocol
Adapter
AdapterSteering Status
steering_angle
steering_angle
Gate
Gate
Other Controls
(emergency, external, joystick, ...)
Other Controls...Actuation Command
acceleration, brake, steering
acceleration, brake, steeringText is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/integrating-autoware/creating-your-autoware-meta-repository/creating-autoware-meta-repository.md b/docs/how-to-guides/integrating-autoware/creating-your-autoware-meta-repository/creating-autoware-meta-repository.md new file mode 100644 index 00000000000..71b128ba18f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-your-autoware-meta-repository/creating-autoware-meta-repository.md @@ -0,0 +1,57 @@ +# Creating Autoware meta-repository + +## What is Meta-repository? + +A meta-repository is a repository that manages multiple repositories, and [Autoware](https://github.com/autowarefoundation/autoware) is one of them. +It serves as a centralized control point for referencing, configuring, and versioning other repositories. + +By using Ansible and VCS, you can automatically set up your Autoware. +`autoware.repos` file manages the configuration of multiple repositories. + +Note: VCS stands for Version Control System, such as Git or Subversion. + +## How to create and customize your autoware meta-repository + +### 1. Create autoware repository + +If you want to integrate Autoware into your vehicle, the first step is to create an Autoware meta-repository. + +One easy way is to fork [autowarefoundation/autoware](https://github.com/autowarefoundation/autoware) and clone it. +For how to fork a repository, refer to [GitHub Docs](https://docs.github.com/en/get-started/quickstart/fork-a-repo). + +```bash +git clone https://github.com/YOUR_NAME/autoware.git +``` + +If you set up multiple types of vehicles, adding a suffix like `autoware.vehicle_A` or `autoware.vehicle_B` is recommended + +### 2. Customize your autoware.repos for your environment + +You need to customize `autoware.repos` for your own vehicle's Autoware. + +For example, if you want to customize the parameters in your `individual_params` or `autoware_launch` package to fit your vehicle, you can modify the configuration of each package and use them accordingly. + +Please edit the parameters in Autoware's `autoware_individual_params` and `autoware_launch` packages to match your vehicle's specific requirements, as these packages provide sample parameters and may not be tailored to your vehicle by default. + +If you want to fork `autoware_individual_params` and make modifications, it would be as follows: + +Example: If you fork `individual_params` and rename `autoware_individual_params.vehicle_A`: + +```diff +- param/autoware_individual_params: +- type: git +- url: https://github.com/autowarefoundation/autoware_individual_params +- version: main ++ param/autoware_individual_params.vehicle_A: ++ type: git ++ url: https://github.com/YOUR_NAME/autoware_individual_params.vehicle_A ++ version: main +``` + +Please refer to the following documentation link for instructions on how to create and customize each `vehicle_interface`: + +- [creating-vehicle-and-sensor-description](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description) +- [creating-vehicle-interface-package](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-a-vehicle-interface-for-an-ackermann-kinematic-model/) +- [customizing-for-differential-drive-model](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/) + +Please remember to add all your custom packages, such as interfaces and descriptions, to your `autoware.repos` to ensure that your packages are properly included and managed within the Autoware repository. diff --git a/docs/how-to-guides/images/integrating-autoware-with-your-vehicle/autoware-state-panel.png b/docs/how-to-guides/integrating-autoware/images/autoware-state-panel.png similarity index 100% rename from docs/how-to-guides/images/integrating-autoware-with-your-vehicle/autoware-state-panel.png rename to docs/how-to-guides/integrating-autoware/images/autoware-state-panel.png diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/.pages b/docs/how-to-guides/integrating-autoware/launch-autoware/.pages new file mode 100644 index 00000000000..f3708e7a449 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/.pages @@ -0,0 +1,4 @@ +nav: + - index.md + - Localization methods: localization-methods + - Perception mode: perception.md diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/images/2d_goal_pose.png b/docs/how-to-guides/integrating-autoware/launch-autoware/images/2d_goal_pose.png new file mode 100644 index 00000000000..5f394ce73ce Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/launch-autoware/images/2d_goal_pose.png differ diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/images/2d_pose_estimate.png b/docs/how-to-guides/integrating-autoware/launch-autoware/images/2d_pose_estimate.png new file mode 100644 index 00000000000..e6ebf3197ec Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/launch-autoware/images/2d_pose_estimate.png differ diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/images/autoware_state_panel_after.png b/docs/how-to-guides/integrating-autoware/launch-autoware/images/autoware_state_panel_after.png new file mode 100644 index 00000000000..687cd150d2e Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/launch-autoware/images/autoware_state_panel_after.png differ diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/images/autoware_state_panel_before.png b/docs/how-to-guides/integrating-autoware/launch-autoware/images/autoware_state_panel_before.png new file mode 100644 index 00000000000..7d9147521dd Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/launch-autoware/images/autoware_state_panel_before.png differ diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/images/route_planning_is_complete.png b/docs/how-to-guides/integrating-autoware/launch-autoware/images/route_planning_is_complete.png new file mode 100644 index 00000000000..59557f912c3 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/launch-autoware/images/route_planning_is_complete.png differ diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/index.md new file mode 100644 index 00000000000..1877a2cc39f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/index.md @@ -0,0 +1,87 @@ +# Launch Autoware + +!!! warning + + Under Construction + +This section explains how to run your vehicle with Autoware. + +## Install Autoware + +Follow the [installation steps of Autoware](../../../installation/). + +## Launch Autoware + +Launch Autoware with the following command: + +```bash +ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP +``` + +It is possible to specify which components to launch using command-line arguments. +For example, if you don't need to launch perception, planning, and control for localization debug, you can launch the following: + +```bash +ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ + launch_perception:=false \ + launch_planning:=false \ + launch_control:=false +``` + +The basic command-line options are documented in [autoware.launch.xml](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/launch/autoware.launch.xml). + +There are options available to switch between different methods for some component. +For example, by specifying `pose_source`/`twist_source` or `perception_mode`, you can switch localization and perception methods, respectively. +These options allow you to choose the desired algorithms or sensor configurations for the respective functionalities. + +For options on eagleye component, please refer to the sub-pages. + +- [localization-mode](localization-methods/index.md) +- [perception-mode](perception.md) + +## Set initial pose + +If GNSS is available, Autoware automatically initializes the vehicle's pose. + +If not or if the automatic initialization returns an incorrect position, 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 + + ![2D Pose estimate](images/2d_pose_estimate.png) + +2. In the 3D View pane, click and hold the left mouse button, and then drag to set the direction for the initial pose. + +## Set goal pose + +Set a goal pose for the ego vehicle. + +1. Click the 2D Nav Goal button in the toolbar, or hit the G key + + ![2D Pose estimate](images/2d_goal_pose.png) + +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. + + ![route planning](images/route_planning_is_complete.png){width="800"} + +## Engage + +In your terminal, execute the following command. + +```bash +source ~/autoware.YOURS/install/setup.bash +ros2 topic pub /autoware.YOURS/engage autoware_auto_vehicle_msgs/msg/Engage "engage: true" -1 +``` + +You can also engage via RViz with "AutowareStatePanel". +The panel can be found in `Panels > Add New Panel > tier4_state_rviz_plugin > AutowareStatePanel`. + +Once the route is computed, the "AUTO" button becomes active. Pressing the AUTO button engages the autonomous driving mode. + +![autoware state panel](images/autoware_state_panel_before.png) + +Now the vehicle should drive along the calculated path! + +During the autonomous driving, the StatePanel appears as shown in the image below. Pressing the "STOP" button allows you to stop the vehicle. + +![autoware state panel](images/autoware_state_panel_after.png) diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/.pages b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/.pages new file mode 100644 index 00000000000..24441b7323f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/.pages @@ -0,0 +1,3 @@ +nav: + - index.md + - Eagleye: eagleye-guide.md diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/eagleye-guide.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/eagleye-guide.md new file mode 100644 index 00000000000..38eacf7f53b --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/eagleye-guide.md @@ -0,0 +1,120 @@ +# Using Eagleye with Autoware + +This page will show you how to set up [Eagleye](https://github.com/MapIV/eagleye) in order to use it with Autoware. +For the details of the integration proposal, please refer to [this discussion](https://github.com/orgs/autowarefoundation/discussions/3257). + +## What is Eagleye? + +Eagleye is an open-source GNSS/IMU-based localizer initially developed by [MAP IV. Inc](https://map4.jp/). 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. + +### Dependencies + +The below packages are automatically installed during the setup of Autoware as they are listed in [autoware.repos](https://github.com/autowarefoundation/autoware/blob/main/autoware.repos). + +1. [Eagleye](https://github.com/MapIV/eagleye.git) (autoware-main branch) +2. [RTKLIB ROS Bridge](https://github.com/MapIV/rtklib_ros_bridge.git) (ros2-v0.1.0 branch) +3. [LLH Converter](https://github.com/MapIV/llh_converter.git) (ros2 branch) + +## Architecture + +Eagleye can be utilized in the Autoware localization stack in two ways: + +1. Feed only twist into the EKF localizer. + + ![Eagleye twist integration](images/eagleye-integration-guide/eagleye_twist.drawio.svg) + +2. Feed both twist and pose from Eagleye into the EKF localizer (twist can also be used with regular `gyro_odometry`). + + ![Eagleye pose twist integration](images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg) + +**Note: RTK positioning is required when using Eagleye as the pose estimator.** +On the other hand, it is not mandatory when using it as the twist estimator. + +## Requirements + +Eagleye requires GNSS, IMU and vehicle speed as inputs. + +### IMU topic + +`sensor_msgs/msg/Imu` is supported for Eagleye IMU input. + +### Vehicle speed topic + +`geometry_msgs/msg/TwistStamped` and `geometry_msgs/msg/TwistWithCovarianceStamped` are supported for the input vehicle speed. + +### GNSS topic + +Eagleye requires latitude/longitude height and doppler velocity 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: + +| GNSS ROS drivers | modification | +| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [ublox_gps](https://github.com/KumarRobotics/ublox/tree/ros2/ublox_gps) | No additional settings are required. It publishes `sensor_msgs/msg/NavSatFix` and `geometry_msgs/msg/TwistWithCovarianceStamped` required by Eagleye with default settings. | +| [septentrio_gnss_driver](https://github.com/septentrio-gnss/septentrio_gnss_driver/tree/ros2) | Set `publish.navsatfix` and `publish.twist` in the config file [`gnss.yaml`](https://github.com/septentrio-gnss/septentrio_gnss_driver/blob/ros2/config/gnss.yaml#L90) to `true` | + +## Parameter Modifications for Integration into Your Vehicle + +### topic name & topic type + +The users must correctly specify input topics for GNSS latitude, longitude, and height , GNSS doppler speed , IMU , and vehicle speed in the [`eagleye_config.yaml`](https://github.com/MapIV/autoware_launch/blob/3f04a9dd7bc4a4c49d4ec790e3f6b9958ab822da/autoware_launch/config/localization/eagleye_config.param.yaml#L7-L16). + +```yaml +# Topic +twist: + twist_type: 1 # TwistStamped : 0, TwistWithCovarianceStamped: 1 + twist_topic: /sensing/vehicle_velocity_converter/twist_with_covariance +imu_topic: /sensing/imu/tamagawa/imu_raw +gnss: + velocity_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, ublox_msgs/NavPVT: 2, geometry_msgs/TwistWithCovarianceStamped: 3 + velocity_source_topic: /sensing/gnss/ublox/navpvt + llh_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, sensor_msgs/NavSatFix: 2 + llh_source_topic: /sensing/gnss/ublox/nav_sat_fix +``` + +### sensor frequency + +Also, the frequency of GNSS and IMU must be set in [`eagleye_config.yaml`](https://github.com/MapIV/autoware_launch/blob/3f04a9dd7bc4a4c49d4ec790e3f6b9958ab822da/autoware_launch/config/localization/eagleye_config.param.yaml#L36) + +```yaml +common: + imu_rate: 50 + gnss_rate: 5 +``` + +### Conversion from fix to pose + +The parameters for converting `sensor_msgs/msg/NavSatFix` to `geometry_msgs/msg/PoseWithCovarianceStamped` is listed in [`fix2pose.yaml`](https://github.com/MapIV/eagleye/blob/autoware-main/eagleye_util/fix2pose/launch/fix2pose.xml). +If you use a different geoid or projection type, change these parameters. + +### Other parameters + +The other parameters are described [here](https://github.com/MapIV/eagleye/tree/autoware-main/eagleye_rt/config). +Basically, these do not need to be changed . + +## Notes on initialization + +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.** + +### 1. Static Initialization + +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. + +### 2. Dynamic initialization + +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. + +### How to check the progress of initialization + +- **TODO** + +## Note on georeferenced maps + +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. diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg new file mode 100644 index 00000000000..4b0f24f10cf --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg @@ -0,0 +1,4 @@ + + + +
Eagleye
Eagleye
IMU
IMU
EKF
EKF
GNSS
GNSS
Wheel
Odometry
Wheel...
twist with
covariance
twist with...
pose with
covariance
pose with...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_twist.drawio.svg b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_twist.drawio.svg new file mode 100644 index 00000000000..11d6cfa80f8 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_twist.drawio.svg @@ -0,0 +1,4 @@ + + + +
Eagleye
Eagleye
IMU
IMU
3DLiDAR
3DLiDAR
NDT
NDT
EKF
EKF
GNSS
GNSS
Wheel
Odometry
Wheel...
pose with
covariance
pose with...
twist with
covariance
twist with...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md new file mode 100644 index 00000000000..c508d7cb589 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md @@ -0,0 +1,65 @@ +# Localization methods + +Current localization launcher implemented by TIER IV supports multiple localization methods, both pose estimators and twist estimators. +`tier4_localization_component.launch.xml` has two arguments to select which estimators to launch: + +- `pose_source` : an argument to select pose_estimator, currently supporting `ndt` (default), `yabloc`, and `eagleye` +- `twist_source` : an argument to select twist_estimator, currently supporting `gyro_odom` (default), and `eagleye` + +## NDT scan matcher: a LiDAR and pointcloud map based pose estimator (default) + +By default, Autoware launches [ndt_scan_matcher](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/ndt_scan_matcher) for pose estimator. +In order to launch this explicitly, you need to specify as follows: + +```bash +ros2 launch autoware_launch autoware.launch.xml ... pose_source:=ndt ... +``` + +Note that currently `pose_source` is set to NDT as default, so you can skip this argument. + +## Gyro Odometer: an IMU & wheel odometry based twist estimator (default) + +By default, Autoware launches [gyro_odometer](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/gyro_odometer) for twist estimator. +In order to launch this explicitly, you need to specify as follows: + +```bash +ros2 launch autoware_launch autoware.launch.xml ... twist_source:=gyro_odom ... +``` + +Note that currently `twist_source` is set to Gyro Odometer as default, so you can skip this argument. + +## YabLoc: a camera and vector map based pose estimator + +You can use YabLoc as a camera-based localization method. +For more details on YabLoc, please refer to the [README of YabLoc](https://github.com/autowarefoundation/autoware.universe/blob/main/localization/yabloc/README.md) in autoware.universe. + +To use YabLoc as a pose_estimator, add `pose_source:=yabloc` when launching Autoware. +By default, the `pose_source` is set to `ndt`. +By specifying this command-line argument, YabLoc nodes will be automatically launched while the NDT nodes will not be started. + +Here is an example of a launch command: + +```bash +ros2 launch autoware_launch autoware.launch.xml ... pose_source:=yabloc ... +``` + +## Eagleye: a GNSS & IMU & wheel odometry based pose and twist estimator + +You can use Eagleye as a GNSS & IMU & wheel odometry-based localization method. For more details on Eagleye, please refer to the [Eagleye](eagleye-guide.md). + +Eagleye has a function for position estimation and twist estimation, namely `pose_estimator` and `twist_estimator`, respectively. +When running Eagleye in twist_estimator mode with other pose_estimator such as ndt_scan_matcher, Eagleye is still helpful since it can improve scan matching by providing accurate twists using GNSS doppler. + +You can use Eagleye by specifying the `pose_source` and `twist_source` accordingly through command-line arguments. + +**Example of using Eagleye as the pose twist estimator:** + +```bash +ros2 launch autoware_launch autoware.launch.xml ... pose_source:=eagleye twist_source:=eagleye ... +``` + +**Example of using Eagleye as the twist estimator:** + +```bash +ros2 launch autoware_launch autoware.launch.xml ... twist_source:=eagleye ... +``` diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/perception.md b/docs/how-to-guides/integrating-autoware/launch-autoware/perception.md new file mode 100644 index 00000000000..708715e6b43 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/perception.md @@ -0,0 +1,33 @@ +# Perception mode + +!!! warning + + Under Construction + +By specifying the `perception_mode`, users can switch between different sensor configurations for perception. +This allows you to choose the specific sensor setup that you want to use for the perception tasks. + +```bash +ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ + perception_mode:=lidar +``` + +## LiDAR + +`perception_mode:=lidar` + +## Radar + +`perception_mode:=radar` + +## Camera LiDAR fusion + +`perception_mode:=camera_lidar_fusion` + +## Camera LiDAR Radar fusion + +`perception_mode:=camera_lidar_radar_fusion` + +## LiDAR Radar fusion + +`perception_mode:=lidar_radar_fusion` diff --git a/docs/how-to-guides/integrating-autoware-with-your-vehicle.md b/docs/how-to-guides/integrating-autoware/overview.md similarity index 81% rename from docs/how-to-guides/integrating-autoware-with-your-vehicle.md rename to docs/how-to-guides/integrating-autoware/overview.md index 6700ede40ba..0eaec1bb889 100644 --- a/docs/how-to-guides/integrating-autoware-with-your-vehicle.md +++ b/docs/how-to-guides/integrating-autoware/overview.md @@ -1,10 +1,10 @@ -# Integrating Autoware with your vehicle +# Overview -## 1. Prepare your real vehicle hardware +## Requirement: prepare your real vehicle hardware Prerequisites for the vehicle: -- An onboard computer that satisfies the [Autoware installation prerequisites](https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/#prerequisites) +- An onboard computer that satisfies the [Autoware installation prerequisites](../../installation/autoware/source-installation.md#prerequisites) - The following devices attached - Drive-by-wire interface - LiDAR @@ -12,24 +12,7 @@ Prerequisites for the vehicle: - Optional: Camera - Optional: GNSS -## 2. Create maps - -You need both a pointcloud map and a vector map in order to use Autoware. - -### Create a pointcloud map - -Use third-party tools such as a LiDAR-based SLAM (Simultaneous Localization And Mapping) package to create a pointcloud map in the `.pcd` format. -Some examples are: - -- [HDL](https://github.com/koide3/hdl_graph_slam) -- [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) -- [LiDAR-SLAM (ROS 2)](https://github.com/rsasaki0109/lidarslam_ros2) - -### Create vector map - -Use third-party tools such as [TIER IV's Vector Map Builder](https://tools.tier4.jp/) to create a Lanelet2 format `.osm` file. - -## 3. Create your Autoware meta-repository +## 1. Creating your Autoware meta-repository Create your Autoware meta-repository. One easy way is to fork [autowarefoundation/autoware](https://github.com/autowarefoundation/autoware) and clone it. @@ -41,7 +24,7 @@ git clone https://github.com/YOUR_NAME/autoware.git If you set up multiple types of vehicles, adding a suffix like "autoware.vehicle_A" or "autoware.vehicle_B" is recommended. -## 4. Create the description packages of your vehicle +## 2. Creating the your vehicle and sensor description Next, you need to create description packages that define the vehicle and sensor configuration of your vehicle. @@ -100,13 +83,13 @@ Create `launch/sensing.launch.xml` that launches the interfaces of all the senso !!! 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](https://autowarefoundation.github.io/autoware-documentation/main/installation/) (starting from the dependency installation step) and then run the following command: + To do so, you need to build and install Autoware using your cloned repository. Follow the [steps for either Docker or source installation](../installation/) (starting from the dependency installation step) and then run the following command: ```bash ros2 launch autoware_launch planning_simulator.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP ``` -## 5. Create a `vehicle_interface` package +## 3. Create a `vehicle_interface` package You need to create an interface package for your vehicle. The package is expected to provide the following two functions. @@ -114,16 +97,30 @@ 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](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-interface/). +You can find detailed information about the requirements of the `vehicle_interface` package in the [Vehicle Interface design documentation](../../design/autoware-interfaces/components/vehicle-interface.md). You can also refer to TIER IV's [pacmod_interface repository](https://github.com/tier4/pacmod_interface) as an example of a vehicle interface package. -## 6. Launch Autoware +## 4. Create maps + +You need both a pointcloud map and a vector map in order to use Autoware. +For more information on map design, please click [here](../../design/autoware-architecture/map/index.md). + +### Create a pointcloud map + +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](creating-maps/index.md). + +### Create vector map + +Use third-party tools such as [TIER IV's Vector Map Builder](https://tools.tier4.jp/) to create a Lanelet2 format `.osm` file. + +## 5. Launch Autoware This section briefly explains how to run your vehicle with Autoware. ### Install Autoware -Follow the [installation steps of Autoware](https://autowarefoundation.github.io/autoware-documentation/main/installation/). +Follow the [installation steps of Autoware](../../installation/). ### Launch Autoware @@ -162,12 +159,10 @@ ros2 topic pub /autoware.YOURS/engage autoware_auto_vehicle_msgs/msg/Engage "eng You can also engage via RViz with "AutowareStatePanel". The panel can be found in `Panels > Add New Panel > tier4_state_rviz_plugin > AutowareStatePanel`. -![Autoware State Panel](images/integrating-autoware-with-your-vehicle/autoware-state-panel.png){: style="height:360px;width:640px"} +![Autoware State Panel](images/autoware-state-panel.png){: style="height:360px;width:640px"} Now the vehicle should drive along the calculated path! -## 7. Tune parameters for your vehicle & environment +## 6. Tune parameters for your vehicle & environment You may need to tune your parameters depending on the domain in which you will operate your vehicle. - -If you have any issues or questions, feel free to create an [Autoware Foundation GitHub Discussion](https://github.com/orgs/autowarefoundation/discussions) in the Q&A category! diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/.pages b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/.pages new file mode 100644 index 00000000000..9cb01955bdf --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/.pages @@ -0,0 +1,3 @@ +nav: + - evaluating-controller-performance.md + - evaluating-real-time-performance.md diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance.md b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance.md new file mode 100644 index 00000000000..50989f798f2 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance.md @@ -0,0 +1,75 @@ +# Evaluating the controller performance + +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](https://github.com/autowarefoundation/autoware.universe/tree/main/control/control_performance_analysis). + +## How to use + +### Before Driving + +#### 1. Firstly you need to launch Autoware. You can also use this tool with real vehicle driving + +#### 2. Initialize the vehicle and send goal position to create route + +- If you have any problem with launching Autoware, please see the [tutorials](../../../tutorials/index.md) page. + +#### 3. Launch the control_performance_analysis package + +```bash +ros2 launch control_performance_analysis controller_performance_analysis.launch.xml +``` + +- After this command, you should be able to see the driving monitor and error variables in topics. + +#### 4. Run the PlotJuggler in sourced terminal + +```bash +source ~/autoware/install/setup.bash +``` + +```bash +ros2 run plotjuggler plotjuggler +``` + +- If you do not have PlotJuggler in your computer, please refer [here](https://github.com/facontidavide/PlotJuggler#installation) for installation guideline. + +#### 5. Increase the buffer size (maximum is 100), and import the layout from `/autoware.universe/control/control_performance_analysis/config/controller_monitor.xml` + +- 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. + +![Start PlotJuggler](images/evaluating-controller-performance/start-plotjuggler.png) + +#### 6. Now, you can start to driving. You should see all the performance and driving variables in PlotJuggler + +![Controller Monitor](images/evaluating-controller-performance/controller-monitor.png) + +### After Driving + +#### 1. You can export the statistical output and all data to compare and later usage + +- With statistical data, you can export the all statistical values like (min, max, average) to compare the controllers. + +![CVS Export](images/evaluating-controller-performance/export-cvs.png) + +- You can also export all data to later use. To investigate them again, after launch PlotJuggler, import the `.cvs` file from data section. + +![Import Data](images/evaluating-controller-performance/import-data.png) + +### Tips + +- 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. + +![Plot XY Curve](images/evaluating-controller-performance/plot-xy.png) + +- If you see too much noised curve in plots, you can adjust the `odom_interval` and `low_pass_filter_gain` from [here](https://github.com/autowarefoundation/autoware.universe/blob/main/control/control_performance_analysis/config/control_performance_analysis.param.yaml) to avoid noised data. diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance.md b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance.md new file mode 100644 index 00000000000..5005973432f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance.md @@ -0,0 +1,205 @@ +# Evaluating real-time performance + +## Introduction + +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 + +## Performance measurement + +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. + +### Single node execution + +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`](https://github.com/sykwer/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. + +### Prepare separated cores + +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](https://phoenixnap.com/kb/build-linux-kernel)). +Note that even if full tickless is enabled, timer interrupts are generated for scheduling if more than two tasks exist in one core. + +```text +# Enable CONFIG_NO_HZ_FULL +-> General setup +-> Timers subsystem +-> Timer tick handling (Full dynticks system (tickless)) +(X) Full dynticks system (tickless) + +# Allows RCU callback processing to be offloaded from selected CPUs +# (CONFIG_RCU_NOCB_CPU=y) +-> General setup +-> RCU Subsystem +-*- Offload RCU callback processing from boot-selected CPUs +``` + +Additionally, the kernel boot parameters need to be set as follows. + +```text +GRUB_CMDLINE_LINUX_DEFAULT= + "... isolcpus=2,8 rcu_nocbs=2,8 rcu_nocb_poll nohz_full=2,8 intel_pstate=disable” +``` + +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. + +```shell +cat /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor // ondemand +sudo sh -c "echo userspace > /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor" +``` + +This allows you to freely set the desired frequency within a defined range. + +```shell +sudo sh -c "echo > /sys/devices/system/cpu/cpu2/cpufreq/scaling_setspeed" +``` + +Turbo Boost needs to be switched off on Intel CPUs, which is often overlooked. + +```shell +sudo sh -c "echo 0 > /sys/devices/system/cpu/cpufreq/boost" +``` + +### Run single node separately + +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. + +```shell +taskset --cpu-list -p +``` + +To avoid interference in the last level cache, minimize the number of other applications running during the measurement. + +### Measurement and visualization + +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`](https://github.com/sykwer/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. + +## Case studies + +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. + +### Sensing component + +First, we will explain the procedure for performance improvement, taking the node `ring_outlier_filter` as an example. +Refer to the [Pull Request](https://github.com/autowarefoundation/autoware.universe/pull/3014) 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. + +![ring outlier filter turnaround time](https://raw.githubusercontent.com/autowarefoundation/autoware-documentation/0ad57338ca24b35f0a271c6ae003aa303b3dd4ce/docs/assets/images/ring_outlier_filter_turnaround_time.png) + +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. + +![ring outlier filter minor faults](https://raw.githubusercontent.com/autowarefoundation/autoware-documentation/0ad57338ca24b35f0a271c6ae003aa303b3dd4ce/docs/assets/images/ring_outlier_filter_minor_faults.png) + +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`](https://github.com/tier4/heaphook) to avoid soft page faults while running Autoware callback. +If you are interested, refer to the [GitHub discussion](https://github.com/orgs/autowarefoundation/discussions/3274) and the [issue](https://github.com/autowarefoundation/autoware/issues/3310). + +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. + +```cpp +void callback(const PointCloudMsg &input_msg) { + auto output_msg = allocate_msg(output_size); + fill(input_msg, output_msg); + publish(std::move(output_msg)); +} +``` + +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. + +```cpp +void callback(const sensor_msgs::PointCloud2ConstPtr &input_msg) { + pcl::PointCloud::Ptr input_pcl(new pcl::PointCloud); + pcl::fromROSMsg(*input_msg, *input_pcl); + + // Algorithm is described for point cloud type of pcl + pcl::PointCloud::Ptr output_pcl(new pcl::PointCloud); + fill_pcl(*input_pcl, *output_pcl); + + auto output_msg = allocate_msg(output_size); + pcl::toROSMsg(*output_pcl, *output_msg); + publish(std::move(output_msg)); +} +``` + +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., ). +For large message types such as map data, there should be only one instance in the entire system in terms of physical memory. + +### Planning component + +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. + +![detection area turnaround time](https://raw.githubusercontent.com/autowarefoundation/autoware-documentation/36647431080a837a1c8a983faf5045d6524cee66/docs/assets/images/detection_area_turnaround_time.png) + +Using [`pmu_analyzer`](https://github.com/sykwer/pmu_analyzer) tool to further identify the bottleneck, we have found that the following multiple loops were taking up a lot of processing time: + +```cpp +for ( area : detection_areas ) + for ( point : point_clouds ) + if ( boost::geometry::within(point, area) ) + // do something with O(1) +``` + +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’t have to call the `within` function in most cases. Below is the pseudocode after optimization. + +```cpp +for ( area : detection_areas ) + circle = calc_minimum_enclosing_circle(area) + for ( point : point_clouds ) + if ( point is in circle ) + if ( boost::geometry::within(point, area) ) + // do something with O(1) +``` + +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](https://github.com/autowarefoundation/autoware.universe/pull/2846). + +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. diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/controller-monitor.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/controller-monitor.png new file mode 100644 index 00000000000..40f68175dfa Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/controller-monitor.png differ diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/export-cvs.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/export-cvs.png new file mode 100644 index 00000000000..3f33336111c Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/export-cvs.png differ diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/import-data.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/import-data.png new file mode 100644 index 00000000000..c793a02e54a Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/import-data.png differ diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/plot-xy.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/plot-xy.png new file mode 100644 index 00000000000..29f86ba8a48 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/plot-xy.png differ diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/start-plotjuggler.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/start-plotjuggler.png new file mode 100644 index 00000000000..8fe25945511 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/start-plotjuggler.png differ diff --git a/docs/how-to-guides/others/.pages b/docs/how-to-guides/others/.pages new file mode 100644 index 00000000000..1ac1fb2ba08 --- /dev/null +++ b/docs/how-to-guides/others/.pages @@ -0,0 +1 @@ +nav: diff --git a/docs/how-to-guides/others/add-a-custom-ros-message.md b/docs/how-to-guides/others/add-a-custom-ros-message.md new file mode 100644 index 00000000000..f15ffd00b3a --- /dev/null +++ b/docs/how-to-guides/others/add-a-custom-ros-message.md @@ -0,0 +1,131 @@ +# Add a custom ROS message + +## Overview + +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](https://github.com/autowarefoundation/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](https://github.com/orgs/autowarefoundation/discussions/categories/design). + +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](https://github.com/tier4/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 ROS 2 tutorial, see [Create custom msg and srv files](http://docs.ros.org/en/galactic/Tutorials/Beginner-Client-Libraries/Custom-ROS2-Interfaces.html). + +## How to create custom message + +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 + + ```console + cd ./src/core/autoware_msgs + ros2 pkg create --build-type ament_cmake autoware_sensing_msgs + ``` + +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: + + ```console + mkdir msg + cd msg + touch GnssInsOrientation.msg + touch GnssInsOrientationStamped.msg + ``` + + Edit `GnssInsOrientation.msg` with your editor to be the following content: + + ```c++ + geometry_msgs/Quaternion orientation + float32 rmse_rotation_x + float32 rmse_rotation_y + float32 rmse_rotation_z + ``` + + 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: + + ```c++ + std_msgs/Header header + GnssInsOrientation orientation + ``` + + 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`: + + ```cmake + rosidl_generate_interfaces(${PROJECT_NAME} + "msg/GnssInsOrientation.msg" + "msg/GnssInsOrientationStamped.msg" + DEPENDENCIES + geometry_msgs + std_msgs + ADD_LINTER_TESTS + ) + ``` + + :speech_balloon: 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 + + ```cmake + find_package(ament_cmake REQUIRED) + + ament_package() + ``` + + with + + ```cmake + find_package(ament_cmake_auto REQUIRED) + + ament_auto_package() + ``` + +4. Edit package.xml + + We need to declare relevant dependencies in `package.xml`. For the above example we need to add the following content: + + ```xml + rosidl_default_generators + + rosidl_default_runtime + + geometry_msgs + std_msgs + + rosidl_interface_packages + ``` + + We need to replace `ament_cmake` with `ament_cmake_auto` 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: + + ```console + colcon build --packages-select autoware_sensing_msgs + ``` + + Now the `GnssInsOrientationStamped` message will be discoverable by other packages in Autoware. + +## How to use custom messages in Autoware + +You can use the custom messages in Autoware by following these steps: + +- Add dependency in `package.xml`. + - For example, `autoware_sensing_msgs`. +- Include the `.hpp` file of the relevant message in the code. + - For example, `#include `. diff --git a/docs/how-to-guides/advanced-usage-of-colcon.md b/docs/how-to-guides/others/advanced-usage-of-colcon.md similarity index 100% rename from docs/how-to-guides/advanced-usage-of-colcon.md rename to docs/how-to-guides/others/advanced-usage-of-colcon.md diff --git a/docs/how-to-guides/others/an-example-procedure-for-adding-and-evaluating-a-new-node.md b/docs/how-to-guides/others/an-example-procedure-for-adding-and-evaluating-a-new-node.md new file mode 100644 index 00000000000..3f82819b61a --- /dev/null +++ b/docs/how-to-guides/others/an-example-procedure-for-adding-and-evaluating-a-new-node.md @@ -0,0 +1,78 @@ +# An example procedure for adding and evaluating a new node + +## Overview + +This page provides a guide for evaluating Autoware when a new node is implemented, especially about developing a novel localization node. + +The workflow involves initial testing and rosbag recording using a real vehicle or AWSIM, implementing the new node, subsequent testing using the recorded rosbag, and finally evaluating with a real vehicle or AWSIM. + +It is assumed that the method intended for addition has already been verified well with public datasets and so on. + +## 1. Running Autoware in its standard configuration + +First of all, it is important to be able to run the standard Autoware to establish a basis for performance and behavior comparison. + +Autoware constantly incorporates new features. +It is crucial to initially confirm that it operates as expected with the current version, which helps in problem troubleshooting. + +In this context, AWSIM is presumed. +Therefore, [AWSIM simulator](https://autowarefoundation.github.io/autoware-documentation/main/tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial/) can be useful. +If you are using actual hardware, please refer to the [How-to guides](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/). + +## 2. Recording a rosbag using Autoware + +Before developing a new node, it is recommended to record a rosbag in order to evaluate. +If you need a new sensor, you should add it to your vehicle or AWSIM. + +In this case, it is recommended to save all topics regardless of whether they are necessary or not. +For example, in Localization, since the initial position estimation service is triggered by the input to rviz and the GNSS topic, the initial position estimation does not start when playing back data unless those topics are saved. + +Consider the use of the [mcap format](https://mcap.dev/) if data capacity becomes a concern. + +It is worth noting that using `ros2 bag record` increases computational load and might affect performance. +After data recording, verifying the smooth flow of sensor data and unchanged time series is advised. +This verification can be accomplished, for example, by inspecting the image data with `rqt_image_view` during `ros2 bag play`. + +## 3. Developing the new node + +When developing a new node, it could be beneficial to reference a package that is similar to the one you intend to create. + +It is advisable to thoroughly read the [Design page](https://autowarefoundation.github.io/autoware-documentation/main/design/), contemplate the addition or replacement of nodes in Autoware, and then implement your solution. + +For example, a node doing NDT, a LiDAR-based localization method, is [ndt_scan_matcher](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/ndt_scan_matcher). +If you want to replace this with a different approach, implement a node which produces the same topics and provides the same services. + +`ndt_scan_matcher` is launched as [pose_estimator](https://github.com/autowarefoundation/autoware.universe/blob/main/launch/tier4_localization_launch/launch/pose_estimator/pose_estimator.launch.xml), so it is necessary to replace the launch file as well. + +## 4. Evaluating by a rosbag-based simulator + +Once the new node is implemented, it is time to evaluate it. +[logging_simulator](https://autowarefoundation.github.io/autoware-documentation/main/tutorials/ad-hoc-simulation/rosbag-replay-simulation/) is a tool of how to evaluate the new node using the rosbag captured in step 2. + +When you run the logging_simulator, you can set `planning:=false` or `control:=false` to disable the launch of specific component nodes. + +`ros2 launch autoware_launch logging_simulator.launch.xml ... planning:=false control:=false` + +After launching logging_simulator, the rosbag file obtained in step 2 should be replayed using `ros2 bag play `. + +If you remap the topics related to the localization that you want to verify this time, Autoware will use the data it is calculating this time instead of the data it recorded. +Also, using the `--topics` option of `ros2 bag play`, you can publish only specific topics in rosbag. + +There is [ros2bag_extensions](https://github.com/tier4/ros2bag_extensions) available to filter the rosbag file and create a new rosbag file that contains only the topics you need. + +## 5. Evaluating in a realtime environment + +Once you have sufficiently verified the behavior in the logging_simulator, let's run it as Autoware with new nodes added in the realtime environment. + +To debug Autoware, the method described at [debug-autoware](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/others/debug-autoware/) is useful. + +For reproducibility, you may want to fix the GoalPose. +In such cases, consider using the [tier4_automatic_goal_rviz_plugin](https://github.com/autowarefoundation/autoware.universe/tree/main/common/tier4_automatic_goal_rviz_plugin). + +## 6. Sharing the results + +If your implementation works successfully, please consider a pull request to Autoware. + +It is also a good idea to start by presenting your ideas in Discussion at [Show and tell](https://github.com/orgs/autowarefoundation/discussions/categories/show-and-tell). + +For localization, [YabLoc's Proposal](https://github.com/orgs/autowarefoundation/discussions/3484) may provide valuable insights. diff --git a/docs/how-to-guides/others/applying-clang-tidy-to-ros-packages.md b/docs/how-to-guides/others/applying-clang-tidy-to-ros-packages.md new file mode 100644 index 00000000000..8cdbc4bc4bf --- /dev/null +++ b/docs/how-to-guides/others/applying-clang-tidy-to-ros-packages.md @@ -0,0 +1,43 @@ +# Applying Clang-Tidy to ROS packages + +[Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/) is a powerful C++ linter. + +## Preparation + +You need to generate `build/compile_commands.json` before using Clang-Tidy. + +```bash +colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1 +``` + +## Usage + +```bash +clang-tidy -p build/ path/to/file1 path/to/file2 ... +``` + +If you want to apply Clang-Tidy to all files in a package, using the [fd](https://github.com/sharkdp/fd) command is useful. +To install `fd`, see the [installation manual](https://github.com/sharkdp/fd#on-ubuntu). + +```bash +clang-tidy -p build/ $(fd -e cpp -e hpp --full-path "/autoware_utils/") +``` + +## IDE integration + +### CLion + +Refer to the [CLion Documentation](https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html). + +### Visual Studio Code + +Use either one of the following extensions: + +- [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) +- [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) + +## Troubleshooting + +If you encounter `clang-diagnostic-error`, try installing `libomp-dev`. + +Related: diff --git a/docs/how-to-guides/others/debug-autoware.md b/docs/how-to-guides/others/debug-autoware.md new file mode 100644 index 00000000000..73d9ae028ef --- /dev/null +++ b/docs/how-to-guides/others/debug-autoware.md @@ -0,0 +1,114 @@ +# Debug Autoware + +This page provides some methods for debugging Autoware. + +## Print debug messages + +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](../../contributing/coding-guidelines/ros-nodes/console-logging.md). + +## Using ROS tools debug Autoware + +### Using command line tools + +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](http://docs.ros.org/en/galactic/Tutorials/Beginner-CLI-Tools.html). + +### Using rviz2 + +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: + +```console +rviz2 +``` + +When Autoware launch the simulators, the Rviz2 tool is opened by default to visualize the autopilot graphic information. + +### Using rqt tools + +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: + +```console +rqt +``` + +This GUI allows you to choose any available plugins on your system. You can also run plugins in standalone windows. For example, RQt Console: + +```console +ros2 run rqt_console rqt_console +``` + +#### Common RQt tools + +1. rqt_graph: view node interaction + + In complex applications, it may be helpful to get a visual representation of the ROS node interactions. + + ```console + ros2 run rqt_graph rqt_graph + ``` + +2. rqt_console: view messages + + rqt_console is a great gui for viewing ROS topics. + + ```console + ros2 run rqt_console rqt_console + ``` + +3. rqt_plot: view data plots + + rqt_plot is an easy way to plot ROS data in real time. + + ```console + ros2 run rqt_plot rqt_plot + ``` + +### Using ros2_graph + +[`ros2_graph`](https://github.com/kiwicampus/ros2_graph) can be used to generate [mermaid](https://mermaid.js.org/#/) 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: + +```bash +pip install ros2-graph +``` + +Then you can generate a mermaid description of the graph with: + +```bash +ros2_graph your_node + +# or like with an output file +ros2_graph /turtlesim -o turtle_diagram.md + +# or multiple nodes +ros2_graph /turtlesim /teleop_turtle +``` + +You can then visualize these graphs with: + +- [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) +- Visual Studio Code extension [mermaid preview](https://marketplace.visualstudio.com/items?itemName=vstirbu.vscode-mermaid-preview) +- JetBrains IDEs [with native support](https://www.jetbrains.com/go/guide/tips/mermaid-js-support-in-markdown/) + +### Using ros2doctor + +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](https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Getting-Started-With-Ros2doctor.html). + +## Using a debugger with breakpoints + +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: + +- +- diff --git a/docs/how-to-guides/others/defining-temporal-performance-metrics.md b/docs/how-to-guides/others/defining-temporal-performance-metrics.md new file mode 100644 index 00000000000..b95d2c68e23 --- /dev/null +++ b/docs/how-to-guides/others/defining-temporal-performance-metrics.md @@ -0,0 +1,152 @@ +# Defining temporal performance metrics on components + +## Motivation to defining temporal performance metrics + +### Objective of the page + +This page introduces policies to define metrics to evaluate temporal performance on components of Autoware. The term "temporal performance" is often used throughout the page in order to distinguish between functional performance, which referred to as accuracy as well, and time-related performance. + +It is expected that most algorithms employed for Autoware are executed with as high frequency and short response time as possible. In order to achieve safe autonomous driving, one of the desired outcomes is no time gap between perceived and actual situation. The time gap is commonly referred to as delay. If the delay is significant, the system may determine trajectory and maneuver based on outdated situation. Consequently, if the actual situation differs from the perceived one due to the delay, the system may make unexpected decisions. + +As mentioned above, this page presents the policies to define metrics. Besides, the page contains lists of sample metrics that are crucial for the main functionalities of Autoware: Localization, Perception, Planning, and Control. + +!!! note + + Other functionalities, such as system components for diagnosis, are excluded currently. However they will be taken into account in the near future. + +### Contribution of the temporal performance metrics + +Temporal performance metrics are important for evaluating Autoware. These metrics are particularly useful for assessing delays caused by new algorithms and logic. They can be employed when comparing the temporal performance of software on a desktop computer with that on a vehicle during the vehicle integration phase. + +In addition, these metrics are useful for designers and evaluators of middleware, operating systems, and computers. They are selected based on user and product requirements. One of these requirements is to provide sufficient temporal performance for executing Autoware. "Sufficient temporal performance" is defined as a temporal performance requirement, but it can be challenging to define the requirement because it varies depending on the product type, Operational Design Domain (ODD), and other factors. Then, this page specifically focuses on temporal performance metrics rather than requirements. + +Temporal performance metrics are important for evaluating the reliability of Autoware. However, ensuring the reliability of Autoware requires consideration of not only temporal performance metrics but also other metrics. + +### Tools for evaluating the metrics + +There are several tools available for evaluating Autoware according to the metrics listed in the page. For example, both [CARET](https://github.com/tier4/caret) and [ros2_tracing](https://github.com/ros2/ros2_tracing) are recommended options when evaluating Autoware on Linux and ROS 2. If you want to measure the metrics with either of these tools, refer to the corresponding user guide for instructions. It's important to note that if you import Autoware to a platform other than Linux and ROS 2, you will need to choose a supported tool for evaluation. + +!!! note + + TIER IV plans to measure Autoware, which is running according to [the tutorial](../../tutorials/), and provide a performance evaluation report periodically. An example of such a report can be found [here](https://tier4.github.io/CARET_report/), although it may not include all of the metrics listed. + +The page does not aim to provide instructions on how to use these tools or measure the metrics. Its primary focus is on the metrics themselves, as they are more important than the specific tools used. These metrics retain their relevance regardless of the employed platform. + +## Policies to define temporal performance metrics + +As mentioned above, the configuration of Autoware varies by the product type, ODD, and other factors. The variety of configurations makes it difficult to define the uniform metrics for evaluating Autoware. +However, the policies used to define them are basically reused even when the configuration changes. Each of temporal performance metrics is categorized into two types: **execution frequency** and **response time**. Although there are many types of metrics, such as communication latency, the only two types are considered for simplicity. +Execution frequency is observed using rate of Inter-Process Communication (IPC) messages. You will find an enormous number of messages in Autoware, but you don't have to take care of all. Some messages might be critical to functionality and they should be chosen for evaluation. +Response time is duration elapsed through a series of processing. A series of processing is referred to as a path. Response time is calculated from timestamps of start and end of a path. Although many paths can be defined in Autoware, you have to choose significant paths. + +As a hint, here are some characteristics of message and path in order to choose metrics. + +1. Messages and paths on boundaries where observed values from sensors are consumed +2. Messages and paths on boundaries of functions, e.g., a boundary of perception and planning +3. Messages and paths on boundaries where timer-based frequency is switched +4. Messages and paths on boundaries where two different messages are synchronized and merged +5. Messages that must be transmitted at expected frequency, e.g., vehicle command messages + +Those hints would be helpful for most configurations but there may be exclusions. Defining metrics precisely requires an understanding of configuration. + +In addition, it is recommended that metrics be determined incrementally from the architectural level to the detailed design and implementation level. Mixing metrics at different levels of granularity can be confusing. + +## List of sample metrics + +This section demonstrates how to define metrics according to the policies explained and has lists of the metrics for Autoware launched according to [the tutorial](../../tutorials/). The section is divided into multiple subsections, each containing a model diagram and an accompanying list that explains the important temporal performance metrics. Each model is equipped with checkpoints that serve as indicators for these metrics. + +The first subsection presents the top-level temporal performance metrics, which are depicted in the abstract structure of Autoware as a whole. The detailed metrics are not included in the model as they would add complexity to it. Instead, the subsequent section introduces the detailed metrics. The detailed metrics are subject to more frequent updates compared to the top-level ones, which is another reason for categorizing them separately. + +Each list includes a column for the reference value. The reference value represents the observed value of each metric when Autoware is running according to [the tutorial](../../tutorials/). It is important to note that the reference value is not a required value, meaning that Autoware does not necessarily fail in [the tutorial](../../tutorials/) execution if certain metrics do not fulfill the reference value. + +### Top-level temporal performance metrics for Autoware + +The diagram below introduces the model for top-level temporal performance metrics. + +![Model for top-level temporal performance metrics](./images/important-temporal-performance-metrics/model-for-top-level-metrics.svg) + +The following three policies assist in selecting the top-level performance metrics: + +- Splitting Autoware based on components that consume observed values, such as sensor data, and considering the processing frequency and response time around these components +- Dividing Autoware based on the entry point of Planning and Control and considering the processing frequency and response time around these components +- Showing the minimum metrics for the Vehicle Interface, as they may vary depending on the target vehicle + +Additionally, it is assumed that algorithms are implemented as multiple nodes and function as a pipeline processing system. + + + +| ID | Representation in the model | Metric meaning | Related functionality | Reference value | Reason to choose it as a metric | Note | +| -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| AWOV-001 | **Message rate** from CPA #9 to CPA #18 | Update rate of result from Prediction to Planning. | Perception | 10 Hz | Planning relies on fresh and up-to-date perceived data from Perception for creating accurate trajectory. | | +| AWOV-002 | **Response time** from CPA #0 to CPA #20 via CPA #18 | Response time in main body of Perception. | Perception | N/A | Planning relies on fresh and up-to-date perceived data from Perception for creating accurate trajectory. | The metric is used if delay compensation is disabled in Tracking. | +| AWOV-003 | **Response time** from CPA #7 to CPA #20 | Response time from Tracking output of Tracking to its data consumption in Planning. | Perception | N/A | Planning relies on fresh and up-to-date perceived data from Perception for creating accurate trajectory. | The metric is used if delay compensation is enabled in Tracking. | +| AWOV-004 | **Response time** from CPA #0 to CPA #6 | Duration to process pointcloud data in Sensing and Detection. | Perception | N/A | Tracking relies on detection to provide real-time and up-to-date sensed data for accurate tracking. | The metric is used if delay compensation is enabled in Tracking. | +| AWOV-005 | **Message rate** from CPA #4 to CPA #5 | Update rate of Detection result received by Tracking. | Perception | 10 Hz | Tracking relies on detection to provide real-time and up-to-date sensed data for accurate tracking. | | +| AWOV-006 | **Response time** from CPA #0 to CPA #14 | Response time from output of observed data from LiDARs to its consumption in EKF Localizer via NDT Scan Matcher. | Localization | N/A | EKF Localizer relies on fresh and up-to-date observed data from sensors for accurate estimation of self pose. | | +| AWOV-007 | **Message rate** from CPA #11 to CPA #13 | Update rate of pose estimated by NDT Scan Matcher. | Localization | 10 Hz | EKF Localizer relies on fresh and up-to-date observed data from sensors for accurate estimation of self pose. | | +| AWOV-008 | **Message rate** from CPA #15 to CPA #12 | Update rate of feed backed pose estimated by EKF Localizer. | Localization | 50 Hz | NDT Scan Matcher relies on receiving estimated pose from EKF Localizer smoothly for linear interpolation. | | +| AWOV-009 | **Message rate** from CPA #17 to CPA #19 | Update rate of Localization result received by Planning. | Localization | 50 Hz | Planning relies on Localization to update the estimated pose frequently. | | +| AWOV-010 | **Response time** from CPA #20 to CPA #23 | Processing time from beginning of Planning to consumption of Trajectory message in Control. | Planning | N/A | A vehicle relies on Planning to update trajectory within a short time frame to achieve safe driving behavior. | | +| AWOV-011 | **Message rate** from CPA #21 to CPA #22 | Update rate of Trajectory message from Planning. | Planning | 10 Hz | A vehicle relies on Planning to update trajectory frequently to achieve safe driving behavior. | | +| AWOV-012 | **Message rate** from CPA #24 to CPA #25 | Update rate of Control command. | Control | 33 Hz | Control stability and comfort relies on sampling frequency of Control. | | +| AWOV-013 | **Message rate** between CPA #26 and Vehicle | Communication rate between Autoware and Vehicle. | Vehicle Interface | N/A | A vehicle requires Autoware to communicate with each other at predetermined frequency. | Temporal performance requirement varies depending on vehicle type. | + +!!! note + + There is an assumption that each of sensors, such as LiDARs and cameras, outputs a set of pointcloud with a timestamp. CPA #0 is observed with the timestamp. If the sensors are not configured to output the timestamp, the time when Autoware receives the pointcloud is used instead. That is represented by CPA #1 in the model. The detailed metrics employs the idea as well. + +### Detailed temporal performance metrics for Perception + +The diagram below introduces the model for temporal performance metrics for Perception. + +![Model for Perception temporal performance metrics](./images/important-temporal-performance-metrics/model-for-perception-metrics.svg) + +The following two policies assist in selecting the performance metrics: + +- Regarding the frequency and response time at which Recognition results from Object Recognition and Traffic Light Recognition are consumed in Planning +- Splitting Perception component on merging points of data from multiple processing paths and considering the frequency and response time around that point + +The following list shows the temporal performance metrics for Perception. + +| ID | Representation in the model | Metric meaning | Related functionality | Reference value | Reason to choose it as a metric | Note | +| -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| APER-001 | **Message rate** from CPP #2 to CPP #26 | Update rate of Traffic Light Recognition. | Traffic Light Recognition | 10 Hz | Planning relies on fresh and up-to-date perceived data from Traffic Light Recognition for making precise decisions. | | +| APER-002 | **Response time** from CPP #0 to CPP #30 | Response time from camera input to consumption of the result in Planning. | Traffic Light Recognition | N/A | Planning relies on fresh and up-to-date perceived data from Traffic Light Recognition for making precise decisions. | | +| APER-003 | **Message rate** from CPP #25 to CPP #28 | Update rate of result from Prediction (Object Recognition) to Planning. | Object Recognition | 10 Hz | Planning relies on fresh and up-to-date perceived data from Perception for creating accurate trajectory. | The metric is same as AWOV-001. | +| APER-004 | **Response time** from CPP #6 to CPP #30 | Response time from Tracking output of Tracking to its data consumption in Planning. | Object Recognition | N/A | Planning relies on fresh and up-to-date perceived data from Perception for creating accurate trajectory. | The metric is same as AWOV-002 and used if delay compensation is disabled in Tracking. | +| APER-005 | **Response time** from CPP #23 to CPP #30 | Response time from Tracking output of Tracking to its data consumption in Planning. | Object Recognition | N/A | Planning relies on fresh and up-to-date perceived data from Perception for creating accurate trajectory. | The metric is same as AWOV-003 and used if delay compensation is enabled in Tracking. | +| APER-006 | **Response time** from CPP #6 to CPP #21 | Duration to process pointcloud data in Sensing and Detection. | Object Recognition | N/A | Tracking relies on Detection to provide real-time and up-to-date perceived data. | The metrics is same as AWOV-004 and used if delay compensation is enabled in Tracking. | +| APER-007 | **Message rate** from CPP #20 to CPP #21 | Update rate of Detection result received by Tracking. | Object Recognition | 10 Hz | Tracking relies on detection to provide real-time and up-to-date sensed data for accurate tracking. | The metric is same as AWOV-005 | +| APER-008 | **Message rate** from CPP #14 to CPP #19 | Update rate of data sent from Sensor Fusion. | Object Recognition | 10 Hz | Association Merger relies on the data to be updated at expected frequency for data synchronization. | | +| APER-009 | **Message rate** from CPP #16 to CPP #19 | Update rate of data sent from Detection by Tracker. | Object Recognition | 10 Hz | Association Merger relies on the data to be updated at expected frequency for data synchronization. | | +| APER-010 | **Message rate** from CPP #18 to CPP #19 | Update rate of data sent from Validation | Object Recognition. | 10 Hz | Association Merger relies on the data to be updated at expected frequency for data synchronization. | +| APER-011 | **Response time** from CPP #6 to CPP #19 via CPP #14 | Response time to consume data sent from Sensor Fusion after LiDARs output pointcloud. | Object Recognition | N/A | Association Merger relies on fresh and up-to-date data for data synchronization. | | +| APER-012 | **Response time** from CPP #6 to CPP #19 via CPP #16 | Response time to consume data sent from Detection by Tracker after LiDARs output pointcloud. | Object Recognition | N/A | Association Merger relies on fresh and up-to-date data for data synchronization. | | +| APER-013 | **Response time** from CPP #6 to CPP #19 via CPP #18 | Response time to consume data sent from Validator after LiDARs output pointcloud. | Object Recognition | N/A | Association Merger relies on fresh and up-to-date data for data synchronization. | | +| APER-014 | **Message rate** from CPP #10 to CPP #13 | Update rate of data sent from Clustering. | Object Recognition | 10 Hz | Sensor Fusion relies on the data to be updated at expected frequency for data synchronization. | | +| APER-015 | **Message rate** from CPP #5 to CPP #13 | Update rate of data sent from Camera-based Object detection. | Object Recognition | 10 Hz | Sensor Fusion relies on the data to be updated at expected frequency for data synchronization. | | +| APER-016 | **Response time** from CPP #6 to CPP #13 | Response time to consume data sent from Clustering after LiDARs output pointcloud. | Object Recognition | N/A | Sensor Fusion relies on fresh and up-to-date data for data synchronization. | | +| APER-017 | **Response time** from CPP #3 to CPP #13 | Response time to consume data sent from Camera-based Object detection after Cameras output images. | Object Recognition | N/A | Sensor Fusion relies on fresh and up-to-date data for data synchronization. | | +| APER-018 | **Message rate** from CPP #10 to CPP #17 | Update rate of data sent from Clustering. | Object Recognition | 10 Hz | Validator relies on the data to be updated at expected frequency for data synchronization. | It seems similar to APER-014, but the topic message is different. | +| APER-019 | **Message rate** from CPP #12 to CPP #17 | Update rate of data sent from DNN-based Object Recognition. | Object Recognition | 10 Hz | Validator relies on the data to be updated at expected frequency for data synchronization. | +| APER-020 | **Response time** from CPP #6 to CPP #17 via CPP #10 | Response time to consume data sent from Clustering after LiDARs output pointcloud. | Object Recognition | N/A | Validator relies on fresh and update-date data for data synchronization. | It seems similar to APER-015, but the topic message is different. | +| APER-021 | **Response time** from CPP #6 to CPP #17 via CPP #12 | Response time to consume data sent from DNN-based Object Recognition after LiDARs output pointcloud. | Object Recognition | N/A | Validator relies on fresh and update-date data for data synchronization. | | + +### Detailed temporal performance metrics for Paths between Obstacle segmentation and Planning + +Obstacle segmentation, which is a crucial part of Perception, transmits data to Planning. The figure below illustrates the model that takes into account performance metrics related to Obstacle segmentation and Planning. + +![Model for Obstacle segmentation temporal performance metrics](./images/important-temporal-performance-metrics/model-for-obstacle-segmentation-metrics.svg) + +!!! note + + Both the Obstacle grid map and Obstacle segmentation transmit data to multiple sub-components of Planning. However, not all of these sub-components are described in the model. This is because our primary focus is on the paths from LiDAR to Planning via Obstacle segmentation. + +The following list shows the temporal performance metrics around Obstacle segmentation and Planning. + +| ID | Representation in the model | Metric meaning | Related functionality | Reference value | Reason to choose it as a metric | Note | +| -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | ---- | +| OSEG-001 | **Message rate** from CPS #4 to CPS #7 | Update rate of Occupancy grid map received by Planning (`behavior_path_planner`) | Obstacle segmentation | 10 Hz | Planning relies on Occupancy grid map to be updated frequently and smoothly for creating accurate trajectory. | | +| OSEG-002 | **Response time** from CPS #0 to CPS #9 via CPS #7 | Response time to consume Occupancy grid map after LiDARs output sensing data. | Obstacle segmentation | N/A | Planning relies on fresh and up-to-date perceived data from Occupancy grid map for creating accurate trajectory.. | | +| OSEG-003 | **Message rate** from CPS #6 to CPS #11 | Update rate of obstacle segmentation received by Planning (`behavior_velocity_planner`). | Obstacle segmentation | 10 Hz | Planning relies on Obstacle segmentation to be updated frequently and smoothly for creating accurate trajectory. | | +| OSEG-004 | **Response time** from CPS #0 to CPS #13 via CPS #11 | Response time to consume Obstacle segmentation after LiDARs output sensing data. | Obstacle segmentation | N/A | Planning relies on fresh and up-to-date perceived data from Obstacle segmentation for creating accurate trajectory.. | | diff --git a/docs/how-to-guides/determining-component-dependencies.md b/docs/how-to-guides/others/determining-component-dependencies.md similarity index 100% rename from docs/how-to-guides/determining-component-dependencies.md rename to docs/how-to-guides/others/determining-component-dependencies.md diff --git a/docs/how-to-guides/others/fixing-dependent-package-versions.md b/docs/how-to-guides/others/fixing-dependent-package-versions.md new file mode 100644 index 00000000000..c496a05969e --- /dev/null +++ b/docs/how-to-guides/others/fixing-dependent-package-versions.md @@ -0,0 +1,10 @@ +# Fixing dependent package versions + +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. + +```bash +vcs export src --exact > my_autoware.repos +``` diff --git a/docs/how-to-guides/images/determining-component-dependencies/perception_stack_dependencies.png b/docs/how-to-guides/others/images/determining-component-dependencies/perception_stack_dependencies.png similarity index 100% rename from docs/how-to-guides/images/determining-component-dependencies/perception_stack_dependencies.png rename to docs/how-to-guides/others/images/determining-component-dependencies/perception_stack_dependencies.png diff --git a/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-obstacle-segmentation-metrics.svg b/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-obstacle-segmentation-metrics.svg new file mode 100644 index 00000000000..4b294e262c6 --- /dev/null +++ b/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-obstacle-segmentation-metrics.svg @@ -0,0 +1,4 @@ + + + +
LiDARs
LiDARs
CPS #0
CPS #0
Sensing (preprocessing and concatenate)
Sensing (preproces...
CPS #1
CPS #1
CPS #2
CPS #2
Perception/Occupancy grid map
Perception/Occupancy...
Perception/Obstacle segmentation
Perception/Obstacle seg...
Planning/Behavior path planner
Planning/Behavior pat...
subscription
callback
subscription...
timer callback
timer callback
Planning/Behavior velocity planner
Planning/Behavior vel...
subscription
callback
subscription...
subscription
callback
subscription...
CPS #3
CPS #3
CPS #4
CPS #4
CPS #5
CPS #5
CPS #6
CPS #6
CPS #7
CPS #7
CPS #8
CPS #8
CPS #9
CPS #9
CPS #10
CPS #10
CPS #11
CPS #11
CPS #12
CPS #12
CPS #13
CPS #13
CPS #14
CPS #14
CPS #: Checkpoint for Segmentation and planning components
CPS #: Checkpoint for Segmentation and planni...
Legend
Legend
Key Component
Key Component
Callback
Callback
callbacks denote when input messages are consumed rather than received.
callbacks denote when inpu...
inter-component
communication
inter-componentcom...
intra-component
communication
intra-componentcom...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-perception-metrics.svg b/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-perception-metrics.svg new file mode 100644 index 00000000000..68e52c545db --- /dev/null +++ b/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-perception-metrics.svg @@ -0,0 +1,4 @@ + + + +
LiDARs
LiDARs
CPP #6
CPP #6
Sensing (preprocessing and concatenate)
Sensing (preprocessing...
Clustering
(including
- occupancy grid map
- obstacle segmentation)
Clustering...
DNN-based
 Object Recognition
(Centerpoint)
DNN-based...
Camera-based
Object Recognition
Camera-based...
OR Cameras
OR Cameras
Sensor Fusion
Sensor Fusion
Detection by Tracker
Detection by Tracker
Association
Merger
Association...
Tracking
Tracking
Prediction
Prediction
Planning/Behavior Path Planner
Planning/Behavior Pa...
TLR Cameras
TLR Cameras
Camera-based
Traffic Light Recognition
Camera-based...
CPP #P #0
CPP #P #0
CPP #1
CPP #1
CPP #2
CPP #2
CPP #3
CPP #3
CPP #4
CPP #4
CPP #5
CPP #5
CPP #7
CPP #7
CPP #8
CPP #8
CPP #9
CPP #9
CPP #10
CPP #10
CPP #11
CPP #11
CPP #12
CPP #12
CPP #13
CPP #13
CPP #14
CPP #14
CPP #15
CPP #15
CPP #16
CPP #16
CPP #19
CPP #19
CPP #20
CPP #20
CPP #24
CPP #24
CPP #25
CPP #25
CPP #26
CPP #26
timer callback
timer callback
CPP #22
CPP #22
subscription
callback
subscription...
CPP #21
CPP #21
CPP #23
CPP #23
subscription
callback
subscription...
subscription
callback
subscription...
timer callback
(10 Hz)
timer callback...
CPP #28
CPP #28
CPP #30
CPP #30
CPP #27
CPP #27
CPP #29
CPP #29
CPP #31
CPP #31
Validator
Validator
CPP #17
CPP #17
CPP #18
CPP #18
CPP #: Checkpoint for Perception components
CPP #: Checkpoint for Perception components
Legend
Legend
Key Component
Key Component
Callback
Callback
inter-component
communication
inter-componentcom...
intra-component
communication
intra-componentcom...
callbacks denote when input messages are consumed rather than received.
callbacks denote when inpu...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-top-level-metrics.svg b/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-top-level-metrics.svg new file mode 100644 index 00000000000..b6ec6119716 --- /dev/null +++ b/docs/how-to-guides/others/images/important-temporal-performance-metrics/model-for-top-level-metrics.svg @@ -0,0 +1,4 @@ + + + +
Sensing
Sensing
Sensor
(LiDARs)
Sensor...
Localization
/NDT Scan Matcher
Localization/NDT Scan...
Planning
Planning
Control
Control
Vehicle Interface
Vehicle Interface
CPA #0
CPA #0
CPA #: Checkpoint for Autoware overview
CPA #: Checkpoint for Autoware overview
Vehicle
ECU
Vehicle...
Localization
/Stop Filter
Localization...
CPA #1
CPA #1
CPA #2
CPA #2
CPA #10
CPA #10
CPA #3
CPA #3
CPA #9
CPA #9
CPA #11
CPA #11
CPA #16
CPA #16
CPA #17
CPA #17
subscription
callback
subscription...
subscription
callback
subscription...
CPA #12
CPA #12
Perception/
Detection
Perception/...
Perception/
Tracking
Perception/...
Perception/
Prediction
Perception/...
subscription
callback
subscription...
timer
callback
timer...
CPA #4
CPA #4
CPA #5
CPA #5
CPA #7
CPA #7
CPA #6
CPA #6
CPA #8
CPA #8
Legend
Legend
Key Component
Key Component
Callback
Callback
CPA #13
CPA #13
subscription
callback
subscription...
timer
callback
timer...
CPA #14
CPA #14
Localization
/EKF Localizer
Localization/EKF...
CPA #18
CPA #18
subscription
callback
subscription...
CPA #19
CPA #19
subscription
callback
subscription...
CPA #20
CPA #20
CPA #21
CPA #21
CPA #15
CPA #15
CPA #22
CPA #22
subscription
callback
subscription...
CPA #23
CPA #23
CPA #24
CPA #24
CPA #25
CPA #25
inter-component
communication
inter-componentcom...
intra-component
communication
intra-componentcom...
CPA #26
CPA #26
callbacks denote when input messages are consumed rather than received.
callbacks denote when inpu...
a chain of callback driven by a timer
a chain of callback dr...
a chain of callback driven by a timer
a chain of callback dr...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/running-autoware-without-cuda.md b/docs/how-to-guides/others/running-autoware-without-cuda.md similarity index 100% rename from docs/how-to-guides/running-autoware-without-cuda.md rename to docs/how-to-guides/others/running-autoware-without-cuda.md diff --git a/docs/index.md b/docs/index.md index 07310033b23..5ddf5639734 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,12 @@ Autoware is the world’s leading open-source software project for autonomous dr Please see [here](https://www.autoware.org/autoware) for more details. +## Related Documentations + +This [Autoware Documentation](https://autowarefoundation.github.io/autoware-documentation/) is for Autoware's general information. + +For detailed documents of Autoware Universe components, see [Autoware Universe Documentation](https://autowarefoundation.github.io/autoware.universe/). + ## Getting started - [Installation](installation) pages explain the installation steps of Autoware and related tools. @@ -15,3 +21,4 @@ Please see [here](https://www.autoware.org/autoware) for more details. - [Contributing](contributing) pages explain how to contribute to Autoware. - [Datasets](datasets) pages contain information about datasets that can be used with Autoware. - [Support](support) pages explain several support resources. +- [Competitions](autoware-competitions) pages explain on-going challenges related to AWF diff --git a/docs/installation/additional-settings-for-developers/index.md b/docs/installation/additional-settings-for-developers/index.md index 3ba67d6f751..1379d9c2992 100644 --- a/docs/installation/additional-settings-for-developers/index.md +++ b/docs/installation/additional-settings-for-developers/index.md @@ -1,6 +1,6 @@ # Additional settings for developers -## ROS 2 settings +## Console settings for ROS 2 ### Colorizing logger output @@ -22,16 +22,49 @@ export RCUTILS_CONSOLE_OUTPUT_FORMAT="[{severity} {time}] [{name}]: {message} ({ For more options, see [here](https://docs.ros.org/en/rolling/Tutorials/Logging-and-logger-configuration.html#console-output-formatting). -### Enabling localhost-only communication +## Network settings for ROS 2 -By default, ROS 2 communicates using multi-cast, which may unnecessarily increase the network traffic. -To avoid it, write the following in your `.bashrc`: +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](http://design.ros2.org/articles/ros_on_dds.html). + +### ROS 2 network setting + +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. + +#### Enabling localhost-only communication + +Write the following in your `.bashrc`: +For more information, see the [ROS 2 documentation](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#the-ros-localhost-only-variable). ```bash export ROS_LOCALHOST_ONLY=1 ``` -### Setting up `ROS_DOMAIN_ID` +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. + +```console +$ ip link show lo +1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 +``` + +If the word `MULTICAST` is not printed, use the following command to enable it. + +```bash +sudo ip link set lo multicast on +``` + +#### Same domain only communication on the local network 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. @@ -44,4 +77,60 @@ To avoid it, set a different domain ID for each group in your `.bashrc`: export ROS_DOMAIN_ID=X ``` -For more information, see [here](https://docs.ros.org/en/foxy/Concepts/About-Domain-ID.html#the-ros-domain-id). +Also confirm that `ROS_LOCALHOST_ONLY` is `0` by using the following command. + +```bash +echo $ROS_LOCALHOST_ONLY # If the output is 1, localhost has priority. +``` + +For more information, see the [ROS 2 Documentation](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#the-ros-domain-id-variable). + +### DDS settings + +Autoware uses DDS for inter-node communication. [ROS 2 documentation](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html) 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. + +#### Tuning DDS + +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 + + + + + + + + default + 65500B + + + + + 500kB + + + + +``` + +This configuration is mostly taken from [Eclipse Cyclone DDS:Run-time configuration documentation](https://github.com/eclipse-cyclonedds/cyclonedds/tree/a10ced3c81cc009e7176912190f710331a4d6caf#run-time-configuration). +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. + +```bash +export CYCLONEDDS_URI=file:///absolute/path/to/cyclonedds_config.xml +sudo sysctl -w net.core.rmem_max=2147483647 +``` + +For more information, Refer to [ROS 2 documentation](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html). Reading user guide for chosen DDS is helpful for more understanding. + +#### Tuning DDS for multiple host computers (for advanced users) + +When Autoware runs on multiple host computers, IP Fragmentation should be taken into account. As [ROS 2 documentation](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html#cross-vendor-tuning) recommends, parameters for IP Fragmentation should be set as shown in the following example. + +```bash +sudo sysctl -w net.ipv4.ipfrag_time=3 +sudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728 # (128 MB) +``` diff --git a/docs/installation/autoware/docker-installation-devel.md b/docs/installation/autoware/docker-installation-devel.md new file mode 100644 index 00000000000..0dd77b04a2f --- /dev/null +++ b/docs/installation/autoware/docker-installation-devel.md @@ -0,0 +1,152 @@ +# Docker installation for development + +## Prerequisites + +- [Git](https://git-scm.com/) + +- For NVIDIA Jetson devices, install [JetPack](https://docs.nvidia.com/jetson/jetpack/install-jetpack/index.html#how-to-install-jetpack) >= 5.0 + +## How to set up a development environment + +1. Clone `autowarefoundation/autoware` and move to the directory. + + ```bash + git clone https://github.com/autowarefoundation/autoware.git + cd autoware + ``` + +2. 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](https://docs.nvidia.com/cuda/eula/index.html) + +### Installing dependencies manually + +- [Install Nvidia CUDA](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda#manual-installation) +- [Install Docker Engine](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/docker_engine#manual-installation) +- [Install NVIDIA Container Toolkit](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/nvidia_docker#manual-installation) +- [Install rocker](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rocker#manual-installation) + +### Installing dependencies using Ansible + +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. + +```bash +./setup-dev-env.sh docker +``` + +You might need to log out and log back to make the current user able to use docker. + +## How to set up a workspace + +!!! warning + + Before proceeding, confirm and agree with the [NVIDIA Deep Learning Container license](https://developer.nvidia.com/ngc/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. + + ```bash + mkdir ~/autoware_map + ``` + +2. Pull the Docker image + + ```bash + docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda + ``` + +3. Launch a Docker container. + + - For amd64 architecture computers with NVIDIA GPU: + + ```bash + rocker --nvidia --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda + ``` + + - If you want to run container without using NVIDIA GPU, or for arm64 architecture computers: + + ```bash + rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda + ``` + + For detailed reason could be found [here](./docker-installation.md#docker-with-nvidia-gpu-fails-to-start-autoware-on-arm64-devices) + + For more advanced usage, see [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md). + + After that, move to the workspace in the container: + + ```bash + cd autoware + ``` + +4. Create the `src` directory and clone repositories into it. + + ```bash + mkdir src + vcs import src < autoware.repos + ``` + +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. + + ```bash + sudo apt update + rosdep update + rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO + ``` + +6. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + + If there is any build issue, refer to [Troubleshooting](../../support/troubleshooting/index.md#build-issues). + +## How to update a workspace + +1. Update the Docker image. + + ```bash + docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda + ``` + +2. Launch a Docker container. + + - For amd64 architecture computers: + + ```bash + rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda + ``` + + - If you want to run container without using NVIDIA GPU, or for arm64 architecture computers: + + ```bash + rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda + ``` + +3. Update the `.repos` file. + + ```bash + cd autoware + git pull + ``` + +4. Update the repositories. + + ```bash + vcs import src < autoware.repos + vcs pull src + ``` + +5. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` diff --git a/docs/installation/autoware/docker-installation-prebuilt.md b/docs/installation/autoware/docker-installation-prebuilt.md new file mode 100644 index 00000000000..40d4700d9b1 --- /dev/null +++ b/docs/installation/autoware/docker-installation-prebuilt.md @@ -0,0 +1,35 @@ +# Docker installation for quick start + +## How to set up a development environment + +1. Installing dependencies manually + + - [Install Docker Engine](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/docker_engine#manual-installation) + + - [Install NVIDIA Container Toolkit](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/nvidia_docker#manual-installation) + + - [Install rocker](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rocker#manual-installation) + +## How to set up a workspace + +1. Create the `autoware_map` directory for map data later. + + ```bash + mkdir ~/autoware_map + ``` + +2. Launch a Docker container. + + ```bash + rocker --nvidia --x11 --user --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-prebuilt + ``` + + For more advanced usage, see [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md). + +3. Run Autoware simulator + + Inside the container, you can run the Autoware simulation by following this tutorial: + + [planning simulation](../../tutorials/ad-hoc-simulation/planning-simulation.md) + + [rosbag replay simulation](../../tutorials/ad-hoc-simulation/rosbag-replay-simulation.md). diff --git a/docs/installation/autoware/docker-installation.md b/docs/installation/autoware/docker-installation.md index 0e2ff7d7274..eae63229ff5 100644 --- a/docs/installation/autoware/docker-installation.md +++ b/docs/installation/autoware/docker-installation.md @@ -4,156 +4,23 @@ Since this page explains Docker-specific information, it is recommended to see [Source installation](./source-installation.md) as well if you need detailed information. -## Prerequisites +Here are two ways to install Autoware by docker: -- [Git](https://git-scm.com/) +- 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 -- For NVIDIA Jetson devices, install [JetPack](https://docs.nvidia.com/jetson/jetpack/install-jetpack/index.html#how-to-install-jetpack) >= 5.0 +- The second way is to start Autoware with `devel image`, which supports developing and running Autoware using docker -## How to set up a development environment +## Docker installation for quick start -1. Clone `autowarefoundation/autoware` and move to the directory. +[docker installation for quick start](./docker-installation-prebuilt.md) - ```bash - git clone https://github.com/autowarefoundation/autoware.git - cd autoware - ``` +![type:video](https://youtube.com/embed/3KUhEFkEbI8) - If you want to use ROS 2 Humble, use the `humble` branch. +## Docker installation for development - ```bash - git clone https://github.com/autowarefoundation/autoware.git -b humble - cd autoware - ``` +[docker installation for development](./docker-installation-devel.md) -2. You can install the dependencies either manually or using the provided Ansible script. - -### Installing dependencies manually - -- [Install Docker Engine](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/docker_engine#manual-installation) -- [Install NVIDIA Container Toolkit](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/nvidia_docker#manual-installation) -- [Install rocker](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rocker#manual-installation) - -### Installing dependencies using Ansible - -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. - -```bash -./setup-dev-env.sh docker -``` - -You might need to log out and log back to make the current user able to use docker. - -## How to set up a workspace - -!!! warning - - Before proceeding, confirm and agree with the [NVIDIA Deep Learning Container license](https://developer.nvidia.com/ngc/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. - - ```bash - mkdir ~/autoware_map - ``` - -2. Launch a Docker container. - - - For amd64 architecture computers with NVIDIA GPU: - - ```bash - rocker --nvidia --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - - - If you want to use ROS 2 Humble: - - ```bash - rocker --nvidia --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda - ``` - - - If you want to run container without using NVIDIA GPU, or for arm64 architecture computers: - - ```bash - rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - - For detailed reason could be found [here](#docker-with-nvidia-gpu-fails-to-start-autoware-on-arm64-devices) - - For more advanced usage, see [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md). - - After that, move to the workspace in the container: - - ```bash - cd autoware - ``` - -3. Create the `src` directory and clone repositories into it. - - ```bash - mkdir src - vcs import src < autoware.repos - ``` - -4. 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. - - ```bash - sudo apt update - rosdep update - rosdep install --from-paths . --ignore-src --rosdistro $ROS_DISTRO - ``` - -5. Build the workspace. - - ```bash - colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release - ``` - -## How to update a workspace - -1. Update the Docker image. - - ```bash - docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - -2. Launch a Docker container. - - - For amd64 architecture computers: - - ```bash - rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - - - If you want to run container without using NVIDIA GPU, or for arm64 architecture computers: - - ```bash - rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - -3. Update the `.repos` file. - - ```bash - cd autoware - git pull - ``` - -4. Update the repositories. - - ```bash - vcs import src < autoware.repos - vcs pull src - ``` - -5. Build the workspace. - - ```bash - colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release - ``` +![type:video](https://youtube.com/embed/UrSF-VwncGQ) ## Troubleshooting @@ -177,7 +44,7 @@ To fix this, restart your system after installing the new NVIDIA driver. 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: ```bash -nvidia@xavier:~$ rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:galactic-latest-cuda-arm64 +nvidia@xavier:~$ rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64 ... Collecting staticx==0.12.3 @@ -233,7 +100,7 @@ aarch64 To run Autoware's Docker images of `arm64` architecture, add the suffix `-arm64`. ```sh-session -$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:galactic-latest-cuda-arm64 +$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64 WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested root@5b71391ad50f:/autoware# ``` diff --git a/docs/installation/autoware/source-installation.md b/docs/installation/autoware/source-installation.md index 207d0c11842..900833b7bb8 100644 --- a/docs/installation/autoware/source-installation.md +++ b/docs/installation/autoware/source-installation.md @@ -4,12 +4,10 @@ - OS - - [Ubuntu 20.04](https://releases.ubuntu.com/20.04/) - [Ubuntu 22.04](https://releases.ubuntu.com/22.04/) - ROS - - ROS 2 Galactic - ROS 2 Humble For ROS 2 system dependencies, refer to [REP-2000](https://www.ros.org/reps/rep-2000.html). @@ -22,6 +20,8 @@ sudo apt-get -y update sudo apt-get -y install git ``` +> Note: If you wish to use ROS 2 Galactic on Ubuntu 20.04, refer to installation instruction from [galactic](https://autowarefoundation.github.io/autoware-documentation/galactic/installation/autoware/source-installation/) branch, but be aware that Galactic version of Autoware might not have latest features. + ## How to set up a development environment 1. Clone `autowarefoundation/autoware` and move to the directory. @@ -31,42 +31,35 @@ sudo apt-get -y install git cd autoware ``` - If you want to use ROS 2 Humble, use the `humble` branch. +2. If you are installing Autoware for the first time, you can automatically install the dependencies by using the provided Ansible script. ```bash - git clone https://github.com/autowarefoundation/autoware.git -b humble - cd autoware + ./setup-dev-env.sh ``` -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](https://docs.nvidia.com/cuda/eula/index.html) -- [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/sla/index.html) -- [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/sla/index.html) + If you encounter any build issues, please consult the [Troubleshooting](../../support/troubleshooting/index.md#build-issues) section for assistance. -### Installing dependencies manually +!!! info -- [Install ROS 2](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2#manual-installation) -- [Install ROS 2 Dev Tools](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2_dev_tools#manual-installation) -- [Install the RMW Implementation](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation#manual-installation) -- [Install pacmod](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pacmod#manual-installation) -- [Install Autoware Core dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_core#manual-installation) -- [Install Autoware Universe dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_universe#manual-installation) -- [Install pre-commit dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pre_commit#manual-installation) -- [Install Nvidia CUDA](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda#manual-installation) -- [Install Nvidia cuDNN and TensorRT](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/tensorrt#manual-installation) + Before installing NVIDIA libraries, please ensure that you have reviewed and agreed to the licenses. -### Installing dependencies using Ansible + - [CUDA](https://docs.nvidia.com/cuda/eula/index.html) + - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/sla/index.html) + - [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/sla/index.html) -Be very careful with this method. Make sure you read and confirmed all the steps in the Ansible configuration before using it. +!!! note -If you've manually installed the dependencies, you can skip this section. + 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. -```bash -./setup-dev-env.sh -``` + - [Install ROS 2](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2#manual-installation) + - [Install ROS 2 Dev Tools](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2_dev_tools#manual-installation) + - [Install the RMW Implementation](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation#manual-installation) + - [Install pacmod](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pacmod#manual-installation) + - [Install Autoware Core dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_core#manual-installation) + - [Install Autoware Universe dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_universe#manual-installation) + - [Install pre-commit dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pre_commit#manual-installation) + - [Install Nvidia CUDA](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda#manual-installation) + - [Install Nvidia cuDNN and TensorRT](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/tensorrt#manual-installation) ## How to set up a workspace @@ -87,7 +80,7 @@ If you've manually installed the dependencies, you can skip this section. You might need to run `rosdep update` before `rosdep install`. ```bash - source /opt/ros/galactic/setup.bash + source /opt/ros/humble/setup.bash rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO ``` @@ -100,15 +93,19 @@ If you've manually installed the dependencies, you can skip this section. colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release ``` + If there is any build issue, refer to [Troubleshooting](../../support/troubleshooting/index.md#build-issues). + ## How to update a workspace 1. Update the `.repos` file. ```bash cd autoware - git pull + git pull ``` + `` is usually `git@github.com:autowarefoundation/autoware.git` + 2. Update the repositories. ```bash @@ -128,7 +125,7 @@ If you've manually installed the dependencies, you can skip this section. 3. Install dependent ROS packages. ```bash - source /opt/ros/galactic/setup.bash + source /opt/ros/humble/setup.bash rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO ``` diff --git a/docs/installation/index.md b/docs/installation/index.md index 82e83c4103d..7b99b35577f 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -29,13 +29,13 @@ The Autoware Foundation provides no support on other platforms than those listed > - 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](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/running-autoware-without-cuda/). +For details of how to enable object detection and traffic light detection/classification without a GPU, refer to the [Running Autoware without CUDA](../how-to-guides/others/running-autoware-without-cuda.md). ## Installing Autoware 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](https://autowarefoundation.github.io/autoware-documentation/main/support). +If any issues occur during installation, refer to the [Support page](../support). ### 1. Docker installation @@ -47,7 +47,7 @@ For more information, refer to the [Docker installation guide](autoware/docker-i ### 2. Source installation 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. +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](autoware/source-installation.md). diff --git a/docs/reference-hw/.pages b/docs/reference-hw/.pages new file mode 100644 index 00000000000..adb1a5ea36a --- /dev/null +++ b/docs/reference-hw/.pages @@ -0,0 +1,12 @@ +nav: + - index.md + - ad-computers.md + - lidars.md + - radars.md + - cameras.md + - thermal_cameras.md + - imu_ahrs_gnss_ins.md + - vehicle_drive_by_wire_suppliers.md + - vehicle_platform_suppliers.md + - remote_drive.md + - full_drivers_list.md diff --git a/docs/reference-hw/ad-computers.md b/docs/reference-hw/ad-computers.md new file mode 100644 index 00000000000..af39cbd9bb9 --- /dev/null +++ b/docs/reference-hw/ad-computers.md @@ -0,0 +1,47 @@ +# AD Computers + +## **ADLINK In-Vehicle Computers** + +ADLINK solutions which is used for autonomous driving and tested by one or more community members are listed below: + + + +| Supported Products List | CPU | GPU | RAM, Interfaces | Environmental | Autoware Tested (Y/N) | +| ------------------------------- | ------------------------------ | ------------------------ | ------------------------------------------------------------ | ---------------------------------------------- | --------------------- | +| AVA-351001 | Intel® Xeon® E-2278GE | Dual RTX 5000 | 64GB RAM,CAN, USB, 10G Ethernet, DIO, Hot-Swap SSD, USIM | 9~36 VDC, MIL-STD-810H,ISO 7637-2 & SAE 113-11 | Y | +| SOAFEE’s AVA Developer Platform | Ampere Altra ARMv8 | optional | USB, Ethernet, DIO, M.2 NVMe SSDs | 110/220 AC | Y | +| RQX-58G | Carmel ARMv8.2 2.26GHz | Nvidia Jetson AGX Xavier | USB, Ethernet, M.2 NVME SSD, CAN, USIM, GMSL2 Camera support | 9~36VDC | Y | +| RQX-59G | 8-core Arm® Cortex®-A78AE v8.2 | Nvidia Jetson AGX Orin | USB, Ethernet, M.2 NVME SSD, CAN, USIM, GMSL2 Camera support | 9~36VDC | N | +| SOAFEE’s AVA AP1 | Ampere Altra ARMv8 | optional | CAN, USB, Ethernet, DIO, M.2 NVMe SSDs | 12 Volt | Y | + +Link to company website is [here.](https://www.adlinktech.com/en/Connected-Autonomous-Vehicle-Solutions) + +## **NXP In-Vehicle Computers** + +NXP solutions which is used for autonomous driving and tested by one or more community members are listed below: + +| Supported Products List | CPU | GPU | RAM, Interfaces | Environmental | Autoware Tested (Y/N) | +| ----------------------- | --------------------- | -------------------------- | ----------------------------------------------- | ------------- | --------------------- | +| BLUEBOX 3.0 | 16 x Arm® Cortex®-A72 | Dual RTX 8000 or RTX A6000 | 16 GB RAM CAN, FlexRay, USB, Ethernet, DIO, SSD | ASIL-D | - | + +Link to company website is [here.](https://www.nxp.com/design/designs/bluebox-3-0-automotive-high-performance-compute-ahpc-development-platform:BlueBox) + +## **Neousys In-Vehicle Computers** + +Neousys solutions which is used for autonomous driving and tested by one or more community members are listed below: + +| Supported Products List | CPU | GPU | RAM, Interfaces | Environmental | Autoware Tested (Y/N) | +| ----------------------- | --------------------- | --------------------------- | --------------------------------------------------- | ----------------------------------------------- | --------------------- | +| 8208-GC | Intel® Xeon® E-2278GE | Dual RTX 2080ti or RTX 3070 | 128 GB RAM,CAN, USB, Ethernet, Serial, Hot-Swap SSD | 8-35 VoltVibration:MIL-STD810G 5-500 Hz, 3 axes | - | + +Link to company website is [here.](http://bit.ly/neousys8208GC) + +## **Crystal Rugged In-Vehicle Computers** + +Crystal Rugged solutions which is used for autonomous driving and tested by one or more community members are listed below: + +| Supported Products List | CPU | GPU | RAM, Interfaces | Environmental | Autoware Tested (Y/N) | +| ----------------------- | --------------------- | ------------------- | ------------------------------------------------ | ---------------------------------------------- | --------------------- | +| AVC 0161-AC | Intel® Xeon® Scalable | Dual GPU RTX Series | 2TB RAM,CAN, USB, Ethernet, Serial, Hot-Swap SSD | 10-32 VoltVibration:2 G RMS 10-1000 Hz, 3 axes | - | + +Link to company website is [here.](https://www.crystalrugged.com/product/AVC0161-Ai-Autonomy-Solution/) diff --git a/docs/reference-hw/cameras.md b/docs/reference-hw/cameras.md new file mode 100644 index 00000000000..3f5faaf1d1c --- /dev/null +++ b/docs/reference-hw/cameras.md @@ -0,0 +1,44 @@ +# CAMERAs + +## **FLIR Machine Vision Cameras** + +FLIR Machine Vision cameras which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | MP | FPS | Interface | Sensor Format | Lens | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ------------ | ---------- | --------- | ------------- | ------ | ------------ | --------------------- | +| Blackfly S | 2.0
5.0 | 22
95 | USB-GigE | 1” - ⅔” | C & CS | Y | - | +| Grasshopper3 | 2.3
5.0 | 26
90 | USB-GigE | 1” - ⅔” | C & CS | Y | - | + +Link to ROS 2 driver: +[https://github.com/berndpfrommer/flir_spinnaker_ros2](https://github.com/berndpfrommer/flir_spinnaker_ros2) + +Link to company website: +[https://www.flir.eu/iis/machine-vision/](https://www.flir.eu/iis/machine-vision/) + +## **Lucid Vision Cameras** + +Lucid Vision cameras which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | MP | FPS | Interface | Sensor Format | Lens | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | --- | ---- | --------- | ------------- | ------- | ------------ | --------------------- | +| TRITON 054S | 5.4 | 22 | GigE | 1/1.55” | C Mount | Y | Y | +| TRITON 032S | 3.2 | 35.4 | GigE | 1/1.8” | C Mount | Y | Y | + +Link to ROS 2 driver: +[https://gitlab.com/leo-drive/Drivers/arena_camera](https://gitlab.com/leo-drive/Drivers/arena_camera) +Link to company website: +[https://thinklucid.com/triton-gige-machine-vision/](https://thinklucid.com/triton-gige-machine-vision/) + +## **Allied Vision Cameras** + +Allied Vision cameras which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | MP | FPS | Interface | Sensor Format | Lens | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | --- | ---- | --------- | ------------- | ------- | ------------ | --------------------- | +| Mako G319 | 3.2 | 37.6 | GigE | 1/1.8” | C Mount | Y | - | + +Link to ROS 2 driver: +[https://github.com/neil-rti/avt_vimba_camera](https://github.com/neil-rti/avt_vimba_camera) + +Link to company website: +[https://www.alliedvision.com/en/products/camera-series/mako-g](https://www.alliedvision.com/en/products/camera-series/mako-g) diff --git a/docs/reference-hw/full_drivers_list.md b/docs/reference-hw/full_drivers_list.md new file mode 100644 index 00000000000..b4027184774 --- /dev/null +++ b/docs/reference-hw/full_drivers_list.md @@ -0,0 +1,19 @@ +# Drivers List + +The list of all drivers listed above for easy access as a table with additional information: + +| Type | Maker | Driver links | License | Maintainer | +| ------ | ------------- | ------------------------------------------------------------------------------ | -------- | -------------------------------------------- | +| Lidar | Velodyne | [Link](https://github.com/ros-drivers/velodyne/tree/ros2/velodyne_pointcloud) | BSD | jwhitley@autonomoustuff.com | +| Lidar | Robosense | [Link](https://github.com/RoboSense-LiDAR/rslidar_sdk) | BSD | zdxiao@robosense.cn | +| Lidar | Hesai | [Link](https://github.com/HesaiTechnology/HesaiLidar_General_ROS) | Apache 2 | wuxiaozhou@hesaitech.com | +| Lidar | Leishen | [Link](https://github.com/leishen-lidar) | - | - | +| Lidar | Livox | [Link](https://github.com/Livox-SDK/livox_ros2_driver) | MIT | dev@livoxtech.com | +| Lidar | Ouster | [Link](https://github.com/ros-drivers/ros2_ouster_drivers) | Apache 2 | stevenmacenski@gmail.com, tom@boxrobotics.ai | +| Radar | smartmicro | [Link](https://github.com/smartmicro/smartmicro_ros2_radars) | Apache 2 | opensource@smartmicro.de | +| Camera | Flir | [Link](https://github.com/berndpfrommer/flir_spinnaker_ros2) | Apache 2 | bernd.pfrommer@gmail.com | +| Camera | Lucid Vision | [Link](https://gitlab.com/leo-drive/Drivers/arena_camera) | - | kcolak@leodrive.ai | +| Camera | Allied Vision | [Link](https://github.com/neil-rti/avt_vimba_camera) | Apache 2 | at@email.com | +| GNSS | NovAtel | [Link](https://github.com/swri-robotics/novatel_gps_driver/tree/dashing-devel) | BSD | preed@swri.org | +| GNSS | SBG Systems | [Link](https://github.com/SBG-Systems/sbg_ros2_driver) | MIT | support@sbg-systems.com | +| GNSS | PolyExplore | [Link](https://github.com/polyexplore/ROS2_Driver) | - | support@polyexplore.com | diff --git a/docs/reference-hw/images/platforms.png b/docs/reference-hw/images/platforms.png new file mode 100644 index 00000000000..195c976f4cd Binary files /dev/null and b/docs/reference-hw/images/platforms.png differ diff --git a/docs/reference-hw/imu_ahrs_gnss_ins.md b/docs/reference-hw/imu_ahrs_gnss_ins.md new file mode 100644 index 00000000000..082d6e93610 --- /dev/null +++ b/docs/reference-hw/imu_ahrs_gnss_ins.md @@ -0,0 +1,78 @@ +# IMU, AHRS & GNSS/INS + +## **NovAtel GNSS/INS Sensors** + +NovAtel GNSS/INS sensors which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | INS Rate | Roll, Pitch, Yaw Acc. | GNSS | ROS 2 Driver  | Autoware Tested (Y/N) | +| ----------------------- | -------- | -------------------------------------- | --------------------------------------- | ------------- | --------------------- | +| PwrPak7D-E2 | 200 Hz | R (0.013°)
P (0.013°)
Y (0.070°) | 20 Hz
L1 / L2 / L5
555 Channels | Y | - | +| Span CPT7 | 200 Hz | R (0.01°) 
P (0.01°) 
Y (0.03°) | 20 Hz
L1 / L2 / L5
555 Channels | Y | - | + +Link to ROS 2 driver: +[https://github.com/swri-robotics/novatel_gps_driver/tree/dashing-devel](https://github.com/swri-robotics/novatel_gps_driver/tree/dashing-devel) + +Link to company website: +[https://hexagonpositioning.com/](https://hexagonpositioning.com/) + +## **XSens GNSS/INS & IMU Sensors** + +XSens GNSS/INS sensors which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | INS/IMU Rate | Roll, Pitch, Yaw Acc. | GNSS | ROS 2 Driver  | Autoware Tested (Y/N) | +| ----------------------- | ------------ | -------------------------------- | -------------------------------- | ------------- | --------------------- | +| MTi-680G | 2 kHz | R (0.2°)
P (0.2°)
Y (0.5°) | 5 Hz
L1 / L2 
184 Channels | Y | - | +| MTi-300 AHRS | 2 kHz | R (0.2°)
P (0.2°)
Y (1°) | Not Applicable | Y | - | + +Link to ROS 2 driver: +[http://wiki.ros.org/xsens_mti_driver](http://wiki.ros.org/xsens_mti_driver) + +Link to company website: +[https://www.xsens.com/](https://www.xsens.com/) + +## **SBG GNSS/INS & IMU Sensors** + +SBG GNSS/INS sensors which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | INS/IMU Rate | Roll, Pitch, Yaw Acc. | GNSS | ROS 2 Driver  | Autoware Tested (Y/N) | +| ----------------------- | ------------------- | --------------------------------- | ------------------------------- | ------------- | --------------------- | +| Ellipse-D | 200 Hz, 1 kHz (IMU) | R (0.1°)
P (0.1°)
Y (0.05°) | 5 Hz
L1 / L2
184 Channels | Y | Y | +| Ellipse-A (AHRS) | 200 Hz, 1 kHz (IMU) | R (0.1°)
P (0.1°)
Y (0.8°) | Not Applicable | Y | - | + +Link to ROS 2 driver: +[https://github.com/SBG-Systems/sbg_ros2](https://github.com/SBG-Systems/sbg_ros2) + +Link to company website: +[https://www.sbg-systems.com/products/ellipse-series/](https://www.sbg-systems.com/products/ellipse-series/) + +## **Applanix GNSS/INS Sensors** + + + +SBG GNSS/INS sensors which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | INS/IMU Rate | Roll, Pitch, Yaw Acc. | GNSS | ROS 2 Driver  | Autoware Tested (Y/N) | +| ----------------------- | ------------ | ----------------------------------- | ---------------------------- | ------------- | --------------------- | +| POSLVX | 200 Hz | R (0.03°)
P (0.03°)
Y (0.09°) | L1 / L2 / L5
336 Channels | Y | Y | +| POSLV220 | 200 Hz | R (0.02°)
P (0.02°)
Y (0.05°) | L1 / L2 / L5
336 Channels | Y | Y | + +Link to ROS 2 driver: +[http://wiki.ros.org/applanix_driver](http://wiki.ros.org/applanix_driver) + +Link to company website: +[https://www.applanix.com/products/poslv.htm](https://www.applanix.com/products/poslv.htm) + +## **PolyExplore GNSS/INS Sensors** + +PolyExplore GNSS/INS sensors which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | INS/IMU Rate | Roll, Pitch, Yaw Acc. | GNSS | ROS 2 Driver  | Autoware Tested (Y/N) | +| ----------------------- | ------------ | ------------------------------------- | ----------------------- | ------------- | --------------------- | +| POLYNAV 2000P | 100 Hz | R (0.01°)
P (0.01°)
Y (0.1°) | L1 / L2
240 Channels | Y | - | +| POLYNAV 2000S | 100 Hz | R (0.015°)
P (0.015°)
Y (0.08°) | L1 / L2
40 Channels | Y | - | + +Link to ROS 2 driver: +[https://github.com/polyexplore/ROS2_Driver](https://github.com/polyexplore/ROS2_Driver) + +Link to company website: +[https://www.polyexplore.com/](https://www.polyexplore.com/) diff --git a/docs/reference-hw/index.md b/docs/reference-hw/index.md new file mode 100644 index 00000000000..ead8e0a6188 --- /dev/null +++ b/docs/reference-hw/index.md @@ -0,0 +1,71 @@ +# Reference HW Design + +This document is created to describe and give additional information of the sensors and systems supported by Autoware.Auto software. + +All equipment listed in this document has available ROS 2 drivers and has been tested by one or more of the community members on field in autonomous vehicle and robotics applications. + +The listed sensors and systems are not sold, developed or given direct technical support by the Autoware community. Having said that any ROS 2 and Autoware related issue regarding the hardware usage could be asked using the community guidelines which found [here.](https://answers.ros.org/questions/ask/?tags=autoware) + +The documents consists of the sections listed below: + +- AD COMPUTERs + + - ADLINK In-Vehicle Computers + - NXP In-Vehicle Computers + - Neousys In-Vehicle Computers + - Crystal Rugged In-Vehicle Computers + +- LiDARs + + - Velodyne 3D LiDAR Sensors + - Robosense 3D LiDAR Sensors + - HESAI 3D LiDAR Sensors + - Leishen 3D LiDAR Sensors + - Livox 3D LiDAR Sensors + - Ouster 3D LiDAR Sensors + +- RADARs + + - Smartmicro Automotive Radars + - Aptiv Automotive Radars + - Continental Engineering Radars + +- CAMERAs + + - FLIR Machine Vision Cameras + - Lucid Vision Cameras + - Allied Vision Cameras + +- Thermal CAMERAs + + - FLIR Thermal Automotive Dev. Kit + +- IMU, AHRS & GNSS/INS + + - NovAtel GNSS/INS Sensors + - XSens GNSS/INS & IMU Sensors + - SBG GNSS/INS & IMU Sensors + - Applanix GNSS/INS Sensors + - PolyExplore GNSS/INS Sensors + +- Vehicle Drive By Wire Suppliers + + + - New Eagle DBW Solutions + - Dataspeed DBW Solutions + - AStuff Pacmod DBW Solutions + - Schaeffler-Paravan Space Drive DBW Solutions + +- Vehicle Platform Suppliers + + - PIX MOVING Autonomous Vehicle Solutions + - Autonomoustuff AV Solutions + - NAVYA AV Solutions + - ZING ROBOTICS AV Solutions + +- Remote Drive + + - FORT ROBOTICS + - LOGITECH + +- Full Drivers List diff --git a/docs/reference-hw/lidars.md b/docs/reference-hw/lidars.md new file mode 100644 index 00000000000..5b967b34527 --- /dev/null +++ b/docs/reference-hw/lidars.md @@ -0,0 +1,104 @@ +# LIDARs + +## **Velodyne 3D LIDAR Sensors** + +Velodyne Lidars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (V), (H) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ----- | --------------------- | ------------ | --------------------- | +| Alpha Prime | 245m | (+15°)/(-25°), (360°) | Y | Y | +| Ultra Puck | 200m | (+15°)/(-25°), (360°) | Y | Y | +| Puck | 100m | (+15°)/(-15°), (360°) | Y | Y | +| Puck Hi-res | 100m | (+10°)/(-10°), (360°) | Y | Y | + +Link to ROS 2 drivers: + [https://github.com/ros-drivers/velodyne/tree/ros2/velodyne_pointcloud](https://github.com/ros-drivers/velodyne/tree/ros2/velodyne_pointcloud) + [https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/tree/master/src/drivers/velodyne_nodes](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/tree/master/src/drivers/velodyne_nodes) +[https://github.com/autowarefoundation/awf_velodyne/tree/tier4/universe](https://github.com/autowarefoundation/awf_velodyne/tree/tier4/universe) + +Link to company website: +[https://velodynelidar.com/](https://velodynelidar.com/) + +## **RoboSense 3D LIDAR Sensors** + +RoboSense Lidars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (V), (H) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ----- | -------------------- | ------------ | --------------------- | +| RS-Ruby | 250m | (+15°)/(-25°), (360) | Y | - | +| RS-Ruby-Lite | 230m | (+15°)/(-25°), (360) | Y | - | +| RS-LiDAR-32 | 200m | (+15°)/(-25°), (360) | Y | - | +| RS-LiDAR-16 | 150m | (+15°)/(-15), (360) | Y | - | + +Link to ROS 2 driver: +[https://github.com/RoboSense-LiDAR/rslidar_sdk](https://github.com/RoboSense-LiDAR/rslidar_sdk) + +Link to company website: +[https://www.robosense.ai/](https://www.robosense.ai/) + +## **HESAI 3D LIDAR Sensors** + +Hesai Lidars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (V), (H) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ----- | ---------------------- | ------------ | --------------------- | +| Pandar 128 | 200m | (+15°)/(-25°), (360°) | Y | - | +| Pandar 64 | 200m | (+15°)/(-25°), (360°) | Y | - | +| Pandar XT | 120m | (+15°)/(-16°), (360°) | Y | - | +| Pandar QT | 20m | (-52.1°/+52.1°)/(360°) | Y | - | + +Link to ROS 2 driver: +[https://github.com/HesaiTechnology/HesaiLidar_General_ROS](https://github.com/HesaiTechnology/HesaiLidar_General_ROS) + +Link to company website: +[https://www.hesaitech.com/en/](https://www.hesaitech.com/en/) + +## **Leishen 3D LIDAR Sensors** + +Leishen Lidars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (V), (H) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ----- | -------------------- | ------------ | --------------------- | +| LS C16 | 150m | (+15°/-15°), (360°) | Y | - | +| LS C32  | 150m | (+15°/-15°), (360°) | Y | - | +| CH 32 | 120m | (+3.7°/-6.7°),(120°) | Y | - | +| CH 128 | 20m | (+14°/-17°)/(150°) | Y | - | + +Link to ROS 2 driver: +[https://github.com/leishen-lidar](https://github.com/leishen-lidar) + +Link to company website: +[http://www.lslidar.com/](http://www.lslidar.com/) + +## **Livox 3D LIDAR Sensors** + +Livox Lidars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (V), (H) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ----- | ----------------- | ------------ | --------------------- | +| Horizon | 260m | (81.7°), (25.1°) | Y | Y | +| Mid-70 | 90m | (70.4°), (77.2°) | Y | - | +| Avia | 190m | (70.4°), Circular | Y | - | +| HAP | 150m | (25°), (120°) | - | - | + +Link to ROS 2 driver: +[https://github.com/Livox-SDK/livox_ros2_driver](https://github.com/Livox-SDK/livox_ros2_driver) + +Link to company website: +[https://www.livoxtech.com/](https://www.livoxtech.com/) + +## **Ouster 3D LIDAR Sensors** + +Ouster Lidars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (V), (H) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ----- | --------------- | ------------ | --------------------- | +| OS0 | 50m | (90°), (360°) | Y | - | +| OS1 | 120m | (45°), (360°) | Y | - | +| OS2 | 240m | (22,5°), (360°) | Y | Y | + +Link to ROS 2 driver: +[https://github.com/ros-drivers/ros2_ouster_drivers](https://github.com/ros-drivers/ros2_ouster_drivers) + +Link to company website: +[https://ouster.com/](https://ouster.com/) diff --git a/docs/reference-hw/radars.md b/docs/reference-hw/radars.md new file mode 100644 index 00000000000..4dceecde24b --- /dev/null +++ b/docs/reference-hw/radars.md @@ -0,0 +1,39 @@ +# RADARs + +## **Smartmicro Automotive Radars** + +Smartmicro Radars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (Azimuth), (Elevation) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- | ------------ | --------------------- | +| Type 153 (Triple Mode Short, Medium Long) | S:0.2...19 m M:0.4...55 m L:0.8...120 m | Short: (130°), (15°) Medium: (130°), (15°)
Long: (100°),(15°) | Y | Y | +| Type 132 ,(Dual Mode ,Medium, Long) | M:0.5...64 m  L:1...175 m | Medium: (100°), (15°) Long: (32°), (15°) | Y | Y | + +Link to ROS 2 driver: +[https://github.com/smartmicro/smartmicro_ros2_radars](https://github.com/smartmicro/smartmicro_ros2_radars) + +Link to company website: +[https://www.smartmicro.com/automotive-radar](https://www.smartmicro.com/automotive-radar) + +## **Aptiv Automotive Radars** + +Aptiv Radars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (Azimuth), (Elevation) | ROS 2 Driver | Autoware Tested (Y/N) | +| ---------------------------------------- | ------------------------ | --------------------------------------- | ------------ | --------------------- | +| Aptiv MMR (Dual Mode Short, Long) | S: 1...40 m L: 3...160 m | Short.: (90), (90°) Long: (90°), (90°) | Y | - | +| Aptiv ESR 2.5 (Dual Mode (Medium, Long)) | M: 1...60 m L: 1...175 m | Med.: (90°), (4.4°) Long: (20°), (4.4°) | Y | - | + +Link to company website: +[https://autonomoustuff.com/products](https://autonomoustuff.com/products) + +## **Continental Engineering Radars** + +Continental Engineering Radars which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | Range | FOV (Azimuth), (Elevation) | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ----- | -------------------------- | ------------ | --------------------- | +| ARS430DI | 250m | (120), (18°) | - | - | + +Link to company website: +[https://conti-engineering.com/components/ars430/](https://conti-engineering.com/components/ars430/) diff --git a/docs/reference-hw/remote_drive.md b/docs/reference-hw/remote_drive.md new file mode 100644 index 00000000000..376a75dedad --- /dev/null +++ b/docs/reference-hw/remote_drive.md @@ -0,0 +1,26 @@ +# Remote Drive + +## **FORT ROBOTICS** + +Fort Robotics remote control & E-stop devices which are used for autonomous driving and tested by one or more community members are listed below: + +| Supported Products | Op.Frequency | Controller | ROS 2 Support | Autoware Tested (Y/N) | +| ------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------- | +| Vehicle Safety Controller with E-stop | 900 Mhz radio: up to 2km LOS
2.4Ghz radio: up to 500m LOS | IP 66 Enclosure
Built-in emergency stop safety control
(2) 2-axis joysticks
(2) 1-axis finger sticks
(8) buttons | - | - | + +Link to company website: +[https://fortrobotics.com/vehicle-safety-controller/](https://fortrobotics.com/vehicle-safety-controller/) + +## **LOGITECH** + +Logitech joysticks which are used for autonomous driving and tested by one or more community members are listed below: + +| Supported Products | Op.Frequency | Controller | ROS 2 Support | Autoware Tested (Y/N) | | +| ------------------ | --------------------------- | ------------------------ | ------------- | --------------------- | --- | +| Logitech F-710 | 2.4 GHz Wireless, 10m range | (2) 2-axis joysticks
| (18) buttons | Y | Y | + +Link to ROS driver: +[http://wiki.ros.org/joy](http://wiki.ros.org/joy) + +Link to company website: +[https://www.logitechg.com/en-us/products/gamepads/f710-wireless-gamepad.html](https://www.logitechg.com/en-us/products/gamepads/f710-wireless-gamepad.html) diff --git a/docs/reference-hw/thermal_cameras.md b/docs/reference-hw/thermal_cameras.md new file mode 100644 index 00000000000..9102aee893b --- /dev/null +++ b/docs/reference-hw/thermal_cameras.md @@ -0,0 +1,9 @@ +# Thermal CAMERAs + +## **FLIR Thermal Automotive Dev. Kit** + +FLIR ADK Thermal Vision cameras which has ROS 2 driver and tested by one or more community members are listed below: + +| Supported Products List | MP | FPS | Interface | Spectral Band | FOV | ROS 2 Driver | Autoware Tested (Y/N) | +| ----------------------- | ------- | --- | ----------------- | -------------- | ---------------------- | ------------ | --------------------- | +| FLIR ADK | 640x512 | 30 | USB-GMSL,Ethernet | 8-14 um (LWIR) | 75˚, 50˚, 32˚, and 24˚ | - | - | diff --git a/docs/reference-hw/vehicle_drive_by_wire_suppliers.md b/docs/reference-hw/vehicle_drive_by_wire_suppliers.md new file mode 100644 index 00000000000..a515b9121bb --- /dev/null +++ b/docs/reference-hw/vehicle_drive_by_wire_suppliers.md @@ -0,0 +1,47 @@ +# Vehicle Drive By Wire Suppliers + +## **New Eagle DBW Solutions** + +New Eagle DBW Controllers which is used for autonomous driving and tested by one or more community members are listed below: + +| Supported Vehicles | Power | Remote Control | ROS 2 Support | Autoware Tested (Y/N) | +| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------- | ------------- | --------------------- | +| Jeep Cherokee
Chrysler Pacifica
Toyota Prius
Chevy Bolt
Ford Transit
RAM 1500
Custom  | 500W Sine Inverter
2000 Watts
8 Channel PDS | Optional, Available | Y | Y | + +Link to company website: +[https://neweagle.net/autonomous-machines/](https://neweagle.net/autonomous-machines/) + +## **Dataspeed DBW Solutions** + +Dataspeed DBW Controllers which is used for autonomous driving and tested by one or more community members are listed below: + +| Supported Vehicles | Power | Remote Control | ROS 2 Support | Autoware Tested (Y/N) | +| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------- | ------------- | --------------------- | +| Lincoln MKZ, Nautilus
Ford Fusion, F150, Transit Connect, Ranger
Chrysler Pacifica
Jeep Cherokee
Polaris GEM, RZR | 12 Channel PDS,15 A Each at 12 V | Optional, Available | Y | - | + +Link to company website: +[https://www.dataspeedinc.com/](https://www.dataspeedinc.com/) + +## **AStuff Pacmod DBW Solutions** + +Autonomous Stuff Pacmod DBW Controllers which is used for autonomous driving and tested by one or more community members are listed below: + +| Supported Vehicles | Power | Remote Control | ROS 2 Support | Autoware Tested (Y/N) | +| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | ------------------- | ------------- | --------------------- | +| Polaris GEM Series
Polaris eLXD MY 2016+
Polaris Ranger X900
International ProStar
Lexus RX-450h MY
Ford Ranger
Toyota Minivan | Power distribution panel | Optional, Available | Y | Y | + +Link to company website: +[https://autonomoustuff.com/platform/pacmod](https://autonomoustuff.com/platform/pacmod) + + + +## **Schaeffler-Paravan Space Drive DBW Solutions** + +Schaeffler-Paravan Space Drive DBW Controllers which is used for autonomous driving and tested by one or more community members are listed below: + +| Supported Vehicles | Power | Remote Control | ROS 2 Support | Autoware Tested (Y/N) | +| --------------------------------- | ----- | ------------------- | ------------- | --------------------- | +| Custom Integration with Actuators | - | Optional, Available | Y | Y | + +Link to company website: +[https://www.schaeffler-paravan.de/en/products/space-drive-system/](https://www.schaeffler-paravan.com/en/space-drive/space-drive-2-already-home-streets-world) diff --git a/docs/reference-hw/vehicle_platform_suppliers.md b/docs/reference-hw/vehicle_platform_suppliers.md new file mode 100644 index 00000000000..e7880700265 --- /dev/null +++ b/docs/reference-hw/vehicle_platform_suppliers.md @@ -0,0 +1,49 @@ +# Vehicle Platform Suppliers + +## **PIX MOVING Autonomous Vehicle Solutions** + +PIX Moving AV solutions which is used for autonomous development and tested by one or more community members are listed below: + +| Vehicle Types | Sensors Integrated | Autoware Installed | ROS 2 Support | Autoware Tested (Y/N) | +| ---------------------------------- | ------------------ | ------------------ | ------------- | --------------------- | +| Electric DBW Chassis and Platforms | Y | Y | Y | - | + +Link to company website: +[https://www.pixmoving.com/pixkit](https://www.pixmoving.com/pixkit) + +Different sizes of platforms + +![platforms.png](images/platforms.png) + +## **Autonomoustuff AV Solutions** + +Autonomoustuff platform solutions which is used for autonomous development and tested by one or more community members are listed below: + +| Vehicle Types | Sensors Integrated | Autoware Installed | ROS 2 Support | Autoware Tested (Y/N) | +| ---------------------------------- | ------------------ | ------------------ | ------------- | --------------------- | +| Road Vehicles, Golf Carts & Trucks | Y | Y | Y | - | + +Link to company website: +[https://autonomoustuff.com/platform](https://autonomoustuff.com/platform) + +## **NAVYA AV Solutions** + +NAVYA platform solutions which is used for autonomous development and tested by one or more community members are listed below: + +| Vehicle Types | Sensors Integrated | Autoware Installed | ROS 2 Support | Autoware Tested (Y/N) | +| ---------------------------------- | ------------------ | ------------------ | ------------- | --------------------- | +| Shuttle Bus, Taxi and Tow Tractors | Y | Y | - | - | + +Link to company website: +[https://navya.tech/en](https://navya.tech/en) + +## **ZING ROBOTICS AV Solutions** + +ZING Robotics platform solutions which is used for autonomous development and tested by one or more community members are listed below: + +| Vehicle Types | Sensors Integrated | Autoware Installed | ROS 2 Support | Autoware Tested (Y/N) | +| ---------------------------------------------------------------------- | ------------------ | ------------------ | ------------- | --------------------- | +| Purpose built electric autonomous vehicles for aviation, military etc. | Y | Y | - | - | + +Link to company website: +[https://www.zingrobotics.com/](https://www.zingrobotics.com/) diff --git a/docs/support/.pages b/docs/support/.pages index 9a9ce05db53..514c94b63c3 100644 --- a/docs/support/.pages +++ b/docs/support/.pages @@ -1,5 +1,5 @@ nav: - index.md - support-guidelines.md - - troubleshooting.md + - troubleshooting - docs-guide.md diff --git a/docs/support/index.md b/docs/support/index.md index 53e3a5c0cd5..ca56b3236cf 100644 --- a/docs/support/index.md +++ b/docs/support/index.md @@ -3,5 +3,5 @@ This page explains several support resources. - [Support guidelines](support-guidelines.md) pages explain the support mechanisms and guidelines. -- [Troubleshooting](troubleshooting.md) pages explain solutions for common issues. +- [Troubleshooting](troubleshooting/index.md) pages explain solutions for common issues. - [Docs guide](docs-guide.md) pages explain related documentation sites. diff --git a/docs/support/troubleshooting/.pages b/docs/support/troubleshooting/.pages new file mode 100644 index 00000000000..f854e9816fc --- /dev/null +++ b/docs/support/troubleshooting/.pages @@ -0,0 +1,3 @@ +nav: + - index.md + - performance-troubleshooting.md diff --git a/docs/support/troubleshooting.md b/docs/support/troubleshooting/index.md similarity index 63% rename from docs/support/troubleshooting.md rename to docs/support/troubleshooting/index.md index eed2ac3abfc..0262637a256 100644 --- a/docs/support/troubleshooting.md +++ b/docs/support/troubleshooting/index.md @@ -79,6 +79,28 @@ free -h 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](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-20-04) +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. + +```bash +MAKEFLAGS="-j4" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release +``` + +You can adjust `-j4` to any number based on your system. +For more details, see the [manual page of GNU make](https://www.gnu.org/software/make/manual/make.html#Parallel-Disable). + +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. + +```bash +MAKEFLAGS="-j1" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --parallel-workers 1 +``` + +!!! 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. + ### Errors when using the latest version of Autoware If you are working with the latest version of Autoware, issues can occur due to out-of-date software or old build files. @@ -90,7 +112,7 @@ rm -rf build/ install/ log/ colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release ``` -If the error is not resolved, remove `src/` and update your workspace according to installation type ([Docker](../installation/autoware/docker-installation.md#how-to-update-a-workspace) / [source](../installation/autoware/source-installation.md#how-to-update-a-workspace)). +If the error is not resolved, remove `src/` and update your workspace according to installation type ([Docker](../../installation/autoware/docker-installation.md#how-to-update-a-workspace) / [source](../../installation/autoware/source-installation.md#how-to-update-a-workspace)). !!! Warning @@ -120,6 +142,24 @@ In addition to the causes listed above, there are two common misunderstandings a 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. +### Error when building python package + +During building the following issue can occurs + +```bash +pkg_resources.extern.packaging.version.InvalidVersion: Invalid version: '0.23ubuntu1' +``` + +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](https://peps.python.org/pep-0440/) conformant. +Since version 67.5.1 `setuptools` has a [fallback](https://github.com/pypa/setuptools/commit/1640731114734043b8500d211366fc941b741f67) that makes it possible to work with old packages again. + +The solution is to update `setuptools` to the newest version with the following command + +```bash +pip install --upgrade setuptools +``` + ## Docker/rocker issues 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: @@ -137,36 +177,21 @@ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:latest ## Runtime issues -### Map does not display when running the Planning Simulator - -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](https://autowarefoundation.github.io/autoware-documentation/main/tutorials/ad-hoc-simulation/planning-simulation/#how-to-run-a-planning-simulation). 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. +### Performance related issues -Another possible reason is that map loading is taking a long time due to poor DDS performance. To address this issue, first enable localhost-only communication to reduce network traffic, and then [tune DDS settings](https://docs.ros.org/en/rolling/How-To-Guides/DDS-tuning.html) if the problem continues to occur. +Symptoms: -1. [Enable localhost-only communication](../installation/additional-settings-for-developers/index.md#enabling-localhost-only-communication) -2. Tune DDS settings +- 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 -Add the following lines to `/etc/sysctl.conf` +If you have any of these symptoms, please the [Performance Troubleshooting](performance-troubleshooting.md) page. -```bash -net.ipv4.ipfrag_time=3 // generic DDS setting -net.ipv4.ipfrag_high_thresh=134217728 // generic DDS setting -net.core.rmem_max=2147483647 // only add if CycloneDDS is configured -net.core.rmem_default=8388608 // only add if CycloneDDS is confgured -``` - -!!! note - - DDS configuration can be determined by running the following command. - - ```bash - echo $RMW_IMPLEMENTATION // if Cyclone DDS is configured, this command will return "rmw_cyclonedds_cpp" - ``` - -### Multicast is disabled +### Map does not display when running the Planning Simulator -If you get the error message `selected interface "{your-interface-name}" is not multicast-capable: disabling multicast`, run the following command to allow multicast. +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](../../tutorials/ad-hoc-simulation/planning-simulation.md#how-to-run-a-planning-simulation). 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. -```bash -sudo ip link set multicast on {your-interface-name} -``` +Another possible reason is that map loading is taking a long time due to poor DDS performance. For this, please visit the [Performance Troubleshooting](performance-troubleshooting.md) page. diff --git a/docs/support/troubleshooting/performance-troubleshooting.md b/docs/support/troubleshooting/performance-troubleshooting.md new file mode 100644 index 00000000000..6fee15d21ce --- /dev/null +++ b/docs/support/troubleshooting/performance-troubleshooting.md @@ -0,0 +1,220 @@ +# Performance Troubleshooting + +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 + +## Diagnostic Steps + +### Check if multicast is enabled + +#### Target symptoms + +- When multiple subscribers use the same publishers, the message rate drops + +#### Diagnosis + +Make sure that the multicast is enabled for your interface. + +For example when you run following: + +```bash +source /opt/ros/humble/setup.bash +ros2 run demo_nodes_cpp talker +``` + +If you get the error message `selected interface "{your-interface-name}" is not multicast-capable: disabling multicast`, this should be fixed. + +#### Solution + +Run the following command to allow multicast: + +```bash +sudo ip link set multicast on {your-interface-name} +``` + +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: + + ```bash + if [ ! -e /tmp/multicast_is_set ]; then + sudo ip link set lo multicast on + touch /tmp/multicast_is_set + fi + ``` + + - This will probably ask for password on the terminal every time you restart the computer. + +### Check the compilation flags + +#### Target symptoms + +- Autoware is running slower than expected +- Point clouds are lagging +- When multiple subscribers use the same publishers, the message rate drops even further + +#### Diagnosis + +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](https://github.com/autowarefoundation/autoware.universe/issues/2597#issuecomment-1491789081) + +#### Solution + +- Remove the `build`, `install` and optionally `log` folders in the main `autoware` folder. +- Compile the Autoware with either `Release` or `RelWithDebInfo` tags: + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + # Or build with debug flags too (comparable performance but you can debug too) + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo + ``` + +### Check the DDS settings + +#### Target symptoms + +- 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 + +#### Check the RMW (ROS Middleware) implementation + +##### Diagnosis + +Run following to check the middleware used: + +```bash +echo $RMW_IMPLEMENTATION +``` + +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. + +##### Solution + +Add `export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp` as a separate line in you `~/.bashrc` file. + +#### Check if the CycloneDDS is configured correctly + +##### Diagnosis + +Run following to check the configuration `.xml` file of the `CycloneDDS`: + +```bash +echo $CYCLONEDDS_URI +``` + +The return line should be a valid path pointing to an `.xml` file with `CycloneDDS` configuration. + +Also check if the file is configured correctly: + +```bash +cat !{echo $CYCLONEDDS_URI} +``` + +This should print the `.xml` file on the terminal. + +##### Solution + +Follow [DDS settings:Tuning DDS documentation](../../installation/additional-settings-for-developers/index.md#tuning-dds) 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. + +#### Check the Linux kernel maximum buffer size + +##### Diagnosis + +- 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](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html#cross-vendor-tuning) + +##### Solution + +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`): + + ```bash + net.core.rmem_max=2147483647 + net.ipv4.ipfrag_time=3 + net.ipv4.ipfrag_high_thresh=134217728 # (128 MB) + ``` + + - Either restart the computer or run following to enable the changes: + + ```bash + sudo sysctl -w net.core.rmem_max=2147483647 + sudo sysctl -w net.ipv4.ipfrag_time=3 + sudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728 + ``` + +- **OR** put following lines to the `~/.bashrc` file: + + ```bash + if [ ! -e /tmp/kernel_network_conf_is_set ]; then + sudo sysctl -w net.core.rmem_max=2147483647 + sudo sysctl -w net.ipv4.ipfrag_time=3 + sudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728 # (128 MB) + fi + ``` + + - This will probably ask for password on the terminal every time you restart the computer. + +### Check if ROS localhost only communication is enabled + +- 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](../../installation/additional-settings-for-developers/index.md#enabling-localhost-only-communication) + +#### Target symptoms + +- 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. + +#### Diagnosis + +Run following to check it: + +```bash +echo $ROS_LOCALHOST_ONLY +``` + +The return line should be `1`. If not, apply the solution. + +#### Solution + +- 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. diff --git a/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/.pages b/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/.pages index 3654d1f5c63..fa6d79b1553 100644 --- a/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/.pages +++ b/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/.pages @@ -1,2 +1,3 @@ nav: - awsim-tutorial.md + - MORAI_Sim-tutorial.md diff --git a/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial.md b/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial.md new file mode 100644 index 00000000000..fa10ec27263 --- /dev/null +++ b/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/MORAI_Sim-tutorial.md @@ -0,0 +1,49 @@ +# MORAI Sim: Drive + +!!! note + + Any kind of for-profit activity with the trial version of the MORAI SIM:Drive is strictly prohibited. + +## Hardware requirements + +| 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 | + +## Application and Download + +Only for AWF developers, trial license for 3 months can be issued. +Download the [application form](https://drive.google.com/file/d/1SO9hAr2-828MNl410xSABp3znHaR-AWV/view?usp=sharing) and send to [Hyeongseok Jeon](#technical-support) + +After the trial license is issued, you can login to MORAI Sim:Drive via Launchers ([Windows](https://drive.google.com/file/d/1NMd2kInUALXYosRMtOHDPPGou9yCWMKK/view?usp=sharing)/[Ubuntu](https://drive.google.com/file/d/1qmA_1eUDyNJ85AeAzSxZRQaDbR_Sc76R/view?usp=sharing)) + +CAUTION: Do not use the Launchers in the following manual + +## Technical Documents + +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](https://morai-sim--drive-user-manual--en-22-r2.scrollhelp.site/msdume2/) +- [ITRI BUS Odd tutorial](https://morai.atlassian.net/wiki/external/1158610949/ZDE2Mjk0MTc5OTAxNGZmZjg3ZDMxZjQxNzFkNTgxYWM?atlOrigin=eyJpIjoiNDc1OGNkMjkxMTMzNDVjOGExMGFiMDY0M2ZmNzkwMjkiLCJwIjoiYyJ9) +- [Tutorial for rosbag replay with Tacoma Airport](https://morai.atlassian.net/wiki/external/1098547535/MTJjMDRmZDlhZDhiNDI2YzhkNzgzMWJiMjNiYTYxMzc?atlOrigin=eyJpIjoiZTc5NzBlM2VkMmFiNDZlM2JlZjk1N2Q3ZjZjYWYwZjMiLCJwIjoiYyJ9) + +## Technical Support + + + +Hyeongseok Jeon will give full technical support + +- hsjeon@morai.ai +- Hyeongseok Jeon#2355 in Discord diff --git a/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial.md b/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial.md index dd021156283..e91f74a46c3 100644 --- a/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial.md +++ b/docs/tutorials/ad-hoc-simulation/digital-twin-simulation/awsim-tutorial.md @@ -1,214 +1,3 @@ -# AWSIM simulator setup +# AWSIM simulator -!!! note - - The binary is just a sample one for the initial testing, for AWF developers only. To get access, please contact Wojciech Jaworski on Autoware Discord. The official binary from TIER IV will be released in October. - -## Hardware requirements - -| Required PC Specs | | -| :---------------- | :---------------------------- | -| OS | Ubuntu 20.04 | -| CPU | 6cores and 12thread or higher | -| GPU | RTX2080Ti or higher | - -## Prerequisites - -1. Nvidia GPU driver (Skip if already installed) - - 1. Add Nvidia driver to apt repository - - ```bash - sudo add-apt-repository ppa:graphics-drivers/ppa - ``` - - 1. Check supported Nvidia driver versions - - ```bash - $ ubuntu-drivers devices - == /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0 == - modalias : pci:v000010DEd00001F91sv000017AAsd0000229Fbc03sc00i00 - vendor : NVIDIA Corporation - driver : nvidia-driver-435 - distro non-free - driver : nvidia-driver-440-server - distro non-free - driver : nvidia-driver-418-server - distro non-free - driver : nvidia-driver-450 - third-party free recommended - driver : nvidia-driver-440 - distro non-free - driver : xserver-xorg-video-nouveau - distro free builtin - - == /sys/devices/pci0000:00/0000:00:1d.6/0000:52:00.0 == - modalias : pci:v00008086d00002723sv00008086sd00000080bc02sc80i00 - vendor : Intel Corporation - manual_install: True - driver : backport-iwlwifi-dkms - distro free - ``` - - 1. Install the recommended version - - ```bash - sudo apt install nvidia-driver-450 - ``` - - 1. reboot and check nvidia-smi - - ```bash - $ nvidia-smi - Fri Aug 14 18:18:17 2020 - +-----------------------------------------------------------------------------+ - | NVIDIA-SMI 450.57 Driver Version: 450.57 CUDA Version: 11.0 | - |-------------------------------+----------------------+----------------------+ - | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | - | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | - | | | MIG M. | - |===============================+======================+======================| - | 0 GeForce GTX 165... Off | 00000000:01:00.0 On | N/A | - | N/A 40C P8 4W / N/A | 540MiB / 3903MiB | 1% Default | - | | | N/A | - +-------------------------------+----------------------+----------------------+ - - +-----------------------------------------------------------------------------+ - | Processes: | - | GPU GI CI PID Type Process name GPU Memory | - | ID ID Usage | - |=============================================================================| - | 0 N/A N/A 1264 G /usr/lib/xorg/Xorg 26MiB | - | 0 N/A N/A 1406 G /usr/bin/gnome-shell 47MiB | - | 0 N/A N/A 1606 G /usr/lib/xorg/Xorg 202MiB | - | 0 N/A N/A 1739 G /usr/bin/gnome-shell 110MiB | - | 0 N/A N/A 3697 G ...AAAAAAAAA= --shared-files 149MiB | - +-----------------------------------------------------------------------------+ - ``` - -1. Vulkun Graphics Library (Skip if already installed) - - 1. Update apt - - ```bash - sudo apt update - ``` - - 1. install libvulkan1 - - ```bash - sudo apt install libvulkan1 - ``` - -## Preparation - -- Install Autoware following the [official guide](https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/) -- Download and extract the [AWSIM binary](https://drive.google.com/file/d/1p_dEiSTODHjCVkxFy8F7tLkY1J9VItIb/view?usp=sharing) - -!!! note - - In case of less powerful computers, performance problems might occur when running Autoware with high-resolution camera simulation on single PC. For such situations, AWSIM binaries with lower camera resolution are prepared: [AWSIM-720p](https://drive.google.com/file/d/14iiidsKiwzADyEqk9PeHQefkIIFpuA6B/view?usp=sharing) , [AWSIM-360p](https://drive.google.com/file/d/1c8gADhhS6jtseE_TN2treSNkL-4_6UE6/view?usp=sharing) - -- Download and extract the [sample map folder](https://drive.google.com/file/d/1vGFI0o0zQ-gRZYqKrPbnrtCN3c3-92Fy/view?usp=sharing) - -## Running steps - -### AWSIM Simulator - -To run the AWSIM simulator, open a terminal window, navigate to the simulation directory and run the following commands: - -```bash -source /opt/ros/galactic/setup.bash -cd -./AWSIM.x86_64 -``` - -If the simulator is working properly, Lidar rays should be visible and the [expected data topics](https://github.com/autowarefoundation/autoware-projects/wiki/Bus-ODD-Simulation-requirements#integration-interface-with-autoware-universe) should appear when `ros2 topic list` is run. - -![correctly working simulator](./images/workingSim.png) - -#### Simulator shortcuts - -It is also possible to control the simulation using the keyboard shortcuts listed below: - -| Shortcut | Description | -| -------- | ------------------------------------------------------ | -| v | Toggle lidar points visualization | -| m | Toggle manual operation mode (Ego listens to keyboard) | - - In manual mode: - -| Shortcut | Description | -| -------- | ----------------------------- | -| d | Shift gear to Drive | -| p | Shift gear to Park | -| r | Shift gear to Reverse | -| ← ↑ ↓ → | Accelerate/brake and steering | -| 1 | Left blinker | -| 2 | Right blinker | -| 3 | Emergency lights | -| 4 | Turn off lights | - -### Running Autoware to control AWSIM - -To run Autoware, open a terminal and run the following commands: - -```bash -cd /autoware -source install/setup.bash -ros2 launch autoware_launch autoware.launch.xml map_path:= vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit use_sim_time:=true launch_sensing_driver:=false -``` - -!!! note - - Note that `map_path` must be a full path. Relative paths will not work. - -- RViz should appear with the Lanelet2 map displayed. Although the ego vehicle can localize itself at the beginning, the localization can be inaccurate. It is recommended to explicitly set the vehicle's initial pose using the `2D Pose Estimate` button as shown in the image below. - -![how to initialize autoware](./images/initializeAutoware.png) - -- To make Autoware plan the route, use the `2D Goal Pose` button to set a goal pose somewhere within the Lanelet2 road lanes. - -- To make Autoware execute the planned route, open a new terminal and send the engage message: - -```bash -cd /autoware -source install/setup.bash -ros2 topic pub /autoware/engage autoware_auto_vehicle_msgs/msg/Engage "engage: true" -``` - -From now on, Autoware will execute the planned route and operate the AWSIM Simulator. - -![AWSIM with autoware](./images/awf_awsim.png) - -### NPC Control (optional) - -Currently the only supported way to add NPCs to the simulation is using prerecorded rosbags. - -!!! note - -The current NPC control feature will not be supported in the OSS version of AWSIM - -#### Preparation - -- Download and extract [npc_msgs](https://drive.google.com/file/d/1fMvjOnz7Z0cGXotwdOAhBfLPYO52ssp0/view?usp=sharing) -- Download and extract [sample rosbags](https://drive.google.com/file/d/1BSoIq82DW_RIyeSR6OinhKmA6lD6jmWe/view?usp=sharing) - -#### Run NPCs from rosbag - -To run NPCs from rosbag, follow the steps: - -- Navigate to the directory where the `npc_msgs` source code was extracted -- Build and source `npc_msgs`: - -```bash -colcon build -source install/setup.bash -``` - -- Play the downloaded sample rosbag while AWSIM is running: - -```bash -ros2 bag play -``` - -![AWSIM with autoware and NPCs](./images/awsim_npc.png) - -### Troubleshooting - -If the expected ROS topic data is not produced, or the point cloud is not visible on the simulation screen, report the problem as an [Autoware Q&A discussion](https://github.com/autowarefoundation/autoware/discussions/). - -To make analysis of the problem easier, make sure to provide a description of your environment, a detailed set of reproduction steps, screenshots or a short video of any unexpected behaviour and attach the `Player.log` file, which can be found in the `~/.config/unity3d/Tier\ IV/E2ESimulator/Player.log` directory. +AWSIM is a simulator for Autoware development and testing. To get started, please follow the official [instruction](https://tier4.github.io/AWSIM/GettingStarted/QuickStartDemo/) provided by TIER IV. diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/avoidance/set-dummy-bus.png b/docs/tutorials/ad-hoc-simulation/images/planning/avoidance/set-dummy-bus.png new file mode 100644 index 00000000000..d3aaf85a2cf Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/avoidance/set-dummy-bus.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/avoidance/set-position-and-goal.png b/docs/tutorials/ad-hoc-simulation/images/planning/avoidance/set-position-and-goal.png new file mode 100644 index 00000000000..83072f02dd0 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/avoidance/set-position-and-goal.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/lane-changing.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/lane-changing.png new file mode 100644 index 00000000000..3d110bafbfb Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/lane-changing.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/open-nishishinjuku-map.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/open-nishishinjuku-map.png new file mode 100644 index 00000000000..91030eca0b5 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/open-nishishinjuku-map.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/set-position-and-goal.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/set-position-and-goal.png new file mode 100644 index 00000000000..a5b83bee665 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-change/set-position-and-goal.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/after-autoware-launch.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/after-autoware-launch.png index 8443c17ee5c..37fd404f36d 100644 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/after-autoware-launch.png and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/after-autoware-launch.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/after-traffic-light-color-update.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/after-traffic-light-color-update.png deleted file mode 100644 index 0c3c70c142e..00000000000 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/after-traffic-light-color-update.png and /dev/null differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/check-interactive.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/check-interactive.png new file mode 100644 index 00000000000..bfd8446b752 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/check-interactive.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/engage-and-start-planning.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/engage-and-start-planning.png deleted file mode 100644 index 9fff8107c0c..00000000000 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/engage-and-start-planning.png and /dev/null differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/move-dummy-object.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/move-dummy-object.png new file mode 100644 index 00000000000..50d828645a8 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/move-dummy-object.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/send-traffic-light-color.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/send-traffic-light-color.png deleted file mode 100644 index b355567cb11..00000000000 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/send-traffic-light-color.png and /dev/null differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-goal-pose.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-goal-pose.png index 9f55b07e1a5..45d2aca1991 100644 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-goal-pose.png and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-goal-pose.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-initial-pose.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-initial-pose.png index 2ed59767372..0a5fe929bd4 100644 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-initial-pose.png and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-initial-pose.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-traffic-light.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-traffic-light.png deleted file mode 100644 index cb28e89536b..00000000000 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-traffic-light.png and /dev/null differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/start-driving.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/start-driving.png new file mode 100644 index 00000000000..d6b2c7cc6e9 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/start-driving.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/parking/after-set-goal-pose.png b/docs/tutorials/ad-hoc-simulation/images/planning/parking/after-set-goal-pose.png index cdb15418c69..71bb15dd006 100644 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/parking/after-set-goal-pose.png and b/docs/tutorials/ad-hoc-simulation/images/planning/parking/after-set-goal-pose.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/parking/parking-maneuver.png b/docs/tutorials/ad-hoc-simulation/images/planning/parking/parking-maneuver.png index eaff48f0ddb..8bc4cee7723 100644 Binary files a/docs/tutorials/ad-hoc-simulation/images/planning/parking/parking-maneuver.png and b/docs/tutorials/ad-hoc-simulation/images/planning/parking/parking-maneuver.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/after-traffic-light-color-update.png b/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/after-traffic-light-color-update.png new file mode 100644 index 00000000000..b01c52bc638 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/after-traffic-light-color-update.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/see-traffic-light-ID.png b/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/see-traffic-light-ID.png similarity index 100% rename from docs/tutorials/ad-hoc-simulation/images/planning/lane-following/see-traffic-light-ID.png rename to docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/see-traffic-light-ID.png diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/send-traffic-light-color.png b/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/send-traffic-light-color.png new file mode 100644 index 00000000000..68ed99c5082 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/send-traffic-light-color.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/set-traffic-light.png b/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/set-traffic-light.png new file mode 100644 index 00000000000..a1dfa91c9a1 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/traffic-light/set-traffic-light.png differ diff --git a/docs/tutorials/ad-hoc-simulation/planning-simulation.md b/docs/tutorials/ad-hoc-simulation/planning-simulation.md index c0392a1be25..eda90349010 100644 --- a/docs/tutorials/ad-hoc-simulation/planning-simulation.md +++ b/docs/tutorials/ad-hoc-simulation/planning-simulation.md @@ -34,13 +34,7 @@ ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/autowa ![after-autoware-launch](images/planning/lane-following/after-autoware-launch.png) -#### 2. Add Autoware State Panel - -This panel is useful when running planning simulations. To add the panel, click `Panels -> Add new panel`, select `AutowareStatePanel`, and then click `OK`. - -![after-autoware-launch](images/planning/lane-following/open-autoware-state-panel.png) - -#### 3. Set an initial pose for the ego vehicle +#### 2. Set an initial pose for the ego vehicle ![set-initial-pose](images/planning/lane-following/set-initial-pose.png) @@ -54,7 +48,7 @@ b) In the 3D View pane, click and hold the left-mouse button, and then drag to s To confirm the direction of the lane, check the arrowheads displayed on the map. -#### 4. Set a goal pose for the ego vehicle +#### 3. Set a goal pose for the ego vehicle a) Click the `2D Goal Pose` button in the toolbar, or hit the `G` key. @@ -62,16 +56,19 @@ b) In the 3D View pane, click and hold the left-mouse button, and then drag to s ![set-goal-pose](images/planning/lane-following/set-goal-pose.png) -#### 5. Engage the ego vehicle +#### 4. Start the ego vehicle -Now you can start the ego vehicle driving by clicking the `Engage` button in `AutowareStatePanel`. Alteratively, you can manually engage the vehicle by running the following command: +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: ```bash source ~/autoware/install/setup.bash -ros2 topic pub /autoware/engage autoware_auto_vehicle_msgs/msg/Engage "engage: true" -1 +ros2 service call /api/operation_mode/change_to_autonomous autoware_adapi_v1_msgs/srv/ChangeOperationMode {} ``` -![start-driving](images/planning/lane-following/engage-and-start-planning.png) +After that, you can see `AUTONOMOUS` sign on `OperationMode` and `AUTO` button is grayed out. + +![start-driving](images/planning/lane-following/start-driving.png) ### Parking scenario @@ -84,21 +81,69 @@ ros2 topic pub /autoware/engage autoware_auto_vehicle_msgs/msg/Engage "engage: t ![parking-maneuver](images/planning/parking/parking-maneuver.png) +### Lane change scenario + +1. Download and unpack Nishishinjuku map. + + ```bash + gdown -O ~/autoware_map/ 'https://github.com/tier4/AWSIM/releases/download/v1.1.0/nishishinjuku_autoware_map.zip' + unzip -d ~/autoware_map ~/autoware_map/nishishinjuku_autoware_map.zip + ``` + +2. Launch autoware with Nishishinjuku map with following command: + + ```bash + source ~/autoware/install/setup.bash + ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/autoware_map/nishishinjuku_autoware_map vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit + ``` + + ![open-nishishinjuku-map](images/planning/lane-change/open-nishishinjuku-map.png) + +3. Set an initial pose and a goal pose in adjacent lanes. + + ![set-position-and-goal](images/planning/lane-change/set-position-and-goal.png) + +4. Engage the ego vehicle. It will make a lane change along the planned path. + + ![lane-changing](images/planning/lane-change/lane-changing.png) + +### Avoidance scenario + +1. Set an initial pose and a goal pose in the same lane. A path will be planned. + + ![set-position-and-goal](images/planning/avoidance/set-position-and-goal.png) + +2. Set a "2D Dummy Bus" on the roadside. A new path will be planned. + + ![set-dummy-bus](images/planning/avoidance/set-dummy-bus.png) + +3. Engage the ego vehicle. It will avoid the obstacle along the newly planned path. + ## Advanced Simulations ### Placing dummy objects 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 + !!! note + + Changes to the `velocity` parameter will only affect objects placed after the parameter is changed. + + ![set-dummy-car](images/planning/lane-following/place-dummy-car.png) + +4. Delete any dummy objects placed in the view by clicking the `Delete All Objects` button in the toolbar. - Changes to the `velocity` parameter will only affect objects placed after the parameter is changed. +5. Click the `Interactive` button in the toolbar to make the dummy object interactive. -![set-dummy-car](images/planning/lane-following/place-dummy-car.png) 4. Delete any dummy objects placed in the view by clicking the `Delete All Objects` button in the toolbar. + ![set-interactive-dummy-car](images/planning/lane-following/check-interactive.png) + +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. + + ![move-interactive-dummy-car](images/planning/lane-following/move-dummy-object.png) ### Traffic light recognition simulation @@ -113,15 +158,15 @@ The following steps explain how to set and reset traffic lights in order to test 2. In `TrafficLightPublishPanel`, set the `ID` and color of the traffic light. 3. Click the `SET` button. - ![set-traffic-light](images/planning/lane-following/set-traffic-light.png) + ![set-traffic-light](images/planning/traffic-light/set-traffic-light.png) 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. -![send-traffic-light-color](images/planning/lane-following/send-traffic-light-color.png) +![send-traffic-light-color](images/planning/traffic-light/send-traffic-light-color.png) 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 the event that the IDs are not displayed, try the following troubleshooting steps: +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`. @@ -129,12 +174,14 @@ b) Check the `traffic_light_id` checkbox. c) Reload the topic by clicking the `Map` checkbox twice. -![see-traffic-light-ID](images/planning/lane-following/see-traffic-light-ID.png) +![see-traffic-light-ID](images/planning/traffic-light/see-traffic-light-ID.png) #### Update/Reset traffic light 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. -![after-traffic-light-color-update](images/planning/lane-following/after-traffic-light-color-update.png) +![after-traffic-light-color-update](images/planning/traffic-light/after-traffic-light-color-update.png) To remove a traffic light from `TrafficLightPublishPanel`, click the `RESET` button. + +[Reference video tutorials](https://drive.google.com/file/d/1bs_dX1JJ76qHk-SGvS6YF9gmekkN8fz7/view?usp=sharing) diff --git a/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md b/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md index 46e6e9d6cac..27e23c14202 100644 --- a/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md +++ b/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md @@ -56,3 +56,5 @@ 4. To switch the view to `Third Person Follower` etc, change the `Type` in the RViz Views panel. ![third-person-follower](images/rosbag-replay/third-person-follower.png) + +[Reference video tutorials](https://drive.google.com/file/d/12D6aSC1Y3Kf7STtEPWG5RYynxKdVcPrc/view?usp=sharing) diff --git a/docs/tutorials/scenario-simulation/.pages b/docs/tutorials/scenario-simulation/.pages index f7440312cfc..37ce01897a5 100644 --- a/docs/tutorials/scenario-simulation/.pages +++ b/docs/tutorials/scenario-simulation/.pages @@ -1,3 +1,4 @@ nav: + - index.md - planning-simulation - - rosbag-replay-simulation.md + - rosbag-replay-simulation diff --git a/docs/contributing/coding-guidelines/ros-nodes/naming.md b/docs/tutorials/scenario-simulation/index.md similarity index 62% rename from docs/contributing/coding-guidelines/ros-nodes/naming.md rename to docs/tutorials/scenario-simulation/index.md index 6873692fef7..3b6ba0b02c9 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/naming.md +++ b/docs/tutorials/scenario-simulation/index.md @@ -1,4 +1,4 @@ -# Topic namespaces +# Scenario simulation !!! warning diff --git a/docs/tutorials/scenario-simulation/planning-simulation/installation.md b/docs/tutorials/scenario-simulation/planning-simulation/installation.md index 839ac5b89a1..e9a386777b7 100644 --- a/docs/tutorials/scenario-simulation/planning-simulation/installation.md +++ b/docs/tutorials/scenario-simulation/planning-simulation/installation.md @@ -4,7 +4,7 @@ This document contains step-by-step instruction on how to build [AWF Autoware Co ## Prerequisites -1. [Autoware has been built and installed](https://autowarefoundation.github.io/autoware-documentation/main/installation/) +1. [Autoware has been built and installed](../../../installation/) ## How to build @@ -23,7 +23,7 @@ This document contains step-by-step instruction on how to build [AWF Autoware Co 3. Install dependent ROS packages: ```bash - source /opt/ros/galactic/setup.bash + source /opt/ros/humble/setup.bash rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO ``` diff --git a/docs/tutorials/scenario-simulation/planning-simulation/scenario-test-simulation.md b/docs/tutorials/scenario-simulation/planning-simulation/scenario-test-simulation.md index ef2606cf64e..ebd2e256321 100644 --- a/docs/tutorials/scenario-simulation/planning-simulation/scenario-test-simulation.md +++ b/docs/tutorials/scenario-simulation/planning-simulation/scenario-test-simulation.md @@ -26,3 +26,5 @@ ``` ![scenario_test_runner](images/scenario_test_runner.png) + +[Reference video tutorials](https://user-images.githubusercontent.com/102840938/206996920-758b62ae-270a-497c-8a72-f9e4867df695.mp4) diff --git a/docs/tutorials/scenario-simulation/rosbag-replay-simulation/.pages b/docs/tutorials/scenario-simulation/rosbag-replay-simulation/.pages new file mode 100644 index 00000000000..44be6bc689b --- /dev/null +++ b/docs/tutorials/scenario-simulation/rosbag-replay-simulation/.pages @@ -0,0 +1,2 @@ +nav: + - driving-log-replayer.md diff --git a/docs/tutorials/scenario-simulation/rosbag-replay-simulation/driving-log-replayer.md b/docs/tutorials/scenario-simulation/rosbag-replay-simulation/driving-log-replayer.md new file mode 100644 index 00000000000..28a8586c448 --- /dev/null +++ b/docs/tutorials/scenario-simulation/rosbag-replay-simulation/driving-log-replayer.md @@ -0,0 +1,4 @@ +# Driving Log Replayer + +Driving Log Replayer is an evaluation tool for Autoware. +To get started, follow the [official instruction](https://tier4.github.io/driving_log_replayer/quick_start/installation/) provided by TIER IV. diff --git a/main.py b/main.py index caea352cdd8..6952a83155e 100644 --- a/main.py +++ b/main.py @@ -1,10 +1,27 @@ import os # for relpath, cannot use pathlib +import urllib def define_env(env): + @env.filter + def drawio(image_path): + image_url = urllib.parse.quote(f"{env.conf['site_url']}{image_path}", "") + return f"https://app.diagrams.net/?lightbox=1#U{image_url}" + + @env.macro + def create_relative_link(text, root_path): + path = os.path.relpath(root_path, env.page.url) + return f"[{text}]({path})" @env.macro def link_ad_api(name): - root_path = "design/autoware-interfaces/ad-api" - base_path = os.path.relpath(root_path, env.page.url) + "/list" - return f"[{name}]({base_path}{name})" + return create_relative_link(name, f"design/autoware-interfaces/ad-api/list/{name}") + + @env.macro + def resolve_msg_field(type, name, ext): + specs = env.variables["autoware_interfaces"]["types"] + for field in name.split("."): + type = type.split("[")[0] + type = specs[type][ext][field] + ext = "msg" + return type diff --git a/mkdocs-base.yaml b/mkdocs-base.yaml new file mode 100644 index 00000000000..56c51cbb64f --- /dev/null +++ b/mkdocs-base.yaml @@ -0,0 +1,95 @@ +site_name: Autoware Documentation +site_url: https://autowarefoundation.github.io/autoware-documentation +repo_url: https://github.com/autowarefoundation/autoware +edit_uri: https://github.com/autowarefoundation/autoware-documentation/edit/main/docs/ +docs_dir: docs +copyright: Copyright © 2023 The Autoware Foundation + +theme: + name: material + features: + - navigation.expand + - navigation.indexes + - navigation.instant + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.footer + favicon: assets/images/autoware-foundation.png + icon: + logo: fontawesome/solid/car + repo: fontawesome/brands/github + language: en + palette: + - scheme: default + primary: white + toggle: + icon: material/weather-sunny + name: Switch to dark mode + - scheme: slate + primary: grey + toggle: + icon: material/weather-night + name: Switch to light mode + +extra: + font: + text: Roboto + code: Roboto Mono + version: + provider: mike + +extra_css: + - assets/css/extra.css + - https://use.fontawesome.com/releases/v5.15.4/css/all.css + +extra_javascript: + - assets/js/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + +plugins: + - awesome-pages + - exclude: + regex: + - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?gif|(.*\.)?jpg).*$ + - ^(.*/)?[^.]*$ + - macros + - mkdocs-video + - same-dir + - search + +markdown_extensions: + - abbr + - admonition + - attr_list + - codehilite: + guess_lang: false + - fontawesome_markdown + - footnotes + - md_in_html + - mdx_math + - mdx_truly_sane_lists: + nested_indent: 2 + - plantuml_markdown: + server: http://www.plantuml.com/plantuml + format: svg + - pymdownx.arithmatex: + generic: true + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight + - pymdownx.snippets: + auto_append: + - includes/abbreviations.md + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - toc: + permalink: "#" + toc_depth: 3 diff --git a/mkdocs.yaml b/mkdocs.yaml index 0eed1e1c44c..19e8c22b726 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -3,7 +3,7 @@ site_url: https://autowarefoundation.github.io/autoware-documentation repo_url: https://github.com/autowarefoundation/autoware edit_uri: https://github.com/autowarefoundation/autoware-documentation/edit/main/docs/ docs_dir: docs -copyright: Copyright © 2022 The Autoware Foundation +copyright: Copyright © 2023 The Autoware Foundation theme: name: material @@ -15,6 +15,7 @@ theme: - navigation.tabs - navigation.tabs.sticky - navigation.top + - navigation.footer favicon: assets/images/autoware-foundation.png icon: logo: fontawesome/solid/car @@ -44,15 +45,20 @@ extra_css: - https://use.fontawesome.com/releases/v5.15.4/css/all.css extra_javascript: - - https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML + - assets/js/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js plugins: - awesome-pages - exclude: regex: - - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?jpg).*$ + - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?gif|(.*\.)?jpg).*$ - ^(.*/)?[^.]*$ - - macros + - macros: + include_yaml: + - autoware_interfaces: yaml/autoware-interfaces.yaml + - mkdocs-video - same-dir - search @@ -64,14 +70,19 @@ markdown_extensions: guess_lang: false - fontawesome_markdown - footnotes + - md_in_html - mdx_math - mdx_truly_sane_lists: nested_indent: 2 - plantuml_markdown: server: http://www.plantuml.com/plantuml format: svg - - pymdownx.arithmatex + - pymdownx.arithmatex: + generic: true - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg - pymdownx.highlight - pymdownx.snippets: auto_append: diff --git a/tools/autoware-interfaces/README.md b/tools/autoware-interfaces/README.md new file mode 100644 index 00000000000..b7d8ffdb9e6 --- /dev/null +++ b/tools/autoware-interfaces/README.md @@ -0,0 +1,31 @@ +# Document generation for autoware interfaces + +Some of the documents under the `docs/design/autoware-interfaces` are generated by scripts. +If you would like to update these documents, please follow the steps below. + +## Usage + +Create a workspace anywhere and source the dependent message packages. + +```bash +mkdir -p workspace/src +cd workspace/src +git clone https://github.com/autowarefoundation/autoware_adapi_msgs.git +cd .. +colcon build +source install/setup.bash +``` + +Execute the script from the root of this repository. + +```bash +cd "repository root" +python3 tools/autoware-interfaces/generate.py +``` + +A document will be generated in the following paths. + +```txt +yaml/autoware-interfaces.yaml +docs/design/autoware-interfaces/ad-api/types/**/*.md +``` diff --git a/tools/autoware-interfaces/generate.py b/tools/autoware-interfaces/generate.py new file mode 100755 index 00000000000..c0f6fceb392 --- /dev/null +++ b/tools/autoware-interfaces/generate.py @@ -0,0 +1,162 @@ +#!/usr/bin/env python3 + +# Copyright 2023 The Autoware Contributors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# This script requires "source install/setup.bash" for dependent messages/services. + +import shutil +import yaml +from pathlib import Path + +from rosidl_adapter.parser import MessageSpecification +from rosidl_adapter.parser import parse_message_file +from rosidl_adapter.parser import parse_service_file +from ament_index_python.packages import get_package_share_directory + + +# cSpell:words indentless +class MyDumper(yaml.SafeDumper): + def increase_indent(self, flow=False, *args, **kwargs): + return super().increase_indent(flow=flow, indentless=False) + + +def load_markdown_metadata(path: Path): + lines = path.read_text().splitlines() + if (2 < len(lines)) and (lines[0] == "---"): + data = lines[1:lines.index("---", 1)] + data = yaml.safe_load("\n".join(data)) + return test_markdown_metadata(data, path) + return None + + +def test_markdown_metadata(data, path): + if "status" not in data: + raise KeyError(f"status in {path}") + return data + + +def is_documentation_msg(name: str): + targets = set(["autoware_adapi_version_msgs", "autoware_adapi_v1_msgs"]) + return name.split("/")[0] in targets + + +def strip_array_suffix(name: str): + return name.split("[")[0] + + +def resolve_msg_file_path(name: str): + pkg, ext, msg = name.split("/") + return Path(get_package_share_directory(pkg)).joinpath(ext, msg).with_suffix("." + ext) + + +def normalize_msg_name(name: str): + parts = str(name).split("/") + return parts[0] if len(parts) == 1 else f"{parts[0]}/msg/{parts[1]}" + + +def parse_rosidl_spec(depends: set, visited: set, spec: MessageSpecification): + fields = {field.name: normalize_msg_name(field.type) for field in spec.fields} + for name in fields.values(): + name = strip_array_suffix(name) + if name not in visited: + depends.add(name) + return fields + + +def parse_rosidl_file(depends: set, visited: set, specs: dict, name: str): + visited.add(name) + if is_documentation_msg(name): + pkg, ext, msg = name.split("/") + if ext == "msg": + msg = parse_message_file(pkg, resolve_msg_file_path(name)) + msg = parse_rosidl_spec(depends, visited, msg) + specs[name] = {"msg": msg} + specs[name] = {k: v for k, v in specs[name].items() if v} + if ext == "srv": + srv = parse_service_file(pkg, resolve_msg_file_path(name)) + req = parse_rosidl_spec(depends, visited, srv.request) + res = parse_rosidl_spec(depends, visited, srv.response) + specs[name] = {"req": req, "res": res} + specs[name] = {k: v for k, v in specs[name].items() if v} + +def main(): + # Create a list of data types used in adapi. + adapi = Path("docs/design/autoware-interfaces/ad-api/list/api") + pages = (load_markdown_metadata(path) for path in adapi.glob("**/*.md")) + pages = [page for page in pages if page] + + # Create a field list for each data type. + names = (page["type"]["name"] for page in pages) + specs = {} + visited = set() + depends = set(names) + while depends: + name = depends.pop() + parse_rosidl_file(depends, visited, specs, name) + + # Export a field list. + data = {"types": specs} + Path("yaml/autoware-interfaces.yaml").write_text(yaml.dump(data, Dumper=MyDumper)) + + # Create data type dependencies. + type_uses = {name: set() for name in specs} + type_used = {name: set() for name in specs} + for user, spec in specs.items(): + for field in spec.values(): + for name in field.values(): + name = strip_array_suffix(name) + if is_documentation_msg(name): + type_uses[user].add(name) + type_used[name].add(user) + + # Clean up data type pages. + base = Path("docs/design/autoware-interfaces/ad-api/types") + for path in base.iterdir(): + if path.is_dir(): + shutil.rmtree(path) + + # Generate data type pages. + for name in specs: + uses = list(sorted(type_uses[name])) + used = list(sorted(type_used[name])) + data = {"title": name, "uses": uses, "used": used} + data = {k: v for k, v in data.items() if v} + text = "---\n" + text += "# This file is generated by tools/autoware-interfaces/generate.py\n" + text += yaml.dump(data, Dumper=MyDumper).strip() + "\n" + text += "---\n\n" + text += "{% extends 'design/autoware-interfaces/templates/autoware-data-type.jinja2' %}\n" + text += "{% block definition %}\n" + text += "\n```txt\n" + text += resolve_msg_file_path(name).read_text().strip() + "\n" + text += "```\n\n" + text += "{% endblock %}\n" + path = base.joinpath(name).with_suffix(".md") + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + + ## Generate api list page. + text = "# List of Autoware AD API\n\n" + for title in sorted(page["title"] for page in pages): + text += f"- [{title}](.{title}.md)\n" + Path("docs/design/autoware-interfaces/ad-api/list/index.md").write_text(text) + + ## Generate api type page. + text = "# Types of Autoware AD API\n\n" + for spec in sorted(specs): + text += f"- [{spec}](./{spec}.md)\n" + Path("docs/design/autoware-interfaces/ad-api/types/index.md").write_text(text) + +main() diff --git a/yaml/autoware-interfaces.yaml b/yaml/autoware-interfaces.yaml new file mode 100644 index 00000000000..a86ed502e4d --- /dev/null +++ b/yaml/autoware-interfaces.yaml @@ -0,0 +1,200 @@ +types: + autoware_adapi_v1_msgs/msg/DoorCommand: + msg: + command: uint8 + index: uint32 + autoware_adapi_v1_msgs/msg/DoorLayout: + msg: + description: string + roles: uint8[] + autoware_adapi_v1_msgs/msg/DoorStatus: + msg: + status: uint8 + autoware_adapi_v1_msgs/msg/DoorStatusArray: + msg: + doors: autoware_adapi_v1_msgs/msg/DoorStatus[] + stamp: builtin_interfaces/msg/Time + autoware_adapi_v1_msgs/msg/DynamicObject: + msg: + classification: autoware_adapi_v1_msgs/msg/ObjectClassification[] + existence_probability: float64 + id: unique_identifier_msgs/msg/UUID + kinematics: autoware_adapi_v1_msgs/msg/DynamicObjectKinematics + shape: shape_msgs/msg/SolidPrimitive + autoware_adapi_v1_msgs/msg/DynamicObjectArray: + msg: + header: std_msgs/msg/Header + objects: autoware_adapi_v1_msgs/msg/DynamicObject[] + autoware_adapi_v1_msgs/msg/DynamicObjectKinematics: + msg: + accel: geometry_msgs/msg/Accel + pose: geometry_msgs/msg/Pose + predicted_paths: autoware_adapi_v1_msgs/msg/DynamicObjectPath[] + twist: geometry_msgs/msg/Twist + autoware_adapi_v1_msgs/msg/DynamicObjectPath: + msg: + confidence: float64 + path: geometry_msgs/msg/Pose[] + time_step: builtin_interfaces/msg/Duration + autoware_adapi_v1_msgs/msg/Gear: + msg: + status: uint8 + autoware_adapi_v1_msgs/msg/HazardLights: + msg: + status: uint8 + autoware_adapi_v1_msgs/msg/LocalizationInitializationState: + msg: + stamp: builtin_interfaces/msg/Time + state: uint16 + autoware_adapi_v1_msgs/msg/MotionState: + msg: + stamp: builtin_interfaces/msg/Time + state: uint16 + autoware_adapi_v1_msgs/msg/MrmState: + msg: + behavior: uint16 + stamp: builtin_interfaces/msg/Time + state: uint16 + autoware_adapi_v1_msgs/msg/ObjectClassification: + msg: + label: uint8 + probability: float64 + autoware_adapi_v1_msgs/msg/OperationModeState: + msg: + is_autonomous_mode_available: bool + is_autoware_control_enabled: bool + is_in_transition: bool + is_local_mode_available: bool + is_remote_mode_available: bool + is_stop_mode_available: bool + mode: uint8 + stamp: builtin_interfaces/msg/Time + autoware_adapi_v1_msgs/msg/ResponseStatus: + msg: + code: uint16 + message: string + success: bool + autoware_adapi_v1_msgs/msg/Route: + msg: + data: autoware_adapi_v1_msgs/msg/RouteData[<=1] + header: std_msgs/msg/Header + autoware_adapi_v1_msgs/msg/RouteData: + msg: + goal: geometry_msgs/msg/Pose + segments: autoware_adapi_v1_msgs/msg/RouteSegment[] + start: geometry_msgs/msg/Pose + autoware_adapi_v1_msgs/msg/RouteOption: + msg: + allow_goal_modification: bool + autoware_adapi_v1_msgs/msg/RoutePrimitive: + msg: + id: int64 + type: string + autoware_adapi_v1_msgs/msg/RouteSegment: + msg: + alternatives: autoware_adapi_v1_msgs/msg/RoutePrimitive[] + preferred: autoware_adapi_v1_msgs/msg/RoutePrimitive + autoware_adapi_v1_msgs/msg/RouteState: + msg: + stamp: builtin_interfaces/msg/Time + state: uint16 + autoware_adapi_v1_msgs/msg/SteeringFactor: + msg: + detail: string + direction: uint16 + distance: float32[2] + pose: geometry_msgs/msg/Pose[2] + status: uint16 + type: uint16 + autoware_adapi_v1_msgs/msg/SteeringFactorArray: + msg: + factors: autoware_adapi_v1_msgs/msg/SteeringFactor[] + header: std_msgs/msg/Header + autoware_adapi_v1_msgs/msg/TurnIndicators: + msg: + status: uint8 + autoware_adapi_v1_msgs/msg/VehicleDimensions: + msg: + footprint: geometry_msgs/msg/Polygon + front_overhang: float32 + height: float32 + left_overhang: float32 + rear_overhang: float32 + right_overhang: float32 + wheel_base: float32 + wheel_radius: float32 + wheel_tread: float32 + wheel_width: float32 + autoware_adapi_v1_msgs/msg/VehicleKinematics: + msg: + accel: geometry_msgs/msg/AccelWithCovarianceStamped + geographic_pose: geographic_msgs/msg/GeoPointStamped + pose: geometry_msgs/msg/PoseWithCovarianceStamped + twist: geometry_msgs/msg/TwistWithCovarianceStamped + autoware_adapi_v1_msgs/msg/VehicleStatus: + msg: + energy_percentage: float32 + gear: autoware_adapi_v1_msgs/msg/Gear + hazard_lights: autoware_adapi_v1_msgs/msg/HazardLights + stamp: builtin_interfaces/msg/Time + steering_tire_angle: float64 + turn_indicators: autoware_adapi_v1_msgs/msg/TurnIndicators + autoware_adapi_v1_msgs/msg/VelocityFactor: + msg: + detail: string + distance: float32 + pose: geometry_msgs/msg/Pose + status: uint16 + type: uint16 + autoware_adapi_v1_msgs/msg/VelocityFactorArray: + msg: + factors: autoware_adapi_v1_msgs/msg/VelocityFactor[] + header: std_msgs/msg/Header + autoware_adapi_v1_msgs/srv/AcceptStart: + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/ChangeOperationMode: + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/ClearRoute: + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/GetDoorLayout: + res: + doors: autoware_adapi_v1_msgs/msg/DoorLayout[] + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/GetVehicleDimensions: + res: + dimensions: autoware_adapi_v1_msgs/msg/VehicleDimensions + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/InitializeLocalization: + req: + pose: geometry_msgs/msg/PoseWithCovarianceStamped[<=1] + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/SetDoorCommand: + req: + doors: autoware_adapi_v1_msgs/msg/DoorCommand[] + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/SetRoute: + req: + goal: geometry_msgs/msg/Pose + header: std_msgs/msg/Header + option: autoware_adapi_v1_msgs/msg/RouteOption + segments: autoware_adapi_v1_msgs/msg/RouteSegment[] + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_v1_msgs/srv/SetRoutePoints: + req: + goal: geometry_msgs/msg/Pose + header: std_msgs/msg/Header + option: autoware_adapi_v1_msgs/msg/RouteOption + waypoints: geometry_msgs/msg/Pose[] + res: + status: autoware_adapi_v1_msgs/msg/ResponseStatus + autoware_adapi_version_msgs/srv/InterfaceVersion: + res: + major: uint16 + minor: uint16 + patch: uint16