phosphobot

repository·main·Indexed 18 days ago

https://github.com/phospho-app/phosphobot

A comprehensive software platform for robotics research and deployment. It enables robot control, recording of teleoperation datasets, and training of Vision Language Action (VLA) models. The platform includes a React-based dashboard, a LeRobot Dataset Viewer for private datasets, and a variety of control examples including absolute/relative movement, keyboard control, and offline voice commands using CMUSphinx.

Tokens
51.1K
Snippets
181
Records
240
Agent score
64%

What's inside phosphobot

  1. Overview of Modal application structure

    main

    The Modal directory contains several distinct model images and services:

    • admin: A FastAPI server used by phosphobot to manage GPUs and models. It exposes endpoints via fastapi_app.
    • gr00t: The gr00t-n1 model image. Includes spawn (to launch the inference server over a tunnel) and train (to train a gr00t model).
    • act: The ACT model image. Includes a train function.
    • paligemma: The paligemma model image. Includes warmup_model (to load the model) and detect_object (to perform object detection).
  2. Architecture for adding new LeRobot policy models

    main

    Adding support for a new LeRobot policy model in phosphobot requires a multi-layer implementation across the backend, frontend, and CI/CD.

    Backend Layers

    • Core Action Model Layer (phosphobot/am/): Defines client-side model interfaces, control logic, validators, and spawn configurations.
    • Modal Infrastructure Layer (modal/lerobot_modal/): Handles server-side inference and training infrastructure on Modal.
    • Phospho Dashboard Endpoints: Provides the API endpoints for AI Control and AI Training.

    Frontend Layers

    • Phospho Dashboard (dashboard/src): UI components and state management for controlling and training models.

    CI/CD

    • Deployment (.github/workflows): Automated deployment of policies to Modal upon commits to the main branch.
  3. How the Voice Command implementation works

    main

    The voice command system is built on the following architecture:

    • Speech Recognition: Uses CMUSphinx for offline speech recognition (no internet required).
    • Audio Capture: Records audio input only while the SPACEBAR is held down.
    • Command Logic: Processes voice input through simple keyword matching.
    • Execution: Triggers robot movements by executing pre-recorded movement patterns stored as JSON files.
  4. Understand the Relative Square Movement Logic

    main

    The square_relative.py script follows a specific operational lifecycle to execute the pattern:

    1. Initialization: Calls the API's /move/init endpoint to prepare the robot.
    2. Positioning: Moves the robot to the starting position (top left corner of the square).
    3. Pattern Execution: Executes a 3cm x 3cm square pattern by performing a sequence of relative moves:
      • Move to top right
      • Move to bottom right
      • Move to bottom left
      • Move back to top left
    4. Iteration: Repeats the sequence for the amount specified by NUMBER_OF_SQUARES.
  5. Understand the Kinematics Coordinate Transformation

    main

    The system transforms coordinates through several frames to move the robot accurately:

    1. Pixel to 3D Camera Coordinates: Converts 2D pixel coordinates and depth into 3D space relative to the camera. pos_3d = pixel_to_3d_position(u, v, depth, camera_matrix)

    2. Camera to ArUco Marker Coordinates: Translates camera-space coordinates to the local frame of the ArUco marker. marker_coords = pixel_to_marker_coordinates(rgb_x, rgb_y)

    3. ArUco to Robot Coordinates: Maps the marker's local frame to the robot's coordinate system. robot_coords = convert_to_robot_frame(marker_coords)

    ArUco Marker Frame Reference:

    • Origin: Top-left corner of the marker.
    • +X: Rightward along the top edge.
    • +Y: Downward along the left edge.
    • +Z: Out of the marker plane toward the camera.

    Robot Frame Mapping Logic:

    • robot_x = -aruco_y
    • robot_y = -aruco_x
    • robot_z = -aruco_z - 0.13 (includes a 13cm offset)
  6. Quickstart: Control AI robots with phosphobot

    main

    phospho (or phosphobot) is a software suite designed to control robots, record datasets, and train/use Vision Language Action (VLA) models.

    Core Workflow:

    1. Hardware Setup: Use a phospho starter pack or supported robots (SO-101, SO-100, Unitree Go2, AgileX Piper, etc.).
    2. Installation: Install the phosphobot server using the OS-specific one-liners available at docs.phospho.ai/installation.
    3. Teleoperation: Access the webapp at localhost:80 (or localhost:8020 if port 80 is occupied) to control the robot via keyboard, gamepad, leader arm, or Meta Quest.
    4. Data Collection: Record a dataset (e.g., 50 episodes) of the desired task.
    5. Training: Train an action model (ACT, smolVLA, π0.5, or gr00t-n1.5) via the webapp or locally.
    6. Inference: Deploy the trained model from HuggingFace to control the robot via the webapp or the phosphobot Python package.
  7. Run the Wave Back Example

    main

    The Wave Back example demonstrates a robot that performs a waving motion when a hand is detected via a webcam using MediaPipe.

    Prerequisites

    • Python 3.6+
    • A robot running the PhosphoBot server
    • A connected webcam or camera

    Setup Steps

    1. Ensure the robot is powered on and the PhosphoBot server is running.
    2. Connect your webcam.
    3. Install required dependencies:
      pip install -r requirements.txt
    4. Grant camera access permissions to the application.

    Execution

    Run the script using Python:

    python wave_hand.py

    Once running, a camera feed window will appear. Showing your hand to the camera will trigger the robot to wave. The robot will respect a cooldown period before waving again. Press Ctrl+C in the terminal to exit.

  8. Deploy the dashboard to the phosphobot server

    main
    The dashboard files are intended to be served by the phosphobot server. After transpiling the React application to HTML and CSS, the resulting files should be copied to the ../phosphobot/resources/dist directory to be served correctly.
  9. Run the PhosphoBot Keyboard Control Example

    main

    This example allows you to control a robot via keyboard inputs. To use it, you must have a robot running the PhosphoBot server and the necessary Python environment set up.

    Setup Steps

    1. Ensure your robot is powered on and the PhosphoBot server is active.
    2. Install the required dependencies:
      pip install -r requirements.txt
    3. Execute the control script:
      python crane.py
    4. When prompted, select your position relative to the robot: Behind or Facing.
    pip install -r requirements.txt
    python crane.py
  10. Implement a Core Action Model class

    main

    To add a new policy to the backend, create a new file phosphobot/am/your_policy.py. You must implement two main components:

    1. Config Validators: Define dataclasses inheriting from HuggingFaceModelValidator, HuggingFaceAugmentedValidator, and LeRobotSpawnConfig to validate model configurations and spawn settings.
    2. Policy Class: Create a class inheriting from LeRobot. This class must implement class methods to return your specific validator and spawn config classes, and an _prepare_model_inputs method to handle model-specific preprocessing (e.g., adding prompts for SmolVLA or detection instructions for ACT).

    Example implementation structure:

    class YourPolicyHuggingFaceModelValidator(HuggingFaceModelValidator):
        type: Literal["model_type"]
    
    class YourPolicyHuggingFaceAugmentedValidator(HuggingFaceAugmentedValidator):
        type: Literal["model_type"]
    
    class YourPolicySpawnConfig(LeRobotSpawnConfig):
        hf_model_config: YourPolicyHuggingFaceAugmentedValidator  # type: ignore[assignment]
    
    class YourPolicy(LeRobot):
        @classmethod
        def _get_model_validator_class(cls) -> type:
            return YourPolicyHuggingFaceModelValidator
    
        @classmethod
        def _get_augmented_validator_class(cls) -> type:
            return YourPolicyHuggingFaceAugmentedValidator
    
        @classmethod
        def _get_spawn_config_class(cls) -> type:
            return YourPolicySpawnConfig
    
        def _prepare_model_inputs(self, config, state, image_inputs) -> Dict[str, np.ndarray | str]:
            inputs: Dict[str, np.ndarray | str] = {
                config.input_features.state_key: state,
                **image_inputs,
            }
            # Add model-specific input processing here (e.g., prompts or custom preprocessing)
            return inputs
  11. Run the Move in Circles Example

    main

    This example demonstrates how to use the PhosphoBot API to command a robot to move in circular patterns using absolute position commands.

    Prerequisites

    • Python 3.6+
    • A robot running the PhosphoBot server

    Setup and Execution

    1. Install dependencies:
      pip install -r requirements.txt
    2. Configure the PI_IP and PI_PORT in circles_absolute.py to match your robot's API server.
    3. Execute the script:
      python circles_absolute.py
    pip install -r requirements.txt
    python circles_absolute.py
  12. Access the Web Dashboard and Control Panel

    main

    Once the phosphobot server is running, you can access the interactive control panel via your web browser. By default, the server is available at http://localhost:80.

    Through the dashboard, you can:

    • Teleoperate: Control your robot using a keyboard, leader arm, or Meta Quest.
    • Record: Capture demonstration datasets (approximately 40 episodes are recommended).
    • Train & Deploy: Manage action model training and deployment directly from the UI.
    http://<YOUR_SERVER_ADDRESS>:<PORT>/