# Manual de uso — BotLab Studio EV3 Pybricks

Base de versión: 1.5.0
Revisión documental: 2026-10-28, copia cloud de remediación.
La identidad exacta de cada entrega está en su manifiesto de archivos.

Esta revisión no acredita un despliegue ni una liberación completa. El corte
integra reparaciones con evidencia focal y una campaña de ejecución de programas,
con revisión independiente focal favorable de H-WEB2 V2 y de clasificación
causal de timeout. El rollback de arranque parcial y la fluidez de impresión
continua tienen correcciones revisadas independientemente. El estado del resto
de casos y las reservas se detallan en el informe del corte entregado; no se
declara aprobación global. Las instrucciones Web describen la candidata; las secciones de
escritorio son referencia histórica no revalidada.

## 1. Objetivo

Este programa permite:

- Escribir y ejecutar el subconjunto de Python/Pybricks documentado para el corte.
  Una importación correcta no acredita todos los comportamientos del robot.
- Simular el robot EV3 en un mundo 2D.
- Crear y editar mundos personalizados con el Editor de Mundos EV3.

## 1.1 Estado de interfaces

- La Web es la referencia de diseño, etiquetas, orden de controles y estados.
- La interfaz Tkinter pertenece a otra superficie de uso. La remediación Web
  no vuelve a acreditar su paridad funcional o visual.
- La paridad es un objetivo de proyecto que requiere pruebas de ambas interfaces,
  no una consecuencia automática de modificar la Web.

## 2. Uso Web con Flask

La versión web separa dos funcionalidades que antes estaban juntas en la aplicación de escritorio:

- **Simulación del robot**: `http://127.0.0.1:5050/`
- **Creación de mundos**: `http://127.0.0.1:5050/worlds`

Esta separación evita ejecutar código mientras se está construyendo un mundo y permite que cada flujo tenga controles propios.

### 2.1 Iniciar el servidor web

Los comandos Windows que siguen pertenecen a la distribución completa anterior.
La copia Web auditada no incluye `scripts/start_web.cmd` ni los scripts de parada;
no asumir que existen en este paquete. Para el runner y los requisitos Linux,
consultar `GUIA_DESPLIEGUE_LINUX.md`. No iniciar ni reconfigurar un servicio
compartido sin autorización del responsable.


Desde PowerShell:

```powershell
cd <ruta-del-repositorio>
.\scripts\start_web.cmd
```

Si Windows bloquea la ejecución de `.ps1`, usar:

```powershell
.\scripts\start_web.cmd
```

Abrir en el navegador:

```text
http://127.0.0.1:5050/
```

### 2.2 Página de simulación

Ruta: `http://127.0.0.1:5050/`

Funciones:

- Escribir o cargar código Pybricks.
- Seleccionar ejemplos desde `examples/`.
- Seleccionar presets de sólo lectura y mundos privados accesibles al workspace
  del navegador; no existe una carpeta global de guardados de alumnos.
- Ejecutar, pausar y reanudar simulación.
- Detener y reiniciar simulación con un único botón: `Detener y reiniciar`.
- Ver canvas, telemetría, motores, sensores, LED y pantalla EV3.
- Usar depuración con breakpoints, step y continue.
- Ver resaltado de la línea actual durante depuración.
- Ubicar robot desde el canvas y ajustar `theta`.

La página de simulación no incluye controles para crear o editar mundos.

Nota: cuando un script finaliza naturalmente, la sesión publica `finished` y
conserva el estado final visible. Usa `Detener y reiniciar` para iniciar un
nuevo ciclo de simulación.

### 2.3 Página de creación de mundos

Ruta: `http://127.0.0.1:5050/worlds`

Funciones:

- Crear un mundo nuevo.
- Colocar robot, muros, líneas, zonas y pisos.
- Mover, rotar, duplicar y eliminar assets.
- Arrastrar assets directamente sobre el canvas.
- Editar propiedades de asset desde el panel lateral.
- Definir pose inicial del robot.
- Validar el mundo.
- Importar y exportar JSON.
- Guardar mundos privados cuando el workspace está habilitado.
- Descargar una copia JSON portable con `Guardar como`; comprobar su descarga.

La página de mundos no incluye editor de código ni botones para ejecutar la simulación.

### 2.4 Flujo recomendado web

1. Abrir `http://127.0.0.1:5050/worlds`.
2. Crear el mundo y colocar los assets requeridos.
3. Colocar el robot o definir su pose inicial.
4. Validar el mundo.
5. Leer el aviso de almacenamiento, descargar una copia JSON y, si el guardado
   privado está habilitado, guardar con un nombre nuevo, por ejemplo `prueba_lineas`.
   No sobrescribir un preset; guardarlo con otro nombre.
6. Usar el enlace **Simular mundo guardado**.
7. La simulación abre `/?world=prueba_lineas.json` dentro del mismo workspace
   válido. Compartir esa URL no concede acceso a un mundo privado. Si no hay
   workspace habilitado, conservar el JSON portable; la equivalencia completa
   del recorrido de importación/exportación se valida aparte.
8. Escribir o cargar el script Pybricks.
9. Ejecutar y observar telemetría/canvas.

### 2.5 Sesiones, workspace y conservación del trabajo

Cada pestaña crea una sesión de ejecución con token propio. El workspace es
otra capacidad: una cookie firmada del navegador que permite guardar y reabrir
mundos privados. Dos pestañas del mismo navegador pueden compartir workspace
sin compartir el token de ejecución. No es una cuenta ni identifica al alumno.

Los presets son de sólo lectura. Los archivos privados se conservan separados
del worker y no se borran por cerrar o expirar una sesión. Para reabrir después
de reiniciar se necesitan una cookie válida, la misma clave configurada y el
directorio privado conservado. El valor predeterminado de ese directorio es
temporal: no garantiza durabilidad. Descargar `.py` y JSON es un respaldo
independiente que debe comprobarse.

Sin clave aceptable, el modo `configured` no habilita guardado privado. En el
modo explícito de desarrollo/QA `ephemeral`, la clave sólo vive en memoria y no
hay garantía tras reiniciar o perder la cookie. Producción rechaza ese modo.
Perder la cookie o cambiar la clave puede impedir acceso aunque el archivo siga
en disco; conocer su identificador no lo recupera. El flujo guiado «Crear
espacio nuevo» exige confirmación. Un recorrido visual comprobó que conserva
el borrador y no ejecuta el programa solo; no recupera los archivos antiguos ni
los borra.
Exportar antes el código y cualquier mundo visible que se necesite conservar.

No compartir cookies ni tokens ni usar un perfil de navegador común esperando
separación entre personas. La recuperación entre dispositivos y las cuentas
humanas no forman parte de esta capacidad.

Las sesiones de ejecución no son almacenamiento duradero. Redis o el espejo de
metadatos no conservan un programa Python vivo ni sustituyen una copia de respaldo. El TTL
se basa en actividad aceptada: GET, polling y SSE no lo renuevan. Las acciones
válidas y la señal explícita de interacción sí pueden hacerlo. Es actividad
declarada por el cliente, no prueba de identidad o presencia humana.

### 2.6 Depuración, perfiles y trazas

En la Web se configuran puntos de interrupción y expresiones observadas, se
avanza un paso y se continúa. La fase transitoria de espera tiene corrección
y evidencia focal: mientras se ejecuta un paso, los controles Paso/Continuar
no deben admitir otra acción; al llegar a la pausa siguiente se restablecen
las expresiones observadas. La comprobación visual H-WEB1 usó `wait(3000)`
para observar la transición, distinta del caso original `wait(400)`. No se
extrapola a toda secuencia de doble clic, navegador o dispositivo. Los mensajes
de tránsito están traducidos. El contexto de variables debe corresponder a
una pausa confirmada: consultar el informe de la entrega para la reparación
y verificación del caso de contexto anterior durante un paso en ejecución.

En **Configuración > Precisión de simulación** se eligen los perfiles disponibles. Los
perfiles no sustituyen la calibración de un robot físico; consultar
`Documentos/DIFERENCIAS_SIMULADOR_ROBOT.md` antes de usar una actividad en aula.

En **Diagnóstico > Trazas de simulación** se inicia o detiene el registro y se permite avanzar un tick y
exportar la evidencia en JSON/CSV. Las trazas no dependen de la interfaz usada.

### 2.6.1 Tiempo máximo

El techo predeterminado del servidor es 120 segundos, positivo y finito. La
candidata muestra el techo efectivo y opciones que no lo superan; no ofrece
una ejecución sin límite. El alumno no puede ampliar el techo del servidor.
Una práctica de unos 305 segundos exige un entorno cuyo responsable haya
autorizado y configurado un techo suficiente, por ejemplo 360 segundos. El
supervisor tiene revisión focal con procesos reales. La campaña finita H-WEB1
ejecutó las prácticas largas con límites de QA ampliados; no cambió el techo
predeterminado. La clasificación causal de timeout tiene revisión independiente
focal favorable; el ciclo de inicio/cierre de hilos se evalúa por separado.

### 2.7 Accesibilidad y teclado

- `Ctrl+N`: crear script.
- `Ctrl+O`: abrir script.
- `Ctrl+S`: guardar script.
- `Escape`: cerrar cuadros de ayuda o acerca de cuando están abiertos.
- Los controles reflejan fases canónicas con comprobación focal del paso en
  espera; no se garantiza por ello toda secuencia, doble clic o dispositivo.
- Teclado completo, lector de pantalla y tamaños móviles no están acreditados
  por esta revisión Web.

La Web es la referencia visual del proyecto. La paridad con Tkinter y la
accesibilidad completa necesitan evaluación independiente.

### 2.8 Tamaño del mapa web

La escala geométrica de la Web se expresa así:

- `32 px = 100 mm`.
- Un mundo de `2000 x 2000 mm` corresponde a `640 x 640 px` internos.
- La vista del editor puede ajustar el zoom para mostrar el mundo completo.
  Sus coordenadas y la geometría guardada no cambian por ese ajuste.
- El área editable se distingue del exterior; el recorrido visual final del
  ajuste y de la pose del robot tiene evidencia focal: guardado, exportación y
  reapertura a 45° en un mundo de 40 × 40 celdas. No acredita todas las dimensiones.

La coincidencia de escala no acredita por sí sola paridad actual con Tkinter.

### 2.9 Detener el servidor web

En PowerShell:

```powershell
.\scripts\stop_web.ps1
```

Alternativa:

```powershell
.\scripts\stop_web.cmd
```

Para reiniciar:

```powershell
.\scripts\restart_web.ps1
```

Alternativa:

```powershell
.\scripts\restart_web.cmd
```

La guía histórica `GUIA_WEB_FLASK_WINDOWS.md` no está incluida en este paquete.
No confundir recursos heredados de una instalación anterior con los presets y
los guardados privados de la candidata; su migración requiere clasificación.

## 3. Aplicación de Escritorio

Las secciones 4 a 10 siguientes corresponden al manual histórico de escritorio
basado en `tkinter`. Se conservan como referencia, no como resultado de QA de la
candidata Web ni garantía de archivos incluidos en esta entrega.

## 4. Ventana Principal

La ventana de escritorio sigue el mismo orden de la página de simulación Web:

- Barra de menús: Archivo, Aprender, Mundos, Prácticas guiadas, Configuración,
  Diagnóstico y Ayuda.
- Barra de simulación: Ejecutar, Pausar, Reanudar y Detener y reiniciar.
- Mundo a la izquierda y editor/depuración a la derecha.
- Telemetría y EV3 Brick debajo del mundo; la telemetría se divide en Robot,
  Motores y Sensores.
- Franja de estado al pie de la ventana.

Los temas Claro y Oscuro, el foco de teclado y los estados deshabilitados usan
la misma semántica de color que la Web. Las diferencias limitadas a bordes,
desplegables y barras de desplazamiento son propias de los controles nativos
de Windows.

### 4.0 Editor de código y colores de sintaxis

El editor identifica palabras clave, nombres integrados, números, cadenas y
comentarios. Los comentarios que comienzan con `#`, incluidos los que aparecen
al final de una instrucción, usan un color propio. Los bloques documentales
entre triples comillas (`"""..."""` o `'''...'''`) se muestran como una única
cadena aunque ocupen varias líneas.

El resaltado se actualiza al escribir y al cambiar entre los temas Claro y
Oscuro; los colores se ajustan para conservar contraste y legibilidad. Un
script incompleto mientras se escribe no bloquea el editor.

### 4.1 Menú Archivo

- `Nuevo script`: limpia el editor para iniciar un script nuevo.
- `Abrir script...`: abre un archivo `.py`.
- `Guardar script...`: guarda el script actual en un archivo `.py`.
- `Salir`: cierra la aplicación.

Atajos:

- `Ctrl+N`: nuevo script.
- `Ctrl+O`: abrir script.
- `Ctrl+S`: guardar script.

### 4.2 Menú Aprender

Carga scripts de ejemplo desde `examples/`, agrupados en Empezar, Movimiento,
Sensores, Control y navegación y Retos avanzados.

### 4.3 Menú Mundos

- `Cargar mundo JSON...`: carga un mundo desde archivo.
- `Editor de mundos...`: abre el editor visual.
- Lista de mundos detectados en `worlds/`.

### 4.4 Menú Prácticas guiadas

Carga combinaciones predefinidas de objetivo + mundo + script. Antes de confirmar
se informa qué recursos cambiarán; si hay cambios sin guardar, puede cancelar sin
perder el programa actual.

### 4.5 Centro de ayuda contextual

El menú `Ayuda > Centro de ayuda...` abre el mismo catálogo de guías de la
Web. Puedes buscar por una tarea o error, filtrar por categoría y abrir el
flujo correspondiente sin tener que recorrer de nuevo los menús. Cada guía
indica requisitos, pasos, resultado esperado y una forma de recuperación.

### 4.6 Diagnóstico de sesión y soporte

En ambas interfaces, `Diagnóstico` concentra `Diagnóstico de sesión`, trazas y
`Exportar diagnóstico JSON`. `Ayuda` contiene `Centro de ayuda`, `Guía rápida:
primera simulación`, `Libro: Programación en Python para robótica (LEGO EV3)` y
`Acerca de`.

El diagnóstico muestra datos técnicos seguros de la sesión actual (estado,
tick, tiempo y worker cuando exista). En la Web añade métricas de renderizado;
en el escritorio se muestra mediante un diálogo nativo. `Exportar diagnóstico
JSON` crea un archivo UTF-8 versionado para soporte. El archivo no contiene el
código del editor, tokens, contraseñas ni credenciales. `Acerca de` queda
reservado para créditos, versión e información institucional.

El enlace del libro abre en el navegador predeterminado y dirige al repositorio
institucional de UTP para la obra escrita por los autores del proyecto:
**Programación en Python para robótica: de la teoría a la práctica con LEGO
EV3**.

Las instrucciones de instalación, despliegue y operación técnica permanecen
separadas en `GUIA_WEB_FLASK_WINDOWS.md`, `GUIA_DESPLIEGUE_LINUX.md` y
`CONTROLES_CALIDAD.md` para no mezclar el aprendizaje del simulador con tareas
de administración.

Para verificar la navegación nativa con ratón en un equipo Windows con sesión
gráfica, instala `.[desktop-e2e]` y ejecuta:

```powershell
$env:EV3_RUN_DESKTOP_E2E = "1"
.\.venv\Scripts\python.exe -m pytest tests/e2e/test_desktop_pywinauto.py -q
```

## 5. Flujo Básico de Uso

1. Carga o crea un script en el editor.
2. Carga un mundo desde `Mundos` o abre `Editor de mundos...`.
3. Coloca el robot en el mapa (clic y orientación).
4. Pulsa `Ejecutar`.
5. Observa telemetría, trayectoria y pantalla LCD.
6. Usa `Detener y reiniciar` para cancelar y restaurar el estado inicial, o
   permite que el programa termine y conserva su snapshot final.

## 6. Colocación del Robot

Antes de ejecutar:

- Haz clic en el mapa para definir `X` y `Y`.
- Arrastra o usa la rueda del mouse para ajustar `theta`.
- La barra informativa muestra coordenadas y orientación.

Convención de unidades:

- Las coordenadas visibles de `X` y `Y` se muestran en `cm`.
- `theta` se mantiene en grados (`deg`).

Al iniciar la simulación, el modo de colocación se desactiva.

## 7. Telemetría

La telemetría muestra:

- Estado del robot (X, Y, theta, colisión).
- Motores A/B/C/D (velocidad, ángulo, estado).
- Sensores S1/S2/S3/S4 (tipo y valor).
- Tiempo/ticks de simulación.

Convención de unidades en UI:

- Distancias visibles (`X`, `Y`, sensor ultrasónico) en `cm`.
- Ángulos en `deg`.
- Velocidad angular de motor en `deg/s`.

## 8. Editor de Mundos EV3

Funciones principales:

- Nuevo, abrir, guardar y guardar como.
- Paleta de objetos (robot, muros, zonas, líneas, fondos).
- Colocación por rejilla.
- Propiedades del objeto seleccionado.
- Validación del mundo.
- Después de guardar un mundo válido, el botón `Simular mundo guardado` lo
  aplica directamente a la ventana principal. No es necesario volver a buscar
  el archivo JSON desde el menú Mundos.

Reglas clave:

- Solo se permite un robot por mapa.
- El robot del mapa define la posición inicial en la simulación.

## 9. Formato de Mundos

Los mundos se guardan en JSON y pueden incluir:

- Dimensiones del mundo.
- Obstáculos y superficies.
- Datos visuales del editor (`editor_spec`).

## 10. Recomendaciones

- Guarda frecuentemente el script y el mundo.
- Usa escenarios para pruebas rápidas.
- Si cambias de mundo, revisa la pose inicial del robot.

## 11. Resolución de Problemas

- Si un script no se ejecuta: revisar errores en la ventana de mensaje.
- Si no ves cambios: confirmar que el mundo correcto está cargado.
- Si la telemetría no cambia: verificar puertos y creación de dispositivos en el script.
- Si la Web parece colgada: consultar `/healthz` con el acceso operativo autorizado;
  un `403` puede ser la política de acceso, y un `200` no demuestra que el programa
  esté sano ni que se hayan liberado sus recursos.
- Si un script corto no termina: verificar que la sesión alcance `finished`; el estado final permanece visible hasta que el usuario reinicie manualmente.
- Si el mapa parece cortado: usar el ajuste de vista o el desplazamiento del
  panel según corresponda; no confundir zoom visual con dimensiones del mundo.

## 12. Centro de ayuda y recorridos guiados

El catálogo y sus capturas se actualizan por separado de este manual. Mientras
una imagen conserve la fecha histórica del 24 de agosto de 2026, no debe
interpretarse como una captura de esta candidata. La imagen de tiempo máximo
se sustituyó por una captura real del 28 de octubre de 2026, con techo de 120 s
y opciones positivas del entorno de prueba; no existe la opción ilimitada.
El texto alternativo, la transcripción, la fecha y la huella se actualizaron
con la imagen. Para guardado,
recuperación y seguridad prevalecen los límites descritos arriba.


El menú **Ayuda** abre el Centro de ayuda en Web y escritorio. Cada guía ofrece
prerrequisitos, pasos marcables, resultado esperado, recuperación y acceso al
destino correcto. El avance se conserva de forma local: no incorpora código,
credenciales ni identificadores de sesión.

Las rutas cubren primera simulación, mundos, motores, sensores, depuración,
misiones, trazas, tiempo máximo y diagnóstico. En Web, las capturas incluyen
texto alternativo y transcripción; en Tkinter se muestran capturas reales de
escritorio con una explicación textual de respaldo.

Para una clase, active **Modo docente**. Propone una práctica de 25 minutos y
la evidencia mínima: captura del mundo, código final, resultado de misión y
explicación de una lectura de sensor. La simulación no reemplaza la validación
en un EV3 físico: confirme puertos, batería, montaje y sensores antes de una
demostración real.

## 13. Versión

Revisión de la copia cloud de remediación del 2026-10-28, basada en `1.5.0`. No se
ha liberado una versión por actualizar este manual. El documento histórico
`ESTADO_ACTUAL_PROYECTO.md` no está incluido en este paquete; consultar el
registro de aceptación de la entrega concreta y no una fecha antigua.