Merge pull request #39 from tier4/sync-upstream

chore: sync upstream

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

@@ -1,5 +1,36 @@
 # Parameters
 
-!!! warning
+The ROS packages in Autoware have ROS parameters. You need to customize the parameters depending on your applications.
+It is recommended not to set default values when declaring ROS parameters to avoid unintended behaviors due to accidental use of default values.
+Instead, set parameters from configuration files named `*.param.yaml`.
 
-    Under Construction
+For understanding ROS 2 parameters, also check out the official documentation [Understanding parameters](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html).
+
+## Parameter files
+
+Autoware has the following two types of parameter files for ROS packages:
+
+- **Node parameter file**
+  - Node parameter files store the default parameters provided for each package in Autoware.
+    - For example, [the parameter of `behavior_path_planner`](https://github.com/autowarefoundation/autoware.universe/tree/245242cee866de2d113e89c562353c5fc17f1f98/planning/behavior_path_planner/config)
+  - All nodes in Autoware must have a parameter file if one or more parameters that can be customized by the user are defined.
+  - For `FOO_package`, the parameter is expected to be stored in `FOO_package/config`.
+  - The launch file for individual packages must load node parameter by default:
+
+```xml
+<launch>
+  <arg name="foo_node_param_path" default="$(find-pkg-share FOO_package)/config/foo_node.param.yaml" />
+
+  <node pkg="FOO_package" exec="foo_node">
+    ...
+    <param from="$(var foo_node_param_path)" />
+  </node>
+</launch>
+```
+
+- **Launch parameter file**
+  - Launch parameter files store the customized parameters for user's vehicle.
+    - For example, [the customized parameter of `behavior_path_planner` stored under `autoware_launch`](https://github.com/autowarefoundation/autoware_launch/tree/5fa613b9d80bf4f0db77efde03a43f7ede6bac86/autoware_launch/config)
+  - Launch parameter files are stored under `autoware_launch`.
+
+All the parameter files should have the `.param.yaml` suffix so that the auto-format can be applied properly.

docs/installation/additional-settings-for-developers/index.md

@@ -1,6 +1,6 @@
 # Additional settings for developers
 
-## ROS 2 settings
+## Console settings for ROS 2
 
 ### Colorizing logger output
 
@@ -22,16 +22,49 @@ export RCUTILS_CONSOLE_OUTPUT_FORMAT="[{severity} {time}] [{name}]: {message} ({
 
 For more options, see [here](https://docs.ros.org/en/rolling/Tutorials/Logging-and-logger-configuration.html#console-output-formatting).
 
-### Enabling localhost-only communication
+## Network settings for ROS 2
 
-By default, ROS 2 communicates using multi-cast, which may unnecessarily increase the network traffic.
-To avoid it, write the following in your `.bashrc`:
+ROS 2 employs DDS, and the configuration of ROS 2 and DDS is described separately.
+For ROS 2 networking concepts, refer to the [official documentation](http://design.ros2.org/articles/ros_on_dds.html).
+
+### ROS 2 network setting
+
+ROS 2 multicasts data on the local network by default.
+Therefore, when you develop in an office, the data flows over the local network of your office.
+It may cause collisions of packets or increases in network traffic.
+
+To avoid these, there are two options.
+
+- Localhost-only communication
+- Same domain only communication on the local network
+
+Unless you plan to use multiple host computers on the local network, localhost-only communication is recommended.
+For details, refer to the sections below.
+
+#### Enabling localhost-only communication
+
+Write the following in your `.bashrc`:
+For more information, see the [ROS 2 documentation](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#the-ros-localhost-only-variable).
 
 ```bash
 export ROS_LOCALHOST_ONLY=1
 ```
 
-### Setting up `ROS_DOMAIN_ID`
+If you export `ROS_LOCALHOST_ONLY=1`, `MULTICAST` must be enabled at the loopback address.
+To verify that `MULTICAST` is enabled, use the following command.
+
+```console
+$ ip link show lo
+1: lo: <LOOPBACK,MULTICAST,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
+```
+
+If the word `MULTICAST` is not printed, use the following command to enable it.
+
+```bash
+sudo ip link set lo multicast on
+```
+
+#### Same domain only communication on the local network
 
 ROS 2 uses `ROS_DOMAIN_ID` to create groups and communicate between machines in the groups.
 Since all ROS 2 nodes use domain ID `0` by default, it may cause unintended interference.
@@ -44,13 +77,21 @@ To avoid it, set a different domain ID for each group in your `.bashrc`:
 export ROS_DOMAIN_ID=X
 ```
 
-For more information, see [here](https://docs.ros.org/en/foxy/Concepts/About-Domain-ID.html#the-ros-domain-id).
+Also confirm that `ROS_LOCALHOST_ONLY` is `0` by using the following command.
 
-### Tuning DDS
+```bash
+echo $ROS_LOCALHOST_ONLY # If the output is 1, localhost has priority.
+```
+
+For more information, see the [ROS 2 Documentation](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#the-ros-domain-id-variable).
+
+### DDS settings
 
 Autoware uses DDS for inter-node communication. [ROS 2 documentation](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html) recommends users to tune DDS to utilize its capability. Especially, receive buffer size is the critical parameter for Autoware. If the parameter is not large enough, Autoware will failed in receiving large data like point cloud or image.
 
-For example, to execute Autoware with CycloneDDS, prepare config file. A sample config file, named as `cyclonedds_config.xml`, is given below.
+#### Tuning DDS
+
+Unless customized, CycloneDDS is adopted by default. For example, to execute Autoware with CycloneDDS, prepare a config file. A sample config file is given below. Save it as `cyclonedds_config.xml`.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8" ?>
@@ -71,9 +112,9 @@ export CYCLONEDDS_URI=file:///absolute/path/to/cyclonedds_config.xml
 sudo sysctl -w net.core.rmem_max=2147483647
 ```
 
-Refer to [ROS 2 documentation](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html) for more information. Reading user guide for chosen DDS is helpful for more understanding.
+For more information, Refer to [ROS 2 documentation](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html). Reading user guide for chosen DDS is helpful for more understanding.
 
-### Tuning DDS for multiple host computers (for advanced users)
+#### Tuning DDS for multiple host computers (for advanced users)
 
 When Autoware runs on multiple host computers, IP Fragmentation should be taken into account. As [ROS 2 documentation](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html#cross-vendor-tuning) recommends, parameters for IP Fragmentation should be set as shown in the following example.
 

docs/installation/autoware/docker-installation-devel.md

@@ -53,7 +53,7 @@ You might need to log out and log back to make the current user able to use dock
    mkdir ~/autoware_map
    ```
 
-2. Pull the Dokcer image
+2. Pull the Docker image
 
    ```bash
    docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda

docs/support/troubleshooting.md

@@ -169,16 +169,15 @@ When running the Planning Simulator, the most common reason for the map not bein
 
 Another possible reason is that map loading is taking a long time due to poor DDS performance. To address this issue, first enable localhost-only communication to reduce network traffic, and then [tune DDS settings](https://docs.ros.org/en/rolling/How-To-Guides/DDS-tuning.html) if the problem continues to occur.
 
-1. [Enable localhost-only communication](../installation/additional-settings-for-developers/index.md#enabling-localhost-only-communication)
-2. Tune DDS settings
-
-Add the following lines to `/etc/sysctl.conf`
+Simply put, add the following settings to `.bashrc` and reboot the terminal. In many cases this is not a problem.
 
 ```bash
-net.ipv4.ipfrag_time=3  // generic DDS setting
-net.ipv4.ipfrag_high_thresh=134217728 // generic DDS setting
-net.core.rmem_max=2147483647 // only add if CycloneDDS is configured
-net.core.rmem_default=8388608 // only add if CycloneDDS is confgured
+export ROS_LOCALHOST_ONLY=1
+if [ ! -e /tmp/cycloneDDS_configured ]; then
+  sudo sysctl -w net.core.rmem_max=2147483647
+  sudo ip link set lo multicast on
+  touch /tmp/cycloneDDS_configured
+fi
 ```
 
 !!! note
@@ -189,6 +188,11 @@ net.core.rmem_default=8388608 // only add if CycloneDDS is confgured
     echo $RMW_IMPLEMENTATION  // if Cyclone DDS is configured, this command will return "rmw_cyclonedds_cpp"
     ```
 
+If that does not work or you need more information, read the following documents.
+
+1. [Enable localhost-only communication](../installation/additional-settings-for-developers/index.md#enabling-localhost-only-communication)
+2. [DDS settings](../installation/additional-settings-for-developers/index.md#tuning-dds)
+
 ### Multicast is disabled
 
 If you get the error message `selected interface "{your-interface-name}" is not multicast-capable: disabling multicast`, run the following command to allow multicast.

mkdocs.yaml

@@ -15,6 +15,7 @@ theme:
     - navigation.tabs
     - navigation.tabs.sticky
     - navigation.top
+    - navigation.footer
   favicon: assets/images/autoware-foundation.png
   icon:
     logo: fontawesome/solid/car