ADCS-CUBESAT y cómo usa fiil/test_seu

1. Resumen

2. Los dos repositorios

VHDL/
├── fiil/test_seu/            genérico: run_sim.py, tb/, utils/, matlab/
└── fiil-examples/
    └── ADCS-CUBESAT/
        ├── rtl/      controlador_adcs.vhd + config_sim_controlador_adcs.yml
        ├── sim/      sistema_adcs_tcp.py + config_planta_adcs_tcp.yml + results/
        ├── matlab/   adcs_simulink.slx, adcs_simulink_vhdl.slx, adcs_script.m
        ├── doc/      artículo y revisión del modelo
        └── Makefile  TOP=controlador_adcs  PLANTA=sim/sistema_adcs_tcp.py

Si fiil no está clonado junto al ejemplo, el Makefile lo clona (make fiil).

3. Qué hace el ADCS

Por cada muestra (cada TS = 10 ms) el controlador calcula el par de control que se aplica a las ruedas:

tau = −Jd .* (M(φ, θ) · a_des) = neg_alpha .* (M · a_des)

M = [1,  0,      −sin θ;
     0,  cos φ,   cos θ·sin φ;
     0, −sin φ,   cos θ·cos φ]

a_des es la aceleración angular de Euler que pide el PID de cada eje.

Arquitectura del controlador VHDL (controlador_adcs.vhd)

Máquina de estados del top

Los resultados u_x/y/z se actualizan unos 13 ciclos de reloj después de la muestra y se mantienen hasta la siguiente.

4. Cómo funciona una campaña

1. make sim arranca el servidor, que espera al cliente hasta timeout_conexion_s (300 s) en el host:puerto del .yml de la planta.
2. El cliente (cliente_tcp o make cliente-matlab) simula adcs_simulink_vhdl.slx sin ritmo de tiempo real: cada TS envía los sensores, Simulink se detiene, espera la respuesta y aplica el par ts_act_s después.
3. Guarda los mensajes (en_cli_/re_cli_) y los To Workspace (senales_cosim_<sim>.mat) en sim/results/.
4. Como el .yml tiene modelo_referencia, después simula adcs_simulink.slx y dibuja phi_0, tau y ECM: arriba Simulink, abajo VHDL.
5. Opcional: make comparar-tcp compara los mensajes del servidor y del cliente.

Cada campaña necesita lanzar el cliente otra vez.

5. Qué piezas de test_seu usa el ADCS

6. Protocolo TCP y flujo del código

Se envía un JSON por línea. Mensajes: start (servidor→cliente), muestra (cliente→servidor), respuesta (servidor→cliente), fin y fin con error. Las magnitudes se escalan con un exponente en base 2 para pasarlas a coma fija. El cliente usa readline bloqueante con timeout_respuesta_s.

Ventanas: N = TS / ts_act_s; en el ADCS, TS = 10 ms y N = 20, es decir ts_act_s = 0,5 ms. La ventana 1 es la salida del cálculo; la ventana j se aplica en t_muestra + j·ts_act_s.

7. Modo muestreado y modo continuo

8. SEU, estabilización y cálculos colgados

• Dónde inyecta: en los biestables de la lista generada desde el netlist de Yosys (transitorio o permanente).
• Cuándo termina el cálculo: el testbench da flancos de reloj tras cada muestra o SEU hasta que considera que el circuito se ha estabilizado; entonces salta sin simular hasta el siguiente suceso. El criterio se elige con la clave fin_de_calculo (cuatro modos, en la tabla siguiente).
• Cálculo colgado: un SEU puede causar que el circuito no se estabilice. Se detecta cuando el cálculo no termina en max_ciclos_estable ciclos o antes del siguiente suceso, en cualquiera de los cuatro modos. Entonces se lanza CalculoColgado, se llama a abortar(), el servidor envía fin con error y la referencia se simula solo hasta el último instante válido. La campaña figura como ABORTADA, un resultado válido con sus CSV guardados.
• Tiempo: el testbench distingue tiempo virtual y tiempo de GHDL.

Los cuatro modos de fin_de_calculo

Indican cómo decide el testbench que el circuito ya se ha estabilizado y se puede leer su salida.

Bit-flip en reposo: tras inyectarlo se da un ciclo. Si ha cambiado el estado vigilado, el SEU ha lanzado un cálculo y se sigue con el criterio de fin_de_calculo; si no, se sigue con el criterio biestables, de modo que un fallo en un registro de datos no se da por inofensivo tras un solo ciclo.

9. Configuración: los ficheros .yml y el generador de configuración

Una simulación no se programa: se describe en dos ficheros .yml. Cada uno contiene un bloque común y una entrada por campaña (sim_1, sim_2…), de modo que con un mismo circuito se definen tantas configuraciones como se quiera y make sim las lanza una detrás de otra.

Elegir cómo y dónde caen los SEU

• Clave seu: aparicion (siempre | nunca | aleatoria | periodica), probabilidad_muestra, patron (lista de 0/1 que se repite) y, solo en muestreado, probabilidad_ciclo. Como mucho hay un bit-flip por muestra; sin la clave no se inyecta ninguno.
• Qué biestables pueden fallar: biestables_incluidos/excluidos y componentes_incluidos/excluidos (por entidad o por instancia: controlador_pid, seno_coseno, calc_sen_cos_phi, acoplador…). Gana la regla más específica: biestable > instancia > entidad. El controlador completo tiene 1408 bits.
• Otros: modelo_fallo (transitorio o permanente), max_ciclos_estable y un fin_de_calculo propio por campaña.
• Comprobaciones: si falta una clave obligatoria o un valor no es válido, run_sim.py se detiene al arrancar, antes de simular, y dice qué clave está mal. Una errata en una clave opcional se avisa con la clave más parecida.

La “aplicación de configuración”: generar_config (make config)

Crea el .yml de campañas en blanco leyendo solo el texto de los .vhd (sin GHDL ni Yosys). Escribe una campaña sim_1 con todas las claves posibles: las obligatorias salen vacías y marcadas con # OBLIGATORIO, y las opcionales comentadas, listas para descomentar. En comentarios VHDL: añade lo que encuentra: puertos con tipo y ancho, generics con su valor por defecto, señales internas con la ruta de la instancia y una propuesta de reloj y reset.

make config                      # rtl/config_sim_controlador_adcs.yml en blanco
make config NOMBRE=config_sim_otro FORZAR=1
# equivale a:
python3 <fiil>/test_seu/utils/generar_config --top controlador_adcs \
        --planta sim/sistema_adcs_tcp.py rtl/*.vhd

• Con --planta también genera sim/config_planta_<top>.yml con los parámetros de la planta y deja el .yml del rtl con testbench: tb_seu_eventos, porque la planta define respuesta().
• Si los ficheros ya existen no los toca; solo los sobrescribe con FORZAR=1.

10. Representar resultados con app_grafica

app_grafica es un visor Qt (PyQt5 o PySide6 + matplotlib + pyyaml) de los CSV que deja la simulación en sim/results/. A diferencia de dibujar un CSV suelto, combina varios CSV en la misma ventana, dibuja las señales binarias bit a bit y trabaja sobre una ventana de tiempo.

make graficas                       # lee sim/results
make graficas RUTA=otra/carpeta     # lee los CSV de otra carpeta
# equivale a: python3 <fiil>/test_seu/utils/app_grafica [carpeta]

Pasos

1. Agregar gráfica abre la ventana de selección con la lista de CSV de la carpeta (y la casilla Representar todo).
2. Por cada CSV marcado aparecen sus señales (sin la columna de tiempo). Se marcan las deseadas y, si hace falta, se cambia su tipo: binario, signed, unsigned o real. Por defecto se deduce del .yml (listas signed/unsigned) y de los valores del CSV.
3. Representar dibuja una gráfica por señal, con el tiempo en ns en el eje x. Las binarias muestran una fila por bit (el más significativo arriba).
4. Desde (ns) y Hasta (ns) fijan la ventana de tiempo (Intro o Aplicar). Al principio se ven las 200 primeras muestras.

Herramientas

Qué mirar en el ADCS: las señales de puertos u_x/y/z (el par tau) y tvalid, la señal binaria colgado (0/1) para ver cuándo se abortó una campaña, y el CSV de fallos para relacionar cada SEU con su efecto. La comparación completa Simulink vs VHDL (phi_0, tau, ECM) la dibuja MATLAB con comparar_modelos, no esta aplicación.

11. El Makefile del ADCS

Se ejecuta desde ADCS-CUBESAT/ (run_sim.py escribe en el sim/results/ del directorio de trabajo) y necesita un shell POSIX (Linux, WSL o Git Bash). Contiene solo lo propio del modelo y apunta al resto de fiil. make sin argumentos muestra la ayuda.

Variables principales

Todas se pueden sobrescribir: make sim CONFIG=rtl/config_sim_otro.yml, make sim FIIL_DIR=/ruta/a/fiil.

Objetivos, en el orden del flujo

Dependencias

VHDL ──► netlist (rtl/netlist.json) ──► biestables (lista .json) ──► make sim
make sim ◄── TCP ──► make cliente-matlab         (una vez por sim_X)
sim/results/*.csv ──► make graficas · make comparar-tcp · make zip-results

Make solo rehace el netlist si cambia algún .vhd, y la lista de biestables si cambia el netlist. Si cambias un ancho (data_width), actualiza a la vez GENERICS y los generics del .yml.

12. Cómo lanzarlo

# Terminal 1: servidor, todas las campañas
make sim
# Terminal 2: cliente de UNA campaña
make cliente-matlab
# Opcional
make comparar-tcp
make graficas RUTA=sim/results
make comprobar CON_MATLAB=1