From dbaedb850d8ad18906a5c80e644263167c3da946 Mon Sep 17 00:00:00 2001
From: Chris Iverach-Brereton <civerachb@clearpathrobotics.com>
Date: Mon, 29 Sep 2025 14:13:47 -0400
Subject: [PATCH] Add documentation for system.bash and updated
 platform.extras.launch

---
 .../ros/config/yaml/platform/extras.mdx       | 55 ++++++++++++++++---
 .../ros/config/yaml/system.mdx                | 24 ++++++++
 2 files changed, 72 insertions(+), 7 deletions(-)

diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx
index b57d619dc..38534af04 100644
--- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx
+++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx
@@ -12,11 +12,12 @@ Despite all current customization options, we still would like our users to be a
 Extras have the following entries:
 
 - **urdf:**
-  - **package:** name of the ROS 2 package that contains the extras URDF (optional).
   - **path:** relative path within the package or absolute path to robot extras URDF
-- **launch:**
-  - **package:** name of the ROS 2 package that contains the extras launch file (optional).
+  - **package:** name of the ROS 2 package that contains the extras URDF (optional)
+- **launch:** a list of objects containing
   - **path:** relative path within the package or absolute path to robot extras launch file
+  - **package:** name of the ROS 2 package that contains the extras launch file (optional)
+  - **args:** launch arguments to pass to the launch file when it is started (optional)
 - **ros_parameters:** in YAML to pass in parameters to platform nodes. This is useful to change parameters such as the robot's velocity and acceleration.
 
 ```yaml
@@ -25,8 +26,8 @@ extras:
     package: package_name
     path: relative/path/to/urdf/in/package.urdf.xacro # or can contain /absolute/path/to/urdf.urdf.xacro
   launch:
-    package: package_name
-    path: relative/path/to/launch/in/package.launch.py
+    - package: package_name
+      path: relative/path/to/launch/in/package.launch.py
   ros_parameters: {} # node parameters, see below
 ```
 
@@ -132,8 +133,48 @@ The robot's URDF will now include the antenna, as shown in the image below:
 
 ## Extras Launch
 
-If an `extras.launch` is specified, it is launched as part of the `clearpath-platform-extras.service` job. To check the status
-of the extras launch, run
+The launch files specified in this section are started as part of the `clearpath-platform-extras.service` job. Each launch file can be specified either as an absolute path or as a relative path within a package. Additionally, launch arguments may be specified with the `args` field:
+
+```yaml
+platform:
+  extras:
+    launch:
+      - path: /absolute/path/to/some/file.launch.py
+      - path: launch/my_launch_file.launch.py
+        package: my_package
+      - path: launch/my_launch_with_args.launch.py
+        package: my_other_package
+        args:
+          spam: eggs
+          foo: bar
+```
+
+The three launches above are equivalent to the following command-line invocations:
+
+```bash
+ros2 launch /absolute/path/to/some/file.launch.py
+
+ros2 launch my_package launch/my_launch_file.launch.py
+
+ros2 launch my_other_package launch/my_launch_with_args.launch.py spam:=eggs foo:=bar
+```
+
+:::note
+
+In `2.7.x` and earlier `extras.launch` only supported a single launch file:
+
+```yaml
+platform:
+  extras:
+    path: launch/my_launch_file.launch.py
+    package: my_package
+```
+
+If your `robot.yaml` file contains the old format you will see a deprecation notice. We recommend updating your `robot.yaml` to the new format by converting `extras.launch` to a list.
+
+:::
+
+To check the status of the extras launch, run
 
 ```bash
 systemctl status clearpath-platform-extras.service
diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/system.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/system.mdx
index f61e618c5..ad0db9872 100644
--- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/system.mdx
+++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/system.mdx
@@ -121,6 +121,30 @@ servers:
     enabled: True
 ```
 
+## Bash Environment
+
+Some ROS nodes may expect additional environment variables to be set. Instead of setting these system-wide, you may instead use the `system.bash` section to define additional environment variables or source additional bash files _before_ any ROS nodes are started by the Clearpath systemd jobs.
+
+```yaml
+system:
+  bash:
+    source:
+      - /path/to/some_config.bash
+      - /path/to/another_setup.bash
+    env:
+      ADDITIONAL_ENVAR: spam
+      ANOTHER_ENVAR: eggs
+```
+
+This example will include the following in the generated `setup.bash` file used by all Clearpath systemd jobs:
+
+```bash
+source /path/to/some_config.bash
+source /path/to/another_setup.bash
+export ADDITIONAL_ENVAR="spam"
+export ANOTHER_ENVAR="eggs"
+```
+
 ## Sample
 
 <details>