From 58fc7036c7b2b8d88a11f519f71b5c956b24ad2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksander=20Szyma=C5=84ski?= Date: Tue, 7 Oct 2025 18:03:44 +0200 Subject: [PATCH 1/6] bldc-motors: added initial tutorial with software sections filled MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Aleksander Szymański --- docs/leo-rover/addons/bldc-motors.mdx | 290 ++++++++++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 docs/leo-rover/addons/bldc-motors.mdx diff --git a/docs/leo-rover/addons/bldc-motors.mdx b/docs/leo-rover/addons/bldc-motors.mdx new file mode 100644 index 00000000..af6a623a --- /dev/null +++ b/docs/leo-rover/addons/bldc-motors.mdx @@ -0,0 +1,290 @@ +--- +title: BLDC motored wheels +sidebar_label: BLDC motored wheels +sidebar_position: 2 +keywords: + - bldc + - development + - cable routing + - addon +description: >- + Learn how to setup and customize Leo Rover running bldc motors. +--- + +{/* TODO: BLA BLA COŚ O TYCH SILNIKACH CHYBA CO NIE HMMM. */} + +## What to expect? + +After completing this tutorial, you will have a fully operational Leo Rover +equipped with BLDC motor-driven wheels {/* TODO: MOŻE FOTA? */} + +## Referenced products + +{/* TODO: JEŻELI BĘDZIE. */} + +## List of components + +{/* TODO: PEWNIE KOMPLET WYLISTOWAĆ TUTAJ */} + +## Mechanical integration + +{/* TODO: WIADOMKA */} + +## Software integration + +To make the process as straightforward as possible, we’ve prepared a dedicated +version of **LeoOS** that includes all the necessary software for the BLDC motor +system. +Simply download the [image](TODO), flash it onto the SD card, and insert it into +the robot. + +You can follow this guide for detailed instructions on flashing the OS image: + + + +Once the new system is installed, ensure that **LeoCore** is properly +communicating with it by updating the firmware on the board. +Follow this guide to update the firmware: + + + +After completing the firmware update, reboot the robot or restart the ROS nodes: + +```bash +ros-nodes-restart +``` + +### Configuration + +The prepared BLDC motor integration is highly configurable — you can adjust each +parameter at runtime to observe how it affects the system and the rover’s +behavior. +This part of the tutorial will guide you through accessing one of the most +convenient interfaces for configuring these parameters. + +You will need **ROS Jazzy** installed on your computer. If you don’t have ROS +installed, follow this guide: + + + +Before configuring any parameters, make sure your computer is connected to the +rover’s access point: + + + +Next, connect your local ROS environment to the one running on the robot. +To do so, source either the `/opt/ros/jazzy/setup.bash` file or the +`install/setup.bash` file from your ROS workspace (if you have one). +Then verify the connection by running: + +```bash +ros2 node list +``` + +If this command displays a list of running nodes, the connection has been +established successfully. You can now launch the configuration interface: + +```bash +rqt -s rqt_reconfigure +``` + +:::info + +If this command returns an error, the plugin might not be installed. Install it +by running: + +```bash +sudo apt install ros-jazzy-rqt-reconfigure +``` + +::: + +In the **rqt** window, select the `bldc_manager` node from the list on the left +side of the screen. You will see all available parameters that can be configured +in real time. {/* TODO: DODAĆ SCREEN JAK ZROBIE */} + +Hover your cursor over a parameter name to display its description and learn +what it controls. + +The next section provides a detailed explanation of each parameter, including +valid value ranges and usage notes. + +## Parameters + +The parameters are divided into three main groups: + +- **`node` parameters** - general settings that affect the ROS-related aspects + of the system. +- **`wheel controller` parameters** - define the BLDC motor configuration and + behavior (these apply to all motors simultaneously). +- **`robot controller` parameters** - used primarily for odometry calculations + and system timeouts. + It's recommended to leave these unchanged unless you know exactly what you're + adjusting. + +### `bldc_manager` node + +- **`mecanum_wheels`** (type: `bool`, default: `false`) + Indicates whether the rover is equipped with mecanum wheels. + When set to `true`, the robot operates in _holonomic_ motion mode. + When set to `false`, it uses _differential_ motion mode. + +- **`max_linear_velocity`** (type: `float`, default: `5.0`) + The maximum linear velocity of the robot, expressed in meters per second. + Accepted values range from **0.1 m/s** to **20.0 m/s**. + + :::info + + Keep in mind that even though the parameter accepts high values, the physical + rover may not be capable of reaching them. + + ::: + +- **`max_angular_velocity`** (type: `float`, default: `4.8`) + The maximum angular velocity of the robot, expressed in radians per second. + Accepted values range from **0.1 rad/s** to **20.0 rad/s**. + + :::info + + As with linear velocity, higher values may exceed the physical limits of the + rover's drivetrain. + + ::: + +- **`tf_frame_prefix`** (type: `string`, default: `''`) + Prefix added to the names of published TF frames. + +- **`robot_frame_id`** (type: `string`, default: `base_footprint`) + The TF frame associated with the robot base. + +- **`odom_frame_id`** (type: `string`, default: `odom`) + The TF frame associated with odometry readings. + +- **`wheel_joint_names`** (type: `string[]`, default: + `['wheel_RL_joint', 'wheel_RR_joint', 'wheel_FL_joint', 'wheel_FR_joint']`) + The names of the wheel joints used in the `joint_states` topic. + The order of names is: **rear left**, **rear right**, **front left**, **front + right**. + +- **`wheel_odom_twist_covariance_diagonal`** (type: `float[]`, default: + `[0.0001, 0, 0, 0, 0, 0.001]`) + The diagonal elements of the covariance matrix for standard wheel odometry + twist readings. + The array must contain exactly six values representing variances for **linear + x**, **linear y**, **linear z**, **angular x**, **angular y**, and **angular + z**. + +- **`wheel_odom_mecanum_twist_covariance_diagonal`** (type: `float[]`, + default: + `[0.0001, 0.0001, 0, 0, 0, 0.001]`) + The diagonal elements of the covariance matrix for mecanum wheel odometry + twist readings. + The array must contain exactly six values representing variances for **linear + x**, **linear y**, **linear z**, **angular x**, **angular y**, and **angular + z**. + +### `Wheel Controller` + +- **`max_torque`** (type: `float`, default: `1.5`) + The maximum torque that the motors can produce (in newton-meters). + +- **`pid_constants`** (type: `float[]`, default: `[0.2, 0.5, 0.0]`) + The proportional (**P**), integral (**I**), and derivative (**D**) constants + of the PID controller. + The array must contain exactly three non-negative values. + + :::warning This is one of the most critical parameters, as it significantly + affects how the rover drives. + Incorrect configuration can result in poor control, unstable motion, or even + motor damage. + + When using the **D** component, keep its value low (preferably below + `0.0001`). + A high derivative value can make the motors noisy and increase the risk of + overheating or failure. ::: + +- **`pid_integral_max`** (type: `float`, default: `20.0`) + The upper limit for the output of the integral component in the PID controller + (in radians per second). + The value must be non-negative. + +- **`profile_velocity`** (type: `float`, default: `6.0`) + The target velocity for the velocity profile motion mode (in radians per + second). + Acceptable values range from **0.0 rad/s** to **60.0 rad/s**. + +- **`profile_acceleration`** (type: `float`, default: `6.0`) + The target acceleration for the velocity profile motion mode (in radians per + second²). + Acceptable values range from **0.0 rad/s^2** to **100.0 rad/s^2**. + +- **`motion_mode`** (type: `int`, default: `0`) + The motion mode used by the motor controller. + Possible values are: + - `0` - **VELOCITY_PID** + - `1` - **VELOCITY_PROFILE** + - `2` - **IDLE** + +- **`min_velocity`** (type: `float`, default: `0.1`) + The minimum velocity for a wheel to be considered rotating (in radians per + second). + This threshold is used to detect when the rover is stationary, allowing the + system to disable motor effort to conserve power when appropriate. + +### `Robot Controller` + +- **`diff_drive/wheel_radius`** (type: `float`, default: `0.0625`) + The radius of each wheel (in meters). + Valid range: **0.01-0.2**. + Used only when the `mecanum_wheels` parameter is set to `false`. + +- **`diff_drive/wheel_separation`** (type: `float`, default: `0.358`) + The distance between the centers of the left and right wheels (in meters). + Valid range: **0.1-1.0**. + Used only when `mecanum_wheels` is `false`. + +- **`diff_drive/angular_velocity_multiplier`** (type: `float`, default: + `1.76`) + A scaling factor for angular velocity. + The angular velocity in the `cmd_vel` command is **multiplied** by this + value, + while the calculated odometry's angular velocity is **divided** by it. + Valid range: **0.01-5.0**. + Used only when `mecanum_wheels` is `false`. + +- **`mecanum/wheel_radius`** (type: `float`, default: `0.0635`) + The radius of each mecanum wheel (in meters). + Valid range: **0.01-0.2**. + Used only when `mecanum_wheels` is `true`. + +- **`mecanum/wheel_separation`** (type: `float`, default: `0.354`) + The distance between the centers of the left and right mecanum wheels (in + meters). + Valid range: **0.1-1.0**. + Used only when `mecanum_wheels` is `true`. + +- **`mecanum/wheel_base`** (type: `float`, default: `0.3052`) + The distance between the centers of the front and rear mecanum wheels (in + meters). + Valid range: **0.1-1.0**. + Used only when `mecanum_wheels` is `true`. + +- **`mecanum/angular_velocity_multiplier`** (type: `float`, default: `1.0`) + A scaling factor for angular velocity in mecanum drive mode. + The angular velocity in the `cmd_vel` command is **multiplied** by this + value, + while the odometry's angular velocity is **divided** by it. + Valid range: **0.01-5.0**. + Used only when `mecanum_wheels` is `true`. + +- **`input_timeout`** (type: `int`, default: `500`) + The timeout (in milliseconds) for `cmd_vel` messages. + The controller is disabled if no command is received within this period. + Setting this value to `0` disables the timeout. + Valid range: **0-2000**. + +- **`effort_timeout`** (type: `int`, default: `500`) + The timeout (in milliseconds) before motor effort is released. + If the robot remains stationary for this duration, motor effort is set to + zero. + Valid range: **100-2000**. From f2d76c604a4bd597428f7271297927946829f6b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksander=20Szyma=C5=84ski?= Date: Fri, 10 Oct 2025 14:24:49 +0200 Subject: [PATCH 2/6] bldc-motors: temp fix so the page builds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Aleksander Szymański --- docs/leo-rover/addons/bldc-motors.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/leo-rover/addons/bldc-motors.mdx b/docs/leo-rover/addons/bldc-motors.mdx index af6a623a..bf4e7f6a 100644 --- a/docs/leo-rover/addons/bldc-motors.mdx +++ b/docs/leo-rover/addons/bldc-motors.mdx @@ -34,8 +34,9 @@ equipped with BLDC motor-driven wheels {/* TODO: MOŻE FOTA? */} To make the process as straightforward as possible, we’ve prepared a dedicated version of **LeoOS** that includes all the necessary software for the BLDC motor -system. -Simply download the [image](TODO), flash it onto the SD card, and insert it into +system. +{/* TODO: PODMIENIĆ NA LINK DO OS */} +Simply download the image, flash it onto the SD card, and insert it into the robot. You can follow this guide for detailed instructions on flashing the OS image: From 1aa367c776018c50c3d3ff76876414be2b9d1577 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksander=20Szyma=C5=84ski?= Date: Tue, 25 Nov 2025 13:07:41 +0100 Subject: [PATCH 3/6] leo_bldc: fix TODO comments, add tutorial intro, fix used apostrophe signs and format code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Aleksander Szymański --- docs/leo-rover/addons/bldc-motors.mdx | 34 ++++++++++++++++----------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/leo-rover/addons/bldc-motors.mdx b/docs/leo-rover/addons/bldc-motors.mdx index bf4e7f6a..c4d36052 100644 --- a/docs/leo-rover/addons/bldc-motors.mdx +++ b/docs/leo-rover/addons/bldc-motors.mdx @@ -11,33 +11,39 @@ description: >- Learn how to setup and customize Leo Rover running bldc motors. --- -{/* TODO: BLA BLA COŚ O TYCH SILNIKACH CHYBA CO NIE HMMM. */} +Brushless DC (BLDC) motors offer high efficiency, smooth operation, and +excellent power density, making them a common choice in robotics and automation. +Their electronic commutation provides better control and reliability compared to +traditional brushed motors. + +In this project, we replace the stock wheel motors of our robot with more +powerful BLDC motors, resulting in significantly higher speed and improved +overall performance. This tutorial outlines the key steps and considerations +involved in integrating BLDC motors into a mobile robot platform. ## What to expect? After completing this tutorial, you will have a fully operational Leo Rover -equipped with BLDC motor-driven wheels {/* TODO: MOŻE FOTA? */} +equipped with BLDC motor-driven wheels {/* TODO: MAYBE IMAGE HERE? */} ## Referenced products -{/* TODO: JEŻELI BĘDZIE. */} +{/* TODO: IF ANY. */} ## List of components -{/* TODO: PEWNIE KOMPLET WYLISTOWAĆ TUTAJ */} +{/* TODO: LIST THE SETUP */} ## Mechanical integration -{/* TODO: WIADOMKA */} +{/* TODO */} ## Software integration -To make the process as straightforward as possible, we’ve prepared a dedicated +To make the process as straightforward as possible, we've prepared a dedicated version of **LeoOS** that includes all the necessary software for the BLDC motor -system. -{/* TODO: PODMIENIĆ NA LINK DO OS */} -Simply download the image, flash it onto the SD card, and insert it into -the robot. +system. {/* TODO: ADD LINK WITH OS IMAGE */} Simply download the image, flash it +onto the SD card, and insert it into the robot. You can follow this guide for detailed instructions on flashing the OS image: @@ -58,18 +64,18 @@ ros-nodes-restart ### Configuration The prepared BLDC motor integration is highly configurable — you can adjust each -parameter at runtime to observe how it affects the system and the rover’s +parameter at runtime to observe how it affects the system and the rover's behavior. This part of the tutorial will guide you through accessing one of the most convenient interfaces for configuring these parameters. -You will need **ROS Jazzy** installed on your computer. If you don’t have ROS +You will need **ROS Jazzy** installed on your computer. If you don't have ROS installed, follow this guide: Before configuring any parameters, make sure your computer is connected to the -rover’s access point: +rover's access point: @@ -102,7 +108,7 @@ sudo apt install ros-jazzy-rqt-reconfigure In the **rqt** window, select the `bldc_manager` node from the list on the left side of the screen. You will see all available parameters that can be configured -in real time. {/* TODO: DODAĆ SCREEN JAK ZROBIE */} +in real time. {/* TODO: ADD SCREENSHOT */} Hover your cursor over a parameter name to display its description and learn what it controls. From 1fa22a73d57ce87b630b6a73a437687a5b85369c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksander=20Szyma=C5=84ski?= Date: Tue, 25 Nov 2025 13:38:49 +0100 Subject: [PATCH 4/6] leo_bldc: add image to metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Aleksander Szymański --- docs/leo-rover/addons/bldc-motors.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/leo-rover/addons/bldc-motors.mdx b/docs/leo-rover/addons/bldc-motors.mdx index c4d36052..06b76853 100644 --- a/docs/leo-rover/addons/bldc-motors.mdx +++ b/docs/leo-rover/addons/bldc-motors.mdx @@ -9,6 +9,8 @@ keywords: - addon description: >- Learn how to setup and customize Leo Rover running bldc motors. +{/* TODO CHANGE THE PHOTO FOR MORE ACCURATE ONE*/} +image: "/img/robots/leo/leo-rover-1.9-shop.webp" --- Brushless DC (BLDC) motors offer high efficiency, smooth operation, and From 7ba2c9bde04dd28d740f4c003ff0557c323a7643 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksander=20Szyma=C5=84ski?= Date: Tue, 25 Nov 2025 13:42:26 +0100 Subject: [PATCH 5/6] leo_bldc: fix metadata comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Aleksander Szymański --- docs/leo-rover/addons/bldc-motors.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/leo-rover/addons/bldc-motors.mdx b/docs/leo-rover/addons/bldc-motors.mdx index 06b76853..23608fbe 100644 --- a/docs/leo-rover/addons/bldc-motors.mdx +++ b/docs/leo-rover/addons/bldc-motors.mdx @@ -9,8 +9,8 @@ keywords: - addon description: >- Learn how to setup and customize Leo Rover running bldc motors. -{/* TODO CHANGE THE PHOTO FOR MORE ACCURATE ONE*/} -image: "/img/robots/leo/leo-rover-1.9-shop.webp" +#{/* TODO CHANGE THE PHOTO FOR MORE ACCURATE ONE*/} +image: '/img/robots/leo/leo-rover-1.9-shop.webp' --- Brushless DC (BLDC) motors offer high efficiency, smooth operation, and From ad7c385bec22d21415260636fe304f614658ab26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksander=20Szyma=C5=84ski?= Date: Wed, 26 Nov 2025 12:20:58 +0100 Subject: [PATCH 6/6] leo_bldc: code review guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Aleksander Szymański --- docs/leo-rover/addons/bldc-motors.mdx | 47 ++++++++++++++++++++------- 1 file changed, 35 insertions(+), 12 deletions(-) diff --git a/docs/leo-rover/addons/bldc-motors.mdx b/docs/leo-rover/addons/bldc-motors.mdx index 23608fbe..294c4eaa 100644 --- a/docs/leo-rover/addons/bldc-motors.mdx +++ b/docs/leo-rover/addons/bldc-motors.mdx @@ -28,17 +28,11 @@ involved in integrating BLDC motors into a mobile robot platform. After completing this tutorial, you will have a fully operational Leo Rover equipped with BLDC motor-driven wheels {/* TODO: MAYBE IMAGE HERE? */} -## Referenced products +{/* TODO: IF ANY. ## Referenced products */} -{/* TODO: IF ANY. */} +{/* TODO: LIST THE SETUP ## List of components */} -## List of components - -{/* TODO: LIST THE SETUP */} - -## Mechanical integration - -{/* TODO */} +{/* TODO: ## Mechanical integration */} ## Software integration @@ -63,6 +57,9 @@ After completing the firmware update, reboot the robot or restart the ROS nodes: ros-nodes-restart ``` +Now you should be able to control the robot with BLDC motors in their default +configuration. + ### Configuration The prepared BLDC motor integration is highly configurable — you can adjust each @@ -76,6 +73,20 @@ installed, follow this guide: +:::tip + +If for some reason you don't want to install ROS on your machine, you can always +use the `ros2 param` CLI tool which will allow you to change parameter values - +you just have to connect to the rover through ssh. + + + +You can learn how to use `ros2 param` tool from +[this](https://docs.ros.org/en/jazzy/How-To-Guides/Using-ros2-param.html) +tutorial. + +::: + Before configuring any parameters, make sure your computer is connected to the rover's access point: @@ -202,15 +213,19 @@ The parameters are divided into three main groups: of the PID controller. The array must contain exactly three non-negative values. - :::warning This is one of the most critical parameters, as it significantly - affects how the rover drives. + :::warning + + This is one of the most critical parameters, as it significantly affects how + the rover drives. Incorrect configuration can result in poor control, unstable motion, or even motor damage. When using the **D** component, keep its value low (preferably below `0.0001`). A high derivative value can make the motors noisy and increase the risk of - overheating or failure. ::: + overheating or failure. + + ::: - **`pid_integral_max`** (type: `float`, default: `20.0`) The upper limit for the output of the integral component in the PID controller @@ -234,6 +249,14 @@ The parameters are divided into three main groups: - `1` - **VELOCITY_PROFILE** - `2` - **IDLE** + :::info + + You can read about the `VELOCITY_` modes + [here](https://mabrobotics.github.io/MD80-x-CANdle-Documentation/MD/motion.html). + In `IDLE` mode the motors don't produce any torque. + + ::: + - **`min_velocity`** (type: `float`, default: `0.1`) The minimum velocity for a wheel to be considered rotating (in radians per second).