sim2bot.RobotState

RobotState dataclass

Latest complete telemetry packet for one robot.

Joint quantities use the command order announced by RobotInfo. TCP quantities are expressed in the world frame. Derivatives are unsmoothed; any smoothing selected in the GUI is display-only.

Attributes:

• robot (int) –

  Current scene robot index.

• id (str) –

  Robot scene identity.

• name (str) –

  Human-readable robot name.

• dof (int) –

  Number of reported arm joints.

• t (float) –

  MuJoCo simulation time in seconds.

• q (list[float]) –

  Joint positions in radians.

• target (list[float]) –

  Latest joint-position targets in radians.

• qd (list[float]) –

  Joint velocities in radians per second.

• qdd (list[float]) –

  Joint accelerations in radians per second squared.

• qddd (list[float]) –

  Joint jerk in radians per second cubed.

• tcp (list[float]) –

  TCP world position [x, y, z] in metres.

• tcp_orientation (list[float]) –

  TCP world quaternion [x, y, z, w].

• tcp_linear_velocity (list[float]) –

  World-frame linear velocity in metres per second.

• tcp_angular_velocity (list[float]) –

  World-frame angular velocity in radians per second.

• tcp_linear_acceleration (list[float]) –

  Linear acceleration in metres per second squared.

• tcp_angular_acceleration (list[float]) –

  Angular acceleration in radians per second squared.

• tcp_linear_jerk (list[float]) –

  Linear jerk in metres per second cubed.

• tcp_angular_jerk (list[float]) –

  Angular jerk in radians per second cubed.

• gripper (Optional[float]) –

  Commanded opening fraction from 0 closed to 1 open, if present.

• sensors (list[dict]) –

  Authored sensor readings associated with this robot packet.

• room_devices (list[dict]) –

  Scene door/window states, currently carried by robot 0.

• capture_ts (Optional[float]) –

  Unix capture timestamp for the newest packet sample.

• samples (list[dict]) –

  Physics-substep {t, q, qd} samples since the prior packet.

Source code in sim2bot/client.py

@dataclass
class RobotState:
    """Latest complete telemetry packet for one robot.

    Joint quantities use the command order announced by
    [`RobotInfo`][sim2bot.client.RobotInfo].
    TCP quantities are expressed in the world frame. Derivatives are unsmoothed;
    any smoothing selected in the GUI is display-only.

    Attributes:
        robot: Current scene robot index.
        id: Robot scene identity.
        name: Human-readable robot name.
        dof: Number of reported arm joints.
        t: MuJoCo simulation time in seconds.
        q: Joint positions in radians.
        target: Latest joint-position targets in radians.
        qd: Joint velocities in radians per second.
        qdd: Joint accelerations in radians per second squared.
        qddd: Joint jerk in radians per second cubed.
        tcp: TCP world position ``[x, y, z]`` in metres.
        tcp_orientation: TCP world quaternion ``[x, y, z, w]``.
        tcp_linear_velocity: World-frame linear velocity in metres per second.
        tcp_angular_velocity: World-frame angular velocity in radians per second.
        tcp_linear_acceleration: Linear acceleration in metres per second squared.
        tcp_angular_acceleration: Angular acceleration in radians per second squared.
        tcp_linear_jerk: Linear jerk in metres per second cubed.
        tcp_angular_jerk: Angular jerk in radians per second cubed.
        gripper: Commanded opening fraction from 0 closed to 1 open, if present.
        sensors: Authored sensor readings associated with this robot packet.
        room_devices: Scene door/window states, currently carried by robot 0.
        capture_ts: Unix capture timestamp for the newest packet sample.
        samples: Physics-substep ``{t, q, qd}`` samples since the prior packet.
    """

    robot: int
    """Current scene robot index used by addressed SDK commands."""
    id: str
    """Stable robot identity while the current scene instance remains loaded."""
    name: str
    """Human-readable robot model or scene-instance name."""
    dof: int
    """Number of reported controllable arm joints."""
    t: float
    """MuJoCo simulation time in seconds for the newest sample."""
    q: list[float]
    """Joint positions in radians and discovered joint order."""
    target: list[float]
    """Latest joint-position targets in radians and discovered joint order."""
    qd: list[float] = field(default_factory=list)
    """Joint velocities in radians per second."""
    qdd: list[float] = field(default_factory=list)
    """Unsmoothed joint accelerations in radians per second squared."""
    qddd: list[float] = field(default_factory=list)
    """Unsmoothed joint jerk in radians per second cubed."""
    tcp: list[float] = field(default_factory=list)
    """TCP world position ``[x, y, z]`` in metres."""
    tcp_orientation: list[float] = field(default_factory=list)
    """TCP world orientation quaternion in ``[x, y, z, w]`` order."""
    tcp_linear_velocity: list[float] = field(default_factory=list)
    """TCP world-frame linear velocity ``[x, y, z]`` in metres per second."""
    tcp_angular_velocity: list[float] = field(default_factory=list)
    """TCP world-frame angular velocity ``[x, y, z]`` in radians per second."""
    tcp_linear_acceleration: list[float] = field(default_factory=list)
    """TCP linear acceleration in metres per second squared."""
    tcp_angular_acceleration: list[float] = field(default_factory=list)
    """TCP angular acceleration in radians per second squared."""
    tcp_linear_jerk: list[float] = field(default_factory=list)
    """TCP linear jerk in metres per second cubed."""
    tcp_angular_jerk: list[float] = field(default_factory=list)
    """TCP angular jerk in radians per second cubed."""
    gripper: Optional[float] = None
    """Commanded opening fraction from 0 closed to 1 open, or ``None``."""
    sensors: list[dict] = field(default_factory=list)
    """Authored sensor readings associated with this robot telemetry packet."""
    # Scene-level door/window joint states. Present on robot 0 telemetry.
    room_devices: list[dict] = field(default_factory=list)
    """Scene door/window states, currently carried on robot 0 telemetry."""
    # Wall-clock capture time (unix s) of the newest sample, for latency.
    capture_ts: Optional[float] = None
    """Browser wall-clock capture timestamp in Unix seconds, if available."""
    # High-rate batch since the previous packet: [{t, q, qd}, ...] at physics rate.
    samples: list[dict] = field(default_factory=list)
    """Physics-substep ``{t, q, qd}`` samples since the previous packet."""

    @classmethod
    def from_json(cls, data: dict) -> "RobotState":
        return cls(
            robot=int(data.get("robot", 0)),
            id=str(data.get("id") or ""),
            name=str(data.get("name", "")),
            dof=int(data.get("dof", 0)),
            t=float(data.get("t", 0.0)),
            q=list(data.get("q", []) or []),
            target=list(data.get("target", []) or []),
            qd=list(data.get("qd", []) or []),
            qdd=list(data.get("qdd", []) or []),
            qddd=list(data.get("qddd", []) or []),
            tcp=list(data.get("tcp", []) or []),
            tcp_orientation=list(data.get("tcpOrientation", []) or []),
            tcp_linear_velocity=list(data.get("tcpLinearVelocity", []) or []),
            tcp_angular_velocity=list(data.get("tcpAngularVelocity", []) or []),
            tcp_linear_acceleration=list(data.get("tcpLinearAcceleration", []) or []),
            tcp_angular_acceleration=list(data.get("tcpAngularAcceleration", []) or []),
            tcp_linear_jerk=list(data.get("tcpLinearJerk", []) or []),
            tcp_angular_jerk=list(data.get("tcpAngularJerk", []) or []),
            gripper=data.get("gripper"),
            sensors=list(data.get("sensors", []) or []),
            room_devices=list(data.get("roomDevices", []) or []),
            capture_ts=data.get("captureTs"),
            samples=list(data.get("samples", []) or []),
        )

    @property
    def latency(self) -> Optional[float]:
        """Return the current telemetry age in seconds.

        Returns:
            Seconds since browser capture, or ``None`` when the packet did not
            include a capture timestamp.
        """
        return (time.time() - self.capture_ts) if self.capture_ts else None

---

Practical examples

Examples use objects discovered from the current scene rather than hard-coded robot metadata.

Read joint derivatives

state = sim.state(robot=arm.index)
if state:
    print(state.qd)    # rad/s
    print(state.qdd)   # rad/s²
    print(state.qddd)  # rad/s³

Read the full TCP pose

if state:
    position_m = state.tcp
    orientation_xyzw = state.tcp_orientation

---

Guidance

Usage tip

GUI derivative smoothing is display-only; these SDK values remain unsmoothed.

---

See also

• sim2bot.Robot.state
• sim2bot.Robot.states
• sim2bot.RobotState.latency
• Python SDK workflows
• Python examples
• Bridge and networking