Middleware ZMQ

El proceso coordinador de la NUC usa ZeroMQ con cuatro puertos, uno por tipo de dato. Esta página los describe desde dentro del sistema —cómo los abre y los atiende el coordinador—; el contrato entre subsistemas, con la tabla de puertos verificados, está en Comunicaciones del sistema.

Nivel de replicación

Reproducible

Están los archivos de fabricación. Puedes producir una copia idéntica sin rediseñar nada.

Lo que encuentras aquí

• Código fuente completo del coordinador, 2409 líneas
• Puertos, tópicos y esquema de comandos con sus frecuencias
• Dependencias de Python y hardware necesario
• Todos los parámetros de red, watchdog y puentes serie

Lo que falta

• Versiones exactas de las dependencias: el código no trae requirements.txt ni fija versión de ultralytics, pyrealsense2 u OpenCV
• Script de arranque automático al encender la NUC

Artefacto

Coordinador de la NUC — nuc_master_code.py

80 KB

Cómo se ejecuta

El coordinador es un único proceso de Python que abre los cuatro puertos ZeroMQ, conecta los sensores y mantiene los dos puentes serie. No hay orquestador ni servicio: se lanza a mano.

Dependencias del coordinador

Paquete	Para qué	Nota
pyzmq	Los cuatro canales ZeroMQ	Núcleo del middleware
opencv-python	Compresión JPEG y morfología del pipeline de paredes	Se importa como cv2
numpy	Grids, máscaras y nubes de puntos	—
pyrealsense2	RealSense D435i	Requiere el SDK de Intel instalado
ultralytics	YOLO en los modos pose y segmentación	Descarga los pesos la primera vez
pyserial	Puentes COM4 y COM5	Import opcional: sin él, el arranque no falla
rplidarc1	RPLiDAR C1	Con respaldo a un módulo scanner local

El código tolera que falten pyserial y el módulo del LiDAR: los envuelve en try/except y arranca igual, sin ese periférico. Eso permite desarrollar la parte de percepción o de red sin el robot conectado.

Los puertos serie están fijados en el código (COM4, COM5, COM3), no son configurables por argumento ni por variable de entorno. En otra máquina hay que editarlos.

Puertos

Puertos ZMQ del middleware de la NUC

Puerto	Rol NUC	Rol Unity	Tipo
5555	PUB	SUB	Video — frames JPEG comprimidos
5001	PUB	SUB	Sensores y estado — JSON por tópico
5002	SUB	PUB	Comandos desde Unity hacia la NUC
5007	PUB	SUB	Paredes y puntos LiDAR — datos binarios

Tres decisiones de diseño gobiernan este reparto:

• Puertos separados por tipo de dato. El video y los datos binarios no pueden bloquear el canal JSON, que es el que lleva el estado y los comandos.
• Streaming selectivo. Cada modo publica solo mientras está activo, así que un sensor apagado no cuesta ni CPU ni ancho de banda.
• High watermark por canal. Cada puerto tiene su propio límite de cola, y la diferencia entre ellos es deliberada.

High watermark de envío por canal

Parámetro	Valor	Unidad	Notas
Video (5555)	2	mensajes	Un frame viejo no sirve: mejor descartarlo que acumular retraso
Sensores y estado (5001)	300	mensajes	JSON pequeño; conviene no perder eventos de estado
Paredes y puntos (5007)	50	mensajes	Punto medio: paquetes grandes, pero tolera algo de cola

El límite de 2 en video es lo que mantiene la teleoperación utilizable. Con una cola profunda, el operador vería frames cada vez más viejos conforme la red se degrada, en lugar de perder algunos y seguir viendo el presente.

Tópicos JSON (puerto 5001)

Tópico	Frecuencia	Contenido
stat	~2 Hz	Estado global: sensores OK, modos activos, ángulos del manipulador, gripper_mm
mode_ack	Al cambiar modo	Confirmación de cambio de modo
lidar_grid	~12 Hz	Grid de ocupación linealizado del modo activo
manip_state	~4 Hz	Ángulos actuales del manipulador y finales de carrera
gripper_state	~4 Hz	Posición del gripper en mm, busy, calibrated
vision	~10 Hz	Resultados YOLOv8 (pose o segmentación)
cam_info	Continuo	Intrínsecos de la RealSense y escala de profundidad

Comandos (puerto 5002)

Todos los comandos viajan como JSON. Estos son los más relevantes, agrupados por función:

Familia	Ejemplo
Modo de percepción	{"type": "set_camera_mode", "mode": "normal|pose|segment|off"}
Habilitar control	{"type": "master_arm"} / {"type": "master_disarm"} / {"type": "stop_all"}
Base móvil	{"type": "drive_cmd", "v": 0.5, "w": -0.3, "enabled": true}
Manipulador	{"type": "manip_cmd", "q": [base_deg, codo_deg, muneca_deg]}
Gripper	{"type": "gripper_cmd", "opening_mm": 30.0}

drive_cmd usa modelo uniciclo: la NUC mezcla v/w y envía al Puente H maestro a 15 Hz.

Parámetros de mando y seguridad

Valores que gobiernan el mando y sus paros

Parámetro	Valor	Unidad	Notas
Envío de tracción al maestro	15	Hz
Timeout de drive_cmd	0,35	s	Sin comando nuevo, la tracción se detiene
Zona muerta del joystick	0,08	—	Evita deriva por reposo impreciso del control
Consigna máxima al puente H	255	crudo
Timeout de heartbeat de comandos	2,0	s
Consulta de estado al manipulador	4	Hz
Consulta de estado al gripper	4	Hz
Envío de comandos al gripper	20	Hz
Reintento de reconexión serie	1,0	s

Los dos timeouts cubren fallos distintos. El de drive_cmd (0,35 s) actúa cuando el operador deja de mandar pero la conexión sigue viva. El de heartbeat (2 s) actúa cuando se cae el enlace entero.

Puentes seriales

Puentes serie de la NUC hacia la electrónica embebida

Puerto	Baudrate	Destino	Ejemplo de comando de salida
COM4	115 200	Puente H maestro — base y manipulador	POSE {base} {codo} {muneca}
COM5	115 200	Controlador del gripper	m {mm}

Estado

Funcionalidad	Estado
Streaming video, grid LiDAR, stat	Verificado
Cambio de modos cámara/LiDAR desde Unity	Verificado vía mode_ack
Control de base móvil y manipulador	Implementado
Telemetría de manipulador y gripper	Implementada
Watchdog de timeout de drive_cmd (0,35 s)	Implementado
Watchdog de conexión ZMQ con paro seguro	Pendiente