Metadata-Version: 2.4
Name: roboapi
Version: 0.4.2
Summary: Run robot policies on UR and Franka through a browser or an MCP agent.
Author: PokeBot
License-Expression: Apache-2.0 AND MIT AND ISC AND OFL-1.1 AND LicenseRef-MiSans
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: POSIX :: Linux
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: frontend/public/assets/Bundler-LICENSE.txt
License-File: frontend/public/assets/Inter-OFL.txt
License-File: frontend/public/assets/Lucide-LICENSE.txt
License-File: frontend/public/assets/Meshoptimizer-LICENSE.txt
License-File: frontend/public/assets/PokeBrand-NOTICE.txt
License-File: frontend/public/assets/React-LICENSE.txt
License-File: frontend/public/assets/Three-LICENSE.txt
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pillow
Requires-Dist: opencv-python
Requires-Dist: imageio-ffmpeg
Requires-Dist: httpx
Requires-Dist: pyyaml
Requires-Dist: mcp
Requires-Dist: tyro<2,>=1.0.16
Provides-Extra: ur-cb3
Requires-Dist: ur_rtde; extra == "ur-cb3"
Provides-Extra: franka
Requires-Dist: franky-control<3,>=2.0; extra == "franka"
Requires-Dist: websockets>=15; extra == "franka"
Provides-Extra: franka56
Requires-Dist: franky-control==2.0.0+libfranka.0.13.3; extra == "franka56"
Requires-Dist: websockets>=15; extra == "franka56"
Provides-Extra: panda
Requires-Dist: franky-control==2.0.0+libfranka.0.9.2; extra == "panda"
Requires-Dist: websockets>=15; extra == "panda"
Provides-Extra: gripper
Requires-Dist: minimalmodbus; extra == "gripper"
Dynamic: license-file

# 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](https://docs.astral.sh/uv/getting-started/installation/).
- **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:

   ```sh
   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:

   ```sh
   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](https://frankarobotics.github.io/docs/doc/libfranka/docs/real_time_kernel.html),
   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:

   ```sh
   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:

   ```sh
   roboapi http
   ```

   Open [localhost:8080](http://127.0.0.1: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:

| Mode | Start with | Connect to |
| --- | --- | --- |
| Browser | `roboapi http` | `http://127.0.0.1:8080/` |
| Browser and network MCP | `roboapi http --with-mcp` | Browser on 8080; MCP at `http://127.0.0.1:8000/mcp` |
| Client-managed stdio MCP | Let the MCP client launch `roboapi serve` | stdio; browser also available on 8080 by default |

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

| Guide | Contents |
| --- | --- |
| `docs/installation.md` | Hardware preparation, native builds, connections, local files and upgrades |
| `docs/calibration.md` | Home, reference plane and shared task coordinates |
| `docs/model-api.md` | Sessions, observations, actions and execution feedback |
| `docs/development.md` | Source setup, tests, packaging and releases |
| `DESIGN.md` | Product scope and architecture |

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](https://www.apache.org/licenses/LICENSE-2.0).
Bundled third-party components retain their respective licenses; see `NOTICE` in the source archive.
