Documentation – RevPiModIO 2

The main class, which is instantiated and provides all access to the IOs of the Revolution Pi.

From the RevPi Bookworm image, the user who executes the process must be a member of the picontrol group (pi is a member of the group by default). In the event of a PermissionDenied error, this should be the first to check. With sudo usermod -a -G picontrol newuser, for example, the user newuser can be added to the group.

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

Further specialized instantiations

Use only specific devices
revpimodio2.RevPiModIOSelected(deviceselection, [autorefresh=False, monitoring=False, syncoutputs=True, debug=False, replace_io_file=None, shared_procimg=False])
  • deviceselection = Single or list of Devices of the RevPi Core to be managed.
    You can use the name <class ‘str’>, the position number <class ‘int’> or a list <class ‘list’> of names or position numbers.
Use virtual device to write data to inputs (driver)
revpimodio2.RevPiModIODriver(virtdev, [autorefresh=False, syncoutputs=True, debug=False, replace_io_file=None, shared_procimg=False])
  • virtdev = Name or position number of a virtual device as <class ‘str’> or <class ‘int’> or a list name / position number <class ‘list’>. In these virtual devices data can be written to inputs and just read outputs. This means that other applications can access this data via the process image.

NOTE: Parameter ‘monitoring’ and ‘simulator’ are not available here because they are set automatically.

Instantiating Parameters

  • autorefresh = Update process Image automatically
    This Parameter should ALWAYS be set to True. The module automatically synchronizes the IOs in the Background. The default value for the cycle time depends on the hardware or mode:
    Core 1: 40 Milliseconds (25 Hz)
    Core3 / Connect: 20 Milliseconds (50 Hz)
    NetIO: 50 Milliseconds (20 Hz)
    The value can be changed via .cycletime. The use of .cycleloop(...) or .mainloop(...)is only possible if AutoRefresh is activated!

  • monitoring = If True: Read IOs only, never write them
    If this parameter is set to True, the IOs are read, but never written. This serves e.g. for Monitoring when another software controls the process image.

  • syncoutputs = Read outputvalues, while instantiating
    In Standard this parameter is set to True  and reads the current output values for instantiation.

  • debug = If True, prints detailed error messages
    This parameter is set to False in the default and can be used for error detection, if set to True. The library will then issue detailed error messages that may be helpful during the development phase.

  • replace_io_file = File with definitions of IOs, which should be changed
    As an alternative to .replace_io(…) in the Python program, a file can be created, which the library uses when instantiating. The IOs are changed as specified.
    Especially helpful, for Network programs with (RevPiNetIO) or RevPiPyLoad to have the same replaced IOs. The MQTT server function of RevPiPyLoad also works with these replaced IOs.

    # Almost the same syntax as the function call .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 = Write outputs without buffer to process image (WARNING)
    Only activate this option in exceptional cases with True!
    RevPiModIO uses an internal buffer for IOs, which significantly increases the speed and ensures that the values from the Python program are guaranteed to be in the process image as well.
    If multiple instances or programs are using the process image, each instance would constantly set its outputs and create a messy state (flickering outputs / false input values).
    If this option is activated, the outputs are written directly to the process image when a new value is assigned. If many outputs are changed per cycle, this could affect performance.
    Note: It must be expected that an output that the Python program sets to True can already be False in the next cycle if it has been changed by another program in the process image.

Further Parameters for simulations

  • procimg = Alternative path for Processimage
    This Parameter can be used to specify an alternative path for the process Image. This is for simulation applications. If not specified, “/dev/piControl0” is used, which contains the process image on the RevPi.

  • configrsc = Alternative path for piCtory configuration
    An alternative piCtory configuration can be transferred via this parameter. This is for simulation applications. If not specified, the piCtory configuration is automatically used on the RevPi core.

  • simulator = If True, inputs and outputs are swapped
    By transferring True, the inputs and outputs are swapped. This makes it possible to write the inputs and to only read the outputs. This is for simulation applications!
Classobjects
  • .app
    Access to piCtory configurationdata
  • .core
    Direct access on the RevPi Core (LEDs and status values)
  • .device
    This object includes all devices
  • .io
    This object includes all IOs
  • .summary
    Summary from piCtory
Classattributes

  • .cycletime
    Sets or returns the current cycle time in milliseconds at autorefresh=True for process image updating.

  • .exitsignal
    This event should be used by the user to create their own loops, which can be left clean at the end of the program(.handlesignalend(...)) or after calling .exit ().
    This is useful when the program uses the event system with .mainloop(blocking=False) and should also perform cyclic tasks.

    # Start event system, but do not block here
rpi.mainloop(blocking=False)

# Additional cyclic tasks
while not rpi.exitsignal.is_set():

    # Switch A1 LED on / off
    rpi.core.a1green.value != rpi.core.a1green.value

    # Flash frequency (do not use time.sleep it will block!)
    rpi.exitsignal.wait(0.5)

  • .ioerrors
    Returns the number of read / write Errors that occurred. A reset of the value can be executed through .resetioerrors() .

  • .length
    Returns the number of bytes occupied by IOs in the process Image.

  • .maxioerrors
    If this value is 0 (Default value), read / write errors are only counted. If a value greater than 0 is specified here, an exception is triggered in the Python program.

Further attributes for simulation purpose

  • .configrsc
    Returns path of the used piCtory configuration data

  • .monitoring
    Returns value True, if the module was instantiated with monitoring=True , otherwise the value is False

  • .procimg
    Returns the used process Image path.

  • .simulator
    Returns true, if the module was instantiated with simulator=True , otherwise the value is False
classfunctions

.autorefresh_all()

Sets all devices in to the AutoRefresh-mode, if this wasn’t done while instantiating with  autorefresh=True or after the call of .exit() without parameter full=False.

.cleanup()

Cleans the whole module, closes the Loops, AutoRefresh and all FileHandler. This function can be used in the interactive Pythonshell. With a Python program, the “Garbage Collector” does this automatically.

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

The current program thread is “caught” until .exit() is called. It executes the function “func” after each update of the process image and processes it. The process image is not updated during execution of the function. The inputs are keeping the current value until the end. Set Outputs are written into the process Image after the end of the function run.
The cycleloop is left, if the called function does not return a value of  None  (e.g. return 1), or by calling .exit().
NOTE: The time for the process Image synchronization and the running time of the function must not exceed the set .cycletime time or transferred cycletime !

  • cyclefunction
    This passed function is executed cyclically after reading the inputs. The outputs are written after execution.
    The function is passed an instance of  Cycletools() , which must accept:         def zyklusfunktion(ct):
  • cycletime
    The update rate for the process image can be set via the optional parameter (same function as setting .cycletime).
  • blocking
    If this parameter is set to False, the program does NOT block at this point. The cycle function is executed as usual and the program can do other tasks after the call.

.exit([full=True])

This function terminates the .cycleloop() or .mainloop() function and returns the sequence to the part of the Python program, where a Loop function was called.

  • full=True
    If the Parameter full is True (default value), all devices are removed from AutoRefresh. The process image will be synchronized a last time to guarantee all changes are written to it.

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

With this function, all IOs created in this instance by .replace_io(...) can be exported. This allows importing into other instances or in RevPiPyLoad. These new IOs are displayed in the RevPiPyControl and can be obtained from RevPiNetIO via the network.

    • filename="replace_ios.conf"
      Path and file name under which the file should be created. When using RevPiPyLoad, we recommend calling this function without parameters in order to put the file in "/var/lib/revpipyload/replace_ios.conf" and to adapt the configuration file revpipyload.conf.

.handlesignalend([cleanupfunc=own_function])

If this function is called, RevPiModIO takes over the signal handlers for SIGINT and SIGTERM. These are received when the operating system or the user wants to terminate the control program cleanly. After receiving one of the signals and terminating the RevPiModIO threads / functions, the signal handlers are released again.
The .exitsignal will be set on SIGINT / SIGTERM, too.

  • cleanupfunc
    The optional transferable function is executed last, after the last reading of the inputs. Outputs set there, are written one last time after the function has finished. This is entended for cleanup operations, e.g. turning off the LEDs on the RevPi core.

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

The current program thread is “trapped” (unless blocking=False) until  .exit()is called. It passes the Event monitoring and checks changes to the IOs registered with an event. If a change is detected, the program executes the corresponding functions in sequence.

  • freeze=False
    If this parameter is set to True, the process Image synchronization is paused until all event functions have been executed. Inputs retain their current value for the entire duration, and outputs are written to the process image only after all functions have been completed.
  • blocking=True
    If this parameter is specified with False, this activates the event monitoring and does NOT block the program at the location of the call. Good for GUI programming, if events ar

.readprocimg()

Read in all inputs of all devices from the process image.

Note: Devices with activated autorefresh are excluded!

  • The returned value is True, if work on all devices was successful.

.resetioerrors()

Resets the counted read / write errors of the process image to 0. The .ioerros attribute then begins the count at 0 again.

.setdefaultvalues()

All outputs are set to ethe piCtory default values.

Note: If autorefresh is not active, all output values must be written to the process Image via .writeprocimg().

.syncoutputs()

Read all current output values from the process Image. Can be used for initial synchronization, if it was  syncoutputs=False at instantiation.

Note: Devices with activated autorefresh are excluded!

  • The returned value is True, if the work on all devices were successful

.writeprocimg()

Write of all output values in to the process Image.

Note: Devices with activated autorefresh are excluded!

  • The returned value is True, if the work on all devices were successful