GitHub - amitb-quantum/roboapi: The unified API layer for...

The unified API layer for robotics. Connect any robot, any brand, with one SDK.

The Problem

Every robot manufacturer ships a different SDK, a different protocol, and a different data format.

A Boston Dynamics Spot speaks nothing like a Universal Robots UR5.
A Figure humanoid has nothing in common with an Agility Robotics Digit.
Every team building on top of robots rewrites the same integration layer from scratch.

This is a multi-billion dollar tax on the robotics industry.

The Solution

RoboAPI is the Stripe for Robotics — a single unified API that abstracts every robot into one clean developer experience. One SDK. One API key. Every robot.

import roboapi

# Connect to ANY robot — simulated, ROS2, or real hardware
robot = roboapi.connect(robot_id="spot-01", brand="simulated")

# Universal commands — same code regardless of robot brand
robot.move(x=1.0, y=0.0, speed=0.5)

# Live telemetry — normalised across all hardware
telemetry = robot.sense()
print(f"Position: {telemetry.position}")
print(f"Battery:  {telemetry.battery_pct}%")

# Works identically on a Boston Dynamics robot, a ROS2 robot, or a simulation

Quickstart — 5 minutes to your first robot

1. Clone and install

git clone https://github.com/YOUR_USERNAME/roboapi.git
cd roboapi
conda create -n roboapi python=3.11 -y
conda activate roboapi
pip install fastapi "uvicorn[standard]" pydantic websockets httpx python-dotenv roslibpy

2. Start the server

uvicorn api.main:app --reload

🤖 RoboAPI v0.1.0 starting up...
INFO: Uvicorn running on http://127.0.0.1:8000

3. Connect a simulated robot

curl -X POST http://localhost:8000/v1/robots/connect \
  -H "Content-Type: application/json" \
  -d '{"robot_id": "my-robot", "brand": "simulated"}'

{
  "robot_id": "my-robot",
  "brand": "simulated",
  "status": "connected",
  "connected_at": 1714000000.0
}

4. Move it

curl -X POST http://localhost:8000/v1/robots/my-robot/move \
  -H "Content-Type: application/json" \
  -d '{"x": 1.0, "y": 0.0, "speed": 0.5}'

5. Read live telemetry

curl http://localhost:8000/v1/robots/my-robot/sense

{
  "robot_id": "my-robot",
  "battery_pct": 99.8,
  "position": {"x": 0.037, "y": 0.001, "z": 0.0},
  "velocity": {"vx": 0.749, "vy": 0.002, "vz": 0.0},
  "status": "busy"
}

That's it. No ROS knowledge required. No brand-specific SDKs. No protocol translation.

Browse the full interactive API docs at http://localhost:8000/docs

Connecting a Real ROS2 Robot

RoboAPI connects to any ROS2 robot via rosbridge.

# Terminal 1 — start your ROS2 robot (or turtlesim for testing)
ros2 run turtlesim turtlesim_node

# Terminal 2 — start rosbridge
ros2 launch rosbridge_server rosbridge_websocket_launch.xml

# Terminal 3 — start RoboAPI
uvicorn api.main:app --reload

# Connect to the ROS2 robot through RoboAPI
curl -X POST http://localhost:8000/v1/robots/connect \
  -H "Content-Type: application/json" \
  -d '{
    "robot_id": "turtle1",
    "brand": "ros",
    "host": "localhost",
    "port": 9090
  }'

# Move it — RoboAPI translates to ROS Twist messages automatically
curl -X POST http://localhost:8000/v1/robots/turtle1/move \
  -H "Content-Type: application/json" \
  -d '{"x": 1.0, "y": 0.8, "speed": 0.6, "duration_ms": 6500}'

The turtle draws a full circle — driven entirely through the unified RoboAPI layer. 🐢

API Reference

Robots

Method	Endpoint	Description
`POST`	`/v1/robots/connect`	Connect a robot and register it
`POST`	`/v1/robots/{id}/move`	Send a normalised move command
`POST`	`/v1/robots/{id}/stop`	Graceful or emergency stop
`GET`	`/v1/robots/{id}/sense`	Poll current sensor snapshot
`GET`	`/v1/robots/{id}/status`	Connection info and health
`DELETE`	`/v1/robots/{id}/disconnect`	Disconnect and deregister
`GET`	`/v1/robots`	List all connected robots

Fleet

Method	Endpoint	Description
`GET`	`/v1/fleet`	List all robots in fleet
`POST`	`/v1/fleet/stop-all`	Emergency stop every robot
`POST`	`/v1/fleet/broadcast/move`	Send move to all robots at once

Telemetry

Method	Endpoint	Description
`WS`	`/v1/telemetry/{id}/stream`	Real-time stream at configurable Hz

# WebSocket telemetry stream — live position updates at 5Hz
wscat -c "ws://localhost:8000/v1/telemetry/my-robot/stream?hz=5"

Supported Robots

Brand	Status	Adapter
Simulated	✅ Ready	Built-in physics sim, battery, sensor noise
ROS / ROS2	✅ Ready	Any ROS2 robot via rosbridge WebSocket
Boston Dynamics	🔶 Planned	Phase 2
Universal Robots	🔶 Planned	Phase 2
Figure / Humanoids	🔶 Planned	Phase 2
Custom hardware	🔶 Planned	Open adapter spec — implement `BaseAdapter`

Adding a new robot brand

RoboAPI uses a pluggable adapter pattern. To add any robot:

# adapters/your_robot_adapter.py
from adapters.base import BaseAdapter

class YourRobotAdapter(BaseAdapter):
    async def connect(self) -> bool: ...
    async def disconnect(self) -> None: ...
    async def move(self, cmd: MoveCommand) -> CommandResponse: ...
    async def stop(self, cmd: StopCommand) -> CommandResponse: ...
    async def get_telemetry(self) -> TelemetrySnapshot: ...
    async def is_alive(self) -> bool: ...

Architecture

┌─────────────────────────────────────────────────┐
│              Your Application                    │
│         (curl / Python SDK / Dashboard)          │
└─────────────────┬───────────────────────────────┘
                  │  REST + WebSocket
┌─────────────────▼───────────────────────────────┐
│                 RoboAPI Core                     │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Robots   │  │  Fleet   │  │   Telemetry   │  │
│  │  API     │  │  API     │  │   WebSocket   │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│  ┌─────────────────────────────────────────────┐ │
│  │           Adapter Factory                   │ │
│  └─────────────────────────────────────────────┘ │
└────┬──────────────┬──────────────┬───────────────┘
     │              │              │
┌────▼────┐  ┌──────▼──────┐  ┌───▼──────────────┐
│   Sim   │  │    ROS2     │  │  Future: BD / UR  │
│ Adapter │  │   Adapter   │  │     Adapters      │
└─────────┘  └─────────────┘  └──────────────────┘
     │              │
┌────▼────┐  ┌──────▼──────┐
│  Built- │  │  rosbridge  │
│   in    │  │  port 9090  │
│   Sim   │  └──────▼──────┘
└─────────┘         │
               ┌────▼────────────────┐
               │   Any ROS2 Robot    │
               │  Turtlesim · Spot · │
               │  Custom hardware    │
               └─────────────────────┘

Project Structure

roboapi/
├── api/
│   ├── main.py              # FastAPI app entry point
│   └── v1/
│       ├── robots.py        # Core robot endpoints
│       ├── fleet.py         # Fleet management
│       └── telemetry.py     # WebSocket streaming
├── adapters/
│   ├── base.py              # Abstract adapter interface
│   ├── sim_adapter.py       # Simulated robot
│   └── ros_adapter.py       # ROS2 via rosbridge
├── core/
│   ├── command.py           # Pydantic models
│   └── robot_registry.py   # Robot state management
├── sdk/                     # Python SDK (coming soon)
├── dashboard/               # React dashboard (coming soon)
└── tests/
    └── test_api.py          # 14 passing tests

Roadmap

Phase 1 — Foundation ✅ (current)

Unified REST API — connect, move, stop, sense
Simulated robot adapter
ROS2 adapter via rosbridge
Real-time WebSocket telemetry
Fleet management — stop-all, broadcast
14-test pytest suite
Auto-generated API docs

Phase 2 — Platform (next)

API key authentication
Python SDK — pip install roboapi
React developer dashboard
Boston Dynamics adapter
OTA firmware update pipeline
Redis-backed fleet registry

Phase 3 — Intelligence

AI bridge — connect any LLM to any robot
Natural language commands
Vision model integration
Data flywheel — aggregate telemetry model

Phase 4 — Scale

Hosted cloud platform
Multi-tenant fleet management
Compliance & audit logging
Enterprise SLAs

Development

# Run tests
pytest tests/ -v

# Run with auto-reload
uvicorn api.main:app --reload

# Code formatting
black .
ruff check .

Contributing

RoboAPI is in early development and we welcome contributions — especially:

Robot adapters — if you have access to hardware we haven't supported yet
Bug reports — open an issue with your robot model and error
Feature requests — what would make this useful for your project

See CONTRIBUTING.md for guidelines.

Why RoboAPI?

The robotics industry is at its Stripe moment.

Before Stripe, every company built custom payment integrations. Before Twilio, everyone wrote their own SMS stack. The pattern is always the same: fragmented, complex, infrastructure problem → one abstraction layer wins → everything builds on top.

Robotics is there right now. Dozens of manufacturers, dozens of protocols, thousands of teams rebuilding the same middleware. RoboAPI is the abstraction layer.

License

MIT — see LICENSE

Status

🚧 Early development — API may change. Not yet recommended for production.
⭐ Star this repo to follow progress.
💬 Open an issue to request a robot adapter or report a bug.

Built with FastAPI · ROS2 · roslibpy

推荐订阅源

Hacker News: Show HN