Spaces:

pollen-robotics
/

reachy_mini_remote_control_app

Running

App Files Files Community

reachy_mini_remote_control_app / README.md

andito HF Staff

add token for private spaces

0a14fcd about 1 month ago

11 kB

title: Reachy Mini Remote Control App
emoji: 🎤
colorFrom: red
colorTo: blue
sdk: static
pinned: false
short_description: Remote control Reachy Mini !
hf_oauth: true
hf_oauth_expiration_minutes: 480
hf_oauth_scopes:
  - contribute-repos
  - manage-repos
  - write-repos
tags:
  - reachy_mini
  - reachy_mini_python_app

Reachy Mini Remote Control App

A standalone app that connects Reachy Mini robot to a remote server for WebSocket-based control. The robot acts as a WebSocket client connecting to a remote server (e.g., Hugging Face Space), enabling remote control, video streaming, and bidirectional audio.

🚀 Quick Start - Setup Your Control Space

This Space provides a beautiful web interface for setting up remote control:

Option 1: Public Shared Space (Instant)

Just copy this URI and configure it on your robot:

wss://huggingfacem4-reachy-mini-remote-control.hf.space

Option 2: Private Space (Recommended)

Click "Sign in with Hugging Face" below
Clone your own private control space
Get your custom URI: wss://your-username-reachy-mini-remote-control.hf.space
Create a Hugging Face access token with read permissions at https://huggingface.co/settings/tokens
Configure both the URI and token on your robot (see "Connecting to Private Spaces" below)

👉 Visit the web interface above to get started!

Features

WebSocket Client Architecture: Robot connects to remote server (works behind NAT/firewalls)
Profile-Based Configuration: Easily switch between different remote servers
Bidirectional Streaming: Video (robot → server) and Audio (robot ↔ server)
Movement Control: Receive movement commands from remote server
Connection Monitoring: Track latency, frames, and connection health
Optional REST API: Query status and manage profiles via HTTP endpoints

Architecture

Remote Server                    Robot (this app)                Reachy Mini Daemon
(Hugging Face Space)

WebSocket Server     ←──────     WebSocket Clients    ←──────    ReachyMini SDK
- /robot                         - robot_control.py              (Zenoh protocol)
- /video_stream                  - video_stream.py
- /audio_stream                  - audio_stream.py

The app connects TO a remote server as a client, not the other way around. This simplifies network setup since the robot only needs outbound connections.

Installation

From Source

cd reachy_mini_remote_control_app
pip install -e .

Requirements

Python >= 3.10
Reachy Mini daemon running (reachy-mini-daemon)
Remote server running (e.g., reachy_mini_remote_control/app.py)

Usage

1. Start the Remote Server

First, start the remote server that the robot will connect to:

cd ../reachy_mini_remote_control
python app.py
# Server starts on ws://localhost:8000

2. Start the Reachy Mini Daemon

reachy-mini-daemon --mockup-sim

3. Start the Remote Control App

reachy-mini-remote-control-app --profile default

The app will:

Connect to the remote server at ws://localhost:8000
Stream video and audio
Receive and execute movement commands

Command Line Options

reachy-mini-remote-control-app [OPTIONS]

Options:
  --profile PROFILE            Profile to use (default: from .env)
  --websocket-uri URI          WebSocket URI to connect to (overrides profile)
  --robot-name NAME            Robot name (default: reachy_mini)
  --log-level LEVEL            Logging level (DEBUG, INFO, WARNING, ERROR)
  --no-rest-api                Disable REST API for status endpoints

Configuration

Profiles

Profiles are stored in src/reachy_mini_remote_control_app/profiles/. Each profile is a directory with a config.txt file.

Default Profile (profiles/default/config.txt):

WEBSOCKET_URI=ws://localhost:8000
VIDEO_JPEG_QUALITY=80
VIDEO_WITH_TIMESTAMP=false
VIDEO_FPS=25
AUDIO_WITH_TIMESTAMP=false
AUDIO_BATCH_SIZE=4096
ENABLE_METRICS_LOGGING=true
METRICS_LOG_INTERVAL_SEC=5

Example Remote Profile (profiles/example_remote/config.txt):

WEBSOCKET_URI=wss://YOUR-SPACE.hf.space
VIDEO_JPEG_QUALITY=75
VIDEO_WITH_TIMESTAMP=true
VIDEO_FPS=25
AUDIO_WITH_TIMESTAMP=true
AUDIO_BATCH_SIZE=4096
ENABLE_METRICS_LOGGING=true
METRICS_LOG_INTERVAL_SEC=10

Connecting to Private Spaces

If you're using a private Hugging Face Space, you need to authenticate with a Hugging Face token:

Create a Hugging Face Access Token:
- Go to https://huggingface.co/settings/tokens
- Create a new token with read permissions
- Copy the token
Configure the Token:

Option A: Via Profile Configuration (Recommended)

Add the token to your profile's config.txt:
```
WEBSOCKET_URI=wss://your-username-reachy-mini-remote-control.hf.space
HF_TOKEN=hf_your_token_here
```
Option B: Via Environment Variable

Add to your .env file:
```
HF_TOKEN=hf_your_token_here
```
Run the app - it will automatically use the token for authentication when connecting to the private space.

Environment Variables

Create a .env file (copy from .env.example):

REMOTE_CONTROL_PROFILE=default
ROBOT_NAME=reachy_mini
LOG_LEVEL=INFO
VIDEO_JPEG_QUALITY=80
LATENCY_WARNING_MS=200
ENABLE_REST_API=true
REST_API_HOST=0.0.0.0
REST_API_PORT=7860
# Optional: HF_TOKEN for private Hugging Face Spaces
# HF_TOKEN=hf_your_token_here

REST API (Optional)

If ENABLE_REST_API=true, the app provides HTTP endpoints:

Get Status

curl http://localhost:7860/status

Response:

{
  "robot_connected": true,
  "control": {
    "connected": true,
    "commands_received": 42,
    "last_command_type": "movement",
    "last_activity": 1705123456.78
  },
  "video": {
    "connected": true,
    "frames_sent": 1234,
    "frames_dropped": 5,
    "fps": 24.8,
    "latency_ms": 45.2,
    "latency_avg_ms": 42.1,
    "latency_min_ms": 38.5,
    "latency_max_ms": 52.3,
    "last_activity": 1705123456.78
  },
  "audio": {
    "connected": true,
    "chunks_sent": 567,
    "chunks_received": 234,
    "latency_avg_ms": 38.5,
    "last_activity": 1705123456.78
  }
}

List Profiles

curl http://localhost:7860/profiles

Response:

{
  "profiles": ["default", "example_remote"],
  "current": "default"
}

Switch Profile

curl -X POST http://localhost:7860/profile/example_remote

Note: Requires app restart to take effect.

Health Check

curl http://localhost:7860/health

Integration with Reachy Mini Dashboard

This app integrates with the Reachy Mini dashboard as a ReachyMiniApp:

Install the app: pip install -e reachy_mini_remote_control_app
The app will appear in the dashboard
Start from the dashboard UI
The dashboard provides the ReachyMini instance and stop_event

HuggingFace OAuth

This Space uses OAuth for seamless authentication. The metadata above enables OAuth with:

hf_oauth: true - Enables OAuth flow
hf_oauth_expiration_minutes: 480 - Tokens valid for 8 hours
hf_oauth_scopes: openid, profile - Access to user info

How OAuth Works

User clicks "Sign in with Hugging Face" in the web interface
HuggingFace OAuth flow - User authorizes the app
Access token returned - Stored securely in session storage
Space cloning - User can duplicate the remote control server to their account
Private URI generated - Custom WebSocket URI for their private space

The OAuth implementation uses the @huggingface/hub JavaScript library for client-side authentication. See hf-auth.js for implementation details.

For Robot Users

The robot doesn't need OAuth - it just connects to the WebSocket URI. OAuth is only used in the web interface for space management.

Deployment to Production

Hugging Face Space Setup

Deploy the remote server (reachy_mini_remote_control/app.py) to Hugging Face Space
Note the Space URL: wss://YOUR-SPACE.hf.space
Create a new profile:

mkdir -p src/reachy_mini_remote_control_app/profiles/production

Edit profiles/production/config.txt:

WEBSOCKET_URI=wss://YOUR-SPACE.hf.space
VIDEO_JPEG_QUALITY=75
VIDEO_WITH_TIMESTAMP=true
VIDEO_FPS=25
AUDIO_WITH_TIMESTAMP=true
AUDIO_BATCH_SIZE=4096
ENABLE_METRICS_LOGGING=true
METRICS_LOG_INTERVAL_SEC=10

Set environment variable:

export REMOTE_CONTROL_PROFILE=production

Run the app:

reachy-mini-remote-control-app --profile production

Network Requirements

Robot side: Only outbound connections needed (no port forwarding required)
Server side: WebSocket server must be publicly accessible
Protocol: Use WSS (WebSocket Secure) for production

Security Considerations

Use WSS (not WS) for encrypted connections
Consider implementing authentication tokens
Monitor connection logs for suspicious activity
Rate limiting on the server side

Troubleshooting

Robot fails to connect to daemon

Failed to connect to robot: Connection timeout

Solution: Make sure the daemon is running:

reachy-mini-daemon --mockup-sim

WebSocket connection fails

[Robot Control] Connection failed: Cannot connect to host

Solutions:

Verify the remote server is running and accessible
Check the WEBSOCKET_URI in your profile
Test connectivity: curl http://YOUR-SERVER:8000/health (if server has health endpoint)
Check firewall rules

No video/audio streaming

Solutions:

Ensure media is started: check daemon logs
Verify WebSocket connections are established: check /status endpoint
Check frame/audio publisher threads are running (look for log messages)

High latency

Check the /status endpoint for latency metrics:

curl http://localhost:7860/status | jq '.video.latency_avg_ms'

Solutions:

Reduce VIDEO_JPEG_QUALITY in profile (e.g., from 80 to 60)
Lower VIDEO_FPS (e.g., from 25 to 15)
Use a server geographically closer to the robot
Check network bandwidth

Development

Running Tests

pytest tests/

Code Structure

config.py - Configuration management and profile loading
monitoring/ - Metrics tracking and connection monitoring
websocket_clients/ - WebSocket client implementations
- robot_control.py - Receive movement commands
- video_stream.py - Send video frames
- audio_stream.py - Bidirectional audio
app.py - Optional REST API for status
main.py - Entry point and ReachyMiniApp implementation

License

Same as Reachy Mini SDK.

Support

For issues and questions:

GitHub Issues: pollen-robotics/reachy_mini
Email: contact@pollen-robotics.com