"""Raiden teleop helpers (single-arm convenience).

Wraps the four-line raiden setup-and-start sequence:
``RobotController(...) → setup_for_teleop_recording → enable_estop →
start_teleoperation``. Returns the ``RobotController`` so the caller
can read the follower joints and watch for the yellow leader button
via ``rc.check_button_press()``.

Fail-loud: any raiden error propagates. Press the yellow leader top
button to exit any teleop session cleanly.
"""
from __future__ import annotations

from raiden.robot.controller import RobotController


def start_teleop(arm: str = "right") -> RobotController:
    """Start raiden teleop for one arm. ``arm`` is ``'right'`` or ``'left'``."""
    if arm not in ("right", "left"):
        raise ValueError(f"arm must be 'right' or 'left', got {arm!r}")
    rc = RobotController(
        use_right_leader=(arm == "right"),
        use_right_follower=(arm == "right"),
        use_left_leader=(arm == "left"),
        use_left_follower=(arm == "left"),
    )
    rc.setup_for_teleop_recording()
    rc.enable_estop()
    rc.start_teleoperation()
    return rc


def stop_teleop(rc: RobotController) -> None:
    """Symmetric teardown: stop, home, shutdown."""
    rc.stop_teleoperation()
    rc.return_to_home()
    rc.shutdown()