Metadata-Version: 2.4
Name: rosp-sdk
Version: 0.1.0
Summary: Robot Open Specification Protocol (ROSP) SDK — base classes, data models, and tools for building robot adapters
Project-URL: Homepage, https://github.com/FaultLine-labs/rosp
Project-URL: Documentation, https://github.com/FaultLine-labs/rosp/tree/main/docs/spec
Project-URL: Repository, https://github.com/FaultLine-labs/rosp
Project-URL: Issues, https://github.com/FaultLine-labs/rosp/issues
Project-URL: Changelog, https://github.com/FaultLine-labs/rosp/blob/main/CHANGELOG.md
Author-email: RoboSwarm <dev@roboswarm.io>
License: Apache-2.0
License-File: LICENSE
Keywords: fleet-management,protocol,robot-card,robotics,rosp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.20.0
Provides-Extra: cli
Requires-Dist: click>=8.1.0; extra == 'cli'
Requires-Dist: rich>=13.0.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: zenoh
Requires-Dist: eclipse-zenoh>=1.0.0; extra == 'zenoh'
Description-Content-Type: text/markdown

# ROSP — Robot Open Specification Protocol

[![PyPI version](https://img.shields.io/pypi/v/rosp-sdk.svg)](https://pypi.org/project/rosp-sdk/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

**The universal protocol for describing, discovering, and streaming data from any robot.**

ROSP solves the M x N integration problem in robotics. Instead of every platform building custom connectors for every robot type, each robot implements one ROSP adapter. Any ROSP-compatible platform can then work with any ROSP-described robot.

```
Before ROSP:  M platforms x N robot types = M*N custom integrations
With ROSP:    M platforms + N adapters     = M+N standardized connections
```

## Install

```bash
pip install rosp-sdk
```

With CLI tools:
```bash
pip install rosp-sdk[cli]
```

## Quick Start

```python
from rosp_sdk import RobotCard, validate_robot_card, score_completeness

# Describe your robot
card = RobotCard(
    rosp_version="0.1",
    id="urn:rosp:robot:robotis:turtlebot3:waffle-001",
    identity={"type": "mobile_robot", "manufacturer": "ROBOTIS", "model": "TurtleBot3 Waffle"},
    hardware={"weight_kg": 1.8, "max_velocity_mps": 0.26},
    sensors=[
        {"sensor_id": "lidar", "type": "lidar", "model": "LDS-01"},
        {"sensor_id": "imu", "type": "imu", "model": "ICM-20948"},
        {"sensor_id": "camera", "type": "camera_rgb", "model": "RealSense R200"},
    ],
    actuators=[
        {"actuator_id": "base", "type": "wheel", "max_velocity": 0.26},
    ],
    capabilities=[
        {"capability_id": "cap:nav", "name": "Navigation", "type": "navigation"},
    ],
    integration={"supported_protocols": [{"protocol": "ros2", "version": "humble"}]},
)

# Validate against the ROSP schema
errors = validate_robot_card(card)
print(f"Valid: {len(errors) == 0}")  # Valid: True

# Score completeness
score = score_completeness(card)
print(f"Completeness: {score.level} ({score.percent}%)")  # Completeness: standard (72%)
```

## CLI

```bash
# Validate a Robot Card JSON file
rosp validate robot-card.json

# Inspect card details (sensors, actuators, capabilities)
rosp inspect robot-card.json

# Export card in different formats
rosp export-card robot-card.json --format summary

# Check SDK and spec version
rosp version
```

## Build an Adapter

ROSP adapters bridge a specific robot platform to the protocol. Implement 5 methods:

```python
from rosp_sdk import ROSPAdapter, RobotCard, StreamMessage, HealthStatus

class MyRobotAdapter(ROSPAdapter):
    async def connect(self) -> None:
        """Connect to the robot."""

    async def disconnect(self) -> None:
        """Disconnect from the robot."""

    async def describe(self, depth="full") -> RobotCard:
        """Return a Robot Card describing this robot."""

    async def stream(self, topics, qos=None) -> AsyncIterator[StreamMessage]:
        """Stream sensor data from the robot."""

    async def discover(self) -> DiscoveryInfo:
        """Return discovery information for this robot."""

    async def health_check(self) -> HealthStatus:
        """Check adapter and robot health."""
```

Register in `pyproject.toml`:
```toml
[project.entry-points."rosp.adapters"]
myrobot = "my_adapter:MyRobotAdapter"
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [Adapter SDK Guide](docs/spec/ROSP-v0.1-adapter-sdk.md) for the full guide.

## Official Adapters

| Adapter | Robots | Install |
|---------|--------|---------|
| [ROS2](adapters/ros2/) | Any ROS2 robot (TurtleBot, UR, ABB, etc.) | `pip install rosp-adapter-ros2` |
| [gRPC](adapters/grpc/) | Boston Dynamics Spot, Viam, custom gRPC | `pip install rosp-adapter-grpc` |
| [VDA 5050](adapters/vda5050/) | Any VDA 5050 MQTT AGV (MiR, KUKA, Jungheinrich) | `pip install rosp-adapter-vda5050` |

## How It Works

ROSP defines three core operations:

| Operation | What it does | Think of it as... |
|-----------|-------------|-------------------|
| **describe** | Returns a Robot Card — complete description of what the robot IS and CAN DO | USB device descriptor |
| **stream** | Streams sensor data in real-time with configurable QoS | ROS2 topics, but protocol-agnostic |
| **discover** | Announces robot availability on the network | mDNS / SSDP for robots |

Plus two **DRAFT** operations for future versions:
- **command** — Send commands to robots (navigate, pick, etc.)
- **coordinate** — Multi-robot coordination

## The Robot Card

The Robot Card is the core data structure — a complete, machine-readable description of a robot:

```
Robot Card
├── identity (manufacturer, model, type, firmware)
├── hardware (weight, dimensions, DOF, battery)
├── sensors[] (LiDAR, cameras, IMUs — with SOSA/SSN metadata)
├── actuators[] (drives, arms, grippers — with limits)
├── capabilities[] (navigation, manipulation, mapping)
├── integration (how to connect: ROS2, gRPC, MQTT, etc.)
├── safety (e-stop, zones, collision limits)
├── skills[] (DRAFT — high-level abilities)
└── ... (calibration, coordinate frames, simulation, diagnostics)
```

Progressive enrichment: start with 3 required fields (`rosp_version`, `id`, `identity.type`), add more as needed. The completeness scorer tells you what to add next.

## ROSP vs Existing Standards

| | ROSP | URDF/SDF | VDA 5050 | ROS2 msg | W3C WoT |
|---|---|---|---|---|---|
| **Scope** | Full robot description + streaming | Geometry only | AGV orders only | Message format only | IoT devices |
| **Robot types** | Any (mobile, arm, sensor, AGV) | Any (geometry) | AGVs only | Any (ROS2) | IoT devices |
| **Transport** | Any (gRPC, MQTT, WebSocket, Zenoh) | File | MQTT | DDS | HTTP |
| **Discovery** | Built-in | No | No | DDS | mDNS |
| **Streaming** | Built-in with QoS | No | State topic | Native | No |
| **Progressive** | Yes (3 required fields) | No (full model) | No (full spec) | No | Partial |

## Integration with RoboTrace

ROSP works standalone, but pairs with [RoboTrace](https://github.com/FaultLine-labs/robotrace-sdk) for observability:

```python
from rosp_adapter_ros2 import ROS2Adapter
from robotrace import RoboTrace
from robotrace.integrations.rosp import RoboTraceMiddleware

rt = RoboTrace(host="https://your-server.com", public_key="...", secret_key="...")
traced = RoboTraceMiddleware(adapter=ROS2Adapter(config), robotrace=rt)

async with traced:
    card = await traced.describe()  # Auto-registers device + sensors in RoboTrace
    async for msg in traced.stream(["*"]):  # Auto-sends telemetry to dashboard
        pass
```

## Specification

The full ROSP v0.1 specification is at [docs/spec/ROSP-v0.1-spec.md](docs/spec/ROSP-v0.1-spec.md).

JSON Schemas:
- [robot-card.schema.json](docs/spec/schemas/robot-card.schema.json) (1,066 lines)
- [integration-manifest.schema.json](docs/spec/schemas/integration-manifest.schema.json)
- [skill-description.schema.json](docs/spec/schemas/skill-description.schema.json)

Example Robot Cards:
- [MiR250 AGV](docs/spec/schemas/examples/mir250.json)
- [Universal Robots UR5e](docs/spec/schemas/examples/universal-robots-ur5e.json)

## Development

```bash
git clone https://github.com/FaultLine-labs/rosp.git
cd rosp
pip install ".[dev,cli]"
pytest                    # 60 tests
ruff check .              # Lint
```

## License

Apache License 2.0 — see [LICENSE](LICENSE).

Built by [RoboSwarm](https://roboswarm.io) (FaultLine Labs).
