Metadata-Version: 2.3
Name: robo-infra
Version: 0.5.1
Summary: Robotics SDK for prototyping and development (Beta)
License: MIT
Keywords: robotics,servo,motor,sensor,raspberry-pi,automation,iot
Author: nfraxlab
Author-email: dev@nfrax.io
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Provides-Extra: ai
Provides-Extra: api
Provides-Extra: cameras
Provides-Extra: can
Provides-Extra: full
Provides-Extra: gpio
Provides-Extra: hardware
Provides-Extra: i2c
Provides-Extra: jetson
Provides-Extra: oak
Provides-Extra: picamera
Provides-Extra: raspberry-pi
Provides-Extra: realsense
Provides-Extra: serial
Provides-Extra: spi
Provides-Extra: vision
Requires-Dist: ai-infra (>=0.1.166,<0.2.0) ; extra == "ai" or extra == "full"
Requires-Dist: depthai (>=2.20) ; extra == "oak" or extra == "cameras"
Requires-Dist: gpiozero (>=2.0) ; (sys_platform == "linux") and (extra == "gpio" or extra == "raspberry-pi" or extra == "hardware" or extra == "full")
Requires-Dist: lgpio (>=0.2) ; (sys_platform == "linux") and (extra == "gpio" or extra == "raspberry-pi" or extra == "hardware" or extra == "full")
Requires-Dist: numpy (>=1.24)
Requires-Dist: opencv-python-headless (>=4.8) ; extra == "vision" or extra == "cameras" or extra == "full"
Requires-Dist: picamera2 (>=0.3) ; (sys_platform == "linux") and (extra == "picamera" or extra == "raspberry-pi")
Requires-Dist: pydantic (>=2.0)
Requires-Dist: pyrealsense2 (>=2.50) ; extra == "realsense" or extra == "cameras"
Requires-Dist: pyserial (>=3.5) ; extra == "serial" or extra == "raspberry-pi" or extra == "jetson" or extra == "hardware" or extra == "full"
Requires-Dist: python-can (>=4.0) ; extra == "can" or extra == "hardware" or extra == "full"
Requires-Dist: smbus2 (>=0.4) ; extra == "i2c" or extra == "raspberry-pi" or extra == "jetson" or extra == "hardware" or extra == "full"
Requires-Dist: spidev (>=3.6) ; (sys_platform == "linux") and (extra == "spi" or extra == "raspberry-pi" or extra == "jetson" or extra == "hardware" or extra == "full")
Requires-Dist: svc-infra (>=0.1.716,<0.2.0) ; extra == "api" or extra == "full"
Requires-Dist: typing-extensions (>=4.0)
Project-URL: Documentation, https://github.com/nfraxlab/robo-infra#readme
Project-URL: Homepage, https://github.com/nfraxlab/robo-infra
Project-URL: Repository, https://github.com/nfraxlab/robo-infra
Description-Content-Type: text/markdown

# robo-infra

**Robotics infrastructure SDK for prototyping and development.**

> **Beta Software**: This library is under active development. APIs may change. Not yet validated on real hardware in production environments.

[![PyPI](https://img.shields.io/pypi/v/robo-infra)](https://pypi.org/project/robo-infra/)
[![CI](https://github.com/nfraxlab/robo-infra/workflows/CI/badge.svg)](https://github.com/nfraxlab/robo-infra/actions)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Status](https://img.shields.io/badge/status-beta-orange)](ROADMAP.md)

## Overview

`robo-infra` is a hardware-agnostic robotics SDK designed for prototyping, development, and educational projects. It provides simulation-first development with optional real hardware support.

### Key Features

- **Hardware Abstraction** - Common interface for servos, motors, sensors, and controllers
- **Simulation-First** - Everything works without hardware by default
- **AI-Native** - Built-in integration with `ai-infra` for LLM-controlled robots
- **API-Ready** - Seamless integration with `svc-infra` for REST/WebSocket APIs
- **Safety-First** - Comprehensive limits, emergency stops, and collision detection
- ** Observable** - Full telemetry, logging, and monitoring built-in

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Your Application                        │
├─────────────────────────────────────────────────────────────┤
│  Controllers    │  Motion Planning  │  Safety Systems       │
├─────────────────────────────────────────────────────────────┤
│      Actuators (Servos, Motors)  │  Sensors (IMU, Distance) │
├─────────────────────────────────────────────────────────────┤
│                    Hardware Drivers                          │
├─────────────────────────────────────────────────────────────┤
│     Buses (I2C, SPI, UART)    │    Pins (GPIO, PWM, ADC)    │
├─────────────────────────────────────────────────────────────┤
│  Platforms: Raspberry Pi │ Arduino │ Jetson │ Simulation    │
└─────────────────────────────────────────────────────────────┘
```

## Installation

### Core Only (Minimal)

For embedded systems or when you just need robotics abstractions:

```bash
pip install robo-infra
```

### With AI Integration

For LLM-controlled robots using `ai-infra`:

```bash
pip install robo-infra[ai]
```

### With API Integration

For REST/WebSocket APIs using `svc-infra`:

```bash
pip install robo-infra[api]
```

### With Hardware Support

For real hardware buses (I2C, SPI, Serial, CAN):

```bash
pip install robo-infra[hardware]
```

### Full Installation

Install everything:

```bash
pip install robo-infra[full]
```

### Platform-Specific Bundles

| Platform | Command |
|----------|---------|
| Raspberry Pi | `pip install robo-infra[raspberry-pi]` |
| NVIDIA Jetson | `pip install robo-infra[jetson]` |
| Generic Linux | `pip install robo-infra[hardware]` |

### Granular Hardware Extras

| Feature | Extra | Command |
|---------|-------|---------|
| I2C sensors | `[i2c]` | `pip install robo-infra[i2c]` |
| SPI devices | `[spi]` | `pip install robo-infra[spi]` |
| Serial/UART | `[serial]` | `pip install robo-infra[serial]` |
| CAN bus | `[can]` | `pip install robo-infra[can]` |
| GPIO | `[gpio]` | `pip install robo-infra[gpio]` |

### Vision & Camera Extras

| Feature | Extra | Command |
|---------|-------|---------|
| OpenCV | `[vision]` | `pip install robo-infra[vision]` |
| Intel RealSense | `[realsense]` | `pip install robo-infra[realsense]` |
| Luxonis OAK | `[oak]` | `pip install robo-infra[oak]` |
| Raspberry Pi Camera | `[picamera]` | `pip install robo-infra[picamera]` |
| All cameras | `[cameras]` | `pip install robo-infra[cameras]` |

## Quick Start

```python
from robo_infra.actuators import Servo
from robo_infra.core.types import Limits

# Create a servo (works in simulation by default)
servo = Servo(
    name="gripper",
    channel=0,
    limits=Limits(min_value=0, max_value=180),
)

# Move to position
await servo.move_to(90)

# Get current position
print(f"Position: {servo.position}°")
```

### With Real Hardware

```python
from robo_infra.drivers import PCA9685Driver
from robo_infra.actuators import Servo

# Initialize hardware driver
driver = PCA9685Driver(i2c_address=0x40)

# Attach servo to driver
servo = Servo(
    name="gripper",
    driver=driver,
    channel=0,
)

await servo.move_to(90)
```

### AI Integration

```python
from ai_infra import Agent
from robo_infra.actuators import Servo
from robo_infra.integrations import RobotTools

# Create robot components
servo = Servo(name="arm", channel=0)

# Export as AI tools
tools = RobotTools([servo])

# Use with AI agent
agent = Agent(tools=tools.as_tools())
await agent.run("Move the arm to 45 degrees")
```

### API Integration

```python
from svc_infra import create_app
from robo_infra.actuators import Servo
from robo_infra.integrations import RobotRouter

# Create robot components
servo = Servo(name="arm", channel=0)

# Export as API router
router = RobotRouter([servo])

# Add to app
app = create_app()
app.include_router(router.as_router(), prefix="/robot")
```

## Core Concepts

### Actuators

Physical components that create movement:

- **Servo** - Position-controlled rotational actuators
- **Motor** - Speed-controlled rotational actuators
- **Stepper** - Precise step-based motors
- **LinearActuator** - Linear motion actuators

### Sensors

Components that measure the environment:

- **IMU** - Inertial measurement (accelerometer, gyroscope)
- **Distance** - Distance measurement (ultrasonic, ToF, IR)
- **Temperature** - Temperature sensors
- **Current** - Current sensing for motor feedback

### Drivers

Hardware interfaces:

- **PCA9685** - 16-channel PWM driver
- **ADS1115** - 4-channel ADC
- **MCP23017** - 16-bit I/O expander

### Controllers

High-level control systems:

- **ArmController** - Robotic arm coordination
- **DriveController** - Differential/holonomic drive
- **FlightController** - Quadcopter/drone control

## Documentation

- [Getting Started](docs/getting-started.md)
- [Hardware Setup](docs/hardware-setup.md)
- [API Reference](docs/api-reference.md)
- [Examples](examples/)

## Part of the nfrax Ecosystem

`robo-infra` is designed to work seamlessly with:

- **[svc-infra](https://github.com/nfraxlab/svc-infra)** - Backend infrastructure (API, auth, database)
- **[ai-infra](https://github.com/nfraxlab/ai-infra)** - AI/LLM infrastructure (agents, tools, embeddings)

## License

MIT License - see [LICENSE](LICENSE) for details.

