Skip to content

Commit

Permalink
docs(how-to-guides): fill the documentation of creating vehicle inter…
Browse files Browse the repository at this point in the history 
…face for ackerman kinematic model (autowarefoundation#404)

* feat: invalid lanelet documentation (autowarefoundation#337)

* feat: invalid lanelet documentation

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>

* feat: changing module name from invalid_lanelet to no_drivable_lane

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>

* feat(no_drivable_lane): updating the node diagram file will smaller one in size

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>

* feat(no_drivable_lane): reverting back to large size image

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>

* feat(no_drivable_lane): fix review comments / add missing parts regarding no_drivable_lane module documentation

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>

* feat(no_drivable_lane): updating no_drivable_lane doc link

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>

* feat(no_drivable_lane): fixing review comment / update missing no_drivable_lane link

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>

---------

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Start to get writing about vehicle interfaces.

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Finished the implementation part

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* First draft done

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Fixed ackerman to Ackermann, and changed the path of images.

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Fixed the html description of figures in md_in_html style

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Changed ROS2 to ROS 2. Added description about autoware.repos

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Minor revision

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* style(pre-commit): autofix

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* style(pre-commit): autofix

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Fixed typo and indents

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* style(pre-commit): autofix

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Removed redundant new lines

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Revert

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Changed url for source installation explanation

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* docs(ad-api): add use cases of vehicle status (autowarefoundation#381)

* init vehicle status

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix spelling error

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* remove old file

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix spelling error

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix dead link

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* update vehicle message

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* change vehicle motion

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* feat(ad-api): add vehicle information api

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* fix msgs

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* update geo position

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix typo

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* change naming

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* feat: add door group

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update message

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix naming

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* fix typo

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* update geographic_msgs

Signed-off-by: tkhmy <tkh.my.p@gmail.com>

* docs(ad-api): add use cases of vehicle status

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* feat: remove old files

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* feat: use template

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* apply template

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update message name

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update vehicle status feature

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* fix link

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update door layout

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

---------

Signed-off-by: tkhmy <tkh.my.p@gmail.com>
Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>
Co-authored-by: tkhmy <tkh.my.p@gmail.com>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* chore: add mkdocs template for sync files from other repository (autowarefoundation#395)

chore: add mkdocs template for sync files from other directory

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* ci(sync-files): fix source path (autowarefoundation#398)

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* docs(how-to-guides): add creating vehicle and sensor description. (autowarefoundation#399)

* docs(how-to-guides): Creating vehicle and sensor description.
Fixes autowarefoundation#396

Signed-off-by: Naophis <naoto.hiramatsu@tier4.jp>

* style(pre-commit): autofix

Signed-off-by: Naophis <naoto.hiramatsu@tier4.jp>

* fix: typo

Signed-off-by: Naophis <naoto.hiramatsu@tier4.jp>

* fix: typo

Signed-off-by: Naophis <naoto.hiramatsu@tier4.jp>

---------

Signed-off-by: Naophis <naoto.hiramatsu@tier4.jp>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* docs(coding-guidelines): add note for test file with private headers (autowarefoundation#402)

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* merged upstream/main

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Adjust md file to markdown lint

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* style(pre-commit): autofix

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Adjust style again

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* feat: change the adapi page structure (autowarefoundation#406)

* move user stories

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* move features

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* add list page

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update message

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

* update menu

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>

---------

Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* style(pre-commit): autofix

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* style: fix pre-commit errors

Signed-off-by: Kenji Miyake <kenji.miyake@tier4.jp>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* fix indent

Signed-off-by: Kenji Miyake <kenji.miyake@tier4.jp>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Changed list to subsubsections

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* feat(how-to-guides): add important temporal performance metrics (autowarefoundation#389)

* feat(how-to-guides): add new pages for important temporal performance metrics.

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fix: removed unnecessary sub component names.

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed section for top-level temporal performance metrics

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed note

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* fixed table for Perception

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fix table of Perception

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed table of Perception

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed table of Perception

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed not saved

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed table of obstacle segmentation

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* removed or

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* replaced LiDAR by sensor

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* add some minor fix

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* add high-level component name

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* style(pre-commit): autofix

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/important-temporal-performance-metrics.md

Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>

* fixed reason expression.

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed model for perception

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* replace the by a

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* fixed the sentence

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* replace image by correct one

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* fixed missing link

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* chore: mv the pages to how-to-guides/others

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* chore: add page item to the list

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* chore: add the reason why temporal performance is used.

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* chore: add guide to performance evaluation tools

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* add explanation of definition policy

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* fix: completed writing policies

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

* style(pre-commit): autofix

* chore: fixed missing link.

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>

---------

Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>
Co-authored-by: Ryohsuke Mitsudome <43976834+mitsudome-r@users.noreply.github.com>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Update docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/.pages

Get rid of redundancy

Co-authored-by: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Apply three suggestions from code review

Co-authored-by: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Fixed typos.
Added proper articles to the title.
Fixed inconsistancy for the term vehicle interface.
Break paragraphs into lines.
Changed the term hardware (ECU) to control device.

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

* Fixed typo

Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>

---------

Signed-off-by: AhmedEbrahim <ahmed.a.d.ebrahim@gmail.com>
Signed-off-by: TaikiYamada4 <taiki.yamada@tier4.jp>
Signed-off-by: tkhmy <tkh.my.p@gmail.com>
Signed-off-by: Takagi, Isamu <isamu.takagi@tier4.jp>
Signed-off-by: Naophis <naoto.hiramatsu@tier4.jp>
Signed-off-by: Kenji Miyake <kenji.miyake@tier4.jp>
Signed-off-by: Takayuki AKAMINE <takayuki.akamine@tier4.jp>
Co-authored-by: Ahmed Ebrahim <36835765+ahmeddesokyebrahim@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Takagi, Isamu <43976882+isamu-takagi@users.noreply.github.com>
Co-authored-by: tkhmy <tkh.my.p@gmail.com>
Co-authored-by: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com>
Co-authored-by: Naophis <naoto.hiramatsu@tier4.jp>
Co-authored-by: Kenji Miyake <kenji.miyake@tier4.jp>
Co-authored-by: Takayuki AKAMINE <38586589+takam5f2@users.noreply.github.com>
Co-authored-by: takeshi-iwanari <takeshi.iwanari@tier4.jp>
Co-authored-by: Ryohsuke Mitsudome <43976834+mitsudome-r@users.noreply.github.com>
Signed-off-by: Tier4Guan <muhua.guan@tier4.jp>
  • Loading branch information
@TaikiYamada4 @ahmeddesokyebrahim
@pre-commit-ci @isamu-takagi @tkhmy @kenji-miyake @Naophis @takam5f2 @takeshi-iwanari @mitsudome-r @Tier4Guan
11 people authored and Tier4Guan committed Jul 4, 2023
1 parent 00134f8 commit be1f4c5
Show file tree
Hide file tree
Showing 5 changed files with 251 additions and 5 deletions.
3 changes: 3 additions & 0 deletions docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/.pages
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
nav:
- Creating a vehicle interface for an Ackermann kinematic model: creating-a-vehicle-interface-for-an-ackermann-kinematic-model.md
- customizing-for-differential-drive-model.md
244 changes: 244 additions & 0 deletions ...erface-package/creating-a-vehicle-interface-for-an-ackermann-kinematic-model.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,244 @@
# Creating a vehicle interface for an Ackermann kinematic model

This page introduces a module vehicle interface and explains how to implement it.

## What is a vehicle interface

Vehicle interface is an interface that connects the control commands and your vehicle's control device.
Autoware publishes control commands such as:

- Velocity control
- Steering control
- Car light commands

Then, the vehicle interface converts these commands into actuation such like:

- Motor and brake activation
- Steering wheel operation
- Lighting control

So think of the vehicle interface as a module that runs the vehicle's control device to realize the input commands provided by Autoware.

<figure markdown>
![vehicle_interface_IO](images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg){ align=center }
<figcaption>
An example of inputs and outputs for vehicle interface
</figcaption>
</figure>

This page shows you a brief explanation how to implement your vehicle interface, but [you can see further information of vehicle interface in the "design" page](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-interface/).

**Note that there is no package named "vehicle interface" prepared in Autoware.**
**It is a necessary package to actuate your vehicle, but you have to create one by yourself since it is very specific to your vehicle's control device.**

For example, if you are using a by-wire kit [PACMod](https://autonomoustuff.com/platform/pacmod), a vehicle interface named [`pacmod_interface` published by TIER IV, Inc.](https://github.com/tier4/pacmod_interface/tree/main) is available.
However, if you have constructed something original and haven't found an open source vehicle interface applicable, you have to implement your own vehicle interface from scratch.

---

## How to implement a vehicle interface

The following instructions describe how to create a vehicle interface.

### 1. Create a directory for vehicle interface

It is recommended to create your vehicle interface at `<your-autoware-dir>/src/vehicle/external`

```bash
cd <your-autoware-dir>/src/vehicle/external
```

### 2. Install or implement your own vehicle interface

If there is an already complete vehicle interface package (like [`pacmod_interface`](https://github.com/tier4/pacmod_interface/tree/main)), you can install it to your environment.
If not, you have to implement your own vehicle interface by yourself.
Let's create a new package by `ros2 pkg create`.
The following example will show you how to create a vehicle interface package named `my_vehicle_interface`.

```bash
ros2 pkg create --build-type ament_cmake my_vehicle_interface
```

Then, you should write your implementation of vehicle interface in `my_vehicle_interface/src`.
Again, since this implementation is so specific to the control device of your vehicle, it is beyond the scope of this document to describe how to implement your vehicle interface in detail.
Here are some factors that might be considered.

- Subscription of control command topics from Autoware
- Communication between the vehicle interface and your vehicle's control device
- Modification of control values if needed

### 3. Prepare a launch file

After you implement your vehicle interface or you want to debug it by launching it, create a launch file of your vehicle interface, and include it to `vehicle_interface.launch.xml`.

Do not get confused. First, you need to create a launch file for your own vehicle interface module (like `my_vehicle_interface.launch.xml`) **and then include that to `vehicle_interface.launch.xml` which exists in another directory.** Here are the details.

1. Add a `launch` directory in the `my_vehicle_interface` directory, and create a launch file of your own vehicle interface in it. Take a look at [Creating a launch file](https://docs.ros.org/en/humble/Tutorials/Intermediate/Launch/Launch-Main.html) in the ROS 2 documentation.

2. Next, go to `<your-autoware-dir>/src/vehicle`, copy the directory `/sample_vehicle_launch/`, and paste it to the same place (which means it should be lined up with `external` and `sample_vehicle_launch`).

3. You have to rename each "sample_vehicle" to something else. For example, if you want to rename "sample_vehicle" to "my_vehicle_name", you need to change the following. Note that it is restricted to keep the "\_launch" and "\_description" part.

- **Rename the directories**
- `sample_vehicle_launch` &rarr; `my_vehicle_name_launch`
- `my_vehicle_name_launch/sample_vehicle_launch` &rarr; `my_vehicle_name_launch/my_vehicle_name_launch`
- `my_vehicle_name_launch/sample_vehicle_description` &rarr; `my_vehicle_name_launch/my_vehicle_name_description`
- **After you rename your directories, rename each "sample_vehicle" to "my_vehicle_name" in the source code.**
- `my_vehicle_name_description/CMakeLists.txt`
- `my_vehicle_name_description/package.xml`
- `my_vehicle_name_description/urdf/vehicle.xacro` (there are two parts)
- `my_vehicle_name_launch/CMakeLists.txt`
- `my_vehicle_name_launch/package.xml`
- `README.md`

4. Include your launch file to `my_vehicle_name_launch/my_vehicle_name_launch/launch/vehicle_interface.launch.xml` by opening it and add the include terms like below.

```xml title="vehicle_interface.launch.xml"
<?xml version="1.0" encoding="UTF-8"?>
<launch>
<arg name="vehicle_id" default="$(env VEHICLE_ID default)"/>

<include file="$(find-pkg-share my_vehicle_interface)/launch/my_vehicle_interface.launch.xml">
</include>
</launch>
```

Finally, your directory structure may look like below.
Most of the files are omitted for clarity, but the files shown here needs modification as said in the previous and current process.

```diff
<your-autoware-dir>/
└─ src/
└─ vehicle/
├─ external/
+ │ └─ my_vehicle_interface/
+ │ ├─ src/
+ │ └─ launch/
+ │ └─ my_vehicle_interface.launch.xml
├─ sample_vehicle_launch/
+ └─ my_vehicle_name_launch/ (COPIED FROM sample_vehicle_launch)
+ ├─ my_vehicle_name_launch/
+ │ ├─ launch/
+ │ │ └─ vehicle_interface.launch.xml
+ │ ├─ CMakeLists.txt
+ │ └─ package.xml
+ ├─ my_vehicle_name_description/
+ │ ├─ config/
+ │ ├─ mesh/
+ │ ├─ urdf/
+ │ │ └─ vehicle.xacro
+ │ ├─ CMakeLists.txt
+ │ └─ package.xml
+ └─ README.md
```

### 4. Build the vehicle interface package and the launch package

Build three packages `my_vehicle_interface`, `my_vehicle_name_launch` and `my_vehicle_name_description` by `colcon build`, or you can just build the entire Autoware if you have done other things.

```bash
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-select my_vehicle_interface my_vehicle_name_launch my_vehicle_name_description
```

### 5. When you launch Autoware

Finally, you are done implementing your vehicle interface module! Be careful that you need to launch Autoware with the proper `vehicle_model` option like the example below. This example is launching planning simulator.

```bash
ros2 launch autoware_launch planning.launch.xml map_path:=$HOME/autoware_map/sample-map-planning vehicle_model:=my_vehicle_name sensor_model:=sample_sensor_kit
```

### Tips

There are some tips that may help you.

- You can subdivide your vehicle interface into smaller packages if you want. Then your directory structure may look like below (not the only way though). Do not forget to launch all packages in `my_vehicle_interface.launch.xml`.

```diff
<your-autoware-dir>/
└─ src/
└─ vehicle/
├─ external/
│ └─ my_vehicle_interface/
│ ├─ src/
│ │ ├─ package1/
│ │ ├─ package2/
│ │ └─ package3/
│ └─ launch/
│ └─ my_vehicle_interface.launch.xml
├─ sample_vehicle_launch/
└─ my_vehicle_name_launch/
```

- If you are using a vehicle interface and launch package from a open git repository, or created your own as a git repository, it is highly recommended to add those repositories to your `autoware.repos` file which is located to directly under your autoware folder like the example below. You can specify the branch or commit hash by the version tag.

```yaml title="autoware.repos"
# vehicle (this section should be somewhere in autoware.repos and add the below)
vehicle/my_vehicle_name_launch:
type: git
url: https://github.com/<repository-name-A>/my_vehicle_name_launch.git
version: main
vehicle/external/my_vehicle_interface:
type: git
url: https://github.com/<repository-name-B>/my_vehicle_interface.git
version: main
```
Then you can import your entire environment easily to another local device by using the `vcs import` command. (See [the source installation guide](https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/#how-to-set-up-a-workspace))

---

## Ackermann kinematic model

Autoware now supports control inputs for vehicles based on an Ackermann kinematic model.
This section introduces you a brief concept of Ackermann kinematic model and explains how Autoware controls it.

- If your vehicle does not suit the Ackermann kinematic model, you have to modified the control commands. [Another document gives you an example how to convert your Ackermann kinematic model control inputs into a differential drive model.](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/)

### Geometry

The basic style of Ackermann kinematic model has four wheels with an Ackermann link on the front, and it is powered by the rear wheels.
The key point of Ackermann kinematic model is that the axes of all wheels intersect at a same point, which means all wheels will trace a circular trajectory with a different radii but a common center point (See the figure below).
Therefore, this model has a great advantage that it minimizes the slippage of the wheels, and prevent tires to get worn soon.

In general, Ackermann kinematic model accepts the longitudinal speed $v$ and the steering angle $\phi$ as inputs.
In autoware, $\phi$ is positive if it is steered counter clockwise, so the steering angle in the figure below is actually negative.

<figure markdown>
![ackermann_link](images/Ackermann_WB.png){ align=center }
<figcaption>
The basic style of an Ackermann kinematic model. The left figure shows a vehicle facing straight forward, while the right figure shows a vehicle steering to the right.
</figcaption>
</figure>

### Control

Autoware publishes a ROS 2 topic named `control_cmd` from several types of publishers.
A `control_cmd` topic is a [`AckermannControlCommand`](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/AckermannControlCommand.idl) type message that contains

```bash title="AckermannControlCommand"
builtin_interfaces/Time stamp
autoware_auto_control_msgs/AckermannLateralCommand lateral
autoware_auto_control_msgs/LongitudinalCommand longitudinal
```

where,

```bash title="AckermannLateralCommand"
builtin_interfaces/Time stamp
float32 steering_tire_angle
float32 steering_tire_rotation_rate
```

```bash title="LongitudinalCommand"
builtin_interfaces/Time stamp
float32 speed
float32 accelaration
float32 jerk
```

See the [AckermannLateralCommand.idl](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/AckermannLateralCommand.idl) and [LongitudinalCommand.idl](https://gitlab.com/autowarefoundation/autoware.auto/autoware_auto_msgs/-/blob/master/autoware_auto_control_msgs/msg/LongitudinalCommand.idl) for details.

The vehicle interface should realize these control commands through your vehicle's control device.

Moreover, Autoware also provides brake commands, light commands, and more (see [vehicle interface design](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-interface/)), so the vehicle interface module should be applicable to these commands as long as there are devices available to handle them.
5 changes: 0 additions & 5 deletions ...le-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model.md
View file

This file was deleted.

Binary file added ...integrating-autoware/creating-vehicle-interface-package/images/Ackermann_WB.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions ...icle-interface-package/images/Vehicle-Interface-Bus-ODD-Architecture.drawio.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit be1f4c5

Please sign in to comment.