Middleware ZMQ

El middleware es la parte del coordinador de la NUC que mueve mensajes: los cuatro canales ZeroMQ con el visor y los dos puentes serie hacia las placas embebidas.

Sinopsis

Qué es

Código dentro del coordinador de la NUC, no un programa aparte. Abre cuatro puertos ZeroMQ, uno por tipo de dato, y mantiene dos puertos serie. Esta página lo describe desde dentro de la NUC; el contrato entre subsistemas, con la tabla de puertos verificados, está en Comunicaciones del sistema.

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

Archivos

Archivo

Coordinador de la NUC — nuc_master_code.py

80 KB

Cómo funciona

Tres decisiones de diseño gobiernan el 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.

Conexiones

Los canales que el middleware atiende: ZeroMQ hacia el visor y serie hacia las dos placas que reciben órdenes directas de la NUC.

1. NUCcoordinador · Python 3.12
2. Meta Quest 3cliente Unity
3. ZMQ por WiFiMeta Quest 3 → NUC: 5002 · cmd JSONNUC → Meta Quest 3: 5555 · 5001 · 5007
4. Puente H maestrotracción y manipulador
5. COM4 · 115 200 baudNUC → Puente H maestro: POSE {base} {codo} {muneca}Puente H maestro → NUC: estado
6. Controlador del gripperpinza
7. COM5 · 115 200 baudNUC → Controlador del gripper: m {mm}Controlador del gripper → NUC: GRIPPER_STATE

Protocolo

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.

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.