diff --git a/.github/sync-files.yaml b/.github/sync-files.yaml index 8485801ec61..e07c3801d3d 100644 --- a/.github/sync-files.yaml +++ b/.github/sync-files.yaml @@ -4,6 +4,12 @@ - source: CONTRIBUTING.md - source: DISCLAIMER.md - source: LICENSE + - source: .github/ISSUE_TEMPLATE/bug.yaml + - source: .github/ISSUE_TEMPLATE/config.yml + - source: .github/ISSUE_TEMPLATE/task.yaml + - source: .github/PULL_REQUEST_TEMPLATE.md + - source: .github/PULL_REQUEST_TEMPLATE/small-change.md + - source: .github/PULL_REQUEST_TEMPLATE/standard-change.md - source: .github/dependabot.yaml - source: .github/workflows/pre-commit.yaml - source: .github/workflows/pre-commit-optional.yaml @@ -15,3 +21,7 @@ - source: .prettierignore - source: .prettierrc.yaml - source: .yamllint.yaml + +- repository: autowarefoundation/autoware_common + files: + - source: .github/workflows/sync-files.yaml diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml index 045ca76bb2e..cf3049cb223 100644 --- a/.github/workflows/deploy-docs.yaml +++ b/.github/workflows/deploy-docs.yaml @@ -38,4 +38,4 @@ jobs: uses: autowarefoundation/autoware-github-actions/deploy-docs@v1 with: token: ${{ secrets.GITHUB_TOKEN }} - latest: ${{ github.ref_name == github.event.repository.default_branch }} + latest: ${{ github.event_name != 'pull_request_target' && github.ref_name == github.event.repository.default_branch }} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000000..c493cad4da5 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +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 +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][mozilla coc]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][faq]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla coc]: https://github.com/mozilla/diversity +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..22c7ee28e8d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing + +See . diff --git a/DISCLAIMER.md b/DISCLAIMER.md new file mode 100644 index 00000000000..1b5a9bbe4d9 --- /dev/null +++ b/DISCLAIMER.md @@ -0,0 +1,46 @@ +DISCLAIMER + +“Autoware” will be provided by The Autoware Foundation under the Apache License 2.0. +This “DISCLAIMER” will be applied to all users of Autoware (a “User” or “Users”) with +the Apache License 2.0 and Users shall hereby approve and acknowledge all the contents +specified in this disclaimer below and will be deemed to consent to this +disclaimer without any objection upon utilizing or downloading Autoware. + +Disclaimer and Waiver of Warranties + +1. AUTOWARE FOUNDATION MAKES NO REPRESENTATION OR WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, WITH RESPECT TO PROVIDING AUTOWARE (the “Service”) + including but not limited to any representation or warranty (i) of fitness or + suitability for a particular purpose contemplated by the Users, (ii) of the + expected functions, commercial value, accuracy, or usefulness of the Service, + (iii) that the use by the Users of the Service complies with the laws and + regulations applicable to the Users or any internal rules established by + industrial organizations, (iv) that the Service will be free of interruption or + defects, (v) of the non-infringement of any third party's right and (vi) the + accuracy of the content of the Services and the software itself. + +2. The Autoware Foundation shall not be liable for any damage incurred by the + User that are attributable to the Autoware Foundation for any reasons + whatsoever. UNDER NO CIRCUMSTANCES SHALL THE AUTOWARE FOUNDATION BE LIABLE FOR + INCIDENTAL, INDIRECT, SPECIAL OR FUTURE DAMAGES OR LOSS OF PROFITS. + +3. A User shall be entirely responsible for the content posted by the User and + its use of any content of the Service or the Website. If the User is held + responsible in a civil action such as a claim for damages or even in a criminal + case, the Autoware Foundation and member companies, governments and academic & + non-profit organizations and their directors, officers, employees and agents + (collectively, the “Indemnified Parties”) shall be completely discharged from + any rights or assertions the User may have against the Indemnified Parties, or + from any legal action, litigation or similar procedures. + +Indemnity + +A User shall indemnify and hold the Indemnified Parties harmless from any of +their damages, losses, liabilities, costs or expenses (including attorneys' +fees or criminal compensation), or any claims or demands made against the +Indemnified Parties by any third party, due to or arising out of, or in +connection with utilizing Autoware (including the representations and +warranties), the violation of applicable Product Liability Law of each country +(including criminal case) or violation of any applicable laws by the Users, or +the content posted by the User or its use of any content of the Service or the +Website. diff --git a/NOTICE b/NOTICE new file mode 100644 index 00000000000..7b47ca7b3dd --- /dev/null +++ b/NOTICE @@ -0,0 +1,5 @@ +autowarefoundation/autoware-documentation +Copyright 2021 The Autoware Foundation + +This product includes software developed at +The Autoware Foundation (https://www.autoware.org/). diff --git a/docs/contributing/.pages b/docs/contributing/.pages index cd0f83133e9..210e2aea766 100644 --- a/docs/contributing/.pages +++ b/docs/contributing/.pages @@ -1,5 +1,6 @@ nav: - index.md + - license.md - coding-guidelines - testing-guidelines - documentation-guidelines diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 3f8398267e8..c8c3c6cfb5f 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,15 +1,69 @@ # Contributing -!!! warning +This page explains how to contribute to Autoware. - Under Construction +First, conform to the [Code of conduct](#contribution-workflows) section for the general manners in contributions. + +See the [Contribution workflows](#contribution-workflows) section for the workflows. +Also, make sure the contribution is in line with the following guidelines: + +- [Coding guidelines](coding-guidelines/index.md): for contributing source code +- [Testing guidelines](testing-guidelines/index.md): for contributing tests +- [Documentation guidelines](documentation-guidelines/index.md): for contributing documents +- [Pull request guidelines](pull-request-guidelines/index.md): for submitting pull requests +- [Discussion guidelines](discussion-guidelines/index.md): for discussing with other contributors +- [Support guidelines](../help/support-guidelines.md): for finding the right channel when you need help + +It is recommended to read the [Contributing pages in ROS 2 Docs](https://docs.ros.org/en/rolling/Contributing.html) as well because Autoware's guidelines generally depend on them. + +For general information about OSS contributions, [Open Source Guides](https://opensource.guide/) by GitHub is a good resource. + +!!!info + + If you want to make changes to the guidelines in this documentation site, you can open a new discussion thread and propose it. + +## Code of conduct + +We welcome contributions from everyone. +To ensure our community stays open and healthy, we adhere to the [Contributor Covenant](https://www.contributor-covenant.org/), a widely used [code of conduct](https://github.com/autowarefoundation/autoware/blob/main/CODE_OF_CONDUCT.md) adopted by many other communities listed [here](https://www.contributor-covenant.org/adopters/). + +Everyone participating in the Autoware community is expected to follow the code of conduct. +If someone in the community happens to be violating these terms, let the maintainers know, and we will address it as soon as possible. + +!!!warning + + Note that contributions that ignore guidelines are not contributions but nuisances. ## Contribution workflows -### Issues +There are several types of contributions and the workflows differ between the types. +See the description for your contribution type. ### Discussions -### Small pull requests +You can contribute to Autoware by facilitating discussions: + +- Find a bug and open a new issue. +- Propose an idea of features that will enhance Autoware. +- Join an existing discussion and express your opinion. +- Organize discussions for other contributors. +- Answer questions and support other contributors. + +See our [support guidelines](../help/support-guidelines.md) for the detailed steps. + +### Pull requests + +You can submit a pull request directly (without opening an issue) if it is small like the following: + +- Update a small part of documents. +- Fix spelling mistakes. +- Fix CI failures. +- Fix warnings detected by compilers or analysis tools. +- Make small changes to a single package. + +Otherwise, create an issue or a discussion thread before submitting a pull request and discuss the approach with maintainers. + +Also, regardless of the size of your pull request, follow the pull request template of the target repository. -### Large pull requests +See our [pull request guidelines](pull-request-guidelines/index.md) for the detailed steps. +See [License](license.md) for the license notations. diff --git a/docs/contributing/license.md b/docs/contributing/license.md new file mode 100644 index 00000000000..4345d570e80 --- /dev/null +++ b/docs/contributing/license.md @@ -0,0 +1,44 @@ +# License + +Autoware is licensed under Apache License 2.0. +Thus all contributions will be licensed as such as per clause 5 of the Apache License 2.0: + +```text +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. +``` + +Here is an example copyright header to add to the top of a new file: + +```text +Copyright [first year of contribution] The Autoware Contributors +SPDX-License-Identifier: Apache-2.0 +``` + +We don't write copyright notations of each contributor here. +Instead, we place them in the `NOTICE` file like the following. + +```text +This product includes code developed by [company name]. +Copyright [first year of contribution] [company name] +``` + +Let us know if your legal department has a special request for the copyright notation. + +Currently, the old formats explained [here](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/87c5e5880a18068116dd886ad56e1bfc29e694c4/CONTRIBUTING.md) are also acceptable. +Those old formats can be replaced by this new format if the original authors agree. +Note that we won't write their copyrights to the `NOTICE` file unless they agree with the new format. + +References: + +- +- +- +- +- +- diff --git a/docs/contributing/pull-request-guidelines/.pages b/docs/contributing/pull-request-guidelines/.pages index 35fd5a113be..160891a81d7 100644 --- a/docs/contributing/pull-request-guidelines/.pages +++ b/docs/contributing/pull-request-guidelines/.pages @@ -1,2 +1,4 @@ nav: - index.md + - commit-guidelines.md + - review-tips.md diff --git a/docs/contributing/pull-request-guidelines/commit-guidelines.md b/docs/contributing/pull-request-guidelines/commit-guidelines.md new file mode 100644 index 00000000000..1043bb0f066 --- /dev/null +++ b/docs/contributing/pull-request-guidelines/commit-guidelines.md @@ -0,0 +1,140 @@ +# Commit guidelines + +This page explains our guidelines related to committing. + +## Branch rules + +### Start branch names with the corresponding issue numbers (advisory, non-automated) + +#### Rationale + +- Developers can quickly find the corresponding issues. +- It is helpful for tools. +- It is consistent with GitHub's default behavior. + +#### Exception + +If there are no corresponding issues, you can ignore this rule. + +#### Example + +```text +123-add-feature +``` + +#### Reference + +- [GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue) + +### Use `kebab-case` for the separator of branch names (advisory, non-automated) + +#### Rationale + +- It is consistent with GitHub's default behavior. + +#### Example + +```text +123-add-feature +``` + +#### Reference + +- [GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue) + +### Make branch names descriptive (advisory, non-automated) + +#### Rationale + +- It can avoid conflicts of names. +- Developers can understand the purpose of the branch. + +#### Exception + +If you have already submitted a pull request, you do not have to change the branch name because you need to re-create a pull request, which is noisy and a waste of time. +Be careful from the next time. + +#### Example + +Usually it is good to start with a verb. + +```text +123-fix-memory-leak-of-trajectory-follower +``` + +## Commit rules + +### Sign-off your commits (required, automated) + +Developers must certify that they wrote or otherwise have the right to submit the code they are contributing to the project. + +#### Rationale + +If not, it will lead to complex license problems. + +#### Example + +```bash +git commit -s +``` + +```text +feat: add a feature + +Signed-off-by: Autoware +``` + +#### Reference + +- [GitHub Apps - DCO](https://github.com/apps/dco) + +### Follow `Conventional Commits` (required, automated) + +#### Rationale + +- It can generate categorized changelog, for example using [git-cliff](https://github.com/orhun/git-cliff). + +#### Example + +```text +feat(trajectory_follower): add an awesome feature +``` + +Note that you have to start the description part (`add an awesome feature`) with a lowercase. + +Since Autoware uses the `Squash and merge` method of GitHub, you need to make the PR title follow `Conventional Commits` as well. + +#### Reference + +- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) +- [commitizen/conventional-commit-types](https://github.com/commitizen/conventional-commit-types) +- [GitHub Docs](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github#squashing-your-merge-commits) + +### Add the related node names to the scope of `Conventional Commits` (advisory, non-automated) + +#### Rationale + +- The package maintainer can become aware of the pull request by seeing the notification. +- It can make the changelog clearer. + +#### Example + +```text +feat(trajectory_follower): add an awesome feature +``` + +### Keep a pull request small (advisory, non-automated) + +#### Rationale + +- Small pull requests are easy to understand for reviewers. +- Small pull requests are easy to revert for maintainers. + +#### Exception + +It is acceptable if it is agreed with maintainers that there is no other way but to submit a big pull request. + +#### Example + +- Avoid developing two features in one pull request. +- Avoid mixing `feat`, `fix`, and `refactor` in the same commit. diff --git a/docs/contributing/pull-request-guidelines/images/after-press-a.png b/docs/contributing/pull-request-guidelines/images/after-press-a.png new file mode 100644 index 00000000000..479f6e58d52 Binary files /dev/null and b/docs/contributing/pull-request-guidelines/images/after-press-a.png differ diff --git a/docs/contributing/pull-request-guidelines/images/before-press-a.png b/docs/contributing/pull-request-guidelines/images/before-press-a.png new file mode 100644 index 00000000000..aaeccf1eae9 Binary files /dev/null and b/docs/contributing/pull-request-guidelines/images/before-press-a.png differ diff --git a/docs/contributing/pull-request-guidelines/images/ci-checks.png b/docs/contributing/pull-request-guidelines/images/ci-checks.png new file mode 100644 index 00000000000..9ec9f51c791 Binary files /dev/null and b/docs/contributing/pull-request-guidelines/images/ci-checks.png differ diff --git a/docs/contributing/pull-request-guidelines/images/gh-pr-checkout.png b/docs/contributing/pull-request-guidelines/images/gh-pr-checkout.png new file mode 100644 index 00000000000..9cf5fb7f5f5 Binary files /dev/null and b/docs/contributing/pull-request-guidelines/images/gh-pr-checkout.png differ diff --git a/docs/contributing/pull-request-guidelines/index.md b/docs/contributing/pull-request-guidelines/index.md index 3d8aa0fb086..2240fb8c136 100644 --- a/docs/contributing/pull-request-guidelines/index.md +++ b/docs/contributing/pull-request-guidelines/index.md @@ -1,5 +1,133 @@ # Pull request guidelines -!!! warning +## General pull request workflow - Under Construction +Autoware uses the fork-and-pull model. +Refer to [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) for the detailed explanation of the model. + +The following is a general example of our pull request workflow. + +1. Create a fork. (for the first time only) +2. Create an issue. + - Discuss the approach to the issue with maintainers. +3. Write code in the agreed approach. + - Write the tests and documentation if necessary. + - Follow our guidelines when you write code, tests, and documentation. + - [Coding guidelines](../coding-guidelines/index.md) + - [Testing guidelines](../testing-guidelines/index.md) + - [Documentation guidelines](../documentation-guidelines/index.md) + - Follow our [Commit guidelines](commit-guidelines.md) when commit your change. +4. Test the code. + - In the later review process, you will need to write what tests you have done. +5. Create a pull request. + - Read the pull request template carefully and fill the required content. + - Assign reviewers after creating a pull request. + - If you have no rights to assign reviewers, just mention them instead. + - If you are not sure who to set reviewers, contact to the people written as the `maintainer` tag in `package.xml`. +6. Wait for the pull request to be reviewed. + - The reviewers will review your code following our [review guidelines](review-guidelines.md). + - Take a look at the guidelines as well because it is good to understand the thoughts of the reviewer's side. + - If [CI checks](#ci-checks) have failed, fix the errors. +7. Address the review comments pointed out by the reviewers. + - If you cannot understand or agree with a review comment, discuss it with the reviewers and find a rational reason. + - The author should be responsible for the final content of their pull request. + - The reviewers are obligated to make the author understand the meanings of each comment. + - After you have done with them, re-request a review to the reviewers and back to 6. + - If there are no more new review comments, the reviewers will approve the pull request and go to 6. +8. Merge the pull request. + - Confirm all items of the checklist are checked off before merging. + - Anyone with write access can merge the pull request if there is no special request from maintainers. + - Generally, the author is expected to merge it to feel responsible for their pull request. + - If the author does not have write access, ask the reviewers or maintainers. + - It is the author's responsibility to care about their own pull request until it is merged. + +## CI checks + +Autoware has several checks for a pull request. +The results are shown at the bottom of the pull request page as below. + +![ci-checks](images/ci-checks.png) + +If the ❌ mark is shown, click the `Details` button and investigate the failure reason. + +If the `Required` mark is shown, you cannot merge the pull request unless you resolve the error. +If not, it is optional, but preferably it should be fixed. + +The following sections explain about common CI checks in Autoware. +Note that some repositories may have different settings. + +### DCO + +The Developer Certificate of Origin (DCO) is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project. + +This workflow checks whether the pull request fulfills `DCO`. +You need to confirm the [required items](https://developercertificate.org/) and commit with `git commit -s`. + +Refer to the [GitHub App page](https://github.com/apps/dco) for more information. + +### semantic-pull-request + +Autoware uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) with the settings of [commitizen/conventional-commit-types](https://github.com/commitizen/conventional-commit-types). + +This workflow checks whether the pull request follows `Conventional Commits`. + +Note that if there is only one commit in the pull request, you need to make the commit title semantic as well. +This is due to GitHub's non-intuitive behavior when there is only one commit. +GitHub uses the commit title for the squashed commit message, instead of the pull request title. + +Refer to [amannn/action-semantic-pull-request](https://github.com/amannn/action-semantic-pull-request) for more detailed behaviors of this workflow. + +See our [commit guidelines](commit-guidelines.md) for the detailed rules. + +### pre-commit + +[pre-commit](https://pre-commit.com/) is a tool to run formatters or linters when you commit. + +This workflow checks whether the pull request has no error with `pre-commit`. + +In the workflow `pre-commit.ci - pr` is enabled in the repository, it will automatically fix errors by [pre-commit.ci](https://pre-commit.ci/) as many as possible. +If there are some errors remain, fix them manually. + +You can run `pre-commit` in your local environment by the following command: + +```bash +pre-commit run -a +``` + +Or you can install `pre-commit` to the repository and automatically run it before committing: + +```bash +pre-commit install +``` + +Since it is difficult to detect errors with no false positives, some jobs are split into another config file and marked as optional. +To check them, use the `--config` option: + +```bash +pre-commit run -a --config .pre-commit-config-optional.yaml +``` + +### spell-check-differential + +This workflow detects spelling mistakes using [CSpell](https://github.com/streetsidesoftware/cspell) with [our dictionary file](https://github.com/tier4/autoware-spell-check-dict/blob/main/.cspell.json). +You can submit pull requests to [tier4/autoware-spell-check-dict](https://github.com/tier4/autoware-spell-check-dict) to update the dictionary. + +Since it is difficult to detect errors with no false positives, it is an optional workflow, but it is preferable to remove spelling mistakes as many as possible. + +### build-and-test-differential + +This workflow checks `colcon build` and `colcon test` for the pull request. +To make the CI faster, it doesn't check all packages but only modified packages and the dependencies. + +### build-and-test-differential-self-hosted + +This workflow is the `ARM64` version of `build-and-test-differential`. +You need to add the `ARM64` label to run this workflow. + +For reference information, since ARM machines are not supported by GitHub-hosted runners, we use self-hosted runners prepared by the AWF. +Refer to [GitHub Docs](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) for the details about self-hosted runners. + +### deploy-docs + +This workflow deploys the preview documentation site for the pull request. +You need to add the `documentation` label to run this workflow. diff --git a/docs/contributing/pull-request-guidelines/review-tips.md b/docs/contributing/pull-request-guidelines/review-tips.md new file mode 100644 index 00000000000..148226b4348 --- /dev/null +++ b/docs/contributing/pull-request-guidelines/review-tips.md @@ -0,0 +1,45 @@ +# Tips + +This page introduces tips around pull requests or reviews. + +## Toggle annotations or review comments in the diff view + +There will be some annotations or review comments in the diff view during your review. + +Press the `A` key to toggle annotations. + +Before: + +![before-press-a](images/before-press-a.png) + +After: + +![after-press-a](images/after-press-a.png) + +Also, press the `I` key to toggle review comments. + +Refer to [GitHub Docs](https://docs.github.com/en/get-started/using-github/keyboard-shortcuts) for other keyboard shortcuts. + +## View code in the web-based Visual Studio Code + +You can open `Visual Studio Code` from your browser to view code in a rich UI. +Press the `.` key on any repository or pull request. + +Refer to [github/dev](https://github.com/github/dev) for more detailed usage. + +## Check out the branch of a pull request quickly + +If you want to check out the branch of a pull request, it's generally troublesome with the fork-and-pull model. + +```bash +# Copy the user name and the fork URL. +git remote add {user-name} {fork-url} +git checkout {user-name}/{branch-name} +git remote rm {user-name} # To clean up +``` + +Instead, you can use [GitHub CLI](https://cli.github.com/) to simplify the steps, just run `gh pr checkout {pr-number}`. + +You can copy the command from the top right of the pull request page. + +![gh-pr-checkout](images/gh-pr-checkout.png) diff --git a/docs/design/.pages b/docs/design/.pages index e7530c0898b..90c91c30d21 100644 --- a/docs/design/.pages +++ b/docs/design/.pages @@ -1,5 +1,6 @@ nav: - - index.md + - index. + - autoware-concepts - autoware-interface - configuration-management - node-diagram diff --git a/docs/design/autoware-concepts/.pages b/docs/design/autoware-concepts/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/design/autoware-concepts/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/installation/autoware/local-installation.md b/docs/design/autoware-concepts/index.md similarity index 63% rename from docs/installation/autoware/local-installation.md rename to docs/design/autoware-concepts/index.md index 06005ba2b7c..9c0d4c4d235 100644 --- a/docs/installation/autoware/local-installation.md +++ b/docs/design/autoware-concepts/index.md @@ -1,4 +1,4 @@ -# Local installation +# Autoware concepts !!! warning diff --git a/docs/design/component-interfaces/images/Control-Bus-ODD-Architecture.drawio.svg b/docs/design/component-interfaces/images/Control-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..4f406971910 --- /dev/null +++ b/docs/design/component-interfaces/images/Control-Bus-ODD-Architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Planning
Planning
Localization
Localization
Control
Control
Vehicle Interface
Vehicle InterfaceVehicle Kinematic Statenav_msgs/OdometryTrajectoryautoware_auto_planning_msgs/TrajectoryVehicle Signal Commandsautoware_auto_vehicle_msgs/- HandBrakeCommand- HazardLightsCommand- HeadlightsCommand- HornCommand- StationaryLockingCommand- TurnIndicatorsCommand- WipersCommandVehicle Control Commandautoware_auto_vehicle_msgs/AckermannControlCommandActuation Status
acceleration, brake, steering
acceleration, brake, steeringSteering Status
steering_angle
steering_angleText is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/component-interfaces/images/Planning-Bus-ODD-Architecture.drawio.svg b/docs/design/component-interfaces/images/Planning-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..e3ca8777d80 --- /dev/null +++ b/docs/design/component-interfaces/images/Planning-Bus-ODD-Architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Planning
Planning
Perception
Perception
Localization
Localization
Control
Control
Map Server
Map Server
Vehicle Interface
Vehicle Interface3D Object Predictionsautoware_auto_perception_msgs/PredictedObjectsTraffic Light Response🚦Vehicle Kinematic Statenav_msgs/OdometryTrajectoryautoware_auto_planning_msgs/TrajectoryVehicle Signal Commandsautoware_auto_vehicle_msgs/- HandBrakeCommand- HazardLightsCommand- HeadlightsCommand- HornCommand- StationaryLockingCommand- TurnIndicatorsCommand- WipersCommandLanelet2 Mapautoware_auto_mapping_msgs/HADMapBinVehicle Control Commandautoware_auto_vehicle_msgs/AckermannControlCommandVehicle Signal Reportsautoware_auto_vehicle_msgs/- GearReport- HandBrakeReport- HazardLightsReport- HeadlightsReport- HornReport- TurnIndicatorsReport- WipersReport
Diagnostics Manager
Diagnostics ManagerTraffic Light Query🚦
User Interface
User InterfaceEngagement Request- Goal Posegeometry_msgs/PoseStampedEngagement Response- Mission Status⏳Error StatusText is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/component-interfaces/images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg b/docs/design/component-interfaces/images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..ab30e1c47c0 --- /dev/null +++ b/docs/design/component-interfaces/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/design/component-interfaces/planning-control-vehicle-interface.md b/docs/design/component-interfaces/planning-control-vehicle-interface.md new file mode 100644 index 00000000000..9ffe28c0d13 --- /dev/null +++ b/docs/design/component-interfaces/planning-control-vehicle-interface.md @@ -0,0 +1,284 @@ +# Autoware Core/Universe Architecture + +## Planning + +![Node diagram](images/Planning-Bus-ODD-Architecture.drawio.svg) + +### Inputs + +#### 3D Object Predictions + +set of perceived objects around ego that need to be avoided when planning a trajectory. Published by the Perception module. + +- [autoware_auto_perception_msgs/msg/PredictedObjects](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_perception_msgs/msg/PredictedObjects.idl) + - [std_msgs/Header](https://docs.ros.org/en/noetic/api/std_msgs/html/msg/Header.html) header + - sequence<[autoware_auto_perception_msgs::msg::PredictedObject](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_perception_msgs/msg/PredictedObject.idl)> objects + - unique_identifier_msgs::msg::UUID uuid + - float existence_probability + - sequence<[autoware_auto_perception_msgs::msg::ObjectClassification](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_perception_msgs/msg/ObjectClassification.idl)> classification + - uint8 classification + - float probability + - [autoware_auto_perception_msgs::msg::PredictedObjectKinematics](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_perception_msgs/msg/PredictedObjectKinematics.idl) kinematics + - [geometry_msgs::msg::PoseWithCovariance](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/PoseWithCovariance.html) initial_pose + - [geometry_msgs::msg::TwistWithCovariance](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/TwistWithCovariance.html) + - [geometry_msgs::msg::AccelWithCovariance](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/AccelWithCovariance.html) initial_acceleration + - sequence<[autoware_auto_perception_msgs::msg::PredictedPath](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_perception_msgs/msg/PredictedPath.idl), 10> predicted_paths + - sequence<[geometry_msgs::msg::Pose](https://docs.ros.org/en/lunar/api/geometry_msgs/html/msg/Pose.html), 100> path + - builtin_interfaces::msg::Duration time_step + - float confidence + - sequence<[autoware_auto_perception_msgs::msg::Shape](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_perception_msgs/msg/Shape.idl), 5> shape + - [geometry_msgs::msg::Polygon](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Polygon.html) polygon + - float height + +#### Traffic Light Response + +Service response with traffic light information. **The message definition is under discussion.** + +- TrafficLightResponse + - uint64 traffic_light_id + - uint8 traffic_light_state + +With the traffic_light_state being one of the following + +- GREEN = 1 +- GREEN_BLINKING = 2 +- YELLOW = 3 +- YELLOW_BLINKING = 4 +- RED = 5 +- RED_BLINKING = 6 +- OFF = 7 +- UNKNOWN = 8 + +#### Vehicle kinematic state + +current position and orientation of ego. Published by the Localization module. + +- VehicleKinematicState + - [nav_msgs/Odometry](https://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Odometry.html) + - std_msgs/Header header + - string child_frame_id + - [geometry_msgs/PoseWithCovariance pose](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/PoseWithCovariance.html) + - [geometry_msgs/TwistWithCovariance twist](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/TwistWithCovariance.html) + +#### Lanelet2 Map + +map of the environment where the planning takes place. Published by the Map Server. + +- [autoware_auto_mapping_msgs/msg/HADMapBin](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_mapping_msgs/msg/HADMapBin.idl) + - std_msgs::msg::Header header + - uint8 map_format + - string format_version + - string map_version + - sequence < uint8 > data + +#### Goal Pose + +target pose of ego. Published by the User Interface. + +- [geometry_msgs/PoseStamped](https://docs.ros.org/en/lunar/api/geometry_msgs/html/msg/PoseStamped.html) + +#### Engagement Response + +TBD. + +**The message definition is under discussion.** + +#### Error status + +a status corresponding to the current state of Autoware. Used by the Vehicle Interface to switch between different modes in case of emergency. Published by the Diagnostic Manager. + +- [autoware_auto_system_msgs/msg/EmergencyState](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_system_msgs/msg/EmergencyState.idl) + - builtin_interfaces::msg::Time stamp + - uint8 state + +With the state being one of the following: + +- NORMAL = 1 +- OVERRIDE_REQUESTING = 2 +- MRM_OPERATING = 3 +- MRM_SUCCEEDED = 4 +- MRM_FAILED = 5 + +[TODO] original design for these messages: diagnostic manager also publishes an overriding emergency control command ([Add the monitoring system related messages - Autoware.Auto](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/merge_requests/38)). Possible new design: gate of the vehicle interface switches to the emergency control command (generated by another controller) when receiving an OVERRIDE_REQUESTING message. + +**The message definition is under discussion.** + +### Outputs + +#### Traffic Light Query + +service request for the state of a specific traffic light. Sent to the Perception module. + +- uint64 traffic_light_id + +**The message definition is under discussion.** + +#### Trajectory + +A sequence of space and velocity points to be followed by the controller. + +- [autoware_auto_planning_msgs/Trajectory](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_planning_msgs/msg/Trajectory.idl) + - [std_msgs/Header](https://docs.ros.org/en/noetic/api/std_msgs/html/msg/Header.html) header + - sequence<[autoware_auto_planning_msgs::msg::TrajectoryPoint](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_planning_msgs/msg/TrajectoryPoint.idl), 100> points + - builtin_interfaces::msg::Duration time_from_start + - [geometry_msgs::msg::Pose](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Pose.html) pose + - float longitudinal_velocity_mps + - float lateral_velocity_mps + - float acceleration_mps2 + - float heading_rate_rps + - float front_wheel_angle_rad + - float rear_wheel_angle_rad + +#### Vehicle Signal Commands + +Commands for various elements of the vehicle unrelated to motion. Sent to the Vehicle Interface. (See [autoware_auto_vehicle_msgs](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/tree/master/autoware_auto_vehicle_msgs/msg) for the definition.) + +- HandBrake Command +- Hazard Lights Command +- Headlights Command +- Horn Command +- Stationary Locking Command +- Turn Indicator Command +- Wipers Command + +#### Missions Status + +TBD. + +**The message definition is under discussion.** + +#### Engagement Request + +TBD, + +**The message definition is under discussion.** + +## Control + +![Node diagram](images/Control-Bus-ODD-Architecture.drawio.svg) + +### Inputs + +#### Vehicle kinematic state + +Current position and orientation of ego. Published by the Localization module. + +- [nav_msgs/Odometry](https://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Odometry.html) + - [std_msgs/Header](https://docs.ros.org/en/noetic/api/std_msgs/html/msg/Header.html) header + - string child_frame_id + - [geometry_msgs/PoseWithCovariance](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/PoseWithCovariance.html) pose + - [geometry_msgs/TwistWithCovariance](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/TwistWithCovariance.html) twist + +#### Trajectory + +trajectory to be followed by the controller. See Outputs of Planning. + +#### Steering Status + +Current steering of the ego vehicle. Published by the Vehicle Interface. + +- Steering message ([github discussion](https://github.com/autowarefoundation/autoware/discussions/36)). + - builtin_interfaces::msg::Time stamp + - float32 steering_angle + +#### Actuation Status + +Actuation status of the ego vehicle for acceleration, steering, and brake. + +TODO This represents the reported physical efforts exerted by the vehicle actuators. Published by the Vehicle Interface. + +- ActuationStatus ([github discussion](https://github.com/autowarefoundation/autoware/discussions/36)). + - builtin_interfaces::msg::Time stamp + - float32 acceleration + - float32 steering + +### Output + +#### Vehicle Control Command + +A motion signal to drive the vehicle, achieved by the low-level controller in the vehicle layer. Used by the Vehicle Interface. + +- [autoware_auto_control_msgs/AckermannControlCommand]( + - builtin_interfaces::msg::Time stamp + - [autoware_auto_control_msgs/AckermannLateralCommand](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/AckermannLateralCommand.idl) lateral + - builtin_interfaces::msg::Time stamp + - float steering_tire_angle + - float steering_tire_rotation_rate + - [autoware_auto_control_msgs/LongitudinalCommand](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/LongitudinalCommand.idl) longitudinal + - builtin_interfaces::msg::Time stamp + - builtin_interfaces::msg::Duration duration + - builtin_interfaces::msg::Duration time_step + - float[] speeds + - float[] accelerations + - float[] jerks + +## Vehicle Interface + +![Node diagram](images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg) + +The `Vehicle Interface` receives the `Vehicle Signal Commands` and `Vehicle Control Commands` and publishes the vehicle status. It also communicates with vehicle by the vehicle-specific protocol. + +The `Gate` switches multiple `Vehicle Control Commands`. These signals include autonomous diving command, joystick, remote control, and emergency operation, etc. +The `Adapter` converts generalized control command (target steering, steering rate, velocity, acceleration, jerk) into vehicle-specific control values (steering-torque, wheel-torque, voltage, pressure, accel pedal position, etc). + +### Inputs + +#### Error status + +(See Inputs of Planning.) + +#### Vehicle Control Command + +(See Output of Control.) + +#### Vehicle Signals Commands + +Commands for various elements of the vehicle unrelated to motion. Published by the Planning module. + +### Outputs + +#### Vehicle Signal Reports + +Reports for various elements of the vehicle unrelated to motion. Published by the Vehicle Interface. + +#### Vehicle Odometry + +Odometry of the vehicle. Used by the Localization module to update the pose of the vehicle in the map. + +- [geometry_msgs/TwistWithCovarianceStamped](https://docs.ros.org/en/melodic/api/geometry_msgs/html/msg/TwistWithCovarianceStamped.html) odometry + +#### Steering Status + +Steering of the ego vehicle. Published by the Vehicle Interface. + +- Steering message ([github discussion](https://github.com/autowarefoundation/autoware/discussions/36)). + - builtin_interfaces::msg::Time stamp + - float32 steering_angle + +#### Actuation Status + +Actuation status of the ego vehicle for acceleration, steering, and brake. This represents the reported physical efforts exerted by the vehicle actuators. Published by the Vehicle Interface. + +- ActuationStatus ([github discussion](https://github.com/autowarefoundation/autoware/discussions/36)). + - builtin_interfaces::msg::Time stamp + - float32 acceleration + - float32 steering + - float32 brake + +**The message definition is under discussion.** + +#### Actuation Command + +Actuation command sent to the ego vehicle. This represents the requested physical efforts to be exerted by the vehicle actuators. Published by the Vehicle Interface as generated by the adapter. + +- ActuationCommand ([github discussion](https://github.com/autowarefoundation/autoware/discussions/36).) + - builtin_interfaces::msg::Time stamp + - float32 acceleration + - float32 steering + - float32 brake + +**The message definition is under discussion.** + +#### Vehicle Communication + +Vehicle specific messages protocol like CAN (Controller Area Network). diff --git a/docs/design/index.md b/docs/design/index.md index 77a9964e33e..6c9daba4b8d 100644 --- a/docs/design/index.md +++ b/docs/design/index.md @@ -4,6 +4,8 @@ Under Construction +## Autoware concepts + ## Autoware interfaces ## Configuration management diff --git a/docs/help/.pages b/docs/help/.pages index af1f2cda5c6..9a9ce05db53 100644 --- a/docs/help/.pages +++ b/docs/help/.pages @@ -1,4 +1,5 @@ nav: - index.md - support-guidelines.md + - troubleshooting.md - docs-guide.md diff --git a/docs/help/docs-guide.md b/docs/help/docs-guide.md index 6f7f3782d35..a67d21fc7e4 100644 --- a/docs/help/docs-guide.md +++ b/docs/help/docs-guide.md @@ -4,7 +4,7 @@ Under Construction -This page explains documentations sites that are useful for Autoware and ROS development. +This page explains several documentation sites that are useful for Autoware and ROS development. ## [The Autoware Foundation](https://www.autoware.org/) diff --git a/docs/help/support-guidelines.md b/docs/help/support-guidelines.md index 4ae6bfd7e0b..f877e8d1b34 100644 --- a/docs/help/support-guidelines.md +++ b/docs/help/support-guidelines.md @@ -1,5 +1,84 @@ # Support guidelines +This page explains the support mechanisms we provide. + !!! warning - Under Construction + Before asking for help, search and read this documentation site carefully. + Also, follow the [discussion guidelines](../contributing/discussion-guidelines/index.md) for discussions. + +Choose appropriate resources depending on what kind of help you need and read the detailed description in the sections below. + +- [Documentation sites](#documentation-sites) + - Various information +- [GitHub Discussions](#github-discussions) + - Questions + - Unconfirmed bugs + - Feature requests + - Design discussions +- [GitHub Issues](#github-issues) + - Confirmed bugs +- [Slack](#slack) + - Instant messaging between contributors +- [ROS Discourse](#ros-discourse) + - General topics that should be widely announced + +## Documentation sites + +[Docs guide](docs-guide.md) shows the list of useful documentation sites. +Visit them and see if there is any information related to your problem. + +Note that the documentation sites aren't always up-to-date and perfect. +If you find out that some information is wrong, unclear, or missing in Autoware docs, feel free to submit a pull request following our [contribution guidelines](../contributing/index.md). + +!!!warning + + Since this documentation site is still under construction, there are some empty pages. + +## GitHub Discussions + +If you encounter a problem with Autoware, check existing issues and questions and search for similar issues first. + +- [Issues](https://github.com/autowarefoundation/autoware/issues) + + Note that Autoware has multiple repositories listed in [autoware.repos](https://github.com/autowarefoundation/autoware/blob/main/autoware.repos). + It is recommended to search across the repositories. + +- [Questions](https://github.com/autowarefoundation/autoware/discussions/categories/q-a) + +If no answer was found, create a new question thread [here](https://github.com/autowarefoundation/autoware/discussions/categories/q-a). +If your question is not answered within a week, then @mention the maintainers to remind them. + +Also, there are other discussion types such as [feature requests](https://github.com/autowarefoundation/autoware/discussions/categories/feature-requests) or [design discussions](https://github.com/autowarefoundation/autoware/discussions/categories/design). +Feel free to open or join such discussions. + +## GitHub Issues + +If you have a problem and you have confirmed it is a bug, find the appropriate repository and create a new issue there. +If you can't determine the appropriate repository, ask the maintainers for help by creating a new discussion in the [Q&A category](https://github.com/autowarefoundation/autoware/discussions/categories/q-a). + +!!!warning + + Do not create issues for questions or unconfirmed bugs. If such issues are created, maintainers will transfer them to GitHub Discussions. + +If you want to fix the bug by yourself, discuss the approach with maintainers and submit a pull request. + +## Slack + +Autoware has a Slack workspace for casual communication between contributors. + +For example, this is a good place for the following activities: + +- Introduce yourself to the community. +- Chat with contributors. +- Take a quick straw poll. + +Note that it is not the right place to get help for your issues. + +## ROS Discourse + +If you want to widely discuss a topic with the general Autoware and ROS community or ask a question not related to Autoware's bugs, post to [the Autoware category on ROS Discourse](https://discourse.ros.org/c/autoware). + +!!!warning + + Do not post questions about bugs to ROS Discourse! diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md new file mode 100644 index 00000000000..9cf917b8213 --- /dev/null +++ b/docs/help/troubleshooting.md @@ -0,0 +1,94 @@ +# Troubleshooting + +## How to resolve errors of the setup script? + +### CUDA-related errors + +When installing CUDA, it may cause errors because of version conflicts. +To resolve this, try either: + +- Uninstall all CUDA-related libraries and rerun the setup script. + + ```bash + sudo apt purge \ + "cuda*" \ + "libcudnn*" \ + "libnvinfer*" \ + "libnvonnxparsers*" \ + "libnvparsers*" \ + "nvidia*" + + sudo apt autoremove + + ./setup-dev-env.sh + ``` + +!!! warning + + Note that this may break your system and run carefully. + +- Run the setup script without installing CUDA-related libraries. + + ```bash + ./setup-dev-env.sh --no-nvidia + ``` + +!!! warning + + Note that some components in `autoware.universe` don't work without CUDA. + + Also, although Autoware could work with different versions of CUDA libraries as well, + remember it is not officially supported and may sometimes be broken. + +## How to resolve build errors? + +When you get build errors, follow the instruction below depending on the version you use. + +### In case you use the latest version + +Note that the software may sometimes be broken if you follow the latest version. +Most issues are due to out-of-date software or old build files. + +To resolve the problem, try cleaning your build artifacts and rebuilding first: + +```bash +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 the workspace depending on your installation type: + +- [Docker](../../installation/autoware/docker-installation/#how-to-update-a-workspace) +- [Source](../../installation/autoware/source-installation/#how-to-update-a-workspace) + +!!! Warning + + Before removing `src/`, confirm that there are no necessary modifications left in your local environment. + +If the error still persists, delete the entire workspace and restart from cloning the repository. + +```bash +rm -rf autoware/ +git clone https://github.com/autowarefoundation/autoware.git +``` + +### In case you use a fixed version + +It is unusual that an error occurs when you use a fixed version. + +Possible causes are: + +- ROS 2 has been updated with breaking changes. + - Check out [Packaging and Release Management](https://discourse.ros.org/c/release/16) tag on ROS Discourse to confirm that. +- Your local environment is broken. + - Confirm your `.bashrc` file, environment variables, and library versions. + +Also, there are two common cases that you misunderstand you use a fixed version. + +1. You used a fixed version only for `autowarefoundation/autoware`. + If you specify a hash of `autowarefoundation/autoware`, it doesn't mean the version of the entire workspace is fixed. + You have to fix the versions in the `.repos` file to use a completely fixed version. + +2. You didn't update the workspace after you changed the branch of `autowarefoundation/autoware`. + If you change the branch of `autowarefoundation/autoware`, it doesn't affect the files under `src/`. + You have to run the `vcs import` command to update them. diff --git a/docs/how-to-guides/.pages b/docs/how-to-guides/.pages index 35fd5a113be..f909325ec3f 100644 --- a/docs/how-to-guides/.pages +++ b/docs/how-to-guides/.pages @@ -1,2 +1,3 @@ nav: - index.md + - advanced-usage-of-colcon.md diff --git a/docs/how-to-guides/advanced-usage-of-colcon.md b/docs/how-to-guides/advanced-usage-of-colcon.md new file mode 100644 index 00000000000..36eb58db696 --- /dev/null +++ b/docs/how-to-guides/advanced-usage-of-colcon.md @@ -0,0 +1,126 @@ +# Advanced usage of colcon + +This page shows some advanced and useful usage of `colcon`. +If you need more detailed information, refer to the [colcon documentation](https://colcon.readthedocs.io/). + +## Common mistakes + +### Do not run from other than the workspace root + +It is important that you always run `colcon build` from the workspace root because `colcon` builds only under the current directory. +If you have mistakenly built in a wrong directory, run `rm -rf build/ install/ log/` to clean the generated files. + +### Do not unnecessarily overlay workspaces + +`colcon` overlays workspaces if you have sourced the `setup.bash` of other workspaces before building a workspace. +You should take care of this especially when you have multiple workspaces. + +Run `echo $COLCON_PREFIX_PATH` to check whether workspaces are overlaid. +If you find some workspaces are unnecessarily overlaid, remove all built files, restart the terminal to clean environment variables, and re-build the workspace. + +For more details about `workspace overlaying`, refer to the [ROS2 documentation](https://docs.ros.org/en/rolling/Tutorials/Workspace/Creating-A-Workspace.html#source-the-overlay). + +## Cleaning up the build artifacts + +`colcon` sometimes causes errors of because of the old cache. +To remove the cache and rebuild the workspace, run the following command: + +```bash +rm -rf build/ install/ +``` + +In case you know what packages to remove: + +```bash +rm -rf {build,install}/{package_a,package_b} +``` + +## Selecting packages to build + +To just build specified packages: + +```bash +colcon build --packages-select ... +``` + +To build specified packages and their dependencies recursively: + +```bash +colcon build --packages-up-to ... +``` + +You can also use these options for `colcon test`. + +## Changing the optimization level + +Set `DCMAKE_BUILD_TYPE` to change the optimization level. + +!!! warning + + If you specify `DCMAKE_BUILD_TYPE=Debug` or no `DCMAKE_BUILD_TYPE` is given for building the entire Autoware, it may be too slow to use. + +```bash +colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug +``` + +```bash +colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo +``` + +```bash +colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release +``` + +## Changing the default configuration of colcon + +Create `$COLCON_HOME/defaults.yaml` to change the default configuration. + +```bash +mkdir -p ~/.colcon +cat << EOS > ~/.colcon/defaults.yaml +{ + "build": { + "symlink-install": true + } +} +``` + +See [here](https://colcon.readthedocs.io/en/released/user/configuration.html#defaults-yaml) for more details. + +## Generating compile_commands.json + +[compile_commands.json](https://colcon.readthedocs.io/en/released/user/how-to.html#cmake-packages-generating-compile-commands-json) is used by IDEs/tools to analyze the build dependencies and symbol relationships. + +You can generate it with the flag `DCMAKE_EXPORT_COMPILE_COMMANDS=1`: + +```bash +colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1 +``` + +## Seeing compiler commands + +To see the compiler and linker invocations for a package, use `VERBOSE=1` and `--event-handlers console_cohesion+`: + +```bash +VERBOSE=1 colcon build --packages-up-to --event-handlers console_cohesion+ +``` + +See [here](https://colcon.readthedocs.io/en/released/reference/event-handler-arguments.html) for other options. + +## Using Ccache + +[Ccache](https://ccache.dev/) can speed up recompilation. +It is recommended to use it to save your time unless you have a specific reason not to do so. + +1. Install `Ccache`: + + ```bash + sudo apt update && sudo apt install ccache + ``` + +2. Write the following in your `.bashrc`: + + ```bash + export CC="/usr/lib/ccache/gcc" + export CXX="/usr/lib/ccache/g++" + ``` diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 46ecf6764e2..2b7f34fc4b9 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -1,11 +1,11 @@ # How-to guides -!!! warning +- [Advanced usage of colcon](advanced-usage-of-colcon) - Under Construction +TODO: Write the following contents. -- Write an Autoware package -- Add a message +- Create an Autoware package +- Add a custom ROS message - Debug Autoware - Integrate Autoware with a real vehicle - etc. diff --git a/docs/installation/autoware/.pages b/docs/installation/autoware/.pages index e4ef1036208..3bda360633c 100644 --- a/docs/installation/autoware/.pages +++ b/docs/installation/autoware/.pages @@ -1,4 +1,4 @@ nav: - index.md - - local-installation.md - docker-installation.md + - source-installation.md diff --git a/docs/installation/autoware/docker-installation.md b/docs/installation/autoware/docker-installation.md index bb436018849..b3b23b469e8 100644 --- a/docs/installation/autoware/docker-installation.md +++ b/docs/installation/autoware/docker-installation.md @@ -1,5 +1,131 @@ # Docker installation -!!! warning +!!! info - Under Construction + Since this page explains Docker-specific information, it is recommended to see [Source installation](./source-installation.md) as well if you need detailed information. + +## Prerequisites + +- [Git](https://git-scm.com/) + +## How to set up a development environment + +1. Clone `autowarefoundation/autoware` and move to the directory. + + ```bash + git clone https://github.com/autowarefoundation/autoware.git + ``` + +2. Install the dependencies. + + ```bash + ./setup-dev-env.sh docker + ``` + +## How to set up a workspace + +1. Launch a Docker container + + ```bash + rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest + ``` + + See [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md) for more advanced usage. + + After that, move to the workspace in the container: + + ```bash + cd autoware + ``` + +2. Create the `src` directory and clone repositories into it. + + ```bash + mkdir src + vcs import src < autoware.repos + ``` + +3. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + +## How to update a workspace + +1. Update the Docker image. + + ```bash + docker pull ghcr.io/autowarefoundation/autoware-universe:latest + rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest + ``` + +2. Update the `.repos` file. + + ```bash + cd autoware + git pull + ``` + +3. Update the repositories. + + ```bash + vcs import src < autoware.repos + vcs pull + ``` + +4. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + +## Troubleshooting + +Here are solutions for a few specific errors: + +### cuda error: forward compatibility was attempted on non supported hw + +When starting Docker with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error: + +```bash +docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"process_linux.go:432: running prestart hook 0 caused \\\"error running hook: exit status 1, stdout: , stderr: nvidia-container-cli: initialization error: cuda error: forward compatibility was attempted on non supported hw\\\\n\\\"\"": unknown. +ERROR: Command return non-zero exit code (see above): 125 +``` + +This usually indicates that a new NVIDIA graphics driver has been installed (usually via `apt`) but the system has not yet been restarted. A similar message may appear if the graphics driver is not available, for example because of resuming after suspend. + +To fix this, restart your system after installing the new NVIDIA driver. + +## Tips + +### Non-native arm64 System + +This section describes a process to run `arm64` systems on `amd64` systems using [`qemu-user-static`](https://github.com/multiarch/qemu-user-static). + +Initially, your system is usually incompatible with `arm64` systems. +To check that: + +```sh-session +$ docker run --rm -t arm64v8/ubuntu uname -m +WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested +standard_init_linux.go:228: exec user process caused: exec format error +``` + +Installing `qemu-user-static` enables us to run `arm64` images on `amd64` systems. + +```sh-session +$ sudo apt-get install qemu-user-static +$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +$ docker run --rm -t arm64v8/ubuntu uname -m +WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested +aarch64 +``` + +To run Autoware's Docker images of `arm64` architecture, add the suffix `-arm64`. + +```sh-session +$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:latest-arm64 +WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested +root@5b71391ad50f:/autoware# +``` diff --git a/docs/installation/autoware/index.md b/docs/installation/autoware/index.md index 292dd772203..1e060f96713 100644 --- a/docs/installation/autoware/index.md +++ b/docs/installation/autoware/index.md @@ -1,5 +1,20 @@ # Installation of Autoware -!!! warning +There are two ways to set up Autoware. Choose one according to your preference. - Under Construction +## 1. Docker installation + +Docker can ensure that all developers in a project have a common, consistent development environment. +It is recommended for beginners, light users, people who do not use Ubuntu. + +See [here](docker-installation.md) for the detailed steps. +Refer to [autowarefoundation/autoware/docker/README.md](https://github.com/autowarefoundation/autoware/blob/main/docker/README.md) as well. + +## 2. Source installation + +Source installation is for the cases where more granular control of the installation environment is needed. +It is recommended for skilled users or people who want to customize the environment. +Note that some problems may occur depending on your local environment. + +See [here](source-installation.md) for the detailed steps. +Refer to the [autowarefoundation/autoware/README.md](https://github.com/autowarefoundation/autoware/blob/main/README.md) as well. diff --git a/docs/installation/autoware/source-installation.md b/docs/installation/autoware/source-installation.md new file mode 100644 index 00000000000..3b90fc77ba3 --- /dev/null +++ b/docs/installation/autoware/source-installation.md @@ -0,0 +1,109 @@ +# Source installation + +## Prerequisites + +- [Ubuntu 20.04](https://releases.ubuntu.com/20.04/) +- [Git](https://git-scm.com/) + - [Registering SSH keys to GitHub](https://github.com/settings/keys) is preferable. + +```bash +sudo apt-get -y update +sudo apt-get -y install git +``` + +## How to set up a development environment + +1. Clone `autowarefoundation/autoware` and move to the directory. + + ```bash + git clone https://github.com/autowarefoundation/autoware.git + cd autoware + ``` + +2. Install the dependencies. + + We use [Ansible](https://www.ansible.com/) to simplify the steps. + Please see the Ansible playbooks and roles if you want to know exactly what packages are installed. + + > Note: Before installing NVIDIA libraries, confirm and agree with the licenses. + + - [CUDA](https://docs.nvidia.com/cuda/eula/index.html) + - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/sla/index.html) + - [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/sla/index.html) + + ```bash + ./setup-dev-env.sh + ``` + +!!!warning + + Be very careful with this method. Make sure you read and confirmed all the steps in the ansible configuration before using it. + +## How to set up a workspace + +1. Create the `src` directory and clone repositories into it. + + Autoware uses [vcstool](https://github.com/dirk-thomas/vcstool) to construct workspaces. + + ```bash + cd autoware + mkdir src + vcs import src < autoware.repos + ``` + +2. Install dependent ROS packages. + + Autoware requires some ROS 2 packages in addition to the core components. + The tool `rosdep` allows an automatic search and installation of such dependencies. + + ```bash + source /opt/ros/galactic/setup.bash + rosdep install --from-paths src --ignore-src --rosdistro $ROS_DISTRO + ``` + +3. Build the workspace. + + Autoware uses [colcon](https://colcon.readthedocs.io/en/released/index.html) to build workspaces. + Refer to the documentation for more advanced options. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + +## How to update a workspace + +1. Update the `.repos` file. + + ```bash + cd autoware + git pull + ``` + +2. Update the repositories. + + ```bash + vcs import src < autoware.repos + vcs pull + ``` + + For Git users: + + - `vcs import` is similar to `git checkout`. + - Note that it doesn't pull from the remote. + - `vcs pull` is similar to `git pull`. + - Note that it doesn't switch branches. + + Refer to the [official documentation](https://github.com/dirk-thomas/vcstool) for more information. + +3. Install dependent ROS packages. + + ```bash + source /opt/ros/galactic/setup.bash + rosdep install --from-paths src --ignore-src --rosdistro $ROS_DISTRO + ``` + +4. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` diff --git a/docs/installation/index.md b/docs/installation/index.md index 2fc0dd37325..cef81300758 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -1,7 +1,36 @@ # Installation -!!! warning +## Target platforms - Under Construction +Autoware targets the platforms listed below. It may change in future versions of Autoware. -## Supported platforms +The Autoware Foundation provides no support on other platforms than those listed below. + +### Architecture + +- amd64 +- arm64 + +### ROS version + +- ROS 2 Galactic (**active development**) +- ROS 2 Humble (**will be supported in 2022**) + +Refer to [REP-2000](https://www.ros.org/reps/rep-2000.html) for the system dependencies. + +## Installation steps of Autoware + +See [here](autoware) for how to install Autoware. + +## Installation steps of tools for users + +Some other tools are required depending on the evaluation you want to do. +For example, if you run E2E simulation, you need to install a simulator for that. + +See [here](tools-for-users) for how to install the tools. + +## Installation steps of tools for developers + +There are also tools and settings for developers, such as Shells or IDEs. + +See [here](tools-for-developers) for how to install the tools. diff --git a/docs/installation/tools-for-developers/index.md b/docs/installation/tools-for-developers/index.md index 5f541ef509b..f2a9d09e5ad 100644 --- a/docs/installation/tools-for-developers/index.md +++ b/docs/installation/tools-for-developers/index.md @@ -1,5 +1,47 @@ # Installation of tools for developers -!!! warning +## ROS 2 settings - Under Construction +### Colorizing logger output + +By default, ROS 2 logger doesn't colorize the output. +To colorize it, write the following in your `.bashrc`: + +```bash +export RCUTILS_COLORIZED_OUTPUT=1 +``` + +### Customizing the format of logger output + +By default, ROS 2 logger doesn't output detailed information such as file name, function name, or line number. +To customize it, write the following in your `.bashrc`: + +```bash +export RCUTILS_CONSOLE_OUTPUT_FORMAT="[{severity} {time}] [{name}]: {message} ({function_name}() at {file_name}:{line_number})" +``` + +See [here](https://docs.ros.org/en/rolling/Tutorials/Logging-and-logger-configuration.html#console-output-formatting) for more options. + +### Enabling localhost-only communication + +By default, ROS 2 communicates using multi-cast, which may unnecessarily increase the network traffic. +To avoid it, write the following in your `.bashrc`: + +```bash +export ROS_LOCALHOST_ONLY=1 +``` + +### Setting up `ROS_DOMAIN_ID` + +ROS 2 uses `ROS_DOMAIN_ID` to create groups and communicate between machines in the groups. +Since all ROS 2 nodes use domain ID `0` by default, it may cause unintended interference. + +To avoid it, set a different domain ID for each group in your `.bashrc`: + +```bash +# Replace X with the Domain ID you want to use +# Domain ID should be a number in range [0, 101] (inclusive) +export ROS_DOMAIN_ID=X +``` + +See [here](https://docs.ros.org/en/foxy/Concepts/About-Domain-ID.html#the-ros-domain-id) for more information. 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 new file mode 100644 index 00000000000..b217ab49651 Binary files /dev/null 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/delete-objects.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/delete-objects.png new file mode 100644 index 00000000000..b9f773dd6e2 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/delete-objects.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/reach-goal.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/reach-goal.png new file mode 100644 index 00000000000..34aa57d1b7b Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/reach-goal.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/restart-driving.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/restart-driving.png new file mode 100644 index 00000000000..e50cac89190 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/restart-driving.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-dummy-pedestrian.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-dummy-pedestrian.png new file mode 100644 index 00000000000..4cf593b84ae Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/set-dummy-pedestrian.png 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 new file mode 100644 index 00000000000..cc75bd8470f Binary files /dev/null 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 new file mode 100644 index 00000000000..633a65884f9 Binary files /dev/null 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/start-driving.png b/docs/tutorials/ad-hoc-simulation/images/planning/lane-following/start-driving.png new file mode 100644 index 00000000000..fb5e4f7de03 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 new file mode 100644 index 00000000000..5cbbfe0c29b Binary files /dev/null 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/backward-driving.png b/docs/tutorials/ad-hoc-simulation/images/planning/parking/backward-driving.png new file mode 100644 index 00000000000..608e676bfe4 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/parking/backward-driving.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/parking/change-to-parking-mode.png b/docs/tutorials/ad-hoc-simulation/images/planning/parking/change-to-parking-mode.png new file mode 100644 index 00000000000..299e40b6d4b Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/parking/change-to-parking-mode.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/planning/parking/reach-goal.png b/docs/tutorials/ad-hoc-simulation/images/planning/parking/reach-goal.png new file mode 100644 index 00000000000..f303c526406 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/planning/parking/reach-goal.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/after-autoware-launch.png b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/after-autoware-launch.png new file mode 100644 index 00000000000..549d86a906f Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/after-autoware-launch.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/after-rosbag-play.png b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/after-rosbag-play.png new file mode 100644 index 00000000000..60c392f28c9 Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/after-rosbag-play.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/change-target-frame.png b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/change-target-frame.png new file mode 100644 index 00000000000..cd7d991a67c Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/change-target-frame.png differ diff --git a/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/third-person-follower.png b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/third-person-follower.png new file mode 100644 index 00000000000..5a03d5559fc Binary files /dev/null and b/docs/tutorials/ad-hoc-simulation/images/rosbag-replay/third-person-follower.png differ diff --git a/docs/tutorials/ad-hoc-simulation/planning-simulation.md b/docs/tutorials/ad-hoc-simulation/planning-simulation.md index 976af0d7d82..f247f8c992c 100644 --- a/docs/tutorials/ad-hoc-simulation/planning-simulation.md +++ b/docs/tutorials/ad-hoc-simulation/planning-simulation.md @@ -1,5 +1,81 @@ # Planning simulation -!!! warning +## Preparation - Under Construction +1. Download and unpack a sample map. + + - Click [here](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) to download. + - Unpack it by running the following command. + + ```bash + unzip -d ~/Downloads/ ~/Downloads/sample-map-planning.zip + ``` + +### Note + +- Sample map: Copyright 2020 TIER IV, Inc. + +## How to run a planning simulation + +1. Launch Autoware. + + ```sh + source ~/autoware/install/setup.bash + ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/Downloads/sample-map-planning vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit + ``` + + Note that you cannot use `~` instead of `$HOME` here. + + ![after-autoware-launch](images/planning/lane-following/after-autoware-launch.png) + +2. Set an initial pose for the ego vehicle. + + - a) Click the `2D Pose estimate` button in the toolbar, or hit the `P` key + - b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the initial pose. + + ![set-initial-pose](images/planning/lane-following/set-initial-pose.png) + +3. Set a goal pose for the ego vehicle. + + - a) Click the `2D Nav Goal` button in the toolbar, or hit the `G` key + - b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the goal pose. + + ![set-goal-pose](images/planning/lane-following/set-goal-pose.png) + +4. To place a dummy object such as a pedestrian, click the `2D Dummy Pedestrian` button in the toolbar. + + ![set-dummy-pedestrian](images/planning/lane-following/set-dummy-pedestrian.png) + +5. Engage the ego vehicle. + + ```bash + ros2 topic pub /autoware/engage autoware_auto_vehicle_msgs/msg/Engage "engage: true" -1 + ``` + + ![start-driving](images/planning/lane-following/start-driving.png) + +6. To delete objects, click the `Delete All Objects` button in the toolbar. + + ![delete-objects](images/planning/lane-following/delete-objects.png) + +7. After that, the vehicle will restart driving and reach the goal. + + ![restart-driving](images/planning/lane-following/restart-driving.png) + + ![reach-goal](images/planning/lane-following/reach-goal.png) + +## How to simulate parking maneuvers + +1. Set an initial pose and a goal pose, and engage the ego vehicle. + + ![after-set-goal-pose](images/planning/parking/after-set-goal-pose.png) + +2. When the vehicle approaches the goal, it will change to the parking mode. + + ![change-to-parking-mode](images/planning/parking/change-to-parking-mode.png) + +3. After that, the vehicle will start driving backwards and park at the destination parking spot. + + ![backward-driving](images/planning/parking/backward-driving.png) + + ![reach-goal](images/planning/parking/reach-goal.png) diff --git a/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md b/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md index 9fdf4319c16..531bb132c7f 100644 --- a/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md +++ b/docs/tutorials/ad-hoc-simulation/rosbag-replay-simulation.md @@ -1,5 +1,58 @@ # Rosbag replay simulation -!!! warning +## Steps - Under Construction +1. Download and unpack a sample map. + + - Click [here](https://drive.google.com/file/d/1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI/view?usp=sharing) to download. + - Unpack it by running the following command. + + ```bash + unzip -d ~/Downloads/ ~/Downloads/sample-map-rosbag.zip + ``` + +2. Download the sample rosbag files. + + - Click [here](https://drive.google.com/file/d/1VnwJx9tI3kI_cTLzP61ktuAJ1ChgygpG/view?usp=sharing) to download. + - Unpack it by running the following command. + + ```bash + unzip -d ~/Downloads/ ~/Downloads/sample-rosbag.zip + ``` + +### Note + +- Sample map and rosbag: Copyright 2020 TIER IV, Inc. +- Due to privacy concerns, the rosbag does not contain image data, which will cause: + - Traffic light recognition functionality cannot be tested with this sample rosbag. + - Object detection accuracy is decreased. + +## How to run a rosbag replay simulation + +1. Launch Autoware. + + ```sh + source ~/autoware/install/setup.bash + ros2 launch autoware_launch logging_simulator.launch.xml map_path:=$HOME/Downloads/sample-map-rosbag vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit + ``` + + Note that you cannot use `~` instead of `$HOME` here. + + ![after-autoware-launch](images/rosbag-replay/after-autoware-launch.png) + +2. Play the sample rosbag file. + + ```sh + source ~/autoware/install/setup.bash + ros2 bag play ~/Downloads/sample-rosbag/sample.db3 -r 0.2 + ``` + + ![after-rosbag-play](images/rosbag-replay/after-rosbag-play.png) + +3. To focus the view on the ego vehicle, change the `Target Frame` in the RViz Views panel from `viewer` to `base_link`. + + ![change-target-frame](images/rosbag-replay/change-target-frame.png) + +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) diff --git a/mkdocs.yaml b/mkdocs.yaml index b5b9baf80af..eaf2a8f00de 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -52,6 +52,7 @@ plugins: regex: - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?jpg).*$ - ^(.*/)?[^.]*$ + - macros - same-dir - search