Python API Reference - G1 Machine

• GalbotRobot: Core robot control module. Use this for robot connection, lifecycle management, joint control, sensor data queries, and hardware state monitoring.
• GalbotMotion: Motion planning and execution module. Use this for Cartesian/joint space movements, trajectory planning, inverse kinematics, and whole-body control.
• GalbotNavigation: Mobile navigation module. Use this for mobile base localization, mapping, path planning, and autonomous movement.
• GalbotPerception: On-device perception. Load vision models, run inference, and read structured results such as stereo depth; use together with GalbotRobot sensor APIs.
• Types & Enums: Data structures, enums, and status types. Use this section to look up type definitions, sensor types, error codes, and state structures used by other modules.

---

GalbotRobot

Main robot control interface for Galbot humanoid robot.

This class provides a singleton interface for controlling the Galbot robot. It supports: Joint position and trajectory control End-effector control Mobile base velocity control Sensor data acquisition Coordinate frame transformations System lifecycle management Use GalbotRobot::get_instance(MachineType) to obtain a reference for a specific platform (G1/S1/G3). All angles are in radians unless otherwise specified. All linear distances are in meters unless otherwise specified. All timestamps are in nanoseconds unless otherwise specified.

acquire_controller

def acquire_controller(controller_name: str) -> ControlStatus

Acquire hardware authority.

Requests the specified controller to take ownership of the hardware. This uses the same WBCS switch request as switch_controller.

Parameters

Name	Type	Default	Description
controller_name	str	required	Controller name, for example "left_arm_pvt_ctrl".

Returns

Type	Description
ControlStatus	ControlStatus: Result of the operation.

check_trajectory_execution_status

def check_trajectory_execution_status(
    joint_groups: Sequence[str] = []
) -> list[TrajectoryControlStatus]

Get trajectory execution status for specified joint groups.

Queries the current execution status of trajectories for the specified joint groups. This is useful for monitoring trajectory progress in non-blocking execution mode.

Parameters

Name	Type	Default	Description
joint_groups	Sequence[str]	[]	Joint groups to query (optional).

Returns

Type	Description
list[TrajectoryControlStatus]	List[TrajectoryControlStatus]: List of trajectory execution statuses.

clear_end_effector_command

def clear_end_effector_command(hold: bool = False) -> ControlStatus

Clear WBC end-effector task commands.

Clears published end-effector task trajectory commands for the WBC channel.

Parameters

Name	Type	Default	Description
hold	bool	False	If True, joints hold their current pose after clear. If False (default), joints return to the reference pose.

Returns

Type	Description
ControlStatus	ControlStatus: Command publishing result.

destroy

def destroy() -> None

Clean up system resources.

Performs final cleanup of robot control system resources including middleware connections, sensor interfaces, and communication channels. This is the last step of the shutdown sequence: request_shutdown() -> wait_for_shutdown() -> destroy().

This method should only be called once at program exit. After destroy(), the SDK enters a terminal state and cannot be re-initialized in the same process. To use the SDK again, exit the current process and launch a new one.

emergency_stop

def emergency_stop() -> ControlStatus

Robot emergency stop.

The robot's safety stop mechanism is immediately triggered via the software interface, interrupting all ongoing motion control commands and trajectory planning tasks, forcing the robot into a safe stop state. This operation takes effect immediately and has higher priority than all other control commands.

Returns

Type	Description
ControlStatus	ControlStatus: Result of the operation.

execute_joint_trajectory

def execute_joint_trajectory(trajectory: Trajectory, is_blocking: bool = True) -> ControlStatus

Execute a pre-planned joint trajectory.

Executes a trajectory consisting of waypoints with associated joint positions, velocities, and timing information. The trajectory controller interpolates between waypoints to generate smooth motion.

For standard joints (head, legs, arms), only position is effective in current versions; velocity, acceleration, and effort are currently ignored.

Parameters

Name	Type	Default	Description
trajectory	Trajectory	required	Trajectory data to execute. Either joint_groups or joint_names must be specified; returns INVALID_INPUT if both are empty.
is_blocking	bool	True	Whether to block until trajectory execution completes (optional, default: True).

Returns

Type	Description
ControlStatus	ControlStatus: Trajectory execution/sending result.

warning

Each TrajectoryPoint.joint_command_vec order MUST match the joint order defined by trajectory.joint_names or the expanded order of trajectory.joint_groups.

warning

For per-frame model inference output, prefer command streaming interfaces (set_joint_commands / set_joint_commands_batch) rather than repeatedly re-submitting full trajectories.

get_active_controller

def get_active_controller(group_name: str) -> str

Get active controller name for specified joint group.

Returns the controller last known by this SDK instance. It is initialized with the model default controller and updated after successful SDK controller management calls. If control has been released or the group has no known controller, returns "CONTROLLER_NAME_NUM".

Parameters

Name	Type	Default	Description
group_name	str	required	The joint group name to query.

Returns

Type	Description
str	str: Active controller name for the group.

get_base_velocity

def get_base_velocity() -> dict

Get current mobile base velocity.

Returns the latest base velocity in a structured form.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'linear_velocity': Linear velocity array [vx, vy, vz] in m/s - 'angular_velocity': Angular velocity array [wx, wy, wz] in rad/s Returns empty dictionary on failure.

get_bms_information

def get_bms_information() -> dict

Get BMS (Battery Management System) information.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'voltage': Battery voltage in V - 'current': Battery current in A - 'battery_level': Battery level in % - 'temperature': Battery temperature in C - 'charging_status': Charging status (bool) - 'health_status': Health status (bool) - 'capacity': Remaining capacity in Ah Returns empty dictionary on failure.

get_camera_intrinsic

def get_camera_intrinsic(camera_id: SensorType) -> dict

Get camera intrinsic parameters.

Retrieves the intrinsic parameters of the specified camera, including focal lengths, principal points, and distortion coefficients, etc.

Parameters

Name	Type	Default	Description
camera_id	SensorType	required	Camera sensor ID to query.

Returns

Type

Description

dict

dict: Dictionary containing camera intrinsic parameters. - header: Message header with timestamp and frame information - height: Image height in pixels - width: Image width in pixels - distortion_model: Distortion model, e.g., 'plumb_bob' - D: Distortion coefficients (list of float) - K: Camera intrinsic matrix (list of 9 float) - binning_x: Horizontal binning factor - binning_y: Vertical binning factor - roi: Region of interest (list of int) - camera_type: camera type Returns empty dictionary on failure.

note

The camera sensor must be enabled during initialization via enable_sensor_set

get_config

def get_config(service: ConfigService, keys: Sequence[str], use_default: bool = False) -> tuple

Read current or robot-default configuration values.

By default, values are resolved as the current user-configured values; this does not query the running service's in-memory state. When use_default is true, only the robot's built-in default configuration is read. An empty keys vector reads all registered fields applicable to the current robot.

Parameters

Name	Type	Default	Description
service	ConfigService	required	-
keys	Sequence[str]	required	-
use_default	bool	False	-

Returns

Type	Description
tuple	-

get_depth_data

def get_depth_data(camera_id: SensorType) -> dict

Get latest depth image from specified arm depth camera.

Retrieves the most recent depth frame from an arm-mounted RGB-D depth stream. Only SensorType::LEFT_ARM_DEPTH_CAMERA and SensorType::RIGHT_ARM_DEPTH_CAMERA are valid for this method.

Parameters

Name	Type	Default	Description
camera_id	SensorType	required	Depth camera sensor ID to query.

Returns

Type

Description

dict

dict: Dictionary containing the following keys: - 'header': Message header with timestamp and frame information - 'format': Depth image encoding and compression format - 'depth_scale': Depth scaling factor - 'height': Image height in pixels - 'width': Image width in pixels - 'data': Encoded depth image bytes Returns empty dictionary if the sensor type is invalid, the sensor is not enabled, or data retrieval fails.

note

The depth sensor must be included in enable_sensor_set during initialization.

note

This API is supported on G1 and S1 only. G3 does not provide arm-mounted depth cameras.

note

DepthData::data stores encoded depth image bytes. Decode the image first, then convert pixel values to meters with: depth_m = pixel_value / depth_scale. For example, depth_scale = 1000 means 1000 counts = 1.0 m.

note

A decoded pixel value of 0 usually indicates invalid or missing depth.

get_device_information

def get_device_information() -> dict

Get device information.

Retrieves basic device information including device model, serial number, firmware version, hardware version, and manufacturer. This information is used for device management, version control, system diagnostics, and device identification.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'model': Device model name or identifier (str) - 'serial_number': Unique serial number for device identification (str) - 'firmware_version': System firmware version string (str) - 'hardware_version': Hardware version or revision number (str) - 'manufacturer': Manufacturer name or company identifier (str) Returns empty dictionary on failure.

get_dexhand_state

def get_dexhand_state(end_effector: str, dexhand_type: DexHandType = ...) -> Any

Get current dexterous hand (dexhand) state.

Retrieves dexhand feedback into dexhand_state. For INSPIRE, INSPIRE_RH56DFX, INSPIRE_RH56F2, and BRAINCO, only dexhand_state.joint_state is filled and force_sensor_map is empty. For SHARPA, fills full joint state plus named force sensor data when available.

Parameters

Name	Type	Default	Description
end_effector	str	required	Dexhand name, e.g. "left_dexhand" or "right_dexhand".
dexhand_type	DexHandType	...	Dexhand model type (optional, default: INSPIRE).

Returns

Type	Description
Any	DexhandState | None: Dexhand state on success (use .joint_state; .force_sensor_map for Sharpa), otherwise None.

get_force_sensor_data

def get_force_sensor_data(
    sensor_type: GalbotOneFoxtrotSensor,
    calibrated: bool = False,
    ref_frame: str = ''
) -> dict

Get force/torque sensor data .

Retrieves the latest raw or calibrated measurements from the specified force/torque sensor. The force and torque components can optionally be rotated to the axes of a supported reference frame while retaining the sensor measurement origin.

Parameters

Name	Type	Default	Description
sensor_type	GalbotOneFoxtrotSensor	required	Force sensor enum to query.
calibrated	bool	False	Whether to read the calibrated contact wrench from WBC info. Defaults to False.
ref_frame	str	''	Frame whose axes are used for the returned force and torque. An empty string keeps the source-frame axes. Supported non-empty frames are "base_link", "torso_base_link", and the matching "left_arm_end_effector_mount_link" or "right_arm_end_effector_mount_link".

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'timestamp_ns': Timestamp in nanoseconds - 'force': Force vector dictionary with 'x', 'y', 'z' keys - 'torque': Torque vector dictionary with 'x', 'y', 'z' keys Returns empty dictionary for invalid input, unavailable data, or transform failure.

note

Raw force sensor data requires the sensor to be enabled during initialization via enable_sensor_set.

note

Coordinate conversion rotates force and torque only; it does not shift the wrench reference point or add a translation-induced moment.

get_frame_names

def get_frame_names() -> list[str]

Get all available coordinate frame names in the TF tree.

Returns

Type	Description
list[str]	list(str): List of all frame names.

get_gripper_state

def get_gripper_state(end_effector: str) -> GripperState

Get current gripper state.

Retrieves the current state of the specified gripper, including position, velocity, force, and motion-state estimation.

GripperState::is_moving is window-based: if no effective width change is detected within the internal time window, is_moving becomes false.

Parameters

Name	Type	Default	Description
end_effector	str	required	Gripper name, e.g. "left_gripper" or "right_gripper".

Returns

Type	Description
GripperState	GripperState: Gripper state information.

get_imu_data

def get_imu_data(sensor_id: SensorType) -> dict

Get IMU (Inertial Measurement Unit) sensor data.

Retrieves the latest IMU measurements including linear acceleration, angular velocity, and orientation estimation.

Parameters

Name	Type	Default	Description
sensor_id	SensorType	required	IMU sensor enum to query.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'timestamp_ns': Timestamp in nanoseconds - 'accel': Acceleration Vector3 {'x': float, 'y': float, 'z': float} - 'gyro': Gyroscope Vector3 {'x': float, 'y': float, 'z': float} - 'magnet': Magnetometer Vector3 {'x': float, 'y': float, 'z': float} Returns empty dictionary on failure.

note

The IMU sensor must be enabled during initialization via enable_sensor_set

note

Acceleration is in meters per second squared (m/s²)

note

Angular velocity is in radians per second (rad/s)

get_ir_data

def get_ir_data(camera_id: SensorType) -> dict

Get latest infrared image from specified IR camera.

Retrieves the most recent infrared image captured by the specified IR camera. Only available when ir_enabled is true in the camera parameter configuration.

Parameters

Name	Type	Default	Description
camera_id	SensorType	required	IR camera sensor ID to query. Valid values: LEFT_ARM_INFRA_CAMERA_1, LEFT_ARM_INFRA_CAMERA_2, RIGHT_ARM_INFRA_CAMERA_1, RIGHT_ARM_INFRA_CAMERA_2

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'header': Message header with timestamp and frame information - 'format': Image format, e.g., 'mono8; jpeg compressed mono8' - 'data': Compressed grayscale image binary data (bytes) Returns empty dictionary if camera is not enabled, ir_enabled is false, or no data has been received yet.

note

The IR sensor must be included in enable_sensor_set during initialization

note

ir_enabled must be true in the camera parameter topic for subscription to occur

get_joint_group_names

def get_joint_group_names() -> list[str]

Get available joint group names for the robot.

Retrieves all joint group names defined in the robot's kinematic configuration. This is useful for discovering available control groups at runtime.

Returns

Type	Description
list[str]	List[str]: Array of available joint group names, returns empty list on failure.

get_joint_names

def get_joint_names(only_active_joint: bool = True, joint_groups: Sequence[str] = []) -> list[str]

Get robot joint names by group name.

Retrieves the names of joints belonging to specified joint groups. This is useful for determining the correct ordering when setting joint positions.

Parameters

Name	Type	Default	Description
only_active_joint	bool	True	Whether to only get active joints (optional, default: True).
joint_groups	Sequence[str]	[]	Joint groups (optional).

Returns

Type	Description
list[str]	List[str]: Array of corresponding joint names.

get_joint_positions

def get_joint_positions(
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = []
) -> list[float]

Get current joint positions by group name.

Retrieves the current angular positions of joints in the specified groups.

Parameters

Name	Type	Default	Description
joint_groups	Sequence[str]	[]	Joint groups to query (optional).
joint_names	Sequence[str]	[]	Specific joint names, takes priority over joint_groups (optional).

Returns

Type	Description
list[float]	List[float]: Array of corresponding joint angles in radians. .. note:: Return order: - joint_names specified: Returns in the exact order of joint_names. - Only joint_groups specified: Returns in the order groups are defined. - Both empty (machine-dependent body-joint order): - G1: chassis, head, left_arm, right_arm, leg - S1: torso, head, left_arm, right_arm

note

Return order: joint_names specified: Returns in the exact order of joint_names. Only joint_groups specified: Returns in the order groups are defined. Both empty (machine-dependent body-joint order): G1: chassis, head, left_arm, right_arm, leg S1: torso, head, left_arm, right_arm

get_joint_states

def get_joint_states(
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = []
) -> list[JointState]

Get real-time joint states by group name.

Retrieves comprehensive state information for specified joints, including position, velocity, acceleration, effort (torque), and other feedback data.

Parameters

Name	Type	Default	Description
joint_groups	Sequence[str]	[]	Joint groups to query (optional).
joint_names	Sequence[str]	[]	Specific joint names, takes priority over joint_groups (optional).

Returns

Type	Description
list[JointState]	List[JointState]: Real-time state data for corresponding joints. .. note:: Return order: - joint_names specified: Returns in the exact order of joint_names. - Only joint_groups specified: Returns in the order groups are defined. - Both empty (machine-dependent body-joint order): - G1: chassis, head, left_arm, right_arm, leg - S1: torso, head, left_arm, right_arm

note

Return order: joint_names_vec specified: Returns in the exact order of joint_names_vec. Only joint_group_vec specified: Returns in the order groups are defined. Both empty (machine-dependent body-joint order): G1: chassis, head, left_arm, right_arm, leg S1: torso, head, left_arm, right_arm

get_lidar_data

def get_lidar_data(sensor_id: SensorType) -> dict

Get latest LiDAR point cloud data.

Retrieves the most recent 3D point cloud captured by the specified LiDAR sensor. Each point typically contains (x, y, z) coordinates and optional intensity values.

Parameters

Name	Type	Default	Description
sensor_id	SensorType	required	LiDAR sensor enum to query.

Returns

Type	Description
dict	dict: Dictionary containing point cloud data fields and binary point data. Returns empty dictionary on failure.

note

The LiDAR sensor must be enabled during initialization via enable_sensor_set

get_log_information

def get_log_information(timewindow_s: SupportsInt, log_level: LogLevel) -> dict

Get log information.

Parameters

Name	Type	Default	Description
timewindow_s	SupportsInt	required	Time window in seconds.
log_level	LogLevel	required	Log level.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'level': Log level - 'message': Log message Returns empty dictionary on failure.

get_odom

def get_odom() -> dict

Get robot odometry information.

Retrieves the robot's current pose and velocity estimates from the odometry system. Odometry typically fuses wheel encoders, IMU, and other proprioceptive sensors.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'timestamp_ns': Timestamp in nanoseconds - 'position': Position array [x, y, z] in meters - 'orientation': Quaternion array [x, y, z, w] Returns empty dictionary on failure.

get_rgb_data

def get_rgb_data(camera_id: SensorType, format: RgbOutputFormat = ..., once: bool = True) -> dict

Get one RGB image from the specified camera.

Retrieves one DMA FD camera frame and returns CPU-owned data in the requested representation. JPEG uses the Jetson hardware encoder; NV12/BGR/RGB return tightly packed CPU bytes with layout metadata in RgbData.

Parameters

Name	Type	Default	Description
camera_id	SensorType	required	Camera sensor ID to query.
format	RgbOutputFormat	...	JPEG (default), NV12, BGR, or RGB.
once	bool	True	True (default) waits for one fresh frame of the requested format and then removes that one-shot format request. The per-camera DMA-FD subscriber is started lazily and reused. False starts or reuses the persistent worker/cache and keeps the requested format active.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'header': Message header; DMA FD RGB frames have an empty frame_id. - 'format' / 'output_format': String and RgbOutputFormat representation. - 'width', 'height', 'plane_count', 'stride_bytes', 'plane_offset_bytes'. - 'data': JPEG bytes, or tightly packed NV12/BGR/RGB bytes. Returns empty dictionary on failure.

note

The camera sensor must be enabled during initialization via enable_sensor_set

note

DMA FD frame headers do not provide frame_id. For RGB DMA output, use get_camera_intrinsic() / camera_info for frame metadata.

get_sensor_extrinsic

def get_sensor_extrinsic(sensor_id: SensorType, reference_frame: str = 'base_link') -> tuple

Get sensor extrinsic parameters.

Retrieves the extrinsic parameters of the specified sensor, including rotation and translation vectors relative to the robot's base frame.

Parameters

Name	Type	Default	Description
sensor_id	SensorType	required	Sensor enum to query.
reference_frame	str	'base_link'	Name of the reference coordinate frame (frame to transform from). Default is "base_link".

Returns

Type	Description
tuple	tuple(List[float], int): Transform [x, y, z, qx, qy, qz, qw] and timestamp. Returns empty list on failure.

note

The sensor must be enabled during initialization via enable_sensor_set

get_suction_cup_state

def get_suction_cup_state(end_effector: str) -> SuctionCupState

Get current suction cup state.

Retrieves the current state of the specified suction cup, including activation status and vacuum pressure measurements.

Parameters

Name	Type	Default	Description
end_effector	str	required	Suction cup name, e.g. "left_suction_cup" or "right_suction_cup".

Returns

Type	Description
SuctionCupState	SuctionCupState: Suction cup state information.

get_synced_observation

def get_synced_observation(
    cameras: Sequence[SensorType],
    with_joint_state: bool = True
) -> SyncedObservation

Get synchronized observation aligned by camera timestamp.

Uses the first sensor in cameras as anchor. The anchor camera takes latest frame, other cameras are matched by nearest-neighbor timestamp in internal buffers. If with_joint_state is true, returns nearest-neighbor joint state by same anchor timestamp. RGB entries use CPU-owned NV12 data in synchronization mode so all camera acquisition timestamps can remain aligned without waiting for serialized JPEG encoding. The call waits up to one second for an initially empty requested camera history. Each entry in returned joint_state->joint_state_vec includes joint_name so callers can identify the semantic meaning of each joint sample.

Parameters

Name	Type	Default	Description
cameras	Sequence[SensorType]	required	Cameras to synchronize. First item is anchor.
with_joint_state	bool	True	Whether to include nearest-neighbor joint state.

Returns

Type	Description
SyncedObservation	SyncedObservation | None: - rgb_data_map: dict[SensorType, RgbData] containing NV12 frames - depth_data_map: dict[SensorType, DepthData] - joint_state: JointStateMessage | None The call waits up to one second for an initially empty requested camera history and returns None on invalid input or unavailable data.

note

This is software timestamp alignment rather than hardware-trigger synchronization. The nearest-neighbor lookup does not enforce a maximum timestamp difference; callers with strict synchronization requirements should validate the returned timestamps.

get_transform

def get_transform(
    target_frame: str,
    source_frame: str,
    timestamp_ns: SupportsInt = 0,
    timeout_ms: SupportsInt = 100
) -> tuple

Query coordinate frame transformation (TF)

Queries the transformation between two coordinate frames in the robot's TF tree. This is used for converting poses and positions between different reference frames (e.g., from camera frame to base frame, from end-effector to world frame).

Parameters

Name	Type	Default	Description
target_frame	str	required	Target coordinate frame (e.g., map, base_link, imu_base_link; actual list is from get_frame_names()).
source_frame	str	required	Source coordinate frame (e.g., map, base_link, imu_base_link; actual list is from get_frame_names()).
timestamp_ns	SupportsInt	0	Desired transform timestamp in nanoseconds, 0 for latest (optional, default: 0).
timeout_ms	SupportsInt	100	Query timeout in milliseconds (optional, default: 100).

Returns

Type	Description
tuple	tuple(List[float], int): Transform matrix list and timestamp. Returns empty list on failure.

get_ultrasonic_data

def get_ultrasonic_data(ultrasonic_type: UltrasonicType) -> dict

Get distance measurement from specified ultrasonic sensor.

Retrieves the latest distance measurement from one of the ultrasonic range sensors. The robot typically has multiple ultrasonic sensors arranged around its perimeter.

Parameters

Name	Type	Default	Description
ultrasonic_type	UltrasonicType	required	Ultrasonic sensor enum to query.

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'timestamp_ns': Timestamp in nanoseconds - 'distance': Distance value in meters Returns empty dictionary on failure.

note

The ultrasonic sensor must be enabled during initialization via enable_sensor_set

get_volume

def get_volume() -> float

Get current system global volume value.

Returns

Type	Description
float	float: Current volume value, range 0.0 to 100.0.

get_wbc_end_effector_poses

def get_wbc_end_effector_poses() -> dict[str, list[float]]

Get WBC end effector poses.

Retrieves the current poses of WBC end effectors (left arm, right arm, head).

Returns

Type	Description
dict[str, list[float]]	dict: Pose vectors [x, y, z, qx, qy, qz, qw] per key, or empty lists if unavailable.

init

def init(enable_sensor_set: Set[SensorType] = ..., enable_sync_mode: bool = False) -> bool

Initialize the robot control system.

Initializes the robot hardware communication, middleware, and sensor interfaces. To optimize resource usage, only sensors specified in the enable_sensor_set will be initialized and available for data reading.

This method should only be called once at program startup. Calling it multiple times without calling destroy() will not error, but only the first call has effect.

Parameters

Name	Type	Default	Description
enable_sensor_set	Set[SensorType]	...	Set of sensors to enable. Empty set uses default sensors.
enable_sync_mode	bool	False	Enable internal sync buffers for timestamp-aligned observation APIs.

Returns

Type	Description
bool	bool: True if initialization succeeded; False otherwise.

is_running

def is_running() -> bool

Check if the robot control system is running.

Queries whether the robot control system is still active or if a shutdown signal (e.g., SIGINT, SIGTERM) has been received.

Returns

Type	Description
bool	bool: True if system is running, False if shutdown signal captured and preparing to shutdown.

publish_target

def publish_target(target: SingoriXTarget) -> ControlStatus

Publish a raw SingoriXTarget through the WBC publish channel.

This is the advanced high-frequency path. Construct a SingoriXTarget directly, then call this interface to send it to the low-level controller without waiting for a service response. The SDK performs only basic structural validation.

Parameters

Name	Type	Default	Description
target	SingoriXTarget	required	SDK mirror target containing group-space and/or task-space trajectories.

Returns

Type	Description
ControlStatus	ControlStatus: Local validation / publish result.

release_controller

def release_controller(group_name: str = 'all') -> ControlStatus

Release hardware authority.

Yields control of the hardware, freeing the joints. Opposite of acquire_controller. Implicitly stops execution if running.

Parameters

Name	Type	Default	Description
group_name	str	'all'	Name of the joint group (default: "all").

Returns

Type	Description
ControlStatus	ControlStatus: Result of the operation.

reload_controller

def reload_controller(group_name: str = 'all') -> ControlStatus

Reload a controller.

Reinitializes the controller. Equivalent to a full restart cycle: stop -> reset -> start. Useful for error recovery or applying configuration changes.

Parameters

Name	Type	Default	Description
group_name	str	'all'	Name of the joint group (default: "all").

Returns

Type	Description
ControlStatus	ControlStatus: Result of the operation.

request_shutdown

def request_shutdown() -> None

Request system shutdown.

Sends a shutdown signal to initiate graceful system shutdown. This triggers registered exit callbacks and begins resource cleanup. Call this as the first step of the shutdown sequence: request_shutdown() -> wait_for_shutdown() -> destroy().

request_target

def request_target(target: SingoriXTarget) -> ErrorInfo

Request execution of a raw SingoriXTarget through the WBC service channel.

This is the advanced request path. The SDK performs request-side runtime error screening, sends the target through the middleware client, and returns the ErrorInfo service payload. A return value of None means the client was unavailable, disconnected, timed out, or returned an empty response.

Parameters

Name	Type	Default	Description
target	SingoriXTarget	required	SDK mirror target containing group-space and/or task-space trajectories.

Returns

Type	Description
ErrorInfo	ErrorInfo | None: Error response payload or None when no valid response was received.

resume_from_emergency_stop

def resume_from_emergency_stop() -> ControlStatus

Robot emergency stop recovery.

After confirming that the safety conditions are met, deactivate the robot's software emergency stop, restoring the robot from a safe stop state to a controllable state and re-enabling all control-related functions. Before resuming, the user must ensure that all safety conditions are met.

Returns

Type	Description
ControlStatus	ControlStatus: Result of the operation.

set_base_pose

def set_base_pose(
    base_pose: Pose,
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

Set base pose command using Pose.

Parameters

Name	Type	Default	Description
base_pose	Pose	required	Target base pose.
is_blocking	bool	True	Whether to block until command execution completes (optional, default: True).
timeout_s	SupportsFloat	15.0	Blocking timeout in seconds (optional, default: 15.0).

Returns

Type	Description
ControlStatus	ControlStatus: Command sending result.

set_base_pose

def set_base_pose(
    x: SupportsFloat,
    y: SupportsFloat,
    yaw: SupportsFloat,
    frame_id: str = 'rel(0)',
    reference_frame_id: str = 'odom',
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

Set base pose command with frame ids.

Parameters

Name	Type	Default	Description
x	SupportsFloat	required	Target x position.
y	SupportsFloat	required	Target y position.
yaw	SupportsFloat	required	Target yaw (rad).
frame_id	str	'rel(0)'	Frame id. Current recommended value: "rel(0)", which means the x/y/yaw target is interpreted relative to the current base pose. "base_link", "odom", and "map" are retained for compatibility, but are not recommended for current use and may be changed or removed in a future update. Default "rel(0)".
reference_frame_id	str	'odom'	Reference frame id ("odom"/"map"). Default "odom".
is_blocking	bool	True	Whether to block until command execution completes (optional, default: True).
timeout_s	SupportsFloat	15.0	Blocking timeout in seconds (optional, default: 15.0).

Returns

Type	Description
ControlStatus	ControlStatus: Command sending result.

set_base_pose

def set_base_pose(
    x: SupportsFloat,
    y: SupportsFloat,
    yaw: SupportsFloat,
    frame_id: str,
    reference_frame_id: str,
    time_from_start_s: SupportsFloat,
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

Set base pose (x, y, yaw) with explicit interpolation time.

Parameters

Name	Type	Default	Description
x	SupportsFloat	required	Target x position (meters).
y	SupportsFloat	required	Target y position (meters).
yaw	SupportsFloat	required	Target yaw (radians).
frame_id	str	required	Frame id of target. Current recommended value: "rel(0)", which means the x/y/yaw target is interpreted relative to the current base pose. "base_link", "odom", and "map" are retained for compatibility, but are not recommended for current use and may be changed or removed in a future update.
reference_frame_id	str	required	Reference frame id ("odom"/"map").
time_from_start_s	SupportsFloat	required	Chassis pose interpolation time (seconds).
is_blocking	bool	True	Whether to block until command execution completes (optional, default: True).
timeout_s	SupportsFloat	15.0	Request timeout in seconds (optional, default: 15.0).

Returns

Type	Description
ControlStatus	ControlStatus: Command sending result.

set_base_velocity

def set_base_velocity(
    linear_velocity: list[float],
    angular_velocity: list[float],
    duration_s: SupportsFloat = 0.0
) -> ControlStatus

Set mobile base velocity command.

Commands the robot's mobile base to move with specified linear and angular velocities. Velocities are expressed in the robot's base frame coordinate system.

Parameters

Name	Type	Default	Description
linear_velocity	list[float]	required	Linear velocity command [vx, vy, vz] in m/s.
angular_velocity	list[float]	required	Angular velocity command [wx, wy, wz] in rad/s.
duration_s	SupportsFloat	0.0	Velocity publishing window in seconds (optional, default: 0.0). Zero publishes once. Positive values block this calling thread, publishing immediately and then at 10 Hz until the window ends. Negative, non-finite, or unrepresentable durations are invalid.

Returns

Type	Description
ControlStatus	ControlStatus: SUCCESS when publishing completes (not confirmation of a stopped base), INVALID_INPUT for invalid input, STOPPED_UNREACHED on SDK shutdown, or the initialization/controller/communication/fault/publishing error.

note

No stop command is sent on expiry or early exit. Actual stopping depends on the underlying watchdog and braking; SUCCESS does not mean the base has stopped.

note

The window starts after the first successful publish. Controller switching and publishing overhead add to call latency. Waiting releases the CPU; Python releases the GIL.

note

Do not issue concurrent base commands during this call; other commands do not cancel this publishing loop. For caller-controlled stopping, use single-publish mode.

set_config

def set_config(service: ConfigService, fields: Sequence[ConfigItem]) -> ControlStatus

Set one or more configuration fields for a service.

If any field in fields is invalid, none of it takes effect and this call returns ControlStatus::INVALID_INPUT.

This call reports only a single aggregate status; it does not return which field(s) failed or why. Check the log output when this call does not return SUCCESS.

Parameters

Name	Type	Default	Description
service	ConfigService	required	Which service's configuration to edit.
fields	Sequence[ConfigItem]	required	Fields to set, addressed by ConfigItem.key (an SDK-defined friendly field identifier; see each service's field registry).

Returns

Type	Description
ControlStatus	ControlStatus: - SUCCESS if every field validated and was written. - INVALID_INPUT if scene resolution or field validation failed (in this case none of the fields were written). - DATA_FETCH_FAILED / PUBLISH_FAIL on read/write RPC failure. - FAULT for an unimplemented service.

note

A successful call only persists the configuration; it does not take effect until the device is restarted and the owning service reloads it.

set_dexhand_command

def set_dexhand_command(
    end_effector: str,
    dexhand_command: Sequence[JointCommand],
    dexhand_type: DexHandType = ...,
    is_blocking: bool = True
) -> ControlStatus

Control dexhand with joint commands.

Commands the dexhand with a vector of joint commands (position, velocity, effort, etc.).

Parameters

Name	Type	Default	Description
end_effector	str	required	Dexhand name, e.g. "left_dexhand" or "right_dexhand".
dexhand_command	Sequence[JointCommand]	required	Joint command list for the dexhand.
dexhand_type	DexHandType	...	Dexhand model type (optional, default: INSPIRE).
is_blocking	bool	True	Whether to block until action completes (optional, default: True).

Returns

Type	Description
ControlStatus	ControlStatus: Command execution/sending result.

set_end_effector_command

def set_end_effector_command(
    poses: Sequence[list[float]],
    end_effector_frames: Sequence[str],
    reference_frames: Sequence[str] = []
) -> ControlStatus

Set WBC end-effector pose commands for high-frequency real-time control (task trajectory publish).

Each row of poses is [x, y, z, qx, qy, qz, qw] (meters, quaternion xyzw). poses and end_effector_frames must have equal length.

Parameters

Name	Type	Default	Description
poses	Sequence[list[float]]	required	One pose per end effector; each row is [x, y, z, qx, qy, qz, qw] (meters, quaternion xyzw).
end_effector_frames	Sequence[str]	required	Target frame id per pose (e.g. link names).
reference_frames	Sequence[str]	[]	Reference frame per pose. Omit or pass [] to use "world" for every pose. Otherwise length must match poses. Common values: "world" (default)

Returns

Type	Description
ControlStatus	ControlStatus: Command publishing result.

set_gripper_command

def set_gripper_command(
    end_effector: str,
    width_m: SupportsFloat,
    velocity_mps: SupportsFloat = 0.03,
    effort: SupportsFloat = 5,
    is_blocking: bool = True
) -> ControlStatus

Control gripper opening width and force.

Commands the gripper to move to a specified opening width with controlled velocity and maximum gripping force.

Parameters

Name	Type	Default	Description
end_effector	str	required	Gripper name, e.g. "left_gripper" or "right_gripper".
width_m	SupportsFloat	required	Target gripper width in meters. G1 gripper width range is 0 to 0.12 m. S1 long-stroke gripper width range is 0.007 to 0.11 m. S1 short-stroke gripper width range is 0.007 to 0.076 m.
velocity_mps	SupportsFloat	0.03	Gripper motion speed in m/s (optional, default: 0.03). The value range is greater than 0 and less than or equal to 0.2 m/s.
effort	SupportsFloat	5	Gripper effort in Nm (optional, default: 5). The value range is greater than 0 and less than or equal to 100.
is_blocking	bool	True	Whether to block until action completes (optional, default: True).

Returns

Type	Description
ControlStatus	ControlStatus: Command execution/sending result.

set_joint_commands

def set_joint_commands(
    joint_commands: Sequence[JointCommand],
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = [],
    time_from_start_s: SupportsFloat = 0.0
) -> ControlStatus

Set low-level joint commands for high-frequency streaming control.

Suitable for high-frequency command streaming (for example, per-frame model inference output).

This API does not interpolate from the current/start position to the first target. The controller drives joints toward each commanded target as quickly as possible.

For standard joints (head, legs, arms), only JointCommand::position is effective in current versions; velocity, acceleration, and effort are currently ignored.

For gripper joints, the position field represents gripper width and both velocity and effort fields are supported and effective.

Parameters

Name	Type	Default	Description
joint_commands	Sequence[JointCommand]	required	List of joint commands to control.
joint_groups	Sequence[str]	[]	Joint groups to control. Must not be empty if joint_names is also empty.
joint_names	Sequence[str]	[]	Specific joint names, takes priority over joint_groups. Must not be empty if joint_groups is also empty.
time_from_start_s	SupportsFloat	0.0	Execution will begin after time_start_s seconds.(optional, default: 0.0).

Returns

Type	Description
ControlStatus	ControlStatus: Result of command execution.

warning

Especially on the first command, avoid a large gap between current and target joint angles. Large jumps may cause excessively fast motion and safety risk.

set_joint_commands_batch

def set_joint_commands_batch(trajectory: Trajectory) -> ControlStatus

Set joint commands in batch mode (non-blocking)

Sets multiple joint command trajectory points in real-time control mode, supporting one-time submission of trajectory control commands for multiple time points. Provides a non-blocking high-frequency trajectory execution interface. Similar to set_joint_commands but supports batch trajectory control, suitable for scenarios such as VLA inference batch output.

Parameters

Name	Type	Default	Description
trajectory	Trajectory	required	Trajectory data structure containing waypoints with joint commands. Either joint_groups or joint_names must be specified; returns INVALID_INPUT if both are empty. Each TrajectoryPoint contains time_from_start and a list of JointCommand. JointCommand includes position (rad), velocity (rad/s), acceleration (rad/s²), effort (N·m), Kp (position gain), and Kd (velocity gain).

Returns

Type	Description
ControlStatus	ControlStatus: Command submission result. Returns immediately without waiting for execution completion (non-blocking).

warning

Each TrajectoryPoint.joint_command_vec order MUST match the joint order defined by trajectory.joint_names or the expanded order of trajectory.joint_groups.

set_joint_positions

def set_joint_positions(
    joint_positions: list[float],
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = [],
    is_blocking: bool = True,
    speed_rad_s: SupportsFloat = 0.2,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

Set target joint positions for specified joint groups by name (for low-frequency keyframe/posture transitions)

Commands the robot to move specified joints to target positions. The motion is executed as a smooth trajectory with configurable speed limits.

Parameters

Name	Type	Default	Description
joint_positions	list[float]	required	Array of joint angles in radians.
joint_groups	Sequence[str]	[]	Joint groups to control. Must not be empty if joint_names is also empty.
joint_names	Sequence[str]	[]	Specific joint names, takes priority over joint_groups. Must not be empty if joint_groups is also empty.
is_blocking	bool	True	Whether to block until command execution completes (optional, default: True).
speed_rad_s	SupportsFloat	0.2	Maximum joint speed in rad/s (optional, default: 0.2).
timeout_s	SupportsFloat	15.0	Maximum blocking wait time in seconds (optional, default: 15.0).

Returns

Type	Description
ControlStatus	ControlStatus: Execution result status.

warning

This API is not suitable for high-frequency frame-by-frame model inference control. Each call creates a new interpolation goal, and continuous calls can cause lag or discontinuous motion. If your task is model-inference command streaming, use set_joint_commands or set_joint_commands_batch instead.

set_leg_height

def set_leg_height(
    link_height: SupportsFloat,
    duration: SupportsFloat = 4.0,
    is_blocking: bool = False,
    timeout_s: SupportsFloat = -1.0
) -> ControlStatus

Set the G1 or G3 robot leg height.

Switches the leg group to the leg height controller and asynchronously publishes a smooth motion target for head_base_link in base_link. The supported target range is [0.96, 1.54] m and the supported duration range is [0, 60] s. A duration of 0 requests the fastest motion and should be used with caution. This method returns after publishing the target by default. In blocking mode, it waits for the matching leg_height task to report target_finished, while monitoring runtime errors and leg sensor availability.

Parameters

Name	Type	Default	Description
link_height	SupportsFloat	required	Target Z coordinate of head_base_link in base_link, in meters.
duration	SupportsFloat	4.0	Requested minimum motion duration in seconds (default: 4.0). If too short, the server extends the actual duration to satisfy its velocity, acceleration, and jerk limits.
is_blocking	bool	False	Whether to wait for the motion to finish (default: False).
timeout_s	SupportsFloat	-1.0	Blocking timeout; <= 0 uses duration + 8 seconds (default: -1.0).

Returns

Type	Description
ControlStatus	ControlStatus: Publish result, or completed motion result in blocking mode.

note

The current height can be read from the z component returned by get_transform("base_link", "head_base_link").

set_suction_cup_command

def set_suction_cup_command(end_effector: str, activate: bool) -> ControlStatus

Control suction cup activation state.

Activates or deactivates the specified suction cup end-effector.

Parameters

Name	Type	Default	Description
end_effector	str	required	Suction cup name, e.g. "left_suction_cup" or "right_suction_cup".
activate	bool	required	Whether to activate the suction cup.

Returns

Type	Description
ControlStatus	ControlStatus: Command sending result.

set_volume

def set_volume(volume: SupportsFloat) -> bool

Set system global volume value.

Parameters

Name	Type	Default	Description
volume	SupportsFloat	required	Target volume value, range 0.0 to 100.0.

Returns

Type	Description
bool	bool: Returns the volume setting result. True indicates the volume was set successfully, False indicates the volume setting failed.

start_controller

def start_controller(group_name: str = 'all') -> ControlStatus

Start controller execution.

Activates the controller to begin sending commands. Opposite of stop_controller. Requires prior hardware authority (acquire).

Parameters

Name	Type	Default	Description
group_name	str	'all'	Name of the joint group (default: "all").

Returns

Type	Description
ControlStatus	ControlStatus: Result of the operation.

start_microphone_stream_input

def start_microphone_stream_input(
    callback: Callable,
    chunk_size: SupportsInt = 2560,
    use_raw_audio: bool = False
) -> str

Start microphone streaming audio input.

Parameters

Name	Type	Default	Description
callback	Callable	required	Audio data callback function with signature: void(dict audio_data). The audio_data dict fields (see AudioData): - 'header' (dict): Message header. - 'timestamp_ns' (int): Data acquisition timestamp (nanoseconds since epoch). - 'frame_id' (str): Stream or source frame identifier. - 'type' (str): Audio data type identifier. Possible values: - 'waken_up': Wake-up event; format is 'json'; data is a UTF-8 JSON string. - 'denoise_chunk': Denoised audio chunk; format is 'pcm'; data is PCM binary. - 'vad_begin': VAD start marker; data is empty. - 'vad_chunk': Audio during VAD; format is 'pcm'; data is PCM binary. - 'vad_end': VAD end marker; data is empty. - 'format' (str): How to interpret 'data': - 'pcm': 16000 Hz, 16-bit, mono PCM. - 'json': UTF-8 encoded JSON text. - 'data' (bytes): Binary payload. For 'pcm', each 80 ms chunk is 2560 bytes; for 'json', length varies or may be empty for marker-only messages.
chunk_size	SupportsInt	2560	Audio data chunk size in bytes, default value 2560. Dynamic configuration not supported yet
use_raw_audio	bool	False	Whether to use raw audio, default false. Dynamic configuration not supported yet.

Returns

Type	Description
str	str: Stream ID used to identify the audio input stream.

stop_audio_stream_output

def stop_audio_stream_output(stream_id: str = '') -> None

Stop the specified audio output stream or all active audio output streams playback.

Parameters

Name	Type	Default	Description
stream_id	str	''	Audio output stream ID to stop. Empty string means stop all active audio output streams (optional, default: "").

stop_base

def stop_base() -> ControlStatus

Emergency stop mobile base movement.

Immediately commands the mobile base to stop all motion. This is a safety function that should be used when immediate cessation of base motion is required.

Returns

Type	Description
ControlStatus	ControlStatus: Command sending result.

stop_controller

def stop_controller(group_name: str = 'all') -> ControlStatus

Stop controller execution.

Halts command execution but retains hardware authority. Opposite of start_controller.

Parameters

Name	Type	Default	Description
group_name	str	'all'	Name of the joint group (default: "all").

Returns

Type	Description
ControlStatus	ControlStatus: Result of the operation.

stop_microphone_stream_input

def stop_microphone_stream_input(stream_id: str = '') -> None

Stop the specified microphone streaming audio input.

Parameters

Name	Type	Default	Description
stream_id	str	''	Audio input stream ID to stop. Empty string stops all active streams (optional, default: "").

stop_trajectory_execution

def stop_trajectory_execution() -> ControlStatus

Stop all currently executing joint trajectories.

Immediately halts execution of all active joint trajectories across all joint groups. Joints will maintain their current positions after stopping.

Returns

Type	Description
ControlStatus	ControlStatus: Command sending result.

subscribe_video_data

def subscribe_video_data(camera_id: SensorType, callback: Callable) -> SensorStatus

Subscribe to H.264 encoded video frames from the specified camera.

Registers a callback for one H.264 video stream. The user callback is executed by an internal SDK dispatch thread and does not block the middleware receive callback thread.

Parameters

Name	Type	Default	Description
camera_id	SensorType	required	Camera sensor ID to subscribe.
callback	Callable	required	Callback function with signature: void(dict video_data).

Returns

Type	Description
SensorStatus	SensorStatus: SUCCESS if callback is registered.

note

The camera sensor must be enabled during initialization via enable_sensor_set.

note

Keep the callback short and non-blocking. Long-running work may delay video frame delivery for this subscription.

switch_controller

def switch_controller(controller_name: str) -> ControlStatus

Switch active controller strategy.

Transitions hardware control to a new strategy. The request is sent to the WBCS controller manager, which performs the safe switch and starts the selected controller when accepted.

Parameters

Name	Type	Default	Description
controller_name	str	required	Controller name, for example "chassis_pose_ctrl".

Returns

Type	Description
ControlStatus	ControlStatus: SUCCESS if WBCS accepts the switch; INVALID_INPUT if the controller name is unknown; INIT_FAILED if the WBCS client is unavailable; TIMEOUT if no response is received within 5 seconds; or FAULT if the response contains any controller-command error.

note

WBCS enforces controller priority. When a BYPASS controller has a higher priority than the target PVT controller, it cannot switch directly to PVT. Call stop_controller(group_name), release_controller(group_name), acquire_controller(pvt_controller), and start_controller(group_name) in that order.

unsubscribe_video_data

def unsubscribe_video_data(camera_id: SensorType) -> SensorStatus

Unsubscribe from H.264 encoded video frames for the specified camera.

Clears all user callbacks previously registered for this camera through subscribe_video_data. Internal SDK reader, ring buffer, and dispatch thread remain running to avoid repeated thread and resource creation/destruction.

Parameters

Name	Type	Default	Description
camera_id	SensorType	required	Camera sensor ID to unsubscribe.

Returns

Type	Description
SensorStatus	SensorStatus: SUCCESS if callbacks are cleared.

wait_for_shutdown

def wait_for_shutdown() -> None

Block until shutdown is complete.

Blocks the calling thread until all modules have finished shutting down gracefully. This is the second step of the shutdown sequence, after request_shutdown() and before destroy().

note

This function will return when is_running() becomes false

write_audio_stream_output

def write_audio_stream_output(audio_chunk: str, stream_id: str = '') -> bool

Write PCM format audio data chunk to audio output stream for real-time playback.

Parameters

Name	Type	Default	Description
audio_chunk	str	required	Audio data chunk in PCM format (16000 Hz, 16-bit little-endian), single channel.
stream_id	str	''	Audio stream ID to distinguish different audio sources. Empty string means use default stream (optional, default: "").

Returns

Type	Description
bool	bool: True if audio data has been successfully written and playback task issued, False if write failed.

zero_whole_body_and_base

def zero_whole_body_and_base(
    base_zero_pose: Pose,
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = None
) -> tuple[MotionStatus, ControlStatus]

One-key zero: move whole-body joints to zero and base to zero pose.

Parameters

Name	Type	Default	Description
base_zero_pose	Pose	required	-
is_blocking	bool	True	-
leg_head_speed_rad_s	SupportsFloat	0.2	-
leg_head_timeout_s	SupportsFloat	15.0	-
params	Parameter	None	-

Returns

Type	Description
tuple[MotionStatus, ControlStatus]	-

zero_whole_body_and_base

def zero_whole_body_and_base(
    frame_id: str = 'odom',
    reference_frame_id: str = 'odom',
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = None
) -> tuple[MotionStatus, ControlStatus]

One-key zero: move whole-body joints to zero and base (x,y,yaw) to zero with frames.

Parameters

Name	Type	Default	Description
frame_id	str	'odom'	Frame id ("base_link"/"odom"/"map"). Default "odom".
reference_frame_id	str	'odom'	Reference frame id ("odom"/"map"). Default "odom".
is_blocking	bool	True	Whether to block on joint zeroing (optional, default: True).
leg_head_speed_rad_s	SupportsFloat	0.2	Leg/head joint speed limit in rad/s (optional, default: 0.2).
leg_head_timeout_s	SupportsFloat	15.0	Leg/head blocking timeout in seconds (optional, default: 15.0).
params	Parameter	None	Motion planning parameters (optional, default: None).

Returns

Type	Description
tuple[MotionStatus, ControlStatus]	-

---

GalbotMotion

Unified motion planning and control interface for Galbot robots.

This interface provides a comprehensive API for robot motion control, including: Forward and inverse kinematics computation Single-chain and multi-chain trajectory planning Collision detection (self-collision and environment) Tool and obstacle management Whole-body coordinated motion planning Use GalbotMotion::get_instance(MachineType) to obtain a reference for a specific platform (G1/S1/G3). All angular units are radians, linear units are meters (SI standard). Quaternions must be unit-normalized: sqrt(x² + y² + z² + w²) = 1.

add_obstacle

def add_obstacle(
    obstacle_id: str,
    obstacle_type: str,
    pose: list[float],
    scale: list[float] = [0.0, 0.0, 0.0],
    key: str = '',
    target_frame: str = 'world',
    ee_frame: str = 'ee_base',
    reference_joint_positions: list[float] = [],
    reference_base_pose: list[float] = [],
    ignore_collision_link_names: Sequence[str] = [],
    safe_margin: SupportsFloat = 0.0,
    resolution: SupportsFloat = 0.01
) -> MotionStatus

Load collision object into environment.

Inserts a geometric or mesh-based obstacle into the environment for collision avoidance. Obstacles can be static (world-fixed) or robot-relative. Supports primitive shapes, meshes, point clouds, and depth images.

Parameters

Name	Type	Default	Description
obstacle_id	str	required	Unique ID for the obstacle (cannot be duplicated)
obstacle_type	str	required	Obstacle type. Options: box / sphere / cylinder / mesh / point_cloud / depth_image
pose	list[float]	required	Position and orientation of the obstacle. Length 7: [x, y, z, qx, qy, qz, qw]
scale	list[float]	[0.0, 0.0, 0.0]	Geometric size of the obstacle box: length / width / height (l / w / h) / sphere: radius / - / - / cylinder: radius / height / -
key	str	''	key for the obstacle. mesh / point_cloud: file path / depth_image: camera type (front_head / left_arm / right_arm)
target_frame	str	'world'	Target coordinate frame. Options: world / base_link / motion chain name
ee_frame	str	'ee_base'	End-effector coordinate frame. Only effective when target_frame is a motion chain name
reference_joint_positions	list[float]	[]	Robot joint state when loading obstacle. If empty, current joint state is used
reference_base_pose	list[float]	[]	Robot base pose in map coordinate frame. If empty, current base pose is used
ignore_collision_link_names	Sequence[str]	[]	List of robot link names to ignore in collision detection
safe_margin	SupportsFloat	0.0	Safe distance to obstacle. Collision is detected when obstacle distance is less than this value
resolution	SupportsFloat	0.01	Loading precision for some obstacle types. Defaults to 0.01

Returns

Type	Description
MotionStatus	MotionStatus: Result of adding the obstacle

note

Point-cloud note: point_cloud here refers to a point-cloud obstacle explicitly loaded via this API (typically from a file/offline data). It is NOT the same as a navigation-maintained point-cloud map. galbotMotion does not automatically subscribe to or synchronize with galbotNav's point-cloud map for collision.

note

Obstacles persist until explicitly removed or cleared.

note

For moving obstacles, remove and re-add at new poses (no update method currently).

warning

Large safe_margin values may over-constrain planning; use conservatively.

attach_target_object

def attach_target_object(
    obstacle_id: str,
    obstacle_type: str,
    pose: list[float],
    scale: list[float] = [0.0, 0.0, 0.0],
    key: str = '',
    target_frame: str = 'world',
    ee_frame: str = 'ee_base',
    reference_joint_positions: list[float] = [],
    reference_base_pose: list[float] = [],
    ignore_collision_link_names: Sequence[str] = [],
    safe_margin: SupportsFloat = 0.0,
    resolution: SupportsFloat = 0.01
) -> MotionStatus

Attach a collision object to the robot (e.g., grasped object).

Similar to add_obstacle(), but the object moves with the robot (attached to a link/chain). Used for representing grasped objects, sensors, or payloads. The object's pose is maintained relative to the attachment frame during motion.

Parameters

Name	Type	Default	Description
obstacle_id	str	required	Unique ID for the obstacle (cannot repeat)
obstacle_type	str	required	Type of obstacle (box/sphere/cylinder/mesh/point_cloud/depth_image)
pose	list[float]	required	Position and orientation of the obstacle (length 7: xyz+quat)
scale	list[float]	[0.0, 0.0, 0.0]	Geometry size (box: l/w/h; sphere: r/-/-; cylinder: r/h/-)
key	str	''	File path (mesh/point_cloud) or camera type (depth_image: front_head/left_arm/right_arm)
target_frame	str	'world'	Target coordinate frame (world/base_link/chain name)
ee_frame	str	'ee_base'	End-effector frame (only valid if target_frame is a chain)
reference_joint_positions	list[float]	[]	Robot joint state when loading obstacle (current if empty)
reference_base_pose	list[float]	[]	Robot base pose in map frame (current if empty)
ignore_collision_link_names	Sequence[str]	[]	Links to ignore collision with
safe_margin	SupportsFloat	0.0	Safe distance (collision if < this value)
resolution	SupportsFloat	0.01	Loading precision for some obstacle types

Returns

Type	Description
MotionStatus	MotionStatus: Result of adding obstacle

note

Point-cloud note: same as add_obstacle(). point_cloud here is an explicitly loaded point-cloud object and will not be automatically synchronized with any navigation-side point-cloud map.

note

Attached objects move with the robot; their collision geometry is updated automatically.

note

Typically used in pick-and-place: attach_target_object after grasp, detach after release.

warning

Ensure ignore_collision_link_names includes grasping links to avoid false collisions.

attach_tool

def attach_tool(chain: str, tool: str) -> MotionStatus

Attach a tool to an end-effector.

Loads a tool (gripper, camera, custom end-effector) onto a kinematic chain. Updates the kinematic model and collision geometry to include the tool.

Parameters

Name	Type	Default	Description
chain	str	required	The robot motion chain. Only "left_arm" and "right_arm" are supported.
tool	str	required	The tool to attach. Its name must be returned by get_supported_tool_list(), but that list is only a candidate range. Select a tool compatible with the actual end-effector type and configuration of the specified robot model and arm.

Returns

Type	Description
MotionStatus	MotionStatus: Result of the tool attachment.

note

Tool transform and collision geometry must be pre-configured in robot description.

note

Tool compatibility can differ by robot model, arm, and deployed robot/MPS configuration. A tool returned by get_support_tool_list() is therefore not guaranteed to be attachable to every supported chain.

note

Attaching a new tool automatically detaches any previously attached tool on that chain.

note

For set_end_effector_pose(), the target remains the flange by default. Set Parameter::is_tool_pose=true (or call Parameter::set_tool_pose(true)) when target_pose is the tool TCP.

note

get_support_tool_list() returns attachable tool names. get_support_ee_frame() returns frame types accepted by APIs with frame_id/target_frame (for example "EndEffector", "Camera", and "TCP").

warning

Kinematics and collision checking will reflect the attached tool; update plans accordingly.

check_collision

def check_collision(
    start: Sequence[RobotStates],
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, list[bool]]

Check robot states for collisions.

Therefore, if you need Motion to consider environmental obstacles (including point clouds), you must load the obstacle map/objects explicitly (e.g., obstacle_type = point_cloud with a file path in key).

Note: integrating real-time perception (navigation-style obstacle updates / point-cloud map) into galbotMotion is a planned future feature and has limited internal validation at the moment.

Validates whether given robot configurations are collision-free. Checks both self-collisions (robot links with each other) and environment collisions (robot with scene obstacles). Batch processing supported for efficiency.

Parameters

Name	Type	Default	Description
start	Sequence[RobotStates]	required	The robot states.
enable_collision_check	bool	True	Whether to enable collision checking. Defaults to true.
params	Parameter	...	Additional parameters for the collision checking. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, list[bool]]	bool: True if there is a collision, False otherwise.

note

[Obstacle perception & point-cloud usage: galbotNav vs galbotMotion]

note

Useful for validating planned trajectories or sampling-based planners.

note

Respects safe_margin settings in previously added obstacles.

check_collision_detail

def check_collision_detail(
    robot_states: Sequence[RobotStates],
    is_check_once: bool = False,
    is_log: bool = False,
    params: Parameter = ...
) -> tuple[MotionStatus, list[CollisionInfo]]

Check robot states for detailed collision pairs.

Queries the kinematic collision service and returns the collision pair details currently provided by MPS.

Parameters

Name	Type	Default	Description
robot_states	Sequence[RobotStates]	required	Robot states to check. If empty, MPS checks the current robot state.
is_check_once	bool	False	Whether to run one-shot collision checking. Defaults to False.
is_log	bool	False	Whether MPS should emit collision-check logs. Defaults to False.
params	Parameter	...	Additional parameters. Only timeout_second is used today.

Returns

Type	Description
tuple[MotionStatus, list[CollisionInfo]]	tuple[MotionStatus, list[CollisionInfo]]: Status and collision pair details.

note

• collision_type contains the raw MPS common_str metadata, including the sample tag and a collision classification whose value is self or env.
• A default-constructed CollisionInfo uses UNKNOWN; an empty MPS value is returned as an empty string.

clear_obstacle

def clear_obstacle() -> MotionStatus

Remove all collision obstacles from the planning scene.

Clears the entire obstacle set, resetting the planning scene to empty (except robot geometry).

Returns

Type	Description
MotionStatus	-

note

Attached objects (see attach_target_object) are not affected.

note

Safe to call even if scene is already empty.

combine_plan

def combine_plan(
    plan_reqs: Sequence[PlanRequest],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

Combine multiple heterogeneous plan requests into a single coordinated trajectory.

Accepts a sequence of PlanRequest objects, each specifying its own plan type (MOTION_PLAN / TRAJ_PLAN / MOVE_LINE), target waypoints, and per-segment options. The server composes these into a single continuous trajectory that transitions smoothly between segments, with each segment using its own planning algorithm.

Server-side flow: The SDK sends a CombinePlanReq (proto field: combine_plan_req) containing a sequence of SigPlanReq sub-requests, each with its own plan_type, target states, and PlannerConfig options. The enforce_pass flag sent to the server is the logical AND of all segment enforce_pass values. When true, the server attempts to continue planning even if individual segments encounter issues; when false, any segment failure aborts the entire combined plan. Per-segment options override the top-level server_options where explicitly set. The server concatenates resulting trajectories into a single RobotTrajectoryVec with C1 continuity (smooth velocity transition) at segment boundaries. If is_direct_execute=true, the combined trajectory is pushed to the WBC queue.

Typical use cases: Pick-and-place: approach (move_line) -> grasp (motion_plan with collision) -> retreat (move_line) Mixing collision-checked path segments with fast trajectory-only segments Multi-stage operations where different phases need different planning strategies Recovery sequences: move away from obstacle (motion_plan) -> return to task (traj_plan)

Parameters

Name	Type	Default	Description
plan_reqs	Sequence[PlanRequest]	required	-
params	PlannerConfig	...	-
start_state	RobotStates	None	-

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	-

note

The server ensures C1 continuity (smooth velocity transition) at segment boundaries.

note

All segments share the same trajectory timeline; chains are time-synchronized.

warning

The server-side CombinePlanReq handler must be implemented in the MPS server (proto field: combine_plan_req = 17). If the server version does not support this handler, the request will fail.

warning

For direct execution (is_direct_execute=true), avoid passing start_state.

detach_target_object

def detach_target_object(obstacle_id: str) -> MotionStatus

Detach an object from the robot (e.g., after release).

Removes an attached object from the robot. Typically called after releasing a grasped object. The object is removed from the planning scene entirely (not converted to a static obstacle).

Parameters

Name	Type	Default	Description
obstacle_id	str	required	-

Returns

Type	Description
MotionStatus	-

note

To keep the object in the scene as a static obstacle after release, call detach_target_object() then add_obstacle() with the object's final pose.

detach_tool

def detach_tool(chain: str) -> MotionStatus

Detach the current tool from an end-effector.

Removes the attached tool from a kinematic chain, reverting to the base end-effector. Updates kinematic model and collision geometry accordingly.

Parameters

Name	Type	Default	Description
chain	str	required	The robot motion chain. Only "left_arm" and "right_arm" are supported.

Returns

Type	Description
MotionStatus	MotionStatus: Result of the tool detachment.

note

If no tool is attached, operation succeeds as a no-op.

forward_kinematics

def forward_kinematics(
    target_frame: str,
    reference_frame: str = 'base_link',
    joint_state: dict] = {},
    params: Parameter = ...
) -> tuple[MotionStatus, list[float]]

Compute forward kinematics for a target link.

Calculates the Cartesian pose of a specified link given joint configurations. Useful for determining end-effector positions, validating configurations, or computing intermediate link poses.

Parameters

Name	Type	Default	Description
target_frame	str	required	The name of the target frame.
reference_frame	str	'base_link'	"world", "map", "base_link" (or "base"), or a link name returned by get_supported_links(). Defaults to "base_link".
joint_state	dict]	{}	A dictionary mapping joint names to their positions. Defaults to an empty dictionary.
params	Parameter	...	Additional parameters for the forward kinematics. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, list[float]]	Pose: The computed pose of the target frame.

note

Joint angles in radians, output pose in meters with unit quaternion.

warning

target_frame must be a valid link in the URDF model.

forward_kinematics_by_state

def forward_kinematics_by_state(
    target_frame: str,
    reference_robot_states: RobotStates = None,
    reference_frame: str = 'base_link',
    params: Parameter = ...
) -> tuple[MotionStatus, list[float]]

Compute forward kinematics using complete robot state.

Similar to forward_kinematics(), but accepts a RobotStates object for specifying the complete robot configuration (whole-body joints + base pose).

Parameters

Name	Type	Default	Description
target_frame	str	required	The name of the target frame.
reference_robot_states	RobotStates	None	The reference robot states. Defaults to nullptr.
reference_frame	str	'base_link'	"world", "map", "base_link" (or "base"), or a link name returned by get_supported_links(). Defaults to "base_link".
params	Parameter	...	Additional parameters for the forward kinematics. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, list[float]]	Pose: The computed pose of the target frame.

note

Useful when computing FK for hypothetical states without modifying current robot state.

get_built_obstacles_list

def get_built_obstacles_list() -> list[str]

Get the list of currently loaded obstacle IDs.

Returns

Type	Description
list[str]	-

get_chain_joint_names

def get_chain_joint_names(chain_name: str) -> list[str]

Get joint names for a specific kinematic chain.

Returns the ordered list of joint names belonging to the specified chain, as configured in the robot model.

Parameters

Name	Type	Default	Description
chain_name	str	required	-

Returns

Type	Description
list[str]	-

get_chain_joint_state

def get_chain_joint_state() -> dict[str, list[float]]

Get current joint configurations for all kinematic chains.

Retrieves per-chain joint states, decomposing the whole-body configuration into individual chain contributions.

Returns

Type	Description
dict[str, list[float]]	-

note

Joint vector sizes vary by chain DOF.

get_config_by_type

def get_config_by_type(config_type: str) -> tuple[MotionStatus, MotionPlanConfig]

Get MPS configuration by type (result via MotionPlanConfig.common_str).

Parameters

Name	Type	Default	Description
config_type	str	required	-

Returns

Type	Description
tuple[MotionStatus, MotionPlanConfig]	-

get_end_effector_pose

def get_end_effector_pose(
    end_effector_frame: str,
    reference_frame: str = 'base_link'
) -> tuple[MotionStatus, list[float]]

Get current end-effector pose from robot state.

Computes the current Cartesian pose via MPS forward kinematics using the robot's live joint state. Requires the link to be defined in the robot's URDF model.

Parameters

Name	Type	Default	Description
end_effector_frame	str	required	The name of the end-effector frame.
reference_frame	str	'base_link'	"world", "map", "base_link" (or "base"), or a link name returned by get_supported_links(). Defaults to "base_link".

Returns

Type	Description
tuple[MotionStatus, list[float]]	Pose: The computed pose of the end-effector frame.

note

Reflects the current actual robot state (not planned state).

note

Use this method when the exact URDF link name is already known. For chain-relative semantic frames such as the flange, camera, or attached-tool TCP, use get_end_effector_pose_on_chain() instead.

get_end_effector_pose_on_chain

def get_end_effector_pose_on_chain(
    chain_name: str,
    frame_id: str = 'EndEffector',
    reference_frame: str = 'base_link'
) -> tuple[MotionStatus, list[float]]

Get current end-effector pose for a specific kinematic chain.

Convenience method for retrieving end-effector pose by chain name and frame type, without needing to know the exact link name in URDF.

Parameters

Name	Type	Default	Description
chain_name	str	required	The name of the chain.
frame_id	str	'EndEffector'	The name of the end-effector frame. Defaults to "EndEffector".
reference_frame	str	'base_link'	"world", "map", "base_link" (or "base"), or a link name returned by get_supported_links(). Defaults to "base_link".

Returns

Type	Description
tuple[MotionStatus, list[float]]	Pose: The computed pose of the end-effector frame on the specified chain.

note

Internally maps chain_name + frame_id to actual URDF link name.

note

Use this method when you want a semantic frame without knowing the URDF link name. Supported frame types include "EndEffector" (the chain flange), "Camera", and "TCP"/"ToolPose" (the attached tool TCP). A TCP query requires a tool to be attached first; otherwise the call returns MotionStatus::INVALID_INPUT.

note

The resolved frame is ultimately queried through the same forward-kinematics path as get_end_effector_pose(). The difference is that this overload resolves chain_name + frame_id first.

get_jacobian

def get_jacobian(
    chain_name: str,
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    joint_state: dict] = {},
    params: Parameter = ...
) -> tuple[MotionStatus, list[list[float]]]

Compute the Jacobian matrix for a kinematic chain.

Computes the 6xN Jacobian matrix relating joint velocities to the target frame's 6D spatial velocity (linear + angular).

This API is the chain-level convenience form. The caller provides a chain_name and, optionally, a joint_state map for one or more chains. When joint_state is non-empty, the SDK reads the current whole-body state and replaces the specified chain joint values before sending the request. When joint_state is empty, the current robot state is used directly.

Use this API when you want to evaluate the Jacobian for a specific chain with a small set of chain joint values and do not need to provide an entire RobotStates object. Use get_jacobian_by_state() instead when the complete whole-body joint vector or base pose must be specified explicitly.

Parameters

Name	Type	Default	Description
chain_name	str	required	Kinematic chain (e.g., "left_arm", "right_arm")
target_frame	str	'EndEffector'	Frame on chain. Defaults to "EndEffector".
reference_frame	str	'base_link'	"world", "map", or "base_link". Defaults to "base_link".
joint_state	dict]	{}	Chain joint override map. Uses current complete state if empty.
params	Parameter	...	Planning parameters. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, list[list[float]]]	tuple: (MotionStatus, jacobian_matrix) - jacobian_matrix is a list of lists: [[float]] (6 rows x N cols)

note

Jacobian rows: [vx, vy, vz, wx, wy, wz] (linear then angular velocity).

note

Columns correspond to joints in the chain, ordered by joint index.

note

Use get_support_links() / get_link_names() to discover valid target_frame link names.

get_jacobian_by_state

def get_jacobian_by_state(
    chain_name: str,
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    params: Parameter = ...
) -> tuple[MotionStatus, list[list[float]]]

Compute the Jacobian matrix using a complete robot state.

Computes the same 6xN Jacobian as get_jacobian(), but the state input is a complete RobotStates object rather than a chain-level joint_state map. The whole_body_joint field defines the complete robot joint configuration and base_state defines the mobile base pose used by the kinematic service. If reference_robot_states is nullptr, the SDK reads the current complete robot state.

Use this API for offline/hypothetical-state computation, reproducible tests, or any case where the Jacobian must be evaluated at a known whole-body joint vector and base pose. Use get_jacobian() for simpler chain-level current-state or chain-joint override queries.

Parameters

Name	Type	Default	Description
chain_name	str	required	Kinematic chain (e.g., "left_arm", "right_arm")
target_frame	str	'EndEffector'	Frame on chain. Defaults to "EndEffector".
reference_frame	str	'base_link'	"world", "map", or "base_link". Defaults to "base_link".
reference_robot_states	RobotStates	None	Complete robot state. Uses current complete state if None.
params	Parameter	...	Planning parameters. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, list[list[float]]]	tuple: (MotionStatus, jacobian_matrix) - jacobian_matrix is a list of lists: [[float]] (6 rows x N cols)

note

Useful when computing Jacobian for hypothetical states without modifying current robot state.

get_link_names

def get_link_names(only_end_effector: bool = False) -> list[str]

Get robot link names from kinematic model.

Retrieves the list of link names defined in the robot's URDF model. Can filter to only end-effector links or return all links.

Parameters

Name	Type	Default	Description
only_end_effector	bool	False	If true, returns only end-effector/tool links; if false, returns all links including base, intermediate, and end-effector links.

Returns

Type	Description
list[str]	list: Vector of link name strings (empty if retrieval fails)

note

End-effector detection based on link having no child links in kinematic tree.

note

Useful for forward kinematics queries or TF frame validation.

get_motion_plan_config

def get_motion_plan_config() -> tuple[MotionStatus, MotionPlanConfig]

Get current motion planning configuration.

Retrieves the active planner configuration, including velocity/acceleration limits and planning algorithm parameters.

Returns

Type	Description
tuple[MotionStatus, MotionPlanConfig]	-

note

Useful for inspecting current limits or saving/restoring configurations.

get_robot_states

def get_robot_states() -> RobotStates

Get current complete robot state.

Retrieves the current whole-body joint configuration and mobile base pose. Represents the full kinematic state of the robot.

Returns

Type	Description
RobotStates	-

note

Reflects actual robot state (from sensor feedback/state estimation).

note

Useful as seed/reference for planning operations.

get_supported_chains

def get_supported_chains() -> set[str]

Get the set of supported kinematic chain names (e.g. left_arm, right_arm).

Returns

Type	Description
set[str]	-

get_supported_ee_frames

def get_supported_ee_frames() -> set[str]

Get the set of supported end-effector frame identifiers.

Returns

Type	Description
set[str]	-

get_supported_frames

def get_supported_frames() -> set[str]

Get the set of supported reference frame names.

Returns

Type	Description
set[str]	-

get_supported_links

def get_supported_links() -> set[str]

Get the set of supported link names (URDF link names for FK/IK).

Returns

Type	Description
set[str]	-

get_supported_obstacle_types

def get_supported_obstacle_types() -> set[str]

Get the set of supported obstacle types (e.g. box, sphere, cylinder, mesh).

Returns

Type	Description
set[str]	-

get_supported_tool_list

def get_supported_tool_list() -> set[str]

Get the list of supported tool names for attach_tool.

Returns

Type	Description
set[str]	-

init

def init() -> bool

Initialize motion planning system and communication interfaces.

Must be called before any other API functions. Initializes internal communication middleware, loads robot kinematic models, and establishes connections to control services.

Returns

Type	Description
bool	-

note

Safe to call multiple times; subsequent calls after successful init are no-ops.

warning

All other API calls will fail if init() returns false.

inverse_kinematics

def inverse_kinematics(
    target_pose: list[float],
    chain_names: Sequence[str],
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    initial_joint_positions: dict] = {},
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[float]]]

Compute inverse kinematics for target Cartesian pose.

Solves for joint configurations that achieve the specified end-effector pose. Supports single-chain IK (arm only) or coordinated multi-chain IK (arm + torso/legs).

Parameters

Name	Type	Default	Description
target_pose	list[float]	required	The target pose.
chain_names	Sequence[str]	required	The list of chain names to consider.
target_frame	str	'EndEffector'	The name of the target frame. Defaults to "EndEffector".
reference_frame	str	'base_link'	"world", "map", or "base_link". Defaults to "base_link".
initial_joint_positions	dict]	{}	A dictionary mapping joint names to their initial positions. Defaults to an empty dictionary.
enable_collision_check	bool	True	Whether to enable collision checking. Defaults to true.
params	Parameter	...	Additional parameters for the inverse kinematics. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[float]]]	dict: A dictionary mapping joint names to their computed positions.

note

IK may have multiple solutions; returns first valid solution found.

note

Seed configuration affects convergence speed and which solution is returned.

warning

No solution guaranteed if target is outside workspace or in singular configuration.

inverse_kinematics_by_state

def inverse_kinematics_by_state(
    target_pose: list[float],
    chain_names: Sequence[str],
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[float]]]

Compute inverse kinematics using complete robot state as seed.

Similar to inverse_kinematics(), but accepts RobotStates for specifying the seed configuration, allowing precise control over the entire robot state.

Parameters

Name	Type	Default	Description
target_pose	list[float]	required	The target pose.
chain_names	Sequence[str]	required	The list of chain names to consider.
target_frame	str	'EndEffector'	The name of the target frame. Defaults to "EndEffector".
reference_frame	str	'base_link'	"world", "map", or "base_link". Defaults to "base_link".
reference_robot_states	RobotStates	None	The reference robot states. Defaults to nullptr.
enable_collision_check	bool	True	Whether to enable collision checking. Defaults to true.
params	Parameter	...	Additional parameters for the inverse kinematics. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[float]]]	dict: A dictionary mapping joint names to their computed positions.

note

Useful for offline planning with hypothetical robot states.

inverse_kinematics_general

def inverse_kinematics_general(
    target_waypoint: Sequence[MotionPlanChainTarget],
    reference_robot_states: RobotStates = None,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, JointStates]]

Compute inverse kinematics using generalized multi-chain target description.

Uses the newer MotionPlanTarget schema (inverse_kinematic_general_req) to support mixed chain targets and assist-chain settings in a single request.

Parameters

Name	Type	Default	Description
target_waypoint	Sequence[MotionPlanChainTarget]	required	-
reference_robot_states	RobotStates	None	-
params	Parameter	...	-

Returns

Type	Description
tuple[MotionStatus, dict[str, JointStates]]	-

motion_plan

def motion_plan(
    target: RobotStates,
    start: RobotStates = None,
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

Plan a time-parameterized trajectory to one Cartesian or joint-space target.

This is the high-level single-target overload. target must be a PoseState or JointStates instance whose chain_name identifies the chain to plan. It dispatches to traj_plan() by default, or to move_line() when params.move_line is True.

Parameters

Name	Type	Default	Description
target	RobotStates	required	PoseState or JointStates goal. Base RobotStates is not accepted. For PoseState, frame_id selects the target frame on the chain.
start	RobotStates	None	Optional chain start state. If provided, it must be a JointStates instance; other RobotStates types return MotionStatus.INVALID_INPUT. None uses the current state.
reference_robot_states	RobotStates	None	Whole-body planning context. If start is provided, its chain values override the corresponding values in this state.
enable_collision_check	bool	True	Require a collision-free trajectory. Defaults to True.
params	Parameter	...	Planning and execution options, including direct execution, timeout and Cartesian line dispatch. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	tuple[MotionStatus, dict[str, list[list[float]]]]: Status and per-chain joint trajectory.

note

• GalbotMotion does not automatically import real-time perception into its collision world.
• Collision checking uses self-collision and environment objects explicitly loaded through add_obstacle() or attach_target_object().
• The returned trajectory respects configured velocity and acceleration limits.
• For the leg chain, params.move_line must be True and target must be a Cartesian PoseState without assist chains.

warning

target must be PoseState or JointStates. For direct execution, normally leave start and reference_robot_states as None to avoid conflicts with the actual robot state.

motion_plan

def motion_plan(
    waypoints: Sequence[Sequence[MotionPlanChainTarget]],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

Plan a collision-aware path through MotionPlanWaypoints via the motion-planning server.

This is the low-level server-facing overload. waypoints can describe one or more coordinated chains. The server performs sampling-based geometric path search and then time-parameterizes the result with the configured velocity, acceleration, and jerk limits.

Parameters

Name	Type	Default	Description
waypoints	Sequence[Sequence[MotionPlanChainTarget]]	required	Ordered waypoints; each waypoint contains one MotionPlanChainTarget per chain to coordinate.
params	PlannerConfig	...	Server planning options. is_direct_execute pushes the result to WBC, is_check_collision validates the path, and enable_env_collision_check includes explicitly loaded environment obstacles. actuate_type globally adds its assist chain to every Cartesian target. Defaults to PlannerConfig().
start_state	RobotStates	None	Explicit whole-body start state. None uses the current robot state. Defaults to None.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	tuple[MotionStatus, dict[str, list[list[float]]]]: Status and time-parameterized per-chain joint trajectory.

note

• GalbotMotion does not automatically import real-time perception into its collision world.
• Collision checking uses self-collision and environment objects explicitly loaded through add_obstacle() or attach_target_object().
• params.actuate_type applies to all Cartesian targets and is not recommended for waypoint-specific control. Set cart.assist_chains on individual targets instead.
• For single-target planning with a simpler API, use motion_plan(target, start, ), which dispatches to traj_plan() by default or move_line() when params.move_line is True. It does not call this sampling-based overload.

warning

The "leg" chain is not supported as chain_name or in assist_chains. For direct execution, normally leave start_state as None to avoid conflicts with the actual robot state.

motion_plan_multi_waypoints

def motion_plan_multi_waypoints(
    target: RobotStates,
    waypoint_poses: Sequence[list[float]],
    start: RobotStates = None,
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

Plan a trajectory through multiple waypoints for one kinematic chain.

target is a PoseState or JointStates template that supplies the waypoint type and chain_name; its stored state values are not used as a goal. waypoint_poses contains the actual Cartesian poses or joint configurations to traverse.

Parameters

Name	Type	Default	Description
target	RobotStates	required	PoseState or JointStates template with chain_name set.
waypoint_poses	Sequence[list[float]]	required	Cartesian poses for PoseState or joint configurations in radians for JointStates.
start	RobotStates	None	Optional chain start state. None uses the current state.
reference_robot_states	RobotStates	None	Whole-body planning context. None uses the current state.
enable_collision_check	bool	True	Require a collision-free trajectory. Defaults to True.
params	Parameter	...	Planning and execution options. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	tuple[MotionStatus, dict[str, list[list[float]]]]: Status and the chain trajectory.

note

• GalbotMotion does not automatically import real-time perception into its collision world.
• Collision checking uses self-collision and environment objects explicitly loaded through add_obstacle() or attach_target_object().
• The planner produces C1-continuous motion, so intermediate waypoints may be blended instead of reached exactly.

warning

Use separate plans when an intermediate waypoint must be reached exactly. For direct execution, normally leave start and reference_robot_states as None.

motion_plan_multi_waypoints

def motion_plan_multi_waypoints(
    targets: dict]],
    start: Sequence[RobotStates] = [],
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

Plan synchronized trajectories through waypoints for multiple kinematic chains.

Use this overload for coordinated motion such as bimanual manipulation. Each targets mapping key is a PoseState or JointStates template identifying one chain and waypoint representation; the corresponding value is that chain's waypoint sequence.

Parameters

Name	Type	Default	Description
targets	dict]]	required	State template to waypoint-sequence mapping for every chain to coordinate.
start	Sequence[RobotStates]	[]	Optional per-chain start states. An empty list uses current states. Defaults to an empty list.
reference_robot_states	RobotStates	None	Whole-body planning context. None uses the current state.
enable_collision_check	bool	True	Require collision-free coordinated trajectories. Defaults to True.
params	Parameter	...	Planning and execution options shared by all chains. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	tuple[MotionStatus, dict[str, list[list[float]]]]: Status and synchronized per-chain trajectories.

note

• GalbotMotion does not automatically import real-time perception into its collision world.
• Collision checking uses self-collision and environment objects explicitly loaded through add_obstacle() or attach_target_object().
• All returned chain trajectories are time-synchronized.

warning

For direct execution, normally leave start empty and reference_robot_states as None to avoid conflicts with the actual robot state.

move_line

def move_line(
    waypoints: Sequence[Sequence[MotionPlanChainTarget]],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

Generate straight-line Cartesian motion through waypoints.

Sends a MoveLineReq to the server , which plans a straight-line path in Cartesian (task) space for the end-effector, then converts it to a joint-space trajectory via IK at intermediate sampling points.

Server-side flow: For single chain: calls singleChainMoveLine(). For multi-chain: calls multiChainMoveLine(). The planner samples intermediate points along the Cartesian line using the move_line_intermidiate_point count configured in TrajPlanner. At each sample point, IK is solved to find the corresponding joint configuration. The resulting joint sequence is time-parameterized and validated.

Compared to other plan types: motion_plan(): joint-space sampling with collision avoidance; end-effector path shape is planner-determined (not guaranteed straight). traj_plan(): direct joint-space interpolation; end-effector path is unpredictable. move_line(): Cartesian-space linear interpolation; end-effector path is a straight line.

Typical use cases: Precise linear approach/retract motions (e.g., peg-in-hole insertion, suction pick) Surface-following tasks (painting, welding, gluing) Any operation requiring a predictable straight-line end-effector trajectory

Parameters

Name	Type	Default	Description
waypoints	Sequence[Sequence[MotionPlanChainTarget]]	required	-
params	PlannerConfig	...	-
start_state	RobotStates	None	-

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	-

note

Collision semantics: collision checking (if enabled in params) is performed against self-collision and user-loaded environment obstacles. The server validates intermediate IK-sampled points for collision.

note

The number of intermediate IK samples is controlled by move_line_intermidiate_point in the server's TrajPlanner config. More samples = smoother path but slower planning.

warning

Cartesian linear motion may encounter joint velocity/acceleration limits, singularities, or unreachable configurations along the path, causing planning failure.

warning

Ensure all waypoints are within the chain's reachable workspace.

move_whole_body_joint_zero

def move_whole_body_joint_zero(
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = ...
) -> MotionStatus

Move the whole-body joints to the predefined zero (home) configuration.

The leg and head joints are commanded via GalbotRobot (direct joint control), while the left/right arms are planned via the motion planner with collision checking enabled.

Joint order of the zero configuration follows the SDK convention: leg(5) + head(2) + left_arm(7) + right_arm(7).

Parameters

Name	Type	Default	Description
is_blocking	bool	True	-
leg_head_speed_rad_s	SupportsFloat	0.2	-
leg_head_timeout_s	SupportsFloat	15.0	-
params	Parameter	...	-

Returns

Type	Description
MotionStatus	-

remove_obstacle

def remove_obstacle(obstacle_id: str) -> MotionStatus

Remove a collision obstacle from the planning scene.

Parameters

Name	Type	Default	Description
obstacle_id	str	required	-

Returns

Type	Description
MotionStatus	-

note

Removing a non-existent obstacle returns INVALID_INPUT (not silently ignored).

set_config_by_type

def set_config_by_type(config: MotionPlanConfig) -> MotionStatus

Set/Get MPS configuration by type (GetSet channel).

This is a thin wrapper over MPS Get/Set MotionPlanConfig RPC: config.config_type selects the target subsystem (e.g. "sampler", "ik_solver", "trajectory_planner"). For set_config_by_type, the request payload is encoded in config.common_str (type-dependent). For get_config_by_type, the response payload is returned in out.common_str (type-dependent).

The goal is to avoid exposing many narrow, type-specific configuration APIs.

Parameters

Name	Type	Default	Description
config	MotionPlanConfig	required	-

Returns

Type	Description
MotionStatus	-

set_end_effector_pose

def set_end_effector_pose(
    target_pose: list[float],
    end_effector_frame: str,
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    is_blocking: bool = True,
    timeout: SupportsFloat = -1.0,
    params: Parameter = ...
) -> MotionStatus

Command one end-effector chain to a target Cartesian pose.

Use this overload for single-chain planning without additional assist chains. end_effector_frame selects the kinematic chain, such as "left_arm" or "right_arm"; it does not select a semantic link on that chain.

Parameters

Name	Type	Default	Description
target_pose	list[float]	required	Target [x, y, z, qx, qy, qz, qw] pose in reference_frame.
end_effector_frame	str	required	Kinematic chain to command, for example "left_arm".
reference_frame	str	'base_link'	"world", "map", "base_link", or a chain name returned by get_supported_chains(). Defaults to "base_link".
reference_robot_states	RobotStates	None	Whole-body planning seed. None uses the current robot state. Defaults to None.
enable_collision_check	bool	True	Require a collision-free trajectory. Defaults to True.
is_blocking	bool	True	Whether this API waits for execution completion. False still starts robot motion and returns immediately. Defaults to True.
timeout	SupportsFloat	-1.0	Maximum time in seconds for the SDK to wait for motion completion. If negative, params.timeout_second is used. In non-blocking mode, the timeout is applied inside the background task. Defaults to -1.0.
params	Parameter	...	Motion-planning and execution options. In particular, is_tool_pose selects TCP versus flange targeting and move_line selects Cartesian straight-line target-frame motion. Defaults to default_param.

Returns

Type	Description
MotionStatus	MotionStatus: Planning or execution status.

note

• target_pose refers to the flange by default. After attach_tool(), set params.is_tool_pose=True when the target describes the attached-tool TCP.
• attach_tool() updates the kinematic and collision models but does not automatically change the target frame used by this API.

warning

For direct execution, normally leave reference_robot_states as None to avoid conflicts with the actual robot state. Non-blocking mode does not cancel or skip motion; it only returns before execution completes.

set_end_effector_pose

def set_end_effector_pose(
    target_pose: list[float],
    end_effector_frame: str,
    reference_frame: str,
    assist_chains: Set[str],
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    is_blocking: bool = True,
    timeout: SupportsFloat = -1.0,
    params: Parameter = ...
) -> MotionStatus

Command one end-effector chain to a target Cartesian pose with coordinated assist chains.

This overload coordinates the chains listed in assist_chains in addition to the primary chain. end_effector_frame selects that primary kinematic chain; it is not a semantic link name.

Parameters

Name	Type	Default	Description
target_pose	list[float]	required	Target [x, y, z, qx, qy, qz, qw] pose in reference_frame.
end_effector_frame	str	required	Primary kinematic chain to command, for example "left_arm".
reference_frame	str	required	"world", "map", "base_link", or a chain name returned by get_supported_chains().
assist_chains	Set[str]	required	Additional chains to coordinate during planning.
reference_robot_states	RobotStates	None	Whole-body planning seed. None uses the current robot state. Defaults to None.
enable_collision_check	bool	True	Require a collision-free trajectory. Defaults to True.
is_blocking	bool	True	Whether this API waits for execution completion. False still starts robot motion and returns immediately. Defaults to True.
timeout	SupportsFloat	-1.0	Maximum wait time in seconds. If negative, params.timeout_second is used. Defaults to -1.0.
params	Parameter	...	Motion-planning and execution options. Set is_tool_pose=True when target_pose describes the attached-tool TCP. Defaults to default_param.

Returns

Type	Description
MotionStatus	MotionStatus: Planning or execution status.

note

• target_pose refers to the flange by default. After attach_tool(), set params.is_tool_pose=True when the target describes the attached-tool TCP.
• attach_tool() updates the kinematic and collision models but does not automatically change the target frame used by this API.

warning

The "leg" chain is not supported in assist_chains. For direct execution, normally leave reference_robot_states as None. Non-blocking mode still starts robot motion.

set_motion_plan_config

def set_motion_plan_config(config: MotionPlanConfig) -> MotionStatus

Set global motion planning configuration.

Updates planner settings such as velocity/acceleration limits, planning algorithm parameters, and optimization objectives. Affects all subsequent planning operations.

Parameters

Name	Type	Default	Description
config	MotionPlanConfig	required	-

Returns

Type	Description
MotionStatus	-

note

Changes persist until explicitly reset or process restart.

note

See MotionPlanConfig documentation for available parameters.

status_to_string

def status_to_string(status: MotionStatus) -> str

Convert MotionStatus enum to human-readable string.

Maps status codes to descriptive strings for logging, error reporting, or UI display.

Parameters

Name	Type	Default	Description
status	MotionStatus	required	-

Returns

Type	Description
str	-

note

Uses status_string_map_ for lookup; returns "UNKNOWN" if status not found.

traj_plan

def traj_plan(
    waypoints: Sequence[Sequence[MotionPlanChainTarget]],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

Generate a time-parameterized joint trajectory through waypoints WITHOUT path search.

Sends a TrajPlanReq to the server (mps_core.cpp:handle_sig_point_traj_plan_req or handle_mul_point_traj_plan_req), which performs direct joint-space interpolation with time parameterization. Unlike motion_plan(), this does NOT run the sampling-based path search it connects waypoints directly in joint space.

Server-side flow: Single-point target: calls moveJointPlan() direct start-to-target interpolation. Multi-point targets: calls moveWaypointJointPlan() smooth multi-waypoint interpolation. is_direct_connect_try=true and is_path_search=false by default for this path. is_check_collision still applies (default: true), so joint limits and velocity are validated after interpolation.

Typical use cases: Quick repositioning in known-free space where sampling-based planning is unnecessary Generating smooth trajectories through teach-points or recorded joint configurations Internal use by higher-level planning functions that have already validated the path

Parameters

Name	Type	Default	Description
waypoints	Sequence[Sequence[MotionPlanChainTarget]]	required	-
params	PlannerConfig	...	-
start_state	RobotStates	None	-

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	-

note

Faster than motion_plan() since it skips the sampling-based path search phase.

warning

Does NOT search for collision-free paths; if any waypoint or the direct interpolation passes through obstacles, the planner will not detect it. is_check_collision (default: true) still validates joint limits and velocity feasibility, but not collision.

---

GalbotNavigation

Navigation interface for mobile robot chassis motion planning and localization.

This class provides a thread-safe singleton interface for controlling the mobile base navigation system. It supports 2D pose estimation, relocalization, goal-directed navigation with dynamic obstacle avoidance, and path planning capabilities. The navigation system operates in a global map frame and provides both blocking and non-blocking navigation modes. It supports both differential drive and omnidirectional motion planning strategies. This class uses the singleton pattern with thread-safe initialization. All pose coordinates are specified in the map frame unless explicitly stated otherwise. Typical usage: auto&nav=GalbotNavigation::get_instance(MachineType::G1); if(nav.init()){ Posegoal; goal.x=1.0;//meters goal.y=2.0;//meters goal.orientation.w=1.0;//identityquaternion(x,y,zdefault0) nav.navigate_to_goal(goal,true,false,30.0,true); }

add_bounding_box

def add_bounding_box(box_info: dict) -> tuple

Add a bounding box for navigation obstacle filtering.

Sends SDK-defined box regions to the fusion service so navigation can ignore the corresponding fused obstacle points instead of treating the boxes as obstacles. Each box is identified by box_tag and attached relative to parent_link_name.

Parameters

Name	Type	Default	Description
box_info	dict	required	Contains:

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

attach_box_to_link

def attach_box_to_link(box_info: dict, ignore_collision_links: Sequence[str] = []) -> tuple

Attach a box collision object to a robot link.

Sends the box as an attached collision object to PNS. The box object name is generated from box_tag, and box_info.parent_link_name is used as the parent link for box_info.box_pose.

Parameters

Name	Type	Default	Description
box_info	dict	required	Contains:
ignore_collision_links	Sequence[str]	[]	Robot links to ignore for collision checking.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

check_goal_arrival

def check_goal_arrival() -> bool

Check if the robot has successfully reached the current goal.

This method queries the navigation system to determine if the robot has arrived at the goal pose within acceptable position and orientation tolerances. This is particularly useful when using non-blocking navigation mode to poll for completion.

Returns

Type	Description
bool	bool: True if the robot has reached the goal; False if still navigating or no active goal.

note

This method is most useful in non-blocking navigation scenarios where the application needs to monitor progress.

note

The tolerance thresholds for "arrival" are defined by the navigation system's internal parameters (typically a few centimeters in position and a few degrees in orientation).

note

If no navigation command is active, this method returns false.

check_path_reachability

def check_path_reachability(goal_pose: numpy.ArrayLike, start_pose: numpy.ArrayLike) -> bool

Check if a collision-free path exists from start to goal in the map.

This method queries the global path planner to determine if a valid, collision-free path exists between the specified start and goal poses. This is useful for validating goal poses before attempting navigation, or for multi-goal path planning.

Parameters

Name	Type	Default	Description
goal_pose	numpy.ArrayLike	required	Goal pose [x, y, z, qx, qy, qz, qw], map frame.
start_pose	numpy.ArrayLike	required	Start pose [x, y, z, qx, qy, qz, qw], map frame.

Returns

Type	Description
bool	bool: True if a collision-free path exists from start to goal; False otherwise.

note

This method only checks for static obstacles based on the map data. Dynamic obstacles are not considered.

note

The path computation may take some time depending on distance and map complexity.

note

A return value of true does not guarantee successful navigation, as dynamic obstacles or localization errors may still cause failures.

detach_box_from_link

def detach_box_from_link(box_tag: SupportsInt) -> tuple

Detach a box collision object from its robot link.

Removes the attached collision object whose SDK object name is generated from box_tag.

Parameters

Name	Type	Default	Description
box_tag	SupportsInt	required	SDK box tag to detach.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

dump_navigation_configs

def dump_navigation_configs() -> tuple

Dump navigation dynamic configuration for debugging.

This method queries commonly used navigation configuration keys and prints the response through the SDK logger. It is intended for diagnostics and debugging.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

note

The output format depends on the PNS service response and may be JSON or protobuf text format.

get_bounding_box

def get_bounding_box() -> list

Get bounding boxes currently used by navigation obstacle filtering.

Queries the fusion service and converts returned SDK-marked box names back to box_tag values when possible.

Returns

Type	Description
list	list[dict]: Each dict contains box_size, box_pose, box_tag, and parent_link_name.

get_current_pose

def get_current_pose() -> list[float]

Get the current estimated pose of the robot chassis in the map frame.

This method returns the most recent pose estimate from the localization system. The pose represents the position and orientation of the robot's base_link frame relative to the map frame origin.

Returns

Type	Description
list[float]	array: [x, y, z, qx, qy, qz, qw], map frame (meters, unit quaternion). Valid only if is_localized() is True.

note

The returned pose is only valid if is_localized() returns true.

note

The pose represents the center of the robot's base footprint.

get_navigation_status

def get_navigation_status() -> NavigationTaskStatus

Get the current navigation task state.

Returns the latest task state reported by the navigation system. This API is useful when monitoring a navigation task in non-blocking mode.

Returns

Type	Description
NavigationTaskStatus	NavigationTaskStatus: Current task state for non-blocking navigation polling.

note

Useful in non-blocking navigation: loop on get_navigation_status() and break on terminal states or after a timeout.

get_navigation_target_status

def get_navigation_target_status(task_id: str) -> NavigationTaskSnapshot

Query the status of an asynchronous navigation task.

Use this API to check the latest state of a task submitted by an asynchronous navigation interface.

Parameters

Name	Type	Default	Description
task_id	str	required	Task identifier returned by the corresponding navigation API.

Returns

Type	Description
NavigationTaskSnapshot	NavigationTaskSnapshot: Latest known state for the requested task.

init

def init() -> bool

Initialize the navigation subsystem and its dependencies.

This method must be called before using any other navigation functions. It initializes communication channels, loads the map, starts the localization module, and prepares the path planner.

Returns

Type	Description
bool	bool: True if initialization succeeded; False otherwise.

note

This method should only be called once after obtaining the singleton instance.

note

Subsequent calls will return the result of the first initialization attempt.

warning

Calling navigation methods before successful initialization will result in undefined behavior.

is_localized

def is_localized() -> bool

Check whether the robot is currently localized in the map.

This method queries the localization system to determine if the robot has a valid pose estimate with sufficient confidence. A robot that is not localized should not perform navigation tasks.

Returns

Type	Description
bool	bool: True if localized; False if localization is lost or uncertain.

note

It is recommended to check localization status before issuing navigation commands.

note

If this returns false, consider calling relocalize() with a known pose estimate.

move_straight_to

def move_straight_to(
    goal_pose: numpy.ArrayLike,
    is_blocking: bool = True,
    timeout: SupportsFloat = 8
) -> tuple

Move the robot to a relative target pose in the odometry frame.

This method commands the robot to move to a pose specified relative to its current position in the odometry (odom) frame. This is useful for short, precise movements where map-based planning is not needed. Unlike navigate_to_goal(), this method does NOT perform dynamic obstacle detection or global path planning. It uses omnidirectional motion planning for direct movement to the target.

Parameters

Name	Type	Default	Description
goal_pose	numpy.ArrayLike	required	Target pose relative to current base_link [x, y, z, qx, qy, qz, qw], odom frame (meters).
is_blocking	bool	True	If True, blocks until motion is complete or timeout; default True.
timeout	SupportsFloat	8	Maximum wait time in seconds for blocking mode; default 8.0.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str) - success: True if motion succeeded. - status_string: Status string.

note

This method does NOT check for obstacles or collisions. Use only when the path is known to be clear.

note

This method uses the odometry frame and does NOT require map localization.

note

Suitable for small, precise adjustments such as final approach positioning or docking maneuvers.

warning

Since collision checking is disabled, ensure the path is obstacle-free before calling this method to avoid collisions.

warning

Odometry drift may affect accuracy over longer distances. For accurate long-distance navigation, use navigate_to_goal() instead.

navigate_along_trajectory

def navigate_along_trajectory(
    waypoints: Sequence[Pose],
    frame_id: str = 'map',
    speed_ratio: SupportsFloat = 1.0,
    enable_collision_check: bool = True
) -> TaskHandle

Submit a trajectory navigation task using ordered 3D poses.

This API uses the input poses as a trajectory reference. Intermediate poses are not guaranteed to be reached exactly; only the final pose is guaranteed as the navigation goal.

Parameters

Name	Type	Default	Description
waypoints	Sequence[Pose]	required	Ordered pose waypoints.
frame_id	str	'map'	Reference frame, typically "map" or "base_link".
speed_ratio	SupportsFloat	1.0	Velocity scaling factor.
enable_collision_check	bool	True	Whether to enable collision checking.

Returns

Type	Description
TaskHandle	TaskHandle: Submitted task id, request result, and message.

navigate_through_waypoints

def navigate_through_waypoints(
    waypoints: Sequence[Waypoint],
    frame_id: str = 'map',
    enable_collision_check: bool = True
) -> TaskHandle

Submit a multi-waypoint navigation task.

This API sends multiple waypoints in one request and executes them in order.

Parameters

Name	Type	Default	Description
waypoints	Sequence[Waypoint]	required	Ordered waypoint targets.
frame_id	str	'map'	Reference frame, typically "map" or "base_link".
enable_collision_check	bool	True	Whether to enable collision checking.

Returns

Type	Description
TaskHandle	TaskHandle: Submitted task id, request result, and message.

navigate_to_goal

def navigate_to_goal(
    goal_pose: numpy.ArrayLike,
    enable_collision_check: bool = True,
    is_blocking: bool = False,
    timeout: SupportsFloat = 8,
    omni_plan: bool = False
) -> tuple

Navigate the robot to a target goal pose in the map frame.

This method commands the mobile base to navigate to a specified goal pose using the global path planner and local trajectory controller. The planner will compute a collision-free path from the current pose to the goal, considering both static map obstacles and dynamic obstacles if collision checking is enabled.

Parameters

Name	Type	Default	Description
goal_pose	numpy.ArrayLike	required	Target goal pose [x, y, z, qx, qy, qz, qw], map frame (meters, quaternion).
enable_collision_check	bool	True	If True, enables dynamic obstacle detection and avoidance; default True.
is_blocking	bool	False	If True, monitor navigation in the current thread; if False, start a background monitor thread and return after command acceptance; default False.
timeout	SupportsFloat	8	SDK-side navigation monitor timeout in seconds; used by both blocking and non-blocking modes. If timeout expires before navigation stops, SDK calls stop_navigation automatically; default 8.0.
omni_plan	bool	False	If True, omnidirectional motion planning; if False, differential drive; default False. S1 does not support omnidirectional motion planning, so keep this parameter False on S1; setting it to True returns INVALID_INPUT.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str) - success: True if navigation succeeded. - status_string: Status string (SUCCESS, FAIL, TIMEOUT, etc.).

note

The robot must be localized (is_localized() returns true) before calling this method.

note

The navigation request communication timeout is fixed internally and is separate from the SDK-side navigation monitor timeout.

note

In both blocking and non-blocking modes, timeout is used by SDK-side monitoring.

warning

In non-blocking mode, monitor navigation progress separately to detect completion or failures.

navigate_to_goal_v2

def navigate_to_goal_v2(
    goal_pose: numpy.ArrayLike,
    max_vel: numpy.ArrayLike,
    pose_frame: str = 'map',
    enable_collision_check: bool = True,
    is_blocking: bool = False,
    timeout: SupportsFloat = 5.0,
    omni_plan: bool = False
) -> tuple

Navigate the robot to a target goal pose using the navigation v2 interface.

This method sends a navigation v2 planning request to the PNS service. It supports global and local target frames through pose_frame, and applies navigation velocity and runtime timeout configurations before sending the goal request.

Parameters

Name	Type	Default	Description
goal_pose	numpy.ArrayLike	required	Target pose [x, y, z, qx, qy, qz, qw] in pose_frame.
max_vel	numpy.ArrayLike	required	Maximum velocity [vx, vy, vyaw].
pose_frame	str	'map'	Reference frame, "map" or "base_link"; default "map".
enable_collision_check	bool	True	Enable v2 collision checking fields; default True.
is_blocking	bool	False	If True, blocks until goal is reached or timeout; default False.
timeout	SupportsFloat	5.0	Navigation runtime timeout sent to the PNS service; negative means no motion time limit; default 5.0.
omni_plan	bool	False	If True, omnidirectional motion planning; if False, heading-based planning; default False. S1 does not support omnidirectional motion planning, so keep this parameter False on S1; setting it to True returns INVALID_INPUT.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str) - success: True if navigation succeeded. - status_string: Status string (SUCCESS, FAIL, TIMEOUT, etc.).

note

This method uses the navigation v2 topic and protocol.

note

pose_frame currently supports "map" for global goals and "base_link" for local goals.

warning

This method may change navigation control parameters that also affect base control behavior, such as velocity limits and navigation timeout. If the application needs independent low-level base control afterward, set the base control parameters again to override the navigation configuration.

warning

In non-blocking mode, monitor navigation progress separately to detect completion or failures.

navigate_with_velocity

def navigate_with_velocity(
    vx: SupportsFloat,
    vy: SupportsFloat,
    vyaw: SupportsFloat,
    duration_s: SupportsFloat = 3.0,
    enable_collision_check: bool = True
) -> tuple

Navigate the robot with a velocity command using the navigation v2 interface.

This method sends a velocity-based navigation command. The command contains planar base velocity components and a duration; execution duration is handled by the navigation service.

Parameters

Name	Type	Default	Description
vx	SupportsFloat	required	Linear velocity in x direction.
vy	SupportsFloat	required	Linear velocity in y direction.
vyaw	SupportsFloat	required	Angular velocity around z axis.
duration_s	SupportsFloat	3.0	Command duration in seconds. Must be greater than 0.0; default 3.0.
enable_collision_check	bool	True	Enable runtime collision checking; default True.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str) Warning: This API is non-blocking. It returns after the velocity command is accepted, not after the command duration has completed.

note

This method uses the navigation v2 topic and protocol.

note

enable_collision_check is a runtime collision checking flag and is not a complete obstacle-avoidance policy switch.

warning

This method is non-blocking. It returns after the velocity command is accepted, not after the velocity duration has completed.

relocalize

def relocalize(init_pose: numpy.ArrayLike) -> tuple

Perform relocalization to re-estimate the robot's pose in the map frame.

This method resets the localization filter and provides an initial pose estimate to help the robot re-establish its position in the known map. This is useful when the robot has lost localization or when manually placing the robot at a known position.

Parameters

Name	Type	Default	Description
init_pose	numpy.ArrayLike	required	Initial pose estimate [x, y, z, qx, qy, qz, qw], map frame (meters, quaternion).

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str) - success: True if relocalization succeeded. - status_string: Status string (SUCCESS, FAIL, etc.).

note

The robot should be stationary during relocalization for best results.

note

After calling this method, use is_localized() to verify successful relocalization before proceeding with navigation tasks.

remove_bounding_box

def remove_bounding_box(box_tag: SupportsInt) -> tuple

Remove a bounding box from navigation obstacle filtering.

Removes an SDK-created box by its box_tag. The tag is converted to the same SDK-marked box name used by add_bounding_box().

Parameters

Name	Type	Default	Description
box_tag	SupportsInt	required	SDK box tag to remove.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

set_navigation_arrival_threshold

def set_navigation_arrival_threshold(threshold: numpy.ArrayLike) -> tuple

Set the navigation arrival threshold.

This method updates the position and yaw tolerances used by navigation planning and control to determine whether a target has been reached.

Parameters

Name	Type	Default	Description
threshold	numpy.ArrayLike	required	[x_error, y_error, yaw_error].

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

note

Different task types may require different arrival precision. Configure this value before starting the corresponding navigation task.

set_navigation_kinematics_limits

def set_navigation_kinematics_limits(
    vel_limit: numpy.ArrayLike,
    acc_limit: numpy.ArrayLike,
    jerk_limit: numpy.ArrayLike
) -> tuple

Set the navigation kinematic limits.

This method updates navigation velocity, acceleration, and jerk limits through the PNS dynamic configuration interface.

Parameters

Name	Type	Default	Description
vel_limit	numpy.ArrayLike	required	[vx_limit, vy_limit, vyaw_limit].
acc_limit	numpy.ArrayLike	required	[ax_limit, ay_limit, ayaw_limit]. Each element must be in range [0.05, 6.0].
jerk_limit	numpy.ArrayLike	required	[jx_limit, jy_limit, jyaw_limit]. Each element must be in range [0.05, 12.0].

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

note

This configuration is intended to be set before starting a navigation task.

warning

This method may change navigation control parameters that also affect base control behavior. If the application needs independent low-level base control afterward, set the base control parameters again to override the navigation configuration.

set_navigation_target

def set_navigation_target(
    target: Pose,
    frame: str = 'map',
    speed_ratio: SupportsFloat = 1.0,
    enable_collision_check: bool = True
) -> TaskHandle

Submit a dynamic navigation target asynchronously.

This API is designed for targets that may change over time, such as dynamic tracking or remote control. When a new target is submitted, the previous target may be preempted and the navigation system will re-plan toward the latest target.

To keep the navigation stable, do not call this API at a very high rate. Frequent updates may cause planning jitter and reduce motion smoothness.

Parameters

Name	Type	Default	Description
target	Pose	required	Target pose [x, y, z, qx, qy, qz, qw].
frame	str	'map'	Target frame identifier, supported values: "map", "base_link".
speed_ratio	SupportsFloat	1.0	Velocity scaling factor in (0, 1.0].
enable_collision_check	bool	True	Whether to enable collision checking and avoidance.

Returns

Type	Description
TaskHandle	TaskHandle: Submitted task id, request result, and message.

set_navigation_timeout

def set_navigation_timeout(timeout_s: SupportsFloat) -> tuple

Set the navigation timeout configuration.

This method updates the navigation timeout through the PNS dynamic configuration interface. It is useful as a safety guard for tasks that should not run indefinitely.

Parameters

Name	Type	Default	Description
timeout_s	SupportsFloat	required	Navigation timeout in seconds. A value less than or equal to 0 disables the navigation motion time limit.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

note

The exact service-side meaning of this timeout is defined by the PNS navigation service.

set_navigation_velocity_limit

def set_navigation_velocity_limit(vel_limit: numpy.ArrayLike) -> tuple

Set the navigation velocity limit.

This method updates the navigation velocity limit through the PNS dynamic configuration interface.

Parameters

Name	Type	Default	Description
vel_limit	numpy.ArrayLike	required	[vx_limit, vy_limit, vyaw_limit].

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str)

note

This configuration is intended to be set before starting a navigation task.

warning

This method may change navigation control parameters that also affect base control behavior. If the application needs independent low-level base control afterward, set the base control parameters again to override the navigation configuration.

stop_navigation

def stop_navigation() -> tuple

Stop the current navigation task and bring the robot to a halt.

This method immediately cancels any ongoing navigation command (from either navigate_to_goal() or move_straight_to()) and commands the robot to stop. The robot will decelerate according to its kinematic constraints and come to a safe stop.

Returns

Type	Description
tuple	tuple: (success: bool, status_string: str) - success: True if stop command was successfully sent. - status_string: Status string.

note

This method can be called at any time during navigation, including when using non-blocking navigation modes.

note

After stopping, the robot's position may not match the original goal.

note

The robot will attempt to stop smoothly following its acceleration limits.

---

GalbotPerception

Perception module interface; obtain the singleton via get_instance(MachineType).

get_latest_result

def get_latest_result(module: PerceptionModule) -> tuple

Return the latest cached result for the module without blocking.

Parameters

Name	Type	Default	Description
module	PerceptionModule	required	Perception module.

Returns

Type	Description
tuple	tuple[bool, DetectionResult]: (success, result). success is True if a result is available, False if none.

init

def init(enabled_modules: Set[PerceptionModule]) -> bool

Initialize perception and load models for the selected modules.

Parameters

Name	Type	Default	Description
enabled_modules	Set[PerceptionModule]	required	Set of perception modules to enable.

Returns

Type	Description
bool	bool: True if every requested module loaded successfully.

run_once

def run_once(module: PerceptionModule) -> bool

Run a single inference for the given module.

Parameters

Name	Type	Default	Description
module	PerceptionModule	required	Perception module to run.

Returns

Type	Description
bool	bool: True if the command was sent successfully.

note

After init, wait ~10s for models to be ready before calling run_once.

wait_for_new_result

def wait_for_new_result(module: PerceptionModule, timeout_s: SupportsFloat = 5.0) -> bool

Block until the module produces a new result, or timeout. Use with run_once to fetch the latest output.

Parameters

Name	Type	Default	Description
module	PerceptionModule	required	Perception module.
timeout_s	SupportsFloat	5.0	Timeout in seconds (default 5.0).

Returns

Type	Description
bool	bool: True if new data arrived, False on timeout.

---

Types & Enums

ActuateType

Actuation type enumeration.

Specifies which kinematic chains should be actuated during motion planning and execution. This controls whether the robot uses only the target arm, or also involves torso or leg motion.

Enum Value	Description
ACTUATE_TYPE_NUM	Total number of actuation types (for boundary checking or array sizing)
ACTUATE_WITH_CHAIN_ONLY	Actuate only the target joint chain (e.g., arm only), base remains fixed
ACTUATE_WITH_LEG	Actuate target joint chain and legs for mobile manipulation
ACTUATE_WITH_TORSO	Actuate target joint chain and torso for extended workspace

---

AudioData

Audio data structure.

Encapsulates audio event payloads.

Member Variables

Name	Type	Description
data	list[int]	Binary payload; interpretation depends on format: pcm — 2560 bytes per 80 ms chunk; json — UTF-8 text length varies or empty for markers
format	str	Audio format: 'pcm' (16000 Hz, 16-bit, mono) or 'json' (UTF-8 encoded JSON text)
header	Header	Message header: timestamp_ns (data acquisition time in ns since epoch), frame_id (stream or source frame identifier)
type	str	Audio type identifier. Possible values: 'waken_up' (wake-up event, format json, data is JSON string), 'denoise_chunk' (denoised audio, format pcm, data is PCM binary), 'vad_begin' (VAD start marker, data empty), 'vad_chunk' (VAD audio, format pcm, data is PCM binary), 'vad_end' (VAD end marker, data empty)

---

CollisionCheckOption

Collision detection enable/disable configuration.

This structure provides fine-grained control over collision checking during motion planning and execution. It supports independent toggling of self-collision detection (robot links colliding with each other) and environment collision detection (robot colliding with obstacles or workspace boundaries). Disabling collision checks improves computational performance but may result in unsafe trajectories. Use with caution in controlled environments.

get_disable_env_collision_check

def get_disable_env_collision_check() -> bool

Check if environment collision detection is disabled.

Returns

Type	Description
bool	-

get_disable_self_collision_check

def get_disable_self_collision_check() -> bool

Check if self-collision detection is disabled.

Returns

Type	Description
bool	-

print

def print() -> None

Print collision detection configuration to standard output.

Outputs enabled/disabled status for each collision check type.

set_disable_env_collision_check

def set_disable_env_collision_check(disable: bool) -> None

Enable or disable environment collision detection.

Parameters

Name	Type	Default	Description
disable	bool	required	-

warning

Disabling environment checks may result in collisions with obstacles

set_disable_self_collision_check

def set_disable_self_collision_check(disable: bool) -> None

Enable or disable self-collision detection.

Parameters

Name	Type	Default	Description
disable	bool	required	-

warning

Disabling self-collision checks may result in physically infeasible configurations

---

CollisionInfo

Detailed collision information for a reported link pair.

Contains the collision state, involved robot or environment links, distance, and collision metadata returned by the MPS kinematic collision service. collision_type contains the raw MPS collision metadata copied from the response common_str. The current format includes the sample tag and a collision classification whose value is "self" or "env". The default value is "UNKNOWN" for a default-constructed CollisionInfo; an empty service value is returned as an empty string.

Member Variables

Name	Type	Description
collision_type	str	Raw MPS collision metadata copied from common_str. The current format includes the sample tag and a collision classification whose value is self or env.
distance	float	Distance between the reported links, in meters.
is_collision	bool	Whether MPS reports a collision for this link pair.
link1	str	Name of the first link in the reported pair.
link2	str	Name of the second link in the reported pair.

---

ConfigItem

One configuration field to set, addressed by an SDK-defined key within a ConfigService.

See the "Set Config Reference" page in the SDK documentation for the list of supported keys, their types, and valid value ranges per service.

Member Variables

Name	Type	Description
key	str	SDK-defined friendly field identifier (see field registry)

---

ConfigService

Service whose configuration can be modified via set_config().

Configuration is scoped to the current scene. See GalbotRobot::set_config() for details.

Enum Value	Description
CONTROL	SingoriX control service
FRONT_HEAD_CAMERA	Front head camera capture service
LEFT_ARM_CAMERA	Left arm camera capture service
MOTION_PLAN	Motion planning service
NAVIGATION	Navigation planning service
RIGHT_ARM_CAMERA	Right arm camera capture service
SURROUND_CAMERAS	Surround camera capture service; G1-only, rejected on other machine types

---

ControlStatus

Control command execution status enumeration.

Represents the execution status of robot control commands, including joint control, end-effector control, and other motion control operations.

Enum Value	Description
COMM_DISCONNECTED	Communication connection lost, cannot continue execution
DATA_FETCH_FAILED	Data retrieval failed during operation, unable to read required state
FAULT	Fault occurred, system detected anomaly and aborted execution
INIT_FAILED	Initialization failed, internal communication or dependent component creation failed
INVALID_INPUT	Input parameters invalid or not meeting interface requirements
IN_PROGRESS	Command is executing but has not reached target state
PUBLISH_FAIL	Control or state data publication failed, command may not be transmitted
STOPPED_UNREACHED	Stopped during execution without reaching target position or state
SUCCESS	Execution succeeded, command completed with valid result
TIMEOUT	Execution timeout, task not completed within specified time limit

---

DepthData

Depth image data structure.

Contains compressed depth image data from depth cameras or RGB-D sensors. Compatible with ROS 2 sensor_msgs/CompressedImage format with depth extensions.

Member Variables

Name	Type	Description
data	bytes	Compressed depth data
depth_scale	int	Depth scale/quantization factor
format	str	Image format
header	Header	Message header
height	int	Image height
width	int	Image width

---

DetectionAndSegmentationResult

Single-object detection or instance segmentation record (2D box, class, optional mask/keypoints).

Member Variables

Name	Type	Description
bbox	tuple[int, int, int, int]	Bounding box as (x, y, width, height)
class_index	int	Class index
class_name	str	Class name
confidence	float	Confidence score
keypoints	list[tuple[float, float]]	Keypoints as list of (x, y) tuples

---

DetectionResult

Aggregated perception output for one module tick (images, masks, poses, point clouds, etc.).

Member Variables

Name	Type	Description
bounding_boxes	list[tuple[int, int, int, int]]	Bounding boxes as list of (x, y, width, height)
class_indices	list[int]	List of class indices
class_names	list[str]	List of class names
confidences	list[float]	List of confidences
detection_results	list[DetectionAndSegmentationResult]	List of DetectionAndSegmentationResult
grasp_pose_result	list[list[float]]	Grasp pose results
instance_mask	Any	Instance mask as numpy array (HxW or HxWxC), or None if empty
ocr_string	list[str]	OCR results
point_clouds	list	Point clouds as list of Nx3 numpy arrays
running_info	str	Running info string
sensor_name	str	Sensor name
target_point_poses	list[numpy.NDArray[numpy.float32]"]]	4x4 poses from perception proto field target_point_poses (same buffer as target_poses here)
target_poses	list[numpy.NDArray[numpy.float32]"]]	List of 4x4 target pose matrices (C++ targetPoses; perception proto target_point_poses fills this)
timestamp_ns	int	Timestamp in nanoseconds

clear

def clear() -> None

Clear all result fields

get_result_info

def get_result_info() -> str

Get result summary string

Returns

Type	Description
str	-

---

DexhandState

Full dexterous hand state.

Contains timestamped joint feedback and, when available (e.g. Sharpa), per-sensor force/torque measurements from the dexhand force topic. sharpa per finger has 22-joint

Member Variables

Name	Type	Description
force_sensor_map	dict[str, EffortInfo]	Named force sensor map: sensor_name -> EffortInfo (Sharpa; empty for Inspire/BrainCo)
joint_state	JointStateMessage	Dexhand joint state message
timestamp_ns	int	Timestamp (nanoseconds)

---

DexHandType

Dexterous hand model type.

The SDK uses this enumeration to route dexhand commands and state queries to the correct implementation. Inspire-series and BrainCo dexhands share the standard joint command/state path. Sharpa dexhands use a dedicated 22-joint topic interface; full state is returned in DexhandState (including force sensors). Linker Hand L20 uses a dedicated 16-joint path keyed by the dexhand group; like Sharpa, its joint commands and feedback are in radians. INSPIRE is kept as a compatibility alias for historical callers and is treated the same as INSPIRE_RH56F2 in the current implementation.

Enum Value	Description
BRAINCO	BrainCo dexterous hand
INSPIRE	Compatibility alias, implemented as INSPIRE_RH56F2
INSPIRE_RH56DFX	Inspire RH56DFX dexterous hand
INSPIRE_RH56F2	Inspire RH56F2 dexterous hand
LINKER_L20	Linker Hand L20 dexterous hand
SHARPA	Sharpa dexterous hand

---

EffortInfo

6D wrench information (force + torque)

Represents a 6-DOF wrench (force and torque) typically measured by a force/torque sensor. Also known as a spatial force or generalized force.

Member Variables

Name	Type	Description
force	Vector3	Force vector Vector3
timestamp_ns	int	Timestamp (nanoseconds)
torque	Vector3	Torque vector Vector3

---

EncodedVideoData

H.264 encoded video frame data.

Stores one complete encoded frame received from an H.264 camera topic.

Member Variables

Name	Type	Description
data	bytes	Encoded video frame bytes
format	str	Video format
header	Header	Message header

---

Error

Error information.

Describes an error from a single module or component, including error code and human-readable description for debugging and diagnostics.

Member Variables

Name	Type	Description
commpent	str	Fault component name
description	str	Human-readable error description
error_code	int	Numerical error code

---

ErrorInfo

Error information collection.

Contains a timestamped collection of error messages from multiple modules or components.

Member Variables

Name	Type	Description
error_vec	list[Error]	List of error entries
timestamp_ns	int	Collection timestamp in nanoseconds

---

ForceData

Force sensor data.

Contains timestamped force and torque measurements from a 6-axis force/torque sensor, typically mounted at robot wrists or tool interfaces.

Member Variables

Name	Type	Description
force	Vector3	Force vector Vector3
timestamp_ns	int	Timestamp (nanoseconds)
torque	Vector3	Torque vector Vector3

---

FrameTriad

Task-space command for a body frame relative to a reference frame.

Mirrors galbot.spatial_proto.FrameTriad at the SDK type layer.

Member Variables

Name	Type	Description
body_frame_id	str	Body frame id
header	Header	Message header
pose	Pose	None
reference_frame_id	str	Reference frame id
twist	Twist	None
wrench	Wrench	None

---

G1ControllerName

Controller-name constants for the G1 robot.

Pass these names to GalbotRobot controller-management APIs such as switch_controller() and acquire_controller(). A controller selects how one hardware group interprets subsequent targets; controllers registered for the same group are mutually exclusive. Switching a controller does not itself command motion. Controller availability depends on the robot model, installed end tool, and the server-side SingoriX configuration. A successful switch confirms that the selected controller is available on the connected robot.

Enum Value	Description
CHASSIS_POSE_CTRL	Closed-loop chassis pose and path controller. Tracks planar position/orientation targets or paths using localization or odometry feedback, generates limited chassis velocity commands, and reports goal completion. Use this controller for navigation and pose goals. Unlike CHASSIS_TWIST_CTRL, it performs pose/path tracking and arrival checks.
CHASSIS_TWIST_CTRL	Direct chassis velocity controller. Tracks planar velocity commands [vx, vy, wz] with configured filtering and velocity/acceleration limits. Use this controller for continuous velocity control such as teleoperation. It does not track a destination or determine whether a pose goal has been reached.
CONTROLLER_NAME_NUM	Sentinel indicating that no valid controller name is available. This value may be returned when the SDK has no known active controller for a group. It is not a controller and must not be passed as a switch target.
HEAD_PVT_BYPASS_CTRL	Buffered streaming position-trajectory controller for the head. Streams head joint-position points through the MCU trajectory queue with interpolation, lookahead, refill, and optional joint-position limiting. It is the head counterpart of LEG_PVT_BYPASS_CTRL and is intended for high-rate position streams rather than regular per-cycle PVT commands.
HEAD_PVT_CTRL	Regular joint PVT controller for the head. Publishes sampled head joint position, velocity, and effort commands every control cycle using configured PID, filters, and limits. Use it for normal head positioning and planned head trajectories.
LEFT_ARM_PVT_BYPASS_CTRL	Buffered streaming position-trajectory controller for the left arm. Streams left-arm joint-position points through the MCU trajectory queue with interpolation, lookahead, refill, and optional joint-position limiting. Use it for high-rate online or precomputed position streams; use LEFT_ARM_PVT_CTRL for regular position/velocity/effort trajectories.
LEFT_ARM_PVT_CTRL	Regular joint PVT controller for the left arm. Publishes sampled left-arm joint position, velocity, and effort commands every control cycle using configured PID, filters, and limits. This is the standard controller for ordinary joint-space and planned arm motion.
LEFT_DEXHAND_CTRL	Multi-axis left dexterous-hand controller. Converts logical left-hand joint positions to the installed hand's raw gesture layout and sends a multi-axis finger command. Joint count, mapping, range, and unit conversion depend on the configured dexterous-hand model. Use LEFT_GRIPPER_CTRL instead for a simple gripper opening command.
LEFT_GRIPPER_CTRL	Left gripper opening controller. Sends the left gripper position/opening command together with optional velocity and effort parameters, applying the configured hardware mode and unit conversion. It controls a gripper as one end-tool action, unlike LEFT_DEXHAND_CTRL, which controls multiple finger axes.
LEG_HEIGHT_CTRL	Task-space body-height controller using the leg mechanism. Accepts a vertical height target for a configured body link, solves a coordinated posture for the first three leg joints, and generates a bounded-jerk joint trajectory. The remaining leg joints can retain independent joint targets. Use it to raise or lower the body by height; use LEG_PVT_CTRL when explicit leg joint positions are required.
LEG_PVT_BYPASS_CTRL	Buffered streaming position-trajectory controller for the leg. Streams leg joint-position points through the MCU trajectory queue with interpolation, lookahead, refill, and optional joint-position limiting. Use it for high-rate online or precomputed position streams. "Bypass" identifies this trajectory data path; it does not bypass controller ownership or hardware safety. Unlike LEG_PVT_CTRL, it does not publish the regular position/velocity/effort command tuple on every control cycle.
LEG_PVT_CTRL	Regular joint PVT controller for the leg. Publishes sampled leg joint position, velocity, and effort commands every control cycle using the configured PID, filters, and limits. Use it for explicit leg joint targets and ordinary planned joint trajectories. Unlike LEG_HEIGHT_CTRL, its primary target is joint motion rather than body height.
RIGHT_ARM_PVT_BYPASS_CTRL	Buffered streaming position-trajectory controller for the right arm. Streams right-arm joint-position points through the MCU trajectory queue with interpolation, lookahead, refill, and optional joint-position limiting. Use it for high-rate online or precomputed position streams; use RIGHT_ARM_PVT_CTRL for regular position/velocity/effort trajectories.
RIGHT_ARM_PVT_CTRL	Regular joint PVT controller for the right arm. Publishes sampled right-arm joint position, velocity, and effort commands every control cycle using configured PID, filters, and limits. This is the standard controller for ordinary joint-space and planned arm motion.
RIGHT_DEXHAND_CTRL	Multi-axis right dexterous-hand controller. Converts logical right-hand joint positions to the installed hand's raw gesture layout and sends a multi-axis finger command. Joint count, mapping, range, and unit conversion depend on the configured dexterous-hand model. Use RIGHT_GRIPPER_CTRL instead for a simple gripper opening command.
RIGHT_GRIPPER_CTRL	Right gripper opening controller. Sends the right gripper position/opening command together with optional velocity and effort parameters, applying the configured hardware mode and unit conversion. It controls a gripper as one end-tool action, unlike RIGHT_DEXHAND_CTRL, which controls multiple finger axes.

---

G1JointGroup

Galbot G1 joint-group names.

A "joint group" is the SDK's primary control/planning unit, not a single joint: Kinematic-consistent control: commands are validated and executed per chain/end-effector group. Deterministic command ordering: joint_groups are expanded to concrete joint_names in group order. Group-level behavior: each group has its own active/passive attribute and execution tolerance. Recommended usage: Use constants in this struct when filling API parameters such as joint_groups. If exact joint names are needed, query them at runtime via get_joint_names(true, {group_name}) instead of hard-coding. In APIs that accept both joint_groups and joint_names, joint_names takes precedence.

Enum Value	Description
chassis	Chassis mechanism group (passive in joint-position control). Default joints: chassis_joint1 ... chassis_joint4. Typical use: chassis state grouping; base motion should use base APIs.
head	Head chain. Default joints: head_joint1, head_joint2. Typical use: gaze/camera orientation.
left_arm	Left 7-DoF arm chain. Default joints: left_arm_joint1 ... left_arm_joint7. Typical use: left-arm reaching/manipulation.
left_dexhand	Left dexterous hand group. Default joints: left_dexhand_joint1 ... left_dexhand_joint6. Typical use: multi-finger dexterous manipulation (left).
left_gripper	Left gripper chain. Default joint: left_gripper_joint1. Typical use: left gripper open/close and grasp width.
left_suction_cup	Left suction-cup end-effector group. Default joint: left_suction_cup_joint1. Typical use: vacuum pick/place on left arm.
leg	Leg chain. Default joints: leg_joint1 ... leg_joint5. Typical use: lower-body posture/locomotion-related body control.
right_arm	Right 7-DoF arm chain. Default joints: right_arm_joint1 ... right_arm_joint7. Typical use: right-arm reaching/manipulation.
right_dexhand	Right dexterous hand group. Default joints: right_dexhand_joint1 ... right_dexhand_joint6. Typical use: multi-finger dexterous manipulation (right).
right_gripper	Right gripper chain. Default joint: right_gripper_joint1. Typical use: right gripper open/close and grasp width.
right_suction_cup	Right suction-cup end-effector group. Default joint: right_suction_cup_joint1. Typical use: vacuum pick/place on right arm.

---

GalbotOneFoxtrotSensor

Force sensor enumeration describing robot wrist force sensors.

Identifies force/torque sensors mounted at the robot's wrist joints for force-controlled manipulation and contact detection.

Enum Value	Description
LEFT_WRIST_FORCE	Left wrist force/torque sensor, typically 6-axis (3 forces + 3 torques)
RIGHT_WRIST_FORCE	Right wrist force/torque sensor, typically 6-axis (3 forces + 3 torques)

---

GripperState

Gripper state.

Represents the current state of a parallel-jaw gripper, including opening width, motion status, and grasping force.

Member Variables

Name	Type	Description
effort	float	Gripper torque (newton-meters)
is_moving	bool	Whether currently moving
joint_positions	list[float]	Joint positions array
timestamp_ns	int	Timestamp (nanoseconds)
velocity	float	Gripper velocity (meters/second)
width	float	Gripper width (meters)

---

GroupCommand

Group-space command at a specific time point.

Member Variables

Name	Type	Description
joint_commands	list[JointCommand]	Joint commands at this point
time_from_start_s	float	Time from trajectory start in seconds

---

Header

Message header structure.

Standard message header containing timestamp and coordinate frame information. Timestamp is stored as nanoseconds since epoch (unified with other sensor types).

Member Variables

Name	Type	Description
frame_id	str	Frame ID
timestamp_ns	int	Timestamp (nanoseconds since epoch)

---

IKSolverConfig

Inverse kinematics (IK) solver configuration parameters.

This structure configures the numerical inverse kinematics solver used to compute joint configurations that achieve desired end-effector poses. It supports collision-aware IK with configurable seed strategies, convergence tolerances, joint limit handling, and timeout parameters. IK solving is an iterative numerical optimization process that may benefit from multiple random initializations to find feasible collision-free solutions.

get_col_aware_ik_joint_limit_bias

def get_col_aware_ik_joint_limit_bias() -> float

Get joint limit safety margin.

Returns

Type	Description
float	-

get_col_aware_ik_timeout

def get_col_aware_ik_timeout() -> float

Get collision-aware IK solver timeout.

Returns

Type	Description
float	-

get_enable_collision_check_log

def get_enable_collision_check_log() -> bool

Check if collision check logging is enabled.

Returns

Type	Description
bool	-

get_rotation_eps

def get_rotation_eps() -> list[float]

Get orientation error tolerance.

Returns

Type	Description
list[float]	-

get_seed_type

def get_seed_type() -> SeedType

Get IK solver seed generation strategy.

Returns

Type	Description
SeedType	-

get_translation_eps

def get_translation_eps() -> list[float]

Get Cartesian position error tolerance.

Returns

Type	Description
list[float]	-

print

def print() -> None

Print IK solver configuration to standard output.

Outputs all configuration parameters for debugging and verification.

set_col_aware_ik_joint_limit_bias

def set_col_aware_ik_joint_limit_bias(bias: SupportsFloat) -> None

Set safety margin from joint position limits.

Parameters

Name	Type	Default	Description
bias	SupportsFloat	required	-

note

Prevents IK solver from proposing configurations near singularities or mechanical limits

set_col_aware_ik_timeout

def set_col_aware_ik_timeout(timeout: SupportsFloat) -> None

Set timeout for collision-aware IK solver.

Parameters

Name	Type	Default	Description
timeout	SupportsFloat	required	-

note

Longer timeouts allow more seed attempts but delay planning

set_enable_collision_check_log

def set_enable_collision_check_log(enable: bool) -> None

Enable or disable detailed collision checking diagnostic logs.

Parameters

Name	Type	Default	Description
enable	bool	required	-

note

Useful for debugging IK failures due to collision constraints

set_rotation_eps

def set_rotation_eps(eps: list[float]) -> None

Set orientation error tolerance for IK convergence.

Parameters

Name	Type	Default	Description
eps	list[float]	required	-

note

IK solution is accepted when orientation error is within this threshold

set_seed_type

def set_seed_type(type: SeedType) -> None

Set initial configuration seed generation strategy.

Parameters

Name	Type	Default	Description
type	SeedType	required	-

set_translation_eps

def set_translation_eps(eps: list[float]) -> None

Set Cartesian position error tolerance for IK convergence.

Parameters

Name	Type	Default	Description
eps	list[float]	required	-

note

IK solution is accepted when position error is within this threshold

---

ImuData

IMU data structure.

Contains timestamped data from an Inertial Measurement Unit (IMU), including accelerometer, gyroscope, and magnetometer measurements.

Member Variables

Name	Type	Description
accel	Vector3	Acceleration Vector3
gyro	Vector3	Gyroscope Vector3
magnet	Vector3	Magnetometer Vector3
timestamp_ns	int	Timestamp (nanoseconds)

---

JointCommand

Single joint control command.

Specifies desired motion parameters for a single robot joint in a trajectory or control command.

Member Variables

Name	Type	Description
acceleration	float	- acceleration (float): Joint acceleration
effort	float	- effort (float): Joint torque (N·m)
position	float	- position (float): Joint target position (radians)
velocity	float	- velocity (float): Joint velocity (radians/second)

---

JointState

Single joint state structure.

Represents the complete real-time state of a single robot joint, including joint identity and sampling time metadata, plus kinematic quantities (position, velocity, acceleration) and dynamic quantities (torque/effort and motor current).

Member Variables

Name	Type	Description
acceleration	float	-
current	float	-
effort	float	-
position	float	-
timestamp_ns	int	-
velocity	float	-

---

JointStateMessage

Joint state message structure.

Timestamped collection of joint states for multiple joints, typically representing a snapshot of the robot's complete joint configuration at one instant.

Member Variables

Name	Type	Description
joint_state_vec	list[JointState]	Joint state list
timestamp_ns	int	Timestamp (nanoseconds)

---

JointStates

Joint-space target specification.

Represents target joint configuration for a kinematic chain. Extends RobotStates to specify joint-based motion goals. Used in joint trajectory planning and forward kinematics computation. All joint angles must be in radians. Vector size must match the DOF of the specified kinematic chain.

Member Variables

Name	Type	Description
joint_names	list[str]	-
joint_positions	list[float]	-

get_type

def get_type() -> RobotStatesType

Get runtime type identifier.

Returns

Type	Description
RobotStatesType	-

set_joint

def set_joint(index: SupportsInt, val: SupportsInt) -> None

Set individual joint angle by index.

Parameters

Name	Type	Default	Description
index	SupportsInt	required	-
val	SupportsInt	required	-

note

Function performs bounds checking; invalid indices are silently ignored.

warning

No error is returned for out-of-bounds access; ensure index validity externally.

set_joint_positions

def set_joint_positions(joints: list[float]) -> None

Set complete joint configuration for the kinematic chain.

Parameters

Name	Type	Default	Description
joints	list[float]	required	-

note

Vector size should equal the number of actuated joints in the specified chain.

---

KinematicsBoundary

Kinematic boundary parameters for robot kinematic chain joints.

This structure defines the kinematic constraints for a robot kinematic chain (e.g., manipulator arms, mobile base, or leg chains). It specifies position, velocity, acceleration, and jerk limits for each joint in the chain. These boundaries are critical for ensuring safe and physically feasible motion during trajectory planning and execution. Each vector should contain one value per joint in the kinematic chain. All joint space quantities are specified in radians or radians per unit time.

get_acc_lower_limit

def get_acc_lower_limit() -> list[float]

Get joint acceleration lower bounds.

Returns

Type	Description
list[float]	-

get_acc_upper_limit

def get_acc_upper_limit() -> list[float]

Get joint acceleration upper bounds.

Returns

Type	Description
list[float]	-

get_chain_name

def get_chain_name() -> str

Get the kinematic chain name identifier.

Returns

Type	Description
str	-

get_jerk_lower_limit

def get_jerk_lower_limit() -> list[float]

Get joint jerk lower bounds.

Returns

Type	Description
list[float]	-

get_jerk_upper_limit

def get_jerk_upper_limit() -> list[float]

Get joint jerk upper bounds.

Returns

Type	Description
list[float]	-

get_lower_limit

def get_lower_limit() -> list[float]

Get joint position lower bounds.

Returns

Type	Description
list[float]	-

get_upper_limit

def get_upper_limit() -> list[float]

Get joint position upper bounds.

Returns

Type	Description
list[float]	-

get_vel_lower_limit

def get_vel_lower_limit() -> list[float]

Get joint velocity lower bounds.

Returns

Type	Description
list[float]	-

get_vel_upper_limit

def get_vel_upper_limit() -> list[float]

Get joint velocity upper bounds.

Returns

Type	Description
list[float]	-

print

def print() -> None

Print kinematic boundary information to standard output.

Outputs all boundary parameters for debugging and visualization purposes.

set_acc_lower_limit

def set_acc_lower_limit(limits: list[float]) -> None

Set joint acceleration lower bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Used for trajectory optimization and smoothness constraints

set_acc_upper_limit

def set_acc_upper_limit(limits: list[float]) -> None

Set joint acceleration upper bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Used for trajectory optimization and smoothness constraints

set_chain_name

def set_chain_name(name: str) -> None

Set the name identifier for this kinematic chain.

Parameters

Name	Type	Default	Description
name	str	required	-

set_jerk_lower_limit

def set_jerk_lower_limit(limits: list[float]) -> None

Set joint jerk lower bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Jerk constraints improve motion smoothness and reduce mechanical wear

set_jerk_upper_limit

def set_jerk_upper_limit(limits: list[float]) -> None

Set joint jerk upper bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Jerk constraints improve motion smoothness and reduce mechanical wear

set_lower_limit

def set_lower_limit(limits: list[float]) -> None

Set joint position lower bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Vector size must equal the number of joints in the chain

set_upper_limit

def set_upper_limit(limits: list[float]) -> None

Set joint position upper bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Vector size must equal the number of joints in the chain

set_vel_lower_limit

def set_vel_lower_limit(limits: list[float]) -> None

Set joint velocity lower bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Typically negative values for bidirectional joints

set_vel_upper_limit

def set_vel_upper_limit(limits: list[float]) -> None

Set joint velocity upper bounds.

Parameters

Name	Type	Default	Description
limits	list[float]	required	-

note

Typically positive values for bidirectional joints

---

LidarData

Lidar data structure.

Generic N-dimensional point cloud structure compatible with ROS 2 sensor_msgs/PointCloud2. Stores point data as a binary blob with field descriptors defining the data layout. Supports both ordered (structured) and unordered (unstructured) point clouds.

Member Variables

Name	Type	Description
data	list[int]	Point cloud binary data
fields	list[PointField]	Point field description list
header	Header	Message header
height	int	Point cloud height
is_bigendian	bool	Whether big-endian
is_dense	bool	Whether dense
point_step	int	Bytes per point
row_step	int	Bytes per row
width	int	Point cloud width

---

LineTrajCheckPrimitive

Geometric primitive configuration for Cartesian linear trajectory validation.

This structure configures the collision detection geometric representation for linear end-effector trajectories in Cartesian space. It supports two primitive types: infinitesimally thin lines and swept-volume cylinders. Choosing the appropriate primitive affects collision detection conservativeness and computational cost. Cylinder primitives model the robot's actual swept volume more accurately but require more expensive geometric queries.

get_cylinder_prim_radius

def get_cylinder_prim_radius() -> float

Get the cylinder primitive swept-volume radius.

Returns

Type	Description
float	-

get_line_check_primitive_type

def get_line_check_primitive_type() -> PrimitiveType

Get the geometric primitive type for trajectory checking.

Returns

Type	Description
PrimitiveType	-

get_line_prim_curvature

def get_line_prim_curvature() -> float

Get the line primitive curvature approximation tolerance.

Returns

Type	Description
float	-

print

def print() -> None

Print line trajectory check primitive configuration to standard output.

Outputs selected primitive type and associated parameters for debugging.

set_cylinder_prim_radius

def set_cylinder_prim_radius(radius: SupportsFloat) -> None

Set swept-volume cylinder radius for trajectory collision checking.

Parameters

Name	Type	Default	Description
radius	SupportsFloat	required	-

note

Larger radii increase safety margins but may be overly conservative

note

Only applies when primitive type is CYLINDER

set_line_check_primitive_type

def set_line_check_primitive_type(type: PrimitiveType) -> None

Set geometric primitive type for linear trajectory validation.

Parameters

Name	Type	Default	Description
type	PrimitiveType	required	-

note

CYLINDER is recommended for safety-critical applications

set_line_prim_curvature

def set_line_prim_curvature(curvature: SupportsFloat) -> None

Set curvature approximation tolerance for line primitive.

Parameters

Name	Type	Default	Description
curvature	SupportsFloat	required	-

note

Controls how finely curved paths are discretized into line segments

note

Lower values improve accuracy but increase computational cost

---

LogLevel

Log level enumeration.

Represents the severity level of log messages.

Enum Value	Description
CRITICAL	Critical level, severe error events that lead to application termination
DEBUG	Debug level, diagnostic information for developers
ERROR	Error level, error events that might still allow the application to continue running
INFO	Info level, general operational messages
TRACE	Trace level, detailed information for debugging
WARN	Warn level, potentially harmful situations

---

MachineType

Supported robot machine types.

This enumeration defines the different robot platforms or machine types supported by the Galbot SDK. Clients can use these values to specify which robot model they are working with, particularly for factory methods that return platform-specific implementations. Keeping the enumeration in the common type definitions ensures consistency across the SDK while hiding implementation details in the respective modules.

Enum Value	Description
G1	Galbot G1 humanoid robot platform
G3	Galbot G3 humanoid robot platform
S1	Galbot S1 humanoid robot platform

---

MotionPlanChainTarget

Target for one kinematic chain at a single path waypoint.

Selects either a joint-space or Cartesian-space target for the named chain. Multiple MotionPlanChainTarget objects can be grouped into one MotionPlanWaypoint to coordinate several chains at the same path waypoint.

Member Variables

Name	Type	Description
cart	PoseState	Cartesian-space target used when mode is MotionPlanTargetMode.kCartesian.
chain_name	str	Name of the kinematic chain targeted at this waypoint.
joint	JointStates	Joint-space target used when mode is MotionPlanTargetMode.kJoint.
mode	MotionPlanTargetMode	Selects the active target representation.

---

MotionPlanConfig

Comprehensive motion planning configuration management.

MotionPlanConfig serves as a centralized configuration container for all motion planning subsystems. It aggregates sampling strategies, trajectory generation parameters, inverse kinematics solver settings, collision detection options, feasibility validation criteria, and kinematic constraint boundaries. This class provides a unified interface for configuring complex motion planning pipelines, supporting both simple manipulator planning and whole-body humanoid motion generation with multiple kinematic chains. Configuration objects are lazily initialized and managed through shared pointers to optimize memory usage and support optional feature configuration.

create_collision_check_option

def create_collision_check_option() -> CollisionCheckOption

Create or retrieve collision check option configuration.

Lazily initializes the collision check options if they do not exist.

Returns

Type	Description
CollisionCheckOption	-

create_ik_solver_config

def create_ik_solver_config() -> IKSolverConfig

Create or retrieve inverse kinematics solver configuration.

Lazily initializes the IK solver configuration if it does not exist.

Returns

Type	Description
IKSolverConfig	-

create_line_traj_check_primitive

def create_line_traj_check_primitive() -> LineTrajCheckPrimitive

Create or retrieve line trajectory check primitive configuration.

Lazily initializes the line trajectory check primitive configuration if it does not exist.

Returns

Type	Description
LineTrajCheckPrimitive	-

create_sampler_config

def create_sampler_config() -> SamplerConfig

Create or retrieve sampler configuration.

Lazily initializes the sampler configuration if it does not exist. Safe to call multiple times; returns the same instance after first creation.

Returns

Type	Description
SamplerConfig	-

create_trajectory_feasibility_check_option

def create_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

Create or retrieve trajectory feasibility check option configuration.

Lazily initializes the trajectory feasibility check options if they do not exist.

Returns

Type	Description
TrajectoryFeasibilityCheckOption	-

create_trajectory_plan_config

def create_trajectory_plan_config() -> TrajectoryPlanConfig

Create or retrieve trajectory planning configuration.

Lazily initializes the trajectory planning configuration if it does not exist.

Returns

Type	Description
TrajectoryPlanConfig	-

get_collision_check_option

def get_collision_check_option() -> CollisionCheckOption

Get collision check option configuration (may be nullptr if not initialized)

Returns

Type	Description
CollisionCheckOption	-

note

Use create_collision_check_option() to ensure a valid configuration exists

get_collision_check_option_ref

def get_collision_check_option_ref() -> CollisionCheckOption

Get mutable reference to collision check option configuration.

Lazily creates a new collision check option with default values if not already initialized.

Returns

Type	Description
CollisionCheckOption	-

get_feasibility_boundary

def get_feasibility_boundary() -> list[KinematicsBoundary]

Get kinematic feasibility boundaries for all chains (mutable)

Returns mutable access to the feasibility boundary configuration for in-place modification.

Returns

Type	Description
list[KinematicsBoundary]	-

get_hard_joint_limit

def get_hard_joint_limit() -> list[KinematicsBoundary]

Get hard joint limits (mutable)

Returns

Type	Description
list[KinematicsBoundary]	-

get_ik_joint_limit

def get_ik_joint_limit() -> list[KinematicsBoundary]

Get IK phase joint limits (mutable)

Returns

Type	Description
list[KinematicsBoundary]	-

get_ik_solver_config

def get_ik_solver_config() -> IKSolverConfig

Get inverse kinematics solver configuration (may be nullptr if not initialized)

Returns

Type	Description
IKSolverConfig	-

note

Use create_ik_solver_config() to ensure a valid configuration exists

get_ik_solver_config_ref

def get_ik_solver_config_ref() -> IKSolverConfig

Get mutable reference to inverse kinematics solver configuration.

Lazily creates a new IK solver configuration with default values if not already initialized.

Returns

Type	Description
IKSolverConfig	-

get_line_traj_check_primitive

def get_line_traj_check_primitive() -> LineTrajCheckPrimitive

Get line trajectory check primitive configuration (may be nullptr if not initialized)

Returns

Type	Description
LineTrajCheckPrimitive	-

note

Use create_line_traj_check_primitive() to ensure a valid configuration exists

get_line_traj_check_primitive_ref

def get_line_traj_check_primitive_ref() -> LineTrajCheckPrimitive

Get mutable reference to line trajectory check primitive configuration.

Lazily creates a new line trajectory check primitive with default values if not already initialized.

Returns

Type	Description
LineTrajCheckPrimitive	-

get_revert_ik_joint_limit

def get_revert_ik_joint_limit() -> bool

Check if IK joint limit reversion is enabled.

Returns

Type	Description
bool	-

get_revert_ik_joint_limit_chains

def get_revert_ik_joint_limit_chains() -> list[str]

Get kinematic chains for selective IK joint limit reversion (mutable)

Returns

Type	Description
list[str]	-

get_sampler_config

def get_sampler_config() -> SamplerConfig

Get sampler configuration (may be nullptr if not initialized)

Returns

Type	Description
SamplerConfig	-

note

Use create_sampler_config() to ensure a valid configuration exists

get_sampler_config_ref

def get_sampler_config_ref() -> SamplerConfig

Get mutable reference to sampler configuration.

Lazily creates a new sampler configuration with default values if not already initialized. Useful for in-place modification of configuration parameters.

Returns

Type	Description
SamplerConfig	-

get_sampler_joint_limit

def get_sampler_joint_limit() -> list[KinematicsBoundary]

Get sampling phase joint limits (mutable)

Returns

Type	Description
list[KinematicsBoundary]	-

get_trajectory_feasibility_check_option

def get_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

Get trajectory feasibility check option configuration (may be nullptr if not initialized)

Returns

Type	Description
TrajectoryFeasibilityCheckOption	-

note

Use create_trajectory_feasibility_check_option() to ensure a valid configuration exists

get_trajectory_feasibility_check_option_ref

def get_trajectory_feasibility_check_option_ref() -> TrajectoryFeasibilityCheckOption

Get mutable reference to trajectory feasibility check option configuration.

Lazily creates a new trajectory feasibility check option with default values if not already initialized.

Returns

Type	Description
TrajectoryFeasibilityCheckOption	-

get_trajectory_plan_config

def get_trajectory_plan_config() -> TrajectoryPlanConfig

Get trajectory planning configuration (may be nullptr if not initialized)

Returns

Type	Description
TrajectoryPlanConfig	-

note

Use create_trajectory_plan_config() to ensure a valid configuration exists

get_trajectory_plan_config_ref

def get_trajectory_plan_config_ref() -> TrajectoryPlanConfig

Get mutable reference to trajectory planning configuration.

Lazily creates a new trajectory planning configuration with default values if not already initialized.

Returns

Type	Description
TrajectoryPlanConfig	-

get_update_time

def get_update_time() -> int

Get configuration update timestamp.

Returns

Type	Description
int	-

print

def print() -> None

Print comprehensive motion planning configuration to standard output.

Outputs all sub-configuration parameters and kinematic boundaries in human-readable format. Useful for debugging, logging, and verification of configuration state.

set_collision_check_option

def set_collision_check_option(option: CollisionCheckOption) -> None

Set or replace collision check option configuration.

Parameters

Name	Type	Default	Description
option	CollisionCheckOption	required	-

set_feasibility_boundary

def set_feasibility_boundary(boundary: Sequence[KinematicsBoundary]) -> None

Set kinematic feasibility boundaries for all chains.

Parameters

Name	Type	Default	Description
boundary	Sequence[KinematicsBoundary]	required	-

note

These boundaries are used for general trajectory feasibility validation

set_hard_joint_limit

def set_hard_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

Set absolute hard joint limits (safety-critical boundaries)

Parameters

Name	Type	Default	Description
boundary	Sequence[KinematicsBoundary]	required	-

note

Hard limits must never be violated; typically correspond to physical joint stops

set_ik_joint_limit

def set_ik_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

Set joint limits used during IK solving phase.

Parameters

Name	Type	Default	Description
boundary	Sequence[KinematicsBoundary]	required	-

note

IK limits may be tighter than hard limits to improve convergence and avoid singularities

set_ik_solver_config

def set_ik_solver_config(config: IKSolverConfig) -> None

Set or replace inverse kinematics solver configuration.

Parameters

Name	Type	Default	Description
config	IKSolverConfig	required	-

set_line_traj_check_primitive

def set_line_traj_check_primitive(primitive: LineTrajCheckPrimitive) -> None

Set or replace line trajectory check primitive configuration.

Parameters

Name	Type	Default	Description
primitive	LineTrajCheckPrimitive	required	-

set_revert_ik_joint_limit

def set_revert_ik_joint_limit(flag: bool) -> None

Enable or disable IK joint limit reversion to hard limits.

Parameters

Name	Type	Default	Description
flag	bool	required	-

note

Useful for recovering from constrained configurations by temporarily relaxing IK limits

set_revert_ik_joint_limit_chains

def set_revert_ik_joint_limit_chains(chains: Sequence[str]) -> None

Set specific kinematic chains for IK joint limit reversion.

Parameters

Name	Type	Default	Description
chains	Sequence[str]	required	-

note

If non-empty, automatically enables revert_ik_joint_limit flag

note

Empty vector disables selective reversion (applies to all chains if flag is set)

set_sampler_config

def set_sampler_config(config: SamplerConfig) -> None

Set or replace sampler configuration.

Parameters

Name	Type	Default	Description
config	SamplerConfig	required	-

set_sampler_joint_limit

def set_sampler_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

Set joint limits used during sampling-based planning phase.

Parameters

Name	Type	Default	Description
boundary	Sequence[KinematicsBoundary]	required	-

note

Sampling limits define the valid configuration space for exploration

set_trajectory_feasibility_check_option

def set_trajectory_feasibility_check_option(option: TrajectoryFeasibilityCheckOption) -> None

Set or replace trajectory feasibility check option configuration.

Parameters

Name	Type	Default	Description
option	TrajectoryFeasibilityCheckOption	required	-

set_trajectory_plan_config

def set_trajectory_plan_config(config: TrajectoryPlanConfig) -> None

Set or replace trajectory planning configuration.

Parameters

Name	Type	Default	Description
config	TrajectoryPlanConfig	required	-

set_update_time

def set_update_time(t: SupportsInt) -> None

Set configuration update timestamp.

Parameters

Name	Type	Default	Description
t	SupportsInt	required	-

note

Used for configuration versioning and cache invalidation

---

MotionPlanTargetMode

Representation used by a single-chain motion-plan target.

Enum Value	Description
kCartesian	Use the Cartesian target stored in MotionPlanChainTarget::cart.
kJoint	Use the joint-space target stored in MotionPlanChainTarget::joint.

---

MotionPlanType

Planning algorithm used for a segment of a combined motion plan.

Enum Value	Description
MOTION_PLAN	Sampling-based, collision-aware path planning.
MOVE_LINE	Cartesian straight-line interpolation with inverse-kinematics sampling.
TRAJ_PLAN	Direct joint-space trajectory interpolation without path search.

---

MotionStatus

Robot motion execution status enumeration.

Represents the execution status of robot motion commands, including trajectory following, pose reaching, and other motion planning operations.

Enum Value	Description
COMM_DISCONNECTED	Communication disconnected or control node unavailable
DATA_FETCH_FAILED	Data retrieval failed, e.g., sensor or state reading failure
FAULT	Fault occurred, motion cannot continue due to hardware or safety issue
INIT_FAILED	Internal initialization failed, communication component or resource creation failed
INVALID_INPUT	Input parameters invalid or not meeting interface requirements
IN_PROGRESS	Motion in progress but has not reached target yet
PUBLISH_FAIL	Data transmission or command delivery failed, motion command may not be executed
STATUS_NUM	Total number of status enumerations (for boundary checking or array sizing)
STOPPED_UNREACHED	Stopped during motion without reaching target position/pose
SUCCESS	Execution succeeded, motion reached expected target position/pose
TIMEOUT	Execution timeout, motion not completed within specified time limit
UNSUPPORTED_FUNCRION	Function not yet supported, called interface or operation not implemented (note: typo in enum name preserved for API compatibility)

---

NavigationTaskSnapshot

Snapshot of a navigation task.

This object is returned by task status query APIs. It contains the task id, the latest known task state, and a short human-readable message.

---

NavigationTaskStatus

Navigation task state.

This enum describes the current state of a navigation task that has been submitted to the SDK. It is used by both legacy navigation polling and the asynchronous target status query API.

Enum Value	Description
CLOSE_TO_OBSTACLE	The robot is too close to an obstacle
COLLISION	A collision condition was detected
FAILED	The task finished with an error
INTERRUPTED	The task was interrupted by a later request or a stop command
OCCUPIED	The goal area or path is occupied
RUNNING	The task is still executing
SUCCESS	The task finished successfully
UNKNOWN	State has not been reported yet, or the task id is unknown

---

OdomData

Odometry data.

Contains robot pose and velocity estimates from odometry sources (wheel encoders, IMU fusion, etc.). Used for robot localization and navigation.

Member Variables

Name	Type	Description
angular_velocity	list[float]	Angular velocity [wx, wy, wz] (radians/second)
linear_velocity	list[float]	Linear velocity [vx, vy, vz] (meters/second)
orientation	list[float]	Orientation quaternion [x, y, z, w]
position	list[float]	Position [x, y, z] (meters)
timestamp_ns	int	Timestamp (nanoseconds)

---

Parameter

Motion planning parameter configuration class.

Parameter derives from PlannerConfig and does not add configuration fields. Use Parameter with high-level APIs whose signature accepts std::shared_ptr; it supplies convenience constructors and setter/getter methods. Use PlannerConfig directly with waypoint/server-facing APIs whose signature accepts const PlannerConfig&. All angular parameters are expected in radians, linear parameters in meters (SI units).

Member Variables

Name	Type	Description
actuate_type	ActuateType	Chains allowed to participate in planning.
enable_env_collision_check	bool	Include loaded environment obstacles in collision checks.
is_blocking	bool	Wait for planning or execution completion.
is_check_collision	bool	Enable planning collision checks.
is_direct_execute	bool	Execute immediately after planning.
is_tool_pose	bool	Interpret Cartesian targets as attached-tool TCP poses instead of flange poses.
joint_state	dict[str, list[float]]	Optional planning seed by chain; an empty mapping uses the current state.
move_line	bool	Select Cartesian straight-line target-frame motion in dispatching APIs.
reference_frame	str	Reference frame used by APIs that consume this field.
timeout_second	float	Maximum planning or execution request wait time in seconds.

get_actuate_type

def get_actuate_type() -> str

Get actuation type as string.

Performs reverse lookup in g_actuate_type_map to convert enum to string key.

Returns

Type	Description
str	-

get_blocking

def get_blocking() -> bool

Get blocking execution mode status.

Returns

Type	Description
bool	-

get_check_collision

def get_check_collision() -> bool

Get collision checking status.

Returns

Type	Description
bool	-

get_direct_execute

def get_direct_execute() -> bool

Get direct execution mode status.

Returns

Type	Description
bool	-

get_reference_frame

def get_reference_frame() -> str

Get reference frame name.

Returns

Type	Description
str	-

get_timeout

def get_timeout() -> float

Get motion execution timeout value.

Returns

Type	Description
float	-

get_tool_pose

def get_tool_pose() -> bool

Get tool coordinate frame usage status.

Returns

Type	Description
bool	-

set_actuate

def set_actuate(actuate: str) -> None

Set actuation type for whole-body coordination.

Parameters

Name	Type	Default	Description
actuate	str	required	-

note

Invalid keys are ignored and leave the current actuation type unchanged.

set_blocking

def set_blocking(blocking: bool) -> None

Set blocking execution mode.

Parameters

Name	Type	Default	Description
blocking	bool	required	-

set_check_collision

def set_check_collision(check_collision: bool) -> None

Enable or disable collision checking.

Parameters

Name	Type	Default	Description
check_collision	bool	required	-

warning

Disabling collision checking may result in unsafe trajectories.

set_direct_execute

def set_direct_execute(direct_execute: bool) -> None

Set direct execution mode.

Parameters

Name	Type	Default	Description
direct_execute	bool	required	-

set_enable_env_collision_check

def set_enable_env_collision_check(enable: bool) -> None

Enable or disable collision checks against loaded environment obstacles.

Parameters

Name	Type	Default	Description
enable	bool	required	-

note

This flag is used only by planning APIs that forward environment-collision configuration to the motion service. Environment obstacles must first be registered through add_obstacle() or attach_target_object(), and callers must explicitly update those collision objects as the environment changes. GalbotMotion does not provide real-time obstacle perception, automatic environment updates, or dynamic-environment obstacle avoidance.

set_move_line

def set_move_line(move_line: bool) -> None

Set Cartesian linear motion mode.

Selects the Cartesian line planner in APIs that dispatch according to Parameter::move_line, including set_end_effector_pose() and motion_plan(). The controlled target frame is interpolated from its current pose to the requested pose in Cartesian space. This constrains the target-frame path, not individual joint motion.

Parameters

Name	Type	Default	Description
move_line	bool	required	-

note

Enable this mode only when the task requires straight-line Cartesian motion of the target frame. A line request can fail if an intermediate pose is unreachable, crosses a singularity, violates joint limits, or has no continuous IK solution.

note

GalbotMotion::move_line always selects Cartesian line planning for its MotionPlanWaypoints input and does not require Parameter::move_line to be true.

set_reference_frame

def set_reference_frame(frame: str) -> None

Set the reference frame for pose specifications.

Parameters

Name	Type	Default	Description
frame	str	required	-

note

Must be a valid frame in the robot's TF tree.

set_timeout

def set_timeout(timeout: SupportsFloat) -> None

Set motion execution timeout.

Parameters

Name	Type	Default	Description
timeout	SupportsFloat	required	-

note

In APIs that launch a background execution task, this timeout can still be applied by that task.

set_tool_pose

def set_tool_pose(tool_pose: bool) -> None

Set tool coordinate frame usage.

Parameters

Name	Type	Default	Description
tool_pose	bool	required	-

---

PerceptionModule

Enabled perception pipelines (model sets loaded at init).

Enum Value	Description
FOUNDATION_STEREO	High-precision stereo depth
LIGHT_STEREO	Lightweight stereo depth

---

PlannerConfig

Motion planning configuration structure.

Comprehensive configuration for robot motion planning and execution, controlling behavior such as planning mode, collision checking, reference frames, and execution parameters.

Member Variables

Name	Type	Description
actuate_type	ActuateType	Chains allowed to participate in planning.
enable_env_collision_check	bool	Include loaded environment obstacles in collision checks.
is_blocking	bool	Wait for planning or execution completion.
is_check_collision	bool	Enable planning collision checks.
is_direct_execute	bool	Execute immediately after planning.
is_relative_pose	bool	Interpret a target pose as a relative displacement.
is_tool_pose	bool	Interpret Cartesian targets as attached-tool TCP poses instead of flange poses.
joint_state	dict[str, list[float]]	Optional planning seed by chain; an empty mapping uses the current state.
move_line	bool	Select Cartesian straight-line target-frame motion in dispatching APIs.
reference_frame	str	Reference frame used by APIs that consume this field.
timeout_second	float	Maximum planning or execution request wait time in seconds.

---

PlanRequest

Planning request for one segment of a combined motion plan.

Defines the planning algorithm, pass-through behavior, reserved segment-specific options, and ordered target waypoints used by GalbotMotion::combine_plan(). Each waypoint may contain coordinated targets for one or more kinematic chains. The SDK sends the logical AND of enforce_pass across all requests to MPS. Therefore, MPS is asked to continue after segment-level issues only when every request sets enforce_pass to true; any false value requests that the combined plan abort.

Member Variables

Name	Type	Description
enforce_pass	bool	Allow continuation after segment issues; all request values are logically ANDed.
options	PlannerConfig	Per-segment planning options, reserved for future overrides in combine_plan().
plan_type	MotionPlanType	MotionPlanType algorithm used for this segment.
target	list[list[MotionPlanChainTarget]]	Ordered multi-chain target waypoints. Each outer item is one path waypoint, and each inner item targets one kinematic chain.

---

Point

3D point

Represents a position in three-dimensional Cartesian space.

Member Variables

Name	Type	Description
x	float	-
y	float	-
z	float	-

---

Point2d

2D point

Represents a position in two-dimensional Cartesian space.

Member Variables

Name	Type	Description
x	float	-
y	float	-

---

PointField

Point cloud field descriptor.

Describes one data field in a PointCloud2 point structure, defining its name, type, offset, and count. Compatible with ROS 2 sensor_msgs/PointField.

Member Variables

Name	Type	Description
count	int	Number of field elements
datatype	...	Data type (DataType enum)
offset	int	Byte offset of field in a single point

---

PointFieldDataType

Data type enumeration.

Defines primitive data types for point cloud fields, determining byte size and interpretation method for each field value.

Enum Value	Description
FLOAT32	32-bit IEEE 754 floating point (4 bytes)
FLOAT64	64-bit IEEE 754 floating point (8 bytes)
INT16	16-bit signed integer (2 bytes)
INT32	32-bit signed integer (4 bytes)
INT8	8-bit signed integer (1 byte)
UINT16	16-bit unsigned integer (2 bytes)
UINT32	32-bit unsigned integer (4 bytes)
UINT8	8-bit unsigned integer (1 byte)
UNKNOWN	Unknown or unspecified type

---

Pose

Pose (position + orientation) structure.

Represents a full 6-DOF (Degrees of Freedom) pose in 3D space, combining position (translation) and orientation (rotation) information. Commonly used for robot end-effector poses, object poses, and coordinate frame transforms.

---

Pose2d

2D pose (position + yaw) structure， for mobile base and navigation targets

Represents a planar pose in two-dimensional Cartesian space, combining position (translation) and heading angle information. Commonly used for mobile base poses and local navigation targets.

Member Variables

Name	Type	Description
theta	float	-

---

PoseState

Cartesian pose target specification.

Represents a target end-effector pose in Cartesian space (SE(3)). Extends RobotStates to specify pose-based motion goals for kinematic chains. Used in inverse kinematics and Cartesian trajectory planning. Pose values: position in meters, orientation as unit quaternion. Coordinate frames must exist in the robot's TF tree.

Member Variables

Name	Type	Description
assist_chains	set[str]	-

get_type

def get_type() -> RobotStatesType

Get runtime type identifier.

Returns

Type	Description
RobotStatesType	-

---

PrimitiveType

Geometric representation for linear trajectory collision checking.

Enum Value	Description
CYLINDER	Swept-volume cylinder with configurable radius (accurate but slower)
LINE	Zero-thickness line segment (fast but less conservative)

---

Quaternion

Quaternion.

Represents a 3D rotation using quaternion representation (x, y, z, w). A unit quaternion has magnitude 1 and represents a valid rotation.

Member Variables

Name	Type	Description
w	float	-
x	float	-
y	float	-
z	float	-

---

RgbData

RGB/color image data structure.

data is always owned CPU memory. For NV12/BGR/RGB, plane metadata describes the tightly packed raw layout; no DMA-BUF fd or mapped address is exposed to SDK users.

Member Variables

Name	Type	Description
data	bytes	Compressed binary data
format	str	Image format
header	Header	Message header
height	int	Image height in pixels
output_format	RgbOutputFormat	Image output encoding
plane_count	int	Number of image planes
plane_offset_bytes	list[int]	Per-plane byte offset from the start of data
stride_bytes	list[int]	Per-plane stride in bytes
width	int	Image width in pixels

---

RgbOutputFormat

Output representation requested from an RGB camera.

Enum Value	Description
BGR	Raw BGR image data.
JPEG	JPEG-encoded image data.
NV12	Raw NV12 image data.
RGB	Raw RGB image data.

---

RobotStates

Robot kinematic state representation.

Encapsulates the complete kinematic state of the robot, including whole-body joint configuration and mobile base pose. This class serves as a base for more specialized state representations (PoseState, JointStates) and is used throughout the planning and control pipeline for state specification and feedback. All angular values are in radians, linear values in meters (SI units). Base pose uses quaternion representation for orientation (x, y, z, qx, qy, qz, qw).

Member Variables

Name	Type	Description
base_state	list[float]	-
whole_body_joint	list[float]	-

get_type

def get_type() -> RobotStatesType

Get the runtime type of this state object.

Returns

Type	Description
RobotStatesType	-

set_base_state

def set_base_state(base_pose: Pose) -> None

Set mobile base pose.

Converts Pose structure to internal base_state vector representation.

Parameters

Name	Type	Default	Description
base_pose	Pose	required	-

note

Quaternion must be unit-normalized (x^2 + y^2 + z^2 + w^2 = 1).

set_whole_body_joint

def set_whole_body_joint(joint_positions: list[float]) -> None

Set complete whole-body joint configuration.

Parameters

Name	Type	Default	Description
joint_positions	list[float]	required	-

note

Vector size should equal the total number of actuated joints in the robot.

---

RobotStatesType

Enumeration for distinguishing derived state types.

Used for runtime type identification of RobotStates-derived classes.

Enum Value	Description
JOINT	JointStates: Joint space target.
POSE	PoseState: Cartesian pose target.
ROBOT_STATES	RobotStates: Generic whole-body state.

---

SamplerConfig

Configuration parameters for sampling-based motion planners.

This structure configures sampling-based planning algorithms (e.g., RRT, RRT*). It controls state space sampling resolution, interpolation settings, path simplification, and planning termination conditions. Sampling-based planners explore the configuration space by randomly sampling states and connecting them to build a motion plan graph.

get_interpolate

def get_interpolate() -> bool

Check if path interpolation is enabled.

Returns

Type	Description
bool	-

get_interpolation_cnt

def get_interpolation_cnt() -> int

Get the number of interpolation waypoints.

Returns

Type	Description
int	-

get_max_planning_time

def get_max_planning_time() -> float

Get maximum planning time budget.

Returns

Type	Description
float	-

get_max_simplification_time

def get_max_simplification_time() -> float

Get maximum path simplification time budget.

Returns

Type	Description
float	-

get_simplify

def get_simplify() -> bool

Check if path simplification is enabled.

Returns

Type	Description
bool	-

get_state_check_resolution

def get_state_check_resolution() -> float

Get state comparison resolution threshold.

Returns

Type	Description
float	-

get_state_check_type

def get_state_check_type() -> StateCheckType

Get the configured distance metric for state comparison.

Returns

Type	Description
StateCheckType	-

get_termination_condition_type

def get_termination_condition_type() -> TerminationConditionType

Get planning termination condition.

Returns

Type	Description
TerminationConditionType	-

print

def print() -> None

Print sampler configuration to standard output.

Outputs all configuration parameters for debugging and verification.

set_interpolate

def set_interpolate(enable: bool) -> None

Enable or disable path interpolation between sampled states.

Parameters

Name	Type	Default	Description
enable	bool	required	-

note

Interpolation improves trajectory smoothness and collision checking accuracy

set_interpolation_cnt

def set_interpolation_cnt(cnt: SupportsInt) -> None

Set the number of interpolation waypoints between consecutive samples.

Parameters

Name	Type	Default	Description
cnt	SupportsInt	required	-

note

Higher counts improve collision detection but increase computational cost

set_max_planning_time

def set_max_planning_time(time: SupportsFloat) -> None

Set maximum time budget for motion planning.

Parameters

Name	Type	Default	Description
time	SupportsFloat	required	-

note

Planning may terminate earlier if exact solution is found (depends on termination condition)

set_max_simplification_time

def set_max_simplification_time(time: SupportsFloat) -> None

Set maximum time budget for path simplification.

Parameters

Name	Type	Default	Description
time	SupportsFloat	required	-

note

Longer simplification time may yield shorter, smoother paths

set_simplify

def set_simplify(enable: bool) -> None

Enable or disable path simplification post-processing.

Parameters

Name	Type	Default	Description
enable	bool	required	-

note

Simplification reduces waypoints and improves trajectory efficiency

set_state_check_resolution

def set_state_check_resolution(resolution: SupportsFloat) -> None

Set state comparison resolution threshold.

Parameters

Name	Type	Default	Description
resolution	SupportsFloat	required	-

note

Lower values increase planning precision but may slow down computation

set_state_check_type

def set_state_check_type(type: StateCheckType) -> None

Set the distance metric for state comparison.

Parameters

Name	Type	Default	Description
type	StateCheckType	required	-

set_termination_condition_type

def set_termination_condition_type(type: TerminationConditionType) -> None

Set planning termination condition.

Parameters

Name	Type	Default	Description
type	TerminationConditionType	required	-

---

SeedType

IK solver seed type enumeration.

Specifies the initialization strategy for inverse kinematics (IK) solvers. Different seed types affect convergence speed and solution quality.

Enum Value	Description
RANDOM_PROGRESSIVE_SEED	Random progressive seed, tries multiple random seeds iteratively (recommended for robustness)
RANDOM_SEED	Random seed, generates random initial joint configurations
USER_DEFINED_SEED	User-defined seed, uses explicitly provided initial joint configuration

---

SensorStatus

Sensor execution status enumeration.

Represents the status of sensor data acquisition and processing operations, applicable to cameras, lidar, IMU, force sensors, and other sensor types.

Enum Value	Description
COMM_DISCONNECTED	Sensor communication connection lost, no data available
DATA_FETCH_FAILED	Data acquisition or reading failed, sensor may be disconnected or malfunctioning
FAULT	Fault occurred, sensor detected anomaly and cannot continue normal operation
INIT_FAILED	Initialization failed, internal communication or dependent component creation failed
INVALID_INPUT	Input parameters invalid or not meeting interface requirements
IN_PROGRESS	Operation in progress but not yet completed
PUBLISH_FAIL	Data transmission or reporting failed, unable to publish sensor data
STOPPED_UNREACHED	Stopped during execution without completing expected operation
SUCCESS	Execution succeeded, sensor data valid and operation completed
TIMEOUT	Execution timeout, data acquisition or operation not completed within specified time limit

---

SensorType

Sensor type enumeration describing various sensors on the robot.

Identifies different sensor types available on the robot for perception, localization, and manipulation tasks.

Enum Value	Description
BASE_LIDAR	G1/G3 Base LiDAR .
BASE_ULTRASONIC	Base ultrasonic sensor array, for proximity detection and collision avoidance .
CHASSIS_IMU	Chassis IMU (Inertial Measurement Unit) .
HEAD_LEFT_CAMERA	Head left camera, typically RGB camera for stereo vision .
HEAD_RIGHT_CAMERA	Head right camera, typically RGB camera for stereo vision .
LEFT_ARM_CAMERA	Left arm camera, mounted on left manipulator for visual servoing .
LEFT_ARM_DEPTH_CAMERA	Left arm depth camera, provides RGB-D data for the G1/S1 left arm workspace .
LEFT_ARM_INFRA_CAMERA_1	Left arm infrared camera 1, provides infrared data for left arm workspace .
LEFT_ARM_INFRA_CAMERA_2	Left arm infrared camera 2, provides infrared data for left arm workspace .
LEFT_FRONT_SURROUND_CAMERA	G1/G3 left-front surround color camera .
LEFT_REAR_SURROUND_CAMERA	G1/G3 left-rear surround color camera .
LIDAR_IMU	G1/G3 LiDAR IMU (Inertial Measurement Unit) .
RIGHT_ARM_CAMERA	Right arm camera, mounted on right manipulator for visual servoing .
RIGHT_ARM_DEPTH_CAMERA	Right arm depth camera, provides RGB-D data for the G1/S1 right arm workspace .
RIGHT_ARM_INFRA_CAMERA_1	Right arm infrared camera 1, provides infrared data for right arm workspace .
RIGHT_ARM_INFRA_CAMERA_2	Right arm infrared camera 2, provides infrared data for right arm workspace .
RIGHT_FRONT_SURROUND_CAMERA	G1/G3 right-front surround color camera .
RIGHT_REAR_SURROUND_CAMERA	G1/G3 right-rear surround color camera .
TORSO_IMU	G1/G3 Torso IMU (Inertial Measurement Unit), measures acceleration and angular velocity .

---

SingoriXTarget

SDK mirror of galbot.singorix_proto.SingoriXTarget.

Member Variables

Name	Type	Description
header	Header	Message header
target_group_trajectory_map	dict[str, TargetGroupTrajectory]	Joint-space trajectory map
target_task_trajectory_map	dict[str, TargetTaskTrajectory]	Task-space trajectory map

---

StateCheckType

Distance metric for comparing states in configuration space.

Enum Value	Description
EUCLIDEAN_DISTANCE	Cartesian Euclidean distance in joint space (treats joint angles as Cartesian coordinates)
RADIAN_DISTANCE	Angular distance metric accounting for joint angle wraparound and weighting

---

SUCTION_ACTION_STATE

Suction cup action state enumeration.

Represents the operational state of a vacuum suction cup end-effector, tracking the suction process from idle to success or failure.

Enum Value	Description
FAILED	Suction failed
IDLE	Not sucking
SUCCESS	Suction successful
SUCKING	Currently sucking

---

SuctionCupState

Suction cup state.

Contains the current state of a vacuum suction cup gripper, including activation status, pressure reading, and action state.

Member Variables

Name	Type	Description
action_state	SUCTION_ACTION_STATE	Current suction cup action state (SUCTION_ACTION_STATE enum)
activation	bool	Whether currently sucking
pressure	float	Current pressure (Pa)
timestamp_ns	int	Timestamp (nanoseconds)

---

SyncedObservation

Synchronized multi-sensor observation payload.

Contains timestamp-aligned camera frames and optional joint state. The alignment anchor is the first camera passed to get_synced_observation().

Member Variables

Name	Type	Description
depth_data_map	dict[SensorType, DepthData]	Timestamp-aligned depth frames
joint_state	JointStateMessage	Nearest-neighbor joint sample for anchor timestamp (JointStateMessage | None)
rgb_data_map	dict[SensorType, RgbData]	Timestamp-aligned CPU-owned NV12 RGB frames

---

TargetConfig

Common target configuration shared by group and task trajectories.

Member Variables

Name	Type	Description
target_data	int	Target data bitmask
target_id	str	Target identifier
target_priority	int	Target priority
target_sampling	TargetSampling	Sampling strategy
target_ts	Timestamp	Target timestamp
target_type	int	Target type bitmask

---

TargetGroupTrajectory

Target trajectory for a group of joints.

Member Variables

Name	Type	Description
group_commands	list[GroupCommand]	Trajectory points
joint_names	list[str]	Joint names
target_config	TargetConfig	Target configuration

---

TargetSampling

Sampling strategy for a target trajectory.

Mirrors galbot.singorix_proto.TargetSampling while remaining in the SDK type layer.

Enum Value	Description
TARGET_SAMPLING_B_SPLINES	B-splines
TARGET_SAMPLING_CUBIC_SPLINES	Cubic splines
TARGET_SAMPLING_CUSTOM	Custom sampling
TARGET_SAMPLING_DEFAULT	Default sampling strategy
TARGET_SAMPLING_DIRECT_PASS	Direct pass-through
TARGET_SAMPLING_LINEAR_INTERPOLATE	Linear interpolation
TARGET_SAMPLING_QUINTIC_SPLINES	Quintic splines
TARGET_SAMPLING_S_CURVE_PROFILE	S-curve profile
TARGET_SAMPLING_TRAPEZOIDAL_PROFILE	Trapezoidal profile

---

TargetTaskTrajectory

Target trajectory for task-space control.

Member Variables

Name	Type	Description
group_names	list[str]	Related group names
joint_names	list[str]	Related joint names
subtask_names	list[str]	Subtask names
target_config	TargetConfig	Target configuration
task_commands	list[TaskCommand]	Trajectory points

---

TaskCommand

Task-space command at a specific time point.

Member Variables

Name	Type	Description
subtask_commands	list[FrameTriad]	Subtask commands at this point
time_from_start_s	float	Time from trajectory start in seconds

---

TaskHandle

Handle returned when a navigation task is submitted asynchronously.

The handle identifies the task and tells whether the request was accepted by the navigation service. The execution state should be queried separately using task_id.

---

TerminationConditionType

Planning termination criteria.

Enum Value	Description
TIMEOUT	Terminate only when maximum planning time is exceeded
TIMEOUT_AND_EXACT_SOLUTION	Terminate when timeout occurs OR exact goal solution is found

---

Timestamp

Timestamp structure.

Represents high-precision time points with second and nanosecond components. Compatible with ROS 2 builtin_interfaces/Time and std_msgs/Header timestamp format.

Member Variables

Name	Type	Description
nanosec	int	Nanoseconds
sec	int	Seconds

---

Trajectory

Joint trajectory.

Represents a complete robot trajectory consisting of multiple waypoints over time. Both joint_groups and joint_names MUST NOT be empty at the same time. If both are empty, the function returns ControlStatus::INVALID_INPUT. This restriction ensures deterministic joint ordering and prevents subtle bugs caused by implicit internal default order (which may change between SDK versions). Usage: Preferred: Set joint_groups with semantic group names (e.g., {"left_arm", "right_arm"}). Fine-grained: Set joint_names with explicit joint names in the exact order of your point data. joint_names takes precedence over joint_groups if both are set. Example: Trajectorytraj; traj.joint_groups={"left_arm","right_arm"};//Recommended //Or:traj.joint_names={"left_arm_joint1",...,"right_arm_joint1",...};

Member Variables

Name	Type	Description
joint_groups	list[str]	List of joint group names. Recommended: use semantic groups like ["left_arm", "right_arm"].
joint_names	list[str]	List of joint names. Takes precedence over joint_groups if both are set.
points	list[TrajectoryPoint]	List of trajectory points (TrajectoryPoint list)

---

TrajectoryControlStatus

Robot trajectory execution status enumeration.

Represents the real-time execution status when the robot follows a pre-planned trajectory consisting of multiple waypoints.

Enum Value	Description
COMPLETED	Trajectory execution completed successfully, reached final target point
DATA_FETCH_FAILED	Execution data retrieval failed, e.g., joint state or sensor feedback unavailable
ERROR	Error occurred, trajectory execution cannot continue
INVALID_INPUT	Input parameters do not meet requirements, trajectory cannot be executed
RUNNING	Trajectory is currently executing, not yet completed
STOPPED_UNREACHED	Stopped during trajectory execution without reaching endpoint

---

TrajectoryFeasibilityCheckOption

Trajectory validation and feasibility checking configuration.

This structure provides fine-grained control over which feasibility constraints are enforced during trajectory validation. It supports independent toggling of collision detection, joint limit compliance, and velocity profile feasibility. Selectively disabling checks can improve computational performance for debugging, simulation, or scenarios where certain constraints are guaranteed to be satisfied. Disabling feasibility checks may produce trajectories that are unsafe or physically unrealizable. Use with caution and only when constraints are verified through other means.

get_disable_collision_check

def get_disable_collision_check() -> bool

Check if collision detection is disabled.

Returns

Type	Description
bool	-

get_disable_joint_limit_check

def get_disable_joint_limit_check() -> bool

Check if joint limit checking is disabled.

Returns

Type	Description
bool	-

get_disable_velocity_feasibility_check

def get_disable_velocity_feasibility_check() -> bool

Check if velocity feasibility checking is disabled.

Returns

Type	Description
bool	-

print

def print() -> None

Print trajectory feasibility check configuration to standard output.

Outputs enabled/disabled status for each feasibility check type.

set_disable_collision_check

def set_disable_collision_check(disable: bool) -> None

Enable or disable collision detection during trajectory validation.

Parameters

Name	Type	Default	Description
disable	bool	required	-

warning

Disabling collision checks may result in unsafe motion plans

set_disable_joint_limit_check

def set_disable_joint_limit_check(disable: bool) -> None

Enable or disable joint limit compliance checking.

Parameters

Name	Type	Default	Description
disable	bool	required	-

warning

Disabling joint limit checks may damage hardware or violate safety constraints

set_disable_velocity_feasibility_check

def set_disable_velocity_feasibility_check(disable: bool) -> None

Enable or disable velocity profile feasibility checking.

Parameters

Name	Type	Default	Description
disable	bool	required	-

note

Velocity feasibility ensures the trajectory can be executed within actuator speed limits

---

TrajectoryPlanConfig

Trajectory planning and parameterization configuration.

This structure configures trajectory generation parameters for converting discrete motion plans into smooth, time-parameterized trajectories. It supports both single-segment and multi-waypoint trajectory planning. Trajectory planning involves computing velocity and acceleration profiles along a geometric path while respecting kinematic constraints.

get_min_move_time

def get_min_move_time() -> float

Get minimum motion segment duration.

Returns

Type	Description
float	-

get_move_line_intermediate_point

def get_move_line_intermediate_point() -> float

Get waypoint density for linear motion interpolation.

Returns

Type	Description
float	-

get_way_point_plan_expected_time

def get_way_point_plan_expected_time() -> float

Get expected multi-waypoint trajectory duration.

Returns

Type	Description
float	-

print

def print() -> None

Print trajectory planning configuration to standard output.

Outputs all configuration parameters for debugging and verification.

set_min_move_time

def set_min_move_time(time: SupportsFloat) -> None

Set minimum duration for any motion segment.

Parameters

Name	Type	Default	Description
time	SupportsFloat	required	-

note

Non-zero values prevent excessively fast motions; 0.0 allows maximum speed within kinematic limits

set_move_line_intermediate_point

def set_move_line_intermediate_point(value: SupportsFloat) -> None

Set waypoint density for Cartesian linear motion interpolation.

Parameters

Name	Type	Default	Description
value	SupportsFloat	required	-

note

Higher values improve Cartesian path accuracy but increase computational cost

set_way_point_plan_expected_time

def set_way_point_plan_expected_time(time: SupportsFloat) -> None

Set expected total duration for multi-waypoint trajectory planning.

Parameters

Name	Type	Default	Description
time	SupportsFloat	required	-

note

Used as a hint for time-optimal trajectory generation algorithms

---

TrajectoryPoint

Single trajectory point.

Represents a waypoint in a robot trajectory, specifying joint states at a particular time. The joint_command_vec order must match the joint order defined by Trajectory.joint_names or Trajectory.joint_groups (expanded in order). Mismatched order will cause undefined behavior.

Member Variables

Name	Type	Description
joint_command_vec	list[JointCommand]	- joint_command_vec (List[JointCommand]): List of specific joint commands to execute
time_from_start_second	float	- time_from_start_second (float): Time from trajectory start (seconds)

---

Twist

6D twist command (linear + angular velocity).

Member Variables

Name	Type	Description
angular	Vector3	Angular velocity vector
linear	Vector3	Linear velocity vector

---

UltrasonicData

Ultrasonic sensor data structure .

Contains a single ultrasonic distance measurement with timestamp.

Member Variables

Name	Type	Description
distance	float	Distance (meters)
timestamp_ns	int	Timestamp (nanoseconds)

---

UltrasonicType

Chassis ultrasonic sensor probe enumeration (8 directions) .

Identifies individual ultrasonic sensors arranged around the mobile base chassis for omnidirectional obstacle detection and proximity sensing.

Enum Value	Description
BACK_LEFT	Back left ultrasonic sensor
BACK_RIGHT	Back right ultrasonic sensor
FRONT_LEFT	Front left ultrasonic sensor
FRONT_RIGHT	Front right ultrasonic sensor
LEFT_LEFT	Left side front ultrasonic sensor
LEFT_RIGHT	Left side rear ultrasonic sensor
RIGHT_LEFT	Right side front ultrasonic sensor
RIGHT_RIGHT	Right side rear ultrasonic sensor

---

Vector3

3D vector structure

Represents a three-dimensional vector, used for forces, torques, velocities, accelerations, and other vectorial quantities.

Member Variables

Name	Type	Description
x	float	X coordinate
y	float	Y coordinate
z	float	Z coordinate

---

Waypoint

---

WaypointParams

Optional tuning parameters for a waypoint.

These parameters control how precisely the robot reaches a waypoint and how smoothly it moves while doing so. Fields left unchanged keep their default values.

Member Variables

Name	Type	Description
acceleration_scale	float	-
arrival_orientation_threshold	float	-
arrival_position_threshold_x	float	-
arrival_position_threshold_y	float	-
jerk_scale	float	-
velocity_scale	float	-

---

WBCException

---

Wrench

6D wrench command (force + torque).

Member Variables

Name	Type	Description
force	Vector3	Force vector
torque	Vector3	Torque vector

check_motion_status

def check_motion_status(status: MotionStatus) -> str

Convert a MotionStatus enum value to a string.

Parameters

Name	Type	Default	Description
status	MotionStatus	required	The motion status to convert.

Returns

Type	Description
str	str: The string representation of the motion status.

create_joint_state

def create_joint_state() -> JointStates

Create a JointStates instance.

Returns

Type	Description
JointStates	JointStates: A new JointStates instance.

create_parameter

def create_parameter(
    direct_execute: bool = False,
    blocking: bool = False,
    timeout: SupportsFloat = 20.0,
    actuate: str = 'with_chain_only',
    tool_pose: bool = False,
    check_collision: bool = True,
    frame: str = 'base_link'
) -> Parameter

Create a Parameter instance.

Parameters

Name	Type	Default	Description
direct_execute	bool	False	Execute the planned trajectory immediately.
blocking	bool	False	Wait synchronously for completion.
timeout	SupportsFloat	20.0	Maximum planning or execution request wait time in seconds.
actuate	str	'with_chain_only'	Participating chains: "with_chain_only", "with_torso", or "with_leg".
tool_pose	bool	False	Interpret Cartesian targets as the attached-tool TCP instead of the flange.
check_collision	bool	True	Enable planning collision checks.
frame	str	'base_link'	Reference coordinate frame for pose targets.

Returns

Type	Description
Parameter	Parameter: A new Parameter instance.

create_pose_state

def create_pose_state() -> PoseState

Create a PoseState instance.

Returns

Type	Description
PoseState	PoseState: A new PoseState instance.

---