Basic Joint Controller

Joint-position controller (basic_joint_controller/BasicJointController) with a three-state FSM (HOME / HOLD / MOVEJ). Optional 灵巧手 switch/percent control and optional waist lifting/turning.

Source of truth

Documented from the package READMEs only. Topics and command types are those listed there.

Repository: fiveages-sim/arms_ros2_control (controller/basic_joint_controller/)

Shared FSM types live in libraries/arms_controller_common/ (StateHome, StateHold, StateMoveJ, FSMCommandPublisher).

FSM

/fsm_command is std_msgs/Int32, not String.

Value

Action

1

Switch to HOME (only from HOLD)

2

Switch to HOLD (from HOME / MOVEJ)

4

Switch to MOVEJ (only from HOLD; canonical, same as the whole-body stack)

3

Switch to MOVEJ (legacy alias for standalone use; on mixed OCS2/WBC stacks 3 means OCS2)

switch_command_base (default 100)

(HOME) Cycle to next configuration

switch_command_base + 1 (default 101)

(HOME) Switch to configuration 0

switch_command_base + 2 (default 102)

(HOME) Switch to configuration 1

MOVEJ can only return to HOLD (2). Direct MOVEJ → HOME is rejected.

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 — interpolate to one of up to 10 preset joint configurations

  • StateHold — hold current joint positions

  • StateMoveJ — interpolate to target joints; supports trajectories and prefix-based partial control

Topics

Command topics are namespaced to the controller name (README example: /left_hand_controller/...). The table below is the package README Topic Summary, pinned at commit 9a1da3ba. How to refresh the pin (and recompute :start-line: / :end-line:): Documentation Build.

Assuming controller name my_controller, joint name j1:

Topic

Type

Requires state

Notes

/fsm_command

Int32

any

FSM state/config switching

/my_controller/target_joint_position

Float64MultiArray

MOVEJ

Direct joint targets; tanh/linear/doubles cap speed and may extend duration

/my_controller/target_joint_trajectory

JointTrajectory

MOVEJ

Multi-waypoint trajectory

/my_controller/target_command

Int32 (0/1)

MOVEJ

Hand open/close switch

/my_controller/target_percent

Float64 (0~1)

MOVEJ

Hand proportional control

/my_controller/waist_lifting

Float64

MOVEJ

Waist position delta

/my_controller/waist_lifting_pose_relative

Float64MultiArray

MOVEJ

Waist local relative [dx, dz, dphi]

/my_controller/waist_lifting_pose_absolute

Float64MultiArray

MOVEJ

Absolute [x, z, phi] (TF frames configurable)

/my_controller/waist_lifting_command

Float64

MOVEJ

Waist velocity factor

/my_controller/waist_turning_command

Float64

MOVEJ

Waist turning velocity factor

Hand target_command / target_percent need target_command_enabled. Waist topics need waist_lifting_enabled. Absolute-pose defaults match FiveAges W2 (base_footprint / body_base). README example for ARX Lift / Lift 2S: waist_lifting_type: single_joint with base_link / lift_link. Height-only commands (waist_lifting, waist_lifting_command, target_joint_position) do not use those frames.

On 分体, the body instance is typically /body_joint_controller/…. On 全身, API_REFERENCE maps the same waist names under /ocs2_wbc_controller/…. Cartesian EE */twist and */relative are not this controller — FSM and Topics. Waist pose also has a WaistLiftingPose action (…/waist_lifting_pose); Python prefers execute_waist_lifting_pose_*_action when a result is needed.

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

Argument

Default

Description

robot

fiveages_w1

Description key ({robot}_description)

type

empty

EEF / topology key (left / right / dual, or a symmetric EEF); empty means do not pass type to xacro

hardware

mock_components

gz / isaac / mock_components

enable_head

true

Head controllers

enable_body

true

Body controllers

use_rviz

true

Launch RViz

This demo does not declare left_type / right_type. Those first-class args come from create_robot_profile_launch_arguments() on OCS2 launches — OCS2 Arm Controller. Launch type is the same EEF / topology key as Naming Conventions; robot:= already selected the description package.

Build (README): colcon build --packages-up-to basic_joint_controller --symlink-install.