Relais sicher steuern

Anwendungsfall

Verwenden Sie dieses Muster, wenn Relaisvorgänge echte Hardware beeinflussen und der Aufrufer Wiederholungsversuche, unklare Ergebnisse und mehrere Relaiskanäle handhaben muss, ohne doppelte Nebeneffekte zu erzeugen.

Empfohlener Ablauf

Senden Sie alle Relaisänderungen eines Geräts in einem einzigen relays-Array. Eine Charge wird zu einem einzigen Gerätebefehl und vermeidet sequenzielle Übertragungen, die das Gerät möglicherweise nicht zuverlässig verarbeitet.

Schrittweise Umsetzung

1. Verwenden Sie Gerätetypdefinitionen auflisten (auf Englisch), um device.relay.set, die Relaisanzahl und gültige Aktionen zu bestätigen.
2. Bauen Sie das gewünschte Relais-Array auf. Verwenden Sie ein einzelnes Element, um einen Kanal zu steuern, und mehrere eindeutige Indizes für eine koordinierte Änderung.
3. Generieren Sie einen neuen, dem Aufrufer gehörenden Idempotency-Key für diese Vorgangsabsicht.
4. Rufen Sie Relaisbefehl ausführen (auf Englisch) mit dem device:control-Scope auf.
5. Lesen Sie data.command.id und data.command.status. Wenn der Status SENT ist, verwenden Sie Befehlsergebnis abrufen (auf Englisch), bis ein endgültiger Status erreicht ist oder Ihr eigenes begrenztes Abfragefenster abläuft.
6. Verwenden Sie data.state, wenn die Gerätebestätigung es enthält. Lösen Sie keine weitere Aktualisierung nur aus, um ein optionales Feld zu füllen.
7. Wenn das Ergebnis TIMEOUT ist, lesen Sie den aktuellen Gerätezustand, bevor Sie entscheiden, ob ein weiterer Vorgang sicher ist.

Lebenszyklus des Befehls

Ergebnis	Bedeutung	Client-Aktion
HTTP 202 + COMMAND_ACCEPTED	Die Plattform hat die Anfrage akzeptiert; dies ist kein eigener Befehlsstatus	Lesen Sie data.command.status und speichern Sie die Befehls-ID
SENT	Der Befehl wartet noch auf Bestätigung	Fragen Sie das Ergebnis mit begrenztem Polling ab
SUCCESS	Das Gerät hat die Ausführung bestätigt	Wenden Sie den zurückgegebenen Zustand an, falls vorhanden
FAILED	Die Plattform hat bestätigt, dass der Befehl nicht erfolgreich abgeschlossen wurde	Stoppen Sie automatische Wiederholungsversuche und behandeln Sie den Fehler
TIMEOUT	Innerhalb des Zeitfensters ist keine endgültige Bestätigung eingetroffen	Nehmen Sie nicht an, ob das Gerät den Befehl ausgeführt hat oder nicht; lesen Sie zuerst den aktuellen Zustand

Wichtige Schnittstellen

• Relaisbefehl ausführen (auf Englisch)
• Befehlsergebnis abrufen (auf Englisch)
• Gerätezustand abrufen (auf Englisch)
• Ratenbegrenzungen und Idempotenz (auf Englisch)
• Relaissteuerung über WebSocket (auf Englisch)

Fehler und Wiederherstellung

• Wenn das HTTP-Ergebnis aufgrund eines Netzwerkfehlers unbekannt ist, wiederholen Sie exakt dieselbe Anfrage mit demselben Idempotency-Key.
• Warten Sie nach 429 RATE_LIMITED auf Retry-After und wiederholen Sie dann denselben Vorgang mit dem ursprünglichen Schlüssel.
• Verwenden Sie einen Schlüssel niemals für ein anderes Gerät, ein anderes Relais-Array oder eine andere Aktion wieder; dies gibt IDEMPOTENCY_CONFLICT zurück.
• Aktualisieren Sie nach TIMEOUT zuerst den Zustand. Wenn er weiterhin unbekannt ist, verlangen Sie eine Geschäftsentscheidung, bevor Sie einen weiteren physischen Vorgang senden.
• Das Wiederholen von JOG oder anderen Hardwareaktionen kann echte Nebeneffekte verursachen, selbst wenn die vorherige Antwort verloren gegangen ist. Gestalten Sie Bestätigungen und Sicherheitsmaßnahmen für den Bediener entsprechend.

Überlegungen für die Produktion

• Speichern Sie Idempotenzschlüssel, Befehls-ID, angefordertes Relais-Array, Status und requestId zusammen für Audit und Wiederherstellung.
• Serialisieren oder koordinieren Sie in Ihrer Anwendung Vorgänge, die auf dasselbe Gerät zielen.
• Verwenden Sie begrenztes Polling für Ergebnisse und beachten Sie Ratenbegrenzungen.
• Prüfen Sie den Zielkanal und die physische Sicherheit, bevor Sie Steuerung von einer Oberfläche oder Automatisierungsregel aus zulassen.

Nächste Schritte

• Ereignis für Gerätezustandsänderung (auf Englisch)
• Ressourcen- und Befehlsfehler (auf Englisch)
• Geräteüberwachungs-Dashboard