更新日志

版本 1.0.7 (2026-05-14)

新功能

  • ✨ navigation_via_poses / navigation_via_locations 新增 per-call 回调参数 complete_callback / failed_callback / progress_callback，与 navigation_to_pose 风格对齐。底层通过新增的 NavCallbackGuard RAII 临时安装， 调用结束自动还原成调用前的全局回调（不污染其它模块注册的回调）。

  • 🛡️ C++ 层新增**回调死锁防御**：navigation_client_ 绑在 send_goal_cb_group_ （MutuallyExclusive），在 complete/failed/progress 回调内部再调阻塞型 nav API 会自锁。 通过 thread_local 标志 + RAII 在用户 callback 入口置位；RequestNavigationAct(block=true) / WaitForNavigation / RequestCancelNav 入口检测到立刻抛 std::runtime_error （Python 端见为 RuntimeError），错误消息说明替代方案。

改进

  • 🔧 highlevel skill go_to_location 重构（不兼容变更）：

    • 移除 waypoints 参数；新增 locations: List[str] / poses: List[Pose] 显式多点列表参数。”先经过 A、B 再到 C” 现在直接写 locations=["A", "B", "C"]。

    • 四个目标参数互斥：location / pose / locations / poses，必须且只能给一个。

    • 底层统一走多点导航 API：名字目标 → navigation_via_locations， 位姿目标 → navigation_via_poses。不再单独调 ``navigation_to_pose``——单点情形等价于 长度为 1 的多点导航。

    • 单 location / pose 配合路网时，最短路径展开为完整节点序列（含起点）后**一次性下发**， 不再分”中间段 + 最终段”两次调用。是否 skip 已到达 waypoint 由底层控制器判定。

    • 修复旧版 path_ids[:-1] 切片把”起点”塞进 transit、把”终点”从 transit 中剥离的语义错误； 现在路径列表原样下发，与显式 locations 入参在底层眼中完全等价。

    • travel_params 不再被高层改写 ignore_final_yaw=True：现在列表最后一个就是真正的终点， travel_params 直接透传，终点 yaw 对齐按用户配置生效。

    • 回调改为底层 per-call 安装，不再使用 register_event_callbacks 全局注册的 hack； 完成 / 失败 / 进度三类回调对整条多点导航都生效（旧版仅最终段触发）。

    • 返回类型：_lowlevel_skills.IntelligentNavigationResponse → _lowlevel_skills.NavigationViaPosesResponse。两者都有 state.code / state.cn， 调用方代码通常无需改动。

  • 📝 同步 _lowlevel_skills.pyi：navigation_via_poses / navigation_via_locations 签名追加 3 个 callback 参数 + docstring 说明 per-call 安装机制。

  • 📚 highlevel_skills 模块 章节按新签名重写：参数表、执行路径表、回调死锁防御说明、示例代码全部更新。

  • 📚 skills/go-to-location/SKILL.md 同步：移除 waypoints，新增 locations 抽取提示； script_template 更新；版本号 2.0。

  • 🔧 navigation 回调改为 **per-goal 闭包绑定**（替代 NavCallbackGuard 栈作用域 RAII）。 修复在 failed_callback 内调 navigation_*(block=False) 跳到下一个目标点时， 新 goal 的 complete/failed/progress 回调链断裂的问题。block=True 在回调内仍抛 RuntimeError。

  • 🔧 修复 launch ctrl+c 后导航 goal 残留、task 子进程变孤儿。StopExecution 改为 SIGINT → 等 3s → SIGKILL 两阶段；TaskEngineNode::onConfigure 通过节点 context 注册 on_shutdown 回调，在 rclcpp::shutdown() 早期主动调 TaskManager::Shutdown， 绕开 component 析构时序。

  • 📝 _lowlevel_skills.pyi 中 navigation_via_* 的 callback 字段说明同步到 per-goal 语义； go_to_location.py 的 callback note 段落同步。

版本 1.0.6 (2026-05-13)

新功能

  • ✨ 新增 navigation_via_locations —— 按已注册点位名序列做多点导航，内部循环 LoadSingleLocation 读取 /root/data/daystar_api/points/<name>.yaml 的 nav_pose 拼成 PoseStamped 列表后委托给底层 NavigationViaPoses，任一点位 yaml 加载失败时不会发起底层调用并在错误描述中带出具体哪个点位无法解析。返回类型复用 _lowlevel_skills.NavigationViaPosesResponse。

  • ✨ 新增 ROS2 服务 /sdk/nav/navigation_via_locations``（srv 类型 ``api_msgs::srv::NavigationViaLocations）作为该接口的对外暴露通道。

  • ✨ 新增绑定类型 _lowlevel_skills.SrvAPINavigationViaLocations_Response`（字段语义与 :class:`_lowlevel_skills.SrvAPINavigationViaPoses_Response 一致）。

改进

  • 🔧 highlevel skill go_to_location 重构：新增 waypoints: Optional[List[str]] 参数，可在不依赖路网文件的前提下显式指定必经中间点列表；中间段统一改为调用 navigation_via_locations``（取代原先客户端拼 PoseStamped 列表的写法）；最终段统一改为 ``navigation_to_pose，complete_callback / failed_callback / progress_callback 始终挂在最终段（中间段不触发回调）。

  • 📝 _lowlevel_skills.pyi 同步 navigation_via_locations 函数 stub 与 SrvAPINavigationViaLocations_Response 类 stub，__all__ 同步更新。

  • 📚 新增 highlevel_skills 模块 章节，首批收录 go_to_location；采用手写 py:function 指令（与 逻辑流控制 同风格），不依赖 daystar_api 顶层包的 autodoc 链。

版本 1.0.5 (2026-05-11)

改进

  • 🔧 api_msgs 中含 timeout 字段的 srv 文件统一补充默认值，与 daystar_api 对应函数签名对齐：

    • LoadMap.srv — auto_reload=true, block=false, timeout=30

    • StopMapping.srv — auto_reload=false, need_2d_map=true, block=true, timeout=30

    • AddLocation.srv — timeout=5, use_virtual_pose=false

    • NavigateToPosition.srv / NavigateToLocation.srv — timeout=600

  • 🔧 DaystarServiceNode::LoadMapCallback 此前漏传 req->timeout，现已传入；block=false 时 timeout 真正生效，<=0 时回退到 daystar_api 默认值 30。

  • 🔧 DaystarServiceNode::StopMappingCallback 同样漏传 req->timeout，按相同模式修正。

  • 📝 stop_mapping / load_map docstring 修正 block 与 timeout 的语义说明：block=True 时使用内部最大等待（kBlockMaxTimeoutSeconds = 30 分钟），timeout 参数仅在 block=False 时生效。

  • 🔧 navigation_via_poses 默认 exec_type 由 1=AUTONOMOUS 改为 0=MANUALROUTE``（巡检点位路线，折线无邻点过滤），符合多点导航的常见使用模式；``NavigationViaPoses.srv 同步补充 MANUALROUTE=0 常量与默认值。

  • 🔧 NavigationViaPoses 实现内显式置空 ``goal.pose.header.frame_id``（多点导航下该单点目标位姿不使用），避免上游残留 frame_id 干扰下游解析。

版本 1.0.4 (2026-04-29)

新功能

  • ✨ pybind11 几何/基础数据类型构造糖：16 个类（Point/Vector3/Quaternion/Pose/PoseStamped/Twist/PoseWithCovariance/TwistWithCovariance/PoseWithCovarianceStamped/Header/Time/State/MsgTravelParams/BatteryState/FileInfo/MapFileInfo）新增**位置参数 + kwargs 构造**支持，例如 Point(1.0, 2.0, 3.0) / Pose(position=Point(0.5, 0, 0))。

  • ✨ Quaternion 新构造时 w 默认 1.0（identity rotation），Quaternion(0.5, 0, 0) 直接得到合法旋转。

  • ✨ Pose / PoseStamped / PoseWithCovariance / PoseWithCovarianceStamped 新构造时若不显式给 orientation，自动取 identity Quaternion。

兼容性

  • 所有空构造（Pose() / Quaternion() / PoseStamped() 等）行为完全保持，仍返回 ROS C++ 消息默认值（Quaternion → identity w=1.0；Pose → identity-orientation；Vector3/Twist/Header/Time/State/MsgTravelParams/BatteryState/FileInfo/MapFileInfo → 各字段全 0/false/空字符串/空列表）。

  • def_readwrite 链式赋值 pose.position.x = 1.0 不变。

  • MsgTravelParams 新构造的枚举字段（speed_mode/gait/path_following_mode/direction_constraint）默认 0（UNKNOWN），与现状空构造完全一致；调用方仍需显式赋有效值。

文档

  • 📚 data.rst 16 个数据类型章节示例补充新构造姿势；新增 PoseWithCovariance/TwistWithCovariance/PoseWithCovarianceStamped 章节。

版本 1.0.3 (2026-03-23)

新功能

  • ✨ 新增逻辑流控制接口（任务引擎运行时注入）：

    • run_script(source, parameters) — 串行执行子脚本

    • run_parallel_script(source, parameters) — 后台线程异步执行子脚本，返回 ThreadHandle

    • pause_application() — 在当前位置暂停任务，等待外部 resume 信号

    • resume_application() — 写入 resume 信号，从后台唤醒暂停中的主脚本

    • stop_application() — 取消所有后台线程并立即终止任务

  • ✨ 新增 ThreadHandle 类（join / is_done / cancel）

  • ✨ 新增 ScriptError 异常类（包装子脚本原始异常）

改进

  • 🔧 sleep / pause_application / resume_application / stop_application 加入步骤白名单，确保按脚本书写顺序执行

  • 📚 新增逻辑流控制文档页面（api/flow_control.rst）

  • 📝 lowlevel_skills/__init__.pyi 加入流控制函数类型存根，IDE 可通过 TYPE_CHECKING 获得提示

版本 1.0.2 (2026-02-27)

新功能

  • ✨ 添加运动控制模块 (motion) - 包含站立、躺下、步态控制、充电管理、电池状态查询等功能

  • ✨ 添加 stand_up - 控制机器人站立

  • ✨ 添加 lie_down - 控制机器人躺下

  • ✨ 添加 get_robot_state - 获取机器人当前状态

  • ✨ 添加 adjust_body_height - 调节机器人身体高度

  • ✨ 添加 set_gait / get_gait - 步态类型设置与查询

  • ✨ 添加 set_control_mode / get_control_mode - 控制模式切换

  • ✨ 添加 go_to_dock / leave_dock - 充电座管理

  • ✨ 添加 get_dock_state - 获取充电座状态

  • ✨ 添加 get_battery_state - 获取完整电池信息

  • ✨ 添加 is_charge - 检查充电状态

  • ✨ 添加 send_cmd_vel - 全向运动速度控制

改进

  • 🔧 移除文档示例中不必要的 from ... import 语句（因 task_template.py 已预导入）

  • 📝 完善运动控制接口 docstring（Sphinx 格式）

  • 📚 新增运动模块文档并加入 lowlevel_skills 目录

版本 1.0.1 (2026-02-09)

新文档

  • 📝 完善语音接口 docstring（Sphinx 格式）

  • 📝 新增语音模块文档并加入 lowlevel_skills 目录

  • 📚 更新文档构建指南示例与目录说明

版本 1.0.0 (2025-01-20)

新功能

  • ✨ 添加 navigation_via_poses - 多点导航功能

  • ✨ add_location 支持虚拟打点模式

  • 📝 完整的 Sphinx 文档

改进

  • 🔧 优化导航参数默认值

  • 📚 所有函数添加详细 docstring

  • 🎨 改进 Python 绑定的文档

版本 0.9.0 (2025-01-15)

初始版本

  • 基础导航功能

  • 定位管理

  • 地图管理

  • 云台控制