Merge pull request #20 from tier4/sync-upstream

chore: sync upstream

.github/workflows/github-release.yaml

@@ -9,6 +9,7 @@ on:
   workflow_dispatch:
     inputs:
       beta-branch-or-tag-name:
+        description: The name of the beta branch or tag to release
         type: string
         required: true
 
@@ -54,7 +55,7 @@ jobs:
       - name: Select verb
         id: select-verb
         run: |
-          has_previous_draft=$(gh release view --json isDraft -q ".isDraft" "${{ steps.set-tag-name.outputs.tag-name }}")
+          has_previous_draft=$(gh release view --json isDraft -q ".isDraft" "${{ steps.set-tag-name.outputs.tag-name }}") || true
 
           verb=create
           if [ "$has_previous_draft" = "true" ]; then

.pre-commit-config.yaml

@@ -41,7 +41,7 @@ repos:
       - id: shellcheck
 
   - repo: https://github.com/scop/pre-commit-shfmt
-    rev: v3.4.3-1
+    rev: v3.5.0-1
     hooks:
       - id: shfmt
         args: [-w, -s, -i=4]

docs/contributing/coding-guidelines/ros-nodes/message-guidelines.md

@@ -87,7 +87,7 @@ int32[] unbounded_integer_array
 
 ## Enumerations
 
-ROS2 interfaces don't support enumerations directly.
+ROS 2 interfaces don't support enumerations directly.
 
 It is possible to define integers constants and assign them to a non-constant integer parameter.
 

docs/design/autoware-interfaces/components/.pages

@@ -3,3 +3,4 @@ nav:
   - planning.md
   - control.md
   - vehicle-interface.md
+  - vehicle-dimensions.md

docs/design/autoware-interfaces/components/vehicle-dimensions.md

@@ -0,0 +1,83 @@
+# Vehicle dimensions
+
+## Vehicle axes and base_link
+
+![Vehicle Axes](images/vehicle_axes.svg){: style="width:500px"}
+
+The `base_link` frame is used very frequently throughout the stack, and is in the center of the rear axle.
+
+- Localization module outputs the `map` to `base_link` transformation.
+- Planning module plans the poses for where the `base_link` frame should be in the future.
+- Control module tries to fit `base_link` to incoming poses.
+
+## Vehicle dimensions
+
+![Vehicle Dimensions](images/vehicle_dimensions.svg){: style="width:550px"}
+
+### wheelbase
+
+The distance between front and rear axles.
+
+### track_width
+
+The distance between left and right wheels.
+
+### Overhangs
+
+Overhangs are part of the minimum safety box calculation.
+
+When measuring overhangs, side mirrors, protruding sensors and wheels should be taken into consideration.
+
+#### left_overhang
+
+The distance between the axis centers of the left wheels and the left-most point of the vehicle.
+
+#### right_overhang
+
+The distance between the axis centers of the right wheels and the right-most point of the vehicle.
+
+#### front_overhang
+
+The distance between the front axle and the foremost point of the vehicle.
+
+#### rear_overhang
+
+The distance between the rear axle and the rear-most point of the vehicle.
+
+### vehicle_length
+
+Total length of the vehicle. Calculated by `front_overhang + wheelbase + rear_overhang`
+
+### vehicle_width
+
+Total width of the vehicle. Calculated by `left_overhang + track_width + right_overhang`
+
+### Wheel parameters
+
+![Wheel Dimensions](images/wheels.svg){: style="width:350px"}
+
+#### wheel_width
+
+The lateral width of a wheel tire, primarily used for dead reckoning.
+
+#### wheel_radius
+
+The radius of the wheel, primarily used for dead reckoning.
+
+### polygon_footprint
+
+![Wheel Dimensions](images/polygon_footprint.svg){: style="width:350px"}
+
+The polygon defines the minimum collision area for the vehicle.
+
+The points should be ordered clockwise, with the origin on the `base_link`.
+
+## Wheel orientations
+
+If the vehicle is going forward, a positive wheel angle will result in the vehicle turning left.
+
+Autoware assumes the rear wheels don't turn on `z` axis.
+
+## Notice
+
+The vehicle used in the illustrations was created by xvlblo22 and is from <https://www.turbosquid.com/3d-models/modular-sedan-3d-model-1590886>.

docs/how-to-guides/.pages

@@ -1,3 +1,4 @@
 nav:
   - index.md
   - advanced-usage-of-colcon.md
+  - how-to-integrate-autoware-with-your-vehicle.md

docs/how-to-guides/advanced-usage-of-colcon.md

@@ -18,7 +18,7 @@ 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).
+For more details about `workspace overlaying`, refer to the [ROS 2 documentation](https://docs.ros.org/en/rolling/Tutorials/Workspace/Creating-A-Workspace.html#source-the-overlay).
 
 ## Cleaning up the build artifacts
 

docs/how-to-guides/how-to-integrate-autoware-with-your-vehicle.md

@@ -0,0 +1,173 @@
+# How to integrate Autoware with your vehicle
+
+## 1. Prepare your real vehicle hardware
+
+Prerequisites for the vehicle:
+
+- An onboard computer that satisfies the [Autoware installation prerequisites](https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/#prerequisites)
+- The following devices attached
+  - Drive-by-wire interface
+  - LiDAR
+  - Optional: Inertial measurement unit
+  - Optional: Camera
+  - Optional: GNSS
+
+## 2. Create maps
+
+You need both a pointcloud map and a vector map in order to use Autoware.
+
+### Create a pointcloud map
+
+Use third-party tools such as a LiDAR-based SLAM (Simultaneous Localization And Mapping) package to create a pointcloud map in the `.pcd` format.
+Some examples are:
+
+- [HDL](https://github.com/koide3/hdl_graph_slam)
+- [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM)
+- [LiDAR-SLAM (ROS 2)](https://github.com/rsasaki0109/lidarslam_ros2)
+
+### Create vector map
+
+Use third-party tools such as [TIER IV's Vector Map Builder](https://tools.tier4.jp/) to create a Lanelet2 format `.osm` file.
+
+## 3. Create your Autoware meta-repository
+
+Create your Autoware meta-repository.
+One easy way is to fork [autowarefoundation/autoware](https://github.com/autowarefoundation/autoware) and clone it.
+Refer to [GitHub Docs](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for how to fork a repository.
+
+```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.
+
+## 4. Create the description packages of your vehicle
+
+Next, you need to create description packages that define the vehicle and sensor configuration of your vehicle.
+
+Create the following two packages:
+
+- YOUR_VEHICLE_launch (see [here](https://github.com/autowarefoundation/sample_vehicle_launch) for example)
+- YOUR_SENSOR_KIT_launch (see [here](https://github.com/autowarefoundation/sample_sensor_kit_launch) for example)
+
+Once created, you need to update the `autoware.repos` file of your cloned Autoware repository to refer to these two description packages.
+
+```diff
+-  # sensor_kit
+-  sensor_kit/sample_sensor_kit_launch:
+-    type: git
+-    url: https://github.com/autowarefoundation/sample_sensor_kit_launch.git
+-    version: main
+-  # vehicle
+-  vehicle/sample_vehicle_launch:
+-    type: git
+-    url: https://github.com/autowarefoundation/sample_vehicle_launch.git
+-    version: main
++  # sensor_kit
++  sensor_kit/YOUR_SENSOR_KIT_launch:
++    type: git
++    url: https://github.com/YOUR_NAME/YOUR_SENSOR_KIT_launch.git
++    version: main
++  # vehicle
++  vehicle/YOUR_VEHICLE_launch:
++    type: git
++    url: https://github.com/YOUR_NAME/YOUR_VEHICLE_launch.git
++    version: main
+```
+
+### Adapt YOUR_VEHICLE_launch for autoware launching system
+
+#### At YOUR_VEHICLE_description
+
+Define URDF and parameters in the vehicle description package (refer to the [sample vehicle description package](https://github.com/autowarefoundation/sample_vehicle_launch/tree/main/sample_vehicle_description) for an example).
+
+#### At YOUR_VEHICLE_launch
+
+Create a launch file (refer to the [sample vehicle launch package](https://github.com/autowarefoundation/sample_vehicle_launch/tree/main/sample_vehicle_launch) for example).
+If you have multiple vehicles with the same hardware setup, you can specify `vehicle_id` to distinguish them.
+
+### Adapt YOUR_SENSOR_KIT_description for autoware launching system
+
+#### At YOUR_SENSOR_KIT_description
+
+Define URDF and extrinsic parameters for all the sensors here (refer to the [sample sensor kit description package](https://github.com/autowarefoundation/sample_sensor_kit_launch/tree/main/sample_sensor_kit_description) for example).
+Note that you need to calibrate extrinsic parameters for all the sensors beforehand.
+
+#### At YOUR_SENSOR_KIT_launch
+
+Create `launch/sensing.launch.xml` that launches the interfaces of all the sensors on the vehicle. (refer to the [sample sensor kit launch package](https://github.com/autowarefoundation/sample_sensor_kit_launch/tree/main/sample_sensor_kit_launch) for example).
+
+!!! note
+
+    At this point, you are now able to run Autoware's Planning Simulator to do a basic test of your vehicle and sensing packages.
+    To do so, you need to build and install Autoware using your cloned repository. Follow the [steps for either Docker or source installation](https://autowarefoundation.github.io/autoware-documentation/main/installation/) (starting from the dependency installation step) and then run the following command:
+
+    ```bash
+    ros2 launch autoware_launch planning_simulator.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP
+    ```
+
+## 5. Create a `vehicle_interface` package
+
+You need to create an interface package for your vehicle.
+The package is expected to provide the following two functions.
+
+1. Receive command messages from `vehicle_cmd_gate` and drive the vehicle accordingly
+2. Send vehicle status information to Autoware
+
+You can find detailed information about the requirements of the `vehicle_interface` package in the [Vehicle Interface design documentation](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-interface/).
+You can also refer to TIER IV's [pacmod_interface repository](https://github.com/tier4/pacmod_interface) as an example of a vehicle interface package.
+
+## 6. Launch Autoware
+
+This section briefly explains how to run your vehicle with Autoware.
+
+### Install Autoware
+
+Follow the [installation steps of Autoware](https://autowarefoundation.github.io/autoware-documentation/main/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
+```
+
+### Set initial pose
+
+If GNSS is available, Autoware automatically initializes the vehicle's pose.
+
+If not, 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
+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
+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.
+
+### 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`.
+
+![Autoware State Panel](images/how-to-integrate-autoware-with-your-vehicle/autoware-state-panel.png){: style="height:360px;width:640px"}
+
+Now the vehicle should drive along the calculated path!
+
+## 7. Tune parameters for your vehicle & environment
+
+You may need to tune your parameters depending on the domain in which you will operate your vehicle.
+
+If you have any issues or questions, feel free to create an [Autoware Foundation GitHub Discussion](https://github.com/orgs/autowarefoundation/discussions) in the Q&A category!

docs/how-to-guides/index.md

@@ -1,11 +1,11 @@
 # How-to guides
 
 - [Advanced usage of colcon](advanced-usage-of-colcon.md)
+- [Integrate Autoware with your vehicle](how-to-integrate-autoware-with-your-vehicle.md)
 
 TODO: Write the following contents.
 
 - Create an Autoware package
 - Add a custom ROS message
 - Debug Autoware
-- Integrate Autoware with a real vehicle
 - etc.