RoboAPI

Version 0.3.0 renames the Python package, CLI and import to roboapi. Use a new environment and configuration; existing robomcp releases are different artifacts.

Test and run robot policies on UR and Franka through a browser or an MCP agent.

RoboAPI connects a single arm, a Robotiq parallel gripper and a wrist fisheye camera to a session-based model API. It collects observations, requests action chunks and executes them with the same Cartesian semantics across robots.

The source archive on PyPI includes complete installation, calibration and model API guides in docs/: select Download files on the PyPI project page, download the .tar.gz archive, and extract it. The GitHub repository is currently private.

Requirements

• Robot: UR5 (CB3), UR5e, UR7e, Franka FR3 or Panda with system software 4.2.1–4.x.
• Camera: wrist-mounted fisheye RGB, using V4L2 with MJPG at 1280×720 and 30 FPS. Mounting must match the model's training viewpoint.
• Host: Linux x86-64 and CPython 3.10–3.12; new installations use 3.12 with uv.
• Model service: a Base URL, model ID and API key for the model API contract.

The release wheel includes the web interface. UR e-Series requires a separately built control runtime from sources included in the wheel. Franka uses a compatible SDK and requires a realtime host.

Get started

1. Install system libraries and create a Python environment on the robot host:

   sudo apt-get update
   sudo apt-get install -y libgl1 libglib2.0-0
   mkdir -p ~/roboapi && cd ~/roboapi
   uv venv --python 3.12
   . .venv/bin/activate
   

   Install the matching package for the robot and gripper:

   Robot	Command
   UR CB3	uv pip install 'roboapi[ur-cb3,gripper]'
   UR e-Series	uv pip install 'roboapi[gripper]'
   Franka FR3, system 5.9+	uv pip install 'roboapi[franka,gripper]'
   Franka FR3, system 5.6.0	uv pip install 'roboapi[franka56,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/
   Franka Panda, system 4.2.1–4.x	uv pip install 'roboapi[panda,gripper]' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/

   UR e-Series additionally needs its native runtime built on the host:

   sudo apt-get install -y build-essential cmake
   python -m roboapi.hardware.ur.build --build-dir build/ur-native --install-dir "$VIRTUAL_ENV"
   

   For Franka, configure the realtime kernel and permissions, connect to the control cabinet's Shop Floor interface and enable FCI. FR3 5.6 and Panda require a one-time import of the standard load and flange TCP in Desk: run roboapi export-franka-tool --output endeffector-config.json and follow the Franka installation guide in the source archive. The physical tool must match that preset.

   Use the video and dialout groups as appropriate for the camera and serial gripper. On UR, configure the flange-centre TCP and physical load in PolyScope.

2. Run the setup wizard on the robot host:

   roboapi init
   

   Have the robot address, camera device and model credentials ready. The wizard selects the gripper connection and saves the local configuration; Franka also needs Desk credentials.

3. Start the browser interface:

   roboapi http
   

   Open localhost:8080. Camera preview starts automatically, with read-only arm feedback when available. Franka preview uses Desk; startup leaves its brakes and operating mode unchanged. For a remote robot host, forward its port 8080 over SSH, then open the local forwarded address.

4. Open Settings → Devices → Calibrate. Teach Home and three points on a level surface. After the last point, RoboAPI returns Home, saves the calibration and initializes the arm and gripper. Try the optional direction checks, or choose Done to return to the run view. UR uses PolyScope teaching; Franka uses the arm's native guiding buttons, with one selectable translation axis and rotation held after capturing Home.

5. Enter an Instruction and choose Start. Check the camera and current state; use Logs for errors. The send arrow becomes Robot Stop, and Home returns to the calibrated pose.

Actions run at 30 Hz. Between chunks, RoboAPI waits 0.5 seconds by default before capturing the next observation. Open the current model at the input’s right to go to Settings → Model & runtime and change its connection or Chunk wait (s) while stopped. Choose English or Chinese in Settings → General.

Shift+Enter sends; Enter inserts a newline. Up/Down recalls past instructions without sending. Sending a new draft during a web run interrupts its current action chunk and starts a new task once the stop completes.

Settings → Devices → Motion range sets each axis's negative and positive distances from Home in centimetres. It starts enabled at Home ±0.60 m on each axis. Out-of-range position targets stop at the box boundary without ending the task; this does not constrain external forces or the whole arm. If the robot is already outside, use Home to return smoothly before starting another motion. Installation calibration is unrestricted, and saving limits never moves the robot. Runs continue until stopped or interrupted by a fault. Ctrl+C shuts down the service.

The task cards above the camera retain past instructions. After stopping, send with an empty input to continue the current task, or enter a different instruction to start a new one. Each task has a thumbs-up/down rating, an optional note and one camera recording. Continuing a task appends to its recording and skips the stopped waiting time. Open a task to review or download its video, edit feedback or delete it; selecting an old instruction only fills the input until you explicitly send it.

Recording starts automatically with each run and can be disabled for subsequent runs in Settings → Recording & storage. Videos contain the full camera view, independent of browser panning or cropping. Tasks and feedback remain on the robot host until manually deleted; ratings are not sent to the model service.

Settings can be inspected during a run, with the current state and Robot Stop kept in the section heading. Returning preserves the instruction draft, camera view and expanded history. Storage management shows task and video usage on the robot host. Clear selected or all recordings while keeping instructions and feedback, or delete whole tasks after confirmation. Active tasks and recordings still being saved are skipped. Device shortcuts remain in the main header. Logs opens a floating panel with a text filter; the camera and instruction controls remain in place and stay usable.

Connect an agent

Choose one startup mode for an installation:

Each command starts its own runtime and device connections. Stop the existing service before switching modes. To add a network agent to a browser session, restart with --with-mcp. See docs/installation.md in the source archive for stdio and remote MCP client configuration.

The browser and agent share devices and settings. Stop the run before switching interfaces.

Documentation

CI checks Python 3.10–3.12, frontend tests, hardware SDK imports and the installed web package, and builds and tests the UR control runtime. Physical robot operation requires separate verification; see the validation section of docs/development.md.

License

Copyright 2026 PokeBot. Project code is licensed under Apache-2.0. Bundled third-party components retain their respective licenses; see NOTICE in the source archive.