Dokumentation – RevPiModIO 2

Hauptklasse, welche instanziiert wird und den gesamten Zugriff auf die IOs des Revolution Pi ermöglicht.

Ab dem RevPi Bookworm image muss der Benutzer, welcher den Prozess ausführt, Mitglied der Gruppe picontrol sein (pi ist Standardmäßig Mitglied der Gruppe). Bei einem PermissionDenied-Fehler sollte dies als ersten überprüft werden. Mit sudo usermod -a -G picontrol newuser kann z.B. der Benutzer newuser der Gruppe hinzugefügt werden.

revpimodio2.RevPiModIO([autorefresh=False, monitoring=False, syncoutputs=True, debug=False, replace_io_file=None, shared_procimg=False])

revpimodio2.RevPiModIOSelected(deviceselection, [autorefresh=False, monitoring=False, syncoutputs=True, debug=False, replace_io_file=None, shared_procimg=False])

revpimodio2.RevPiModIODriver(virtdev, [autorefresh=False, syncoutputs=True, debug=False, replace_io_file=None, shared_procimg=False])

Instanziierungsparameter

• autorefresh = Prozessabbild automatisch aktualisieren
  Dieser Parameter sollte IMMER auf True gesetzt werden. Das Modul synchronisiert dann die IOs automatisch im Hintergrund. Der Standardwert für die Zykluszeit hängt von der Hardware und Instantiierung ab.
  Core 1: 40 Millisekunden (25 Hz)
  Core3 / Connect: 20 Millisekunden (50 Hz)
  NetIO: 50 Millisekunden (20 Hz)
  Der Wert kann über .cycletime geändert werden. Nur bei aktiviertem AutoRefresh ist die Verwndung von .cycleloop(...) oder .mainloop(...) möglich!

• monitoring = Wenn True: IOs nur lesen, niemals schreiben
  Wird dieser Parameter auf True gesetzt, werden die IOs nur gelesen, aber niemals geschrieben. Dies dient z.B. für eine Überwachung, wenn eine andere Software das Prozessabbild kontrolliert.

• syncoutputs = Outputwerte bei Instanziierung einlesen
  Dieser Parameter ist im Standard mit True belegt und ließt bei Instanziierung die aktuellen Outputwerte ein.

• debug = Detaillierte Meldungen im Fehlerfall ausgeben
  Dieser Parameter ist im Standard mit False belegt und kann für Fehlerfindung verwendet werden, wenn er auf True gesetzt wird. Die Bibliothek gibt dann detaillierte Fehlermeldungen aus, welche in der Entwicklungsphase hilfreich sein könnten.

• replace_io_file = Datei mit Definitionen zu IOs, welche ausgetauscht werden
  Alternativ zu .replace_io(…) im Python Programm, kann eine Datei erstellt werden, welche die Bibliothek bei Instanziierung einließt. Die IOs werden dann gemäß der Angaben geändert.
  Besonders Hilfreich, um z.B. Netzwerkprogramme (RevPiNetIO) oder RevPiPyLoad mit diesen Daten auf dem selben Stand zu halten. Auch die MQTT-Server Funktion von RevPiPyLoad arbeitet mit diesen ersetzten IOs.

  # Fast selbe Syntax wie der Funktionsaufruf .replace_io(...)
  
  [new_io_name1]
  replace = io_to_replace
  frm = H
  
  [new_io_bit0]
  replace = another_io
  frm = ?
  bit = 0
  
  [new_io_bit5]
  replace = another_io
  frm = ?
  bit = 5

   

• shared_procimg = Ausgänge direkt in das Prozessabbild schreiben (WARNUNG!)
  Diese Option nur in Ausnahmefällen mit True aktivieren!
  RevPiModIO arbeitet mit einem internen Puffer für IOs, der die Geschwindigkeit erheblich erhöht und sicherstellt, dass die Werte aus dem Pythonprogramm garantiert auch im Prozessabbild stehen.
  Wenn mehrere Instanzen oder Programme das Prozessabbild verwenden sollen, würde jede Instanz ständig versuchen seine Ausgänge zu setzen und es entsteht ein chaotischer Zustand (Flackernde Ausgänge / Falsche Eingangswerte).
  Wird diese Option aktiviert, werden die Ausgänge, bei Zuweisung eines neuen Werts, direkt in das Prozessabbild geschrieben. Wenn sehr viele Ausgänge pro Zyklus verändert werden, könnte dies die Leistung beeinflussen.
  Hinweis: Es muss damit gerechnet werden, dass ein Ausgang, den das Python Programm auf True setzt, im nächsten Zyklus schon wieder False sein kann, wenn er von einem anderen Programm im Prozessabbild verändert wurde.

Klassenobjekte

• .app
  Zugriff auf piCtory Konfigurationsdaten
• .core
  Direktzugriff auf den RevPi Core (LEDs und Statuswerte)
• .device
  Dieses Objekt beinhaltet alle Devices
• .io
  Dieses Objekt beinhaltet alle IOs
• .summary
  Zusammenfassung von piCtory

Klassenattribute

• .cycletime
  Setzt oder gibt die aktuelle Zykluszeit bei autorefresh=True für die Prozessbildaktualisierung in Millisekunden zurück.

• .exitsignal
  Dieses Event sollte der Benutzer verwenden, um eigene Endlosschleifen zu erstellen, welche beim Programmende (.handlesignalend(...)) oder nach Aufruf von .exit() sauber verlassen werden können.
  Dies bietet sich an, wenn das Programm z.B. den .mainloop mit blocking=False verwendet und neben dem Eventsystem auch zyklische Aufgaben erledigen soll.

  # Eventsystem aktivieren, aber nicht blockieren
  rpi.mainloop(blocking=False)
  
  # Zusätzliche Aufgaben zyklisch erledigen
  while not rpi.exitsignal.is_set():
  
      # A1 LED blinken lassen
      rpi.core.a1green.value != rpi.core.a1green.value
  
      # Blinkfrequenz (nicht time.sleep verwenden, da es blockiert!)
      rpi.exitsignal.wait(0.5)

• .ioerrors
  Gibt die Anzahl der aufgetretenen Lese- / Schreibfehler zurück. Ein Reset des Wertes kann durch .resetioerrors() durchgeführt werden.

• .length
  Gibt die Anzahl der, durch IOs, belegten Bytes im Prozessabbild zurück.

• .maxioerrors
  Ist dieser Wert 0 (Standardwert) werden Lese- / Schreibfehler lediglich gezählt. Wird hier ein Wert größer 0 angegeben, wird beim Erreichen eine Exception im Pythonprogramm ausgelöst.

Klassenfunktionen

.autorefresh_all()

Setzt alle Devices in den AutoRefresh-Modus, sollte dies bei der Instanziierung mit autorefresh=True nicht gemacht worden sein oder nach Aufruf von .exit() ohne Parameter full=False.

.cleanup()

Bereinigt das gesamte Modul, beendet die Loops, das AutoRefresh und schließt alle FileHandler. Diese Funktion kann in der interaktiven Pythonshell verwendet werden. Bei einem Pythonprogramm erledigt dies der „Garbage Collector“ automatisch.

.cycleloop(func, [cycletime=50, blocking=True])

Der aktuelle Programmthread wird hier bis Aufruf von .exit() „gefangen“. Er führt nach jeder Aktualisierung des Prozessabbilds die übergebene Funktion „func“ aus und arbeitet sie ab. Während der Ausführung der Funktion wird das Prozessabbild nicht aktualisiert. Die Inputs behalten bis zum Ende den aktuellen Wert. Gesetzte Outputs werden nach Ende des Funktionsdurchlaufs in das Prozessabbild geschrieben.
Verlassen wird der Cycleloop, wenn die aufgerufene Funktion einen Rückgabewert nicht gleich None liefert (.z.B. return 1), oder durch Aufruf von .exit().
HINWEIS: Die Zeit für die Prozessabbildsynchronisierung und die Laufzeit der Funktion dürfen die eingestellte .cycletime Zeit, bzw. übergebene cycletime nicht überschreiten!

• cyclefunction
  Diese übergebene Funktion wird zyklisch nach dem Lesen der Inputs ausgeführt. Die Outputs werden nach Ausführung geschrieben.
  Der Funktion wird eine Instanz von Cycletools() übergeben, welche die Akzeptieren muss: def zyklusfunktion(ct):
• cycletime
  Über den optionalen Parameter kann die Aktualisierungsrate für das Prozessabbild gesetzt werden (selbe Funktion wie das Setzen von .cycletime).
• blocking
  Wird dieser Parameter auf False gesetzt, blockiert das Programm NICHT an dieser Stelle. Die Zyklusfunktion wird wie gewohnt ausgeführt und das Programm kann weitere Aufgaben erledigen.

.exit([full=True])

Diese Funktion beendet den .cycleloop() oder .mainloop() und gibt den Ablauf wieder an den Teil des Pythonprogramms ab, an der eine Loopfunktion aufgerufen wurde.

• full=True
  Wenn Parameter full True ist (Standardwert) werden alle Devices aus dem AutoRefresh entfernt. Das Prozessabbild wird ein letztes Mal synchronisiert um sicherzustellen, dass alle Änderungen synchron sind.

.export_replaced_ios([filename="replace_ios.conf"])

Mit dieser Funktion können alle IOs, die in dieser Instanz durch .replace_io(...) erzeugt wurden, exportiert werden. Damit ist ein Import in anderen Insanzen oder in RevPiPyLoad möglich. Es werden im RevPiPyControl diese neuen IOs angezeigt und können von RevPiNetIO über das Netzwerk bezogen werden.

• • filename="replace_ios.conf"
    Pfad und Dateiname, unter welchem die Datei angelegt werden soll. Wir empfehlen bei Verwendung von RevPiPyLoad diese Funktion ohne Parameter aufzurufen um die Datei in "/var/lib/revpipyload/replace_ios.conf"abzulegen und die Konfigurationsdatei revpipyload.conf anzupassen.

.handlesignalend([cleanupfunc=own_function])

Wird diese Funktion aufgerufen, übernimmt RevPiModIO die Signal-Handler für SIGINT und SIGTERM. Diese werden Empfangen, wenn das Betriebssystem oder der Benutzer das Steuerungsprogramm sauber beenden will.  Nach einmaligem Empfangen eines der Signale und dem Beenden der RevPiModIO Threads / Funktionen werden die SignalHandler wieder freigegeben.
Außerdem wird das .exitsignal bei SIGINT / SIGTERM gesetzt.

• cleanupfunc
  Die optional angebbare Funktion wird als letztes nach dem letzten Einlesen der Inputs ausgeführt. Dort gesetzte Outputs werden nach Ablauf der Funktion ein letztes Mal geschrieben. Gedacht ist dies für Aufräumarbeiten, wie z.B. das abschalten der LEDs am RevPi-Core.

.mainloop([freeze=False, blocking=True])

Der aktuelle Programmthread wird hier bis Aufruf von .exit() „gefangen“ (es sei denn blocking=False). Er durchläuft die Eventüberwachung und prüft Änderungen der, mit einem Event registrierten, IOs. Wird eine Veränderung erkannt, führt das Programm die dazugehörigen Funktionen der Reihe nach aus.

• • freeze=False
    Wenn diser Parameter mit True angegeben ist, wird die Prozessabbildsynchronisierung angehalten bis alle Eventfunktionen ausgefuehrt wurden. Inputs behalten für die gesamte Dauer ihren aktuellen Wert und Outputs werden erst nach Durchlauf aller Funktionen in das Prozessabbild geschrieben.
  • blocking=True
    Wenn dieser Parameter mit False angegeben wird, aktiviert dies die Eventüberwachung und blockiert das Programm NICHT an der Stelle des Aufrufs. Eignet sich gut für die GUI Programmierung, wenn Events vom RevPi benötigt werden, aber das Programm weiter ausgeführt werden soll.

.readprocimg()

Einlesen aller Inputs aller Devices vom Prozessabbild.

Hinweis: Devices mit aktiverem autorefresh werden ausgenommen!

• Rückgabewert ist True, wenn Arbeiten an allen Devices erfolgreich waren.

.resetioerrors()

Setzt die gezählten Lese- / Schreibfehler des Prozessabbildes auf 0 zurück. Das Attribut .ioerros beginnt dann wieder bei 0 mit der Zählung.

.setdefaultvalues()

Alle Outputs werden auf die piCtory default Werte gesetzt.

Hinweis: Sollte autorefresh nicht aktiv sein, müssen alle Outputwerte über .writeprocimg() in das Prozessabbild geschrieben werden.

.syncoutputs()

Einlesen aller aktuellen Outputwerte aus dem Prozessabbild. Kann für Erstsynchronisierung genutzt werden, sollte bei Instanziierung syncoutputs=False gewesen sein.

Hinweis: Devices mit aktiverem autorefresh werden ausgenommen!

• Rückgabewert ist True, wenn Arbeiten an allen Devices erfolgreich waren

.writeprocimg()

Schreiben aller Outputwerte in das Prozessabbild.

Hinweis: Devices mit aktiverem autorefresh werden ausgenommen!

• Rückgabewert ist True, wenn Arbeiten an allen Devices erfolgreich waren
  

  ---