Integrar um periférico RS-485

Caso de uso

Use este padrão quando um dispositivo WLTE com capacidade RS-485 precisar trocar bytes brutos com um periférico. O OpenAPI oferece o modo transparente (passthrough); ele não implementa automaticamente uma pilha completa do protocolo Modbus.

Seu serviço é responsável por construir o payload do protocolo de aplicação, o CRC quando necessário, interpretar a resposta e aplicar as regras de nova tentativa específicas do dispositivo.

Fluxo recomendado

1. Leia o deviceType do dispositivo de destino em Listar dispositivos (em inglês).
2. Encontre o perfil correspondente em Listar definições de tipo de dispositivo (em inglês).
3. Ofereça o modo transparente apenas quando supportedOperations contiver device.rs485.transceive.
4. Se precisar configurar a taxa de transmissão, exija separadamente device.rs485.baudRate.set e leia o valor atual em Consultar configuração do dispositivo (em inglês).
5. Envie a requisição bruta com um Idempotency-Key novo e mantenha o ID de comando retornado.
6. Analise command.result.responseHex somente após SUCCESS. Se o status for SENT, consulte o resultado do comando.

Implementação passo a passo

1. Validar a capacidade e a configuração

Não deduza o suporte a RS-485 a partir do nome do dispositivo nem de outro modelo. Use supportedOperations. Mudanças de taxa de transmissão exigem device:config; o modo transparente exige device:control.

O endpoint de taxa de transmissão aceita o intervalo e as unidades documentados em Definir taxa de transmissão RS485 (em inglês). O periférico e o dispositivo devem usar o mesmo valor.

2. Construir a requisição bruta

Via REST, envie requestHex para Comando de transceptor RS485 (em inglês). O contrato atual aceita uma string hexadecimal contínua de 1 a 30 bytes, sem espaços, sem prefixo 0x e sem separadores.

Se o periférico usar Modbus RTU, sua aplicação deve construir o endereço, a função, os dados e os bytes de CRC. O OpenAPI encaminha os bytes e retorna os bytes de resposta brutos; ele não valida os registradores Modbus nem a semântica da função.

3. Tratar o resultado do comando

• SUCCESS: analise result.responseHex de acordo com o protocolo do periférico.
• SENT: consulte Consultar resultado de comando (em inglês).
• FAILED: pare e exiba a falha confirmada.
• TIMEOUT: nenhuma resposta correspondente chegou dentro da janela de espera. Não presuma que a escrita falhou no periférico.

Ao usar WebSocket, os dados correspondentes aparecem na resposta da operação. Dados RS-485 tardios ou não solicitados podem chegar via device.rs485.received (em inglês), que não tem reprodução de histórico.

Interfaces e eventos principais

Finalidade	Referência
Confirmar a capacidade do dispositivo	Listar definições de tipo de dispositivo (em inglês)
Enviar dados brutos via REST	Comando de transceptor RS485 (em inglês)
Enviar dados brutos via WebSocket	Transceptor RS485 (em inglês)
Configurar a taxa de transmissão	Definir taxa de transmissão RS485 (em inglês)
Ler a configuração atual	Consultar configuração do dispositivo (em inglês)
Receber dados não correspondidos	Evento de dados RS485 (em inglês)

Falhas e recuperação

• Reutilize a chave de idempotência original apenas ao tentar novamente a mesma requisição de transceptor após um resultado HTTP desconhecido ou um limite de taxa.
• Trate TIMEOUT como um resultado terminal incerto para o comando original; reutilizar sua chave não reenvia os dados. Gere uma chave nova somente quando outra tentativa física for segura para o comando do periférico.
• Valide o comprimento da resposta, o checksum do protocolo, o endereço e a função no seu próprio analisador antes de aplicar os dados.
• Persista com rapidez os dados não solicitados ou tardios se não puder se dar ao luxo de perdê-los; os eventos WebSocket não são reproduzidos.
• Respeite os limites de taxa por operação de dispositivo em vez de disparar requisições de transceptor em paralelo para o mesmo dispositivo.

Considerações para produção

• Mantenha uma única fila de requisições coordenada por barramento RS-485 físico ou por dispositivo.
• Redija os payloads sensíveis se os dados brutos do barramento puderem conter valores confidenciais.
• Registre o ID do comando, a chave de idempotência, os comprimentos de requisição e resposta, o status terminal e o requestId; evite registrar credenciais ou access token.
• Teste o comportamento de timeout e resposta duplicada com o periférico real antes de ativar tentativas automáticas.

Próximos passos

• Limites de taxa e tentativas (em inglês)
• Consultar resultado de comando (em inglês)
• Evento de dados RS485 via WebSocket (em inglês)