From 4612c91dcc7b01bf11568687e5516cb6c80b2747 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C5=82a=C5=BCej=20Sowa?= Date: Thu, 28 May 2026 12:52:57 +0200 Subject: [PATCH 1/6] Mention parameter overrides file --- docs/leo-rover/documentation/ros-api.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/leo-rover/documentation/ros-api.mdx b/docs/leo-rover/documentation/ros-api.mdx index ad5e2804..531f85a1 100644 --- a/docs/leo-rover/documentation/ros-api.mdx +++ b/docs/leo-rover/documentation/ros-api.mdx @@ -206,6 +206,18 @@ image: /img/robots/leo/leo-rover-1.9.webp ## Parameters +:::info + +Since LeoOS 2.5.0, all the default parameters for the standard nodes running on +the system can be overridden in the `/etc/ros/parameter_overrides.yaml` file. +Check the file for more details and examples. + +The parameters not marked as `read-only` can also be changed at runtime using +command line tools such as `ros2 param set` or graphical tools like +`rqt_reconfigure`. + +::: + #### /camera - `role` (type: `string`, read-only, default: `video`) From d3ea021a4864d83a625f5108f7eb122861071049 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C5=82a=C5=BCej=20Sowa?= Date: Thu, 28 May 2026 12:53:35 +0200 Subject: [PATCH 2/6] Don't use slashes for node names --- docs/leo-rover/documentation/ros-api.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/leo-rover/documentation/ros-api.mdx b/docs/leo-rover/documentation/ros-api.mdx index 531f85a1..9a31d928 100644 --- a/docs/leo-rover/documentation/ros-api.mdx +++ b/docs/leo-rover/documentation/ros-api.mdx @@ -218,7 +218,7 @@ command line tools such as `ros2 param set` or graphical tools like ::: -#### /camera +#### camera - `role` (type: `string`, read-only, default: `video`) @@ -255,7 +255,7 @@ documented in [picamera2 documentation (Appendix C)]. ::: -#### /camera/debayer +#### camera/debayer - `.image_color.compressed.jpeg_quality` (type: `int`, default: `80`) @@ -265,21 +265,21 @@ documented in [picamera2 documentation (Appendix C)]. The quality of the JPEG compression for the monochrome image. Range: 0-100. -#### /camera/rectify_mono +#### camera/rectify_mono - `.image_rect_color.compressed.jpeg_quality` (type: `int`, default: `80`) The quality of the JPEG compression for the rectified color image. Range: 0-100. -#### /camera/rectify_color +#### camera/rectify_color - `.image_rect.compressed.jpeg_quality` (type: `int`, default: `80`) The quality of the JPEG compression for the rectified monochrome image. Range: 0-100. -#### /firmware +#### firmware :::info @@ -348,7 +348,7 @@ The parameters for `/firmware` node can be overridden by modifying the strafing via `linear.y` commands and adjusting odometry calculations for mecanum wheel geometry. -#### /firmware_message_converter +#### firmware_message_converter - `robot_frame_id` (type: `string`, read-only, default: `base_footprint`) @@ -400,7 +400,7 @@ The parameters for `/firmware` node can be overridden by modifying the readings. The size of the array must be 3, representing the variances for the x, y and z axes. -#### /heading_controller +#### heading_controller - `linear_hold_deadband` (type: `float`, default: `0.05`) @@ -424,7 +424,7 @@ The parameters for `/firmware` node can be overridden by modifying the Maximum absolute `angular.z` command still treated as heading-hold mode. Above this value, no heading correction is applied. -#### /imu_filter +#### imu_filter - `gain_acc` (type: `float`, default: `0.01`) @@ -461,7 +461,7 @@ The parameters for `/firmware` node can be overridden by modifying the of the covariance matrix of the IMU orientation readings. The value must be greater than 0. -#### /odom_filter +#### odom_filter - `publish_tf` (type: `bool`, default: `true`) From 7fbfb620b93a1add338e15eba99dd49bbac284d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C5=82a=C5=BCej=20Sowa?= Date: Thu, 28 May 2026 12:54:30 +0200 Subject: [PATCH 3/6] Update firmware parameters --- docs/leo-rover/documentation/ros-api.mdx | 58 +++++++++++++++++------- 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/docs/leo-rover/documentation/ros-api.mdx b/docs/leo-rover/documentation/ros-api.mdx index 9a31d928..6d42c3a8 100644 --- a/docs/leo-rover/documentation/ros-api.mdx +++ b/docs/leo-rover/documentation/ros-api.mdx @@ -283,59 +283,83 @@ documented in [picamera2 documentation (Appendix C)]. :::info -The parameters for `/firmware` node can be overridden by modifying the -`/etc/ros/firmware_overrides.yaml` file. +The parameters for the `firmware` node are not meant to be changed directly by +the users. Instead, the `firmware_parameter_bridge` node provides a set of +parameters duplicating the firmware parameters, and setting those will update +the firmware parameters accordingly. ::: -- `wheels/encoder_resolution` (type: `float`, default: `878.4`) +- `wheels.encoder_resolution` (type: `float`, default: `878.4`) The resolution of the wheel encoder in counts per rotation. -- `wheels/torque_constant` (type: `float`, default: `1.17647`) +- `wheels.torque_constant` (type: `float`, default: `1.17647`) The torque (in newton-meters) produced by the wheel per 1 Ampere of winding current. -- `wheels/pid/p` (type: `float`, default: `0.0`) +- `wheels.pid.kp` (type: `float`, default: `2.64`) - The P constant of the PID regulator. + The proportional gain of the PID regulator. -- `wheels/pid/i` (type: `float`, default: `0.005`) +- `wheels.pid.ki` (type: `float`, default: `42.24`) - The I constant of the PID regulator. + The integral gain of the PID regulator. -- `wheels/pid/d` (type: `float`, default: `0.0`) +- `wheels.pid.kd` (type: `float`, default: `0.11`) - The D constant of the PID regulator. + The derivative gain of the PID regulator. -- `wheels/pwm_duty_limit` (type: `float`, default: `100.0`) +- `wheels.max_voltage` (type: `float`, default: `26.0`) - The limit of the PWM duty applied to the motor in percent. + Maximum voltage (in Volts) that can be applied to the wheels. If the battery + voltage is above this value, the controller will scale down the PWM duty cycle + to avoid applying voltage higher than this to the wheels. -- `controller/wheel_radius` (type: `float`, default: `0.0625`) +- `controller.wheel_radius` (type: `float`, default: `0.0625`) The radius of the wheel in meters. -- `controller/wheel_separation` (type: `float`, default: `0.358`) +- `controller.wheel_separation` (type: `float`, default: `0.358`) The distance (in meters) between the centers of the left and right wheels. -- `controller/wheel_base` (type: `float`, default: `0.3052`) +- `controller.wheel_base` (type: `float`, default: `0.3052`) The distance (in meters) between the centers of the rear and front wheels. -- `controller/angular_velocity_multiplier` (type: `float`, default: `1.76`) +- `controller.angular_velocity_multiplier` (type: `float`, default: `1.76`) The angular velocity in `cmd_vel` command is multiplied by this parameter and the calculated odometry has its angular velocity divided by this parameter. -- `controller/input_timeout` (type: `int`, default: `500`) +- `controller.input_timeout` (type: `int`, default: `500`) The timeout (in milliseconds) for the `cmd_vel` commands. The controller will be disabled if it does not receive a command within the specified time. If set to 0, the timeout is disabled. +- `controller.linear_acceleration` (type: `float`, default: `0.5`) + + The linear acceleration (in $\frac{m}{s^2}$) applied to the robot when + accelerating. + +- `controller.linear_deceleration` (type: `float`, default: `2.0`) + + The linear deceleration (in $\frac{m}{s^2}$) applied to the robot when + decelerating (when the absolute linear velocity is decreasing). + +- `controller.angular_acceleration` (type: `float`, default: `1.0`) + + The angular acceleration (in $\frac{rad}{s^2}$) applied to the robot when + accelerating. + +- `controller.angular_deceleration` (type: `float`, default: `4.0`) + + The angular deceleration (in $\frac{rad}{s^2}$) applied to the robot when + decelerating (when the absolute angular velocity is decreasing). + - `battery_min_voltage` (type: `float`, default: `10.0`) The voltage (in Volts) below which the battery is considered low. If the From a6a0cc837ac66c6f6466ec783aa329a1077690e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C5=82a=C5=BCej=20Sowa?= Date: Thu, 28 May 2026 12:54:43 +0200 Subject: [PATCH 4/6] Add PID gains explanation --- docs/leo-rover/documentation/ros-api.mdx | 30 ++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/leo-rover/documentation/ros-api.mdx b/docs/leo-rover/documentation/ros-api.mdx index 6d42c3a8..20dce116 100644 --- a/docs/leo-rover/documentation/ros-api.mdx +++ b/docs/leo-rover/documentation/ros-api.mdx @@ -311,6 +311,36 @@ the firmware parameters accordingly. The derivative gain of the PID regulator. +:::info + +The PID loop controls the voltage applied to the wheels based on the difference +between the target velocity and the actual velocity. + +The output voltage $U(t)$ at time $t$ is calculated as: + +$$ +U(t) = K_p \cdot e(t) + K_i \cdot \int e(t) \, dt + K_d \cdot \frac{de(t)}{dt} +$$ + +where: + +- $t$ is the time in seconds, +- $e(t)$ is the velocity error at time $t$ (target velocity - actual velocity), +- $K_p$ is the proportional gain (`wheels.pid.kp`), +- $K_i$ is the integral gain (`wheels.pid.ki`), +- $K_d$ is the derivative gain (`wheels.pid.kd`). + +For example, if the target velocity is 1.0 $\frac{m}{s}$ and the actual velocity +is 0.8 $\frac{m}{s}$, the velocity error $e(t)$ is 0.2 $\frac{m}{s}$. \ +A $K_p$ of 10.0 would contribute 2.0 $V$ to the output voltage, a $K_i$ of 50.0 +would contribute 10.0 $V$ per second of sustained error. + +The firmware employs anti-windup measures to prevent the integral term from +accumulating excessively when the output voltage is saturated at the battery +voltage. + +::: + - `wheels.max_voltage` (type: `float`, default: `26.0`) Maximum voltage (in Volts) that can be applied to the wheels. If the battery From f50cfc92a8c002f1b79bc1cd258ae5018c62bf11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C5=82a=C5=BCej=20Sowa?= Date: Thu, 28 May 2026 13:03:17 +0200 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/leo-rover/documentation/ros-api.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/leo-rover/documentation/ros-api.mdx b/docs/leo-rover/documentation/ros-api.mdx index 20dce116..f1782d27 100644 --- a/docs/leo-rover/documentation/ros-api.mdx +++ b/docs/leo-rover/documentation/ros-api.mdx @@ -213,8 +213,8 @@ the system can be overridden in the `/etc/ros/parameter_overrides.yaml` file. Check the file for more details and examples. The parameters not marked as `read-only` can also be changed at runtime using -command line tools such as `ros2 param set` or graphical tools like -`rqt_reconfigure`. +command line tools such as `ros2 param set` or graphical tools like `rqt` with +the `rqt_reconfigure` plugin (run `rqt -s rqt_reconfigure`). ::: @@ -284,9 +284,9 @@ documented in [picamera2 documentation (Appendix C)]. :::info The parameters for the `firmware` node are not meant to be changed directly by -the users. Instead, the `firmware_parameter_bridge` node provides a set of -parameters duplicating the firmware parameters, and setting those will update -the firmware parameters accordingly. +users. Instead, set the corresponding parameters on the +`firmware_parameter_bridge` node (it mirrors the firmware parameters and +forwards updates to `firmware`). ::: @@ -336,8 +336,9 @@ A $K_p$ of 10.0 would contribute 2.0 $V$ to the output voltage, a $K_i$ of 50.0 would contribute 10.0 $V$ per second of sustained error. The firmware employs anti-windup measures to prevent the integral term from -accumulating excessively when the output voltage is saturated at the battery -voltage. +accumulating excessively when the output voltage is saturated at the maximum +available/applied voltage (e.g. limited by battery voltage and/or +`wheels.max_voltage`). ::: From 2c4eb42710ee6a682ea9a2683928896d85fbd45d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C5=82a=C5=BCej=20Sowa?= Date: Thu, 28 May 2026 13:32:58 +0200 Subject: [PATCH 6/6] Clarify documentation on overriding default parameters in ROS API --- docs/leo-rover/documentation/ros-api.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/leo-rover/documentation/ros-api.mdx b/docs/leo-rover/documentation/ros-api.mdx index f1782d27..e61d7519 100644 --- a/docs/leo-rover/documentation/ros-api.mdx +++ b/docs/leo-rover/documentation/ros-api.mdx @@ -208,9 +208,9 @@ image: /img/robots/leo/leo-rover-1.9.webp :::info -Since LeoOS 2.5.0, all the default parameters for the standard nodes running on -the system can be overridden in the `/etc/ros/parameter_overrides.yaml` file. -Check the file for more details and examples. +All of the default parameters for the standard nodes running on the system can +be overridden in the `/etc/ros/parameter_overrides.yaml` file. Check the file +for more details and examples. The parameters not marked as `read-only` can also be changed at runtime using command line tools such as `ros2 param set` or graphical tools like `rqt` with