Integrar un periférico RS-485

Caso de uso

Usa este patrón cuando un dispositivo WLTE con capacidad RS-485 deba intercambiar bytes en bruto con un periférico. OpenAPI ofrece el modo transparente (passthrough); no implementa automáticamente una pila completa del protocolo Modbus.

Tu servicio es responsable de construir el payload del protocolo de aplicación, el CRC cuando haga falta, interpretar la respuesta y aplicar las reglas de reintento propias del dispositivo.

Flujo recomendado

1. Lee el deviceType del dispositivo de destino en Listar dispositivos (en inglés).
2. Busca el perfil correspondiente en Listar definiciones de tipo de dispositivo (en inglés).
3. Ofrece el modo transparente solo si supportedOperations contiene device.rs485.transceive.
4. Si necesitas configurar la velocidad en baudios, exige por separado device.rs485.baudRate.set y lee el valor actual en Consultar configuración del dispositivo (en inglés).
5. Envía la petición en bruto con un Idempotency-Key nuevo y conserva el ID de comando devuelto.
6. Analiza command.result.responseHex solo después de SUCCESS. Si el estado es SENT, consulta el resultado del comando.

Implementación paso a paso

1. Validar la capacidad y la configuración

No deduzcas el soporte de RS-485 a partir del nombre del dispositivo ni de otro modelo. Usa supportedOperations. Los cambios de velocidad en baudios requieren device:config; el modo transparente requiere device:control.

El endpoint de velocidad en baudios acepta el rango y las unidades documentados en Fijar velocidad en baudios de RS485 (en inglés). El periférico y el dispositivo deben usar el mismo valor.

2. Construir la petición en bruto

Por REST, envía requestHex a Comando de transmisión RS485 (en inglés). El contrato actual acepta una cadena hexadecimal continua de entre 1 y 30 bytes, sin espacios, sin prefijo 0x y sin separadores.

Si el periférico usa Modbus RTU, tu aplicación debe construir la dirección, la función, los datos y los bytes de CRC. OpenAPI reenvía los bytes y devuelve los bytes de respuesta en bruto; no valida los registros Modbus ni la semántica de la función.

3. Gestionar el resultado del comando

• SUCCESS: analiza result.responseHex según el protocolo del periférico.
• SENT: consulta Consultar resultado de comando (en inglés).
• FAILED: detente y muestra el fallo confirmado.
• TIMEOUT: no llegó ninguna respuesta correspondiente dentro de la ventana de espera. No des por hecho que la escritura falló en el periférico.

Cuando uses WebSocket, los datos correspondientes aparecen en la respuesta de la operación. Los datos RS-485 tardíos o no solicitados pueden llegar por device.rs485.received (en inglés), que no tiene reproducción de historial.

Interfaces y eventos clave

Para qué	Referencia
Confirmar la capacidad del dispositivo	Listar definiciones de tipo de dispositivo (en inglés)
Enviar datos en bruto por REST	Comando de transmisión RS485 (en inglés)
Enviar datos en bruto por WebSocket	Transmisión RS485 (en inglés)
Configurar la velocidad en baudios	Fijar velocidad en baudios de RS485 (en inglés)
Leer la configuración actual	Consultar configuración del dispositivo (en inglés)
Recibir datos no correspondidos	Evento de datos RS485 (en inglés)

Fallos y recuperación

• Reutiliza la clave de idempotencia original solo al reintentar la misma petición de transmisión tras un resultado HTTP desconocido o un límite de tasa.
• Trata TIMEOUT como un resultado terminal incierto para el comando original; reutilizar su clave no reenvía los datos. Genera una clave nueva solo cuando otro intento físico sea seguro para el comando del periférico.
• Valida en tu propio analizador la longitud de la respuesta, el checksum del protocolo, la dirección y la función antes de aplicar los datos.
• Persiste con prontitud los datos no solicitados o tardíos si no puedes permitirte perderlos; los eventos WebSocket no se reproducen.
• Respeta los límites de tasa por operación de dispositivo en lugar de lanzar peticiones de transmisión en paralelo al mismo dispositivo.

Consideraciones para producción

• Mantén una única cola de peticiones coordinada por bus RS-485 físico o por dispositivo.
• Depura los payloads sensibles si los datos en bruto del bus pueden contener valores confidenciales.
• Registra el ID de comando, la clave de idempotencia, las longitudes de petición y respuesta, el estado terminal y el requestId; evita registrar credenciales o access token.
• Prueba el comportamiento ante timeouts y respuestas duplicadas con el periférico real antes de activar reintentos automáticos.

Siguientes pasos

• Límites de tasa y reintentos (en inglés)
• Consultar resultado de comando (en inglés)
• Evento de datos RS485 por WebSocket (en inglés)