RoboPilot

English | 中文

RoboPilot is a no-ROS-required static engineering toolchain for ROS-style projects and ROS1-to-ROS2 migration scaffolds.

It helps robotics learners and developers plan, refine, validate, generate, inspect, update, roll back, document, and review ROS/ROS2-style project structure without installing ROS, ROS2, catkin, colcon, simulator runtimes, or robot hardware.

What RoboPilot Does

• Creates and validates ProjectSpec files from robotics tasks.
• Renders deterministic ROS-style Python package skeletons.
• Refines and diffs specs before generation.
• Previews, exports, applies, backs up, rolls back, and journals safe project updates.
• Inspects projects and exports read-only reports.
• Detects RoboPilot, ROS1, ROS2, mixed, non-ROS, and unknown project types.
• Statically inspects ROS1 catkin and ROS2 ament packages.
• Analyzes declared and detected dependencies.
• Builds static ROS1-to-ROS2 migration plans, validates/diffs them, previews file-level migration work, generates conservative ROS2 scaffold placeholders, validates generated scaffolds, and exports scaffold reports.
• Provides small offline utilities for robotics error logs and Mermaid workflow graphs.
• Optionally uses an LLM only to produce or refine validated ProjectSpec data.
• Provides a lightweight Python API layer for scripts and future integrations.
• Documents stable top-level JSON keys for integration-oriented --json outputs.
• Provides a VSCode Marketplace extension that wraps RoboPilot CLI JSON outputs, including the migration scaffold review workflow.

RoboPilot does not run ROS, ROS2, launch files, generated code, catkin_make, or colcon. Migration scaffolds are conservative review artifacts, not full automatic migrations; manual review is still required.

Quick Start

Supported Python versions for this release line are Python 3.10 and 3.11. Package metadata declares >=3.10,<3.12; Python 3.12 and 3.13 are not claimed until the test suite passes there.

Install from PyPI:

pip install robopilot
robopilot --help

Install the VSCode extension from Visual Studio Marketplace:

code --install-extension j1angjj.robopilot-vscode

Source install is for development:

python -m venv .venv
.venv\Scripts\activate
python -m pip install -U pip
pip install -e ".[dev]"

On Windows, if pytest has temporary directory permission issues:

python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider

Core Workflows

Spec-first generation:

robopilot plan --name demo_detector --task "Create an object detection pipeline" --output robopilot.yaml
robopilot validate --spec robopilot.yaml
robopilot generate --spec robopilot.yaml

Iterative spec review:

robopilot refine --spec robopilot.yaml --instruction "Add a tracker node after the detector" --output refined.yaml
robopilot diff --old robopilot.yaml --new refined.yaml

Safe project update loop:

robopilot apply-preview --spec refined.yaml --project outputs/demo_detector
robopilot apply-plan --spec refined.yaml --project outputs/demo_detector --output apply_plan.yaml
robopilot apply --plan apply_plan.yaml
robopilot apply --plan apply_plan.yaml --confirm
robopilot history --project outputs/demo_detector

Static project review:

robopilot inspect examples/generated_projects/demo_detector
robopilot repair-suggest examples/generated_projects/demo_detector
robopilot report examples/generated_projects/demo_detector --output report.md

ROS-style static analysis:

robopilot detect path/to/project
robopilot inspect-ros1 path/to/ros1_package
robopilot inspect-ros2 path/to/ros2_package
robopilot deps path/to/project

ROS1 to ROS2 migration planning:

robopilot migrate-plan --from path/to/ros1_package --to ros2 --output migration_plan.yaml
robopilot migrate-plan-validate --plan migration_plan.yaml
robopilot migrate-preview --plan migration_plan.yaml --project path/to/ros1_package
robopilot migrate-scaffold-preview --plan migration_plan.yaml
robopilot migrate-scaffold --plan migration_plan.yaml --output path/to/ros2_scaffold
robopilot migrate-scaffold-validate --plan migration_plan.yaml --scaffold path/to/ros2_scaffold
robopilot migrate-scaffold-report --plan migration_plan.yaml --scaffold path/to/ros2_scaffold --output scaffold_report.md

Documentation

• Chinese Documentation
• Command Reference
• Workflows
• Architecture
• Python API
• JSON Contracts
• Integration Notes
• VSCode Extension
• VSCode Packaging
• VSCode Marketplace Publishing
• ROS1 to ROS2 Migration Tutorial
• VSCode Migration Tutorial
• Demo Walkthrough
• Troubleshooting
• Examples
• Developer Setup
• Testing
• Release Process
• PyPI Publishing
• Compatibility
• Known Limitations
• Stability Policy
• Demo Script
• Changelog
• Roadmap
• 2.x Research Planning

Safety Model

RoboPilot is designed around static analysis and explicit review:

• Default planning, validation, diff, inspection, report, detection, dependency, and migration commands are read-only.
• apply is dry-run by default and writes only with --confirm.
• Confirmed updates write only files listed in a validated apply plan.
• Existing files are backed up before updates.
• rollback is dry-run by default and restores only files from RoboPilot backup directories.
• Migration planning, validation, diff, and preview do not modify source projects.
• Migration scaffold generation writes only to the explicit output directory, refuses overwrites by default, and does not modify the original ROS1 project.
• Migration scaffold validation is read-only and checks generated placeholders without executing or importing scaffold code.
• Migration scaffold reports are read-only unless writing to an explicit report output file.
• Optional LLM paths are limited to ProjectSpec planning/refinement and must pass validation before generation or apply workflows.

Example Output

A static generated demo project is committed at:

examples/generated_projects/demo_detector/

Migration tutorial examples are committed at:

examples/ros1_migration_demo/
examples/ros2_scaffold_demo/
examples/migration_outputs/

Start with the ROS1-to-ROS2 migration tutorial, the VSCode migration tutorial, or the demo walkthrough.

Transient generated projects should go under outputs/, which is intentionally ignored by git.

Project Status

Current stable release: v2.0.1.

RoboPilot v2.0.x is the stable stage-completion release line for the current no-ROS-required static ROS engineering workflow. v2.0.1 is a post-v2.0 public polish patch, not a breaking rewrite.

RoboPilot's no-ROS-required static engineering workflow is the stable v2.0.x baseline:

plan -> refine -> diff -> validate -> generate
      -> apply-preview -> apply-plan -> apply -> rollback -> history
      -> inspect -> repair-suggest -> report
      -> detect -> inspect-ros1 -> inspect-ros2 -> deps
      -> migrate-plan -> migrate-plan-validate -> migrate-plan-diff -> migrate-preview
      -> migrate-scaffold-preview -> migrate-scaffold -> migrate-scaffold-validate
      -> migrate-scaffold-report

The Python API layer, documented CLI JSON contracts, ROS2 static inspector, enhanced dependency analyzer, and VSCode extension source are available for integration work while the CLI remains the primary user interface. The no-ROS-required safety model is unchanged in this stable release.

The VSCode extension is available from Visual Studio Marketplace as j1angjj.robopilot-vscode, and the source lives under vscode-extension/. The extension requires the RoboPilot CLI to be installed, supports the migration scaffold workflow, and remains a thin wrapper over CLI/API/JSON contracts.

pip install robopilot
code --install-extension j1angjj.robopilot-vscode

See docs/vscode_extension.md, docs/vscode_packaging.md, and docs/vscode_marketplace.md.

The Python package version is 2.0.1; the human-facing tag and release name should be v2.0.1. The VSCode extension is versioned separately and remains available as j1angjj.robopilot-vscode.

Development

Run tests:

python -m pytest

Windows fallback:

python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider

License

MIT