Errores y recuperación

Canal correcto

Canal	Argumento	Significado
serial:error	Error	Fallo de conexión, handshake, parser o puerto de serial-core
serial:jsd-error	string	Trama inválida o reintentos JSD agotados
serial:jsd-nack	trama	Confirmación negativa del equipo
*:wrong-cmd	objeto	Formato rechazado, con opcode y parámetros
vision:jsd-license-error	objeto	Restricción de licencia o precios
mdbCardHolder:jsd-license-error	objeto	Restricción de licencia o precios MDB
licensing:report	objeto	Resultado de activación y motivo de fallo
Promesa rechazada	Error	Precondición local incumplida
JSD session ended; operation outcome may be unknown	Error	Terminó la sesión; se rechazaron operaciones pendientes sin reproducirlas

jsd.on('serial:error', err => console.error('Transporte', err.message));
jsd.on('serial:jsd-error', message => console.error('Protocolo', message));
jsd.on('serial:jsd-nack', frame => console.error('NACK', frame.id));
jsd.on('vision:wrong-cmd', data => console.error(data.opcodeName, data.params));
jsd.on('vision:jsd-license-error', data => console.error(data.type, data.actionName));

Mensajes de validación y tiempo límite

Mensaje exacto	Interpretación y acción
Frame too short	Trama decodificada vacía; revisar delimitadores
CRC mismatch	Bytes corruptos, velocidad incorrecta o formato incompatible
Unknown code	CRC válido con código de transporte no admitido
JConnect header too short	DATA sin los seis bytes de cabecera
No response for packet ID … after 3 attempts.	Se agotaron los reintentos; revisar conexión e identificadores ACK

El mensaje dice tres intentos; el código hace un envío inicial y hasta tres reenvíos. serial:message permite inspeccionar los bytes de tramas inválidas. Los buffers crudos vacíos se ignoran.

serial-core también puede emitir Connection failure: … por equipo ausente, puerto ocupado o Handshake timeout (pattern: …). Son diagnósticos del transporte, no un catálogo estable y exhaustivo de códigos JSD.

Precondiciones locales

• assignChannels(): Channel assignment already in progress.
• requestLogs(): Already fetching logs.
• Dispensado por canal y extendido: Machine N is not available to dispense.
• Configurar funciones MDB requiere el lector deshabilitado.
• Aprobar ventas MDB requiere estado on hold; un lector habilitado puede producir un diagnóstico adicional sobre always-idle.
• Aprobar ventas y registrar efectivo requiere importe mayor que 0 y máximo 65535; los identificadores de producto suministrados deben ser números y máximo 65535.
• Dispositivo MDB inválido: Configuration for device number N not found..

El constructor valida selectores, rangos de temporizadores, recuperación, capacidad y exclusión parser/parserFactory de core 0.3.0. Una configuración inválida lanza de forma síncrona. Desbordar la cola JSD produce JSD queue capacity exceeded; un plazo ACK inválido produce JSD timeout must be positive, finite and within the timer limit.

Captura rechazos de métodos. Los fallos del equipo se siguen notificando por eventos aunque el encolado haya terminado correctamente.

Licencias

type puede ser expired-license, app-number-not-licensed, price-control-active-direct-dispense-not-allowed o unknown. La activación distingue formato incorrecto, identidad de equipo distinta y contador incorrecto o archivo reutilizado. Corrige la licencia antes de reenviar.

Limitar operaciones prolongadas

function withDeadline<T>(operation: Promise<T>, ms: number): Promise<T> {
  let timer: ReturnType<typeof setTimeout>;
  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(() => reject(new Error('Application deadline exceeded')), ms);
  });
  return Promise.race([operation, timeout]).finally(() => clearTimeout(timer));
}
const logs = await withDeadline(jsd.manifest.requestLogs(), 30_000);

El límite solo detiene la espera: no cancela comandos, temporizadores ni acciones físicas. Si el resultado de un pago o dispensado es ambiguo, consulta el estado del equipo antes de decidir un reintento que podría repetir la operación.