导航控制

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

核心功能

导航到位置

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)

  • path_following_mode (int) – 单点导航行为，便捷入口（不传时为 1=直线循线）。取值：1=PATH_MODE_DEFAULT 直线循线导航、2=PATH_MODE_OFF 关闭循线即自由绕障导航、3=PATH_MODE_AUTO 自动选择、4=PATH_MODE_STRICT 严格循线。显式传入时覆盖 travel_params 中的同名字段；不传且 travel_params 未设该字段时，底层统一按 1 处理。

  • block (bool) – Whether to block until navigation completes (default: True)

  • timeout (int) – 无进展超时（秒），默认 60：导航持续有进展（feedback/goal status 推进）则不限总时长，连续该秒数双静默才超时取消

  • 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=120)

# 单点直线循线导航（不传 path_following_mode 时的默认行为，等价写法）
navigation_to_location("kitchen", path_following_mode=1)

# 单点绕障导航（关闭循线，自由规划绕开障碍物）
navigation_to_location("kitchen", path_following_mode=2)

底层 ROS2 接口

  • 通道 1（点位解析）: 本接口先在本地解析点位文件，不经 ROS2（读取 $DAYSTAR_DATA_ROOT/points/ 下 yaml，优先当前地图子目录、回退一级目录）

  • 通道 2（导航执行）:

    • 类型: Action daystar_navigation_msgs/action/IntelligentNavitateToPose

    • 名称: /nav/intelligent_navigate_to_pose

    • 参数映射:

    封装参数

    原生字段（Goal）

    location

    由点位名解析出目标位姿填入 goal.exec_waypoints（长度 1， header.frame_id="map"；导航 0731 起 goal.pose 字段弃用， 单点行为由 travel_params.path_following_mode 决定）

    travel_params

    goal.travel_params

    path_following_mode

    goal.travel_params.path_following_mode（便捷入口，显式传入时覆盖 travel_params 中的同名字段）。1=直线循线、2=关闭循线即绕障、 3=自动选择、4=严格循线；不传时按 1 下发

    block / timeout / complete_callback / failed_callback / progress_callback

    客户端行为，不下发（timeout 为无进展超时：等待循环内 feedback/goal status 有进展即续期，连续该秒数双静默才超时取消，非总时长）

导航到位姿

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)

  • path_following_mode (int) – 单点导航行为，便捷入口（不传时为 1=直线循线）。取值：1=PATH_MODE_DEFAULT 直线循线导航、2=PATH_MODE_OFF 关闭循线即自由绕障导航、3=PATH_MODE_AUTO 自动选择、4=PATH_MODE_STRICT 严格循线。显式传入时覆盖 travel_params 中的同名字段；不传且 travel_params 未设该字段时，底层统一按 1 处理。

  • block (bool) – Whether to block until navigation completes (default: True)

  • timeout (int) – 无进展超时（秒），默认 60：导航持续有进展（feedback/goal status 推进）则不限总时长，连续该秒数双静默才超时取消

  • frame_id (str) – 目标位姿所在坐标系（default: “map”）。指点导航（机体相对坐标）传 “base_link”——x 正向为机身前方，y 正向为机身左方，yaw 为相对机身的转角

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

# 指点导航：前进 3 米（base_link 机体相对坐标，由导航栈经 TF 解算）
result = navigation_to_pose(x=3.0, y=0.0, qw=1.0, frame_id="base_link")

# 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=120
)

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

底层 ROS2 接口

  • 类型: Action daystar_navigation_msgs/action/IntelligentNavitateToPose

  • 名称: /nav/intelligent_navigate_to_pose

  • 参数映射:

封装参数

原生字段（Goal）

pose（或 x/y/z/qx/qy/qz/qw）

goal.exec_waypoints（长度 1，header.frame_id 取 frame_id 参数（默认 map，指点导航传 base_link，空串兜底 map），时间戳取 当前时刻；导航 0731 起 goal.pose 字段弃用，单点行为由 travel_params.path_following_mode 决定）

travel_params

goal.travel_params

path_following_mode

goal.travel_params.path_following_mode（便捷入口，显式传入时覆盖 travel_params 中的同名字段）。1=直线循线、2=关闭循线即绕障、 3=自动选择、4=严格循线；不传时按 1 下发

block / timeout / complete_callback / failed_callback / progress_callback
客户端行为，不下发（timeout 为无进展超时：等待循环内 feedback/goal status

有进展即续期，连续该秒数双静默才超时取消，非总时长）

Note

单点 ``path_following_mode`` 兜底（前向兼容）：TravelParams.msg 的 path_following_mode 无默认值声明，ROS 默认初始化为 0（PATH_MODE_UNKNOWN）， 不在单点行为表的合法取值内。SDK 在唯一的 goal 下发口 （Navigation::RequestNavigationAct）统一兜底：``exec_waypoints`` 长度为 1 且该字段为 ``0`` 时，按 ``1``（PATH_MODE_DEFAULT，直线循线）下发，并打一条 INFO。 显式设置的有效值不受影响。

判据取 exec_waypoints 长度而非「调用了哪个 API」——高层技能 daystar_api.highlevel_skills.go_to_location() 的单点情形底层走的是长度为 1 的 多点导航（navigation_via_locations / navigation_via_poses），在导航栈眼中 同样是单点，因此同样受此兜底覆盖。多点（长度 > 1）该字段不参与分支，不做改写。

多点导航

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=60, complete_callback=None, failed_callback=None, progress_callback=None)

Navigate through multiple waypoints. 只传 1 个途经点时等价于单点导航，行为由 travel_params.path_following_mode 决定（默认 1 直线循线，绕障需设 2）。

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, 巡检点位路线，折线，无邻点过滤). 自导航 0731 版本起多点导航仅支持 MANUALROUTE(0)；其余枚举 （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) – 无进展超时（秒），默认 60：多点路线持续有进展（feedback/goal status 推进）则不限总时长，连续该秒数双静默才超时取消

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

底层 ROS2 接口

  • 类型: Action daystar_navigation_msgs/action/IntelligentNavitateToPose

  • 名称: /nav/intelligent_navigate_to_pose

  • 参数映射:

封装参数

原生字段（Goal）

exec_waypoints

goal.exec_waypoints

exec_type

goal.exec_type（导航 0731 起多点仅支持 MANUALROUTE(0)， 其余值 SDK 直接返回失败）

travel_params

goal.travel_params（导航 0731 起单点目标位姿字段 goal.pose 弃用，保持默认空值）

travel_params.path_following_mode

仅在 exec_waypoints 长度为 1 时参与分支（此时等价于单点导航）： 1=直线循线、2=关闭循线即绕障；为 0（UNKNOWN）时 SDK 兜底按 1 下发。 长度 > 1 的真多点导航该字段不参与分支，恒为绕障

block / timeout / complete_callback / failed_callback / progress_callback
客户端行为，不下发（timeout 为无进展超时：等待循环内 feedback/goal status

有进展即续期，连续该秒数双静默才超时取消，非总时长）

Note

只传 1 个途经点时，本接口就是单点导航——导航栈按 exec_waypoints 长度判定行为， 与调用了哪个 API 无关。此时行为由 travel_params.path_following_mode 决定，想要绕障 必须显式传 2（PATH_MODE_OFF），否则按 1（直线循线）执行。详见 单点 path_following_mode 兜底。

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=60, complete_callback=None, failed_callback=None, progress_callback=None)

Navigate through multiple registered locations (point yaml files). 只传 1 个点位名时等价于单点导航，行为由 travel_params.path_following_mode 决定（默认 1 直线循线，绕障需设 2）。

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, 巡检点位路线，折线，无邻点过滤). 自导航 0731 版本起多点导航仅支持 MANUALROUTE(0)；其余枚举 （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) – 无进展超时（秒），默认 60：多点路线持续有进展（feedback/goal status 推进）则不限总时长，连续该秒数双静默才超时取消

  • 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")

底层 ROS2 接口

  • 通道 1（点位解析）: 本接口先在本地逐个解析点位文件，不经 ROS2（任一点位 缺失/非法则在发出任何运动请求前直接失败返回）

  • 通道 2（导航执行）:

    • 类型: Action daystar_navigation_msgs/action/IntelligentNavitateToPose

    • 名称: /nav/intelligent_navigate_to_pose

    • 参数映射:

    封装参数

    原生字段（Goal）

    locations

    逐个解析为 geometry_msgs/PoseStamped（frame_id="map"）填入 goal.exec_waypoints

    exec_type

    goal.exec_type（导航 0731 起多点仅支持 MANUALROUTE(0)， 其余值 SDK 直接返回失败）

    travel_params

    goal.travel_params

    travel_params.path_following_mode

    仅在 locations 长度为 1 时参与分支（此时等价于单点导航）： 1=直线循线、2=关闭循线即绕障；为 0（UNKNOWN）时 SDK 兜底按 1 下发。 长度 > 1 的真多点导航该字段不参与分支，恒为绕障

    block / timeout / complete_callback / failed_callback / progress_callback

    客户端行为，不下发（timeout 为无进展超时：等待循环内 feedback/goal status 有进展即续期，连续该秒数双静默才超时取消，非总时长）

Note

同 navigation_via_poses()：只传 1 个点位名时，本接口就是单点导航，行为由 travel_params.path_following_mode 决定，想要绕障必须显式传 2。高层技能 daystar_api.highlevel_skills.go_to_location() 的单点情形正是走这条路径。 详见 单点 path_following_mode 兜底。

导航控制

cancel_navigation(timeout=5)

Cancel the current navigation task.

Parameters:

timeout (int) – Timeout in seconds for cancellation to complete (default: 5)

Returns:

state.code == 0 表示取消成功

  • state: State object with code and describe

  • response: IntelligentNavigation_Result (result/error_code/error_msg)

Return type:

IntelligentNavigationResponse

Examples:

# Cancel current navigation
result = cancel_navigation()
if result.state.code == 0:
    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")

底层 ROS2 接口

  • 类型: Action 取消请求（async_cancel_all_goals，对应 Action 内置取消服务 /nav/intelligent_navigate_to_pose/_action/cancel_goal，类型 action_msgs/srv/CancelGoal）

  • 名称: /nav/intelligent_navigate_to_pose

  • 参数映射:

封装参数

原生字段

timeout

客户端行为，不下发（等待取消确认的时长）
pause_navigation()

Pause the current navigation task.

Returns:

state.code == 0 表示暂停成功

Return type:

IntelligentNavigationResponse

Examples:

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

底层 ROS2 接口

  • 类型: Action 取消请求（async_cancel_all_goals，对应 Action 内置取消服务 /nav/intelligent_navigate_to_pose/_action/cancel_goal，类型 action_msgs/srv/CancelGoal）

  • 名称: /nav/intelligent_navigate_to_pose

  • 说明: 「暂停」= 取消当前 goal 并在进程内缓存最近一次导航目标，供 resume_navigation() 重发；不向底层发送独立的 pause 指令。本函数无入参。

resume_navigation()

Resume a paused navigation task (async dispatch).

恢复被 pause_navigation() 暂停的导航：重发缓存的最后目标。多航点目标 （navigation_via_poses / navigation_via_locations）恢复时按当前位姿裁剪 已走过的航点，只重发剩余段（终点必留）。目标为异步派发——本函数立即返回 “已重发”，不等导航走完；需要等待完成用 wait_for_navigation()。

Returns:

state.code == 0 表示恢复目标已成功重发

  • response.result: bool, 目标是否已派发

  • future: 恢复后导航的结果句柄（wait_for_navigation 内部使用）

Return type:

IntelligentNavigationResponse

Examples:

# Resume after pause, then wait for the resumed navigation to finish
pause_navigation()
time.sleep(5)
result = resume_navigation()
if result.state.code == 0:
    nav_result = wait_for_navigation(timeout=600)
    print(f"Navigation finished: {nav_result.result}")

Note

  • 恢复的前提是此前有过导航目标（navigation_to_location / navigation_via_poses 等会缓存最后目标）

  • 本函数不阻塞等待导航完成，完成结果经 wait_for_navigation() 获取

底层 ROS2 接口

  • 类型: Action daystar_navigation_msgs/action/IntelligentNavitateToPose

  • 名称: /nav/intelligent_navigate_to_pose

  • 说明: 重发进程内缓存的最近一次导航 Goal（刷新时间戳后原样下发， travel_params 等沿用上次值）；若缓存丢失，先在本地扫描点位 yaml 按上次目标点位名重建 Goal（该重建不经 ROS2）。本函数无入参。

wait_for_navigation(timeout=300)

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: 300). 0 means wait indefinitely.

Return type:

IntelligentNavigation_Result

Returns:

IntelligentNavigation_Result with result=True on success, or result=False and error_msg=”Timeout or canceled” on failure.

  • result: bool, 是否成功

  • error_code: int, 失败错误码

  • error_msg: str, 失败原因

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.error_msg)

底层 ROS2 接口

本接口不经 ROS2 通道（纯客户端实现：阻塞等待最近一次非阻塞 navigation_to_* 调用缓存的 Action 结果回调/future 完成；timeout 为客户端等待时长，不向底层发送任何请求）。

事件回调

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)

底层 ROS2 接口

本接口不经 ROS2 通道（纯进程内实现：注册全局回调函数；回调事件由 /nav/intelligent_navigate_to_pose Action 的 feedback/result 回调驱动， 本函数自身不发送任何 ROS2 请求）。

位置管理

获取当前位置

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)

Returns:

当前位姿响应

  • state: State object with code and describe

  • response.success: bool, 位姿查询是否成功

  • response.location_pose: Pose, 当前位姿（position.x/y/z + orientation 四元数）

Return type:

GetCurrentPoseServiceResponse

Examples:

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

底层 ROS2 接口

  • 类型: Service api_msgs/srv/GetCurrentPose

  • 名称: /sdk/nav/get_current_pose

  • 参数映射:

封装参数

原生字段（Request）

（无业务参数）

Request 为空（由服务端返回 location_pose / success / message）

timeout

客户端行为，不下发（等待服务响应的时长）

添加位置点

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 (bound to the current map).

保存当前机器人位置为命名点位。点位自动绑定当前地图：已加载地图时写入 /root/data/daystar_api/points/<当前地图>/<name>.yaml 并在文件中记录 map 属性； 取不到当前地图（未加载地图）时落 points/ 一级目录，作为不绑定地图的通用点位（老行为）。

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)

底层 ROS2 接口

  • 通道 1（取当前位姿，仅 ``use_virtual_pose=False`` 时）:

    • 类型: Service api_msgs/srv/GetCurrentPose

    • 名称: /sdk/nav/get_current_pose

    • 参数映射:

    封装参数

    原生字段（Request）

    （无业务参数）

    Request 为空（仅用于取回机器人当前位姿）

    timeout

    客户端行为，不下发（等待服务响应的时长）

  • 通道 2（点位落盘）: 不经 ROS2 —— 位姿写入本地 yaml （$DAYSTAR_DATA_ROOT/points/ 下，按当前地图/建图会话三分支选目录； location 仅作为文件名与 point_name，不下发）

  • 说明: use_virtual_pose=True 时直接以 virtual_pose 落盘， 完全不经 ROS2；目录归属判断读取 /nav/current_map 与 /nav/current_localization_mode 的订阅缓存，不发新请求。

删除位置点

delete_location(location)

Delete a saved location point (current-map scope).

删除已注册命名点位。查找口径与读取一致：优先删当前地图子目录 points/<当前地图>/<name>.yaml，找不到再回退删一级目录的同名通用点位（前向兼容）。 其他地图的同名点位不受影响。

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)

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：删除点位 yaml 文件，查找口径为 points/<当前地图>/<name>.yaml 优先、回退一级目录；「当前地图」取自 /nav/current_map 订阅缓存，不发新请求）。

批量删除位置点

delete_locations(location_names=[], delete_all=False)

Batch-delete saved location points.

批量删除已注册命名地点。传 location_names 列表删除指定地点（单元素=指定，多元素=批量）； delete_all=True 时忽略 location_names，快速删除全部”当前地图点位”（= 当前地图子目录 ∪ 一级目录通用点位，不碰其他地图子目录）。删除不可恢复。

Parameters:

  • location_names (list[str]) – 要删除的地点名称列表（delete_all=True 时可省略）

  • delete_all (bool) – 为 True 时删除全部地点，默认 False

Returns:

批量删除结果

  • result: bool，是否全部成功

  • deleted: list[str]，成功删除的名称

  • failed: list[str]，删除失败的名称

Return type:

DeleteLocationsResponse

Examples:

# 删除指定若干地点
delete_locations(["point1", "point2"])

# 快速删除全部地点
delete_locations(delete_all=True)

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：循环删除点位 yaml；delete_all=True 时枚举当前地图子目录与一级目录下全部 *.yaml 后逐个删除）。

删除地图

delete_map(map_name)

Delete a saved map by name.

删除指定名称的已保存地图（移除整个地图目录，不可恢复）。地图存于 /root/data/daystar_api/maps/<map_name>/。允许删除当前正在使用的地图：照常删除， 但返回的 state.describe 会附带”导航功能将不可用”警告，需加载其他地图后导航才能恢复。

Parameters:

map_name (str) – 要删除的地图名称（禁止含 / \ 或 .. 等路径分隔/上跳）

Returns:

删除结果

  • state: 状态（state.code==0 成功）

  • result: bool，是否成功删除

Return type:

DeleteMapResponse

Examples:

# 删除单张地图
result = delete_map("office_floor1")
if result.result:
    print("地图已删除")

# 批量删除多张地图
for name in ["old_map_1", "old_map_2"]:
    delete_map(name)

Note

  • 地图不存在或名称非法时 result=False，state.describe 含原因

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：递归删除地图目录 /root/data/daystar_api/maps/<map_name>/）。

批量删除地图

delete_maps(map_names=[], delete_all=False, include_current=False)

Batch-delete saved maps.

批量删除已保存地图。传 map_names 列表删除指定地图（单元素=指定，多元素=批量， 列表点名当前正在使用的地图时照删，返回 message 附带”导航不可用”警告）； delete_all=True 时忽略 map_names，快速删除全部已保存地图（服务端枚举地图目录逐个删除， 无需先查名字），删除范围由 include_current 控制：False（默认）保留当前正在使用的地图 （见 skipped），True 连当前地图一并删除。删除移除整个地图目录，不可恢复。

Parameters:

  • map_names (list[str]) – 要删除的地图名称列表（delete_all=True 时忽略）

  • delete_all (bool) – 为 True 时删除全部地图，默认 False（优先级最高）

  • include_current (bool) – 仅 delete_all=True 时生效；True=当前地图一并删除，默认 False=保留

Returns:

批量删除结果

  • result: bool，是否全部成功

  • deleted: list[str]，成功删除的名称

  • failed: list[str]，删除失败的名称

  • skipped: list[str]，被保护跳过的地图（仅 delete_all=True 且 include_current=False 时可能非空）

Return type:

DeleteMapsResponse

Examples:

# 删除指定若干地图
r = delete_maps(["old_1", "old_2"])
print("已删除:", r.deleted, "失败:", r.failed)

# 快速删除全部地图（保留当前地图）
delete_maps(delete_all=True)

# 全部删除，包括当前正在使用的地图（返回 message 会附带导航不可用警告）
delete_maps(delete_all=True, include_current=True)

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：循环删除地图目录；delete_all=True 时枚举 /root/data/daystar_api/maps/ 下全部子目录，并按 /nav/current_map 订阅缓存保护当前地图不删，不发新请求）。

获取可用位置

get_available_location(timeout=30)

Get all available saved location points (current-map scope).

获取当前地图下可用的全部点位 = points/<当前地图>/ 子目录点位 ∪ 一级目录通用点位 （无 map 归属的旧式点位，前向兼容），重名时当前地图子目录优先。未加载地图时仅返回 一级目录通用点位。

Parameters:

timeout (int) – Timeout in seconds for the query (default: 3)

Returns:

locations 为 dict 列表，每项含

  • name: 点位名

  • map: 点位归属的地图名；”” 表示未绑定地图的通用点位

  • pose: {position: {x,y,z}, orientation: {x,y,z,w}}

Return type:

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

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：扫描 $DAYSTAR_DATA_ROOT/points/ 下当前地图子目录与一级目录的 *.yaml；timeout 为客户端参数， 当前实现为纯目录扫描、未实际使用）。

全量设置停障检测范围

set_obstacle_detection_limit(front_stop_distance, front_detection_width, rear_stop_distance, rear_detection_width, min_height, max_height, block=True, timeout=30)

全量设置停障检测范围（前/后停障距离与宽度 + 检测高度带，单位：米）。

用途：设置 guardian 停障检测的前方/后方停障盒与检测高度带。6 个业务参数同时生效 （底层为全量设置接口，无法只改部分维度），例如机器人需要感知比默认范围更低的沟坎 或更高的台面时，可调整高度带；需要调整绕障贴近程度时，可调整前后停障距离与宽度。

Parameters:

  • front_stop_distance (float) – 前方停障距离（米，base_link 坐标系，距机体几何中心）。 必须为正有限值。距前方障碍小于该值即停车。

  • front_detection_width (float) – 前方检测宽度（米）。必须为正有限值。

  • rear_stop_distance (float) – 后方停障距离（米）。必须为正有限值。

  • rear_detection_width (float) – 后方检测宽度（米）。必须为正有限值。

  • min_height (float) – 检测高度下限（米）。必须是有限值，且严格小于 max_height。

  • max_height (float) – 检测高度上限（米）。必须是有限值，且严格大于 min_height。

  • block (bool) – True 则阻塞等待底层服务返回（内部最大等待上限）；False 时用 timeout 作等待上限（默认: True）

  • timeout (int) – 超时秒数，仅 block=False 时生效（默认: 30）

Returns:

  • state: 操作状态（code 0=成功）

  • response: 底层服务响应

    • success: 更新结果，True-成功；False-失败（参数校验失败等）

    • message: 结果说明，失败时给出原因

Return type:

SetObstacleDetectionLimitResponse

Examples:

# 前方停障 0.30m/宽 0.50m，后方停障 0.30m/宽 0.30m，高度带 [-0.10, 0.10] 米
result = set_obstacle_detection_limit(0.30, 0.50, 0.30, 0.30, -0.10, 0.10)
if result.response.success:
    print("停障检测范围已更新")
else:
    print(f"更新失败: {result.response.message}")

# 放宽高度带到 [-0.45, 0.50] 米（前后停障参数须同时给全量值）
result = set_obstacle_detection_limit(0.30, 0.50, 0.30, 0.30, -0.45, 0.50)

Note

  • 更新成功后立即作用于里程计感知、原始速度指令感知和辅助遥控感知三条路径，无需重启节点。

  • 本接口为全量设置：每次调用 6 个业务参数同时生效，只想改高度带时也须显式给出 前后停障参数（可参考典型值 0.30/0.50/0.30/0.30）。

  • 导航端校验失败（非有限值、停障参数非正、min_height >= max_height）时不修改当前检测范围。

底层 ROS2 接口

  • 类型: Service daystar_navigation_msgs/srv/SetObstacleDetectionRegion

  • 名称: /nav/set_obstacle_detection_limit

  • 参数映射:

全量设置语义：6 个业务参数同时生效，无法只改部分维度，只想调整高度带时 也须显式给出前后停障参数（可参考典型值 0.30/0.50/0.30/0.30）。更新成功后 立即作用于里程计感知、原始速度指令感知和辅助遥控感知三条路径，无需重启节点。