-
Notifications
You must be signed in to change notification settings - Fork 140
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(launch-autoware): add how to launch yabloc or eagleye (#411)
* add yabloc page but it's empty Signed-off-by: Kento Yabuuchi <[email protected]> * update yabloc-integration-guide Signed-off-by: Kento Yabuuchi <[email protected]> * style(pre-commit): autofix * add what is YabLoc Signed-off-by: Kento Yabuuchi <[email protected]> * moved yabloc and eagleye docs under launch-autoware Signed-off-by: Kento Yabuuchi <[email protected]> * WIP add some descriptions in Japanese Signed-off-by: Kento Yabuuchi <[email protected]> * WIP update Signed-off-by: Kento Yabuuchi <[email protected]> * modified structure Signed-off-by: Kento Yabuuchi <[email protected]> * translate in english Signed-off-by: Kento Yabuuchi <[email protected]> * applied pre-commit Signed-off-by: Kento Yabuuchi <[email protected]> * fix typo Signed-off-by: Kento Yabuuchi <[email protected]> * fix typo again Signed-off-by: Kento Yabuuchi <[email protected]> * reflected reviews Signed-off-by: Kento Yabuuchi <[email protected]> * removed yabloc sub-page Signed-off-by: Kento Yabuuchi <[email protected]> * add comprehensive table Signed-off-by: Kento Yabuuchi <[email protected]> * use markdown rather than html Signed-off-by: Kento Yabuuchi <[email protected]> * i dont know why the table does not appear Signed-off-by: Kento Yabuuchi <[email protected]> * update table Signed-off-by: Kento Yabuuchi <[email protected]> * today's CI is annoying Signed-off-by: Kento Yabuuchi <[email protected]> * split table Signed-off-by: Kento Yabuuchi <[email protected]> --------- Signed-off-by: Kento Yabuuchi <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
- Loading branch information
1 parent
1c3f536
commit acda2fe
Showing
17 changed files
with
377 additions
and
135 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
4 changes: 4 additions & 0 deletions
4
docs/how-to-guides/integrating-autoware/launch-autoware/.pages
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
nav: | ||
- index.md | ||
- Localization mode: localization-mode | ||
- Perception mode: perception.md |
Binary file added
BIN
+15.4 KB
docs/how-to-guides/integrating-autoware/launch-autoware/images/2d_goal_pose.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+15.5 KB
.../how-to-guides/integrating-autoware/launch-autoware/images/2d_pose_estimate.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+41 KB
...ides/integrating-autoware/launch-autoware/images/autoware_state_panel_after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+40.2 KB
...des/integrating-autoware/launch-autoware/images/autoware_state_panel_before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+456 KB
...ides/integrating-autoware/launch-autoware/images/route_planning_is_complete.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
87 changes: 87 additions & 0 deletions
87
docs/how-to-guides/integrating-autoware/launch-autoware/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,87 @@ | ||
# Launch Autoware | ||
|
||
!!! warning | ||
|
||
Under Construction | ||
|
||
This section explains how to run your vehicle with Autoware. | ||
|
||
## Install Autoware | ||
|
||
Follow the [installation steps of Autoware](../../../installation/). | ||
|
||
## Launch Autoware | ||
|
||
Launch Autoware with the following command: | ||
|
||
```bash | ||
ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP | ||
``` | ||
|
||
It is possible to specify which components to launch using command-line arguments. | ||
For example, if you don't need to launch perception, planning, and control for localization debug, you can launch the following: | ||
|
||
```bash | ||
ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ | ||
launch_perception:=false \ | ||
launch_planning:=false \ | ||
launch_control:=false | ||
``` | ||
|
||
The basic command-line options are documented in [autoware.launch.xml](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/launch/autoware.launch.xml). | ||
|
||
There are options available to switch between different methods for some component. | ||
For example, by specifying `localization_mode` or `perception_mode`, you can switch localization and perception methods, respectively. | ||
These options allow you to choose the desired algorithms or sensor configurations for the respective functionalities. | ||
|
||
For options on eagleye component, please refer to the sub-pages. | ||
|
||
- [localization-mode](localization-mode/index.md) | ||
- [perception-mode](perception.md) | ||
|
||
## Set initial pose | ||
|
||
If GNSS is available, Autoware automatically initializes the vehicle's pose. | ||
|
||
If not or if the automatic initialization returns an incorrect position, you need to set the initial pose using the RViz GUI. | ||
|
||
1. Click the 2D Pose estimate button in the toolbar, or hit the P key | ||
|
||
![2D Pose estimate](images/2d_pose_estimate.png) | ||
|
||
2. In the 3D View pane, click and hold the left mouse button, and then drag to set the direction for the initial pose. | ||
|
||
## Set goal pose | ||
|
||
Set a goal pose for the ego vehicle. | ||
|
||
1. Click the 2D Nav Goal button in the toolbar, or hit the G key | ||
|
||
![2D Pose estimate](images/2d_goal_pose.png) | ||
|
||
2. In the 3D View pane, click and hold the left mouse button, and then drag to set the direction for the goal pose. | ||
If successful, you will see the calculated planning path on RViz. | ||
|
||
![route planning](images/route_planning_is_complete.png){width="800"} | ||
|
||
## Engage | ||
|
||
In your terminal, execute the following command. | ||
|
||
```bash | ||
source ~/autoware.YOURS/install/setup.bash | ||
ros2 topic pub /autoware.YOURS/engage autoware_auto_vehicle_msgs/msg/Engage "engage: true" -1 | ||
``` | ||
|
||
You can also engage via RViz with "AutowareStatePanel". | ||
The panel can be found in `Panels > Add New Panel > tier4_state_rviz_plugin > AutowareStatePanel`. | ||
|
||
Once the route is computed, the "AUTO" button becomes active. Pressing the AUTO button engages the autonomous driving mode. | ||
|
||
![autoware state panel](images/autoware_state_panel_before.png) | ||
|
||
Now the vehicle should drive along the calculated path! | ||
|
||
During the autonomous driving, the StatePanel appears as shown in the image below. Pressing the "STOP" button allows you to stop the vehicle. | ||
|
||
![autoware state panel](images/autoware_state_panel_after.png) |
3 changes: 3 additions & 0 deletions
3
docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/.pages
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
nav: | ||
- index.md | ||
- Eagleye: eagleye-guide.md |
120 changes: 120 additions & 0 deletions
120
...-guides/integrating-autoware/launch-autoware/localization-mode/eagleye-guide.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,120 @@ | ||
# Using Eagleye with Autoware | ||
|
||
This page will show you how to set up [Eagleye](https://github.com/MapIV/eagleye) in order to use it with Autoware. | ||
For the details of the integration proposal, please refer to [this discussion](https://github.com/orgs/autowarefoundation/discussions/3257). | ||
|
||
## What is Eagleye? | ||
|
||
Eagleye is an open-source GNSS/IMU-based localizer initially developed by [MAP IV. Inc](https://map4.jp/). It provides a cost-effective alternative to LiDAR and point cloud-based localization by using low-cost GNSS and IMU sensors to provide vehicle position, orientation, and altitude information. | ||
|
||
### Dependencies | ||
|
||
The below packages are automatically installed during the setup of Autoware as they are listed in [autoware.repos](https://github.com/autowarefoundation/autoware/blob/main/autoware.repos). | ||
|
||
1. [Eagleye](https://github.com/MapIV/eagleye.git) (autoware-main branch) | ||
2. [RTKLIB ROS Bridge](https://github.com/MapIV/rtklib_ros_bridge.git) (ros2-v0.1.0 branch) | ||
3. [LLH Converter](https://github.com/MapIV/llh_converter.git) (ros2 branch) | ||
|
||
## Architecture | ||
|
||
Eagleye can be utilized in the Autoware localization stack in two ways: | ||
|
||
1. Feed only twist into the EKF localizer. | ||
|
||
![Eagleye twist integration](images/eagleye-integration-guide/eagleye_twist.drawio.svg) | ||
|
||
2. Feed both twist and pose from Eagleye into the EKF localizer (twist can also be used with regular `gyro_odometry`). | ||
|
||
![Eagleye pose twist integration](images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg) | ||
|
||
**Note: RTK positioning is required when using Eagleye as the pose estimator.** | ||
On the other hand, it is not mandatory when using it as the twist estimator. | ||
|
||
## Requirements | ||
|
||
Eagleye requires GNSS, IMU and vehicle speed as inputs. | ||
|
||
### IMU topic | ||
|
||
`sensor_msgs/msg/Imu` is supported for Eagleye IMU input. | ||
|
||
### Vehicle speed topic | ||
|
||
`geometry_msgs/msg/TwistStamped` and `geometry_msgs/msg/TwistWithCovarianceStamped` are supported for the input vehicle speed. | ||
|
||
### GNSS topic | ||
|
||
Eagleye requires latitude/longitude height and doppler velocity generated by the GNSS receiver. | ||
Your GNSS ROS driver must publish the following messages: | ||
|
||
- `sensor_msgs/msg/NavSatFix`: This message contains latitude, longitude, and height information. | ||
- `geometry_msgs/msg/TwistWithCovarianceStamped`: This message contains gnss doppler velocity information. | ||
|
||
Eagleye has been tested with the following example GNSS ROS drivers: ublox_gps and septentrio_gnss_driver. The settings needed for each of these drivers are as follows: | ||
|
||
| GNSS ROS drivers | modification | | ||
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| [ublox_gps](https://github.com/KumarRobotics/ublox/tree/ros2/ublox_gps) | No additional settings are required. It publishes `sensor_msgs/msg/NavSatFix` and `geometry_msgs/msg/TwistWithCovarianceStamped` required by Eagleye with default settings. | | ||
| [septentrio_gnss_driver](https://github.com/septentrio-gnss/septentrio_gnss_driver/tree/ros2) | Set `publish.navsatfix` and `publish.twist` in the config file [`gnss.yaml`](https://github.com/septentrio-gnss/septentrio_gnss_driver/blob/ros2/config/gnss.yaml#L90) to `true` | | ||
|
||
## Parameter Modifications for Integration into Your Vehicle | ||
|
||
### topic name & topic type | ||
|
||
The users must correctly specify input topics for GNSS latitude, longitude, and height , GNSS doppler speed , IMU , and vehicle speed in the [`eagleye_config.yaml`](https://github.com/MapIV/autoware_launch/blob/3f04a9dd7bc4a4c49d4ec790e3f6b9958ab822da/autoware_launch/config/localization/eagleye_config.param.yaml#L7-L16). | ||
|
||
```yaml | ||
# Topic | ||
twist: | ||
twist_type: 1 # TwistStamped : 0, TwistWithCovarianceStamped: 1 | ||
twist_topic: /sensing/vehicle_velocity_converter/twist_with_covariance | ||
imu_topic: /sensing/imu/tamagawa/imu_raw | ||
gnss: | ||
velocity_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, ublox_msgs/NavPVT: 2, geometry_msgs/TwistWithCovarianceStamped: 3 | ||
velocity_source_topic: /sensing/gnss/ublox/navpvt | ||
llh_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, sensor_msgs/NavSatFix: 2 | ||
llh_source_topic: /sensing/gnss/ublox/nav_sat_fix | ||
``` | ||
### sensor frequency | ||
Also, the frequency of GNSS and IMU must be set in [`eagleye_config.yaml`](https://github.com/MapIV/autoware_launch/blob/3f04a9dd7bc4a4c49d4ec790e3f6b9958ab822da/autoware_launch/config/localization/eagleye_config.param.yaml#L36) | ||
|
||
```yaml | ||
common: | ||
imu_rate: 50 | ||
gnss_rate: 5 | ||
``` | ||
|
||
### Conversion from fix to pose | ||
|
||
The parameters for converting `sensor_msgs/msg/NavSatFix` to `geometry_msgs/msg/PoseWithCovarianceStamped` is listed in [`fix2pose.yaml`](https://github.com/MapIV/eagleye/blob/autoware-main/eagleye_util/fix2pose/launch/fix2pose.xml). | ||
If you use a different geoid or projection type, change these parameters. | ||
|
||
### Other parameters | ||
|
||
The other parameters are described [here](https://github.com/MapIV/eagleye/tree/autoware-main/eagleye_rt/config). | ||
Basically, these do not need to be changed . | ||
|
||
## Notes on initialization | ||
|
||
Eagleye requires an initialization process for proper operation. **Without initialization, the output for twist will be in the raw value, and the pose data will not be available.** | ||
|
||
### 1. Static Initialization | ||
|
||
The first step is static initialization, which involves allowing the Eagleye to remain stationary for approximately 5 seconds after startup to estimate the yaw-rate offset. | ||
|
||
### 2. Dynamic initialization | ||
|
||
The next step is dynamic initialization, which involves running the Eagleye in a straight line for approximately 30 seconds. This process estimates the scale factor of wheel speed and azimuth angle. | ||
|
||
Once dynamic initialization is complete, the Eagleye will be able to provide corrected twist and pose data. | ||
|
||
### How to check the progress of initialization | ||
|
||
- **TODO** | ||
|
||
## Note on georeferenced maps | ||
|
||
Note that the output position might not appear to be in the point cloud maps if you are using maps that are not properly georeferenced. | ||
In the case of a single GNSS antenna, initial position estimation (dynamic initialization) can take several seconds to complete after starting to run in an environment where GNSS positioning is available. |
File renamed without changes
File renamed without changes
129 changes: 129 additions & 0 deletions
129
docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,129 @@ | ||
# Localization mode | ||
|
||
The Autoware provides multiple localization methods that work with multiple different sensor configurations. | ||
The table below shows the supported sensor configurations and their corresponding algorithms. | ||
|
||
| localization mode | algorithm | map type | | ||
| ----------------- | --------- | --------------- | | ||
| LiDAR-based | NDT | point cloud map | | ||
| Camera-based | YabLoc | vector map | | ||
| GNSS/IMU-based | Eagleye | - | | ||
|
||
## LiDAR-based localizer (default) | ||
|
||
By default, Autoware launches [ndt_scan_matcher](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/ndt_scan_matcher) for localization. | ||
|
||
## Camera-based localizer | ||
|
||
You can use YabLoc as a camera-based localization method. | ||
For more details on YabLoc, please refer to the [README of YabLoc](https://github.com/autowarefoundation/autoware.universe/blob/main/localization/yabloc/README.md) in autoware.universe. | ||
|
||
To use YabLoc as a pose_estimator, add `localization_mode:=camera` when launching Autoware. | ||
By default, the `localization_mode` is set to `lidar`. | ||
By specifying this command-line argument, YabLoc nodes will be automatically launched while the NDT nodes will not be started. | ||
|
||
Here is an example of a launch command: | ||
|
||
```bash | ||
ros2 launch autoware_launch autoware.launch.xml \ | ||
vehicle_model:=YOUR_VEHICLE \ | ||
sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ | ||
localization_mode:=camera # Add this argument | ||
``` | ||
|
||
## GNSS/IMU-based localizer | ||
|
||
You can use Eagleye as a GNSS/IMU-based localization method. For more details on Eagleye, please refer to the [Eagleye](eagleye-guide.md). | ||
|
||
Eagleye has a function for position estimation and twist estimation, namely `pose_estimator` and `twist_estimator`, respectively. | ||
When running Eagleye in twist_estimator mode, ndt_scan_matcher is used as the pose_estimator. | ||
Eagleye will improve scan matching by providing accurate twists using GNSS doppler. | ||
|
||
To use Eagleye, it requires both specifying the command-line arguments and modifying the launch file. | ||
|
||
Firstly, please modify the commented-out line and change it to launch `map4_localization_component.launch.xml` instead of `tier4_localization_component.launch.xml` in [`autoware.launch.xml`](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/launch/autoware.launch.xml). | ||
Please refer to the following snippet for the modification details: | ||
|
||
```xml | ||
<!-- Localization --> | ||
<group if="$(var launch_localization)"> | ||
<!-- <include file="$(find-pkg-share autoware_launch)/launch/components/tier4_localization_component.launch.xml"/> --> | ||
<include file="$(find-pkg-share autoware_launch)/launch/components/map4_localization_component.launch.xml"/> | ||
</group> | ||
``` | ||
|
||
NOTE: Please refer to [`map4_localization_launch`](https://github.com/autowarefoundation/autoware.universe/tree/main/launch/map4_localization_launch) in the `autoware.universe` package and [`map4_localization_component.launch.xml`](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/launch/components/map4_localization_component.launch.xml) in `autoware_launch` package for information on how to modify the localization launch. | ||
|
||
Once you have modified the launch file, you can use Eagleye by specifying the `pose_estimator_mode` through command-line arguments. | ||
|
||
**Example of using Eagleye as the pose twist estimator:** | ||
|
||
```bash | ||
ros2 launch autoware_launch autoware.launch.xml \ | ||
vehicle_model:=YOUR_VEHICLE \ | ||
sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ | ||
pose_estimator_mode:=gnss # Add this argument | ||
``` | ||
|
||
**Example of using Eagleye as the twist estimator:** | ||
|
||
```bash | ||
ros2 launch autoware_launch autoware.launch.xml \ | ||
vehicle_model:=YOUR_VEHICLE \ | ||
sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ | ||
pose_estimator_mode:=lidar # Not mandatory, as it is the default. | ||
``` | ||
|
||
## Comprehensive Options Table | ||
|
||
The table below indicates which pose_estimator and twist_estimator are called based on the invoked launch file and provided arguments. | ||
|
||
<table> | ||
<thead> | ||
<tr> | ||
<th colspan=3>tier4_localization_component.launch.xml</th> | ||
</tr> | ||
<tr> | ||
<th>localization_mode</th> | ||
<th>pose_estimator</th> | ||
<th>twist_estimator</th> | ||
</tr> | ||
</thead> | ||
<tbody> | ||
<tr> | ||
<td>lidar (default)</td> | ||
<td>ndt_scan_matcher</td> | ||
<td>gyro_odometer</td> | ||
</tr> | ||
<tr> | ||
<td>camera</td> | ||
<td>yabloc</td> | ||
<td>gyro_odometer</td> | ||
</tr> | ||
</tbody> | ||
</table> | ||
|
||
<table> | ||
<thead> | ||
<tr> | ||
<th colspan=3>map4_localization_component.launch.xml</th> | ||
</tr> | ||
<tr> | ||
<th>pose_estimator_mode</th> | ||
<th>pose_estimator</th> | ||
<th>twist_estimator</th> | ||
</tr> | ||
</thead> | ||
<tbody> | ||
<tr> | ||
<td>lidar (default)</td> | ||
<td>ndt_scan_matcher</td> | ||
<td>eagleye</td> | ||
</tr> | ||
<tr> | ||
<td>gnss</td> | ||
<td>eagleye</td> | ||
<td>eagleye</td> | ||
</tr> | ||
</tbody> | ||
</table> |
Oops, something went wrong.