Dokumentation – RevPiModIO 2

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

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

Weitere spezialisierte Instantierungen

Nur bestimmte Devices verwenden
revpimodio2.RevPiModIOSelected(deviceselection, [autorefresh=False, monitoring=False, syncoutputs=True, debug=False, replace_io_file=None, direct_output=False])
  • deviceselection = Einzelnes oder Liste von Devices des RevPi-Core, welche verwaltet werden sollen.
    Dabei kann sowohl der Name <class ’str‘>, die Positionsnummer <class ‚int‘> oder eine Liste <class ‚list‘> mit Namen oder Positionsnummern übergeben werden.
Virtuelles Device zum Schreiben der daten in Inputs verwenden (Treiber)
revpimodio2.RevPiModIODriver(virtdev, [autorefresh=False, syncoutputs=True, debug=False, replace_io_file=None, direct_output=False])
  • virtdev = Name oder Positionsnummer eines virtuellen Device als <class ’str‘> oder <class ‚int‘> oder eine Liste der Namen / Positionsnummern <class ‚list‘>. In diese virtuellen Devices können Daten in Inputs geschrieben und Outputs gelesen werden. Damit kann mit anderen Anwendungen über das Prozessabbild auf diese Daten zugegriffen werden.

HINWEIS: Parameter ‚monitoring‘ und ’simulator‘ stehen hier nicht zur Verfügung, da diese automatisch gesetzt werden.

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

     

  • direct_output = 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öt 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 kaotischer 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.

Weitere Parameter für Simulationszwecke

  • procimg = Alternativer Pfad für Prozessabbild
    Über diesen Parameter kann ein alternativer Pfad für das Prozessabbild angegeben werden. Dies dient für Simulationseinsätze. Bei Nichtangabe wird „/dev/piControl0“ verwendet, welches auf dem RevPi das Prozessabbild enthält.

  • configrsc = Alternativer Pfad für piCtory Konfiguration
    Über diesen Parameter kann eine alternative piCtory Konfiguration übergeben werden. Dies dient für Simulationseinsätze. Bei Nichtangabe wird auf dem RevPi core automatisch die piCtory Konfiguration verwendet.

  • simulator = Wenn True, werden Inputs und Outputs getauscht
    Durch Übergabe von True, werden die Inputs und Outputs verdreht. Damit ist ein Schreiben der Eingänge und nur das Lesen der Ausgänge möglich. Dies dient für Simulationseinsätze!

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.

Weitere Attribute für Simulationszwecke

  • .configrsc
    Gibt den Pfad der genutzten piCtory Konfigurationsdatei zurück

  • .monitoring
    Gibt True zurück, wenn das Modul mit monitoring=True instanziiert wurde, sonst False

  • .procimg
    Gibt den Pfad des genutzten Prozessabbilds zurück.

  • .simulator
    Gibt True zurück, wenn das Modul mit simulator=True instanziiert wurde, sonst False

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])

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).

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

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([full=True])

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 übergebbare 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 fuer Aufräumarbeiten, wie z.B. das abschalten der LEDs am RevPi-Core.

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

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.
  • no_warn=False
    Wenn Events Funktionen ausführen, wird deren Laufzeit überwacht und eine Warnung generiert, wenn Diese zu viel Zeit in Anspruch nehmen. Durch Setzen von no_warn=True können die Warnungen deaktiviert werden.

.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