客户错误处理

本模块提供自定义日志记录、错误和警告处理功能，允许用户记录消息、清理日志文件以及向UI发送错误和警告信号。

日志管理

记录日志消息

log_message(message, logger='default', include_timestamp=False)

Log a message to a user log file.

Log files are automatically named with timestamp: {logger}_{YYYYMMDD_HHMMSS}.log

Parameters:

  • message (str) – The message to log

  • logger (str) – Logger name (used as filename base), defaults to “default”

  • include_timestamp (bool) – Whether to include timestamp in log content, defaults to False

Returns:

True if logging succeeded

Return type:

bool

Examples:

log_message("Task started")
log_message("Processing item 1", "process_log", True)

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：以 spdlog 写入 /root/data/daystar_api/user_logs/ 下的 {logger}_{启动时间戳}.log 滚动日志文件，并同步向 stdout 打印 [DAYSTAR_USER] 前缀行供任务管理器捕获）。

清理日志文件

clear_log(logger_name='', log_dir='/root/data/daystar_api/user_logs/')

Clear user log files.

This function works independently and doesn’t require initialization.

Parameters:

  • logger_name (str) – Optional logger name. If provided, only delete logs for this logger. If empty (default), delete all log files.

  • log_dir (str) – Optional log directory. Defaults to /root/data/daystar_api/user_logs/

Returns:

Number of log files deleted

Return type:

int

Examples:

# Delete all log files
deleted = clear_log()
print(f"Deleted {deleted} log files")

# Delete only 'my_task' logs
deleted = clear_log("my_task")
print(f"Deleted {deleted} my_task log files")

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：直接遍历删除日志目录下匹配 {logger_name}_*.log 的文件，logger_name 为空时删除全部 .log 文件； 无需初始化即可调用）。

错误和警告处理

触发错误信号

raise_error(message, name='', code=0)

上报一个结构化错误信号到 /sdk/task/raise_error（供 UI 显示）。

注意：本底层函数仅推送 UI 通知并返回 response，不抛异常、不改变任务状态。 若需”上报并使任务失败退出”，请使用 Python 层一体化入口 daystar_api.errors.raise_error(message, name=..., code=..., fatal=True)。

Parameters:

  • message (str) – 错误消息

  • name (str) – 错误名（如 “NAV_ESTOP_RESUME_FAILED”），默认空

  • code (int) – 错误码（系统保留 1-99999，客户自定义 >=100000），默认 0

Returns:

响应

  • state: State 对象（code/describe）

  • response.success: bool，True 表示已被服务端接收

  • response.message: str，服务端回执

Return type:

RaiseErrorResponse

Examples:

resp = raise_error("传感器连接失败", name="SENSOR_CONN_FAILED", code=30001)
if resp.response.success:
    print("已上报")

Note

  • 服务：/sdk/task/raise_error（api_msgs/srv/RaiseError）

  • 任务状态由脚本退出码决定，本函数不触发失败

底层 ROS2 接口

  • 类型: Service api_msgs/srv/RaiseError

  • 名称: /sdk/task/raise_error

  • 参数映射:

封装参数

原生字段（Request）

message

message

name

error_name

code

error_code

（自动填充）

timestamp （当前时间）、task_id （当前任务 ID）

等待响应超时为 C++ 层固定 1 秒（客户端等待时长，不下发，Python 侧未暴露）。

触发警告信号

raise_warn(message, name='', code=0)

上报一个结构化警告信号到 /sdk/task/raise_warn（供 UI 显示）。

Parameters:

  • message (str) – 警告消息

  • name (str) – 警告名，默认空

  • code (int) – 警告码，默认 0

Returns:

响应

  • state: State 对象（code/describe）

  • response.success: bool，True 表示已被服务端接收

  • response.message: str，服务端回执

Return type:

RaiseWarnResponse

Examples:

resp = raise_warn("电量偏低", name="BATTERY_LOW", code=90001)
if resp.response.success:
    print("已上报")

Note

  • 服务：/sdk/task/raise_warn（api_msgs/srv/RaiseWarn）

  • 警告不影响任务状态

底层 ROS2 接口

  • 类型: Service api_msgs/srv/RaiseWarn

  • 名称: /sdk/task/raise_warn

  • 参数映射:

封装参数

原生字段（Request）

message

message

name

error_name

code

error_code

（自动填充）

timestamp （当前时间）、task_id （当前任务 ID）

等待响应超时为 C++ 层固定 1 秒（客户端等待时长，不下发，Python 侧未暴露）。