Basic Joint Controller¶

带三状态 FSM（HOME / HOLD / MOVEJ）的关节位置控制器（basic_joint_controller/BasicJointController）。可选灵巧手开关/比例控制，以及可选腰部升降/转向。

事实来源

仅根据软件包 README 记录。话题和命令类型以其中列出的为准。

英文：basic_joint_controller/README.md
中文：README_zh.md

仓库： fiveages-sim/arms_ros2_control（controller/basic_joint_controller/）

共享 FSM 类型在 libraries/arms_controller_common/（StateHome、StateHold、StateMoveJ、FSMCommandPublisher）。

FSM¶

/fsm_command 是 std_msgs/Int32，不是 String。

取值	Action
`1`	切换到 HOME（仅从 HOLD）
`2`	切换到 HOLD（从 HOME / MOVEJ）
`4`	切换到 MOVEJ（仅从 HOLD；与全身栈统一的规范命令）
`3`	切换到 MOVEJ（独立使用时的旧映射；在混合 OCS2/WBC 栈上 `3` 表示 OCS2）
`switch_command_base`（默认 `100`）	（HOME）循环到下一构型
`switch_command_base + 1`（默认 `101`）	（HOME）切换到构型 0
`switch_command_base + 2`（默认 `102`）	（HOME）切换到构型 1

MOVEJ 只能回到 HOLD（2），不允许直接 MOVEJ → HOME。

ros2 topic pub --once /fsm_command std_msgs/msg/Int32 "data: 1"   # → HOME
ros2 topic pub --once /fsm_command std_msgs/msg/Int32 "data: 4"   # → MOVEJ

StateHome — 插值到最多 10 个预设关节构型之一
StateHold — 保持当前关节位置
StateMoveJ — 插值到目标关节；支持轨迹和基于前缀的局部控制

话题¶

命令话题以控制器名为命名空间（README 示例：/left_hand_controller/...）。下表是软件包 README 的 Topic Summary，钉在提交 9a1da3ba。如何刷新钉选（并重算 :start-line: / :end-line:）：文档构建。

假设控制器名为 my_controller，关节名为 j1：

话题	类型	所需状态	说明
`/fsm_command`	`Int32`	任意	FSM 状态 / 构型切换
`/my_controller/target_joint_position`	`Float64MultiArray`	MOVEJ	直接关节目标；tanh/linear/doubles 会限速并可能延长时长
`/my_controller/target_joint_trajectory`	`JointTrajectory`	MOVEJ	多路点轨迹
`/my_controller/target_command`	`Int32` (0/1)	MOVEJ	手部开合开关
`/my_controller/target_percent`	`Float64` (0~1)	MOVEJ	手部比例控制
`/my_controller/waist_lifting`	`Float64`	MOVEJ	腰部位置增量
`/my_controller/waist_lifting_pose_relative`	`Float64MultiArray`	MOVEJ	腰部局部相对 `[dx, dz, dphi]`
`/my_controller/waist_lifting_pose_absolute`	`Float64MultiArray`	MOVEJ	绝对 `[x, z, phi]`（TF 坐标系可配置）
`/my_controller/waist_lifting_command`	`Float64`	MOVEJ	腰部升降速度系数
`/my_controller/waist_turning_command`	`Float64`	MOVEJ	腰部转向速度系数

手部 target_command / target_percent 需要 target_command_enabled。腰部话题需要 waist_lifting_enabled。绝对位姿默认对齐 FiveAges W2（base_footprint / body_base）。README 中 ARX Lift / Lift 2S 示例：waist_lifting_type: single_joint，坐标系 base_link / lift_link。仅高度命令（waist_lifting、waist_lifting_command、target_joint_position）不使用这些坐标系。

在分体上，身体实例通常是 /body_joint_controller/…。在全身上，API_REFERENCE 把同样的腰部名字映射到 /ocs2_wbc_controller/…。笛卡尔末端 */twist 与 */relative 不是本控制器 — FSM 与话题。腰部位姿还有 WaistLiftingPose Action（…/waist_lifting_pose）；需要结果时 Python 更推荐 execute_waist_lifting_pose_*_action。

Demo launch (README)¶

ros2 launch basic_joint_controller demo.launch.py robot:=fiveages_w1
ros2 launch basic_joint_controller demo.launch.py robot:=fiveages_w1 enable_body:=false
ros2 launch basic_joint_controller demo.launch.py robot:=fiveages_w1 enable_head:=false

参数	默认值	说明
`robot`	`fiveages_w1`	描述键（`{robot}_description`）
`type`	空	末端 / 拓扑键（`left` / `right` / `dual`，或对称末端）；为空表示不向 xacro 传 `type`
`hardware`	`mock_components`	`gz` / `isaac` / `mock_components`
`enable_head`	`true`	头部控制器
`enable_body`	`true`	身体控制器
`use_rviz`	`true`	启动 RViz

此 demo 不声明 left_type / right_type。那些一等参数来自 OCS2 launch 上的 create_robot_profile_launch_arguments() — OCS2 Arm Controller。这里的 launch type 与命名规范的末端 / 拓扑键相同；robot:= 已经选定了描述包。

编译（README）：colcon build --packages-up-to basic_joint_controller --symlink-install。

Basic Joint Controller¶

FSM¶

话题¶

Demo launch (README)¶

相关¶