agent-ros-bridge 0.2.5

Agent ROS Bridge - Universal ROS1/ROS2 bridge for AI agents to control robots and embodied intelligence systems

Agent ROS Bridge

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

---

🔐 Security First

JWT_SECRET is required. The bridge will fail to start without it.

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

For local testing only: Use mock mode to bypass auth (localhost only, not for production).

# Mock mode - disables auth for testing only
export MOCK_MODE=true
export BRIDGE_HOST=127.0.0.1

See SECURITY.md for complete security guidelines.

---

Quick Start

Production (requires ROS1 or ROS2)

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.

# 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):

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:

git clone https://github.com/webthree549-bot/agent-ros-bridge.git
cd agent-ros-bridge
pip install -e .

Dual ROS1 + ROS2 (simultaneous):

# 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 for detailed native installation.

Web Dashboard

# 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)

# 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)

# 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)

# 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)

# 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 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:

# 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 and Repository Structure for details.

Documentation

Document	Description
User Manual	Complete guide (23,000+ words) - Installation, tutorials, troubleshooting
API Reference	Full API docs - Classes, methods, examples
Native ROS	Ubuntu/ROS installation and setup
Multi-ROS	Fleet management and coordination
Docker vs Native	Deployment strategy comparison
DDS Architecture	ROS2/DDS relationship explained
Repository Structure	Clean source/build separation

Quick Links:

• Installation Guide
• Docker vs Native Decision Matrix
• Repository Structure
• WebSocket Protocol
• Fleet Management
• Troubleshooting

Installation

Via PyPI

pip install agent-ros-bridge

Via ClawHub

openclaw skills add agent-ros-bridge

From Source

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

Usage

Python API

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

agent-ros-bridge --demo
agent-ros-bridge --config ./config.yaml

License

MIT License

---

Made with ❤️ by the Agent ROS Bridge Team