Navigation Module - QUANTA X1 Pro 1.0

Capability overview

The navigation module provides capabilities for robot mapping, map saving, and localization management, supporting starting or stopping mapping, saving maps to the robot body, and starting or stopping localization based on existing maps. It also supports switching between the robot's built-in navigation mode and a user-defined navigation mode, allowing developers to choose how navigation is implemented based on their specific scenarios.

start_mapping interface reference

Field	Details
Function	start_mapping()
Signature	def start_mapping(timeout) -> ExecutionResult
Description	Start mapping
Parameter	None
Return Value	ExecutionResult
Notes	None

Example:

robot.navigation.start_mapping()

stop_mapping interface reference

Field	Details
Function	stop_mapping()
Signature	def stop_mapping(save_map_param: SaveMapParam, timeout) -> ExecutionResult
Description	Stop mapping and save the map
Parameter	save_map_param: SaveMapParam. map_name: Name of the map to save. Maps can currently be saved only on the robot.
Return Value	ExecutionResult
Notes	None

Example:

robot.navigation.stop_mapping(
    SaveMapParam(map_name="test")
)

set_navigation_mode interface reference

Field	Details
Function	set_navigation_mode()
Signature	def set_navigation_mode(navigation_mode_param: NavigationModeParam, timeout) -> ExecutionResult
Description	Set the navigation mode
Parameter	navigation_mode_param: NavigationModeParam. mode: Navigation mode. BUILT_IN_NAVIGATION: Use the robot's built-in navigation. USER_CUSTOM_NAVIGATION: Disable built-in navigation so that the user can implement custom navigation control.
Return Value	ExecutionResult
Notes	None

Example:

robot.navigation.set_navigation_mode(
    NavigationModeParam(
        mode=NavigationMode.USER_CUSTOM_NAVIGATION
    )
)

start_localization interface reference

Field	Details
Function	start_localization()
Signature	def start_localization(start_localization_param: StartLocalizationParam, timeout) -> ExecutionResult
Description	Start localization using a specified map
Parameter	StartLocalizationParam.name: Name of the map used to start localization
Return Value	ExecutionResult
Notes

Example:

result = robot.navigation.start_localization(StartLocalizationParam(map_name=map_name, use_init_pose=False))
print(f"start localization success: {result.is_success}")

stop_localization interface reference

Field	Details
Function	stop_localization()
Signature	def stop_localization(timeout) -> ExecutionResult
Description	Stop localization
Parameter	None
Return Value	ExecutionResult
Notes	None

Example:

robot.navigation.stop_localization()

cancel_navigation interface reference

Field	Details
Function	cancel_navigation()
Signature	def cancel_navigation(timeout=None) -> ExecutionResult
Description	Cancel the current navigation task.
Parameter	timeout: Optional RPC timeout in seconds. None means that no explicit timeout is set for this call.
Return Value	ExecutionResult: is_success: Whether the operation succeeded; error_message: Failure message; error_code: Failure category.
Notes	This interface cancels only the current navigation task. It does not delete maps or stop the localization service. If there is no task to cancel, use the returned result to determine the outcome. A connection loss or RPC timeout may raise a gRPC connection exception.

Example:

result = robot.navigation.cancel_navigation(timeout=10)

if result.is_success:
    print("cancel navigation success")
else:
    print(
        "cancel navigation failed: "
        f"error_code={result.error_code}, "
        f"error_message={result.error_message}"
    )

load_map interface reference

Field	Details
Function	load_map()
Signature	def load_map(map_name: str, map_path: str) -> TransferResult
Description	Package a map directory on the SDK client computer and upload it to the robot.
Parameter	map_name: Map name, not a path. It must not contain /, , or .. and must not begin with a period. map_path: Parent directory of the map on the SDK client computer, not a path on the robot. The interface reads <map_path>/<map_name>/.
Return Value	TransferResult: success: Whether packaging and upload succeeded; message: Failure reason; normally empty on success.
Notes	A non-empty <map_path>/<map_name>/ directory must exist on the client. Symbolic links and hard links in the directory are not included in the map package. The robot cannot run another map import or export operation at the same time. Path, packaging, transfer, or robot-side processing failures are normally returned through success=False and message.

Example:

# Read /home/user/maps/office_1/ on the client computer
result = robot.navigation.load_map(
    map_name="office_1",
    map_path="/home/user/maps",
)

if result.success:
    print("load map success")
else:
    print(f"load map failed: {result.message}")

export_map interface reference

Field	Details
Function	export_map()
Signature	def export_map(map_name: str, target_path: str) -> TransferResult
Description	Download a specified map from the robot and extract it on the SDK client computer.
Parameter	map_name: Name of an existing map on the robot, not a path. It must not contain /, , or .. and must not begin with a period. target_path: Destination parent directory on the SDK client computer, not a path on the robot. The interface writes to <target_path>/<map_name>/.
Return Value	TransferResult: success: Whether download and extraction succeeded; message: Failure reason; normally empty on success.
Notes	The specified map must exist on the robot. target_path and any existing <target_path>/<map_name> must be directories. Export to a map directory that does not yet exist or is empty to avoid mixing the export with old files. The robot cannot run another map import or export operation at the same time.

Example:

result = robot.navigation.export_map(
    map_name="office_1",
    target_path="/home/user/exported_maps",
)

if result.success:
    print("map exported to /home/user/exported_maps/office_1")
else:
    print(f"export map failed: {result.message}")

get_map_list interface reference

Field	Details
Function	get_map_list()
Signature	def get_map_list(timeout: Optional[float] = None) -> GetMapListResponse
Description	Query the list of map names saved on the robot.
Parameter	timeout: Optional RPC timeout in seconds. None means that no explicit timeout is set for this call.
Return Value	GetMapListResponse: header: Call status, determined through is_success, error_code, and error_message; map_list: List of map names; empty when no maps are available.
Notes	map_list contains map names only, not client-side or robot-side file-system paths. A connection loss or RPC timeout may raise a gRPC connection exception.

Example:

result = robot.navigation.get_map_list(timeout=10)

if result.header is not None and result.header.is_success:
    print("saved maps:")
    for map_name in result.map_list:
        print(f"- {map_name}")
else:
    error_code = result.header.error_code if result.header is not None else "UNKNOWN"
    error_message = (
        result.header.error_message
        if result.header is not None
        else "response header is missing"
    )
    print(
        "get map list failed: "
        f"error_code={error_code}, error_message={error_message}"
    )

On this page