Instalar y preparar

Mientras se instala, juega con el coche: Juega con el coche en el navegador.

Qué tendrás al final

Al terminar este capítulo tendrás tres cosas:

1. ROS 2 Jazzy y Gazebo Harmonic instalados, con el repositorio del curso compilado.
2. El coche de la WRO en el campo Open, dentro de Gazebo, y las vistas del LiDAR y de la cámara en RViz. Lo conduces con el teclado.
3. Tu propio paquete de ROS, my_open, que compila y se ejecuta. Ahí vivirá tu estrategia a partir del paso 1.

Cuenta con una hora si todo va bien, casi toda en descargas. El entorno ocupa unos 4,5 GB en macOS y varios GB en Ubuntu (ROS 2 de escritorio más Gazebo). Deja unos 10 GB libres para no tener sorpresas.

Seis palabras que vas a leer

No hace falta entenderlas a fondo ahora: cada una vuelve a aparecer cuando se usa.

• ROS 2: un conjunto de herramientas para programar robots como varios programas pequeños, los nodos, que se pasan mensajes por canales con nombre, los tópicos. Por ejemplo, /cmd_vel_raw es el canal donde se piden velocidades al coche.
• Gazebo: el simulador. Pone el campo, el coche y la física.
• RViz: un visor para ver lo que el robot percibe (los puntos del LiDAR, la imagen de la cámara).
• LiDAR: un sensor con un láser que gira y mide la distancia a lo que tiene alrededor. Es la «vista» del coche para las paredes.
• colcon: la herramienta que compila los paquetes. La carpeta con todos los paquetes (aquí, el repositorio) se llama workspace.
• source: el comando que activa en esta terminal lo que acabas de instalar o compilar. Si una orden de ROS «no existe», casi siempre falta un source.

Qué está probado. Lo que ves aquí lo he ejecutado yo, pero no en todas partes:

• Ubuntu 24.04 (arm64, en Docker): la instalación, colcon build, ros2 pkg create y rondas completas sin ventana, y también con la ventana de Gazebo usando render por software. Todo funciona.
• macOS con RoboStack (Apple Silicon): rondas completas con ventana (Metal), 30 de 30 puntos. También creé el entorno desde cero con la línea de abajo (4,5 GB, unos 5 minutos) y en él compilé el repositorio y corrí una ronda en cada sentido: 30 de 30 en las dos.
• No lo he probado: Linux con una GPU y una pantalla reales, WSL2, el coche real.

Si algo de esto no funciona en tu máquina, cuéntamelo.

Requisitos y sistema operativo

Necesitas un ordenador con Ubuntu 24.04 o con macOS en Apple Silicon, conexión a internet y una terminal (la ventana donde se escriben los comandos). Elige tu sistema con las pestañas de abajo. La elección se recuerda en toda la guía.

sudo apt update && sudo apt install -y git
git clone https://github.com/renzodamgo/robotek-learn.git
cd robotek-learn

bash tools/install-ubuntu.sh

source /opt/ros/jazzy/setup.bash
colcon build --symlink-install
source install/setup.bash

brew install micromamba
git clone https://github.com/renzodamgo/robotek-learn.git
cd robotek-learn

micromamba create -y -p ~/robotek-ros/jazzy \
  -c robostack-jazzy -c conda-forge --strict-channel-priority \
  python=3.12 ros-jazzy-ros-base ros-jazzy-ros-gz-sim ros-jazzy-ros-gz-bridge \
  ros-jazzy-robot-state-publisher ros-jazzy-rviz2 ros-jazzy-xacro \
  ros-jazzy-cv-bridge colcon-common-extensions gz-sim8

cd robotek-learn
source tools/macos_env.sh ~/robotek-ros/jazzy

python -m pip install --target ~/robotek-ros/setuptools79 'setuptools<80'
PYTHONPATH=$HOME/robotek-ros/setuptools79 colcon build --symlink-install
source tools/macos_env.sh ~/robotek-ros/jazzy      # ahora sí carga install/

Comprueba la instalación

Con el entorno cargado (el source de arriba), comprueba que ROS y Gazebo responden:

echo $ROS_DISTRO          # jazzy
gz sim --versions         # 8.x (Gazebo Harmonic)
ros2 pkg list | grep robotek

Debes ver jazzy, una versión 8 de Gazebo y seis paquetes: robotek_common, robotek_course, robotek_description, robotek_evaluation, robotek_gazebo y robotek_hardware. Si faltan, no has cargado install/setup.bash (Ubuntu) o tools/macos_env.sh (macOS).

Ahora lanza el simulador:

ros2 launch robotek_course sim.launch.py

Se abre la ventana de Gazebo con el campo del reto Open y el coche quieto, mirando hacia donde empieza la vuelta en sentido contrario a las agujas del reloj (direction:=ccw, el valor por defecto; con direction:=cw empieza mirando al otro lado). El coche lleva un LiDAR, una cámara a 6 fotogramas por segundo y un giroscopio, con los mismos retrasos y ruido que el coche real.

Para ver lo que ve el coche, lanza el simulador con RViz:

ros2 launch robotek_course sim.launch.py rviz:=true

RViz muestra los puntos del LiDAR sobre las paredes y la imagen de la cámara. Hay una tercera imagen, Direction evidence, que queda vacía hasta que corra una estrategia.

Gazebo necesita una pantalla. Si tu máquina no tiene una (un servidor, un contenedor) o va muy justa de GPU, arranca sin la ventana y mira solo RViz:

ros2 launch robotek_course sim.launch.py gui:=false rviz:=true

El servidor de Gazebo corre igual sin ventana (lo verifiqué en Docker con render por software). En el Mac la simulación con cámara y LiDAR consume bastante CPU; si el ordenador se arrastra, cierra otras aplicaciones o prueba con gui:=false.

Conduce con el teclado

Deja el simulador abierto. En otra terminal con el entorno cargado:

ros2 run robotek_course keyboard_drive

Esa terminal debe estar en primer plano, porque lee las teclas directamente.

Prueba esto: pulsa w tres veces y a dos veces. El coche arranca y dibuja un círculo a la izquierda; con d hasta pasar el centro, gira a la derecha. Con espacio se detiene. En RViz fíjate en cómo cambian los puntos del LiDAR cuando te acercas a una pared.

El programa publica en /cmd_vel_raw, el mismo tópico que usará tu estrategia. Convierte la velocidad y el ángulo de dirección en una velocidad de giro con el modelo de bicicleta, que es justo lo que escribirás en el paso 1. Para cerrar, pulsa q en esa terminal y Ctrl+C en la del simulador.

Crea tu paquete

Tu estrategia será un paquete de ROS 2 en Python llamado my_open. Se crea dentro de src/, junto a los demás. Pon tu nombre y tu correo en el comando:

cd src
ros2 pkg create --build-type ament_python my_open --node-name drive \
  --license MIT --maintainer-name "Tu Nombre" --maintainer-email tu@correo.com \
  --description "Mi estrategia del reto Open" \
  --dependencies rclpy geometry_msgs sensor_msgs std_msgs visualization_msgs cv_bridge robotek_common robotek_course
cd ..

Crea esto:

src/my_open/
├── LICENSE
├── package.xml            # nombre del paquete y dependencias
├── setup.py               # cómo se instala y qué comandos expone
├── setup.cfg              # dónde se instalan los ejecutables
├── resource/my_open       # marcador para que ROS encuentre el paquete
├── my_open/
│   ├── __init__.py        # hace que la carpeta sea un módulo de Python
│   └── drive.py           # tu nodo: aquí vivirá la estrategia
└── test/                  # pruebas de estilo que genera ROS (copyright, flake8, pep257)

La lista de dependencias es larga a propósito. Es todo lo que usarás hasta el final del curso: rclpy (ROS en Python), los mensajes de velocidad, LiDAR e imagen, los marcadores de RViz, cv_bridge para pasar imágenes a OpenCV, y los paquetes del curso (robotek_common con las medidas del coche y robotek_course con la clase base de la estrategia). Declararlas ahora evita volver a tocar package.xml en cada paso.

Compila solo tu paquete y cárgalo. En macOS añade el prefijo PYTHONPATH=$HOME/robotek-ros/setuptools79 delante de colcon:

colcon build --symlink-install --packages-select my_open
source install/setup.bash        # en macOS: source tools/macos_env.sh ~/robotek-ros/jazzy
ros2 run my_open drive

Debe imprimir Hi from my_open.. Ese es el nodo de plantilla. En el paso 1 empiezas a llenar my_open/ con código.

Tu código y la referencia

Git ignora src/my_open en la rama main: es tu código, no el del repositorio. El repositorio tiene además una rama solutions con un commit y una etiqueta step-N por cada paso de la guía; esta página corresponde a step-0. Para comparar tu trabajo con la referencia, desde el paso 1:

git fetch --tags
bash tools/compare-step.sh 1        # tu src/my_open contra la referencia del paso 1
bash tools/compare-step.sh 1 2      # qué cambia la referencia entre dos pasos

Si algo falla

• rosdep install (lo pide la documentación general de ROS) falla con una dependencia que no encuentra. No hace falta: ros-jazzy-desktop y ros-jazzy-ros-gz ya traen todo lo que pide el curso. Salta rosdep y ve directo a colcon build.

• La ronda puntúa casi 0 aunque el código esté bien, o el coche avanza muy despacio. Casi siempre quedan procesos de una ejecución anterior que se interrumpió (un gz sim, los puentes o tus nodos). Se mezclan con la nueva ronda: dos modelos de actuadores publican a la vez. Es lo que más tiempo me hizo perder. Una ronda que termina sola limpia lo suyo, pero si cortas con Ctrl+C o por tiempo, ciérralo todo antes de lanzar otra vez:

  bash src/robotek_evaluation/tools/clean_sim.sh

• pytest falla con PluginValidationError de launch_testing (típico en RoboStack). Los plugins de ROS se cargan solos y chocan con pytest. Desactiva la carga automática:

  PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest course/tests/test_step_1.py

• Veo tópicos o nodos que no son míos. Otro ordenador de la red usa tu mismo ROS_DOMAIN_ID. Elige un número entre 0 y 101 y úsalo igual en todas tus terminales: export ROS_DOMAIN_ID=37. En macOS el script ya pone 42.

• Gazebo no abre ventana en WSL2. Comprueba que WSLg funciona (echo $DISPLAY no debe estar vacío y una app gráfica sencilla debe abrirse). Si no, usa gui:=false rviz:=true.

• En macOS, ros2 o colcon no es el de RoboStack, o install/setup.sh menciona /opt/homebrew. Carga tools/macos_env.sh (limpia las variables de Homebrew) y vuelve a compilar.

• En macOS, option --editable not recognized. Falta el truco de setuptools<80 descrito arriba.

• En macOS aparece no such file or directory ... ros2-argcomplete. Es un aviso del autocompletado; puedes ignorarlo.

Cómo seguir la guía

Cada paso de la guía repite el mismo ciclo:

1. Lee la explicación de la página y juega con sus gráficos.

2. Escribe el código en tu editor, dentro de src/my_open/my_open/.

3. Prueba con pytest. Las pruebas de cada paso son Python puro, sin ROS ni Gazebo:

   python3 -m pytest course/tests/test_step_1.py

   En macOS, antepón PYTEST_DISABLE_PLUGIN_AUTOLOAD=1.

4. Comprueba en Gazebo con el script de verificación (python3 course/verify_step.py N, pasos 1 a 6), o lanzando una ronda con tu estrategia:

   ros2 launch robotek_course round.launch.py strategy:=my_open gui:=true direction:=ccw

5. Compara con la referencia: bash tools/compare-step.sh N.

Las rondas se guardan en ~/robotek_runs/ y los puntos son una estimación de simulación con las reglas publicadas, no una puntuación oficial. Los problemas de instalación más comunes están en la sección anterior.

Resumen

• Instalaste ROS 2 Jazzy y Gazebo, compilaste el repositorio y lanzaste el simulador con ros2 launch robotek_course sim.launch.py.
• Cada terminal nueva necesita su source (install/setup.bash en Ubuntu, tools/macos_env.sh en macOS).
• Tu código va en src/my_open, un paquete aparte que git ignora; la referencia de cada paso está en la rama solutions.

Antes de seguir

• ros2 pkg list | grep robotek muestra los seis paquetes y el coche aparece en Gazebo.
• Conduces el coche con keyboard_drive y ves el LiDAR en RViz.
• ros2 run my_open drive imprime Hi from my_open..