Skip to main content

Marvin Pro ROS 2 interfaces

This page documents the customer-facing ROS 2 topics, services, input sources, and network ports for the current Marvin Pro. It applies to Apex Humble v1.0.7.74o / Jazzy v1.0.7.74t (2026-08-17) and later releases using the same interface contract. The software installed on the delivered device remains authoritative. For Skye/Luna, see Gento (Skye/Luna) ROS 2 Interfaces.

Access rules
  • Customer input topics may be published only when the required mode and arbitration source are active.
  • Read-only topics are for subscription, recording, and diagnostics only.
  • Optional topics appear only when the matching Tool, Camera, Recorder, Playback, VLA, or glove module is running.
  • The target device's ros2 topic list -t output is authoritative.

1. Namespace and Compatibility​

Robot, Teleop, QP, Planner, VLA, Recorder, and Playback run in the tj namespace by default. For example, the relative name control/joint_cmd_A resolves to /tj/control/joint_cmd_A.

source /etc/apex/apex_ros_env.sh
echo "APEX_ROS_NAMESPACE=${APEX_ROS_NAMESPACE:-tj}"
ros2 topic list | grep '^/tj/' | sort
ros2 service list | grep '^/tj/' | sort
Legacy paths are not compatible

Core control and gripper interfaces have moved to /tj. Applications that still use /control/... or /info/... may fail to find topics, command the gripper, or receive feedback.

The following interfaces remain global:

  • /hand_left/* and /hand_right/*: Wuji hands;
  • /quad_tile/jpeg/compressed: tiled JPEG camera image;
  • /recorder/set_recording: camera recording service;
  • /info/apex_package_info: Apex package version;
  • /tf, /tf_static, /rosout, and /parameter_events: ROS system interfaces.

2. Safety Requirements​

  • Start Robot in Apex and verify Ready state, operating mode, and a safe initial pose before external control.
  • Never call Home directly from the factory packing pose. After Robot is Ready, enable drag mode, manually move both arms to the standard zero pose, and disable drag mode first.
  • For direct joint commands, select Custom/User (set_input=3).
  • For Cartesian IK commands, select the VLA IK source (set_ik_input=2) and keep Joint Input on Teleop/QP (set_input=1).
  • Clear the workspace, start with small motions, and keep the emergency stop within reach.
  • Publish smooth, time-continuous targets within joint limits.
  • Switch the relevant source to Idle before stopping the publisher.
  • Never publish to topics marked read-only.
  • Inspect the installed marvin_msgs definitions with ros2 interface show before integration.

3. Input Arbitration​

The current release has two arbitration layers. Publishing an input topic alone does not command the robot.

3.1 IK source​

ValueSourceInput topic
0IdleNo IK forwarding
1VR/tj/control/ik_request/vr
2VLA / customer Cartesian input/tj/control/ik_request/vla
3Replay/tj/control/replay/ik_request

Switch with /tj/control/set_ik_input. Read the current source from /tj/info/ik_request_mux/active_source.

The status topic is read-only and cannot switch the source. See Teleoperation Modes and Input Sources for the complete switching order.

3.2 Joint source​

ValueSourceInput topic
0IdleNo joint forwarding
1Teleop / QP/tj/control/qp_controller/joint_cmd_A/B
2Planner/tj/control/joint_cmd_plan_A/B
3Custom / User/tj/control/user/joint_cmd_A/B
4Replay/tj/control/replay/joint_cmd_A/B

Switch with /tj/control/set_input. Read the current source from /tj/control/input_mode.

4. State and Feedback Topics​

Marvin Pro arrays place the seven left-arm joints before the seven right-arm joints.

TopicTypeAccessDescription
/tj/joint_statessensor_msgs/msg/JointStateRead-onlyStandard joint state, approximately 100 Hz by default
/tj/info/joint_feedbackmarvin_msgs/msg/JointfeedbackRead-onlyPosition, velocity, and torque feedback, approximately 200 Hz by default
/tj/info/arm_statestd_msgs/msg/Int16MultiArrayRead-onlyDual-arm state codes
/tj/info/robot_statestd_msgs/msg/Int16MultiArrayRead-onlyWhole-robot control state
/tj/info/robot_infomarvin_msgs/msg/RobotInfoRead-onlyRobot model and controller version
/tj/info/eef_leftgeometry_msgs/msg/PoseStampedRead-onlyLeft end-effector pose
/tj/info/eef_rightgeometry_msgs/msg/PoseStampedRead-onlyRight end-effector pose
/tj/info/wrench_leftgeometry_msgs/msg/WrenchStampedRead-onlyLeft end-effector wrench
/tj/info/wrench_rightgeometry_msgs/msg/WrenchStampedRead-onlyRight end-effector wrench
/tj/info/vr_connectedstd_msgs/msg/BoolRead-onlyHeadset connection state
/tj/info/go_home_statusstd_msgs/msg/StringRead-onlyHome / Planner state
/info/apex_package_infostd_msgs/msg/StringRead-only, globalApex package information

5. Customer Control Inputs​

TopicTypeRequirement
/tj/control/user/joint_cmd_Amarvin_msgs/msg/JointcmdArmLeft seven-joint target in rad; set_input=3
/tj/control/user/joint_cmd_Bmarvin_msgs/msg/JointcmdArmRight seven-joint target in rad; set_input=3
/tj/control/ik_request/vlamarvin_msgs/msg/IKRequestCartesian target; set_ik_input=2, set_input=1
/tj/control/gripperValueLstd_msgs/msg/Float32Left Tool running
/tj/control/gripperValueRstd_msgs/msg/Float32Right Tool running
/tj/control/footkeystd_msgs/msg/BoolOptional; only when glove_mode=true
ros2 interface show marvin_msgs/msg/JointcmdArm
ros2 interface show marvin_msgs/msg/IKRequest
ros2 topic info /tj/control/user/joint_cmd_A -v
ros2 topic info /tj/control/ik_request/vla -v

6. Robot Control Services​

ServiceTypePurpose
/tj/control/set_readystd_srvs/srv/TriggerEnter Ready state
/tj/control/set_modemarvin_msgs/srv/IntSet robot mode
/tj/control/set_dragmarvin_msgs/srv/IntSet drag/teaching mode
/tj/control/set_vel_ratiomarvin_msgs/srv/IntSet planner velocity ratio
/tj/control/clear_faultstd_srvs/srv/TriggerClear faults
/tj/control/get_motor_err_codemarvin_msgs/srv/MotorErrCodeRead motor error codes
/tj/control/set_ik_inputmarvin_msgs/srv/IntSelect IK source: 0=Idle, 1=VR, 2=VLA, 3=Replay
/tj/control/set_inputmarvin_msgs/srv/IntSelect joint source 0/1/2/3/4
/tj/control/movejmarvin_msgs/srv/MoveJPlan a 14-joint point-to-point move
/tj/control/go_homestd_srvs/srv/TriggerPlan both arms to Home; a successful response only means the trajectory started, and completion requires succeeded on /tj/info/go_home_status
/tj/control/reset_grippersstd_srvs/srv/TriggerReset/enable DM or ZY grippers when Tool is running
# Customer joint input
ros2 service call /tj/control/set_input marvin_msgs/srv/Int "{data: 3}"

# Customer Cartesian IK input
ros2 service call /tj/control/set_ik_input marvin_msgs/srv/Int "{data: 2}"
ros2 service call /tj/control/set_input marvin_msgs/srv/Int "{data: 1}"

# Stop joint forwarding
ros2 service call /tj/control/set_input marvin_msgs/srv/Int "{data: 0}"
ros2 service call /tj/control/set_ik_input marvin_msgs/srv/Int "{data: 0}"

7. Read-Only Teleop and Control-Chain Topics​

TopicTypeDescription
/tj/control/target_poseLgeometry_msgs/msg/PoseStampedVR left target pose
/tj/control/target_poseRgeometry_msgs/msg/PoseStampedVR right target pose
/tj/control/enableLstd_msgs/msg/BoolLeft teleoperation enable
/tj/control/enableRstd_msgs/msg/BoolRight teleoperation enable
/tj/control/vr_joy_Lsensor_msgs/msg/JoyRaw left controller input
/tj/control/vr_joy_Rsensor_msgs/msg/JoyRaw right controller input
/tj/control/Elbow_leftgeometry_msgs/msg/PoseStampedLeft elbow tracking pose
/tj/control/Elbow_rightgeometry_msgs/msg/PoseStampedRight elbow tracking pose
/tj/control/eef_cmd_Ageometry_msgs/msg/PoseStampedMapped left Cartesian target
/tj/control/eef_cmd_Bgeometry_msgs/msg/PoseStampedMapped right Cartesian target
/tj/control/ik_request/vrmarvin_msgs/msg/IKRequestVR IK request
/tj/control/ik_requestmarvin_msgs/msg/IKRequestArbitrated QP IK request
/tj/control/ik_cmd_Amarvin_msgs/msg/JointcmdCompatibility left IK diagnostic output; not in the primary command path
/tj/control/ik_cmd_Bmarvin_msgs/msg/JointcmdCompatibility right IK diagnostic output; not in the primary command path
/tj/info/ik_request_mux/active_sourcestd_msgs/msg/Int32Active IK source
/tj/control/ik_resultmarvin_msgs/msg/IKResultIK result
/tj/joint_state_cmdsensor_msgs/msg/JointStateFull-model QP target
/tj/control/qp_controller/joint_cmd_Amarvin_msgs/msg/JointcmdArmQP left output
/tj/control/qp_controller/joint_cmd_Bmarvin_msgs/msg/JointcmdArmQP right output
/tj/control/joint_cmd_plan_Amarvin_msgs/msg/JointcmdPlanner left output
/tj/control/joint_cmd_plan_Bmarvin_msgs/msg/JointcmdPlanner right output
/tj/control/replay/joint_cmd_Amarvin_msgs/msg/JointcmdArmPlayback left output
/tj/control/replay/joint_cmd_Bmarvin_msgs/msg/JointcmdArmPlayback right output
/tj/control/joint_cmd_Amarvin_msgs/msg/JointcmdArmFinal left command
/tj/control/joint_cmd_Bmarvin_msgs/msg/JointcmdArmFinal right command
/tj/control/input_modestd_msgs/msg/Int32Active joint source

8. End-Effector Topics​

8.1 DM / ZY grippers​

TopicTypeAccess
/tj/control/gripperValueLstd_msgs/msg/Float32Customer input
/tj/control/gripperValueRstd_msgs/msg/Float32Customer input
/tj/info/gripper_feedback_Lstd_msgs/msg/Float32MultiArrayRead-only
/tj/info/gripper_feedback_Rstd_msgs/msg/Float32MultiArrayRead-only
/tj/info/gripper_feedback_L_errstd_msgs/msg/Int32MultiArrayRead-only
/tj/info/gripper_feedback_R_errstd_msgs/msg/Int32MultiArrayRead-only

8.2 Wuji hands (global)​

TopicTypeAccess
/hand_left/joint_commandssensor_msgs/msg/JointStateCustomer input
/hand_left/joint_statessensor_msgs/msg/JointStateRead-only
/hand_right/joint_commandssensor_msgs/msg/JointStateCustomer input
/hand_right/joint_statessensor_msgs/msg/JointStateRead-only
/hand_left/joint_commands_playbacksensor_msgs/msg/JointStateRead-only
/hand_right/joint_commands_playbacksensor_msgs/msg/JointStateRead-only

9. Recorder, Playback, and Camera​

Topic / ServiceTypePurpose
/tj/recorder/statusstd_msgs/msg/Int32Recording state topic
/tj/recorder/controlmarvin_msgs/srv/JsonCommandRecording control service
/tj/control/playback_controlstd_msgs/msg/StringCompatibility playback topic
/tj/playback/controlmarvin_msgs/srv/JsonCommandMain playback service
/tj/playback_statusstd_msgs/msg/StringPlayback state topic
/tj/playback_keystd_msgs/msg/BoolPlayback key/state topic
/quad_tile/compressedsensor_msgs/msg/CompressedImageGlobal raw tiled H.264 image, subscriber-driven
/quad_tile/compressed_undistortedsensor_msgs/msg/CompressedImageGlobal calibration-processed tiled H.264 image, subscriber-driven
/quad_tile/jpeg/compressedsensor_msgs/msg/CompressedImageGlobal tiled JPEG image
/recorder/set_recordingmarvin_msgs/srv/VideoCaptureGlobal camera recording service

See Camera Configuration and ROS Interfaces for camera formats, per-camera images, and publication conditions. See Topic Whitelist Configuration and Troubleshooting for recording, playback, WebSocket, and diagnostic-log allowlists.

10. Optional VLA API​

Integrated vlahost consumes robot state, end-effector poses, gripper feedback, and /quad_tile/jpeg/compressed. It publishes actions through the customer input topics above and exposes GET /health, GET /state, WS /ws/state, POST /action, WS /ws/action, and GET /stream/quad.mjpg on TCP port 8000 by default.

11. Network Ports​

PortProtocolDirectionPurpose
9000UDPHeadset → controllerLeft teleoperation data
9001UDPHeadset → controllerRight teleoperation data
9002UDPController → headsetLeft end-effector feedback
9003UDPController → headsetRight end-effector feedback
9004UDPHeadset → controllerAuxiliary tracking data
9010TCPBidirectionalConnection, heartbeat, and handshake
8888UDPBroadcastHost/headset discovery
8000TCPBidirectionalOptional VLA HTTP/WebSocket

12. Minimum Verification​

source /etc/apex/apex_ros_env.sh
ros2 topic list | grep -E '^/tj/(joint_states|info/joint_feedback|control/joint_cmd_A|control/gripperValueL|info/gripper_feedback_L)$'
ros2 service list | grep -E '^/tj/control/(set_ready|set_input|set_ik_input|reset_grippers)$'

Gripper topics and reset_grippers are absent when Tool is stopped. /quad_tile/jpeg/compressed is absent when Camera is stopped. See the Marvin Pro ROS Topic List for the consolidated reference.

13. Topic Rate Reference​

The following values come from the current Marvin Pro source and default parameters. Timer, SDK/CAN control-loop, ROS topic, and frontend WebSocket rates are different concepts. These values are not hard real-time guarantees under Linux, DDS, or network load.

Topic / chainDesign or expected rateCondition
/tj/info/eef_left/right1000 HzTeleop running; actual rate depends on compute load
/tj/control/ik_request/vr1000 HzTeleop running with a valid VR source
/tj/control/qp_controller/joint_cmd_A/BUp to 500 HzRobot Ready, valid target, and healthy QP
/tj/control/joint_cmd_A/BNormally 500 Hz in TeleopJoint source is Teleop; follows the active source
/tj/info/joint_feedback200 HzRobot connected to MarvinSDK
/tj/info/arm_state, /tj/info/robot_state200 HzRobot connected
/tj/joint_states100 HzRobot connected
/tj/info/gripper_feedback_L/R and error topics200 HzDM/ZY Tool running
/tj/recorder/status1 HzRecorder running
/tj/playback_status10 HzPlayback running
/tj/info/robot_info0.2 HzEvery 5 seconds by default, plus one message at startup
/quad_tile/compressed, /quad_tile/compressed_undistorted, /quad_tile/jpeg/compressedDefault maximum 30 Hz, subscriber-drivenActual rate depends on valid inputs, mosaic configuration, and subscription state

Headset targets, enable states, and gripper commands follow actual UDP packets or an upstream customer program and have no universal fixed rate. Planner, Replay, event-state topics, and static TF should not be evaluated as continuous streams.

Check publisher count before measuring so merged traffic from multiple publishers is not mistaken for a single-node rate:

source /etc/apex/apex_ros_env.sh

ros2 topic info -v /tj/info/joint_feedback --no-daemon
ros2 topic info -v /tj/joint_states --no-daemon
ros2 topic info -v /tj/info/gripper_feedback_L --no-daemon

ros2 topic hz /tj/info/eef_left
ros2 topic hz /tj/control/qp_controller/joint_cmd_A
ros2 topic hz /tj/control/joint_cmd_A
ros2 topic hz /tj/info/joint_feedback
ros2 topic hz /tj/joint_states
ros2 topic hz /tj/info/gripper_feedback_L

For a formal stability test, run the arms, grippers, cameras, and recording concurrently for at least 120 seconds. Record mean Hz, period standard deviation, P95/P99, maximum gap, stream interruptions, publisher count, and CPU load.