docs(eagleye-setting-guide): add eagleye setting in how to guides (#334)

* feat: add parameter description (#271) Signed-off-by: Ryohei Sasaki <[email protected]> * Add eagleye-setting in how-to-guides Signed-off-by: Ryohei Sasaki <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Add description of what ealgeye estimates Signed-off-by: Ryohei Sasaki <[email protected]> * Update eagleye-integration-guide.md Signed-off-by: Ryohei Sasaki <[email protected]> * Fix typo Signed-off-by: Ryohei Sasaki <[email protected]> * Delete unnecessary line breaks Signed-off-by: Ryohei Sasaki <[email protected]> * Change prefix Signed-off-by: Ryohei Sasaki <[email protected]> * Add description for eagleye Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Correction of incorrect description of twist integration Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Fix misspellings Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Added explanation of RTK positioning. Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Add description of parameters Signed-off-by: ryohei sasaki <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Specify the files needed for the autoware localized launcher to run eagleye Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Modification to match changes in structue of launch Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Update doc Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Remove unnecessary links Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Add eagleye description as twsit estimator Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Initial suggestions Signed-off-by: Ryohei Sasaki <[email protected]> * Correction of images Signed-off-by: Ryohei Sasaki <[email protected]> * Pretter format Signed-off-by: Ryohei Sasaki <[email protected]> * Fix markdownlint problem Signed-off-by: Ryohei Sasaki <[email protected]> * feat(design): update node diagram (#322) * feat(design): update node diagram Signed-off-by: Kaan Çolak <[email protected]> * feat(design): rm range splitter Signed-off-by: Kaan Çolak <[email protected]> --------- Signed-off-by: Kaan Çolak <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * feat: update map_loader in node diagram (#324) feat: update map_loader Signed-off-by: kminoda <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * feat(installation, troubleshooting): update network settings (#306) * update network setting in additional settings page Signed-off-by: Yukihiro Saito <[email protected]> * Correct duplicates and links Signed-off-by: Yukihiro Saito <[email protected]> * style(pre-commit): autofix * fix title style Signed-off-by: Yukihiro Saito <[email protected]> * modify document following comments Signed-off-by: Yukihiro Saito <[email protected]> --------- Signed-off-by: Yukihiro Saito <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Signed-off-by: Ryohei Sasaki <[email protected]> * fix(node-diagram): revert node-diagram mistake (#326) fix: revert node-diagram mistake Signed-off-by: kminoda <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * docs(planning-diagram): add planning validator (#327) Signed-off-by: Takamasa Horibe <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * docs(design/autoware-interfaces): add localization interface (#311) * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * docs(design/autoware-interfaces): add localization interface Signed-off-by: Cynthia Liu <[email protected]> * style(pre-commit): autofix --------- Signed-off-by: Cynthia Liu <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Signed-off-by: Ryohei Sasaki <[email protected]> * docs(autoware-interfaces): add temporary link for overview (#336) Signed-off-by: Takagi, Isamu <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * feat: add a part of important planning parameters' explanation (#338) Signed-off-by: Takayuki Murooka <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * chore: sync files (#291) Signed-off-by: GitHub <[email protected]> Co-authored-by: kenji-miyake <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * chore: fix links (#341) Signed-off-by: Kenji Miyake <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * chore: sync files (#342) Signed-off-by: GitHub <[email protected]> Co-authored-by: kenji-miyake <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * feat(contributing): add the definition of standard change and small change for PR (#344) * docs(contributing): add the definition of standard change and small change for PR * style(pre-commit): autofix * Update docs/contributing/pull-request-guidelines/index.md Co-authored-by: Kenji Miyake <[email protected]> * docs: change structure Signed-off-by: Shumpei Wakabayashi <[email protected]> * refactor: make simpler Signed-off-by: Shumpei Wakabayashi <[email protected]> * chore: organize sentence Signed-off-by: Shumpei Wakabayashi <[email protected]> * chore: organize sentence Signed-off-by: Shumpei Wakabayashi <[email protected]> * Update docs/contributing/pull-request-guidelines/index.md Co-authored-by: Kenji Miyake <[email protected]> * refactor: more simpler Signed-off-by: Shumpei Wakabayashi <[email protected]> * chore: change the standard template target Signed-off-by: Shumpei Wakabayashi <[email protected]> * style: organize index Signed-off-by: Shumpei Wakabayashi <[email protected]> --------- Signed-off-by: Shumpei Wakabayashi <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Kenji Miyake <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * docs(support/troubleshooting): update information about python setuptools in troubleshooting section (#346) Co-authored-by: Piotr Zyskowski <[email protected]> Signed-off-by: Mateusz Palczuk <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * fix: fix the broken link for MapIV Engine (#349) Fix the broken link for MapIV Engine Signed-off-by: Ryohei Sasaki <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * docs(support/troubleshooting): add a runtime issue troubleshooting (#350) * docs(support/troubleshooting): add a runtime issue troubleshooting Signed-off-by: Cynthia Liu <[email protected]> * style(pre-commit): autofix --------- Signed-off-by: Cynthia Liu <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Signed-off-by: Ryohei Sasaki <[email protected]> * Reflecting reviews Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Fix Autowares Signed-off-by: autoware <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * chore: sync files (#343) Signed-off-by: GitHub <[email protected]> Co-authored-by: kenji-miyake <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * fix the broken link Signed-off-by: Ryohei Sasaki <[email protected]> * fix: fix the broken link for MapIV Engine (#354) Fix the broken link for MapIV Engine Signed-off-by: Ryohei Sasaki <[email protected]> Co-authored-by: Ryohei Sasaki <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Correction of misleading wording and addition of necessary package descriptions Signed-off-by: Ryohei Sasaki <[email protected]> * Change structher (#2) * Change structher Signed-off-by: Ryohei Sasaki <[email protected]> * Add new line Signed-off-by: Ryohei Sasaki <[email protected]> * Structural changes after meeting Signed-off-by: Ryohei Sasaki <[email protected]> --------- Signed-off-by: Ryohei Sasaki <[email protected]> Co-authored-by: Ryohei Sasaki <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> * Run pre-commit locally Signed-off-by: map4 <[email protected]> --------- Signed-off-by: Ryohei Sasaki <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> Signed-off-by: autoware <[email protected]> Signed-off-by: ryohei sasaki <[email protected]> Signed-off-by: Kaan Çolak <[email protected]> Signed-off-by: kminoda <[email protected]> Signed-off-by: Yukihiro Saito <[email protected]> Signed-off-by: Takamasa Horibe <[email protected]> Signed-off-by: Cynthia Liu <[email protected]> Signed-off-by: Takagi, Isamu <[email protected]> Signed-off-by: Takayuki Murooka <[email protected]> Signed-off-by: GitHub <[email protected]> Signed-off-by: Kenji Miyake <[email protected]> Signed-off-by: Shumpei Wakabayashi <[email protected]> Signed-off-by: Mateusz Palczuk <[email protected]> Signed-off-by: Ryohei Sasaki <[email protected]> Signed-off-by: map4 <[email protected]> Co-authored-by: kminoda <[email protected]> Co-authored-by: Patiphon Narksri <[email protected]> Co-authored-by: Kaan Çolak <[email protected]> Co-authored-by: Yukihiro Saito <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Takamasa Horibe <[email protected]> Co-authored-by: cyn-liu <[email protected]> Co-authored-by: Takagi, Isamu <[email protected]> Co-authored-by: Takayuki Murooka <[email protected]> Co-authored-by: awf-autoware-bot[bot] <94889083+awf-autoware-bot[bot]@users.noreply.github.com> Co-authored-by: kenji-miyake <[email protected]> Co-authored-by: Kenji Miyake <[email protected]> Co-authored-by: Shumpei Wakabayashi <[email protected]> Co-authored-by: Mateusz Palczuk <[email protected]> Co-authored-by: Piotr Zyskowski <[email protected]>
autowarefoundation · May 8, 2023 · 3f97e5e · 3f97e5e
1 parent f7cd8df
commit 3f97e5e
Show file tree

Hide file tree

Showing 5 changed files with 138 additions and 0 deletions.
diff --git a/docs/how-to-guides/.pages b/docs/how-to-guides/.pages
@@ -12,3 +12,4 @@ nav:
   - debug-autoware.md
   - add-a-custom-ros-message.md
   - fixing-dependent-package-versions.md
+  - eagleye-integration-guide.md
diff --git a/docs/how-to-guides/eagleye-integration-guide.md b/docs/how-to-guides/eagleye-integration-guide.md
@@ -0,0 +1,128 @@
+# 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](https://github.com/orgs/autowarefoundation/discussions/3257) Discussion.
+
+## 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. By integrating Eagleye into Autoware, users can choose between LiDAR and point cloud-based localization stacks or GNSS/IMU-based Eagleye localizer, depending on their specific needs and operating environment.
+
+## 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 that RTK positioning is only required for localization using the Eagleye pose. RTK positioning is not required for twist.
+
+## Requirements
+
+GNSS/IMU/vehicle speed is required for Eagleye input.
+
+### IMU topic
+
+`sensor_msgs/msg/Imu` are supported for IMU.
+
+### 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 information and velocity information 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:
+
+- [ublox_gps](https://github.com/KumarRobotics/ublox/tree/ros2/ublox_gps): This ROS driver publishes `sensor_msgs/msg/NavSatFix` and `geometry_msgs/msg/TwistWithCovarianceStamped` required by Eagleye with default settings. Therefore, no additional settings are required.
+- [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`
+
+## Eagleye Setup
+
+### Install dependencies
+
+Clone the following three packages for Eagleye:
+
+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)
+
+### Modifying Autoware Launch files
+
+You need to install Eagleye-related packages and change Autoware's launcher. Four files are required in the Autoware localization launcher to run Eagleye: `eagleye_rt.launch.xml`, `eagleye_config.yaml`, `gnss_converter.launch.xml`, and `fix2pose.launch.xml`.
+
+You must correctly specify input topics for GNSS latitude, longitude, and height information, GNSS speed information, IMU information, and vehicle speed information 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
+```
+
+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
+```
+
+The basic parameters that do not need to be changed except those mentioned above, i.e., topic names and sensors' frequency, are described below [here](https://github.com/MapIV/eagleye/tree/autoware-main/eagleye_rt/config).
+Additionally, 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).
+
+Please refer to `map4_localization_launch` in the `autoware.universe` package and `map4_localization_component.launch.xml` in `autoware_launch` package for information on how to modify the localization launch.
+
+Eagleye has a function for position estimation and a function for twist estimation, namely `pose_estimator` and `twist_estimator`, respectively.
+
+| localization launch                                               | twist estimator                     | pose estimator                      |
+| ----------------------------------------------------------------- | ----------------------------------- | ----------------------------------- |
+| `tier4_localization_launch`                                       | `gyro_odometry`                     | `ndt_scan_matcher`                  |
+| `map4_localization_launch/eagleye_twist_localization_launch`      | `eagleye_rt`(gyro/odom/gnss fusion) | `ndt_scan_matcher`                  |
+| `map4_localization_launch/eagleye_pose_twist_localization_launch` | `eagleye_rt`(gyro/odom/gnss fusion) | `eagleye_rt`(gyro/odom/gnss fusion) |
+
+In Autoware, you can set the pose estimator to GNSS by setting `pose_estimator_mode:=gnss` in `map4_localization_component.launch.xml` in `autoware_launch` package.
+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.
+
+Alternatively, the twist estimator can be set to Eagleye and the pose estimator to NDT by specifying `pose_estimator_mode:=lidar` in the same launch file.
+Unlike Eagleye position estimation, Eagleye twist estimation first outputs uncorrected raw values when activated, and then outputs corrected twists as soon as static initialization is complete.
+
+## Executing Launch files
+
+### Execution command
+
+Enable Eagleye in Autoware by switching the localization module in autoware.launch.xml and the `pose_estimator_mode` parameter in `map4_localization_component.launch.xml` in `autoware.launch.xml`.
+
+When using Eagleye, comment out `tier4_localization_component.launch.xml` and start `map4_localization_component.launch.xml` in `autoware.launch.xml`.
+
+```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>
+```
+
+#### Notes with 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.
+
+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.
+
+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.