Metadata-Version: 2.4
Name: ai-teammate-ros2-bridge
Version: 2.6.15
Summary: AI Teammate ROS2 Device Bridge
Author: MobioLabs
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets
Requires-Dist: psutil
Requires-Dist: scipy
Requires-Dist: paho-mqtt
Requires-Dist: PyYAML
Requires-Dist: python-socks
Requires-Dist: lz4>=4.0.0

# AI Teammate Robot Bridge

[![PyPI](https://img.shields.io/pypi/v/ai-teammate-ros2-bridge)](https://pypi.org/project/ai-teammate-ros2-bridge/)
[![Python](https://img.shields.io/pypi/pyversions/ai-teammate-ros2-bridge)](https://pypi.org/project/ai-teammate-ros2-bridge/)

Connects ROS2 robots to the [AI Teammate](https://ai-teammate.net) platform via WebSocket + MQTT.

## Features

- **rclpy native** — Direct DDS participation, no rosbridge required
- **Dual telemetry** — MQTT (primary, 1Hz) + WebSocket (fallback)
- **Auto-detection** — cmd_vel, camera, IMU, LiDAR topics discovered at startup
- **Camera streaming** — RealSense / USB camera auto-detect, JPEG frame streaming
- **Plugin architecture** — Optional [AMR Skills](https://ai-teammate.net) for 54+ robot commands
- **Auto-reconnect** — WebSocket + MQTT reconnection with exponential backoff
- **Simulator mode** — Works without ROS2 for development/testing
- **systemd ready** — Auto-restart, boot start with linger

## Quick Install (Recommended)

```bash
curl -sL "https://ai-teammate.net/api/b2b/install/MY-ROBOT-01?key=YOUR_API_KEY" | bash
```

This single command will:
1. Detect ROS2 and auto-configure topics
2. Install bridge from PyPI + AMR skills (pre-built binary)
3. Configure MQTT telemetry
4. Register device with cloud gateway
5. Create systemd service (auto-restart + boot start)

Get your API key from [Control Tower](https://ai-teammate.net/control-tower) > Devices > + button.

## Manual Install

```bash
pip3 install ai-teammate-ros2-bridge
```

### Configuration

```bash
mkdir -p ~/ai-teammate-bridge && cd ~/ai-teammate-bridge

ai-teammate-bridge init
# → Creates .env with interactive prompts

# Or manually:
cat > .env << EOF
DEVICE_ID=my-robot-01
GATEWAY_URL=wss://ai-teammate.net/gw
API_KEY=dk_YOUR_API_KEY
CONNECTION_MODE=rclpy
STATUS_REPORT_INTERVAL=1.0
CMD_VEL_TOPIC=/cmd_vel
IMU_TOPIC=/imu/data
ODOM_TOPIC=/odom
SCAN_TOPIC=/scan
MQTT_BROKER=ai-teammate.net
MQTT_PORT=1883
MQTT_USER=robot_bridge
MQTT_PASS=mqtt_r0b0t_2026
EOF
```

### Run

```bash
# Source ROS2 environment first
source /opt/ros/humble/setup.bash

ai-teammate-bridge
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DEVICE_ID` | *required* | Unique device identifier |
| `GATEWAY_URL` | *required* | Device Gateway WebSocket URL |
| `API_KEY` | *required* | Device API key (`dk_xxx`) |
| `CONNECTION_MODE` | `rclpy` | `rclpy` for ROS2, `simulator` for testing |
| `STATUS_REPORT_INTERVAL` | `1.0` | Sensor update interval (seconds) |
| `CMD_VEL_TOPIC` | `/cmd_vel` | ROS2 velocity command topic |
| `IMU_TOPIC` | `/imu/data` | IMU subscription topic |
| `ODOM_TOPIC` | `/odom` | Odometry subscription topic |
| `SCAN_TOPIC` | `/scan` | LiDAR scan topic |
| `MQTT_BROKER` | *(empty=disabled)* | MQTT broker hostname |
| `MQTT_PORT` | `1883` | MQTT broker port |
| `MQTT_USER` | `robot_bridge` | MQTT username |
| `MQTT_PASS` | *(empty)* | MQTT password |

## Architecture

```
Robot                              Cloud (ai-teammate.net)
┌──────────────────────┐          ┌─────────────────────┐
│  ai-teammate-bridge  │          │  Device Gateway      │
��  (CLI entry point)   │          │  (port 8003)         │
│                      │          │                      │
│  ���────────────────┐  │  WSS    │  /ws/{device_id}     │
│  │  ws_client.py  │──┼────────▶│    commands ◀──────  │──▶ Control Tower
│  │  DeviceBridge   │◀─┼────────│    responses          │
│  └────────────────┘  │          │                      │
│                      │  MQTT   │  Mosquitto (1883)    │
│  ┌────────────────┐  │────────▶│    telemetry          │
│  │  MQTT publisher │  │         │    position           │
│  └────────────────┘  │         │    health              │
│                      │          └─────────────────────┘
│  ┌────────────────┐  │
│  │  ros2_node.py  │  │  ROS2 DDS (no rosbridge)
│  │  ├─ cmd_vel pub│  │
│  │  ├─ IMU sub    │  │
│  │  ├─ odom sub   │  │
│  │  ├─ scan sub   │  │
│  │  └─ camera sub │  │
│  └────────────────┘  │
│                      │
│  ┌────────────────┐  │
│  │  Skills (opt)  │  │  ai-teammate-ros2-skills
│  │  54+ commands  │  │  (pre-built .so binary)
│  └────────────────┘  │
└──────────────────────┘
```

### Communication Channels

| Channel | Data | Direction | Frequency |
|---------|------|-----------|-----------|
| **WebSocket** | Commands, responses | Bidirectional | On-demand |
| **WebSocket** | Camera frames, SLAM | Robot → Cloud | 2-5 FPS |
| **MQTT** | Telemetry (IMU, battery) | Robot → Cloud | 1 Hz |
| **MQTT** | Position (x, y, theta) | Robot → Cloud | 1 Hz (retained) |
| **MQTT** | Health alerts | Robot → Cloud | On-event (retained) |

## Package Structure

```
ai_teammate_ros2_bridge/
├── cli.py          # Entry point: ai-teammate-bridge command
├── config.py       # Shared state, env loading, MQTT config
├── ws_client.py    # DeviceBridge class, WS + MQTT event loop
├── ros2_node.py    # rclpy spin thread, ROS2 subscriptions
├── sensors.py      # Sensor data aggregation, battery fallback
└── utils.py        # Input sanitization helpers
```

## Systemd Service

The install script creates a systemd service automatically.

```bash
# System-level (if sudo available)
sudo systemctl status ai-teammate-bridge
sudo systemctl restart ai-teammate-bridge
sudo journalctl -u ai-teammate-bridge -f

# User-level (no sudo)
systemctl --user status ai-teammate-bridge
systemctl --user restart ai-teammate-bridge
```

## Supported Platforms

| Platform | Architecture | Python | ROS2 |
|----------|-------------|--------|------|
| Ubuntu 20.04+ | x86_64 | 3.10, 3.12 | Humble, Jazzy |
| Ubuntu 20.04+ | aarch64 (Jetson, RPi4+) | 3.10, 3.12 | Humble, Jazzy |
| Any Linux | x86_64/aarch64 | 3.10+ | *Simulator mode (no ROS2)* |

## Requirements

- Python 3.10+
- ROS2 Humble or Jazzy (optional — simulator mode works without)
- Internet access to ai-teammate.net (WSS + MQTT)

## License

MIT - [MobioLabs](https://mobiolabs.net)
