Navigation Service Interfaces

Introduction

Navigation Service Interfaces:
Provides robot navigation within a localized map, including location navigation, pose navigation, multi-waypoint route planning, and location point add/delete/query management.

Prerequisites:

1. Before using navigation: load a map → relocalization success → switch to navigation mode (NAV_MODE)
2. Use the high-level skill go_to_location to automatically complete the above prerequisites

Purpose	Python
Navigate to Location	✔
Navigate to Pose	✔
Multi-waypoint Navigation	✔
Cancel Navigation	✔
Pause Navigation	✔
Resume Navigation	✔
Wait for Navigation to Complete	✔
Register Navigation Event Callbacks	✔
Get Current Pose	✔
Add Location	✔
Delete Location	✔
Get Available Locations	✔

Navigation Control

Python Interface

navigation_to_location(location, travel_params=None, block=True, timeout=600, complete_callback=None, failed_callback=None, progress_callback=None)

Function Description
Navigate to a saved named location. Supports blocking/non-blocking mode and complete/failed/progress event callbacks.

Parameter Description

Parameter Name	Type	Required/Default	Description
location	str	Required	Target location name. Can also use target or location_name as keyword argument names.
travel_params	MsgTravelParams	Default params	Navigation travel parameters (speed mode, gait, etc.).
block	bool	True	If True, blocks until navigation completes; if False, returns immediately and runs in background.
timeout	int	600	Navigation timeout in seconds.
complete_callback	callable	None	Callback when navigation successfully arrives; receives NavCompleteEvent.
failed_callback	callable	None	Callback when navigation fails; receives NavFailedEvent.
progress_callback	callable	None	Progress callback during navigation; receives NavProgressEvent.

Return Value

Type	Description
IntelligentNavigationResponse	state.code == 0 indicates navigation successfully arrived.

Example

from daystar_api.lowlevel_skills import navigation_to_location

# Simple navigation (blocking)
result = navigation_to_location("kitchen")
if result.state.code == 0:
    print("Arrived at target location")

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

def on_failed(event):
    print(f"Navigation failed: {event.error_msg}")

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

---

navigation_to_pose(x=None, y=None, z=None, qw=1.0, qx=0.0, qy=0.0, qz=0.0, pose=None, travel_params=None, block=True, timeout=600, complete_callback=None, failed_callback=None, progress_callback=None)

Function Description
Navigate to a specified coordinate pose (position + orientation). Supports passing coordinate components directly or a Pose object.

Parameter Description

Parameter Name	Type	Required/Default	Description
x, y, z	float	Required (or use pose)	Target position coordinates (meters).
qw, qx, qy, qz	float	qw=1.0, others 0.0	Target orientation as quaternion.
pose	Pose	Alternative to coordinates	Target pose object (Pose or dict format).
block	bool	True	If True, blocks and waits; if False, runs in background.
timeout	int	600	Navigation timeout in seconds.
complete_callback	callable	None	Navigation success callback.
failed_callback	callable	None	Navigation failure callback.
progress_callback	callable	None	Progress callback.

Return Value

Type	Description
IntelligentNavigationResponse	state.code == 0 indicates navigation successfully arrived.

Example

from daystar_api.lowlevel_skills import navigation_to_pose, Pose

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

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

---

navigation_via_poses(exec_waypoints, exec_type=1, travel_params=None, block=True, timeout=600)

Function Description
Navigate sequentially through multiple pose waypoints (path tracking).

Parameter Description

Parameter Name	Type	Required/Default	Description
exec_waypoints	list[PoseStamped]	Required	List of waypoints (PoseStamped objects).
exec_type	int	1	Execution type: 1 autonomous navigation; 2 strict trajectory tracking; 3 line fitting; 4 arc fitting; 5 sine fitting.
travel_params	MsgTravelParams	Default params	Navigation travel parameters.
block	bool	True	If True, blocks until completion.
timeout	int	600	Timeout in seconds.

Return Value

Type	Description
NavigationViaPosesResponse	state.code == 0 indicates navigation completed.

Example

from daystar_api.lowlevel_skills import navigation_via_poses, PoseStamped

waypoints = []
# Build waypoint list...
result = navigation_via_poses(exec_waypoints=waypoints)

---

cancel_navigation(timeout=5)

Function Description
Cancel the currently executing navigation task.

Parameter Description

Parameter Name	Type	Required/Default	Description
timeout	int	5	Cancel operation timeout in seconds.

Return Value

Type	Description
IntelligentNavigationResponse	state.code == 0 indicates cancellation succeeded.

Example

from daystar_api.lowlevel_skills import cancel_navigation

result = cancel_navigation()
if result.state.code == 0:
    print("Navigation cancelled")

---

pause_navigation()

Function Description
Pause the currently executing navigation task. The robot stops at its current position and waits for a resume command.

Parameter Description

No parameters.

Return Value

Type	Description
IntelligentNavigationResponse	state.code == 0 indicates pause succeeded.

Example

from daystar_api.lowlevel_skills import pause_navigation, resume_navigation
import time

pause_navigation()
print("Navigation paused")
time.sleep(5)
resume_navigation()

---

resume_navigation()

Function Description
Resume a paused navigation task. The robot continues toward the target location.

Parameter Description

No parameters.

Return Value

Type	Description
IntelligentNavigationResponse	state.code == 0 indicates resume succeeded.

Example

from daystar_api.lowlevel_skills import resume_navigation

result = resume_navigation()
if result.state.code == 0:
    print("Navigation resumed")

---

wait_for_navigation(timeout=600)

Function Description
Wait for the most recent non-blocking navigation call to complete. Navigation internally caches the last response, so no argument is needed.

Parameter Description

Parameter Name	Type	Required/Default	Description
timeout	int	600	Seconds to wait. 0 means wait indefinitely.

Return Value

Type	Description
IntelligentNavigation_Result	result=True on success; result=False and message="Timeout or canceled" on failure.

Example

from daystar_api.lowlevel_skills import navigation_to_location, wait_for_navigation

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)

Function Description
Register global navigation event callback functions. Callbacks will apply to all subsequent navigation tasks, including non-blocking calls via navigation_to_location.

Parameter Description

Parameter Name	Type	Required/Default	Description
complete_cb	callable	None	Called when navigation completes successfully; receives NavCompleteEvent (contains final position info).
failed_cb	callable	None	Called when navigation fails; receives NavFailedEvent (contains failure reason and error code).
progress_cb	callable	None	Called periodically during navigation; receives NavProgressEvent (contains progress percentage).

Return Value

Type	Description
None	No return value.

Example

from daystar_api.lowlevel_skills import register_event_callbacks, navigation_to_location

def on_complete(event):
    print("Navigation complete!")

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

register_event_callbacks(complete_cb=on_complete, failed_cb=on_failed)
navigation_to_location("kitchen", block=False)

Location Management

Python Interface

get_current_pose(timeout=5)

Function Description
Get the robot's current pose (position and orientation) in the map.

Parameter Description

Parameter Name	Type	Required/Default	Description
timeout	int	5	Service call timeout in seconds.

Return Value

Type	Description
GetCurrentPoseServiceResponse	state.code == 0 indicates success; access position and orientation via response.location_pose.position.x/y/z and response.location_pose.orientation.x/y/z/w (note: type is Pose, not PoseStamped).

Example

from daystar_api.lowlevel_skills import get_current_pose

result = get_current_pose()
if result.state.code == 0 and result.response.success:
    pose = result.response.location_pose
    print(f"Current position: x={pose.position.x:.2f}, y={pose.position.y:.2f}")

---

add_location(location, use_virtual_pose=False, virtual_pose=None, timeout=5)

Function Description
Save the robot's current pose as a named location. Also supports specifying a virtual pose (without the robot physically being at that location).

Parameter Description

Parameter Name	Type	Required/Default	Description
location	str	Required	Location name.
use_virtual_pose	bool	False	If True, use virtual_pose instead of the robot's current pose.
virtual_pose	Pose	Zero pose	Target pose for virtual location (used when use_virtual_pose=True).
timeout	int	5	Service call timeout in seconds.

Return Value

Type	Description
AddLocationServiceResponse	state.code == 0 indicates save succeeded.

Example

from daystar_api.lowlevel_skills import add_location, Pose

# Save robot's current position
add_location("kitchen")

# Save virtual location (robot doesn't need to be 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)

Function Description
Delete a saved named location.

Parameter Description

Parameter Name	Type	Required/Default	Description
location	str	Required	Name of the location to delete.

Return Value

Type	Description
DeleteLocationResponse	state.code == 0 indicates deletion succeeded; result is a boolean.

Example

from daystar_api.lowlevel_skills import delete_location

result = delete_location("old_point")
if result.result:
    print("Location deleted")

---

get_available_location(timeout=3)

Function Description
Get a list of all registered location names in the system.

Parameter Description

Parameter Name	Type	Required/Default	Description
timeout	int	3	Query timeout in seconds.

Return Value

Type	Description
GetAvailableLocationResponse	locations field is a list of location info; each entry contains name (location name) and pose (pose) fields.

Example

from daystar_api.lowlevel_skills import get_available_location

result = get_available_location()
for loc in result.locations:
    name = loc["name"] if isinstance(loc, dict) else str(loc)
    print(f"Location: {name}")

# Check if a location exists
names = [loc["name"] for loc in result.locations]
if "kitchen" in names:
    print("kitchen location is registered")