OpenRobo

Open-source robotics platform for discovering components, reasoning about compatibility, building robot stacks, verifying builds, and inspecting runtime connections.

---

What is OpenRobo?

Robotics software engineering is fragmented across hundreds of isolated repositories, disparate ROS packages, custom sensor drivers, and fragile dependency chains. Integrating a robot stack — from LiDAR SLAM and arm kinematics to hardware interfaces and simulation — often requires hours of manual dependency debugging.

OpenRobo provides a standardized, vendor-neutral software registry, intelligent compatibility engine, stack builder, automated workspace synthesis, and runtime verification platform for modern robotics:

• Discover Components: Search thousands of ROS 2 packages, hardware drivers, simulation models, and algorithms with weighted full-text and fuzzy typo-tolerant indexing.

• Understand Compatibility: Graph-based constraint validation mapping cross-package compatibility across ROS distributions, CPU architectures, and OS kernels.

• Build Robot Stacks: Compose modular robotics architectures with interactive dependency checking and one-click conflict resolution (/stack-builder).

• Generate Workspaces: Synthesize deterministic, reproducible Colcon workspaces, REP-149 bringup meta-packages, AST-validated launch scripts, multi-stage Dockerfiles, Dev Containers, and lockfiles (openrobo.lock.json).

• Verify Builds & Introspect Runtimes: Execute controlled colcon/container builds, compare planned stack intent against observed live ROS 2 graphs, evaluate QoS compatibility, integrate optional Connection Inspector diagnostics, and inspect telemetry (/runtime).

---

Implemented Features (Available Now)

• Canonical Robotics Schemas: JSON Schema (Draft 2020-12) standards for resource manifests (resource.schema.json), compatibility graphs (graph.schema.json), and robot stacks (stack.schema.json).

• Knowledge Graph & Compatibility Intelligence: Deterministic reasoning layer evaluating ROS 2 distributions (Humble, Jazzy, Iron, Rolling), OS, CPU architecture (x86_64, aarch64), SemVer constraints, required hardware/capabilities, cycle detection, and conflict propagation with sub-50ms matrix performance.

• Zero-Extra-Infrastructure Search Engine: PostgreSQL-backed weighted full-text search (tsvector, GIN indexes) with pg_trgm fuzzy similarity matching and multi-taxonomy faceting.

• Interactive Robotics Stack Builder: Visual 3-panel stack composition studio (/stack-builder) with real-time constraint evaluation, starter templates, dependency auto-resolution proposals, and manifest import/export.

• Hardened Workspace & Deployment Generator: Synthesizes strictly-typed, statically-validated ROS 2 colcon workspaces, launch pipelines, parameter configurations, least-privilege Dockerfiles, Docker Compose definitions, VS Code Dev Containers, setup scripts, and byte-reproducible ZIP bundles.

• Strict Generator Evidence & Safety Model: Enforces "NO EVIDENCE → NO INVENTED CONFIGURATION". Components distinguish VERIFIED_ADAPTER, USER_CONFIGURED, METADATA_DRIVEN, and GENERIC_SCAFFOLD (scaffolding .example templates with explicit required manual configuration steps).

• Reproducible Lockfiles & Provenance: Generates cryptographic lockfiles (openrobo.lock.json) capturing component digests, repository URLs, build types, upstream licenses, evidence levels, and workspace readiness states.

• Controlled Build Verification Runner (Milestone 6): Pluggable execution engine (openrobo_runtime) supporting Docker, Podman, and Local OS providers with timeouts, working-directory constraints, environment allowlists, and exit code capture to transition workspaces from STATICALLY_VALIDATED to BUILD_VERIFIED.

• Native ROS Graph & QoS Introspection (Milestone 6): Machine-readable comparison of planned stack intent against observed running nodes and topics, detecting orphaned publishers/subscribers, type mismatches, and QoS incompatibilities (Reliability, Durability).

• Optional Connection Inspector Integration (Milestone 6): External tool adapter safely detecting installed connection_inspector ROS 2 packages (inspect_cli, GUI) via process boundary while strictly isolating GPL-3.0 upstream code from OpenRobo's Apache-2.0 core.

• Robotics Simulation Adapters (Milestone 6): Unified simulation interface (SimulationAdapter) with environment detection for Gazebo (Harmonic/Fortress), Webots, and MuJoCo.

• Rosbag2 Telemetry Foundation (Milestone 6): Metadata and topic message count introspection for SQLite3 rosbag datasets.

• Runtime Studio Web UI (/runtime) (Milestone 6 & 6.1): Interactive robotics dashboard visualizing execution provider states, simulator readiness, ROS 2 computational graph connections, node health, QoS diagnostics, explicit Demo Mode toggle, and real backend API streaming.

• Live Runtime Wiring & Truthful Verification (Milestone 6.1): Guarded ROS 2 graph collector (rclpy & CLI fallback), RuntimeContract explicit verification, TYPE_MISMATCH detection, LocalProcessProvider environment allowlist, and path traversal containment.

• Edge Agent & Fleet Studio (Milestone 7.1): Cryptographic device PKI, genuine mTLS transport, single-use enrollment tokens, replay protection, and real-time fleet health dashboard (/fleet).

• Signed Releases & Local A/B Foundation (Milestone 7.2.1 / 7.2.1.1): Deterministic .tar.gz releases with Ed25519 detached signatures, agent-owned local TrustedReleaseKeyStore, link-free safe extraction sandbox, crash-consistent activation.intent.json journal, and cryptographic rollback re-verification.

• Unified CLI: Typer/Rich command-line suite for schema validation, static GitHub ingestion, ranked registry search, workspace generation (openrobo workspace), and runtime verification (openrobo runtime).

• Cross-Platform Compatibility: Full first-class support for Linux, macOS, and Windows development workflows.

---

Architecture

OpenRobo is structured as a zero-extra-infrastructure monorepo managed with pnpm and Python virtual environments:

OpenRobo/
├── schemas/                      # Canonical JSON Schema v2020-12 Definitions
│   ├── resource.schema.json      # Component metadata & platform matrix schema
│   ├── graph.schema.json         # Compatibility & dependency edge schema
│   └── stack.schema.json         # Complete robot stack assembly schema
├── packages/
│   ├── schemas/                  # Python schema validation library (openrobo-schemas)
│   ├── compat-engine/            # Compatibility reasoning & graph engine (openrobo-compat)
│   ├── workspace-gen/            # Hardened ROS 2 workspace generator (openrobo-workspace)
│   ├── runtime-core/             # Runtime execution & build verification engine (openrobo-runtime)
│   ├── release-core/             # Release packager, Ed25519 signer & safe extractor (openrobo-release)
│   ├── agent-core/               # Cryptographic edge agent, mTLS & A/B slot manager (openrobo-agent)
│   └── cli/                      # Typer/Rich unified CLI application (openrobo)
├── apps/
│   ├── api/                      # FastAPI async REST API service
│   └── web/                      # Next.js 14 App Router interactive web frontend
├── scripts/                      # Schema validators & seed database scripts
└── docs/                         # Architecture Decision Records & Milestone Plans

---

Quickstart & Local Setup

Prerequisites

• Node.js: v20.x or v24.x (CI uses Node 24)

• pnpm: v12.4.2+ (corepack enable pnpm)

• Python: 3.10, 3.11, or 3.12

• PostgreSQL: 14+ (with pg_trgm extension) or in-memory SQLite for testing

1. Clone & Install Dependencies

git clone https://github.com/Tanishk756/OpenRobo.git

cd OpenRobo

# Install Node & Frontend dependencies

pnpm install

# Setup Python Virtual Environment & CLI

python -m venv .venv

source .venv/bin/activate    # On Windows: .venv\Scripts\Activate.ps1

pip install -e "packages/schemas" -e "packages/compat-engine" -e "packages/workspace-gen" -e "packages/runtime-core" -e "packages/release-core" -e "packages/agent-core" -e "packages/cli" -e "apps/api"

2. Verify Repository Baseline

pnpm run check

---

Third-Party Integrations & Licensing Boundaries

OpenRobo is licensed under the Apache License 2.0.

When interfacing with external third-party robotics diagnostic tools licensed under copyleft terms (such as connection_inspector, which is GPL-3.0-only), OpenRobo enforces a strict process-level boundary:

• OpenRobo does not vendor, embed, or redistribute GPL source code.

• OpenRobo communicates with external tools solely via external process execution and CLI interfaces.

• For complete details, see THIRD_PARTY_NOTICES.md.

---

License & Maintainer

OpenRobo is open-source software licensed under the Apache License 2.0.

Owner & Maintainer: Tanishk Singhal