roboapi 0.4.2__tar.gz

roboapi-0.4.2/.python-version

@@ -0,0 +1 @@
+3.12

roboapi-0.4.2/DESIGN.md

@@ -0,0 +1,175 @@
+# RoboAPI design
+
+## Purpose
+
+RoboAPI tests and runs the specified model API contract across robot embodiments. It applies
+the same model semantics to different robots in a simple, correct way and provides MCP tools
+for interaction with an agent.
+
+## System boundary
+
+The core loop collects observations, requests actions through the specified model API, validates
+and executes those actions, and reports execution results. RoboAPI owns embodiment integration
+and runtime control.
+
+The model service produces actions. An external agent organizes tasks and controls the runtime
+through MCP.
+
+The browser provides interactive model API testing. Browser and MCP operations share the
+same runtime; a policy run accepts task updates only from its starting interface until it
+stops. A local stop can interrupt either interface.
+The HTTP interface can run independently, with MCP optionally sharing the same runtime.
+
+[Simplified Chinese design documentation](docs/zh-CN/DESIGN.md) is available separately.
+
+## Supported setup
+
+The supported setup is one robot arm, one single-degree-of-freedom parallel gripper, and one
+wrist-mounted fisheye RGB camera. New embodiments conform to this setup and the shared model
+semantics. The wrist camera uses the standard mounting arrangement that matches the training
+viewpoint.
+
+Cameras share one V4L2 implementation with a fixed capture mode: MJPG at 1280×720 and 30 FPS.
+The device must negotiate this mode or connection fails. Installation selects the device path.
+
+## Ownership
+
+| Responsibility | Scope |
+| --- | --- |
+| Operation interfaces | Accept commands and return status and results through MCP and other entry points |
+| Shared core | Handle the model API, the observation-and-action loop, and coordinate semantics |
+| Embodiment adapters | Handle device communication and physical control |
+
+New embodiments reuse the shared core rather than duplicating the loop. This is a division of
+responsibilities, not a requirement for new directories or abstraction layers.
+
+An embodiment combines an arm, a gripper and a camera and provides device access through the
+shared coordinate mapping. Model clients, the model loop and execution records belong to the
+shared runtime. Shared motion code handles Cartesian paths and 30 Hz dispatch for normal motion
+and calibration returns, with explicit coordinate boundaries. Device adapters own device-specific
+control, read-only feedback and initialization. Assembly selects components from standard hardware
+definitions and local connection data.
+
+## Web interface
+
+The browser is a small React and TypeScript client with a Run view and dialogs for setup and
+settings. The Python HTTP adapter exposes runtime operations and camera previews; model
+communication, sessions and robot control remain in the shared core.
+
+The interface extends the configured brand visual language: official Inter/MiSans typefaces and
+logo, pale blue borders, soft pink accents, capsule controls and translucent surfaces.
+English and Simplified Chinese can be switched in the header; only the language
+preference is stored in the browser. Font and asset provenance is in
+[frontend/BRAND.md](frontend/BRAND.md).
+
+The camera fills the Run view at its original aspect ratio, cropping excess edges.
+Dragging pans the view within the image bounds. View controls restore the center
+or show the complete frame; captions and input stay fixed. This uses one existing
+stream connection without changing camera capture or model input. Status and
+empty states distinguish connection loss, stale frames and hidden video. The
+current task is a centered caption with runtime and actual inference latency from
+the shared runtime. Additional run metrics and logs open in matching dialogs.
+
+A floating input sits below installation-local preset chips. Chips keep complete
+outlines, shorten edge text with ellipsis and browse one instruction per gesture
+without a scrollbar. The left + opens saved
+instructions and their add/edit/remove controls; selecting one fills the draft. The
+right model entry shows the current configured model and opens connection and run
+settings. The existing API key is never returned to the
+input; a blank key preserves it. Settings require an idle runtime.
+
+Sending starts a run and replaces the arrow with an animated Robot Stop control.
+The browser does not offer Pause, Resume or in-run instruction updates. Sending a new
+draft during a web run interrupts the current action chunk, waits for Stop to finish,
+then starts a new task. Shift+Enter sends; Enter inserts a newline. Up/Down recalls past
+instructions into the draft without sending. When the input is empty, an explicit start reuses the last instruction;
+nonempty draft text takes precedence. The idle input shows the last instruction as its
+placeholder. MCP-owned runs stay read-only in the browser, with local Stop available.
+The protocol's existing ownership, update and stop semantics remain unchanged.
+
+Devices opens connection controls and calibration. Calibration guides native teaching
+and axis selection in a shared dialog. After the final Home return is verified, the
+browser saves and enables control, then offers optional direction trials and a Done exit.
+On small screens the dialog scrolls with reachable actions.
+Beginning calibration exits control and switches to read-only sampling.
+
+Vite builds the frontend into the Python release package. Both ship as one version;
+deployment requires neither Node.js nor a separate frontend server.
+
+## Coordinates and data
+
+Model observations contain an RGB image and a state consisting of a Cartesian pose in the
+training frame and a normalized gripper value. Model actions specify absolute Cartesian pose
+targets and gripper targets in the same frame. Positions use metres. Gripper values range from
+zero (closed) to one (open).
+
+Image processing preserves the raw fisheye distortion, field of view, and image orientation.
+The pipeline is limited to RGB conversion, aspect-ratio-preserving resizing required by the
+model API, and encoding. Embodiment adapters do not crop, pad, mirror, rotate, or undistort the
+model image.
+
+Shared coordinate mapping and driver boundaries convert embodiment-specific representations and
+units. Internal poses use quaternion wxyz; the model API uses xyzw, with explicit conversion at
+the API boundary. MCP motion tools expose roll/pitch/yaw in degrees.
+
+Every supported embodiment and model uses the flange centre as its Cartesian control point,
+with no positional TCP offset. Training Home is fixed at xyz `[-0.13, -0.46, 0.49]` metres and
+quaternion wxyz `[0, 0, 1, 0]`.
+
+Training +Z is world up; +X/+Y lie in the horizontal plane, independent of robot base mounting.
+Installation calibration records a local Cartesian Home above a confirmed level reference surface,
+then surface points A, B and C. All samples keep Home orientation, gripper opening and one fixed
+tool contact point. The surface normal toward Home defines +Z. A→B projected onto that plane
+defines +X; right-handed +Y is derived from +Z × +X.
+
+One shared bidirectional mapping aligns Home position, Home orientation, and task directions with
+the training frame. Observations use this mapping; control targets use its inverse. Tool-axis
+convention changes keep the same physical control point. After C, one automatic return to Home
+and a fresh sample verify the return before saving.
+
+## Execution
+
+Each policy run owns one model session. Inference turns and execution feedback belong to
+that session, which closes when the run ends. The model service owns session history;
+RoboAPI retains only the current session ID, turn, lifecycle state and pending feedback.
+
+Each iteration collects an observation, requests model actions, and executes the complete
+returned action chunk in order. After the final action period ends and the configured wait
+elapses (0.5 seconds by default), the loop collects a fresh image and measured state for
+the next iteration. Runs have no automatic time limit; the user or external agent stops them.
+
+Model actions advance at a fixed 30 Hz across all supported embodiments. This action cadence
+is distinct from model inference timing and embodiment-specific control frequencies.
+
+Explicit interruptions and faults can interrupt execution. Completing an action chunk means
+its action periods have finished; it does not imply exact target tracking or task success.
+The external agent judges task outcomes from observations.
+
+All embodiments share a soft workspace box for flange-centre position targets in the training
+frame. It is enabled by default, extending 0.60 m in each direction from Home. Idle settings can
+change or disable the box; its bounds must contain Home. Out-of-range targets are projected onto
+the boundary before velocities are calculated, without stopping the task. Orientation and gripper
+commands are unchanged. The box limits commands, not measured motion or the volume of the arm:
+compliance, external forces and tracking error can still move the flange outside it.
+
+New motion from outside the box requires an explicit Home return, which follows the existing
+Cartesian path smoothly into the box. Installation teaching and its native-coordinate returns
+are unrestricted while the training-frame mapping is being established. Settings changes never
+move the robot.
+
+## Installation data
+
+Normal startup loads a local installation configuration. Device and model substitutes are
+confined to automated tests.
+
+Startup opens camera preview and read-only arm feedback independently. Later starts require
+explicitly enabling control with the saved calibration. Camera reconnection restores video;
+a device fault ends the current run and the user or agent explicitly starts another one.
+
+The first installation creates and saves the local calibration. Later starts validate and reuse
+the current calibration. Changes to the installation, Home, or task axes require recalibration,
+which replaces the current local result.
+
+Standard hardware presets are maintained and shipped with the code.
+Device addresses, identifiers, installation measurements and runtime output are local
+installation data and stay outside version control.

roboapi-0.4.2/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

roboapi-0.4.2/MANIFEST.in

@@ -0,0 +1,9 @@
+include frontend/package.json frontend/package-lock.json frontend/index.html frontend/tsconfig.json frontend/vite.config.ts
+recursive-include frontend/src *.ts *.tsx *.css *.svg *.png *.ttf *.woff2
+include frontend/src/assets/calibration/*.glb frontend/src/assets/calibration/README.md
+recursive-include frontend/public *.txt
+include frontend/BRAND.md frontend/asset-provenance.json
+include DESIGN.md
+recursive-include roboapi *.json
+include .python-version uv.lock
+recursive-include docs *.md

roboapi-0.4.2/NOTICE

@@ -0,0 +1,16 @@
+roboapi
+Copyright 2026 PokeBot
+
+Project code is licensed under the Apache License, Version 2.0.
+
+The bundled web interface includes React, React DOM, Scheduler, Three.js,
+meshoptimizer, the Vite module preload polyfill and the Rolldown runtime under
+the MIT License, Lucide icons under the ISC and MIT Licenses, and Inter under
+the SIL Open Font License, Version 1.1. It also uses the
+unmodified MiSans typefaces under Xiaomi's MiSans Font Intellectual Property
+License Agreement and the official Poke logo. The project code license does
+not grant rights to the Poke name, logo or other trademarks.
+
+Copyright notices, license texts and brand attribution are included in
+frontend/public/assets/*.txt in the source distribution, and in the installed
+package's license directory and web assets.

roboapi-0.4.2/PKG-INFO

@@ -0,0 +1,205 @@
+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.