Serial Bridge

Serial Bridge es un Hub que comparte dos consolas serie entre un Operador local y los Agentes MCP. No es específico de un sistema operativo: instala los paquetes de Python en requirements.txt y ejecútalo en cualquier host con Python 3.10+. El Hub vive en el paquete serial_bridge/; arráncalo con python -m serial_bridge o con el shim raíz app.py.

Instalar y arrancar

Se recomienda Python 3.10 o superior.

python -m pip install -r requirements.txt
python -m serial_bridge

Los fragmentos de shell que aparecen a continuación usan PowerShell ($env:NAME = "..."). En bash o zsh, define los mismos nombres con export NAME=....

El Hub abre tu navegador en la consola http://127.0.0.1:8765/ en cuanto empieza a escuchar. El shim raíz app.py es equivalente. Para arrancar sin abrir una pestaña del navegador:

$env:SERIAL_BRIDGE_OPEN_UI = "off"
python -m serial_bridge

O pasa --no-open-ui. Usa --open-ui para forzar la apertura cuando el entorno la deshabilita. Si SERIAL_BRIDGE_OPEN_UI no está definida, se abre por defecto; solo 0, false, no y off (sin distinción de mayúsculas) la deshabilitan.

En el primer arranque, el Hub genera automáticamente un token de acceso en serial_bridge.token, junto al archivo de configuración de Port Binding (puedes anular la ruta con SERIAL_BRIDGE_TOKEN_FILE). No hagas commit del archivo de secretos.

Abre Setup (http://127.0.0.1:8765/setup) en el host del Hub para copiar la URL del Hub, ver el token de acceso, rotarlo y pegar un fragmento mcpServers de Cursor. Los secretos de Setup (el token en texto plano, Rotate y el fragmento que contiene secretos) solo son visibles en loopback (127.0.0.1 / ::1).

Alternativamente, define SERIAL_BRIDGE_TOKEN antes de arrancar el Hub y entrega el mismo secreto al cliente MCP. La variable de entorno anula el archivo de secretos durante la vida de ese proceso; Rotate sigue reescribiendo el archivo, pero avisa hasta que la variable se elimine o el Hub se reinicie sin ella.

La autenticación MCP es obligatoria incluso desde loopback. No pongas el token en el control de fuentes, en archivos estáticos del frontend, en URLs ni en registros.

El Hub escucha en 0.0.0.0:8765, por lo que es accesible desde la red local. Usa un cortafuegos de host adecuado y un token fuerte. Los Agentes remotos no pueden cambiar los modos ni los Port Bindings.

MCP

Usa Setup (/setup) en el host del Hub para obtener una configuración de Cursor lista para copiar y pegar. Conexión manual:

Configura la conexión MCP Streamable HTTP del Agente con:

URL: http://<hub-host>:8765/mcp
Authorization: Bearer <SERIAL_BRIDGE_TOKEN>

Usa exactamente /mcp; la interfaz web está en /. El Servidor MCP expone:

• serial_status: lee el modo actual y el Port Binding, el estado de apertura y el indicador de ocupado de cada Target.

• serial_exec: envía un comando de texto y captura la salida hasta que haya una pausa de inactividad, una coincidencia opcional con el prompt o el tiempo de espera de 60 segundos.

• serial_send: envía una línea de texto o un Raw Payload sin esperar la salida.

Para probar el estado y Exec:

1. Abre la interfaz web localmente y cambia a Bridge Mode.

2. Conecta el cliente MCP a la URL anterior con la cabecera Bearer.

3. Llama a serial_status sin argumentos y confirma que mode es bridge y que el Target previsto está abierto.

4. Llama a serial_exec con {"target":"linux","cmd":"uname -a"} o {"target":"rtos","cmd":"help"}.

5. Si el dispositivo tiene un prompt estable, opcionalmente pasa prompt; define prompt_is_regex como true solo cuando el valor de prompt sea una expresión regular.

Exec acepta los nombres de Target linux y rtos, no nombres de dispositivos serie. Devuelve la output capturada junto con los indicadores timed_out, truncated y aborted.

La salida de Exec y las transcripciones live/*.log son texto plano sin escapes ANSI. La interfaz web, en cambio, interpreta los escapes y muestra los colores del dispositivo.

Port Binding

Un Port Binding asigna un Target a una ruta de dispositivo serie y una velocidad en baudios. Los valores predeterminados integrados son de estilo Windows (linux en COM3, rtos en COM6, ambos a 115200); en Linux o macOS, usa rutas como /dev/ttyUSB0 en su lugar.

Anula los valores predeterminados antes del arranque con variables de entorno:

$env:SERIAL_BRIDGE_LINUX_PORT = "COM8"
$env:SERIAL_BRIDGE_LINUX_BAUD = "57600"
$env:SERIAL_BRIDGE_RTOS_PORT = "COM9"
$env:SERIAL_BRIDGE_RTOS_BAUD = "115200"
python -m serial_bridge

Los indicadores CLI equivalentes son --linux-port, --linux-baud, --rtos-port y --rtos-baud. SERIAL_BRIDGE_CONFIG o --config selecciona el archivo JSON persistido. El orden de carga es: valores predeterminados integrados, luego los valores de entorno/CLI y luego el archivo persistido; los valores guardados en la interfaz web tienen prioridad.

Solo el Operador puede editar los Port Bindings, y solo en CRT Mode mientras el Hub haya liberado los puertos. La interfaz web muestra los puertos serie detectados en un menú desplegable por Target; usa Scan para volver a enumerarlos después de conectar un adaptador. Los cambios realizados en la interfaz web persisten tras el reinicio.

Live Directory

El Live Directory es donde el Hub escribe los registros de sesión Bridge por Target y bridge_status.json. El valor predeterminado es <app-dir>/live/, junto a la raíz del proyecto (el mismo directorio que serial_bridge.json y el shim raíz app.py).

Anula antes del arranque con:

$env:SERIAL_BRIDGE_LIVE_DIR = "D:\logs\serial-bridge"
python -m serial_bridge

O pasa --live-dir. El orden de carga coincide con el de Port Binding: valor predeterminado integrado, luego entorno/CLI y luego el archivo de configuración persistido; los guardados de la interfaz web tienen prioridad.

Cada vez que el Operador entra en Bridge Mode, el Hub crea archivos de registro nuevos con el nombre <TargetName>-YYYY-MM-DD-HHMMSS.log (hora local, reloj de 24 horas). Una segunda sesión Bridge crea archivos nuevos; los registros antiguos se quedan donde están y no se migran si cambias el Live Directory o renombras un Target.

Edita el Live Directory en el panel Bindings de la interfaz web solo en CRT Mode (la misma ruta de escritura exclusiva de loopback que Port Binding). El pie de página muestra el directorio configurado y los nombres de archivo de registro de la sesión actual cuando están asignados.

Bridge Mode y CRT Mode

• Bridge Mode: el Hub es el propietario de los puertos serie configurados. El Operador y los Agentes pueden enviar comandos y observar las mismas transcripciones en vivo.

• CRT Mode: el Hub libera los puertos para SecureCRT u otro cliente serie exclusivo. Exec y Send de MCP fallan hasta que el Operador vuelve a Bridge Mode.

Desconecta SecureCRT antes de entrar en Bridge Mode. Cambiar a CRT Mode aborta un Exec en curso y puede devolver una salida parcial.

Aviso de Raw Send

serial_send con raw_hex escribe bytes arbitrarios sin delimitación de líneas de texto ni un final de línea automático. Esto es todo el poder de la consola: los bytes de control pueden interrumpir el arranque, terminar procesos, alterar el estado del dispositivo o dejar una sesión sin respuesta. Prefiere serial_exec para comandos y usa Raw Payloads solo cuando comprendas la secuencia exacta de bytes y el impacto en el dispositivo.