Conexión y configuración

SerialConfig

El constructor recibe el contrato exacto SerialConfig de serial-core.

Opción	Tipo	Obligatoria	Comportamiento
baudRate	number	sí	Velocidad serial; debe coincidir con el equipo
autoConnect	boolean	no	false por defecto; si es true, conectar en una microtarea
reconnectInterval	number	no	Espera inicial de reintento; 2000 ms por defecto
autoReconnect	boolean	no	true por defecto; habilita recuperación automática
reconnectBackoffFactor	number	no	Multiplicador de espera, mínimo 1; predeterminado 1
maxReconnectInterval	number	no	Espera máxima; predeterminado max(30000, reconnectInterval)
maxReconnectAttempts	number	no	Reintentos sin contar el intento inicial; predeterminado Infinity
writeTimeout	number	no	Límite de escritura/drain físico; predeterminado 5000 ms
responseTimeout	number	no	Espera de respuesta de serial-core; 5000 ms; distinta al plazo ACK JSD
maxQueueSize	number	no	Capacidad de comandos activos y pendientes; 1000; limita también la cola JSD
path	string	no	Ruta explícita del puerto
vendorId	string	no	Filtro de fabricante USB para búsqueda
productId	string	no	Filtro de producto USB para búsqueda
serialNumber	string	no	Número de serie exacto para descubrimiento
parser	NodeJS.ReadWriteStream	no	Parser compartido; excluye parserFactory
parserFactory	() => NodeJS.ReadWriteStream	no	Parser nuevo por sesión; JSD proporciona una fábrica por delimitador
handshake	JSDHandshake	no	Handshake propio; JSD proporciona uno del protocolo

Usa autoConnect: false para registrar listeners antes de iniciar la conexión. El constructor conserva el objeto recibido y agrega valores predeterminados en una copia. Un parser nuevo por sesión evita conservar tramas parciales al reconectar.

Rutas y descubrimiento

Ejemplos: /dev/ttyUSB0 o /dev/ttyACM0 en Linux, /dev/cu.usbserial-* en macOS y COM3 en Windows. Usa la ruta real.

const ports = await JSD.listPorts({ availableOnly: true });
console.table(ports);

JSD ofrece listPorts() / findPorts() estáticos y de instancia. Sus filtros se combinan con AND sin abrir puertos. availableOnly comprueba reservas locales del módulo, no disponibilidad del sistema operativo. Para conectarte por descubrimiento, omite path e indica vendorId, productId o serialNumber:

const jsd = new JSD({
  vendorId: '0403',
  productId: '6001',
  baudRate: 9600,
  autoConnect: false,
  reconnectInterval: 1_000
});

serial-core realiza la búsqueda. La versión instalada selecciona el primer puerto libre con VID/PID normalizados y exactos, y número de serie exacto. La ruta explícita tiene prioridad. Los errores de enumeración rechazan; sin coincidencias se devuelve [].

Disponibilidad y reconexión

start(): void solicita la conexión a serial-core. Observa DISCONNECTED, SCANNING, CONNECTING, CONNECTED y RECONNECTING mediante serial:status. Los fallos llegan en serial:error y serial-core programa la política de recuperación, con presupuesto y espera creciente limitada. Observa serial:reconnecting con { attempt, delay } y serial:reconnectFailed con { attempts }. Los contadores excluyen el intento inicial.

import { once } from 'node:events';

const ready = once(jsd, 'serial:connected', {
  signal: AbortSignal.timeout(10_000)
});
jsd.start();
await ready;

El ejemplo limita la espera, pero no convierte serial:error en rechazo. Mantén un listener de errores y llama a stop() si abandonas los intentos.

Handshake y parser predeterminados

JSD envía la trama de conexión de licencias y acepta una trama ACK o DATA válida. El handshake tiene un límite de 500 ms. El parser divide por 0xC0 y excluye ese delimitador. Las tramas inválidas fallan la validación de CRC o estructura.

Un handshake propio reemplaza completamente al predeterminado:

import type { JSDHandshake } from '@danidoble/serial-node-jsd';

const handshake: JSDHandshake = {
  command: Buffer.from([/* bytes de handshake de tu equipo */]),
  pattern: /READY/,
  timeout: 1_000
};

command acepta string o Buffer, pattern string o RegExp, timeout milisegundos, hexPattern un boolean opcional y callback una función opcional (data: Buffer | string) => boolean. Si existe callback, este decide el éxito en lugar del patrón. maxBufferSize limita los bytes acumulados para patrones (65536 por defecto); el callback recibe cada fragmento o trama por separado. Se requiere escritura exitosa y validación para confirmar conexión. Adáptalo al equipo.

Cierre y reintentos

stop(): Promise<void> delega la desconexión y cancela la reconexión de serial-core. También vacía comandos JSD, temporizadores ACK y consultas iniciales diferidas. No se reproducen comandos de sesiones perdidas al reconectar; callbacks de escritura antiguos no afectan a la sesión nueva.

Las lecturas de registros, asignaciones, carritos y dispensas pendientes rechazan con JSD session ended; operation outcome may be unknown. Se liberan sus temporizadores y se invalida la disponibilidad almacenada. Esto no deshace una operación física. No se expone cancelación individual; sigue siendo necesario limitar la espera si el equipo permanece conectado sin completar la respuesta.

La cola JSD espera un ACK con el mismo identificador después del drain físico. El intervalo predeterminado es 500 ms, con el envío inicial y hasta tres reenvíos. Un NACK emite un evento pero no retira inmediatamente el comando.