Python API Reference - S1 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.
• 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.

get_instance

@staticmethod
def get_instance(machine_type: MachineType) -> GalbotRobot

Runtime factory for selecting a concrete robot singleton.

Parameters

Name	Type	Default	Description
machine_type	MachineType	required	-

Returns

Type	Description
GalbotRobot	-

acquire_controller

def acquire_controller(controller_name: str) -> ControlStatus

Acquire hardware authority.

Designates the controller to take ownership of the hardware. Opposite of release_controller. Controller must still be started to begin execution.

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.

destroy

def destroy() -> None

Clean up system resources.

Performs cleanup of robot control system resources including middleware connections, sensor interfaces, and communication channels. Should be called before program exit to ensure graceful shutdown.

note

This function should be called after request_shutdown() or when is_running() returns false

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.
is_blocking	bool	True	Whether to block until trajectory execution completes (optional, default: True).

Returns

Type	Description
ControlStatus	ControlStatus: Trajectory execution/sending result.

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.

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

def get_dexterous_hand_state(end_effector: str) -> tuple

Get current dexterous hand (dexhand) state.

Retrieves the current joint state of the specified dexterous hand.

Parameters

Name	Type	Default	Description
end_effector	str	required	Dexhand name, e.g. "left_dexhand" or "right_dexhand".

Returns

Type	Description
tuple	Tuple[ControlStatus, JointStateMessage]: Query result and current dexhand joint states.

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. The returned vector order matches the joint ordering from get_joint_names().

Parameters

Name	Type	Default	Description
joint_groups	Sequence[str]	required	Joint groups to query.
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.

get_joint_states

def get_joint_states(
    joint_group_vec: Sequence[str],
    joint_names_vec: 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_group_vec	Sequence[str]	required	Joint groups to query (optional).
joint_names_vec	Sequence[str]	[]	Specific joint names, takes priority over joint_group_vec (optional).

Returns

Type	Description
list[JointState]	List[JointState]: Real-time state data for corresponding joints.

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

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.

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.

Programmatically sends a shutdown signal (SIGINT) to initiate graceful system shutdown. This triggers registered exit callbacks and begins resource cleanup.

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],
    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 commands for the dexhand.
is_blocking	bool	True	Whether to block until action completes (optional, default: True).

Returns

Type	Description
ControlStatus	ControlStatus: Command execution/sending 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 (optional).
joint_names	Sequence[str]	[]	Specific joint names, takes priority over joint_groups (optional).
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. 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).

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 (optional).
joint_names	Sequence[str]	[]	Specific joint names, takes priority over joint_groups (optional).
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.

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.

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_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. Operation sequence: stop(old) -> release(old) -> acquire(new) -> start(new).

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 signal is received.

Blocks the calling thread indefinitely until a shutdown signal (SIGINT, SIGTERM) is received. This is useful for keeping the main thread alive while background threads handle robot control.

note

This function will return when is_running() becomes false

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.

get_instance

@staticmethod
def get_instance(machine_type: ...) -> GalbotMotion

Runtime factory for selecting a concrete motion planning singleton.

Parameters

Name	Type	Default	Description
machine_type	...	required	-

Returns

Type	Description
GalbotMotion	-

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

get_instance

@staticmethod
def get_instance(machine_type: MachineType) -> GalbotNavigation

Runtime factory for selecting a concrete navigation singleton.

This static factory method allows runtime selection of the navigation implementation based on the robot machine type. The method declaration resides in the interface header for compile-time availability, while the actual implementation logic (including platform-specific includes and switch statements) is contained in the corresponding .cpp file. This design keeps the interface clean while enabling platform-specific instantiation without exposing implementation details.

Parameters

Name	Type	Default	Description
machine_type	MachineType	required	MachineType enum (e.g. MachineType.G1 / MachineType.S1)

Returns

Type	Description
GalbotNavigation	GalbotNavigation: The navigation instance for that machine type.

note

Adding support for a new machine type requires updating the MachineType enumeration and the factory implementation in the .cpp file.

add_bounding_box

def add_bounding_box(box_info: dict) -> tuple

Add a bounding box for navigation obstacle filtering.

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

Parameters

Name	Type	Default	Description
box_info	dict	required	Contains:

Returns

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

attach_box_to_link

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

Attach a box collision object to a robot link.

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

Parameters

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

Returns

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

check_goal_arrival

def check_goal_arrival() -> bool

Check if the robot has successfully reached the current goal.

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

Returns

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

note

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

note

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

note

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

check_path_reachability

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

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

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

Parameters

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

Returns

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

note

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

note

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

note

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

detach_box_from_link

def detach_box_from_link(box_tag: SupportsInt) -> tuple

Detach a box collision object from its robot link.

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

Parameters

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

Returns

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

get_bounding_box

def get_bounding_box() -> list

Get bounding boxes currently used by navigation obstacle filtering.

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

Returns

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

get_current_pose

def get_current_pose() -> list[float]

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

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

Returns

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

note

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

note

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

get_navigation_status

def get_navigation_status() -> NavigationTaskStatus

Get the current navigation task state.

Returns the 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.

remove_bounding_box

def remove_bounding_box(box_tag: SupportsInt) -> tuple

Remove a bounding box from navigation obstacle filtering.

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

Parameters

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

Returns

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

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.

---

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

---

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

---

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.

---

S1ControllerName

String constants for S1 controller names.

Defines the controller names supported by the S1 robot model.

Enum Value	Description
ELEVATOR_CTRL	Elevator controller
HEAD_PVT_CTRL	Head PVT controller
LEFT_ARM_PVT_CTRL	Left arm PVT controller
LEFT_CAMERA_CTRL	Left camera controller
LEFT_GRIPPER_CTRL	Left gripper controller
RIGHT_ARM_PVT_CTRL	Right arm PVT controller
RIGHT_CAMERA_CTRL	Right camera controller
RIGHT_GRIPPER_CTRL	Right gripper controller
SWERVE_CHASSIS_POSE_CTRL	Swerve chassis pose controller
SWERVE_CHASSIS_TWIST_CTRL	Swerve chassis twist controller

---

S1JointGroup

Galbot S1 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
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 manipulation.
left_camera	Camera mount group placeholder (no active body joints). Typical use: semantic grouping for sensor-side logic.
left_gripper	Left gripper chain. Default joint: left_gripper_joint1. Typical use: grasp width control.
right_arm	Right 7-DoF arm chain. Default joints: right_arm_joint1 ... right_arm_joint7. Typical use: right-arm manipulation.
right_camera	Camera mount group placeholder (no active body joints). Typical use: semantic grouping for sensor-side logic.
right_gripper	Right gripper chain. Default joint: right_gripper_joint1. Typical use: grasp width control.
swerve_chassis	Swerve chassis mechanism group (passive in joint-position control). Default joints: Wheel_1_direction_joint, Wheel_1_drive_joint, Wheel_2_direction_joint, Wheel_2_drive_joint, Wheel_3_direction_joint, Wheel_3_drive_joint, Wheel_4_direction_joint, Wheel_4_drive_joint. Typical use: chassis state grouping; base motion should use base APIs.
torso	Torso chain. Default joint: torso_base_joint. Typical use: upper-body height/pitch adjustment.

---

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
BACK_IMU	S1 Back LiDAR IMU (Inertial Measurement Unit) .
BACK_LIDAR	S1 Back LiDAR (rear), mounted on rear for backward perception .
BASE_ULTRASONIC	Base ultrasonic sensor array, for proximity detection and collision avoidance .
CHASSIS_IMU	S1 Chassis LiDAR IMU (Inertial Measurement Unit) .
CHASSIS_LIDAR	S1 Chassis LiDAR (front), mounted on chassis for forward perception .
HEAD_CAMERA	Head camera, mounted on head for visual servoing .
HEAD_DEPTH_CAMERA	Head depth camera, provides RGB-D data for head workspace .
HEAD_IMU	S1 Head LiDAR IMU (Inertial Measurement Unit) .
HEAD_LEFT_CAMERA	Head left camera, typically RGB camera for stereo vision .
HEAD_LIDAR	S1 Head LiDAR (front), mounted on head for forward perception .
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 .
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 .

---

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

Trajectory result.

Contains the complete planned trajectory with joint positions and timing information.

Member Variables

Name	Type	Description
joint_groups	list[str]	List of joint group names
joint_names	list[str]	List of joint names
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.

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_joint_state

def create_joint_state() -> JointStates

Create a JointStates instance.

Returns

Type	Description
JointStates	JointStates: A new JointStates instance.

create_parameter

def create_parameter(
    direct_execute: bool,
    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.

create_pose_state

def create_pose_state() -> PoseState

Create a PoseState instance.

Returns

Type	Description
PoseState	PoseState: A new PoseState instance.

---