Integrate an RS-485 Peripheral

Use Case

Use this pattern when an RS-485-capable WLTE device must exchange raw bytes with a peripheral. OpenAPI provides data passthrough; it does not automatically implement a complete Modbus protocol stack.

Your service is responsible for constructing the application protocol payload, CRC where required, interpreting the response, and applying device-specific retry rules.

Recommended Flow

1. Read the target device's deviceType from List Devices.
2. Find the matching profile in List Device Type Definitions.
3. Expose passthrough only when supportedOperations contains device.rs485.transceive.
4. If baud-rate configuration is needed, require device.rs485.baudRate.set separately and read the current value from Get Device Configuration.
5. Submit the raw request with a new Idempotency-Key and retain the returned command ID.
6. Parse command.result.responseHex only after SUCCESS. If the status is SENT, query the command result.

Step-by-Step Implementation

1. Validate capability and configuration

Do not infer RS-485 support from a device name or another model. Use supportedOperations. Baud-rate changes require device:config; passthrough requires device:control.

The baud-rate endpoint accepts the range and units documented by Set RS485 Baud Rate. The peripheral and device must use the same value.

2. Build the raw request

For REST, send requestHex to RS485 Transceive Command. The current contract accepts a continuous hexadecimal string containing 1 to 30 bytes, without spaces, a 0x prefix, or separators.

If the peripheral uses Modbus RTU, your application must construct the address, function, data, and CRC bytes. OpenAPI forwards the bytes and returns raw response bytes; it does not validate Modbus registers or function semantics.

3. Handle the command result

• SUCCESS: parse result.responseHex according to the peripheral protocol.
• SENT: query Get Command Result.
• FAILED: stop and surface the confirmed failure.
• TIMEOUT: no matching response arrived in the wait window. Do not assume the write failed at the peripheral.

When using WebSocket, matched data appears in the operation reply. Late or unsolicited RS-485 data may arrive through device.rs485.received, which has no history replay.

Key Interfaces and Events

Purpose	Reference
Confirm device capability	List Device Type Definitions
Send raw data over REST	RS485 Transceive Command
Send raw data over WebSocket	RS485 Transceive
Configure baud rate	Set RS485 Baud Rate
Read current configuration	Get Device Configuration
Receive unmatched data	RS485 Data Event

Failure and Recovery

• Reuse the original idempotency key only when retrying the identical transceive request after an unknown HTTP outcome or rate limit.
• Treat TIMEOUT as an uncertain terminal result for the original command; reusing its key does not resend data. Generate a new key only when another physical attempt is safe for the peripheral command.
• Validate response length, protocol checksum, address, and function in your own parser before applying data.
• Persist unsolicited or late data promptly if losing it is unacceptable; WebSocket events are not replayed.
• Honor device-operation rate limits instead of issuing parallel transceive requests to the same device.

Production Considerations

• Keep one coordinated request queue per physical RS-485 bus or device.
• Redact sensitive payloads if raw bus data may contain confidential values.
• Record command ID, idempotency key, request and response lengths, terminal status, and requestId; avoid logging credentials or access tokens.
• Test timeout and duplicate-response behavior with the actual peripheral before enabling automatic retries.

Next Steps

• Rate Limits and Retries
• Get Command Result
• WebSocket RS485 Data Event