ai-teammate-ros2-bridge 2.6.5

AI Teammate ROS2 Device Bridge

AI Teammate Robot Bridge

Connects ROS2 robots to the AI Teammate 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 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)

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 > Devices > + button.

Manual Install

pip3 install ai-teammate-ros2-bridge

Configuration

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

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

# 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