导航控制

本模块提供机器人导航相关的所有功能，包括位置导航、位姿导航、多点导航等。

核心功能

导航到位置

navigation_to_location(*args, **kwargs)

Navigate to a saved location point.

Parameters:

location (str) – Name of the target location (can also use ‘target’ or ‘location_name’)
travel_params (MsgTravelParams) – Travel parameters for navigation (default: MsgTravelParams)
block (bool) – Whether to block until navigation completes (default: True)
timeout (int) – Timeout in seconds (default: 600)
complete_callback (NavCompleteEvent) – Callback function when navigation completes (default: None)
failed_callback (NavFailedEvent) – Callback function when navigation fails (default: None)
progress_callback (NavProgressEvent) – Callback function for progress updates (default: None)

Return type:

IntelligentNavigationResponse

Returns:

IntelligentNavigationResponse.

Examples:

# Simple navigation to a location
result = navigation_to_location("kitchen")

# Non-blocking navigation with callbacks
def on_complete(event: NavCompleteEvent):
    print("Navigation completed!")

def on_failed(event: NavFailedEvent):
    print("Navigation failed:", event.error_msg)

def on_progress(event: NavProgressEvent):
    print(f"Distance remaining: {event.distance_remaining}")

result = navigation_to_location(
    location="kitchen",
    block=False,
    complete_callback=on_complete,
    failed_callback=on_failed,
    progress_callback=on_progress
)

# Using keyword argument variations
navigation_to_location(target="bedroom")
navigation_to_location(location_name="living_room", timeout=300)

导航到位姿

navigation_to_pose(*args, **kwargs)

Navigate to a specific pose (position + orientation).

Parameters:

pose (Pose) – Target pose (MsgPose object or dict with position/orientation)
x – Position coordinates (alternative to pose parameter)
y – Position coordinates (alternative to pose parameter)
z – Position coordinates (alternative to pose parameter)
qx – Quaternion orientation (alternative to pose parameter, qw defaults to 1.0)
qy – Quaternion orientation (alternative to pose parameter, qw defaults to 1.0)
qz – Quaternion orientation (alternative to pose parameter, qw defaults to 1.0)
qw – Quaternion orientation (alternative to pose parameter, qw defaults to 1.0)
travel_params (MsgTravelParams) – Travel parameters for navigation (default: MsgTravelParams)
block (bool) – Whether to block until navigation completes (default: True)
timeout (int) – Timeout in seconds (default: 600)
complete_callback (NavCompleteEvent) – Callback function when navigation completes (default: None)
failed_callback (NavFailedEvent) – Callback function when navigation fails (default: None)
progress_callback (NavProgressEvent) – Callback function for progress updates (default: None)

Return type:

IntelligentNavigationResponse

Returns:

IntelligentNavigationResponse.

Examples:

# Using coordinate parameters
result = navigation_to_pose(x=1.0, y=2.0, z=0.0, qw=1.0)

# Using MsgPose object
pose = MsgPose()
pose.position.x = 1.0
pose.position.y = 2.0
pose.orientation.w = 1.0
result = navigation_to_pose(pose=pose)

# Using dictionary
pose_dict = {
    "position": {"x": 1.0, "y": 2.0, "z": 0.0},
    "orientation": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0}
}
result = navigation_to_pose(pose=pose_dict)

# Non-blocking navigation with timeout
result = navigation_to_pose(
    x=3.0, y=4.0, z=0.0,
    block=False,
    timeout=300
)

# Non-blocking navigation with callbacks
def on_complete(event: NavCompleteEvent):
    print("Navigation completed!")

def on_failed(event: NavFailedEvent):
    print("Navigation failed:", event.error_msg)

def on_progress(event: NavProgressEvent):
    print(f"Distance remaining: {event.distance_remaining}")

result = navigation_to_pose(
    x=5.0, y=6.0, z=0.0,
    block=False,
    complete_callback=on_complete,
    failed_callback=on_failed,
    progress_callback=on_progress
)

多点导航

navigation_via_poses(exec_waypoints, exec_type=0, travel_params={'direction_constraint': 0, 'disable_body_obstacle_avoidance': False, 'distance_tolerance': 0.0, 'gait': 0, 'ignore_final_yaw': False, 'path_following_mode': 0, 'speed_mode': 0}, block=True, timeout=600, complete_callback=None, failed_callback=None, progress_callback=None)

Navigate through multiple waypoints.

Parameters:

exec_waypoints (List[MsgPoseStamped]) – List of waypoints (PoseStamped) to navigate through
exec_type (NavViaPosesExecType | int) – Execution type. Accepts the NavViaPosesExecType enum (recommended) or its underlying int value. Default: NavViaPosesExecType.MANUALROUTE (0, 巡检点位路线，折线，无邻点过滤). Other values: AUTONOMOUS=1, STRICTTRACK=2, FITTING_STRAIGHT=3, FITTING_CIRCULAR=4, FITTING_SINE=5.
travel_params (MsgTravelParams) – Travel parameters for navigation (default: MsgTravelParams). Note: per the underlying action server, travel_params is applied only at the last waypoint.
block (bool) – Whether to block until navigation completes (default: True)
timeout (int) – Timeout in seconds (default: 600)
complete_callback (NavCompleteEvent) – Per-call callback fired when navigation completes successfully (default: None). Bound to this call’s goal (per-goal); does not affect any global callback registered via register_navigation_callback and won’t be overridden by subsequent calls.
failed_callback (NavFailedEvent) – Per-call callback fired on failure (default: None). You may safely launch another non-blocking navigation_to_* (block=False) from inside this callback to chain to a fallback target — the new goal’s callbacks will fire normally. Blocking APIs (block=True / wait_for_navigation / cancel_navigation) inside the callback are rejected with a RuntimeError to avoid action-client deadlock.
progress_callback (NavProgressEvent) – Per-call callback fired on progress updates (default: None).

Returns:

NavigationViaPosesResponse.

navigation_via_locations(locations, exec_type=0, travel_params={'direction_constraint': 0, 'disable_body_obstacle_avoidance': False, 'distance_tolerance': 0.0, 'gait': 0, 'ignore_final_yaw': False, 'path_following_mode': 0, 'speed_mode': 0}, block=True, timeout=600, complete_callback=None, failed_callback=None, progress_callback=None)

Navigate through multiple registered locations (point yaml files).

Each location name is resolved against /root/data/daystar_api/points/<name>.yaml and its nav_pose is used as a PoseStamped waypoint. Any missing/invalid location aborts the call before any motion request is sent.

Parameters:

locations (List[str]) – Ordered list of registered location names.
exec_type (NavViaPosesExecType | int) – Execution type. Accepts the NavViaPosesExecType enum (recommended) or its underlying int value. Default: NavViaPosesExecType.MANUALROUTE (0, 巡检点位路线，折线，无邻点过滤). Other values: AUTONOMOUS=1, STRICTTRACK=2, FITTING_STRAIGHT=3, FITTING_CIRCULAR=4, FITTING_SINE=5.
travel_params (MsgTravelParams) – Travel parameters for navigation (default: MsgTravelParams). Note: per the underlying action server, travel_params is applied only at the last waypoint.
block (bool) – Whether to block until navigation completes (default: True)
timeout (int) – Timeout in seconds (default: 600)
complete_callback (NavCompleteEvent) – Per-call callback fired when navigation completes successfully (default: None). Bound to this call’s goal (per-goal); does not affect any global callback registered via register_navigation_callback and won’t be overridden by subsequent calls.
failed_callback (NavFailedEvent) – Per-call callback fired on failure (default: None). You may safely launch another non-blocking navigation_to_* (block=False) from inside this callback to chain to a fallback target — the new goal’s callbacks will fire normally. Blocking APIs (block=True / wait_for_navigation / cancel_navigation) inside the callback are rejected with a RuntimeError to avoid action-client deadlock.
progress_callback (NavProgressEvent) – Per-call callback fired on progress updates (default: None).

Returns:

NavigationViaPosesResponse.

Examples:

# 顺序经过三个已注册点位
result = navigation_via_locations(locations=["A", "B", "C"])
if result.state.code == 0:
    print("multi-stop navigation succeeded")

导航控制

cancel_navigation(timeout=5)

Cancel the current navigation task.

Parameters:: timeout (int) – Timeout in seconds for cancellation to complete (default: 5)
Return type:: IntelligentNavigationResponse
Returns:: CancelNavigationResponse.

Examples:

# Cancel current navigation
result = cancel_navigation()
if result.success:
    print("Navigation cancelled")

# Cancel with custom timeout
result = cancel_navigation(timeout=10)

# Cancel in emergency situation
if emergency_detected():
    cancel_navigation(timeout=2)
    print("Emergency stop executed")

pause_navigation()

Pause the current navigation task.

Return type:: IntelligentNavigationResponse
Returns:: PauseNavigationResponse.

Examples:

# Pause navigation temporarily
result = pause_navigation()
if result.success:
    print("Navigation paused")
# Perform some operation
time.sleep(5)
resume_navigation()

resume_navigation()

Resume a paused navigation task.

Return type:: IntelligentNavigationResponse
Returns:: ResumeNavigationResponse.

Examples:

# Resume after pause
pause_navigation()
time.sleep(5)
result = resume_navigation()
if result.success:
    print("Navigation resumed")

wait_for_navigation(timeout=600)

Wait for the most recent non-blocking NavigationTo* call to complete.

Navigation internally caches the last IntelligentNavigationResponse, so no resp argument is needed.

Parameters:: timeout (int) – Seconds to wait (default: 600). 0 means wait indefinitely.
Return type:: IntelligentNavigation_Result
Returns:: IntelligentNavigation_Result with result=True on success, or result=False and message=”Timeout or canceled” on failure.

Examples:

navigation_to_location("kitchen", block=False)
# do other work ...
result = wait_for_navigation(timeout=60)
if result.result:
    print("Arrived at kitchen")
else:
    print("Navigation failed:", result.message)

事件回调

register_event_callbacks(complete_cb=None, failed_cb=None, progress_cb=None)

Register global callbacks for navigation events.

Parameters:

complete_cb (Optional[Any]) – Callback function when navigation completes successfully (default: None)
info (- Receives NavCompleteEvent with success status and completion) –
failed_cb (Optional[Any]) – Callback function when navigation fails (default: None)
details (- Receives NavFailedEvent with failure reason and error) –
progress_cb (Optional[Any]) – Callback function for navigation progress updates (default: None)
state (- Receives NavProgressEvent with progress percentage and current) –

Return type:

None

Returns:

None

Examples:

# Define callback functions
def on_complete(event):
    print("Navigation completed successfully!")
    print(f"Final position: {event.final_pose}")

def on_failed(event):
    print(f"Navigation failed: {event.reason}")
    print(f"Error code: {event.error_code}")

def on_progress(event):
    print(f"Progress: {event.progress}% - State: {event.state}")

# Register all callbacks
register_event_callbacks(
    complete_cb=on_complete,
    failed_cb=on_failed,
    progress_cb=on_progress
)

# Register only completion callback
register_event_callbacks(complete_cb=on_complete)

# Start navigation - callbacks will be triggered
navigation_to_location("kitchen", block=False)

位置管理

获取当前位置

get_current_pose(timeout=5)

Get the robot’s current pose (position and orientation).

Parameters:: timeout (int) – Timeout in seconds for pose query (default: 5)
Return type:: GetCurrentPoseServiceResponse
Returns:: GetCurrentPoseResponse.

Examples:

# Get current pose with default timeout
result = get_current_pose()
if result.success:
    print(f"Position: x={result.pose.position.x}, y={result.pose.position.y}")
    print(f"Orientation: w={result.pose.orientation.w}")

添加位置点

add_location(location, use_virtual_pose=False, virtual_pose={'orientation': {'w': 1.0, 'x': 0.0, 'y': 0.0, 'z': 0.0}, 'position': {'x': 0.0, 'y': 0.0, 'z': 0.0}}, timeout=5)

Add a location point.

Parameters:

location (str) – Name of the location
timeout (int) – Timeout in seconds (default: 5)
use_virtual_pose (bool) – If True, use virtual_pose instead of robot’s current pose (default: False)
virtual_pose (Pose) – Virtual pose for creating location without moving robot (default: api::MsgPose()

Return type:

AddLocationServiceResponse

Returns:

AddLocationServiceResponse

Examples:

# Normal usage - save robot's current position
add_location("kitchen")

# Virtual point - create location without robot being there
virtual_pose = Pose()
virtual_pose.position.x = 1.0
virtual_pose.position.y = 2.0
virtual_pose.orientation.w = 1.0
add_location("virtual_point", use_virtual_pose=True, virtual_pose=virtual_pose)

删除位置点

delete_location(location)

Delete a saved location point.

Parameters:: location (str) – Name of the location to delete
Return type:: DeleteLocationResponse
Returns:: DeleteLocationServiceResponse

Examples:

# Delete a single location
result = delete_location("kitchen")
if result.success:
    print("Location deleted successfully")

# Delete multiple locations in a loop
locations_to_remove = ["point1", "point2", "point3"]
for loc in locations_to_remove:
    delete_location(loc)

获取可用位置

get_available_location(timeout=3)

Get all available saved location points.

Parameters:: timeout (int) – Timeout in seconds for the query (default: 3)
Return type:: GetAvailableLocationResponse
Returns:: GetAvailableLocationResponse.

Examples:

# Get all locations with default timeout
result = get_available_location()
print("Available locations:", result.locations)

# Get locations with custom timeout
result = get_available_location(timeout=5)
for loc in result.locations:
    print(f"Location: {loc}")

# Check if specific location exists
result = get_available_location()
if "kitchen" in result.locations:
    print("Kitchen location exists")