Robot 类

Robot 类是与 3we 机器人交互的主要入口，无论是在仿真环境还是真实硬件上。它提供了统一的接口，用于连接机器人、读取传感器数据和发送运动指令。

快速开始

import asyncio
from threewe import Robot

async def main():
    async with Robot(backend="mock") as robot:
        pose = robot.get_pose()
        print(f"Position: {pose.x}, {pose.y}, heading: {pose.theta}")
        await robot.move_to(x=1.0, y=0.5)

asyncio.run(main())

构造函数

Robot(
    backend: str = "gazebo",
    config: str | RobotConfig = "standard_v2",
    *,
    hardware: str = "3we_standard_v2",
    scene: str = "office_v2",
    auto_connect: bool = True,
)

支持三种后端：

"gazebo"：Gazebo Harmonic 仿真（CPU，CI，快速迭代）
"isaac_sim"：NVIDIA Isaac Sim（GPU RL 训练，域随机化）
"real"：通过 ROS2 Jazzy 连接物理机器人（Pi 5 + ESP32-S3 + micro-ROS）

所有后端以相同格式返回数据——为某一后端编写的代码无需修改即可在其他后端上运行。

核心方法

连接

方法	描述
`connect()`	建立与机器人或仿真器的连接。
`disconnect()`	优雅地关闭连接并释放资源。
`is_connected`	属性。如果机器人当前可达则返回 `True`。

传感器数据

方法	描述
`get_image()`	返回 RGB 图像，格式为 `(H, W, 3)` uint8 numpy 数组。
`get_camera_image()`	与 `get_image()` 相同。
`get_lidar_scan()`	返回 `LaserScan`，包含 360 度 2D 距离数据。
`get_pose()`	返回 `Pose2D(x, y, theta)`，地图坐标系（米、弧度）。
`get_velocity()`	返回 `Velocity(vx, vy, omega)`，机体坐标系。
`get_imu()`	返回 `IMUData`，包含加速度、角速度、方向。
`get_rgbd_image()`	返回 `RGBDImage`，包含对齐的 RGB-D 图像对（需要深度相机）。
`get_map()`	返回当前 SLAM 地图的 `OccupancyGrid`。
`get_battery_state()`	返回 `BatteryState`，包含电压、百分比、充电状态。
`get_observation(modalities=None)`	返回标准化的 numpy 数组字典，用于 ML 模型输入。

运动

方法	描述
`move_to(x, y, theta=None, timeout=60.0)`	使用 Nav2 路径规划导航到地图坐标系目标。返回 `MoveResult`。
`move_forward(distance)`	直线前进 `distance` 米。返回 `MoveResult`。
`rotate(angle)`	原地旋转 `angle` 弧度（正值 = 逆时针）。返回 `MoveResult`。
`follow_path(waypoints)`	按顺序跟踪一系列 `Pose2D` 路径点。返回 `MoveResult`。
`explore(timeout=60.0)`	自主探索未知区域。返回 `ExploreResult`。
`stop()`	立即停止所有运动。
`set_velocity(vx, vy, omega)`	设置瞬时速度指令（m/s, m/s, rad/s）。必须持续调用，否则超时后电机停止。

AI 集成

方法	描述
`execute_instruction(instruction)`	使用 VLM 推理执行自然语言指令。返回 `ExecutionResult`。
`execute_action(action)`	执行策略网络输出的动作向量（numpy 数组）。

生命周期

方法	描述
`reset()`	将机器人重置为初始状态（仿真）或重新归位（硬件）。
`close()`	`disconnect()` 的别名。为上下文管理器兼容性提供。

上下文管理器

Robot 类支持 Python 的异步上下文管理器协议：

from threewe import Robot

async with Robot(backend="mock") as robot:
    await robot.move_to(1.0, 0.0)
    # automatically disconnects on exit

数据类型

类型	字段
`Pose2D`	`x: float`, `y: float`, `theta: float`
`Velocity`	`vx: float`, `vy: float`, `omega: float`
`MoveResult`	`success: bool`, `final_pose: Pose2D`, `duration: float`, `distance: float`, `reason: str`
`ExploreResult`	`coverage: float`, `duration: float`, `cells_explored: int`, `timed_out: bool`
`ExecutionResult`	`success: bool`, `description: str`, `images: list`
`LaserScan`	`ranges: ndarray`, `angles: ndarray`, `range_max: float`, `timestamp: float`
`IMUData`	`acceleration: ndarray`, `angular_velocity: ndarray`, `orientation: ndarray`, `timestamp: float`
`RGBDImage`	`rgb: ndarray`, `depth: ndarray`, `intrinsics: CameraIntrinsics`, `timestamp: float`
`BatteryState`	`voltage: float`, `percentage: float`, `is_charging: bool`
`OccupancyGrid`	`data: ndarray`, `resolution: float`, `origin: Pose2D`, `timestamp: float`

配置

传入配置字典或 YAML 文件路径来自定义行为：

robot = Robot(config="my_robot.yaml")

主要配置选项包括 base_frame、max_velocity、timeout 和 hardware.serial_port。