Dobot Chess - Sistema de Juego de Ajedrez con Robot

Demostración educativa comercial: Integración del brazo robótico Dobot Magician con ajedrez, jugando contra el motor de ajedrez Stockfish en tiempo real.

🎯 Características

• Frontend Interactivo: Interfaz React moderno y responsivo
• Backend Python: FastAPI con WebSockets para tiempo real
• Motor de Ajedrez: Stockfish local (800 ELO - Fácil)
• Control de Robot: SDK Dobot con reintentos automáticos
• Cola de Jugadores: Sistema de turnos para múltiples usuarios
• Dockerizado: Listo para desplegar en Raspberry Pi

📋 Requisitos

Hardware

• Dobot Magician arm
• Raspberry Pi 4+ (2GB mínimo)
• Cable USB para conectar Dobot
• Conexión a red

Software

• Docker & Docker Compose
• O (sin Docker):
  • Python 3.11+
  • Node.js 18+
  • Stockfish 15+

🚀 Instalación Rápida (Con Docker)

# Clonar/descargar el proyecto
cd Dobot-Chess

# Construir imágenes
docker-compose -f docker/docker-compose.yml build

# Ejecutar servicios
docker-compose -f docker/docker-compose.yml up

# Acceder a:
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
# Health Check: http://localhost:8000/health

🛠️ Instalación Sin Docker (Desarrollo)

Backend

cd backend

# Crear entorno virtual
python3 -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

# Instalar dependencias
pip install -r requirements.txt

# Configurar Dobot (ver calibración más abajo)
# Crear archivo .env si es necesario

# Ejecutar servidor
python app.py

Backend corre en: http://localhost:8000

Frontend

cd frontend

# Instalar dependencias
npm install

# Ejecutar servidor de desarrollo
npm start

Frontend corre en: http://localhost:3000

📐 Calibración del Tablero

Muy importante: Antes de jugar, calibrar las esquinas del tablero.

cd calibration
python board_calibration.py

El script te guiará interactivamente:

1. Posiciona el gripper en esquina superior-izquierda (a8)
2. Posiciona en esquina superior-derecha (h8)
3. Posiciona en esquina inferior-izquierda (a1)
4. Posiciona en esquina inferior-derecha (h1)

Las coordenadas se guardarán en backend/config.py

🎮 Uso

1. Iniciar partida: Click en "Iniciar Partida"
2. Si hay cola: Esperar tu turno (máximo 5 minutos en cola)
3. Realizar movimiento: Click en casilla origen, luego destino
4. Robot juega: El brazo automáticamente ejecuta su movimiento
5. Repetir: Hasta que alguien gane/pierda/pida tablas

📁 Estructura del Proyecto

Dobot-Chess/
├── backend/
│   ├── app.py                 # FastAPI main application
│   ├── config.py              # Configuration settings
│   ├── chess_engine.py        # Stockfish wrapper
│   ├── dobot_controller.py    # Robot arm control
│   ├── game_manager.py        # Game logic & queue
│   └── requirements.txt        # Python dependencies
├── frontend/
│   ├── public/
│   │   └── index.html         # HTML entry point
│   ├── src/
│   │   ├── App.jsx            # Main component
│   │   ├── components/        # React components
│   │   │   ├── GameBoard.jsx
│   │   │   ├── GameInfo.jsx
│   │   │   └── Queue.jsx
│   │   ├── services/
│   │   │   └── gameService.js # API client
│   │   └── index.js           # React entry point
│   └── package.json           # Node dependencies
├── calibration/
│   └── board_calibration.py   # Board mapping tool
├── docker/
│   ├── docker-compose.yml     # Container orchestration
│   ├── Dockerfile.backend     # Backend image
│   └── Dockerfile.frontend    # Frontend image
└── README.md                  # Este archivo

🔧 Configuración

Variables de Entorno

Crear backend/.env:

DEBUG=False
HOST=0.0.0.0
PORT=8000

DOBOT_PORT=/dev/ttyUSB0
DOBOT_BAUDRATE=115200
DOBOT_RETRY_ATTEMPTS=3

STOCKFISH_PATH=/usr/games/stockfish
STOCKFISH_ELO=800
STOCKFISH_DEPTH=15

MAX_CONCURRENT_GAMES=1
QUEUE_TIMEOUT=300

API REST Endpoints

POST   /api/game/start              - Iniciar/encolar partida
GET    /api/game/state              - Estado actual
POST   /api/game/move               - Realizar movimiento
POST   /api/game/resign             - Rendirse
WS     /ws/game/{game_id}           - WebSocket actualizaciones

🐛 Solución de Problemas

Dobot no conecta

# Verificar puerto USB
ls -la /dev/ttyUSB*

# Verificar permisos
sudo usermod -a -G dialout $USER

Stockfish no encontrado

# En Raspberry Pi
sudo apt-get install stockfish

# En macOS
brew install stockfish

# En Ubuntu
sudo apt-get install stockfish

WebSocket timeout

• Aumentar QUEUE_TIMEOUT en config.py
• Verificar firewall: asegura puerto 8000 abierto

📊 Diagrama de Arquitectura

┌─────────────────┐
│   Frontend      │ (React)
│   :3000         │
└────────┬────────┘
         │ HTTP/WebSocket
         │
┌────────▼────────────────────────┐
│  Backend (FastAPI) :8000        │
├─────────────────────────────────┤
│ ├─ Game Manager (Queue)         │
│ ├─ Chess Engine (Stockfish)     │
│ └─ Dobot Controller             │
└────────┬──────────┬─────────────┘
         │          │
         │          │ USB
         │          │
    [Files]    ┌────▼─────────┐
              │ Dobot Magician│
              └────────────────┘

🎓 Contexto Educativo

Este proyecto demuestra:

• Integración Hardware: Comunicación USB con dispositivos
• Sistemas Tiempo Real: WebSockets, colas, reintentos
• Ajedrez: Notación UCI, movimientos legales, Stockfish
• Full-Stack: Python backend, React frontend
• DevOps: Docker, configuración, health checks
• Robótica: Cinemática inversa, movimientos precisos

📝 Licencia

Proyecto educativo. Uso libre para fines comerciales y académicos.

👥 Equipo

Demostración desarrollada para mostrar capacidades de integración en ingeniería.

---

Última actualización: Mayo 2026