更新日志

版本 1.0.15 (2026-06-25)

新功能

  • ✨ 新增 delete_map —— 删除指定名称的已保存地图（移除 /root/data/daystar_api/maps/<map_name>/ 整个目录），走 /sdk/nav/delete_map

  • ✨ 新增 delete_image —— 删除指定名称的已抓拍云台照片（移除 /root/data/daystar_api/images/ 下文件），走 /sdk/cam/delete_image

  • ✨ 新增批量删除对外接口 delete_maps / delete_images / delete_locations``（lowlevel + ``/sdk/nav/delete_maps / /sdk/cam/delete_images / /sdk/nav/delete_locations）与任务批量删除 /sdk/delete_tasks``（引擎节点）—— 接受名称列表（单元素=指定，多元素=批量），``delete_all=true 时服务端枚举该域全部条目快速删除，返回成功/失败名称清单。同名 4 个 MCP 工具改为直调批量服务（不再 MCP 层循环）

  • ✨ delete_maps(delete_all=True) 默认保留当前正在使用的地图不删（skipped_names 返回，并打 WARN 日志提醒）

  • ✨ 新增 MCP 批量删除工具 delete_maps / delete_images / delete_locations / delete_tasks``（均支持 ``delete_all）；原 delete_location / delete_task 单删工具保持不变（前向兼容）

  • 📚 新增 DeleteMapResponse / DeleteImageResponse / DeleteMapsResponse / DeleteImagesResponse / DeleteLocationsResponse 响应类型

版本 1.0.14 (2026-06-22)

新功能

  • ✨ 新增 switch_llm_group —— 切换 agent 的 LLM 模型组（cloud/local/hybrid），转发到 /sdk/agent/switch_llm_group

  • ✨ 新增 enable_voice_service / enable_continuous_dialog / enable_sound_orientation / enable_safety_mode —— agent 四运行态开关（F1-F4），转发到 /sdk/agent/enable_*

  • ✨ 新增 set_back_light —— 切换后尾灯样式（后灯板 LED，仅 MX DVT 机型），走 /nav/sdk_action 的 command_name="back_light_style"，放行 54 标准闪 / 55 快闪 / 56 慢呼吸 / 57 标准呼吸（其余电量/充电/转向/急停等为系统默认行为，不开放）

  • 📚 新增 SwitchLlmGroupResponse / AgentSwitchResponse 响应类型文档与 system.rst「Agent 控制面」小节

改进

  • 🔧 Agent 控制面改为标准分层（C++ Agent API → /sdk/agent/* 服务节点 → agent 对内 /agent/*），sdk 前缀的对外接口统一由 daystar_api 封装；新增 latched 运行态话题 /sdk/agent/runtime_state

  • 🔧 set_expression 表情序号集扩展至 4/5/6/7/8/13/14/19/20/21/22/23（新增 7 跟随 / 19 躺下 / 22 皱眉 / 23 害怕），并修正此前 19/21 序号错位（更正为 19=躺下、21=不屑）

  • 📝 新增 agent.cpp/hpp 绑定 docstring 与类型存根

  • 📝 新增 set_back_light 类型存根 docstring 与 motion.rst「后尾灯样式」小节

版本 1.0.13 (2026-06-18)

新功能

  • ✨ 新增 get_current_localization_mode —— 查询当前定位模式（返回 LocalizationMode 枚举：MAP/SLAM/REFLECTOR/UNKNOWN_LOC_MODE，来源 /nav/current_localization_mode 话题，5 秒时效）

  • 📚 新增 GetCurrentLocalizationModeResponse / LocalizationMode 响应类型与枚举文档

改进

  • 🔧 set_localization 新增 candidate_poses 参数 —— 提供多候选初始位姿时优先走自动选点重定位（/nav/autoselect_initialpose），忽略 auto_relocation/location_name

  • 🔧 start_mapping 新增 enable_loop_closure 参数 —— 是否开启闭环检测（默认开启；关闭退化为纯里程计，适合长时运行）

  • 🔧 GetRobotStatusResponse 新增 localization_mode 聚合字段（当前定位模式）

  • 🔧 robot_status 的 loc_state / lidar_state 改读 Navigation 无日志快照（修复此前恒为 UNKNOWN 的缺陷）；数据超时（>5 秒）时返回 UNKNOWN``（此前会保留最后一次旧值），消费方（如定位前置检查 ``loc_state == NORMAL）需注意此语义变化

  • 📝 同步更新 localization.rst / data.rst 与类型存根 docstring

版本 1.0.12 (2026-06-01)

新功能

  • ✨ 新增 get_lidar_state —— 查询雷达整机健康状态（返回 LidarState 枚举：UNKNOWN/NORMAL/HIGHFREQ/LOWFREQ/DISCONNECT）

  • 📚 新增 GetLidarStateResponse / LidarState 响应类型与枚举文档

  • 🔧 GetRobotStatusResponse 新增 lidar_state 聚合字段（雷达健康状态）

  • 📝 同步更新 motion.rst / data.rst 与任务脚本指南

版本 1.0.11 (2026-06-01)

新功能

  • ✨ 新增 get_driver_state —— 查询驱动器使能状态（返回 DriverEnableState 枚举）

  • ✨ 新增 get_emergency_state —— 查询软急停状态

  • ✨ 新增 get_guardian_state —— 查询停障开关状态

  • ✨ 新增 get_robot_status_full —— 一次性获取机器人聚合总状态（姿态/控制模式/步态/充电桩/电池/充电/定位/位姿/使能/急停/停障）

  • ✨ 新增 driver_enable —— 上/下使能驱动器

  • ✨ 新增 emergency_stop —— 触发软件急停

  • ✨ 新增 resume_estop —— 恢复软件急停

  • ✨ 新增 set_guardian_switch —— 开/关停障功能

  • ✨ 新增 demo_control —— 触发演示动作（摇头 / 摆尾 / 打招呼）

  • 📚 新增 GetDriverStateResponse / GetEmergencyStateResponse / GetGuardianStateResponse / GetRobotStatusResponse 响应类型文档

  • 📚 新增 DriverEnableState 枚举文档

  • 📝 同步更新 motion.rst / data.rst 与任务脚本指南

版本 1.0.10 (2026-05-31)

新功能

  • ✨ 新增 request_mode —— 切换机械臂模式（IDLE / MOTION / SERVO，SERVO 再分 CARTESIAN / JOINT），替代旧的 set_state。

  • ✨ 新增 raise_fault / clear_fault —— 主动进入 FAULT（软急停 / 异常上报） 与清除故障恢复 IDLE。

  • ✨ 新增 /sdk/umi/joint_command 话题转发（SERVO/JOINT 关节伺服流， umi_msgs/JointCommand），与既有 /sdk/umi/servo_jog 对称。

变更

  • 🔧 移除 set_state / switch_controller / list_controllers / start_guidance / stop_guidance：set_state 由 request_mode 取代； 控制器切换改由 umi_planning 在 request_mode 内部仲裁，不再对外暴露裸切； guidance 由 request_mode + servo 取代。

  • 📝 同步更新 manipulation.rst / data.rst 与 _lowlevel_skills.pyi 存根。

版本 1.0.9 (2026-05-25)

改进

  • 📝 修正 plan_trajectory 的 tolerance_orientation / tolerance_joint_position 单位：由”弧度”更正为”角度（单位：度）”，与 joint_positions / rpy 等其余 Umi 角度量统一为度（tolerance_position 仍为米）。

  • 🔧 上述两个容差在 umi_planning 服务端新增度→弧度转换后再下发 MoveIt；默认值由 0.001 改为 0.0，表示”用服务端默认”（约 0.057°，即 0.001 rad），省略时 规划行为与此前完全一致。

版本 1.0.8 (2026-05-18)

新功能

  • ✨ 新增 25 个机械臂/双臂 manipulation 接口：move_joint / move_tool / move_to_pose / stop_motion / compute_fk / compute_ik / plan_trajectory / execute_path / save_pose / record_pose / get_pose / list_poses / delete_pose / start_recording / stop_recording / list_trajectories / get_trajectory / delete_trajectory / play_trajectory / read_tcp_pose / read_tcp_rpy / get_current_joints / set_state / switch_controller / list_controllers。覆盖关节/笛卡尔运动、运动学 解算、轨迹规划与执行、位姿库与轨迹库管理、轨迹录制回放、控制器切换等。

  • ✨ 新增 ALL_JOINTS 常量（等价 []），作为 move_joint 的 joint_names 默认值，不指定即作用于全部关节。

改进

  • 📝 将 manipulation_py.cpp 中 25 个接口的 pbdoc 由一句话升级为完整 Google 风格（功能说明 + Args + Returns + Examples），并补充 CartesianTarget / JointTrajectory / JointTrajectoryPoint 类型 存根 docstring；重建后自动再生 _lowlevel_skills.pyi。

  • 🔧 5 个可阻塞接口（move_joint / move_tool / move_to_pose / execute_path / play_trajectory）在 docstring 中明确 block 同步/ 异步语义与 timeout 等待语义，以及与 stop_motion 的协作取消关系。

  • 📚 新增 机械臂操作 文档页，并挂接到 lowlevel_skills 模块 的模块概览与 toctree。

  • 📝 数据结构 新增 25 个 XxxResponse 接口层响应、25 个 UmiXxxResponse ROS 层响应，以及 CartesianTarget / JointTrajectory / JointTrajectoryPoint 消息类型说明。

  • 📝 修正关节角（target_positions / joint_positions / JointTrajectoryPoint.positions）与 CartesianTarget.rpy 的单位 说明：由”弧度”更正为”角度（单位：度）”，对齐 Umi 对外接口实际约定 （x / y / z 仍为米）。

  • 🔧 move_joint 的 joint_names 改为可选（默认 ALL_JOINTS）， 仅传 target_positions 即可作用于全部关节，不再因缺省报 TypeError。

  • 🔧 修复通用任务多行异常消息（如 pybind11 incompatible function arguments 重载报错）仅首行带用户错误前缀的问题，现每物理行均带 [DAYSTAR_USER_ERROR] 前缀，避免下游按前缀转发时签名/Invoked with 行被截断丢弃。

版本 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)

初始版本

  • 基础导航功能

  • 定位管理

  • 地图管理

  • 云台控制