Skip to content

Require explicit motor gains #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
s2015-turtle merged 2 commits into from
Jul 24, 2026
Merged

Require explicit motor gains #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a70710
Require explicit motor gains
s2015-turtle Jul 23, 2026
f26ab98
Merge remote-tracking branch 'origin/main' into safety/require-explic…
s2015-turtle Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,8 @@ Hardwareがactiveの間は、各モーターの動作状態を監視します。
</joint>
```

`kp`と`kd`はmodelの既定値ではなく、実際に使用されるcontrol gainであるため必須引数です。robotの機構と負荷に合わせて選定・検証してください。上記の値は使用例であり、推奨値ではありません。

`4000`は本packageの安全上の既定値であり、モーターのfactory defaultではありません。公式manualでは`0`がfactory defaultでwatchdog無効、`20000` ticksが1秒です。本packageはhostからの指令が失われた場合にモーターをResetへ移行させるため、`0`を受け付けません。

## Controllerとcommand mode
Expand Down
4 changes: 4 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,10 @@ Example:
</joint>
```

`kp` and `kd` are required macro arguments because they are active control
gains, not model defaults. Select and validate them for the robot mechanism and
load. The values above are examples only.

The common `4000` watchdog value is a package safety default, not a factory default.
The official manuals document `0` as the factory value, which disables the
watchdog, and `20000` ticks as 1 second. This package rejects zero so that loss
Expand Down
1 change: 1 addition & 0 deletions robstride_examples/CHANGELOG.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,5 @@ Changelog for package robstride_examples
Forthcoming
-----------
* Add launch, controller configuration, and RS/EduLite actuator profiles.
* Require explicit ``kp`` and ``kd`` arguments for every motor-profile macro.
* Contributors: Yamato.K
5 changes: 5 additions & 0 deletions robstride_examples/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,9 @@ find_package(ament_cmake REQUIRED)
install(DIRECTORY config description launch DESTINATION share/${PROJECT_NAME})
install(FILES LICENSE DESTINATION share/${PROJECT_NAME})

if(BUILD_TESTING)
find_package(ament_cmake_pytest REQUIRED)
ament_add_pytest_test(test_motor_profile_gains test/test_motor_profile_gains.py)
endif()

ament_package()
16 changes: 8 additions & 8 deletions robstride_examples/description/robstride_motor_profiles.xacro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,56 +18,56 @@
<state_interface name="fault"/>
</xacro:macro>

<xacro:macro name="robstride_rs00_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=30.0 kd:=1.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_rs00_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-33.0</param><param name="velocity_max">33.0</param><param name="effort_min">-14.0</param><param name="effort_max">14.0</param>
<param name="effort_wire_min">-14.0</param><param name="effort_wire_max">14.0</param><param name="kp_max">500.0</param><param name="kd_max">5.0</param>
<param name="kp">${kp}</param><param name="kd">${kd}</param><param name="direction">${direction}</param><param name="gear_ratio">${gear_ratio}</param><param name="position_offset">${position_offset}</param>
</xacro:macro>

<xacro:macro name="robstride_rs01_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=30.0 kd:=1.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_rs01_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-44.0</param><param name="velocity_max">44.0</param><param name="effort_min">-17.0</param><param name="effort_max">17.0</param>
<param name="effort_wire_min">-17.0</param><param name="effort_wire_max">17.0</param><param name="kp_max">500.0</param><param name="kd_max">5.0</param>
<param name="kp">${kp}</param><param name="kd">${kd}</param><param name="direction">${direction}</param><param name="gear_ratio">${gear_ratio}</param><param name="position_offset">${position_offset}</param>
</xacro:macro>

<xacro:macro name="robstride_rs02_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=30.0 kd:=1.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_rs02_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-44.0</param><param name="velocity_max">44.0</param><param name="effort_min">-17.0</param><param name="effort_max">17.0</param>
<param name="effort_wire_min">-17.0</param><param name="effort_wire_max">17.0</param><param name="kp_max">500.0</param><param name="kd_max">5.0</param>
<param name="kp">${kp}</param><param name="kd">${kd}</param><param name="direction">${direction}</param><param name="gear_ratio">${gear_ratio}</param><param name="position_offset">${position_offset}</param>
</xacro:macro>

<xacro:macro name="robstride_rs03_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=100.0 kd:=5.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_rs03_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-20.0</param><param name="velocity_max">20.0</param><param name="effort_min">-60.0</param><param name="effort_max">60.0</param>
<param name="effort_wire_min">-60.0</param><param name="effort_wire_max">60.0</param><param name="kp_max">5000.0</param><param name="kd_max">100.0</param>
<param name="kp">${kp}</param><param name="kd">${kd}</param><param name="direction">${direction}</param><param name="gear_ratio">${gear_ratio}</param><param name="position_offset">${position_offset}</param>
</xacro:macro>

<xacro:macro name="robstride_rs04_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=100.0 kd:=5.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_rs04_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-15.0</param><param name="velocity_max">15.0</param><param name="effort_min">-120.0</param><param name="effort_max">120.0</param>
<param name="effort_wire_min">-120.0</param><param name="effort_wire_max">120.0</param><param name="kp_max">5000.0</param><param name="kd_max">100.0</param>
<param name="kp">${kp}</param><param name="kd">${kd}</param><param name="direction">${direction}</param><param name="gear_ratio">${gear_ratio}</param><param name="position_offset">${position_offset}</param>
</xacro:macro>

<xacro:macro name="robstride_rs05_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=30.0 kd:=1.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_rs05_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-50.0</param><param name="velocity_max">50.0</param><param name="effort_min">-5.5</param><param name="effort_max">5.5</param>
<param name="effort_wire_min">-5.5</param><param name="effort_wire_max">5.5</param><param name="kp_max">500.0</param><param name="kd_max">5.0</param>
<param name="kp">${kp}</param><param name="kd">${kd}</param><param name="direction">${direction}</param><param name="gear_ratio">${gear_ratio}</param><param name="position_offset">${position_offset}</param>
</xacro:macro>

<xacro:macro name="robstride_rs06_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=30.0 kd:=1.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_rs06_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-50.0</param><param name="velocity_max">50.0</param><param name="effort_min">-36.0</param><param name="effort_max">36.0</param>
<param name="effort_wire_min">-36.0</param><param name="effort_wire_max">36.0</param><param name="kp_max">5000.0</param><param name="kd_max">100.0</param>
<param name="kp">${kp}</param><param name="kd">${kd}</param><param name="direction">${direction}</param><param name="gear_ratio">${gear_ratio}</param><param name="position_offset">${position_offset}</param>
</xacro:macro>

<xacro:macro name="robstride_edulite05_params" params="can_id direction:=1 gear_ratio:=1.0 position_offset:=0.0 kp:=30.0 kd:=1.0 can_timeout_ticks:=4000">
<xacro:macro name="robstride_edulite05_params" params="can_id kp kd direction:=1 gear_ratio:=1.0 position_offset:=0.0 can_timeout_ticks:=4000">
<param name="can_id">${can_id}</param><param name="can_timeout_ticks">${can_timeout_ticks}</param><param name="position_min">-12.566370614</param><param name="position_max">12.566370614</param>
<param name="velocity_min">-50.0</param><param name="velocity_max">50.0</param><param name="effort_min">-6.0</param><param name="effort_max">6.0</param>
<param name="effort_wire_min">-6.0</param><param name="effort_wire_max">6.0</param><param name="kp_max">500.0</param><param name="kd_max">5.0</param>
Expand Down
1 change: 1 addition & 0 deletions robstride_examples/package.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
<exec_depend>ros2_socketcan</exec_depend>
<exec_depend>velocity_controllers</exec_depend>
<exec_depend>xacro</exec_depend>
<test_depend>ament_cmake_pytest</test_depend>

<export>
<build_type>ament_cmake</build_type>
Expand Down
49 changes: 49 additions & 0 deletions robstride_examples/test/test_motor_profile_gains.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
from pathlib import Path
from xml.dom import minidom

import pytest
import xacro


PROFILE_XACRO = (
Path(__file__).resolve().parents[1] / "description" / "robstride_motor_profiles.xacro"
)
PROFILE_MACROS = [
"robstride_rs00_params",
"robstride_rs01_params",
"robstride_rs02_params",
"robstride_rs03_params",
"robstride_rs04_params",
"robstride_rs05_params",
"robstride_rs06_params",
"robstride_edulite05_params",
]


def process_profile(macro: str, arguments: str) -> None:
document = minidom.parseString(
f"""
<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="gain_test">
<xacro:include filename="{PROFILE_XACRO}"/>
<xacro:{macro} can_id="1" {arguments}/>
</robot>
"""
)
xacro.process_doc(document)


@pytest.mark.parametrize("macro", PROFILE_MACROS)
def test_profile_requires_kp(macro: str) -> None:
with pytest.raises(xacro.XacroException):
process_profile(macro, 'kd="1.0"')


@pytest.mark.parametrize("macro", PROFILE_MACROS)
def test_profile_requires_kd(macro: str) -> None:
with pytest.raises(xacro.XacroException):
process_profile(macro, 'kp="30.0"')


@pytest.mark.parametrize("macro", PROFILE_MACROS)
def test_profile_accepts_explicit_gains(macro: str) -> None:
process_profile(macro, 'kp="30.0" kd="1.0"')
16 changes: 8 additions & 8 deletions robstride_examples/test/test_motor_profiles.urdf.xacro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
<hardware>
<plugin>robstride_ros2/RobStrideSystem</plugin>
</hardware>
<joint name="rs00"><xacro:robstride_rs00_params can_id="1"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs01"><xacro:robstride_rs01_params can_id="2"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs02"><xacro:robstride_rs02_params can_id="3"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs03"><xacro:robstride_rs03_params can_id="4"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs04"><xacro:robstride_rs04_params can_id="5"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs05"><xacro:robstride_rs05_params can_id="6"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs06"><xacro:robstride_rs06_params can_id="7"/><xacro:robstride_joint_interfaces/></joint>
<joint name="edulite05"><xacro:robstride_edulite05_params can_id="8"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs00"><xacro:robstride_rs00_params can_id="1" kp="30.0" kd="1.0"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs01"><xacro:robstride_rs01_params can_id="2" kp="30.0" kd="1.0"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs02"><xacro:robstride_rs02_params can_id="3" kp="30.0" kd="1.0"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs03"><xacro:robstride_rs03_params can_id="4" kp="100.0" kd="5.0"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs04"><xacro:robstride_rs04_params can_id="5" kp="100.0" kd="5.0"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs05"><xacro:robstride_rs05_params can_id="6" kp="30.0" kd="1.0"/><xacro:robstride_joint_interfaces/></joint>
<joint name="rs06"><xacro:robstride_rs06_params can_id="7" kp="30.0" kd="1.0"/><xacro:robstride_joint_interfaces/></joint>
<joint name="edulite05"><xacro:robstride_edulite05_params can_id="8" kp="30.0" kd="1.0"/><xacro:robstride_joint_interfaces/></joint>
</ros2_control>
</robot>