API_Desktop.md

API Documentation - Desktop

Table of Contents

Services

• LeftArmController
  • set_joint_positions
  • set_end_pose
  • get_joint_states
  • get_end_pose
  • reset
  • get_wrench_ext_world
  • get_wrench_ext_local
  • get_joint_states_stream
  • get_end_pose_stream
  • get_wrench_ext_world_stream
  • get_wrench_ext_local_stream
• LeftGripperController
  • set_position
  • get_position
  • get_position_stream
  • get_joint_states_stream
• MasterLeftArm
  • get_control_mode
  • set_control_mode
  • get_joint_states
  • get_end_pose
  • get_gripper_position
  • get_joint_states_stream
  • get_end_pose_stream
  • get_gripper_state_stream
  • set_joint_positions
  • set_end_pose
  • get_gripper_joint_states_stream
• MasterRightArm
  • get_control_mode
  • set_control_mode
  • get_joint_states
  • get_end_pose
  • get_gripper_position
  • get_joint_states_stream
  • get_end_pose_stream
  • get_gripper_state_stream
  • set_joint_positions
  • set_end_pose
  • get_gripper_joint_states_stream
• RightArmController
  • set_joint_positions
  • set_end_pose
  • get_joint_states
  • get_end_pose
  • reset
  • get_wrench_ext_world
  • get_wrench_ext_local
  • get_joint_states_stream
  • get_end_pose_stream
  • get_wrench_ext_world_stream
  • get_wrench_ext_local_stream
• RightGripperController
  • set_position
  • get_position
  • get_position_stream
  • get_joint_states_stream
• RobotStatus
  • get_robot_status
• System
  • set_work_mode
  • get_static_info
  • get_dynamic_info
  • get_model_type

Message Types

• Time
• Point
• Pose
• PoseStamped
• PoseWithCovariance
• Quaternion
• Transform
• TransformStamped
• Vector3
• Wrench
• WrenchStamped
• CompressedImage
• JointState
• TFMessage
• AudioData
• AudioDataStamped
• AudioInfo
• DownloadMeta
• DownloadRequest
• DownloadResponse
• ExecutionResult
• FileTransferMeta
• GetMapListResponse
• GetRobotStatusReply
• GetRobotStatusRequest
• GripperPosition
• JointPositions
• ManipulatorControlModeParam
• ModelTypeResult
• PingRequest
• PlayAudioResponse
• PongResponse
• PowerStatus
• RobotDynamicInfo
• RobotModeParam
• RobotRuntimeInfo
• RobotStaticInfo
• StartLocalizationParam
• StopAudioResponse
• UploadRequest

Enum Types

• RobotModelType
• RobotWorkMode
• VoicePromptPriority

---

API Services

LeftArmController

Left arm controller service

set_joint_positions

def set_joint_positions(joint_positions: JointPositions, timeout) -> ExecutionResult

Control joint angles (must set JOINT_POSITIONS mode first)

For Quanta_X2

• upper limit: [3.1067, 2.0944, 3.1067, 1.0472, 3.1067, 1.0472, 1.5708]
• lower limit: [-3.1067, -2.0944, -3.1067, -2.5307, -3.1067, -1.0472, -1.5708]

For Quanta_X1 and Desktop

• upper limit: [2.792, 3.44, 3.14, 1.57, 1.4, 1.745]
• lower limit: [-2.792, 0.0, -3.14, -1.57, -1.4, -1.745]

Parameters:

• joint_positions (JointPositions)

Returns:

• ExecutionResult

---

set_end_pose

def set_end_pose(_geometry_msgs__: _geometry_msgs__.Pose, timeout) -> ExecutionResult

Control end effector pose (must set END_POSE mode first)

For Quanta_X2

• upper limit: [5.0, 5.0, 5.0, 1.0, 1.0, 1.0, 1.0]
• lower limit: [-5.0, -5.0, -5.0, -1.0, -1.0, -1.0, -1.0]

For Quanta_X1 and Desktop

• upper limit: [5.0, 5.0, 5.0, 1.0, 1.0, 1.0, 1.0]
• lower limit: [-5.0, -5.0, -5.0, -1.0, -1.0, -1.0, -1.0]

Parameters:

• position (Point)
• orientation (Quaternion)

Returns:

• ExecutionResult

---

get_joint_states

def get_joint_states(timeout) -> _sensor_msgs__.JointState

Get joint states (positions, velocities, efforts)

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose

def get_end_pose(timeout) -> _geometry_msgs__.PoseStamped

Get end effector pose

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

reset

def reset(timeout) -> ExecutionResult

Reset arm to home position

Parameters:

• No parameters

Returns:

• ExecutionResult

---

get_wrench_ext_world

def get_wrench_ext_world(timeout) -> _geometry_msgs__.WrenchStamped

Get wrench ext world

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

get_wrench_ext_local

def get_wrench_ext_local(timeout) -> _geometry_msgs__.WrenchStamped

Get wrench ext local

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

get_joint_states_stream

def get_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Get joint states stream

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose_stream

def get_end_pose_stream(timeout) -> Iterator[_geometry_msgs__.PoseStamped]

Get end pose stream

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

get_wrench_ext_world_stream

def get_wrench_ext_world_stream(timeout) -> Iterator[_geometry_msgs__.WrenchStamped]

Get wrench ext world stream

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

get_wrench_ext_local_stream

def get_wrench_ext_local_stream(timeout) -> Iterator[_geometry_msgs__.WrenchStamped]

Get wrench ext local stream

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

LeftGripperController

set_position

def set_position(gripper_position: GripperPosition, timeout) -> ExecutionResult

Control gripper opening/closing degree

For Quanta_X2

• upper limit: 25.2
• lower limit: 0.0

For Quanta_X1

• upper limit: 4.5
• lower limit: 0.0

Parameters:

• gripper_position (GripperPosition)

Returns:

• ExecutionResult

---

get_position

def get_position(timeout) -> GripperPosition

Get current gripper state

Parameters:

• No parameters

Returns:

• GripperPosition

---

get_position_stream

def get_position_stream(timeout) -> Iterator[GripperPosition]

Get position stream

Parameters:

• No parameters

Returns:

• Iterator[[GripperPosition](#message-xrsdkgripperposition)]: Stream of GripperPosition

---

get_joint_states_stream

def get_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Get Joint state stream

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

MasterLeftArm

============================================================================

get_control_mode

def get_control_mode(timeout) -> ManipulatorControlModeParam

Parameters:

• No parameters

Returns:

• ManipulatorControlModeParam

---

set_control_mode

def set_control_mode(manipulator_control_mode_param: ManipulatorControlModeParam, timeout) -> ExecutionResult

Parameters:

• manipulator_control_mode_param (ManipulatorControlModeParam)

Returns:

• ExecutionResult

---

get_joint_states

def get_joint_states(timeout) -> _sensor_msgs__.JointState

Get joint states

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose

def get_end_pose(timeout) -> _geometry_msgs__.PoseStamped

Get End Pose

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

get_gripper_position

def get_gripper_position(timeout) -> GripperPosition

Parameters:

• No parameters

Returns:

• GripperPosition

---

get_joint_states_stream

def get_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Get joint state stream

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose_stream

def get_end_pose_stream(timeout) -> Iterator[_geometry_msgs__.PoseStamped]

Get End Pose stream

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

get_gripper_state_stream

def get_gripper_state_stream(timeout) -> Iterator[GripperPosition]

Parameters:

• No parameters

Returns:

• Iterator[[GripperPosition](#message-xrsdkgripperposition)]: Stream of GripperPosition

---

set_joint_positions

def set_joint_positions(joint_positions: JointPositions, timeout) -> ExecutionResult

Placeholder methods, backend is not supported yet.

Parameters:

• joint_positions (JointPositions)

Returns:

• ExecutionResult

---

set_end_pose

def set_end_pose(_geometry_msgs__: _geometry_msgs__.Pose, timeout) -> ExecutionResult

Control end effector pose (must set END_POSE mode first) position: [x, y, z] in meters, range: [-5.0, 5.0] orientation: [qx, qy, qz, qw] quaternion, range: [-1.0, 1.0]

Parameters:

• position (Point)
• orientation (Quaternion)

Returns:

• ExecutionResult

---

get_gripper_joint_states_stream

def get_gripper_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Backward compatibility for old API shape.

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

MasterRightArm

get_control_mode

def get_control_mode(timeout) -> ManipulatorControlModeParam

Parameters:

• No parameters

Returns:

• ManipulatorControlModeParam

---

set_control_mode

def set_control_mode(manipulator_control_mode_param: ManipulatorControlModeParam, timeout) -> ExecutionResult

Parameters:

• manipulator_control_mode_param (ManipulatorControlModeParam)

Returns:

• ExecutionResult

---

get_joint_states

def get_joint_states(timeout) -> _sensor_msgs__.JointState

Get joint states

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose

def get_end_pose(timeout) -> _geometry_msgs__.PoseStamped

Get End Pose

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

get_gripper_position

def get_gripper_position(timeout) -> GripperPosition

Parameters:

• No parameters

Returns:

• GripperPosition

---

get_joint_states_stream

def get_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Get joint state stream

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose_stream

def get_end_pose_stream(timeout) -> Iterator[_geometry_msgs__.PoseStamped]

Get End Pose stream

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

get_gripper_state_stream

def get_gripper_state_stream(timeout) -> Iterator[GripperPosition]

Parameters:

• No parameters

Returns:

• Iterator[[GripperPosition](#message-xrsdkgripperposition)]: Stream of GripperPosition

---

set_joint_positions

def set_joint_positions(joint_positions: JointPositions, timeout) -> ExecutionResult

Placeholder methods, backend is not supported yet.

Parameters:

• joint_positions (JointPositions)

Returns:

• ExecutionResult

---

set_end_pose

def set_end_pose(_geometry_msgs__: _geometry_msgs__.Pose, timeout) -> ExecutionResult

Control end effector pose (must set END_POSE mode first) position: [x, y, z] in meters, range: [-5.0, 5.0] orientation: [qx, qy, qz, qw] quaternion, range: [-1.0, 1.0]

Parameters:

• position (Point)
• orientation (Quaternion)

Returns:

• ExecutionResult

---

get_gripper_joint_states_stream

def get_gripper_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Backward compatibility for old API shape.

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

RightArmController

Right arm controller service

set_joint_positions

def set_joint_positions(joint_positions: JointPositions, timeout) -> ExecutionResult

Control joint angles (must set JOINT_POSITIONS mode first)

For Quanta_X2

• upper limit: [3.1067, 2.0944, 3.1067, 1.0472, 3.1067, 1.0472, 1.5708]
• lower limit: [-3.1067, -2.0944, -3.1067, -2.5307, -3.1067, -1.0472, -1.5708]

For Quanta_X1 and Desktop

• upper limit: [2.792, 3.44, 3.14, 1.57, 1.4, 1.745]
• lower limit: [-2.792, 0.0, -3.14, -1.57, -1.4, -1.745]

Parameters:

• joint_positions (JointPositions)

Returns:

• ExecutionResult

---

set_end_pose

def set_end_pose(_geometry_msgs__: _geometry_msgs__.Pose, timeout) -> ExecutionResult

Control end effector pose (must set END_POSE mode first)

Supports position and orientation control

Parameters:

• position (Point)
• orientation (Quaternion)

Returns:

• ExecutionResult

---

get_joint_states

def get_joint_states(timeout) -> _sensor_msgs__.JointState

Get joint states (positions, velocities, efforts)

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose

def get_end_pose(timeout) -> _geometry_msgs__.PoseStamped

Get end effector pose

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

reset

def reset(timeout) -> ExecutionResult

Reset arm to home position

Parameters:

• No parameters

Returns:

• ExecutionResult

---

get_wrench_ext_world

def get_wrench_ext_world(timeout) -> _geometry_msgs__.WrenchStamped

Get wrench ext world

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

get_wrench_ext_local

def get_wrench_ext_local(timeout) -> _geometry_msgs__.WrenchStamped

Get wrench ext local

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

get_joint_states_stream

def get_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Get joint states stream

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

get_end_pose_stream

def get_end_pose_stream(timeout) -> Iterator[_geometry_msgs__.PoseStamped]

Get end pose stream

Parameters:

• No parameters

Returns:

• PoseStamped
  • header (Header)
  • pose (Pose)

---

get_wrench_ext_world_stream

def get_wrench_ext_world_stream(timeout) -> Iterator[_geometry_msgs__.WrenchStamped]

Get wrench ext world stream

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

get_wrench_ext_local_stream

def get_wrench_ext_local_stream(timeout) -> Iterator[_geometry_msgs__.WrenchStamped]

Get wrench ext local stream

Parameters:

• No parameters

Returns:

• WrenchStamped
  • header (Header)
  • wrench (Wrench)

---

RightGripperController

set_position

def set_position(gripper_position: GripperPosition, timeout) -> ExecutionResult

Control gripper opening/closing degree

For Quanta_X2

• upper limit: 25.2
• lower limit: 0.0

For Quanta_X1

• upper limit: 4.5
• lower limit: 0.0

Parameters:

• gripper_position (GripperPosition)

Returns:

• ExecutionResult

---

get_position

def get_position(timeout) -> GripperPosition

Get current gripper state

Parameters:

• No parameters

Returns:

• GripperPosition

---

get_position_stream

def get_position_stream(timeout) -> Iterator[GripperPosition]

Get position stream

Parameters:

• No parameters

Returns:

• Iterator[[GripperPosition](#message-xrsdkgripperposition)]: Stream of GripperPosition

---

get_joint_states_stream

def get_joint_states_stream(timeout) -> Iterator[_sensor_msgs__.JointState]

Get Joint state stream

Parameters:

• No parameters

Returns:

• JointState
  • header (Header)
  • name (List[string])
  • position (List[double])
  • velocity (List[double])
  • effort (List[double])

---

RobotStatus

Real-time whole-robot status query service; client wraps JSON payload in SdkResult.

get_robot_status

def get_robot_status(fields = None, request_id = None) -> SdkResult

Query the robot's real-time status.

Parameters:

• fields - Filter list. None or [] returns everything; supports two-level paths, e.g. ["energy"] (whole category) or ["energy.battery_level"] (single field).
• request_id - Per-call trace id; auto-generated as uuid4 when omitted, echoed back in SdkResult.request_id for log correlation.

Returns:

• SdkResult: on success, data is a status dict (energy/motion/execution/safety/health); on failure, error is a standard ErrorCode

---

System

set_work_mode

def set_work_mode(robot_mode_param: RobotModeParam, timeout) -> ExecutionResult

Set Robot work mode: IDLE, INFERE, COLLECT, SDK

Parameters:

• robot_mode_param (RobotModeParam)

Returns:

• ExecutionResult

---

get_static_info

def get_static_info(timeout) -> RobotStaticInfo

Get Robot system info

Parameters:

• No parameters

Returns:

• RobotStaticInfo

---

get_dynamic_info

def get_dynamic_info(timeout) -> RobotDynamicInfo

Get Robot runtime info

Parameters:

• No parameters

Returns:

• RobotDynamicInfo

---

get_model_type

def get_model_type(timeout) -> ModelTypeResult

Get robot model type (works on all models, does not depend on application node)

Parameters:

• No parameters

Returns:

• ModelTypeResult

---

Types

Messages

Time

Fields:

Field	Type	Description
sec	int32
nanosec	uint32

---

Point

Fields:

Field	Type	Description
x	double
y	double
z	double

---

Pose

Fields:

Field	Type	Description
position	Point
orientation	Quaternion

---

PoseStamped

Fields:

Field	Type	Description
header	Header
pose	Pose

---

PoseWithCovariance

Fields:

Field	Type	Description
pose	Pose
covariance	List[double]

---

Quaternion

Fields:

Field	Type	Description
x	double
y	double
z	double
w	double

---

Transform

Fields:

Field	Type	Description
translation	Vector3
rotation	Quaternion

---

TransformStamped

Fields:

Field	Type	Description
header	Header
child_frame_id	string
transform	Transform

---

Vector3

Fields:

Field	Type	Description
x	double
y	double
z	double

---

Wrench

Fields:

Field	Type	Description
force	Vector3
torque	Vector3

---

WrenchStamped

Fields:

Field	Type	Description
header	Header
wrench	Wrench

---

CompressedImage

Fields:

Field	Type	Description
header	Header
format	string
data	bytes

---

JointState

Fields:

Field	Type	Description
header	Header
name	List[string]
position	List[double]
velocity	List[double]
effort	List[double]

---

TFMessage

Fields:

Field	Type	Description
transforms	List[TransformStamped]

---

AudioData

Fields:

Field	Type	Description
data	bytes

---

AudioDataStamped

Fields:

Field	Type	Description
audio_info	AudioInfo
audio_data	AudioData

---

AudioInfo

Fields:

Field	Type	Description
channels	uint32
sample_rate	uint32
sample_format	string
bitrate	uint32
coding_format	string
bit_depth	uint32

---

DownloadMeta

Fields:

Field	Type	Description
total_size	uint64

---

DownloadRequest

Fields:

Field	Type	Description
identifier	string

---

DownloadResponse

Fields:

Field	Type	Description
meta	DownloadMeta
chunk	bytes

---

ExecutionResult

Fields:

Field	Type	Description
is_success	bool
error_message	string
error_code	ErrorCode	Detailed error classification

---

FileTransferMeta

Fields:

Field	Type	Description
identifier	string
total_size	uint64

---

GetMapListResponse

Fields:

Field	Type	Description
header	ExecutionResult	Call status: is_success / error_code / error_message
map_list	List[string]	List of saved map names

---

GetRobotStatusReply

Fields:

Field	Type	Description
json	string	Payload (JSON string) grouped into energy/motion/execution/safety/health. Unavailable or uncaptured fields are null.

---

GetRobotStatusRequest

Fields:

Field	Type	Description
fields	List[string]	Filter field list: empty -> all fields; "energy" -> whole category; "energy.battery_level" -> single field (two-level path).

---

GripperPosition

Fields:

Field	Type	Description
header	Header
position	float

---

JointPositions

Fields:

Field	Type	Description
positions	List[double]

---

ManipulatorControlModeParam

Fields:

Field	Type	Description
mode	ManipulatorControlMode

---

ModelTypeResult

Fields:

Field	Type	Description
model_type	RobotModelType

---

PingRequest

Fields:

Field	Type	Description
payload	string

---

PlayAudioResponse

Fields:

Field	Type	Description
success	bool
message	string
play_id	uint64	equals ROS request_id; reserved 0 for "stop all"
resource_id	string	empty when cache=false

---

PongResponse

Fields:

Field	Type	Description
payload	string

---

PowerStatus

Fields:

Field	Type	Description
is_charging	bool	Whether the robot is charging
value	float	Battery level

---

RobotDynamicInfo

Fields:

Field	Type	Description
power_status	PowerStatus
runtime_info	RobotRuntimeInfo

---

RobotModeParam

Fields:

Field	Type	Description
mode	RobotWorkMode

---

RobotRuntimeInfo

Fields:

Field	Type	Description
cpu_load_percent	float
gpu_load_percent	float
memory_usage_mb	float
core_temp_celsius	float

---

RobotStaticInfo

Fields:

Field	Type	Description
model_type	RobotModelType
model	string
robot_id	uint32
device_sn	string
device_name	string
software_version	string
hardware_version	string	reserved for future use
device_ip	List[string]

---

StartLocalizationParam

Fields:

Field	Type	Description
map_name	string	Map name used for localization
use_init_pose	bool	Whether to use initial pose for localization
init_pose	Pose	Initial pose in map coordinate system, valid only when use_init_pose is true

---

StopAudioResponse

Fields:

Field	Type	Description
success	bool
message	string

---

UploadRequest

Fields:

Field	Type	Description
meta	FileTransferMeta
chunk	bytes

---

Enums

RobotModelType

Value	Description
CX001 (0)
CX002 (1)
EX001 (2)
DESKTOP (3)
EX001_MASTER (4)
EX002 (5)
INVALID_MODEL (255)

---

RobotWorkMode

Value	Description
IDLE (0)	Robot is idle
INFERE (1)	Robot is in inference mode
COLLECT (2)	Robot is in collect mode
SDK (3)	Robot is in SDK mode

---

VoicePromptPriority

Value	Description
PRIORITY_URGENT (0)
PRIORITY_HIGH (1)
PRIORITY_NORMAL (2)

---