Skip to content

sim2bot.Robot.describe

describe(timeout: float = 2.0) -> list[RobotInfo]

Request model-derived metadata for every robot in the current scene.

Parameters:

  • timeout (float, default: 2.0 ) –

    Maximum time in seconds to wait for a scene announcement.

Returns:

  • list[RobotInfo] –

    Robots in current scene order. The returned index is the command

  • list[RobotInfo] –

    address to pass as robot=. An empty list means no scene response

  • list[RobotInfo] –

    arrived before the timeout or no robot is loaded.

Raises:

  • RuntimeError –

    If the client is not connected.

  • ConnectionClosed –

    If the WebSocket closes while sending discovery.

  • OSError –

    If the selected transport cannot send the request.

Notes

Discover the scene instead of hard-coding degree of freedom, joint order, limits, or home targets.

Source code in sim2bot/client.py 
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
def describe(self, timeout: float = 2.0) -> list[RobotInfo]:
    """Request model-derived metadata for every robot in the current scene.

    Args:
        timeout: Maximum time in seconds to wait for a scene announcement.

    Returns:
        Robots in current scene order. The returned ``index`` is the command
        address to pass as ``robot=``. An empty list means no scene response
        arrived before the timeout or no robot is loaded.

    Raises:
        RuntimeError: If the client is not connected.
        ConnectionClosed: If the WebSocket closes while sending discovery.
        OSError: If the selected transport cannot send the request.

    Notes:
        Discover the scene instead of hard-coding degree of freedom, joint
        order, limits, or home targets.
    """
    self._scene_event.clear()
    self._send({"type": "describe"})
    self._scene_event.wait(timeout)
    robots = (self._scene or {}).get("robots", [])
    return [RobotInfo.from_json(item) for item in robots]

Practical examples

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

List every robot

for arm in sim.describe():
    print(arm.index, arm.name, arm.dof)
    print(arm.joint_names)

Select by stable scene ID

arms = sim.describe()
arm = next(item for item in arms if item.id == "robot_f8525b36")
sim.move_to(arm.home, robot=arm.index)

Guidance

Usage tip

Discover before controlling. Scene order, degree of freedom, joint names, and limits can change when users edit the scene.

Common error

An empty list means no robot scene was announced before the timeout; it does not necessarily mean the bridge connection failed.

See also