数据结构

本节描述 Daystar API 中使用的数据结构和消息类型。这些数据结构通过 pybind11 从 C++ 绑定到 Python，用于与机器人系统进行通信。

数据结构分为以下几类：

• 基础消息类型: ROS 标准消息和几何消息，用于构建更复杂的数据结构

• 自定义消息类型: Daystar 特有的消息类型，如状态码、导航参数等

• 接口层响应: API 函数返回的接口层响应对象

• ROS层服务响应: 底层 ROS 服务的响应结构

• 事件类型: 异步事件回调使用的数据结构

基础消息类型

ROS 标准消息类型 (std_msgs)

Header

class Header

class Header(stamp: Time = {'nanosec': 0, 'sec': 0}, frame_id: str = '')

Bases: object

property frame_id: str

frame id

property stamp: Time

timestamp

时间戳和坐标系信息头。

Python 类: Header

字段:

• stamp (Time): 时间戳

• frame_id (str): 坐标系 ID

示例:

from daystar_api.lowlevel_skills import Header, Time

# 方式 1：空构造 + setter
header = Header()
header.frame_id = "map"

# 方式 2：kwargs（frame_id 默认空字符串，stamp 默认全 0）
header = Header(frame_id="map")

# 方式 3：位置参数
header = Header(Time(sec=0, nanosec=0), "map")
print(header)

Time

class Time

class Time(sec: int = 0, nanosec: int = 0)

Bases: object

property nanosec: int

property sec: int

ROS 时间戳。

Python 类: Time

字段:

• sec (int): 秒

• nanosec (int): 纳秒（0–999999999）

示例:

from daystar_api.lowlevel_skills import Time

# 方式 1：空构造 + setter
t = Time()
t.sec = 42
t.nanosec = 500000000

# 方式 2：kwargs / 位置参数
t = Time(sec=42, nanosec=500000000)
t = Time(42, 500000000)

ROS 几何消息类型 (geometry_msgs)

Point

class Point

class Point(x: float = 0.0, y: float = 0.0, z: float = 0.0)

Bases: object

property x: float

property y: float

property z: float

三维空间中的点。

Python 类: Point

字段:

• x (float): X 坐标

• y (float): Y 坐标

• z (float): Z 坐标

示例:

from daystar_api.lowlevel_skills import Point

# 方式 1：空构造 + setter
point = Point()
point.x = 1.0
point.y = 2.0
point.z = 0.0

# 方式 2：位置参数
point = Point(1.0, 2.0, 0.0)

# 方式 3：kwargs（可省略部分字段，缺省为 0.0）
point = Point(x=1.0, y=2.0)

Quaternion

class Quaternion

class Quaternion(x: float = 0.0, y: float = 0.0, z: float = 0.0, w: float = 1.0)

Bases: object

property w: float

property x: float

property y: float

property z: float

四元数表示的方向。

Python 类: Quaternion

字段:

• x (float): X 分量

• y (float): Y 分量

• z (float): Z 分量

• w (float): W 分量（标量部分）

示例:

from daystar_api.lowlevel_skills import Quaternion

# 方式 1：空构造（默认 identity，w=1.0），setter 仍可用
quat = Quaternion()
quat.x = 0.0
quat.y = 0.0
quat.z = 0.0
quat.w = 1.0  # 无旋转（也是空构造的默认值）

# 方式 2：位置参数（w 缺省取 1.0 = identity rotation）
quat = Quaternion(0.0, 0.0, 0.0)        # 等价 identity
quat = Quaternion(0.0, 0.0, 0.0, 1.0)   # 显式 identity

# 方式 3：kwargs（w 缺省取 1.0 = identity rotation）
quat = Quaternion(x=0.5)   # (0.5, 0, 0, 1.0)

Pose

class Pose

class Pose(position: Point = {'x': 0.0, 'y': 0.0, 'z': 0.0}, orientation: Quaternion = {'w': 1.0, 'x': 0.0, 'y': 0.0, 'z': 0.0})

Bases: object

property orientation: Quaternion

property position: Point

位置和方向的组合。

Python 类: Pose

字段:

• position (Point): 位置

• orientation (Quaternion): 方向

示例:

from daystar_api.lowlevel_skills import Pose, Point, Quaternion

# 方式 1：空构造 + setter（orientation 默认 identity，w=1.0 已自动）
pose = Pose()
pose.position.x = 1.0
pose.position.y = 2.0
pose.position.z = 0.0
pose.orientation.w = 1.0  # 显式 setter 仍可用，但默认值已经是 1.0

# 方式 2：kwargs / 位置参数（orientation 缺省取 identity，无需手设 w=1）
pose = Pose(position=Point(1.0, 2.0, 0.0))
pose = Pose(Point(1.0, 2.0, 0.0))   # 等价的位置参数写法

# 方式 3：完整参数
pose = Pose(Point(1.0, 2.0, 0.0), Quaternion(0.0, 0.0, 0.0, 1.0))

PoseStamped

class PoseStamped

class PoseStamped(header: Header = {'frame_id': '', 'stamp': {'nanosec': 0, 'sec': 0}}, pose: Pose = {'orientation': {'w': 1.0, 'x': 0.0, 'y': 0.0, 'z': 0.0}, 'position': {'x': 0.0, 'y': 0.0, 'z': 0.0}})

Bases: object

property header: Header

property pose: Pose

带时间戳和坐标系的位姿。

Python 类: PoseStamped

字段:

• header (Header): 时间戳和坐标系信息

• pose (Pose): 位姿

示例:

from daystar_api.lowlevel_skills import PoseStamped, Pose, Point, Header

# 方式 1：空构造 + setter（内嵌 pose 已是 identity-orientation）
pose_stamped = PoseStamped()
pose_stamped.header.frame_id = "map"
pose_stamped.pose.position.x = 1.0
pose_stamped.pose.position.y = 2.0
pose_stamped.pose.orientation.w = 1.0  # 默认已是 1.0

# 方式 2：kwargs（内嵌 pose 默认 identity-orientation，无需手设 w=1）
pose_stamped = PoseStamped(
    header=Header(frame_id="map"),
    pose=Pose(Point(1.0, 2.0, 0.0)),
)

# 方式 3：位置参数
pose_stamped = PoseStamped(Header(frame_id="map"), Pose(Point(1.0, 2.0, 0.0)))

Vector3

class Vector3

class Vector3(x: float = 0.0, y: float = 0.0, z: float = 0.0)

Bases: object

property x: float

property y: float

property z: float

三维向量。

Python 类: Vector3

字段:

• x (float): X 分量

• y (float): Y 分量

• z (float): Z 分量

示例:

from daystar_api.lowlevel_skills import Vector3

# 方式 1：空构造 + setter
vec = Vector3()
vec.x = 1.0
vec.y = 0.0
vec.z = 0.0

# 方式 2：位置参数
vec = Vector3(1.0, 0.0, 0.0)

# 方式 3：kwargs（可省略部分字段，缺省为 0.0）
vec = Vector3(x=1.0)

Twist

class Twist

class Twist(linear: Vector3 = {'x': 0.0, 'y': 0.0, 'z': 0.0}, angular: Vector3 = {'x': 0.0, 'y': 0.0, 'z': 0.0})

Bases: object

property angular: Vector3

property linear: Vector3

线速度和角速度。

Python 类: Twist

字段:

• linear (Vector3): 线速度 (m/s)

• angular (Vector3): 角速度 (rad/s)

示例:

from daystar_api.lowlevel_skills import Twist, Vector3

# 方式 1：空构造 + setter（linear/angular 默认全 0）
twist = Twist()
twist.linear.x = 0.5  # 前进 0.5 m/s
twist.angular.z = 0.1  # 左转 0.1 rad/s

# 方式 2：kwargs（linear/angular 默认全 0 Vector3）
twist = Twist(linear=Vector3(0.5, 0.0, 0.0), angular=Vector3(z=0.1))

# 方式 3：位置参数
twist = Twist(Vector3(0.5, 0.0, 0.0), Vector3(0.0, 0.0, 0.1))

PoseWithCovariance

class PoseWithCovariance

class PoseWithCovariance(pose: Pose = {'orientation': {'w': 1.0, 'x': 0.0, 'y': 0.0, 'z': 0.0}, 'position': {'x': 0.0, 'y': 0.0, 'z': 0.0}}, covariance: list[float[36]] = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])

Bases: object

property covariance: list[float[36]]

property pose: Pose

带协方差的位姿。

Python 类: PoseWithCovariance

字段:

• pose (Pose): 位姿

• covariance (list[float]): 6×6 协方差矩阵（行优先 36 元素）

示例:

from daystar_api.lowlevel_skills import PoseWithCovariance, Pose, Point

# 方式 1：空构造
pwc = PoseWithCovariance()

# 方式 2：kwargs（pose 默认 identity-orientation，covariance 默认全 0）
pwc = PoseWithCovariance(pose=Pose(Point(1.0, 2.0, 0.0)))

# 方式 3：显式 covariance
cov = [0.0] * 36
cov[0] = 0.1   # x 方差
pwc = PoseWithCovariance(covariance=cov)

TwistWithCovariance

class TwistWithCovariance

class TwistWithCovariance(twist: Twist = {'angular': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'linear': {'x': 0.0, 'y': 0.0, 'z': 0.0}}, covariance: list[float[36]] = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])

Bases: object

property covariance: list[float[36]]

property twist: Twist

带协方差的速度。

字段:

• twist (Twist): 线速度 + 角速度

• covariance (list[float]): 6×6 协方差矩阵（36 元素）

示例:

from daystar_api.lowlevel_skills import TwistWithCovariance, Twist, Vector3

twc = TwistWithCovariance(twist=Twist(linear=Vector3(0.5, 0, 0)))

PoseWithCovarianceStamped

class PoseWithCovarianceStamped

class PoseWithCovarianceStamped(header: Header = {'frame_id': '', 'stamp': {'nanosec': 0, 'sec': 0}}, pose: PoseWithCovariance = {'covariance': [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], 'pose': {'orientation': {'w': 1.0, 'x': 0.0, 'y': 0.0, 'z': 0.0}, 'position': {'x': 0.0, 'y': 0.0, 'z': 0.0}}})

Bases: object

property header: Header

property pose: PoseWithCovariance

带时间戳和坐标系的协方差位姿（常用于定位发布）。

字段:

• header (Header): 时间戳和坐标系

• pose (PoseWithCovariance): 协方差位姿

示例:

from daystar_api.lowlevel_skills import PoseWithCovarianceStamped, Header

pwcs = PoseWithCovarianceStamped(header=Header(frame_id='map'))

自定义消息类型

Daystar 自定义消息类型

class State

class State(code: StateCode = ..., describe: str = '')

Bases: object

property cn: str

StateCode 对应的中文说明

property code: StateCode

state

property describe: str

description

State

通用状态码和描述。

Python 类: State

字段:

• code (int): 状态码

  • 0: SUCCESS - 成功

  • 1: FAIL - 失败

  • 1002: TIMEOUT - 超时

  • 1010: ACTION_REQUEST_TIMEOUT - 动作请求超时

  • 1015: ACTION_CANCELED - 动作被取消

• describe (str): 状态描述文本

示例:

from daystar_api.lowlevel_skills import State

# 读取响应中的 state（最常见用法）
response = navigation_to_location("kitchen")
if response.state.code == 0:
    print(f"成功: {response.state.describe}")
else:
    print(f"失败 (code={response.state.code}): {response.state.describe}")

# 主动构造 State（code 默认 0=SUCCESS，describe 默认空字符串）
ok = State(describe="ok")               # State(code=0, describe='ok')
fail = State(code=1, describe="failed") # 显式指定失败状态

MsgTravelParams

class MsgTravelParams

class MsgTravelParams(speed_mode: int = 0, distance_tolerance: float = 0.0, gait: int = 0, disable_body_obstacle_avoidance: bool = False, ignore_final_yaw: bool = False, path_following_mode: int = 0, direction_constraint: int = 0)

Bases: object

property direction_constraint: int

0=UNKNOWN, 1=NONE(无限制), 2=NO_TURN(禁止掉头), 3=FORWARD(正走), 4=REVERSE(倒走)

Type:

Direction constraint

property disable_body_obstacle_avoidance: bool

True to disable, False to enable

Type:

Disable body obstacle avoidance

property distance_tolerance: float

Distance tolerance in meters - threshold for maximum distance that defines when goal is reached

property gait: int

0=UNKNOWN, 1=GAIT_AUTO, 2=GAIT_TROT(对角小跑), 3=GAIT_CRAWL(爬行), 4=GAIT_AMBLE(缓行), 5=GAIT_SLOPE(斜坡), 6=GAIT_SENSE_STAIR(感知楼梯), 7=GAIT_NORMAL_STAIR(普通楼梯), 8=GAIT_STEEP_STAIR(陡峭楼梯), 9=GAIT_GRADUAL_STAIR(平缓楼梯), 10=GAIT_RL

Type:

Gait mode

property ignore_final_yaw: bool

True to ignore goal orientation, False to match goal orientation

Type:

Ignore final yaw

property path_following_mode: int

0=PATH_MODE_UNKNOWN, 1=PATH_MODE_DEFAULT(默认循线), 2=PATH_MODE_OFF(自由导航), 3=PATH_MODE_AUTO(自动选择), 4=PATH_MODE_STRICT(严格循线)

Type:

Path following mode

property speed_mode: int

0=UNKNOWN, 1=NORMAL, 2=LOW, 3=HIGH

Type:

Speed mode

导航行为参数。

Python 类: MsgTravelParams

字段:

• speed_mode (int): 速度模式

  • 0: UNKNOWN

  • 1: NORMAL - 正常速度

  • 2: LOW - 低速

  • 3: HIGH - 高速

• distance_tolerance (float): 到达目标的距离容差（米），默认 0.5

• gait (int): 步态模式（仅四足机器人）

  • 1: AUTO - 自动

  • 2: TROT - 小跑

  • 3: WALK - 行走

• disable_body_obstacle_avoidance (bool): 是否禁用机身避障，默认 False

• ignore_final_yaw (bool): 是否忽略终点朝向，默认 False

• path_following_mode (int): 路径跟随模式，默认 1

• direction_constraint (int): 方向约束，默认 1

示例:

from daystar_api.lowlevel_skills import MsgTravelParams

# 方式 1：空构造 + setter
params = MsgTravelParams()
params.speed_mode = 2  # 低速模式
params.distance_tolerance = 0.3  # 30cm 到达容差
params.ignore_final_yaw = True  # 不要求朝向

# 方式 2：kwargs（推荐）
params = MsgTravelParams(speed_mode=1, gait=1)

# 方式 3：完整位置参数
params = MsgTravelParams(2, 0.3, 1, False, True, 1, 1)

navigation_to_location("bedroom", travel_params=params)

Note

speed_mode / gait / path_following_mode / direction_constraint 的默认值为 0（UNKNOWN），即镜像 ROS msg 结构体默认。在实际导航调用前请显式 赋有效枚举值（如 speed_mode=1 表示 NORMAL）。

BatteryState

class BatteryState

class BatteryState(header: Header = {'frame_id': '', 'stamp': {'nanosec': 0, 'sec': 0}}, voltage: float = 0.0, temperature: float = 0.0, current: float = 0.0, charge: float = 0.0, capacity: float = 0.0, design_capacity: float = 0.0, percentage: float = 0.0, power_supply_status: int = 0, power_supply_health: int = 0, power_supply_technology: int = 0, present: bool = False, cell_voltage: list[float] = [], cell_temperature: list[float] = [], location: str = '', serial_number: str = '')

Bases: object

property capacity: float

Battery capacity in Amp-hours (Ah)

property cell_temperature: list[float]

Temperature of individual cells (degC)

property cell_voltage: list[float]

Voltage of individual cells (V)

property charge: float

Current charge in Amp-hours (Ah)

property current: float

Current in Amperes (A), negative indicates discharge

property design_capacity: float

Design capacity in Amp-hours (Ah)

property header: Header

Header timestamp

property location: str

Location/identifier of the battery

property percentage: float

Battery charge percentage (0.0-100.0)

property power_supply_health: int

Power supply health (UNKNOWN=0, GOOD=1, OVERHEAT=2, DEAD=3, OVERVOLTAGE=4, etc.)

property power_supply_status: int

Power supply status (UNKNOWN=0, CHARGING=1, DISCHARGING=2, NOT_CHARGING=3, FULL=4)

property power_supply_technology: int

Power supply technology (UNKNOWN=0, NIMH=1, LION=2, LIPO=3, LIFE=4, NICD=5, LIMN=6)

property present: bool

Battery present (true/false)

property serial_number: str

Serial number of the battery

property temperature: float

Temperature in Celsius (degC)

property voltage: float

Voltage in Volts (V)

电池状态信息（镜像 sensor_msgs/BatteryState）。

Python 类: BatteryState

字段:

• header (Header): 时间戳和坐标系

• voltage (float): 电压 (V)

• temperature (float): 温度 (degC)

• current (float): 电流 (A)，负值表示放电

• charge (float): 当前电量 (Ah)

• capacity (float): 容量 (Ah)

• design_capacity (float): 设计容量 (Ah)

• percentage (float): 电量百分比 (0.0–1.0)

• power_supply_status (int): 电源状态枚举

• power_supply_health (int): 电池健康度枚举

• power_supply_technology (int): 电池技术类型枚举

• present (bool): 电池是否存在

• cell_voltage (list[float]): 各电芯电压 (V)

• cell_temperature (list[float]): 各电芯温度 (degC)

• location (str): 电池位置标识

• serial_number (str): 序列号

示例:

from daystar_api.lowlevel_skills import BatteryState

# 方式 1：空构造 + setter
bs = BatteryState()
bs.percentage = 0.85

# 方式 2：kwargs（缺省字段全部取 ROS msg 结构体默认）
bs = BatteryState(voltage=24.0, percentage=0.85, present=True)

FileInfo

class FileInfo

class FileInfo(name: str = '', last_update_time: str = '', md5: str = '')

Bases: object

property last_update_time: str

00:03”

Type:

最后更新时间，格式 “2026-04-12 20

property md5: str

文件 MD5 校验值

property name: str

文件名（含后缀）

文件信息（用于地图等资源文件清单）。

Python 类: FileInfo

字段:

• name (str): 文件名（含后缀）

• last_update_time (str): 最后更新时间，格式 "2026-04-12 20:00:03"

• md5 (str): 文件 MD5 校验值

示例:

from daystar_api.lowlevel_skills import FileInfo

# 方式 1：空构造 + setter
info = FileInfo()
info.name = "office.pgm"

# 方式 2：kwargs / 位置参数
info = FileInfo(name="office.pgm", md5="d41d8cd98f00b204e9800998ecf8427e")
info = FileInfo("office.pgm", "2026-04-12 20:00:03", "d41d8cd98f00b204e9800998ecf8427e")

MapFileInfo

class MapFileInfo

class MapFileInfo(map_name: str = '', file_info: list[FileInfo] = [])

Bases: object

property file_info: list[FileInfo]

该地图下的文件列表

property map_name: str

地图名称（文件夹名）

地图文件信息（包含文件夹下的文件列表）。

Python 类: MapFileInfo

字段:

• map_name (str): 地图名称（文件夹名）

• file_info (list[FileInfo]): 该地图下的文件列表

示例:

from daystar_api.lowlevel_skills import MapFileInfo, FileInfo

# 方式 1：空构造 + setter
m = MapFileInfo()
m.map_name = "office_floor1"

# 方式 2：kwargs / 位置参数
m = MapFileInfo(map_name="office_floor1", file_info=[FileInfo(name="map.pgm")])
m = MapFileInfo("office_floor1", [FileInfo(name="map.pgm")])

接口层响应结构

所有 lowlevel_skills 函数返回的响应都遵循统一结构：

response = {
    "state": State,      # 包含 code 和 describe
    "response": {...}    # 具体的响应数据
}

导航相关响应

IntelligentNavigationResponse

class IntelligentNavigationResponse

Bases: object

has_future()

Return True when a non-blocking future is attached.

Return type:

bool

property future: NavigationFuture

NavigationFuture handle for non-blocking calls (block=False).

None when the call was blocking (block=True).

Examples:

resp = navigation_to_location("kitchen", block=False)
if resp.future:
    result = resp.future.get(timeout=60)

property response: IntelligentNavigation_Result

property state: State

导航操作的响应。

字段:

• state (State): 操作状态

• response (IntelligentNavigation_Result): 导航结果

  • result (int): 结果代码

  • error_code (int): 错误代码

  • error_msg (str): 错误消息

示例:

response = navigation_to_location("kitchen")
print(f"状态码: {response.state.code}")
print(f"结果: {response.response.result}")
if response.response.error_code != 0:
    print(f"错误: {response.response.error_msg}")

NavigationViaPosesResponse

class NavigationViaPosesResponse

Bases: object

property response: SrvAPINavigationViaPoses_Response

property state: State

多点导航的响应。

字段:

• (State): 操作状态

• response (SrvAPINavigationViaPoses_Response): 导航结果

  • success (bool): 是否成功

  • message (str): 状态消息

示例:

response = navigation_via_poses(poses_list)
if response.response.success:
    print("多点导航已启动")

定位相关响应

GetCurrentPoseServiceResponse

class GetCurrentPoseServiceResponse

Bases: object

property response: SrvAPIGetCurrentPose_Response

property state: State

获取当前位姿的响应。

字段:

• (State): 操作状态

• response (SrvAPIGetCurrentPose_Response): 位姿数据

示例:

response = get_current_pose()
if response.response.success:
    pose = response.response.location_pose
    print(f"位置: ({pose.position.x}, {pose.position.y})")

SetLocationResponse

class SetLocationResponse

Bases: object

property response: SrvAPISetLocalization_Response

Result of the response

property state: State

State of the response

字段:

• success (bool): 是否成功

• message (str): 状态消息

示例:

response = set_localization(pose)
if response.response.success:
    print("定位设置成功")

位置点管理响应

GetAvailableLocationResponse

class GetAvailableLocationResponse

Bases: object

property locations: list

Get locations as a list of dictionaries

property state: State

State of the response

获取可用位置点的响应。

字段:

• (State): 操作状态

• locations (list[Point]): 位置点列表，每个包含：

  • name (str): 位置点名称

  • pose (Pose): 位置点的位姿

示例:

response = get_available_location()
for loc in response.locations:
    print(f"{loc.name}: ({loc.pose.position.x}, {loc.pose.position.y})")

AddLocationServiceResponse

class AddLocationServiceResponse

Bases: object

property response: SrvAPIGetCurrentPose_Response

property state: State

增加点位的相应。

字段:

• (State): 操作状态

• response (SrvAPIGetCurrentPose_Response): 位置点列表，每个包含：

示例:

response = add_location("A")
if response.response.success:
     print("打点成功！")

DeleteLocationResponse

class DeleteLocationResponse

Bases: object

property result: bool

Result of the response

property state: State

State of the response

删除位置点的响应。

字段:

• (State): 操作状态

• result (bool): 是否删除成功

示例:

response = delete_location("old_point")
if response.result:
    print("位置点已删除")

相机和图像响应

CaptureImageResponse

class CaptureImageResponse

Bases: object

property response: SrvAPICaptureImage_Response

Service response

property state: State

State of the response

拍照操作的响应。

字段:

• (State): 操作状态

• response (SrvAPICaptureImage_Response ): 拍照结果

  • success (bool): 是否成功

  • message (str): 状态消息

示例:

response = capture_image("photo_001")
if response.response.success:
    print(f"拍照成功: {response.response.message}")

GetAvailableImagesResponse

class GetAvailableImagesResponse

Bases: object

property response: SrvAPIGetAvailableImages_Response

Service response

property state: State

State of the response

获取已拍摄图像列表的响应。

字段:

• (State): 操作状态

• response (SrvAPIGetAvailableImages_Response): 图像列表

  • success (bool): 是否成功

  • message (str): 状态消息

  • image_names (list[str]): 图像文件名列表

示例:

response = get_available_images()
if response.response.success:
    for img in response.response.image_names:
        print(f"图像: {img}")

云台控制响应

GetCurrentPTZFResponse

class GetCurrentPTZFResponse

Bases: object

property focus: int

Get focus

property pan: float

Get pan

property state: State

State of the response

property tilt: float

Get tilt

property zoom: float

Get zoom

获取云台位置的响应。

字段:

• (State): 操作状态

• pan (float): 当前水平角度

• tilt (float): 当前垂直角度

• zoom (float): 当前变焦值

• focus (int): 当前对焦值

示例:

response = get_ptzf()
if response.state.code == 0:
    print(f"Pan: {response.pan}°")
    print(f"Tilt: {response.tilt}°")

SetPTZFServiceResponse

class SetPTZFServiceResponse

Bases: object

property response: SrvSetPtzf_Response

Result of the response

property state: State

State of the response

设置云台位置的响应。

字段:

• (State): 操作状态

• response (SrvSetPtzf_Response): 设置结果

  • result (bool): 是否成功

示例:

response = set_ptzf(pan=30.0, tilt=15.0)
if response.response.result:
    print("云台位置设置成功")

地图和建图响应

GetAvailableMapsResponse

class GetAvailableMapsResponse

Bases: object

property response: SrvAPIGetAvailableMaps_Response

Service response

property state: State

State of the response

获取可用地图列表的响应。

字段:

• (State): 操作状态

• response (SrvAPIGetAvailableMaps_Response): 地图列表

  • success (bool): 是否成功

  • message (str): 状态消息

  • map_names (list[str]): 地图名称列表

示例:

response = get_available_maps()
if response.response.success:
    for map_name in response.response.map_names:
        print(f"地图: {map_name}")

StartMappingResponse

class StartMappingResponse

Bases: object

property response: SrvAPIStartMapping_Response

Service response

property state: State

State of the response

开始建图的响应。

字段:

• (State): 操作状态

• response (SrvAPIStartMapping_Response): 建图结果

  • success (bool): 是否成功

  • message (str): 状态消息

示例:

response = start_mapping("new_map")
if response.response.success:
    print(f"建图已开始: {response.response.message}")

StopMappingResponse

class StopMappingResponse

Bases: object

property response: SrvAPIStopMapping_Response

Service response

property state: State

State of the response

停止建图的响应。

字段:

• (State): 操作状态

• response (SrvAPIStopMapping_Response): 停止结果

  • success (bool): 是否成功

  • message (str): 状态消息

示例:

response = stop_mapping()
if response.response.success:
    print("建图已停止")

LoadMapResponse

class LoadMapResponse

Bases: object

property response: SrvAPILoadMap_Response

Service response

property state: State

State of the response

加载地图的响应。

字段:

• (State): 操作状态

• response (SrvAPILoadMap_Response): 加载结果

  • success (bool): 是否成功

  • message (str): 状态消息

示例:

response = load_map("office_floor1")
if response.response.success:
    print("地图加载成功")

运动控制相关响应

StandUpResponse

class StandUpResponse

Bases: object

property response: SrvRobotCommand_Response

RobotCommand service response

property state: State

State of the response

控制机器人站立的响应。

字段:

• (State): 操作状态

• response (RobotCommand_Response): 命令执行结果

  • result (bool): 是否成功

LieDownResponse

class LieDownResponse

Bases: object

property response: SrvRobotCommand_Response

RobotCommand service response

property state: State

State of the response

控制机器人躺下的响应。

字段:

• (State): 操作状态

• response (RobotCommand_Response): 命令执行结果

  • result (bool): 是否成功

GetRobotStateResponse

class GetRobotStateResponse

Bases: object

property robot_state: RobotState

Robot state (RobotState enum)

property state: State

State of the response

获取机器人状态的响应。

字段:

• (State): 操作状态

• robot_state (RobotState): 机器人当前状态枚举值

RobotCommandResponse

class RobotCommandResponse

Bases: object

property response: SrvRobotCommand_Response

RobotCommand service response

property state: State

State of the response

机器人通用命令的响应。

字段:

• (State): 操作状态

• response (RobotCommand_Response): 命令执行结果

  • result (bool): 是否成功

GetControlModeResponse

class GetControlModeResponse

Bases: object

property control_mode: ControlMode

Control mode (ControlMode enum)

property state: State

State of the response

获取控制模式的响应。

字段:

• (State): 操作状态

• control_mode (ControlMode): 当前控制模式

GetGaitResponse

class GetGaitResponse

Bases: object

property gait_type: GaitType

Gait type (GaitType enum)

property state: State

State of the response

获取步态类型的响应。

字段:

• (State): 操作状态

• gait_type (GaitType): 当前步态类型

GoToDockResponse

class GoToDockResponse

Bases: object

property response: SrvRobotCommand_Response

RobotCommand service response

property state: State

State of the response

前往充电座的响应。

字段:

• (State): 操作状态

• response (RobotCommand_Response): 命令执行结果

  • result (bool): 是否成功

LeaveDockResponse

class LeaveDockResponse

Bases: object

property response: SrvRobotCommand_Response

RobotCommand service response

property state: State

State of the response

离开充电座的响应。

字段:

• (State): 操作状态

• response (RobotCommand_Response): 命令执行结果

  • result (bool): 是否成功

GetDockStateResponse

class GetDockStateResponse

Bases: object

property dock_state: DockState

Dock state (DockState enum)

property state: State

State of the response

获取充电座状态的响应。

字段:

• (State): 操作状态

• dock_state (DockState): 当前充电座状态

GetBatteryStateResponse

class GetBatteryStateResponse

Bases: object

property battery_state: BatteryState

Complete battery state from sensor_msgs/BatteryState

property is_valid: bool

Whether battery_state data is valid (true) or stale/unavailable (false)

property state: State

State of the response

获取电池状态的响应。

字段:

• (State): 操作状态

• is_valid (bool): 数据是否有效

• battery_state (sensor_msgs/BatteryState): 完整的电池信息

IsChargeResponse

class IsChargeResponse

Bases: object

property is_charging: bool

Whether robot is charging (true/false)

property state: State

State of the response

检查充电状态的响应。

字段:

• (State): 操作状态

• is_charging (bool): 是否正在充电

SendCmdVelResponse

class SendCmdVelResponse

Bases: object

property state: State

State of the response

property success: bool

Whether cmd_vel was published successfully

发送速度控制命令的响应。

字段:

• (State): 操作状态

• success (bool): 命令是否发布成功

运动控制枚举类型

RobotState

class RobotState(value)

Bases: object

Robot state enumeration

Values:

LIE_DOWN (0): Robot is lying down STANDING_UP (1): Robot is in the process of standing up STAND_UP (2): Robot is standing ENABLE_FORCECONTROL (3): Force control mode STEPPING (4): Stepping in place SITTING_DOWN (5): Robot is sitting down FALL_DOWN (6): Robot has fallen down RL_STATE (16): Reinforcement learning state UNKNOWN_STATE (99): Unknown state

Members:

LIE_DOWN : Robot is lying down

STANDING_UP : Robot is in the process of standing up

STAND_UP : Robot is standing

ENABLE_FORCECONTROL : Force control mode

STEPPING : Stepping in place

SITTING_DOWN : Robot is sitting down

FALL_DOWN : Robot has fallen down

RL_STATE : Reinforcement learning state

UNKNOWN_STATE : Unknown state

Parameters:

value (int) –

ENABLE_FORCECONTROL: typing.ClassVar[RobotState]

FALL_DOWN: typing.ClassVar[RobotState]

LIE_DOWN: typing.ClassVar[RobotState]

RL_STATE: typing.ClassVar[RobotState]

SITTING_DOWN: typing.ClassVar[RobotState]

STANDING_UP: typing.ClassVar[RobotState]

STAND_UP: typing.ClassVar[RobotState]

STEPPING: typing.ClassVar[RobotState]

UNKNOWN_STATE: typing.ClassVar[RobotState]

property name: str

property value: int

机器人姿态状态枚举。

取值:

• LIE_DOWN (0): 躺下状态

• STANDING_UP (1): 正在站立（过渡状态）

• STAND_UP (2): 站立状态

• UNKNOWN_STATE (7): 未知状态（数据不可用或过期）

ControlMode

class ControlMode(value)

Bases: object

Control mode enumeration

Values:

JOY_MODE (0): Joystick/manual control mode NAV_MODE (1): Navigation/automatic control mode NULL_MODE (2): No state/null mode UWB_MODE (3): UWB positioning mode ASSIST_MODE (4): AI assist mode UNKNOWN_MODE (99): Unknown mode

Members:

JOY_MODE : Joystick/manual control mode

NAV_MODE : Navigation/automatic control mode

NULL_MODE : No state/null mode

UWB_MODE : UWB positioning mode

ASSIST_MODE : AI assist mode

UNKNOWN_MODE : Unknown mode

Parameters:

value (int) –

ASSIST_MODE: typing.ClassVar[ControlMode]

JOY_MODE: typing.ClassVar[ControlMode]

NAV_MODE: typing.ClassVar[ControlMode]

NULL_MODE: typing.ClassVar[ControlMode]

UNKNOWN_MODE: typing.ClassVar[ControlMode]

UWB_MODE: typing.ClassVar[ControlMode]

property name: str

property value: int

机器人控制模式枚举。

取值:

• JOY_MODE (0): 手柄/手动控制模式

• NAV_MODE (1): 导航/自动控制模式

• UNKNOWN_MODE (99): 未知模式（数据不可用或过期）

GaitType

class GaitType(value)

Bases: object

Gait type enumeration

Values:

TROT (0): Trot gait (normal walking) NORMAL_STAIR (1): Normal stair climbing gait SLOPE (2): Slope/incline gait SENSE_STAIR (6): Sensing stair gait POSE_ADJUST (13): Pose adjustment/locked standing (MC) CAR_MODE (14): Crawling/car mode (MC) RL_TROT (0x20): RL walking gait RL_MOUNTAIN (0x21): RL mountain/terrain gait UNKNOWN_GAIT (99): Unknown gait

Members:

TROT : Trot gait (normal walking)

NORMAL_STAIR : Normal stair climbing gait

SLOPE : Slope/incline gait

SENSE_STAIR : Sensing stair gait

POSE_ADJUST : Pose adjustment/locked standing (MC)

CAR_MODE : Crawling/car mode (MC)

RL_TROT : RL walking gait

RL_MOUNTAIN : RL mountain/terrain gait

UNKNOWN_GAIT : Unknown gait

Parameters:

value (int) –

CAR_MODE: typing.ClassVar[GaitType]

NORMAL_STAIR: typing.ClassVar[GaitType]

POSE_ADJUST: typing.ClassVar[GaitType]

RL_MOUNTAIN: typing.ClassVar[GaitType]

RL_TROT: typing.ClassVar[GaitType]

SENSE_STAIR: typing.ClassVar[GaitType]

SLOPE: typing.ClassVar[GaitType]

TROT: typing.ClassVar[GaitType]

UNKNOWN_GAIT: typing.ClassVar[GaitType]

property name: str

property value: int

机器人步态类型枚举。

取值:

• TROT (0): 小跑步态

• NORMAL_STAIR (1): 普通楼梯步态

• SLOPE (2): 斜坡步态

• SENSE_STAIR (6): 感知楼梯步态

• POSE_ADJUST (13): 姿态调整步态

• CAR_MODE (14): 车模式步态

• RL_TROT (0x20): 强化学习小跑步态

• RL_Mountain (0x21): 强化学习山地步态

• UNKNOWN_GAIT (99): 未知步态（数据不可用或过期）

DockState

class DockState(value)

Bases: object

Dock state enumeration

Values:

IDLE (0): Idle state GOING_TO_DOCK (1): Robot is going to the dock STAND_ABOVE_DOCK (2): Robot is standing above the dock ADJUST_POSE (3): Adjusting pose on dock LIE_ON_DOCKER (4): Robot is lying on the dock (charging) STANDING_AFTER_CHARGING (5): Standing up after charging LEAVING_DOCK (6): Robot is leaving the dock LEAVE_DOCK (7): Robot has left the dock UNKNOWN_DOCK (99): Unknown dock state

Members:

IDLE : Idle state

GOING_TO_DOCK : Robot is going to the dock

STAND_ABOVE_DOCK : Robot is standing above the dock

ADJUST_POSE : Adjusting pose on dock

LIE_ON_DOCKER : Robot is lying on the dock (charging)

STANDING_AFTER_CHARGING : Standing up after charging

LEAVING_DOCK : Robot is leaving the dock

LEAVE_DOCK : Robot has left the dock

UNKNOWN_DOCK : Unknown dock state

Parameters:

value (int) –

ADJUST_POSE: typing.ClassVar[DockState]

GOING_TO_DOCK: typing.ClassVar[DockState]

IDLE: typing.ClassVar[DockState]

LEAVE_DOCK: typing.ClassVar[DockState]

LEAVING_DOCK: typing.ClassVar[DockState]

LIE_ON_DOCKER: typing.ClassVar[DockState]

STANDING_AFTER_CHARGING: typing.ClassVar[DockState]

STAND_ABOVE_DOCK: typing.ClassVar[DockState]

UNKNOWN_DOCK: typing.ClassVar[DockState]

property name: str

property value: int

充电座状态枚举。

取值:

• IDLE (0): 空闲

• GOING_TO_DOCK (1): 正在前往充电座

• STAND_ABOVE_DOCK (2): 站在充电座上方

• ADJUST_POSE (3): 正在调整姿态

• LIE_ON_DOCKER (4): 躺在充电座上

• STANDING_AFTER_CHARGING (5): 充电后站立

• LEAVING_DOCK (6): 正在离开充电座

• LEAVE_DOCK (7): 已离开充电座

• UNKNOWN_DOCK (99): 未知状态（数据不可用或过期）

客户自定义错误处理相关响应

RaiseWarnResponse

class RaiseWarnResponse

Bases: object

property response: SrvAPIRaiseWarn_Response

Service response

property state: State

State of the response

触发警告接口的响应。

字段:

• (State): 操作状态

• response (SrvAPIRaiseWarn_Response): 停止结果

  • success (bool): 是否成功

  • message (str): 状态消息

示例:

response = raise_warn()
if response.response.success:
    print("触发警告成功！")

RaiseErrorResponse

class RaiseErrorResponse

Bases: object

property response: SrvAPIRaiseError_Response

Service response

property state: State

State of the response

触发警告接口的响应。

字段:

• (State): 操作状态

• response (SrvAPIRaiseError_Response): 停止结果

  • success (bool): 是否成功

  • message (str): 状态消息

示例:

response = raise_error()
if response.response.success:
    print("触发错误提示成功！")

ROS层服务响应类型

这些类型是底层 ROS 服务的响应结构，通常被包装在上述接口层响应类型的 response 字段中。

导航服务响应

SrvAPINavigationViaPoses_Response

class SrvAPINavigationViaPoses_Response

Bases: object

property message: str

property success: bool

多点导航的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

SrvAPINavigationViaLocations_Response

class SrvAPINavigationViaLocations_Response

Bases: object

property message: str

property success: bool

按已注册点位名序列做多点导航的底层 ROS 服务响应。字段语义与 SrvAPINavigationViaPoses_Response 相同——本类型只是为了与 api_msgs/srv/NavigationViaLocations 一一对应而独立绑定。

字段:

• success (bool): 是否成功

• message (str): 状态消息（任一 location yaml 加载失败时携带具体哪个 location 无法解析）

IntelligentNavigation_Result

class IntelligentNavigation_Result

Bases: object

property error_code: int

property error_msg: str

property result: bool

智能导航动作的结果。

字段:

• result (int): 结果代码

• error_code (int): 错误代码

• error_msg (str): 错误消息

定位服务响应

SrvAPIGetCurrentPose_Response

class SrvAPIGetCurrentPose_Response

Bases: object

property location_pose: Pose

property success: bool

获取当前位姿的底层ROS服务响应。

字段:

• success (bool): 是否成功

• location_pose (PoseStamped): 当前位姿（带时间戳和坐标系）

示例:

# 通常在 GetCurrentPoseServiceResponse.response 中访问
response = get_current_pose()
if response.response.success:
    pose = response.response.location_pose
    print(f"X: {pose.position.x}, Y: {pose.position.y}")

SrvAPIGetLocalizationState_Response

class SrvAPIGetLocalizationState_Response

Bases: object

property loc_state: int

Localization state: - 0: NORMAL

• 1: LACKDATA

• 2: LOST

property success: bool

获取定位状态的底层ROS服务响应。

字段:

• success (bool): 是否成功

• loc_state (int): 定位状态

  • 0: NORMAL - 正常

  • 1: LACKDATA - 数据不足

  • 2: LOST - 丢失

示例:

response = get_localization_state()
if response.response.success:
    if response.response.loc_state == 0:
        print("定位正常")
    elif response.response.loc_state == 2:
        print("定位丢失")

云台服务响应

SrvSetPtzf_Response

class SrvSetPtzf_Response

Bases: object

property result: bool

设置云台位置的底层ROS服务响应。

字段:

• result (bool): 是否成功

SrvAPIGetPtzf_Response

class SrvAPIGetPtzf_Response

Bases: object

property focus: int

property pan: float

property success: bool

property tilt: float

property zoom: float

获取云台位置的底层ROS服务响应。

字段:

• success (bool): 是否成功

• pan (float): 水平角度

• tilt (float): 垂直角度

• zoom (float): 变焦值

• focus (int): 对焦值

相机服务响应

SrvAPICaptureImage_Response

class SrvAPICaptureImage_Response

Bases: object

property message: str

property success: bool

拍照的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

SrvAPIGetAvailableImages_Response

class SrvAPIGetAvailableImages_Response

Bases: object

property image_names: list[str]

property message: str

property success: bool

获取图像列表的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

• image_names (list[str]): 图像文件名列表

地图服务响应

SrvAPIGetAvailableMaps_Response

class SrvAPIGetAvailableMaps_Response

Bases: object

property map_names: list[str]

property maps: list[MapFileInfo]

各地图详细信息列表（含 FileInfo）

property message: str

property success: bool

获取地图列表的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

• map_names (list[str]): 地图名称列表

SrvSetLocalizationMode_Response

class SrvSetLocalizationMode_Response

Bases: object

property result: bool

设置定位模式的底层ROS服务响应。

字段:

• result (bool): 是否成功

SrvReloadMap_Response

class SrvReloadMap_Response

Bases: object

property result: bool

重新加载地图的底层ROS服务响应。

字段:

• result (bool): 是否成功

SrvSaveMap_Response

class SrvSaveMap_Response

Bases: object

property result: bool

保存地图的底层ROS服务响应。

字段:

• result (bool): 是否成功

SrvAPIStartMapping_Response

class SrvAPIStartMapping_Response

Bases: object

property message: str

property success: bool

开始建图的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

SrvAPIStopMapping_Response

class SrvAPIStopMapping_Response

Bases: object

property message: str

property success: bool

停止建图的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

SrvAPILoadMap_Response

class SrvAPILoadMap_Response

Bases: object

property message: str

property success: bool

加载地图的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

SrvAPISetLocalization_Response

class SrvAPISetLocalization_Response

Bases: object

property message: str

property success: bool

设置定位的底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

SrvSetLocalization_Response

class SrvSetLocalization_Response

Bases: object

property result: bool

property result_pose: PoseWithCovarianceStamped

设置定位的底层ROS服务响应。

字段:

• result (bool): 是否成功

• result_pose (PoseStamped): 设置后的位姿

客户自定义错误处理响应

SrvAPIRaiseWarn_Response

class SrvAPIRaiseWarn_Response

Bases: object

property message: str

property success: bool

触发警告底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

SrvAPIRaiseError_Response

class SrvAPIRaiseError_Response

Bases: object

property message: str

property success: bool

触发错误底层ROS服务响应。

字段:

• success (bool): 是否成功

• message (str): 状态消息

事件类型

NavCompleteEvent

class NavCompleteEvent

Bases: object

property current_pose: Pose

property navigation_time: int

property target: str

property task_id: str

property timestamp: str

导航完成事件。

字段:

• result (int): 导航结果代码

• final_pose (Pose): 最终位姿

NavFailedEvent

class NavFailedEvent

Bases: object

property current_pose: Pose

property error_msg: str

property error_type: int

property task_id: str

property timestamp: str

导航失败事件。

字段:

• error_code (int): 错误代码

• error_msg (str): 错误消息

NavProgressEvent

class NavProgressEvent

Bases: object

property current_pose: Pose

property current_state: int

property distance_remaining: float

property navigation_time: int

property target_location: str

property task_id: str

property time_remaining: int

property timestamp: str

导航进度更新事件。

字段:

• distance_remaining (float): 剩余距离（米）

• eta (float): 预计到达时间（秒）

• current_speed (float): 当前速度（m/s）

示例:

def on_progress(event):
    print(f"剩余距离: {event.distance_remaining:.2f}m")
    print(f"预计 {event.eta:.0f}秒后到达")

navigation_to_location("office", progress_callback=on_progress)

类型转换和使用注意事项

Python 和 C++ 类型映射

Python 类型	C++ 类型	说明
str	std::string	字符串
int	int32_t	32 位整数
float	double	双精度浮点数
bool	bool	布尔值
list	std::vector	动态数组
dict	N/A	可用于构造 Pose 等对象

常见用法模式

1. 检查响应状态:

response = some_function()
if response.state.code == 0:
    # 成功
    process_result(response.response)
else:
    # 失败
    print(f"错误: {response.state.describe}")

2. 构造位姿:

# 方法 1：空构造 + setter（任何时候都可用）
pose = Pose()
pose.position.x = 1.0
pose.position.y = 2.0
pose.orientation.w = 1.0

# 方法 2：kwargs / 位置参数（推荐：orientation 默认 identity，无需手设 w=1）
pose = Pose(position=Point(1.0, 2.0, 0.0))
pose = Pose(Point(1.0, 2.0, 0.0))   # 等价

# 方法 3：使用字典（部分高层函数支持）
navigation_to_pose({"x": 1.0, "y": 2.0, "qw": 1.0})

3. 设置导航参数:

params = MsgTravelParams()
params.speed_mode = 2  # 低速
params.distance_tolerance = 0.3

navigation_to_location("target", travel_params=params)

4. 使用回调函数:

def on_complete(event):
    print("导航完成!")

def on_failed(event):
    print(f"导航失败: {event.error_msg}")

navigation_to_location(
    "destination",
    complete_callback=on_complete,
    failed_callback=on_failed
)

相关文档

• 导航控制 - 导航功能详解

• 云台控制 - 云台控制详解

• 定位与位姿 - 定位功能详解

• 地图管理 - 建图功能详解