Tool: rest()

The rest() tool is a function within the Reachy Mini MCP server designed to control the robot's resting state. It provides a simple interface for an AI system to transition the robot between neutral, sleep (low power), and wake states. This tool is one of the seven primary functions exposed by the MCP server for high-level robot control.

Sources: src/server.py:1003-1022, README.md:15

Function Definition

The rest() function is exposed as an MCP tool using the @mcp.tool() decorator. It accepts a single optional argument, mode.

Sources: src/server.py:1003-1004

# File: src/server.py

@mcp.tool()
def rest(mode: Literal["neutral", "sleep", "wake"] = "neutral") -> str:
    """
    Control robot rest state.

    Args:
        mode:
            - "neutral": Return to neutral pose (default)
            - "sleep": Enter sleep mode (low power)
            - "wake": Wake from sleep mode

    Returns:
        Confirmation
    """
    robot = get_robot()
    try:
        if mode == "sleep":
            robot.goto_sleep()
            return "Robot sleeping"
        elif mode == "wake":
            robot.wake_up()
            return "Robot awakened"
        else:  # neutral
            return _do_express("neutral")
    except Exception as e:
        return f"Rest failed: {e}"

Sources: src/server.py:1003-1022

Parameters

The rest() tool has one parameter that determines its behavior.

Sources: README.md:15, src/server.py:1004-1011

Functional Logic

The rest() function's behavior is determined by the mode parameter. It first acquires a connection to the robot via the get_robot() helper function and then executes one of three branches within a try...except block for error handling.

The following diagram illustrates the control flow within the rest() function.

Neutral Mode

When mode is "neutral" or not provided, the function calls the internal helper _do_express("neutral"). This function looks up the "neutral" state in the EXPRESSIONS dictionary and uses the reachy_mini SDK's goto_target method to move the robot's head and antennas to a predefined neutral position.

The "neutral" expression is defined as:

# File: src/server.py

"neutral": {
    "head": {"z": 0, "roll": 0, "pitch": 0, "yaw": 0},
    "antennas": [0, 0],
    "duration": 1.5,
    "method": "minjerk"
},

This configuration sets the head to a level position with no rotation and the antennas to their zero-degree position over 1.5 seconds using a "minjerk" interpolation.

Sources: src/server.py:59-64, src/server.py:1017-1018, src/server.py:270-291

Sleep Mode

If mode is set to "sleep", the function directly calls robot.goto_sleep(). This is a method from the reachy-mini SDK that puts the robot into a low-power state.

Sources: src/server.py:1013-1014

Wake Mode

If mode is set to "wake", the function calls robot.wake_up(), another method from the reachy-mini SDK that brings the robot out of its sleep state.

Sources: src/server.py:1015-1016

Sequence Diagram

This diagram shows the sequence of calls when an AI system uses the rest(mode="sleep") tool.

Project Context

The rest() tool is part of the reachy-mini-mcp project, which aims to provide a simple, high-level interface for AI systems to control a Reachy Mini robot. The project is defined with its dependencies in pyproject.toml and is licensed under the MIT License. The __init__.py file marks the src directory as a Python package.

Sources: pyproject.toml, src/init.py, LICENSE, README.md:1-5