Metadata-Version: 2.4
Name: agent-ros-bridge
Version: 0.2.3
Summary: Agent ROS Bridge - Universal ROS1/ROS2 bridge for AI agents to control robots and embodied intelligence systems
Project-URL: Homepage, https://github.com/webthree549-bot/agent-ros-bridge
Project-URL: Documentation, https://agent-ros-bridge.readthedocs.io
Project-URL: Repository, https://github.com/webthree549-bot/agent-ros-bridge
Project-URL: Issues, https://github.com/webthree549-bot/agent-ros-bridge/issues
Project-URL: Changelog, https://github.com/webthree549-bot/agent-ros-bridge/blob/main/CHANGELOG.md
Author-email: Agent ROS Bridge Team <dev@agent-ros-bridge.org>
License: MIT
License-File: LICENSE
Keywords: agent,ai,automation,bridge,embodied-intelligence,gateway,iot,robotics,ros,ros2
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: paho-mqtt>=1.6.0
Requires-Dist: prometheus-client>=0.17.0
Requires-Dist: psutil>=5.9.5
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: typing-extensions>=4.7.0; python_version < '3.10'
Provides-Extra: all
Requires-Dist: aioresponses>=0.7.4; extra == 'all'
Requires-Dist: bandit[toml]>=1.7.5; extra == 'all'
Requires-Dist: black>=23.7.0; extra == 'all'
Requires-Dist: commitizen>=3.6.0; extra == 'all'
Requires-Dist: factory-boy>=3.3.0; extra == 'all'
Requires-Dist: faker>=19.0.0; extra == 'all'
Requires-Dist: grpcio-tools>=1.56.0; extra == 'all'
Requires-Dist: grpcio>=1.56.0; extra == 'all'
Requires-Dist: isort>=5.12.0; extra == 'all'
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == 'all'
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == 'all'
Requires-Dist: mkdocs-material>=9.1.0; extra == 'all'
Requires-Dist: mkdocs-section-index>=0.3.0; extra == 'all'
Requires-Dist: mkdocs>=1.5.0; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.22.0; extra == 'all'
Requires-Dist: mypy>=1.5.0; extra == 'all'
Requires-Dist: paho-mqtt>=1.6.0; extra == 'all'
Requires-Dist: pre-commit>=3.3.0; extra == 'all'
Requires-Dist: pymavlink>=2.4.30; extra == 'all'
Requires-Dist: pymodbus>=3.5.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest-xdist>=3.3.0; extra == 'all'
Requires-Dist: pytest>=7.4.0; extra == 'all'
Requires-Dist: rclpy>=3.3.0; extra == 'all'
Requires-Dist: responses>=0.23.0; extra == 'all'
Requires-Dist: ruff>=0.0.280; extra == 'all'
Requires-Dist: safety>=2.3.0; extra == 'all'
Requires-Dist: websockets>=11.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.7.0; extra == 'dev'
Requires-Dist: commitizen>=3.6.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.3.0; extra == 'dev'
Requires-Dist: ruff>=0.0.280; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == 'docs'
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.1.0; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.22.0; extra == 'docs'
Provides-Extra: drones
Requires-Dist: pymavlink>=2.4.30; extra == 'drones'
Provides-Extra: industrial
Requires-Dist: pymodbus>=3.5.0; extra == 'industrial'
Provides-Extra: ros2
Requires-Dist: rclpy>=3.3.0; extra == 'ros2'
Provides-Extra: security
Requires-Dist: bandit[toml]>=1.7.5; extra == 'security'
Requires-Dist: safety>=2.3.0; extra == 'security'
Provides-Extra: test
Requires-Dist: aioresponses>=0.7.4; extra == 'test'
Requires-Dist: factory-boy>=3.3.0; extra == 'test'
Requires-Dist: faker>=19.0.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.3.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Requires-Dist: responses>=0.23.0; extra == 'test'
Provides-Extra: transports
Requires-Dist: grpcio-tools>=1.56.0; extra == 'transports'
Requires-Dist: grpcio>=1.56.0; extra == 'transports'
Requires-Dist: paho-mqtt>=1.6.0; extra == 'transports'
Requires-Dist: websockets>=11.0; extra == 'transports'
Description-Content-Type: text/markdown

# Agent ROS Bridge

**Universal ROS1/ROS2 bridge for AI agents to control robots and embodied intelligence systems.**

[![CI](https://github.com/webthree549-bot/agent-ros-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/webthree549-bot/agent-ros-bridge/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agent-ros-bridge.svg)](https://pypi.org/project/agent-ros-bridge/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

## 🔐 Security First

**Required before running:** Set a JWT secret for authentication.

```bash
# Generate a secure secret
export JWT_SECRET=$(openssl rand -base64 32)
```

See [SECURITY.md](SECURITY.md) for complete security guidelines.

---

## Quick Start

### Production (requires ROS1 or ROS2)
```bash
pip install agent-ros-bridge
python run_bridge.py  # Auto-detects ROS1 Noetic or ROS2 Humble/Jazzy
```

### Demo/Testing (Local Only - No ROS Required)

**⚠️ Security Note:** Mock mode disables authentication for testing. **Only run on localhost.**

```bash
# Bind to localhost only (secure for testing)
export BRIDGE_HOST=127.0.0.1
export MOCK_MODE=true

pip install agent-ros-bridge
python examples/quickstart/mock_bridge.py  # Simulated robot
```

### Native ROS (Recommended for Development)

**Install from PyPI (Recommended):**
```bash
pip install agent-ros-bridge

# Run with native ROS
source /opt/ros/humble/setup.bash  # or noetic, jazzy
python run_bridge.py
```

**Or install from source:**
```bash
git clone https://github.com/webthree549-bot/agent-ros-bridge.git
cd agent-ros-bridge
pip install -e .
```

**Dual ROS1 + ROS2 (simultaneous):**
```bash
# Source both ROS environments
source /opt/ros/noetic/setup.bash
source /opt/ros/humble/setup.bash

# Run dual bridge
python run_bridge_dual_ros.py
```

See [docs/NATIVE_ROS.md](docs/NATIVE_ROS.md) for detailed native installation.

### Web Dashboard
```bash
# Start bridge (in another terminal)
cd examples/quickstart && ./run.sh

# Start dashboard
python dashboard/server.py
# Open http://localhost:8080 in browser
```

### Fleet Orchestration (Multi-Robot)
```bash
# Start fleet orchestrator with 4 simulated robots
cd examples/fleet && ./run.sh

# Query fleet status
wscat -c ws://localhost:8771
> {"command": {"action": "fleet.status"}}
> {"command": {"action": "fleet.metrics"}}
> {"command": {"action": "fleet.submit_task", "parameters": {"type": "navigate", "target": "zone_a"}}}
```

### Arm Robot Control (Manipulation)
```bash
# Control UR5 arm
cd examples/arm && ./run.sh --arm-type ur --demo pick_place

# Control xArm
cd examples/arm && ./run.sh --arm-type xarm

# Interactive control
cd examples/arm && ./run.sh --arm-type ur --demo interactive
# Then: wscat -c ws://localhost:8772
```

### ROS Actions (Navigation, Planning)
```bash
# Navigation action demo
cd examples/actions && ./run.sh --action navigate

# Manipulation trajectory demo
cd examples/actions && ./run.sh --action manipulate

# Interactive action control
cd examples/actions && ./run.sh --action interactive
# Then: wscat -c ws://localhost:8773
# Send: {"command": {"action": "actions.navigate", "parameters": {"x": 5.0, "y": 3.0}}}
```

### Prometheus Metrics (Monitoring)
```bash
# Start metrics server
cd examples/metrics && ./run.sh

# View metrics
curl http://localhost:9090/metrics

# For Grafana:
# 1. Import dashboards/grafana-dashboard.json
# 2. Add Prometheus data source: http://localhost:9090
```

## Project Structure

```
agent-ros-bridge/                 # Repository root
├── agent_ros_bridge/            # ⭐ Core source package
│   ├── gateway_v2/              # Main gateway implementation
│   │   ├── core.py              # Bridge class
│   │   ├── auth.py              # Authentication
│   │   ├── transports/          # Communication protocols
│   │   └── connectors/          # ROS connectors
│   ├── fleet/                   # Fleet orchestration
│   ├── plugins/                 # Robot plugins (arm, etc.)
│   ├── actions/                 # ROS actions support
│   └── metrics/                 # Prometheus metrics
├── tests/                       # Test suite
├── examples/                    # ⭐ Runnable examples (7 demos)
│   ├── quickstart/              #   Basic bridge usage
│   ├── fleet/                   #   Multi-robot coordination
│   ├── auth/                    #   JWT authentication
│   ├── mqtt_iot/                #   IoT sensor integration
│   ├── actions/                 #   ROS navigation/actions
│   ├── arm/                     #   Robotic arm control
│   └── metrics/                 #   Prometheus monitoring
├── docs/                        # Documentation (40,000+ words)
├── scripts/                     # Utility scripts
├── config/                      # Configuration templates
├── docker/                      # Docker containers
├── dashboard/                   # Web dashboard
├── Makefile                     # Build automation
└── pyproject.toml              # Package configuration
```

See [Repository Structure](docs/REPOSITORY_STRUCTURE.md) for complete details.

## Features

- **Multi-Protocol**: WebSocket, gRPC, MQTT, TCP
- **Multi-Robot**: Manage fleets of robots
- **Fleet Orchestration**: Task allocation, load balancing, coordination
- **Arm Robot Control**: UR, xArm, Franka manipulation support
- **ROS Actions**: Navigation, motion planning, long-running tasks
- **Prometheus Metrics**: Production monitoring with Grafana dashboards
- **Multi-ROS**: Connect to multiple ROS1/ROS2 endpoints simultaneously
- **Dual ROS**: Run ROS1 + ROS2 in the same bridge instance
- **Remote ROS**: Connect to robots over the network
- **Plugin System**: Build custom applications
- **ROS Support**: ROS1 Noetic, ROS2 Humble/Jazzy/Iron
- **Cloud-Native**: Docker, Kubernetes ready

## Development

The repository maintains strict separation between **source code** and **build artifacts**:

```bash
# Clone and setup
git clone https://github.com/webthree549-bot/agent-ros-bridge.git
cd agent-ros-bridge

# Install in development mode
make install-dev

# Development workflow
make format      # Format code
make test        # Run tests
make check       # Lint + test

# Clean build artifacts
make clean       # Remove all generated files
make build       # Create wheel and sdist
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [Repository Structure](docs/REPOSITORY_STRUCTURE.md) for details.

## Documentation

| Document | Description |
|----------|-------------|
| **[User Manual](docs/USER_MANUAL.md)** | Complete guide (23,000+ words) - Installation, tutorials, troubleshooting |
| **[API Reference](docs/API_REFERENCE.md)** | Full API docs - Classes, methods, examples |
| **[Native ROS](docs/NATIVE_ROS.md)** | Ubuntu/ROS installation and setup |
| **[Multi-ROS](docs/MULTI_ROS.md)** | Fleet management and coordination |
| **[Docker vs Native](docs/DOCKER_VS_NATIVE.md)** | Deployment strategy comparison |
| **[DDS Architecture](docs/DDS_ARCHITECTURE.md)** | ROS2/DDS relationship explained |
| **[Repository Structure](docs/REPOSITORY_STRUCTURE.md)** | Clean source/build separation |

**Quick Links:**
- [Installation Guide](docs/USER_MANUAL.md#installation)
- [Docker vs Native Decision Matrix](docs/DOCKER_VS_NATIVE.md#decision-matrix)
- [Repository Structure](docs/REPOSITORY_STRUCTURE.md)
- [WebSocket Protocol](docs/API_REFERENCE.md#websocket-protocol)
- [Fleet Management](docs/USER_MANUAL.md#fleet-management)
- [Troubleshooting](docs/USER_MANUAL.md#troubleshooting)

## Installation

### Via PyPI
```bash
pip install agent-ros-bridge
```

### Via ClawHub
```bash
openclaw skills add agent-ros-bridge
```

### From Source
```bash
git clone https://github.com/webthree549-bot/agent-ros-bridge.git
cd agent-ros-bridge
pip install -e ".[dev]"
```

## Usage

### Python API
```python
from agent_ros_bridge import Bridge
from agent_ros_bridge.transports.websocket import WebSocketTransport

bridge = Bridge()
bridge.transport_manager.register(WebSocketTransport({"port": 8765}))
await bridge.start()
```

### CLI
```bash
agent-ros-bridge --demo
agent-ros-bridge --config ./config.yaml
```

## License

[MIT License](LICENSE)

---

Made with ❤️ by the Agent ROS Bridge Team
