系统管理

系统初始化、就绪检查和关闭功能。

系统初始化

获取 API 实例

get_api_instance(task='terminal', namespace='', parameters='')

获取（并在首次调用时初始化）DayStarAPI 单例。

首次调用完成全部初始化：初始化 ROS 上下文（若尚未初始化）→ 创建生命周期节点 api_<task>_node（挂在 namespace 下）→ 启动后台 MultiThreadedExecutor spin 线程 → 初始化 Navigation / PTZ / Motion / Speech / Manipulation / UserLogging 各子模块（各自创建 service client 与 topic 订阅）。

Parameters:

• task (str) – 任务标识，用于节点命名 api_<task>_node 与日志标签（默认: “terminal”）

• namespace (str) – 节点的 ROS 命名空间（默认: “”）

• parameters (str) – 传给 rclcpp::init 的附加 ROS 命令行参数，按空白分词 （如 "--ros-args -p use_sim_time:=true"；默认: “” 即无附加参数）

Returns:

单例引用。

Return type:

DayStarAPI

Examples:

# 常规初始化
api = get_api_instance(task='demo')

# 带 ROS 参数初始化
api = get_api_instance(task='demo', parameters='--ros-args -p use_sim_time:=true')

Note

• 单例语义：仅**首次**调用的参数生效，之后再次调用返回同一实例并忽略新参数

• 若进程内 ROS 上下文已初始化，将直接复用现有上下文（parameters 不再生效）

底层 ROS2 接口

• 类型: ROS2 节点初始化（无单一服务调用）

• 机制: 首次调用时初始化 rclcpp 上下文（如尚未初始化），创建生命周期节点 api_<task>_node 并启动 MultiThreadedExecutor 后台 spin 线程；随后初始化 Navigation / PTZ / UserLogging / Speech / Motion / Manipulation 六个子模块， 各自创建所属域的 service client / topic 订阅 / action client（数量较多，仅列 主要前缀：/sdk/nav/*、/nav/*、/cam/PTZ_CAM/*、/sdk/cam/*、 /sdk/task/raise_warn、/sdk/task/raise_error 及语音、运动、机械臂域接口）

• 参数映射:

封装参数	用途
task	组成节点名 api_<task>_node，并作为各服务请求的 task_id 字段
namespace	节点命名空间
parameters	空格分隔的附加命令行参数，透传给 rclcpp::init （不下发到任何服务）

获取 Speech 实例

get_speech_api_instance()

Get the singleton Speech API instance.

Returns the same process-wide Speech singleton as Speech.get_instance(). Call get_api_instance() first so the Speech submodule (its service clients and topic subscriptions) is initialized.

Returns:

The singleton Speech API instance (returned by reference).

Return type:

Speech

Examples:

api = get_api_instance(task='demo')
speech = get_speech_api_instance()
speech.enable_tts(True)
speech.generate_audio("Hello")

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：按引用返回进程内 Speech 单例，与 Speech.get_instance() 为同一实例；Speech 模块的 /speech/* service client 与 topic 订阅在 get_api_instance() 初始化时创建）。

系统就绪检查

daystar_ready(timeout=30)

检查 Daystar API 是否就绪。

当前实现仅校验 ROS 上下文存活（rclcpp::ok()，等待 100ms 后返回成功）； 服务级就绪状态（FSM）检查暂未启用。

Parameters:

timeout (int) – 等待就绪的超时秒数（默认: 30）

Returns:

就绪状态

• code: StateCode（0=success 就绪；timeout=等待超时；fail=内部异常）

• describe: 结果描述

Return type:

State

Examples:

api = get_api_instance(task='demo')
if daystar_ready(timeout=30).code == 0:
    print("系统就绪")

底层 ROS2 接口

• 类型: 本地状态检查（不发起任何 ROS2 服务调用）

• 机制: 仅检查本进程 rclcpp 上下文是否存活（rclcpp::ok()）：存活则等待 100ms 后返回 success；不存活则在截止时间到达后返回 timeout 状态

• 参数映射:

封装参数	用途
timeout	客户端等待时长（秒），不下发

系统关闭

daystar_shutdown(exit=True)

关闭 Daystar API：停止后台 executor 线程并关闭 ROS 上下文。

幂等操作——重复调用只生效一次（后续调用直接跳过）。执行顺序：取消 executor → 等待 spin 线程退出 → rclcpp::shutdown()。

Parameters:

exit (bool) – 仅影响关闭日志的措辞，**不会**调用 exit()——进程退出码 始终由调用方（Python 脚本）控制（默认: True）

Return type:

None

Returns:

None

Examples:

api = get_api_instance(task='demo')
# ... 业务逻辑 ...
daystar_shutdown()

Note

• 关闭后本进程内无法重新初始化 API（单例已绑定已关闭的上下文）， 如需重新使用需重启进程

底层 ROS2 接口

本接口不经 ROS2 服务通道（本地关闭流程：取消 executor、join 后台 spin 线程， 最后调用 rclcpp::shutdown() 关闭 ROS2 上下文；exit 参数仅影响日志提示， 进程退出码由调用方控制）。

Agent 控制面

转发到 daystar_agent 进程的控制面接口：本 Python 封装经 C++ Agent API 直连 agent 对内服务 /agent/*；另有 daystar_service_node 暴露的对外 ROS 服务 /sdk/agent/* 供外部 ROS 客户端使用（两条路径最终都落到 /agent/*）。 属外部控制面操作，不供机器人自身任务规划。

切换 LLM 模型组

switch_llm_group(group, timeout=8)

切换 agent 的 LLM 模型组（一键 local / 云端 / 混合）。

Parameters:

• group (str) – 目标模型组名。常用取值：cloud（全云端）/ local（全本地）/ hybrid（本地分类+云端规划）。

• timeout (int) – 超时秒数（默认 8）；<=0 表示无限等待直到服务返回。

Returns:

切换结果

• success: 是否成功

• message: 结果说明

• active_group: 切换后当前激活组（失败时为切换前的组）

• available_groups: 所有可用模型组名

Return type:

SwitchLlmGroupResponse

Examples:

result = switch_llm_group("local")
if result.success:
    print("已切换到", result.active_group)

Note

• 转发到 daystar_agent 对内服务 /agent/switch_llm_group。

• 属外部控制面操作；agent 进程持有 LLMManager 状态，由其托管。

底层 ROS2 接口

• 类型: Service api_msgs/srv/SwitchLlmGroup

• 名称: /agent/switch_llm_group （daystar_agent 对内服务，C++ 层直连）

• 参数映射:

封装参数	原生字段（Request）
group	group
timeout	客户端等待时长（秒），不下发；<=0 表示无限等待

语音服务开关

enable_voice_service(enabled, timeout=8)

开关智能助手（agent 总开关，含本体语音服务 F1）。关闭后 agent 先停止正在 执行的任务，再停止决策与全部后台任务（语音引擎、视觉刷新、状态轮询、 LLM 连接），仅保留停止类控制（停止任务/暂停/取消）；重开后恢复。

Parameters:

• enabled (bool) – True 开启，False 关闭。

• timeout (int) – 超时秒数（默认 8）；<=0 表示无限等待直到服务返回。

Returns:

success / message

Return type:

AgentSwitchResponse

Examples:

enable_voice_service(False)   # 关闭智能助手（纯遥控/展示场景）
enable_voice_service(True)    # 重新开启

Note

• 转发到 daystar_agent 对内服务 /agent/enable_voice_service。

• 关闭期间本服务与其余开关服务仍可用（重开通道不受总开关影响）。

底层 ROS2 接口

• 类型: Service std_srvs/srv/SetBool

• 名称: /agent/enable_voice_service （daystar_agent 对内服务，C++ 层直连）

• 参数映射:

封装参数	原生字段（Request）
enabled	data
timeout	客户端等待时长（秒），不下发；<=0 表示无限等待

连续对话开关

enable_continuous_dialog(enabled, timeout=8)

开关连续对话（F2）。开启时一句播报后保留免唤醒窗口，可多轮 follow-up。

Parameters:

• enabled (bool) – True 开启，False 关闭。

• timeout (int) – 超时秒数（默认 8）；<=0 表示无限等待直到服务返回。

Returns:

success / message

Return type:

AgentSwitchResponse

Examples:

enable_continuous_dialog(True)

Note

• 转发到 daystar_agent 对内服务 /agent/enable_continuous_dialog。

底层 ROS2 接口

• 类型: Service std_srvs/srv/SetBool

• 名称: /agent/enable_continuous_dialog （daystar_agent 对内服务，C++ 层直连）

• 参数映射:

封装参数	原生字段（Request）
enabled	data
timeout	客户端等待时长（秒），不下发；<=0 表示无限等待

声源朝向开关

enable_sound_orientation(enabled, timeout=8)

开关音源朝向反馈（F3）。开启后唤醒时朝声源方向反馈。

Parameters:

• enabled (bool) – True 开启，False 关闭。

• timeout (int) – 超时秒数（默认 8）；<=0 表示无限等待直到服务返回。

Returns:

success / message

Return type:

AgentSwitchResponse

Examples:

enable_sound_orientation(True)

Note

• 转发到 daystar_agent 对内服务 /agent/enable_sound_orientation。

底层 ROS2 接口

• 类型: Service std_srvs/srv/SetBool

• 名称: /agent/enable_sound_orientation （daystar_agent 对内服务，C++ 层直连）

• 参数映射:

封装参数	原生字段（Request）
enabled	data
timeout	客户端等待时长（秒），不下发；<=0 表示无限等待

安全模式开关

enable_safety_mode(enabled, timeout=8)

开关安全模式（F4）。开启后受 safety_mode 前置约束的动作会被拦截。

Parameters:

• enabled (bool) – True 开启，False 关闭。

• timeout (int) – 超时秒数（默认 8）；<=0 表示无限等待直到服务返回。

Returns:

success / message

Return type:

AgentSwitchResponse

Examples:

enable_safety_mode(True)

Note

• 转发到 daystar_agent 对内服务 /agent/enable_safety_mode。

底层 ROS2 接口

• 类型: Service std_srvs/srv/SetBool

• 名称: /agent/enable_safety_mode （daystar_agent 对内服务，C++ 层直连）

• 参数映射:

封装参数	原生字段（Request）
enabled	data
timeout	客户端等待时长（秒），不下发；<=0 表示无限等待

相关数据类型

• _lowlevel_skills.SwitchLlmGroupResponse

• _lowlevel_skills.AgentSwitchResponse