导航服务接口

介绍

导航服务接口：提供机器人在已定位地图中的导航功能，包括点位导航、位姿导航、多点航路规划，以及点位的增删查管理。

注意事项

使用导航前需确保：已加载地图 → 重定位成功 → 切换到导航模式（NAV_MODE）
使用高层技能 go_to_location 可自动完成上述前置步骤

功能	Python
导航到位置点	✔
导航到位姿	✔
多点航路导航	✔
取消导航	✔
暂停导航	✔
恢复导航	✔
等待导航完成	✔
注册导航事件回调	✔
获取当前位置	✔
添加点位	✔
删除点位	✔
获取可用点位	✔

导航控制

Python接口

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

功能说明
导航到已保存的命名点位。支持阻塞/非阻塞模式，以及完成/失败/进度三种事件回调。

参数说明

参数名	类型	必填/默认值	说明
`location`	`str`	必填	目标点位名称。也可用 `target` 或 `location_name` 作为关键字参数名。
`travel_params`	`MsgTravelParams`	默认: 默认参数	导航行驶参数（速度模式、步态等）。
`block`	`bool`	默认: `True`	`True` 时阻塞直到导航完成；`False` 时立即返回，后台执行。
`timeout`	`int`	默认: 600	导航超时时间（秒）。
`complete_callback`	`callable`	默认: `None`	导航成功到达时的回调，接收 `NavCompleteEvent`。
`failed_callback`	`callable`	默认: `None`	导航失败时的回调，接收 `NavFailedEvent`。
`progress_callback`	`callable`	默认: `None`	导航进度回调，接收 `NavProgressEvent`。

返回值

类型	说明
`IntelligentNavigationResponse`	`state.code == 0` 表示导航成功到达。

调用示例

python

from daystar_api.lowlevel_skills import navigation_to_location

# 简单导航（阻塞）
result = navigation_to_location("kitchen")
if result.state.code == 0:
    print("已到达目标点位")

# 非阻塞导航 + 回调
def on_complete(event):
    print("导航完成！")

def on_failed(event):
    print(f"导航失败: {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)`

功能说明
导航到指定的坐标位姿（位置 + 朝向）。支持直接传入坐标分量或 Pose 对象两种方式。

参数说明

参数名	类型	必填/默认值	说明
`x`, `y`, `z`	`float`	必填（或使用 `pose`）	目标位置坐标（米）。
`qw`, `qx`, `qy`, `qz`	`float`	默认: `qw=1.0`，其余 0.0	目标朝向四元数。
`pose`	`Pose`	与坐标参数二选一	目标位姿对象（`Pose` 或字典格式）。
`block`	`bool`	默认: `True`	`True` 时阻塞等待；`False` 时后台执行。
`timeout`	`int`	默认: 600	导航超时时间（秒）。
`complete_callback`	`callable`	默认: `None`	导航成功回调。
`failed_callback`	`callable`	默认: `None`	导航失败回调。
`progress_callback`	`callable`	默认: `None`	进度回调。

返回值

类型	说明
`IntelligentNavigationResponse`	`state.code == 0` 表示导航成功到达。

调用示例

python

from daystar_api.lowlevel_skills import navigation_to_pose, Pose

# 使用坐标参数
result = navigation_to_pose(x=1.0, y=2.0, z=0.0, qw=1.0)

# 使用 Pose 对象
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)`

功能说明
按顺序导航经过多个位姿航路点（路径跟踪）。

参数说明

参数名	类型	必填/默认值	说明
`exec_waypoints`	`list[PoseStamped]`	必填	航路点列表（`PoseStamped` 对象）。
`exec_type`	`int`	默认: 1	执行类型：`1` 自主导航；`2` 严格轨迹跟踪；`3` 直线拟合；`4` 圆弧拟合；`5` 正弦拟合。
`travel_params`	`MsgTravelParams`	默认: 默认参数	导航行驶参数。
`block`	`bool`	默认: `True`	`True` 时阻塞等待完成。
`timeout`	`int`	默认: 600	超时时间（秒）。

返回值

类型	说明
`NavigationViaPosesResponse`	`state.code == 0` 表示导航完成。

调用示例

python

from daystar_api.lowlevel_skills import navigation_via_poses, PoseStamped

waypoints = []
# 构建航路点列表...
result = navigation_via_poses(exec_waypoints=waypoints)

`cancel_navigation(timeout=5)`

功能说明
取消当前正在执行的导航任务。

参数说明

参数名	类型	必填/默认值	说明
`timeout`	`int`	默认: 5	取消操作超时时间（秒）。

返回值

类型	说明
`IntelligentNavigationResponse`	`state.code == 0` 表示取消成功。

调用示例

python

from daystar_api.lowlevel_skills import cancel_navigation

result = cancel_navigation()
if result.state.code == 0:
    print("导航已取消")

`pause_navigation()`

功能说明
暂停当前正在执行的导航任务，机器人停在当前位置等待恢复指令。

参数说明

无参数。

返回值

类型	说明
`IntelligentNavigationResponse`	`state.code == 0` 表示暂停成功。

调用示例

python

from daystar_api.lowlevel_skills import pause_navigation, resume_navigation
import time

pause_navigation()
print("导航已暂停")
time.sleep(5)
resume_navigation()

`resume_navigation()`

功能说明
恢复已暂停的导航任务，机器人继续向目标点位行进。

参数说明

无参数。

返回值

类型	说明
`IntelligentNavigationResponse`	`state.code == 0` 表示恢复成功。

调用示例

python

from daystar_api.lowlevel_skills import resume_navigation

result = resume_navigation()
if result.state.code == 0:
    print("导航已恢复")

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

功能说明
注册全局导航事件回调函数。回调将在所有后续导航任务中生效（包括通过 navigation_to_location 的 block=False 调用）。

参数说明

参数名	类型	必填/默认值	说明
`complete_cb`	`callable`	默认: `None`	导航成功完成时调用，接收 `NavCompleteEvent`（含终点信息）。
`failed_cb`	`callable`	默认: `None`	导航失败时调用，接收 `NavFailedEvent`（含失败原因和错误码）。
`progress_cb`	`callable`	默认: `None`	导航过程中周期性调用，接收 `NavProgressEvent`（含进度百分比）。

返回值

类型	说明
`None`	无返回值。

调用示例

python

from daystar_api.lowlevel_skills import register_event_callbacks, navigation_to_location

def on_complete(event):
    print("导航完成！")

def on_failed(event):
    print(f"导航失败: {event.reason}")

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

位置管理

Python接口

`get_current_pose(timeout=5)`

功能说明
获取机器人当前在地图中的位姿（位置 + 朝向）。

参数说明

参数名	类型	必填/默认值	说明
`timeout`	`int`	默认: 5	服务调用超时时间（秒）。

返回值

类型	说明
`GetCurrentPoseServiceResponse`	`state.code == 0` 表示成功；通过 `response.location_pose.position.x/y/z` 和 `response.location_pose.orientation.x/y/z/w` 访问位置和朝向（注意：类型为 `Pose`，不是 `PoseStamped`）。

调用示例

python

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"当前位置: x={pose.position.x:.2f}, y={pose.position.y:.2f}")

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

功能说明
将当前机器人位姿保存为命名点位。也支持指定虚拟位姿（无需机器人实际到达该位置）。

参数说明

参数名	类型	必填/默认值	说明
`location`	`str`	必填	点位名称。
`use_virtual_pose`	`bool`	默认: `False`	`True` 时使用 `virtual_pose` 而非机器人当前位姿。
`virtual_pose`	`Pose`	默认: 零位姿	虚拟点位的目标位姿（`use_virtual_pose=True` 时使用）。
`timeout`	`int`	默认: 5	服务调用超时时间（秒）。

返回值

类型	说明
`AddLocationServiceResponse`	`state.code == 0` 表示保存成功。

调用示例

python

from daystar_api.lowlevel_skills import add_location, Pose

# 保存机器人当前位置
add_location("kitchen")

# 保存虚拟点位（无需机器人到达）
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)`

功能说明
删除已保存的命名点位。

参数说明

参数名	类型	必填/默认值	说明
`location`	`str`	必填	要删除的点位名称。

返回值

类型	说明
`DeleteLocationResponse`	`state.code == 0` 表示删除成功；`result` 为布尔值。

调用示例

python

from daystar_api.lowlevel_skills import delete_location

result = delete_location("old_point")
if result.result:
    print("点位已删除")

`get_available_location(timeout=3)`

功能说明
获取系统中所有已注册的点位名称列表。

参数说明

参数名	类型	必填/默认值	说明
`timeout`	`int`	默认: 3	查询超时时间（秒）。

返回值

类型	说明
`GetAvailableLocationResponse`	`locations` 字段为点位信息列表，每项包含 `name`（点位名）和 `pose`（位姿）字段。

调用示例

python

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"点位: {name}")

# 检查点位是否存在
names = [loc["name"] for loc in result.locations]
if "kitchen" in names:
    print("kitchen 点位已注册")

SDK概述

机器狗服务

应用开发

软件服务接口

通用任务服务接口

导航服务接口

介绍

导航控制

Python接口

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

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

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

`cancel_navigation(timeout=5)`

`pause_navigation()`

`resume_navigation()`

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

位置管理

Python接口

`get_current_pose(timeout=5)`

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

`delete_location(location)`

`get_available_location(timeout=3)`

机器狗服务

通用任务服务接口

导航服务接口 ​

介绍 ​

导航控制 ​

Python接口 ​

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

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

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

cancel_navigation(timeout=5) ​

pause_navigation() ​

resume_navigation() ​

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

位置管理 ​

Python接口 ​

get_current_pose(timeout=5) ​

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

delete_location(location) ​

get_available_location(timeout=3) ​

导航服务接口

介绍

导航控制

Python接口

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

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

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

`cancel_navigation(timeout=5)`

`pause_navigation()`

`resume_navigation()`

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

位置管理

Python接口

`get_current_pose(timeout=5)`

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

`delete_location(location)`

`get_available_location(timeout=3)`