Robot Class

The Robot class is the main entry point for interacting with a 3we robot, whether in simulation or on real hardware. It provides a unified interface for connecting to the robot, reading sensor data, and issuing motion commands.

Quick Start

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())

Constructor

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

Supports three backends:

"gazebo": Gazebo Harmonic simulation (CPU, CI, quick iteration)
"isaac_sim": NVIDIA Isaac Sim (GPU RL training, domain randomization)
"real": Physical robot via ROS2 Jazzy (Pi 5 + ESP32-S3 + micro-ROS)

All backends return data in identical formats — code written for one backend works on all others without modification.

Core Methods

Connection

Method	Description
`connect()`	Establish connection to the robot or simulator.
`disconnect()`	Gracefully close the connection and release resources.
`is_connected`	Property. Returns `True` if the robot is currently reachable.

Sensor Data

Method	Description
`get_image()`	Returns RGB image as `(H, W, 3)` uint8 numpy array.
`get_camera_image()`	Same as `get_image()`.
`get_lidar_scan()`	Returns `LaserScan` with 360-degree 2D range data.
`get_pose()`	Returns `Pose2D(x, y, theta)` in map frame (meters, radians).
`get_velocity()`	Returns `Velocity(vx, vy, omega)` in body frame.
`get_imu()`	Returns `IMUData` with acceleration, angular velocity, orientation.
`get_rgbd_image()`	Returns `RGBDImage` with aligned RGB-D pair (requires depth camera).
`get_map()`	Returns `OccupancyGrid` from current SLAM map.
`get_battery_state()`	Returns `BatteryState` with voltage, percentage, charging state.
`get_observation(modalities=None)`	Returns standardized dict of numpy arrays for ML model ingestion.

Motion

Method	Description
`move_to(x, y, theta=None, timeout=60.0)`	Navigate to map-frame goal using Nav2 path planning. Returns `MoveResult`.
`move_forward(distance)`	Drive straight ahead by `distance` meters. Returns `MoveResult`.
`rotate(angle)`	Rotate in place by `angle` radians (positive = CCW). Returns `MoveResult`.
`follow_path(waypoints)`	Follow a sequence of `Pose2D` waypoints in order. Returns `MoveResult`.
`explore(timeout=60.0)`	Autonomously explore unknown areas. Returns `ExploreResult`.
`stop()`	Immediately halt all motion.
`set_velocity(vx, vy, omega)`	Set instantaneous velocity commands (m/s, m/s, rad/s). Must be called continuously or timeout stops motors.

AI Integration

Method	Description
`execute_instruction(instruction)`	Execute a natural language instruction using VLM reasoning. Returns `ExecutionResult`.
`execute_action(action)`	Execute a policy network output action vector (numpy array).

Lifecycle

Method	Description
`reset()`	Reset the robot to its initial state (simulation) or re-home (hardware).
`close()`	Alias for `disconnect()`. Provided for context-manager compatibility.

Context Manager

The Robot class supports Python’s async context manager protocol:

from threewe import Robot

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

Data Types

Type	Fields
`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`

Configuration

Pass a configuration dictionary or path to a YAML file to customize behavior:

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

Key configuration options include base_frame, max_velocity, timeout, and hardware.serial_port.