Configuración del grafo de control

01Panorama

El grafo es un lazo de control compilado con LangGraph que corre a LOOP_HZ = 5.0 (período nominal 200 ms). Cada ciclo captura un fotograma y telemetría, estima el campo de obstáculos por flujo óptico, elige una macro-acción y la traduce a un comando de velocidad en body frame. En paralelo, una capa estratégica propone rodeos como sub-metas en coordenadas del mundo. Su fuente es configurable (STRATEGIC_SOURCE): en la configuración final es una red de profundidad monocular estimada desde el mismo RGB; el VLM queda en la planificación de ruta previa al vuelo.

Cuatro principios estructuran la configuración:

1. Dos lazos desacoplados. El lazo rápido (guiado, evasión por flujo óptico, GIRAR_90, detección de atasco) es el único que comanda velocidades. La capa estratégica corre en un lazo lento y asíncrono (~110 ms con la profundidad, ~0.8 s con el VLM local) y nunca detiene al dron en vuelo normal.
2. La respuesta es válida cuando llega. Cada pedido guarda la pose del fotograma (ancla); la respuesta se traduce con esa pose, no con la actual, y se expresa en rumbos absolutos, no en «izquierda/derecha» del cuerpo. El resultado es una sub-meta en el mundo que el guiado normal persigue.
3. La fuente decide; las reglas no la reescriben. No hay reglas deterministas sobre la respuesta de la red o del modelo. El fallback determinista existe solo ante falla (timeout, formato inválido, rotación imposible durante un barrido).
4. Sin profundidad del simulador. Ni el grafo, ni main.py, ni experiments/runner.py leen el canal de profundidad de AirSim, ni para control ni como métrica. Toda la percepción del lazo rápido sale de ObstacleField (flujo óptico monocular). La profundidad estimada desde el RGB sí se usa en el lazo lento: es lo que haría una red a bordo de un dron sin sensor de profundidad.

El brazo se selecciona con AGENT_ARM (slm · fsm · reactive) sobre el mismo pipeline de percepción y la misma cinemática; la estrategia de resolución de atascos, con DEADLOCK_STRATEGY (depth · deep_vlm · blind); la fuente de la capa estratégica, con STRATEGIC_SOURCE (depth · vlm · off). Con depth/depth el VLM no corre durante el vuelo.

02Topología

03El estado DroneState

DroneState es un TypedDict y LangGraph construye los canales del grafo a partir de él. Esto tiene una consecuencia operativa que es parte de la configuración, no un detalle de implementación:

La auditoría de cada consulta del lazo lento queda en deliberations[]: brazo (depth_strategic, vlm_strategic o barrido), prompt (vacío con la profundidad), respuesta cruda (con la profundidad, el p5 por sector en metros), sub-meta resultante, motivo, latencia y si adhirió al esquema. El fotograma de cada consulta se guarda como photo-*.png. El capítulo 4 del informe describe cada archivo de una corrida (traza JSONL con el DroneState completo, CSV, resúmenes, DistMin, videos) y el visor HTML que los sincroniza por ciclo.

04El lazo externo

No todo vive en el grafo. El orden por ciclo en main.py (y en experiments/runner.py) es:

Los pasos 8b y 9 son exactamente los que dependen de la regla de declaración de la sección 3.

05Nodos

spatial_scan · pre-vuelo, fuera del grafo

Antes del primer ciclo, run_initial_scan() rota al dron detenido y propone un rumbo de arranque; si difiere más de 90° del rumbo al primer waypoint, emite un aviso para revisar el plan de misión. Es consultivo: nunca reemplaza al ObstacleField por ciclo.

capture_node

Guarda el fotograma y la telemetría anteriores, captura RGB + telemetría de AirSim y marca degraded = True si no hay imagen o la telemetría no proviene del simulador. Mantiene el historial de fotogramas (VLM_FRAME_HISTORY_SIZE = 1) con su marca de tiempo. No captura profundidad.

degraded_hover_node

Sin datos no se mueve: emite FRENAR con estado degradado. No consulta al VLM.

perception_node

FlowTTCEstimator: flujo óptico denso (DIS) sobre el par de fotogramas, derotación por la telemetría de actitud, foco de expansión y TTC por celda. Produce ObstacleField (grilla 3×3 con ocupación, TTC, divergencia y confianza), estimated_ttc y un resumen textual. Es la única fuente de percepción del lazo rápido.

navigate_node

Contiene la política de los tres brazos. Para reactive delega en reactive_node; para fsm, en fsm_node (máquina de estados determinista que comparte el barrido de la sección 8 si DEADLOCK_STRATEGY es depth o deep_vlm); para slm, ejecuta las 8 reglas de la sección 6.

• reactive_node: guiado nominal hacia el objetivo activo (MANTENER_RUMBO), con la tasa de guiñada acotada cerca de un obstáculo.
• evasive_node: corrección lateral hacia el sector con menor ocupación y mayor TTC, o continuación de la maniobra comprometida (anti flip-flop).
• GIRAR_90: giro en el lugar hacia el lado del waypoint cuando un muro ocupa más del 60 % del campo visual; adelanta la consulta a la capa estratégica.

motor_node

• Ancla de altitud en FRENAR: un vz = 0 reemitido es un controlador de velocidad, no de altura; el motor corrige la deriva hacia la altitud de anclaje (zona muerta 0.3 m, Kp 0.35, tope 0.8 m/s).
• Gobernador de velocidad: sin evidencia perceptual o tras un bloqueo reciente, limita vx de MANTENER_RUMBO (1.0–1.5 m/s) y luego lo libera en rampa.
• Actuación no bloqueante: execute_velocity() con last-command-wins; exactamente un comando por ciclo.

06Lazo rápido: navigate (brazo slm)

Antes de la cascada, en cada ciclo: StallDetector.update() y StrategicLayer.tick(). El segundo nunca comanda velocidades: envía un pedido si corresponde, o procesa una respuesta y deposita una sub-meta en inject_corner. Durante el despegue vertical (guidance.takeoff) los tres brazos usan reactive_node: el dron sube en el lugar, sin evasión por flujo ni conteo de atasco. Fuera del despegue se evalúa, en orden, la primera regla que aplica:

StallDetector: señales de atasco

Las reglas 3, 4, 5, 7 y 8 forman el lazo rápido común en espíritu a los tres brazos —misma percepción, mismo action_to_command()—, de modo que la comparación entre brazos mide quién decide los rodeos y los deadlocks, no quién reacciona mejor a un muro inminente.

07Capa estratégica

Implementada en vlm_strategic.py. Corre en un hilo aparte a través de DeliberationService; el lazo nunca espera su respuesta. La pregunta —qué sectores de una grilla 3×3 están libres— la responde la fuente de STRATEGIC_SOURCE; las dos fuentes devuelven la misma estructura, de modo que el ancla y la traducción a sub-metas son las mismas.

Ancla y sincronización

Cada pedido guarda la posición, el yaw y el waypoint del momento de la captura. Cuando la respuesta llega, la sub-meta se calcula con esa pose, de modo que es correcta aunque el dron haya girado o avanzado mientras el modelo pensaba. Se descarta, con su motivo registrado, si:

• tiene más de VLM_STRATEGIC_MAX_AGE_S (10 s);
• el waypoint de misión cambió;
• la sub-meta quedó a menos de VLM_SUBGOAL_MIN_AHEAD_M (4 m) por delante del dron, es decir, ya fue superada;
• la respuesta no cumple el esquema (no_parseable): nunca se sustituye por un valor por defecto.

Al entrar en deadlock, cualquier consulta estratégica en vuelo se cancela: el barrido es más reciente y su sub-meta no debe ser pisada por una respuesta más vieja.

08Resolución de deadlock

Barrido panorámico (DEADLOCK_STRATEGY=depth, default, o deep_vlm) — deep_scan.py

1. Rotación: el dron gira en el lugar a SCAN_HEADING_COUNT_DEEP = 4 rumbos (frente, derecha, atrás, izquierda), se asienta 2 ciclos en cada uno y captura un fotograma. Si no alcanza el rumbo en 10 ciclos (2 s), el barrido se abandona.
2. Juicio de cada rumbo: con depth, la red estima la profundidad de cada fotograma y el rumbo es transitable si el p5 del sector central (B2) es ≥ 15 m (AUC 0.87 en el banco; en TownSim resolvió 19 de 30 deadlocks). Con deep_vlm, una sola consulta con las imágenes numeradas (≤ 256 px). Para cada una, el modelo indica tipo (libre, fachada, muro, vegetación, interior, indeterminado), ok (se puede volar recto 15 m) y conf. El modelo nunca reporta ángulos.
3. Geometría: el código asigna a cada imagen el yaw medido al capturarla y calcula el rumbo a la meta desde las posiciones. La salida es una sub-meta a 15 m como máximo (sin pasar del waypoint real) sobre el rumbo transitable más cercano a la meta, con la misma función que la capa estratégica (subgoal.build_subgoal) y a la altitud actual.
4. Salida del deadlock: se descartan los rumbos a menos de 45° del que falló (hacia el objetivo activo) o de uno ya probado en un deadlock a menos de 10 m; con deadlocks repetidos se elige el rumbo libre más distinto de lo ya probado; si no queda ninguno, GANAR_ALTURA. La selección completa queda en _deadlock_event.scan_selection.
5. Sin rumbo transitable: GANAR_ALTURA (con el VLM, PERDER_ALTURA si todo es vegetación).

Al resolverse, se reinician el StallDetector y el contador de progreso del tracker (_escape_reset).

Falla del barrido o estrategia blind

Watchdog del barrido (SLM_DEEP_WATCHDOG_MS = 18 000 ms, menor que el timeout HTTP de 20 s), formato inválido o rotación imposible: escape determinista GANAR_ALTURA durante 1.6 s; por encima de MAX_ESCAPE_ALT_M (30 m), GIRAR_90 hacia el waypoint. Se registra un _deadlock_event con fell_back_to_blind = True.

09Cinemática por macro-acción

action_to_command() es la única fuente de verdad; el lazo rápido, la fsm, el barrido y los escapes la comparten. Body frame, NED (vz negativo = sube).

^† 0.3 m/s si hay estructura cercana al frente.  ^‡ El signo lo fija el lado del waypoint.  ^§ Acotado a 5 °/s cerca de un obstáculo.  ^¶ Más la corrección del ancla de altitud del motor.  Toda acción desconocida cae a FRENAR.

Duración de las maniobras comprometidas: EVADIR_* 2.0 s (MANEUVER_DURATION_S), GANAR_ALTURA/PERDER_ALTURA 1.6 s, GIRAR_90 1.0 s. El snap Manhattan redondea el rumbo objetivo al múltiplo de 90° más cercano, alineando las maniobras con la cuadrícula urbana.

10Umbrales y variables

Fuente única: config/.env. Detalle completo en el Anexo 6 del informe.

Percepción y lazo rápido

Atasco y escape

Capa estratégica del VLM

Los umbrales de la capa estratégica son decisiones de diseño; todavía no están calibrados en vuelo.

11Invariantes

Lo que la configuración garantiza, y dónde se verifica:

246 tests, sin AirSim (stub con la misma interfaz):

python -m pytest tests -q

12Limitaciones conocidas

• Validación en vuelo limitada. La capa estratégica y el barrido tienen dos lotes de vuelo (CitySim y el corredor arbolado de TownSim, 25 corridas, 5 semillas por celda); sus umbrales son decisiones de diseño, no valores calibrados, y la comparación entre brazos con el sistema final (lotes D, E y F) está pendiente.
• El VLM no discrimina en primera persona. En el banco de prueba a bordo, LFM2.5-VL-1.6B no distinguió sectores volables de bloqueados (AUC 0.53) y declaró transitables todos los rumbos del barrido. Por eso la capa y el barrido usan la profundidad estimada; el VLM aporta solo en el plan de ruta sobre el mapa cenital (AUC 0.81).
• Punto ciego del foco de expansión. El flujo óptico traslacional se anula en los obstáculos centrados en la trayectoria. Las señales de contacto, la detección de atasco y la profundidad estimada del lazo lento lo mitigan; la solución estructural sigue siendo un canal de profundidad instantánea (Anexo 7).
• El TTC no es confiable durante el propio escape. FRENAR no produce traslación (sin flujo → sin FOE → sin evidencia) y el ascenso puro produce flujo vertical con FOE espurio. Por eso las maniobras de escape se comprometen por duración y no se re-evalúan con el TTC.
• La derotación no está validada para yaw fuerte. El dataset de calibración quedó casi todo en el bin |yaw_rate| ∈ [0, 0.05) rad/s.
• vy es siempre 0 en el guiado nominal. El desplazamiento es puramente frontal + yaw (estrategia car-like); no hay vuelo lateral coordinado.
• El barrido depende de un único juicio, sin verificación cruzada. El watchdog y el esquema estricto cubren timeout y formato inválido, pero un juicio válido y erróneo se ejecuta igual: la red de seguridad es el resto del lazo, no una segunda opinión. Los errores de la profundidad estimada fueron conservadores en el banco (2 % de libres con un obstáculo a menos de 5 m).

Referencias

• airsim-loop/GRAFO-DE-CONTROL.md — esta referencia, versionada junto al código.
• src/agents/graph.py — topología, DroneState y reglas del lazo rápido (secciones 2, 3 y 6).
• src/agents/vlm_strategic.py — capa estratégica del VLM (sección 7).
• src/agents/deep_scan.py — barrido panorámico en marco mundo (sección 8).
• src/agents/stall_detector.py — señales de atasco (sección 6).
• Yang et al. (2024), Depth Anything V2 — red de profundidad de la capa estratégica y del barrido; capítulo 6 del informe, §6.14.
• Informe, capítulo 5 — arquitectura del lazo táctico; capítulo 9 — modos de falla y mecanismos de contención.