English | Español

Welcome to the Sancho ROS2 Workspace repository! Here you’ll find everything needed to deploy, build, and run your Sancho robot—a modular system based on ROS 2 Humble and a modern web interface built with React and Vite.

1. ✨ Features
2. 🚀 Prerequisites
3. 🦾 Required Hardware
4. 📥 Repository Download
5. 🔧 Installing Dependencies
   • 4.1 ROS2 Dependencies (package.xml)
   • 4.2 Python Dependencies (requirements.txt)
   • 4.3 Node.js Dependencies (Web Client)
6. 🏭 Workspace Compilation
7. ▶️ Getting Started
   • 6.1 Robot Startup
   • 6.2 Interaction Modules
   • 6.3 Navigation
   • 6.4 Web Server & Nginx Proxy
   • 6.5 Web Interface Development Mode
8. 🗂️ Project Structure
9. 🛠️ Contributions
10. 📄 License

• Modular: 13 custom ROS2 packages (sancho_audio, sancho_navigation, sancho_web, etc.).
• Multimodal interaction: social vision, face detection and tracking, VAD-enabled audio, head movement.
• Full Nav2 stack: mapping, localization, planning.
• Modern web UI: React + Vite with WebSocket/HTTP proxy using Nginx.
• Ready-to-use launch scripts (launch.py) for all components.

Make sure you have the following:

• OS: Ubuntu 22.04 LTS

• ROS 2: Humble Hawksbill

  sudo apt update
  sudo apt install ros-humble-desktop
  sudo rosdep init
  rosdep update

• Basic tools: git, pip, colcon

  sudo apt install git python3-pip python3-colcon-common-extensions

• Nginx (WebSocket/HTTP reverse proxy)

  sudo apt install nginx
  sudo systemctl enable --now nginx

• Node.js (LTS ≥18) and npm for React/Vite UI

  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt install -y nodejs
  node -v  # v20.x
  npm -v   # ≥10

Below is a detailed list of the devices used in the robotic system “Sancho.”
All components have been tested together; however, you can replace them with equivalents as long as they offer similar performance.

• Mobile Base — AgileX Ranger Mini V3
  A 4×4 platform with independent steering, turning radius ≤ 0.42 m, and a 48 V Li-ion battery. It serves as the chassis, locomotion actuator, and power source.

• Onboard Computer
  MinisForum HM80 Mini-PC with AMD Ryzen 7 4800U, 32 GB RAM, and 512 GB NVMe SSD; provides the computing power required for ROS 2, vision, and real-time planning.

• Perception Sensors

  • 2 × Hokuyo UTM-30LX LIDARs (270° @ 40 Hz) for mapping and safe navigation.
  • Orbbec Astra RGB-D Camera (640 × 480 @ 30 Hz) with integrated stereo MEMS microphones, used for user detection and TDOA computation (Driver installation Guide: https://github.com/orbbec/ros2_astra_camera).
  • 5 MP USB RGB Camera (ELP-USB500W05G-L170, FoV ≈ 170°) mounted on the head for frontal interaction.

• Pan-Tilt Unit
  Interbotix WidowX Dual XM430 (±105° in pan/tilt, Dynamixel XM430-W350-T servos) to orient the front camera toward the speaker.

Clone this repo into an empty workspace:

git clone https://github.com/antbaena/sancho_ws.git
cd ~/sancho_ws

➡️ src/ contains 13 custom ROS2 packages plus third-party dependencies.

cd ~/sancho_ws
rosdep install --from-paths src --ignore-src -r -y

• Individually:

  pip install -r src/sancho_perception/requirements.txt
  pip install -r src/sancho_audio/requirements.txt
  # …

• All at once:

  find src -name requirements.txt -exec pip install -r {} \;

cd src/sancho_web/ros-web-client
npm install
npm run build

cd ~/sancho_ws
colcon build
source install/setup.bash

• View URDF in RViz2:

  ros2 launch sancho_description display.launch.py

• Start base and sensors:

  ros2 launch sancho_bringup sancho_bringup.launch.py

ros2 launch sancho_navigation navigation_launch.py

ros2 launch sancho_web web.launch.py
scripts/start_nginx.sh
scripts/stop_nginx.sh

cd src/sancho_web/ros-web-client
npm run dev      # http://localhost:5173
npm run preview  # http://localhost:4173

sancho_ws/
├── src/
│   ├── sancho_audio/
│   ├── sancho_bringup/
│   ├── sancho_description/
│   ├── sancho_demo/
│   ├─ …
└── install/

We welcome issues and pull requests! Please:

1. Open an issue describing your proposal or bug.
2. Create a branch (git checkout -b feature/your-feature).
3. Make changes and add tests if needed.
4. Open a pull request describing your work.

This project is under GPL-3 license. See the LICENSE file for more.

¡Bienvenido al repositorio Sancho ROS2 Workspace! Aquí encontrarás todo lo necesario para desplegar, compilar y ejecutar tu robot Sancho, un sistema modular basado en ROS 2 Humble y una interfaz web moderna con React y Vite.

1. ✨ Características
2. 🚀 Requisitos Previos
3. 🦾 Hardware necesario
4. 📥 Descarga del Repositorio
5. 🔧 Instalación de Dependencias
   • 4.1 Dependencias ROS2 (package.xml)
   • 4.2 Dependencias Python (requirements.txt)
   • 4.3 Dependencias Node.js (cliente web)
6. 🏭 Compilación del Workspace
7. ▶️ Puesta en Marcha
   • 6.1 Arranque del Robot
   • 6.2 Módulos de Interacción
   • 6.3 Navegación
   • 6.4 Servidor Web & Proxy Nginx
   • 6.5 Modo Desarrollo de la Interfaz Web
8. 🗂️ Estructura del Proyecto
9. 🛠️ Contribuciones
10. 📄 Licencia

• Modular: 13 paquetes ROS2 propios (sancho_audio, sancho_navigation, sancho_web, etc.).
• Interacción multimodal: visión social, detección y seguimiento de rostros, audio con VAD, movimiento de cabeza.
• Pila completa de navegación Nav2: mapeado, localización y planificación.
• Interfaz web moderna: React + Vite con proxy WebSocket/HTTP mediante Nginx.
• Scripts y lanzadores (launch.py) para todos los componentes.

Antes de empezar, asegúrate de contar con lo siguiente:

• Sistema operativo: Ubuntu 22.04 LTS 🐧

• ROS 2: Humble Hawksbill 🦅

  sudo apt update
  sudo apt install ros-humble-desktop
  sudo rosdep init
  rosdep update

• Herramientas básicas: git, pip, colcon

  sudo apt install git python3-pip python3-colcon-common-extensions

• Nginx (proxy inverso WebSocket/HTTP)

  sudo apt install nginx
  sudo systemctl enable --now nginx

• Node.js (versión LTS ≥18) y npm para compilar la interfaz React/Vite

  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt install -y nodejs
  node -v  # v20.x
  npm -v   # ≥10

A continuación se detalla el conjunto de dispositivos empleados en el sistema robótico «Sancho».
Todos los componentes han sido validados juntos; sin embargo, puedes sustituirlos por equivalentes si mantienes prestaciones similares.

• Base móvil — AgileX Ranger Mini V3
  Plataforma 4 × 4 con dirección independiente, radio de giro ≤ 0,42 m y batería Li-ion 48 V. Sirve de chasis, actuador de locomoción y fuente de energía.

• Ordenador de a bordo
  Mini-PC MinisForum HM80 con AMD Ryzen 7 4800U, 32 GB RAM y SSD NVMe 512 GB; proporciona la potencia de cálculo necesaria para ROS 2, visión y planificación en tiempo real.

• Sensores de percepción

  • 2 × LIDAR Hokuyo UTM-30LX (270 ° @ 40 Hz) para mapeo y navegación segura.
  • Cámara RGB-D Orbbec Astra (640 × 480 @ 30 Hz) con micrófonos MEMS estéreo integrados, usada para detección de usuarios y cálculo TDOA (Guía instalación driver: https://github.com/orbbec/ros2_astra_camera).
  • Cámara USB RGB 5 MP (ELP-USB500W05G-L170, FoV ≈ 170 °) montada en la cabeza para interacción frontal.

• Unidad pan-tilt
  Interbotix WidowX Dual XM430 (± 105 ° en pan/tilt, servos Dynamixel XM430-W350-T) que orienta la cámara frontal hacia el interlocutor.

Clona el repositorio dentro de un workspace vacío:

git clone https://github.com/antbaena/sancho_ws.git
cd ~/sancho_ws

➡️ El directorio src/ contiene 13 paquetes ROS2 propios.

Instala las dependencias declaradas en cada package.xml:

cd ~/sancho_ws
rosdep install --from-paths src --ignore-src -r -y

• Individual:

  pip install -r src/sancho_perception/requirements.txt
  pip install -r src/sancho_audio/requirements.txt
  # …

• Todas a la vez:

  find src -name requirements.txt -exec pip install -r {} \\\;

cd src/sancho_web/ros-web-client
npm install    # instala React, Vite y librerías auxiliares
npm run build  # genera producción en dist/

cd ~/sancho_ws
colcon build
source install/setup.bash

• Visualizar URDF en RViz2:

  ros2 launch sancho_description display.launch.py

• Bring-up de base y sensores:

  ros2 launch sancho_bringup sancho_bringup.launch.py

ros2 launch sancho_navigation navigation_launch.py

• Arrancar servidor web:

  ros2 launch sancho_web web.launch.py

• Control Nginx (opcional):

  scripts/start_nginx.sh  # Inicia proxy WebSocket
  scripts/stop_nginx.sh   # Detiene Nginx

Durante el desarrollo, sirve la SPA con Vite:

cd src/sancho_web/ros-web-client
npm run dev    # http://localhost:5173
# Para previsualizar producción:
npm run preview  # http://localhost:4173

🛠️ Ajusta el proxy de WebSocket en vite.config.js si el rosbridge está en otra máquina o puerto.

sancho_ws/
├── src/
│   ├── sancho_audio/
│   ├── sancho_bringup/
│   ├── sancho_description/
│   ├── sancho_demo/
│   ├─ …
└── install/

¡Se aceptan issues y pull requests! Por favor:

1. Abre un issue detallando tu propuesta o bug.
2. Crea una rama (git checkout -b feature/nueva-funcionalidad).
3. Realiza tus cambios y añade tests si procede.
4. Abre un pull request describiendo los cambios.

Este proyecto está bajo licencia MIT. Consulta el fichero LICENSE para más detalles.

¡Gracias por usar y contribuir al robot Sancho! 🌟