Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(autoware_integration): integration guide improvements #469

Closed
wants to merge 12 commits into from
Closed

docs(autoware_integration): integration guide improvements #469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
bbec537
expand the meta-repository explanation
danielsanchezaran Oct 18, 2023
8396e78
add how to reference a custom package and import i to custom autoware…
danielsanchezaran Oct 18, 2023
6148d3d
add pre commit fixes
danielsanchezaran Oct 18, 2023
2d2d0de
capitalizing and making the style uniform
danielsanchezaran Oct 18, 2023
ab23dc6
Vehicle and sensor description creation guide overhaul
danielsanchezaran Oct 18, 2023
0f322f4
Vehicle and sensor description creation guide overhaul+ precommit
danielsanchezaran Oct 18, 2023
8ba0ae7
Take out name
danielsanchezaran Oct 18, 2023
7434980
Improve docs on creating a meta repo
danielsanchezaran Oct 18, 2023
3058519
refactoring
danielsanchezaran Oct 18, 2023
dd12f56
pre-commit changes
danielsanchezaran Oct 18, 2023
71e99ee
pre-commit changes
danielsanchezaran Oct 18, 2023
6ab5f90
pre-commit changes
danielsanchezaran Oct 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 86 additions & 13 deletions ...ating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,90 @@

## Introduction

This page introduce following topics.
This page introduces the custom packages that you should include in your autoware project to integrate autoware to your vehicle:

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
## Repository and package structure based on Autoware's sample packages

In `YOUR_VEHICLE_description`, the following configurations are set:
This guide assumes you will fork Autoware's sample repositories and packages to use as templates for your custom implementation. You can fork Autoware's sample packages:([sample_sensor_kit_launch](https://github.com/autowarefoundation/sample_sensor_kit_launch.git) , [sample_vehicle_launch](https://github.com/autowarefoundation/sample_vehicle_launch.git), and [autoware_individual_params](https://github.com/autowarefoundation/autoware_individual_params.git)), and rename their folders and files according to your vehicle name/denomination. If you do so, you should have folder structures like these:

```bash
YOUR_VEHICLE_launch (Custom Repository)
├── YOUR_VEHICLE_description (Package)
│ ├── CMakeLists.txt
│ ├── config
│ │ ├── mirror.param.yaml (must be changed)
│ │ ├── simulator_model.param.yaml
│ │ └── vehicle_info.param.yaml (must be changed)
│ ├── mesh
│ │ └── YOUR_VEHICLE_MESH.dae (if you have a .dae mesh, otherwise, use the provided one)
│ ├── package.xml
│ └── urdf
│ └── vehicle.xacro
├── YOUR_VEHICLE_launch (Package)
│ ├── CMakeLists.txt
│ ├── launch
│ │ └── vehicle_interface.launch.xml (must be changed)
│ └── package.xml
└── ...

YOUR_SENSOR_KIT_launch (Custom Repository)
├── common_sensor_launch
│ ├── ...
├── YOUR_SENSOR_KIT_description (Package)
│ ├── CMakeLists.txt
│ ├── config
│ │ ├── sensor_kit_calibration.yaml (NOT USED BY AUTOWARE)
│ │ └── sensors_calibration.yaml (NOT USED BY AUTOWARE)
│ ├── package.xml
│ └── urdf
│ ├── sensor_kit.xacro (must be changed)
│ └── sensors.xacro (must be changed)
├── YOUR_SENSOR_KIT_launch (Package)
│ ├── CMakeLists.txt
│ ├── config
│ │ ├── ...
│ │
│ ├── data
│ │ └── ...
│ ├── launch
│ │ ├── camera.launch.xml
│ │ ├── gnss.launch.xml
│ │ ├── imu.launch.xml (must be changed)
│ │ ├── lidar.launch.xml (must be changed)
│ │ ├── pointcloud_preprocessor.launch.py (must be changed)
│ │ └── sensing.launch.xml (must be changed)
│ └── package.xml
├── README.md
└── ...

YOUR_AUTOWARE_INDIVIDUAL_PARAMS (Custom Repository)
├── individual_params (Package)
│ ├── config
│ │ └── default
│ │ ├── awsim_sensor_kit
│ │ │ ├── sensor_kit_calibration.yaml
│ │ │ └── sensors_calibration.yaml
│ │ └── YOUR_SENSOR_KIT
│ │ ├── imu_corrector.param.yaml
│ │ ├── sensor_kit_calibration.yaml (must be changed)
│ │ └── sensors_calibration.yaml (must be changed)
│ └── ...
└── ...
```

Please note that the YOUR_VEHICLE_launch repository contains two ROS packages that need to be modified: YOUR_VEHICLE_description, and YOUR_VEHICLE_launch (same name as he repository itself). Likewise, YOUR_SENSOR_KIT_launch also contains two ROS packages that require customization: YOUR_SENSOR_KIT_description and YOUR_SENSOR_KIT_launch (same name as the repo). Finally, YOUR_AUTOWARE_INDIVIDUAL_PARAMS contains information about your sensor implementation.

Also,the YOUR_AUTOWARE_INDIVIDUAL_PARAMS package contains the information about your sensor kit and calibration (sensor_kit_calibration.yaml and sensors_calibration.yaml) Autoware will NOT use the parameters contained in YOUR_SENSOR_KIT_launch/YOUR_SENSOR_KIT_description/config. Please, do not confuse them.

## 1. YOUR_VEHICLE_launch/YOUR_VEHICLE_description

In the `YOUR_VEHICLE_description` package, the following configurations are set:

1. vehicle_info.param.yaml (must be changed)
2. mesh file (\*.dae)
Expand Down Expand Up @@ -40,16 +113,16 @@ Configuration file for the [simulator environment](https://autowarefoundation.gi

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
## 2. YOUR_SENSOR_KIT_launch/YOUR_SENSOR_KIT_description

In sensor_kit_description, the following files are configured:
In the `YOUR_SENSOR_KIT_description` package, 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.
Resolves the positions of sensors with `base_link` as the parent frame and defines the positions and orientations based on `sensors_calibration.yaml` in `YOUR_AUTOWARE_INDIVIDUAL_PARAMS`.

> In Autoware, `<YOUR_SENSOR_KIT_description>/config/sensors_calibration.yaml` is not used.

Expand All @@ -60,13 +133,13 @@ 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.
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 `YOUR_AUTOWARE_INDIVIDUAL_PARAMS`.

> In Autoware, `<YOUR_SENSOR_KIT_description>/config/sensor_kit_calibration.yaml` is not used.

## 3. individual_parameter
## 3. YOUR_AUTOWARE_INDIVIDUAL_PARAMS/individual_params

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.
The `individual_params` package is where parameters referenced by `sensors.xacro` and `sensor_kit.xacro` are stored. As the name implies, it is intended to manage parameters for multiple individual instances.

### Introduction to Various Parameters

Expand Down Expand Up @@ -149,9 +222,9 @@ individual_params/
+ └─ sensors_calibration.yaml
```

## 4.YOUR_VEHICLE_launch
## 4.YOUR_VEHICLE_launch/YOUR_VEHICLE_launch

`YOUR_VEHICLE_launch` is where the launch file for starting the drive system devices is stored.
The `YOUR_VEHICLE_launch` package is where the launch file for starting the drive system devices is stored.

1. vehicle_interface.launch.xml (must be changed)

Expand All @@ -161,9 +234,9 @@ individual_params/

If you are operating multiple vehicles, use the `vehicle_id` to switch to the corresponding configuration for each vehicle.

## 5. YOUR_SENSOR_KIT_launch
## 5. YOUR_SENSOR_KIT_launch/YOUR_SENSOR_KIT_launch

`YOUR_SENSOR_KIT_launch` is where the launch files related to sensor startup are stored.
The `YOUR_SENSOR_KIT_launch` package 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)
Expand Down
60 changes: 36 additions & 24 deletions ...are/creating-your-autoware-meta-repository/creating-autoware-meta-repository.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,44 @@
# Creating Autoware meta-repository
# Creating an Autoware Meta-Repository

## What is Meta-repository?
## What is a 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.
A meta-repository is a repository that contains references or information about other repositories. It serves as a central point of reference or coordination for multiple repositories.

By using Ansible and VCS, you can automatically set up your Autoware.
`autoware.repos` file manages the configuration of multiple repositories.
[Autoware](https://github.com/autowarefoundation/autoware) is a meta-repository. It contains references to several other repositories that provide source code used to realize autonomous driving.

Note: VCS stands for Version Control System, such as Git or Subversion.
## How to Create and Customize Your Autoware Meta-Repository

## How to create and customize your autoware meta-repository
### 1. Why Make Your Own Autoware-Meta-Repository?

### 1. Create autoware repository
Most of the packages within the Autoware meta-repository are designed to be vehicle-agnostic, meaning they are not tied to any specific vehicle type.

If you want to integrate Autoware into your vehicle, the first step is to create an Autoware meta-repository.
However, when integrating Autoware with your vehicle, it becomes necessary to create vehicle-specific packages tailored to your specific vehicle's implementation. Once you've developed these vehicle-specific packages, you can incorporate references to them within your Autoware meta-repository. This allows you to combine and utilize Autoware's vehicle-agnostic packages with your custom, vehicle-specific packages.

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).
### 2. Create Your Autoware Repository

To create your own Autoware meta-repository, you can start by forking the [autowarefoundation/autoware](https://github.com/autowarefoundation/autoware) repository. For guidance on forking a repository, you can 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
Note: 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
Then, you can create forks of different Autoware repositories that you might need to customize. Some of the repositories you might need to customize include the `vehicle_description`, the `sensor_kit_description`, `individual_params` and the `vehicle-interface` packages. Said repositories contain packages with information and parameters about your vehicle dimensions and sensor configuration.

You need to customize `autoware.repos` for your own vehicle's Autoware.
### 3. Create Your Custom Vehicle Repositories and Packages

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.
[Autoware](https://github.com/autowarefoundation/autoware) references sample repositories with sample packages that you may use as templates (e.g., sample_vehicle_description, sample_sensor_kit, and individual_parameters packages). However, you may also need to create a package and repository from scratch to define an Autoware-vehicle interface. For more information, please take a look at the following guides:

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.
- [creating-vehicle-and-sensor-description packages](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/)

### 4. Referencing a Custom Repository on Your Autoware Meta-Repository

If you want to fork `autoware_individual_params` and make modifications, it would be as follows:
Once you create a custom package that needs to be referenced by your autoware meta-repository, it should be referenced in your `autoware.repos` file.

Example: If you fork `individual_params` and rename `autoware_individual_params.vehicle_A`:
As an Example: If you fork `individual_params` and rename it to `autoware_individual_params.vehicle_A` you would make the following changes to your `autoware.repos` file on your autoware meta-repository fork:

```diff
- param/autoware_individual_params:
Expand All @@ -48,10 +51,19 @@ Example: If you fork `individual_params` and rename `autoware_individual_params.
+ version: main
```

Please refer to the following documentation link for instructions on how to create and customize each `vehicle_interface`:
### 5. Setting up your workspace

- [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/)
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.

Once you have forked or created your custom Autoware repositories and added their references to `autoware.repos`, you can import them to your autoware project src folder in a similar manner to that of the [Autoware source installation guide](https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/#how-to-set-up-a-workspace) by executing the following commands:

```bash
cd autoware.your_vehicle_name
mkdir src
vcs import src < autoware.repos
```

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.
After importing your custom repos into your project's `src/` folder, you can build and test your autoware implementation as explained by the [Autoware source installation guide](https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/#how-to-set-up-a-workspace).