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 (G1 only). 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 (grippers and suction cups) Mobile base velocity control Sensor data acquisition (IMU, cameras, LiDAR, ultrasonic) Coordinate frame transformations System lifecycle management Use GalbotRobot::get_instance(MachineType) to obtain a reference for a specific platform (G1/S1). 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() -> ControlStatus

Clear WBC end-effector task commands.

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

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.

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.

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_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_depth_data

def get_depth_data(camera_id: SensorType) -> dict

Get latest depth image from specified camera.

Retrieves the most recent depth image captured by the specified depth camera. Depth values typically represent distance from the camera sensor.

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': Image format, e.g., 'depth16' or other - 'depth_scale': Depth scaling factor - 'height': Image height in pixels - 'width': Image width in pixels - 'data': Compressed depth image binary data (bytes). Returns empty dictionary on failure.

note

The camera sensor must be enabled during initialization via enable_sensor_set

note

Depth values are typically in millimeters (mm) or meters (m) depending on sensor

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 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) -> dict

Get force/torque sensor data.

Retrieves the latest measurements from the specified force/torque sensor. These sensors are typically mounted at wrists or end-effectors for contact force monitoring and compliance control.

Parameters

Name	Type	Default	Description
sensor_type	GalbotOneFoxtrotSensor	required	Force sensor enum to query.

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 on failure.

note

The force sensor must be enabled during initialization via enable_sensor_set

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_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: Returns body joints in order: chassis, head, left_arm, right_arm, leg.

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: Returns body joints in order: chassis, head, left_arm, right_arm, leg.

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: Returns body joints in order: chassis, head, left_arm, right_arm, leg.

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: Returns body joints in order: chassis, head, left_arm, right_arm, leg.

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) -> dict

Get latest RGB image from specified camera.

Retrieves the most recent color image captured by the specified RGB camera.

Parameters

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

Returns

Type	Description
dict	dict: Dictionary containing the following keys: - 'header': Message header with timestamp and frame information - 'format': Image format, e.g., 'jpeg' or 'png' - 'data': Compressed image binary data (bytes) Returns empty dictionary on failure.

note

The camera sensor must be enabled during initialization via enable_sensor_set

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_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] = ...) -> 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.

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.

set_base_pose

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

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

Use this overload when arrival timing must be coordinated through time_from_start_s.

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 = 'odom',
    reference_frame_id: str = 'odom',
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

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

Use this overload when arrival timing must be coordinated through time_from_start_s.

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	'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 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 mobile base pose (x, y, yaw) with explicit interpolation time.

Use this overload when arrival timing must be coordinated through time_from_start_s.

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 ("base_link"/"odom"/"map").
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	Duration in seconds before auto-stop (optional, default: 0.0). If <= 0.0, no automatic stop is performed.

Returns

Type	Description
ControlStatus	ControlStatus: Command sending result.

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] = [],
    time_from_start_s: SupportsFloat = 0.0
) -> ControlStatus

Set WBC end-effector pose commands (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)
time_from_start_s	SupportsFloat	0.0	Time from trajectory start in seconds (optional, default: 0.0).

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 = 30,
    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.
velocity_mps	SupportsFloat	0.03	Gripper motion speed in m/s (optional, default: 0.03).
effort	SupportsFloat	30	Gripper effort in Nm (optional, default: 30).
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 = 10.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 to satisfy time_from_start_s (expected arrival time).

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. Gripper motion uses whichever is slower between the specified velocity and time_from_start_s. Therefore, when setting the gripper velocity, time_from_start_s can be set to 0 (fastest arrival), and the gripper will be controlled directly by the specified velocity.

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	10.0	Time in seconds from the start of the motion to execute the command (optional, default: 10.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_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 contains: - 'header': Message header with timestamp and frame information - 'type': Audio data type ('waken_up', 'denoise_chunk', 'vad_begin', 'vad_chunk', 'vad_end') - 'format': Audio format ('pcm', 'json') - 'data': Audio binary data (bytes)
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.

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: Result of the operation.

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 (x,y,yaw) to zero with selectable frames.

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 selectable 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). 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.
tool	str	required	The tool to attach.

Returns

Type	Description
MotionStatus	bool: True if the tool attachment is successful, False otherwise.

note

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

note

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

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.

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.

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.

Returns

Type	Description
MotionStatus	bool: True if the tool detachment is successful, False otherwise.

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'	The name of the reference frame. 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'	The name of the reference frame. 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_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_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.

Queries the TF (Transform) tree to retrieve the current Cartesian pose of a specified end-effector link. 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'	The name of the reference frame. 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).

warning

Requires TF tree to be properly published and up-to-date.

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'	The name of the reference frame. 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.

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'	Reference frame. 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.

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'	Reference frame. 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'	The name of the reference frame. 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'	The name of the reference frame. 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.

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 trajectory for a single kinematic chain.

Parameters

Name	Type	Default	Description
target	RobotStates	required	The target pose.
start	RobotStates	None	The initial robot states. Defaults to nullptr.
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 motion planning. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	bool: True if the motion planning is successful, False otherwise.

note

Collision semantics: galbotMotion does not have real-time obstacle perception. When enable_collision_check=true, collision checking is evaluated against self-collision and the Motion-side environment objects that the user loads manually via add_obstacle() / attach_target_object().

note

Trajectory is time-parameterized with velocity/acceleration limits respected.

note

For direct execution (params->is_direct_execute=true), trajectory is automatically sent to robot.

warning

target must be PoseState or JointStates; passing base RobotStates will cause INVALID_INPUT error.

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 coordinated trajectories through waypoints for multiple chains.

Enables coordinated multi-arm or whole-body motion through waypoint sequences. Each chain can have its own waypoint sequence, executed in synchronized fashion.

Parameters

Name	Type	Default	Description
target	RobotStates	required	The target pose.
waypoint_poses	Sequence[list[float]]	required	The waypoint poses.
start	RobotStates	None	The initial robot states. Defaults to nullptr.
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 motion planning. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	bool: True if the motion planning is successful, False otherwise.

note

All chain trajectories are time-synchronized for coordinated execution.

note

Useful for bimanual manipulation or mobile manipulation tasks.

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 coordinated trajectories through waypoints for multiple chains.

Enables coordinated multi-arm or whole-body motion through waypoint sequences. Each chain can have its own waypoint sequence, executed in synchronized fashion.

Parameters

Name	Type	Default	Description
targets	dict]]	required	The target poses.
start	Sequence[RobotStates]	[]	The initial robot states. Defaults to nullptr.
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 motion planning. Defaults to default_param.

Returns

Type	Description
tuple[MotionStatus, dict[str, list[list[float]]]]	bool: True if the motion planning is successful, False otherwise.

note

All chain trajectories are time-synchronized for coordinated execution.

note

Useful for bimanual manipulation or mobile manipulation tasks.

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_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 end-effector to move to target Cartesian pose.

High-level interface for Cartesian motion commands. Internally performs IK, plans trajectory, and optionally executes the motion. Supports both blocking (wait for completion) and non-blocking (return immediately) modes.

Parameters

Name	Type	Default	Description
target_pose	list[float]	required	The target pose.
end_effector_frame	str	required	The name of the end-effector frame.
reference_frame	str	'base_link'	The name of the reference frame. 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.
is_blocking	bool	True	Whether to block until the motion is completed. Defaults to true.
timeout	SupportsFloat	-1.0	The maximum time to wait for the motion to complete. Defaults to -1.0.
params	Parameter	...	Additional parameters for the motion planning. Defaults to default_param.

Returns

Type	Description
MotionStatus	bool: True if the motion planning is successful, False otherwise.

note

Motion type (linear/joint-space) controlled by params->move_line flag.

note

For direct execution (params->is_direct_execute=true), avoid passing reference_robot_states.

warning

Blocking calls will halt execution until motion completes; use with caution in real-time contexts.

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.

---

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); }

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.

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 most recent task state reported by the navigation system (UNKNOWN, RUNNING, SUCCESS, or FAILED). Use this when running non-blocking navigation to poll for state and exit error logic in time on FAILED or timeout, avoiding deadlock or indefinite wait.

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 SUCCESS, FAILED, or after a timeout.

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_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 = True
) -> 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, blocks until goal is reached or timeout; default False.
timeout	SupportsFloat	8	Maximum wait time in seconds for blocking mode; default 8.0.
omni_plan	bool	True	If True, omnidirectional motion planning; if False, differential drive; default True.

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

For blocking mode, the calling thread will be blocked until completion or timeout.

note

The actual navigation time may exceed the timeout value in blocking mode before the method returns.

warning

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

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.

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).

Implemented for G1 only: get_instance(MachineType::S1) throws std::runtime_error.

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

AudioData

Audio data structure.

Audio data structure used to encapsulate audio data.

Member Variables

Name	Type	Description
data	list[int]	Binary data packet - for pcm format: 2560 bytes per 80ms, for json: text length or empty
format	str	Audio format: 'pcm' (16000Hz 16-bit mono) or 'json' (UTF-8 text)
header	Header	Message header with timestamp and frame ID
type	str	Audio type identifier: 'waken_up' (wake-up event), 'denoise_chunk' (denoised audio), 'vad_begin' (VAD start), 'vad_chunk' (VAD audio), 'vad_end' (VAD end)

---

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

---

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	list[int]	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 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).

Enum Value	Description
BRAINCO	BrainCo dexterous hand
INSPIRE	Inspire 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

---

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

String constants for G1 controller names.

Defines the controller names supported by the G1 robot model.

Enum Value	Description
CHASSIS_POSE_CTRL	Chassis pose controller
CHASSIS_TWIST_CTRL	Chassis twist controller
CONTROLLER_NAME_NUM	Sentinel value for invalid controller name
HEAD_PVT_BYPASS_CTRL	Head PVT bypass controller
HEAD_PVT_CTRL	Head PVT controller
LEFT_ARM_PVT_BYPASS_CTRL	Left arm PVT bypass controller
LEFT_ARM_PVT_CTRL	Left arm PVT controller
LEFT_DEXHAND_CTRL	Left dexhand controller
LEFT_GRIPPER_CTRL	Left gripper controller
LEG_PVT_BYPASS_CTRL	Leg PVT bypass controller
LEG_PVT_CTRL	Leg PVT controller
RIGHT_ARM_PVT_BYPASS_CTRL	Right arm PVT bypass controller
RIGHT_ARM_PVT_CTRL	Right arm PVT controller
RIGHT_DEXHAND_CTRL	Right dexhand controller
RIGHT_GRIPPER_CTRL	Right gripper controller

---

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 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	-
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_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
S1	Galbot S1 humanoid robot platform

---

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

---

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)

---

NavigationTaskStatus

Navigation task current state enumeration.

Represents the current state of an active or completed navigation task, as reported by the navigation system. Used for polling during non-blocking navigation to detect RUNNING, SUCCESS, or FAILED and exit error logic in time.

Enum Value	Description
FAILED	Navigation task failed
RUNNING	Navigation task is in progress
SUCCESS	Navigation task completed successfully
UNKNOWN	Task state unknown or not yet reported

---

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.

This class extends PlannerConfig to provide comprehensive configuration options for whole-body motion planning and execution. It encapsulates execution mode, actuation type, tool frame handling, collision checking, and coordinate frame specifications. All angular parameters are expected in radians, linear parameters in meters (SI units).

Member Variables

Name	Type	Description
joint_state	dict[str, list[float]]	-
timeout_second	float	-

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	-

warning

Must be a valid key in g_actuate_type_map, otherwise behavior is undefined.

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_move_line

def set_move_line(move_line: bool) -> None

Set Cartesian linear motion mode.

Parameters

Name	Type	Default	Description
move_line	bool	required	-

note

Linear motion provides predictable Cartesian paths but may have joint velocity discontinuities.

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

Only applies when blocking mode is enabled.

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

---

Point

3D point

Represents a position in three-dimensional Cartesian space.

Member Variables

Name	Type	Description
x	float	-
y	float	-
z	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.

---

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.

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.

Contains compressed color image data from RGB cameras. Compatible with ROS 2 sensor_msgs/CompressedImage format.

Member Variables

Name	Type	Description
data	list[int]	Compressed binary data
format	str	Image format
header	Header	Message header

---

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

---

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 Base LiDAR .
BASE_ULTRASONIC	Base ultrasonic sensor array, for proximity detection and collision avoidance .
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 left arm workspace .
LEFT_FRONT_SURROUND_CAMERA	G1 left-front surround color camera .
LEFT_REAR_SURROUND_CAMERA	G1 left-rear surround color camera .
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 right arm workspace .
RIGHT_FRONT_SURROUND_CAMERA	G1 right-front surround color camera .
RIGHT_REAR_SURROUND_CAMERA	G1 right-rear surround color camera .
TORSO_IMU	G1 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)

---

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

---

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

---

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_parameter

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

Create a Parameter instance.

Parameters

Name	Type	Default	Description
direct_execute	bool	required	Whether to execute the motion directly.
blocking	bool	required	Whether to block the execution until completion.
timeout	SupportsFloat	required	Maximum time to wait for the motion to complete.
actuate	str	required	Actuation type (position/velocity/torque).
tool_pose	bool	required	Whether the motion is for a tool pose.
check_collision	bool	required	Whether to check for collisions.
frame	str	'base_link'	Coordinate frame for the motion. Defaults to "base_link".

Returns

Type	Description
Parameter	Parameter: A new Parameter instance.

---