Revisión vigente: 2026-08-05 · versión 1.5.0 · cierre técnico c8e8c3c. La referencia de preparación incluida en el control inferior se conserva como antecedente documental; el estado vigente está en Documentos/ESTADO_ACTUAL_PROYECTO.md.
1. Control documental
Documentos/ANEXO_EXPEDIENTE_DERECHOS_AUTOR.md con datos del titular, commit liberado y capturas finales.2. Producto y alcance
La aplicación de escritorio permite crear o cargar mundos 2D, escribir programas Python con una API Pybricks virtual y observar un robot LEGO EV3 simulado sin necesidad de conectividad ni servidor web.
- Ejecuta scripts en un runtime aislado con control de tiempo y cancelación.
- Presenta canvas, editor de código, telemetría, Brick virtual, LCD, motores y sensores.
- Administra mundos JSON, ejemplos, escenarios, misiones y trazas desde una interfaz Tkinter nativa.
- Comparte el núcleo de simulación, contrato de sesión y catálogos con la aplicación web.
3. Arquitectura técnica
La interfaz no accede directamente al motor. Envía comandos mediante el contrato de sesión y recibe snapshots consistentes del worker aislado.
| Componente | Responsabilidad | Ubicación |
|---|---|---|
| Interfaz Tkinter | Ventana, canvas, editor, menús, Brick y telemetría. | simulador_ev3/ui/ |
| Adaptador de escritorio | Conecta los controles nativos al contrato de sesión. | simulador_ev3/application/desktop_session_adapter.py |
| Contrato y snapshots | Comandos, estados, depuración, errores e idempotencia. | simulador_ev3/application/ |
| Runtime aislado | Ejecuta scripts con IPC, límites y cancelación. | simulador_ev3/runtime/ |
| Dominio y motor | Cinemática, colisiones, mundos, sensores y Brick. | simulador_ev3/core/, domain/ |
4. Funcionalidades
| Área | Capacidad |
|---|---|
| Editor y depuración | Edición Python, ejemplos, mensajes de error, breakpoints, watches, paso y continuar. |
| Simulación | Movimiento diferencial, colisiones, perfiles ideal/realista/calibrado, tick temporal, pausa y reinicio. |
| Brick virtual | LED, altavoz, botones y LCD monocroma de 178 × 128. |
| Telemetría | Posición, orientación, colisión, tiempo, motores A–D y sensores S1–S4. |
| Mundos | Colocación y rotación de assets, robot, validación, guardado y carga JSON. |
| Trazas y misiones | Visualización o exportación de recorridos y evaluación local de misiones. |
La cuadrícula visual conserva la escala 32 px = 100 mm. La interfaz muestra distancias en cm; el motor utiliza mm y los ángulos se expresan en grados.
5. API Pybricks virtual
La compatibilidad es educativa y funcional; no equivale al firmware oficial ni sustituye las pruebas físicas.
| Módulo | Elementos principales |
|---|---|
pybricks.hubs | EV3Brick, LED, altavoz, LCD y botones. |
pybricks.ev3devices | Motor, sensores Touch, Ultrasonic, Color, Gyro e Infrared. |
pybricks.robotics | DriveBase: drive, straight, turn, curve, state y reset. |
pybricks.tools | wait y StopWatch. |
pybricks.parameters | Port, Color, Stop, Direction y Button. |
from pybricks.hubs import EV3Brick
from pybricks.ev3devices import Motor
from pybricks.parameters import Port
ev3 = EV3Brick()
motor = Motor(Port.A)
ev3.screen.print("Inicio")
motor.run_angle(360, 720)6. Instalación y arranque
Requiere Windows y Python 3.11 o superior (la validación actual emplea Python 3.12). Tkinter se distribuye normalmente con el intérprete oficial de Python para Windows.
git clone <URL_DEL_REPOSITORIO_AUTORIZADO> cd Codex_SimuladorLegoEV3 py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip python -m pip install -r requirements.txt python -m pip install -e ".[dev,desktop-e2e]" # Inicio .\.venv\Scripts\python.exe -m simulador_ev3.ui.main_window
Si no existe el entorno virtual, puede iniciarse con py -3.12 -m simulador_ev3.ui.main_window después de instalar las dependencias.
7. Operación y mantenimiento
- Abra o cree un mundo y defina la pose inicial del robot.
- Escriba o cargue un ejemplo en el editor.
- Ejecute el programa y observe canvas, Brick y telemetría.
- Use Pausar/Reanudar para controlar el avance; use Detener y reiniciar para cancelar, limpiar el estado transitorio y restaurar la pose inicial.
- Guarde el mundo o exporte trazas cuando se necesite evidencia.
El tiempo máximo protege frente a scripts no terminantes. La fidelidad selecciona un perfil de comportamiento del simulador, no una certificación del robot físico.
8. Seguridad, privacidad y límites
- El runtime aislado, los límites de tiempo y la cancelación reducen el impacto de scripts de estudiante.
- La validación de mundos y transiciones evita estados de sesión incoherentes.
- Las lecturas de sensores son modelos geométricos y no reemplazan mediciones de aula.
- Batería, fricción, iluminación, carga mecánica, firmware y ecos ultrasónicos requieren calibración y validación segura en hardware.
Consulte Documentos/SEGURIDAD_Y_USO_EN_AULA.md para la política de aula.
9. Calidad y evidencia técnica
Las pruebas incluyen niveles unitario, integración, contrato, UI y E2E de escritorio con Pywinauto, además de análisis estático y seguridad.
py -3.12 -m pytest -q py -3.12 -m pytest --cov=simulador_ev3 --cov-report=term -q py -3.12 -m ruff check simulador_ev3 tests py -3.12 -m mypy py -3.12 -m bandit -q -c pyproject.toml -r simulador_ev3 --severity-level medium py -3.12 -m pip_audit
Para una entrega técnica, archive el commit, el hash SHA-256 del paquete, capturas fechadas de la interfaz y los resultados de pruebas ejecutados sobre el commit entregado.