🌐
ASCF · DOCS & GUÍA
Agentic Spatial Computing Framework
Manual de Arquitectura & Onboarding Paso a Paso

Aprende a Conectar, Operar y Gobernar Todo el Ecosistema ASCF

Diseñado especialmente para neófitos y desarrolladores: descubre cómo enlazar dispositivos físicos (ESP32), mandos remotos móviles, clientes inmersivos XR (Unity), microservicios de inferencia adaptativa y las 7 verticales industriales en tiempo real.

🔍
#ESP32 #Móvil #7Verticales #Diagramas #API
El Concepto Fundamental en 30 Segundos MENTAL MODEL

Imagina a ASCF como el Sistema Nervioso Central de un entorno industrial o espacial:

👀 1. Sentidos (Entradas)
Sensores Físicos & Cámaras
El ESP32, tu Smartphone con giroscopio, cámaras de seguridad o visores capturan lo que pasa físicamente.
🧠 2. Cerebro (Backend)
Servidor FastAPI + Agentes
Procesa los datos en <700 ms, decide acciones óptimas, audita reglas y orquesta la colaboración multi-agente.
🦾 3. Músculos (Salidas)
Actuadores, Radar & XR
Prende ventiladores PWM, relés de corte, mueve objetos en Unity 3D o envía alertas hápticas al operador.
1
Paso 1: Conectar tu Celular como Mando Cyber-Físico (Sin instalar nada)
No necesitas comprar ningún hardware para empezar. Tu teléfono móvil ya tiene acelerómetro, giroscopio, linterna y vibrador háptico.
  1. Abre el navegador de tu celular (Chrome o Safari) e ingresa a:
    http://aspatialcomputingframework.duckdns.org/mobile
  2. Presiona el botón verde "Conectar al Bus ASCF".
  3. Autoriza el acceso a sensores de orientación cuando el navegador te lo pida.
  4. Mueve tu teléfono en el aire: verás cómo los ángulos de inclinación (Pitch, Roll, Yaw) se leen en tiempo real.
📱 Abrir Controlador Móvil
2
Paso 2: Abrir el Cockpit en tu Computador y Ver la Telemetría en Vivo
El Cockpit es tu centro de mando aeroespacial / industrial.
  1. En tu PC o laptop, abre la consola: /console.
  2. En la barra superior, asegúrate de que el selector apunte a AWS Lightsail (Cloud) o tu IP local.
  3. Mira el Radar Espacial 3D y el Osciloscopio: si mueves el celular del Paso 1, verás aparecer el punto objetivo (blip) moviéndose según cómo inclinas el móvil.
  4. El banner superior cambiará automáticamente a HARDWARE REAL ACTIVO y bloqueará la simulación artificial para garantizar integridad real.
🔌 Ir al Cockpit de Control
3
Paso 3: Ejecutar las 7 Verticales Industriales (Experience Factory)
ASCF resuelve la inferencia adaptativa para 7 sectores críticos donde cada milisegundo cuenta.
  1. Haz clic en "7 Verticales" en el menú superior o navega a: /experience-factory.html.
  2. Haz clic sobre cualquier tarjeta (por ejemplo "Copiloto de operador de camión CAT" en Minería, o "Near-miss montacargas" en Logística).
  3. Presiona "Ejecutar experiencia": el backend procesará el caso, medirá el tiempo de respuesta y confirmará el cumplimiento del SLA (<700 ms).
  4. O presiona "Ejecutar las 7 experiencias" para correr la suite completa en serie y ver los benchmarks.
🏭 Ir a la Fábrica de 7 Verticales
4
Paso 4: Conectar un ESP32 Físico o Simular un Nodo en Terminal
Si tienes una placa ESP32 con WiFi, o simplemente quieres simular un nodo de fábrica desde tu consola de comandos:
Terminal (Mac / Linux / Windows) — Emular nodo físico IoT
# Opción A: Ejecutar el script CLI incluido en el repositorio
python3 scripts/iot_device_cli.py esp32-nodo-01 mineria-copiloto http://aspatialcomputingframework.duckdns.org

# Opción B: Enviar una lectura única con curl
curl -X POST http://aspatialcomputingframework.duckdns.org/api/iot/sensor \
  -H "Content-Type: application/json" \
  -d '{"client_id": "esp32-taller", "temp": 32.4, "pressure": 2.8, "status": "ONLINE"}'
5
Paso 5: Inyectar Caos y Probar la Resiliencia Agéntica
En el Cockpit (`/console`), baja a la pestaña "Pruebas de Caos":
  • Activa Inyección de Latencia (+500ms) o Pérdida de Paquetes (30%).
  • Comprueba cómo el orquestador cognitivo detecta la anomalía, conmuta a fallback de inferencia rápida y preserva el contrato de seguridad.
1. Topología Cyber-Física End-to-End ARQUITECTURA DE SISTEMA

Flujo de telemetría bidireccional desde dispositivos en borde (Edge) hasta la nube (Cloud) y clientes inmersivos:

BORDE FÍSICO / EDGE ESP32 Hardware Sensores DHT/Presión Smartphone (/mobile) Gyro / Acelerómetro Terminal Node CLI iot_device_cli.py HTTP / WS ASCF CORE BACKEND Caddy 2 Reverse Proxy DuckDNS SSL / Ports 80-443 FastAPI Experience Factory Inferencia Adaptativa (<700ms) Real Device Auto-Lock WebSocket Spatial Bus Peer Mesh / Actuadores PWM Auditoría /gov C2 Ledger CLIENTES Y VISUALIZACIÓN Cockpit HUD (/console) Radar 3D + Osciloscopio 7 Verticales Factory /experience-factory.html Unity XR / Digital Twin Visores Quest / WebGL 3D
2. Ciclo del Agente Autónomo: Recibir ➔ Procesar ➔ Notificar LOOP AGÉNTICO

Cómo opera la toma de decisiones con garantía de tiempo real:

1. INGESTIÓN DE EVENTO
El sensor (temperatura, proximidad o visión por cámara) envía una lectura al endpoint /api/iot/sensor o por WebSocket /ws.
2. INFERENCIA & VERIFICACIÓN
El agente ejecuta el modelo correspondiente (Visión/Texto/Decisión) y valida los invariantes de seguridad en el ledger criptográfico.
3. ACCIÓN & NOTIFICACIÓN
Dispara el actuador físico (ej: activar ventilador PWM al 90%, detener montacargas) y emite un broadcast inmediato a todos los clientes.
Catálogo Oficial de las 7 Verticales de la Experience Factory SLA <700ms

Cada vertical representa una solución empresarial real probada bajo condiciones de latencia estricta:

⛏️
1. Minería Copiloto
Minería a Cielo Abierto & Subterránea
Copiloto inteligente para operadores de camiones de extracción CAT. Analiza la pendiente de la rampa, micro-fisuras de talud y obstáculos en menos de 700 ms, emitiendo recomendaciones críticas en UNA sola frase.
SLA: <700 ms Modalidad: Visión + Radar
📦
2. Logística Nearness
Centros de Distribución & Bodegas 3D
Prevención de accidentes "Near-miss" humano-maquinaria. Calcula la distancia euclidiana entre peatones y montacargas autónomos en tiempo real, frenando el equipo si cruza el perímetro de seguridad de 1,5 metros.
SLA: <700 ms Modalidad: Visión Espacial 3D
🏭
3. Manufactura QA Visual
Líneas de Producción & Ensamble
Inspección óptica de control de calidad al paso de piezas sobre la cinta transportadora. No solo detecta el defecto visual (ej: grieta diagonal), sino que deduce la causa raíz (ej: exceso de presión en prensa hidráulica).
SLA: <700 ms Modalidad: Visión IA + Causa Raíz
🏥
4. Salud Feedback VR
Entrenamiento Quirúrgico & Médicos VR
Asistencia y tutoría háptica durante simulaciones médicas de cirugía en Realidad Virtual. Evalúa la precisión del corte y profundidad del instrumental, devolviendo guía inmediata sin pausar la simulación inmersiva.
SLA: <700 ms (533ms medido) Modalidad: Háptica + USD 3D
🛒
5. Retail Layout Optimization
Grandes Superficies & Supermercados
Optimización dinámica del layout espacial y estanterías en base al flujo y tiempo de permanencia de los clientes. Genera recomendaciones de colocación de productos y balanceo de pasillos de alta afluencia.
SLA: <1000 ms Modalidad: Razonamiento Espacial
🔧
6. Field Service Copilot
Mantenimiento de Campo & Gafas AR
Copiloto manos libres para técnicos en subestaciones o parques eólicos usando gafas AR. Reconoce componentes eléctricos, muestra diagramas unifilares superpuestos en el campo de visión y guía el protocolo de bloqueo (LOTO).
SLA: <700 ms Modalidad: AR + Visión Asistida
7. Utilities Coordination
Redes Eléctricas, Acueductos & Ciudades Inteligentes
Coordinación multi-agente para redes de infraestructura crítica. Ante una sobretensión o ruptura de matriz hídrica, orquesta automáticamente el cierre de válvulas seccionales, el desvío de flujo de energía y la notificación a brigadas de emergencia sin intervención manual.
SLA: <700 ms Modalidad: Multi-Agente Mesh
¿Quieres probar las 7 en vivo?
Entra en la suite interactiva de la Experience Factory y corre los benchmarks con un solo clic.
🚀 Abrir Experience Factory
Protocolo de Conexión de Placas Físicas ESP32 CÓDIGO LISTO

El firmware oficial de ASCF está disponible en la carpeta firmware/esp32_quick_demo/. Puedes compilarlo con Arduino IDE o PlatformIO:

firmware/esp32_quick_demo/src/main.cpp
#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

const char* ssid = "TU_WIFI_SSID";
const char* password = "TU_WIFI_PASSWORD";
const char* serverUrl = "http://aspatialcomputingframework.duckdns.org/api/iot/sensor";

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("\n✓ Conectado a WiFi y listo para emitir al Bus ASCF");
}

void loop() {
  if (WiFi.status() == WL_CONNECTED) {
    HTTPClient http;
    http.begin(serverUrl);
    http.addHeader("Content-Type", "application/json");

    // Telemetría de sensores reales (temperatura, presión, vibración)
    StaticJsonDocument<256> doc;
    doc["client_id"] = "esp32-nodo-01";
    doc["temp"] = 28.5 + (random(-10, 10) / 10.0);
    doc["pressure"] = 2.1 + (random(-2, 2) / 10.0);
    doc["status"] = "NORMAL";

    String payload;
    serializeJson(doc, payload);

    int httpCode = http.POST(payload);
    Serial.printf("Transmisión HTTP: %d\n", httpCode);
    http.end();
  }
  delay(2000); // Frecuencia de muestreo
}
🔒 Auto-Lock Estricto de Realismo:

Apenas el ESP32 o tu móvil emiten una lectura real, el servidor activa un bloqueo estricto (Auto-Lock): desactiva la simulación sintética de fondo para evitar que datos falsos contaminen las decisiones de los agentes.

Tabla 1: Matriz Completa de Endpoints HTTP & WebSockets API SURFACE
Método Ruta Función y Propósito Payload / Entrada Respuesta Típica
GET /console Centro de mando, radar 3D, osciloscopio y agentes Ninguno HTML Console UI
GET /experience-factory.html Suite interactiva de las 7 verticales empresariales Ninguno HTML Factory UI
GET /mobile Controlador remoto para smartphone (giroscopio/háptico) Ninguno HTML Mobile UI
GET /guide.html Guía de arquitectura y onboarding para neófitos Ninguno HTML Docs UI
GET /api/health Health check del servidor y estado del servicio Ninguno {"status": "ok"}
POST /api/iot/sensor Ingesta de telemetría de sensores físicos (ESP32) {"client_id", "temp", ...} {"received": true, ...}
GET /api/devices/hardware-status Verifica si hay hardware real emitiendo en vivo Ninguno {"has_real_hardware": bool}
POST /api/run-all-experiences Ejecuta las 7 verticales secuencialmente y mide SLAs Ninguno {"total": 7, "results": [...]}
WS /ws Bus espacial de eventos peer-to-peer y telemetría JSON String Stream Broadcast a todos los pares
GET /gov/chain/audit Auditoría criptográfica de invariantes de gobernanza C2 Ninguno {"valid": true, "gates": [...]}
Tabla 2: Matriz Comparativa de las 7 Verticales Industriales SPEC V6
ID Vertical Industria SLA Objetivo Tipo de Sensores Actuador / Mitigación Estado Medición
mineria-copiloto Minería <700 ms Cámara de rampa + Talud Alerta de voz al operador CAT CONFORME
logistica-nearness Logística <700 ms Cámara cenital + Lidar Freno de emergencia montacargas CONFORME
manufactura-qa-visual Manufactura <700 ms Cámara óptica en línea Parada de cinta + Ticket raíz CONFORME
salud-feedback-vr Salud <700 ms Simulador VR Háptico Vibración en guante quirúrgico 533ms (USD en F1)
retail-layout-optimization Retail <1000 ms Tráfico Wi-Fi + Cámaras Reorganización de góndolas CONFORME
field-service-copilot Field Service <700 ms Gafas AR + Audio Overlay holográfico de válvulas CONFORME
utilities-coordination Utilities <700 ms Telemetría de presión/tensión Relés y válvulas seccionales CONFORME