piControl is the central system driver of the Revolution Pi system. The driver forms the technical basis for the real-time communication between the Linux operating system on the RevPi base module and the RevPi expansion modules.

Tasks of piControl:

  • provides the cyclically updated process image

  • Reads in the RevPi I/O module values of cyclically

  • Transmits the data for the outputs to the RevPi I/O modules

  • Configures the RevPi I/O modules according to the PiCtory configuration file

Process Image #

piControl generates a continuously updated memory image of all I/O data. This image can be read or written by programs such as Node-RED or Python scripts.

piControl provides a device file /dev/piControl0, which applications can use to read and write to the process image.

Configuration File #

piControl reads the configuration of the Revolution Pi system from the configuration file /etc/revpi/config.rsc, which is typically created with PiCtory, and sets up the RevPi devices accordingly.

Reset Driver #

The driver can be reset via PiCtory. This re-reads the PiCtory configuration file and all values will be reset to their default values.

▷ Start PiCtory.

▷ Select Tools › Reset Driver.

Alternatively, the driver can be reset using the command line tool piTest:

piTest -x

Cycle Time #

The cycle time defines how often all values are exchanged between the RevPi base module and the I/O modules. By default, a cycle is executed as quickly as possible. The time for a cycle can be adjusted via a kernel module parameter.

  • A longer cycle time reduces the CPU load.

  • A shorter cycle time allows a faster response to input and output values.

The cycle time metrics can be read from files in the directory /sys/class/piControl/piControl0/.

Metric Function

cycle_duration

Cycle time in microseconds. Default value is 500 and is semantically interpreted as "as fast as possible", therefore cycles_missed is not increased. Can be modified by writing a value >500.

min_cycle

Shortest measured cycle time since the start of piControl. Can be reset by writing a 0.

max_cycle

Longest measured cycle time since the launch of piControl. Can be reset by writing a 0.

max_cycle_deviation

Maximum tolerated deviation from the set cycle time in microseconds.

cycles_exceeded

Number of cycles that were longer than the cycle time. Is influenced by cycle_duration and max_cycle_deviation.

cycles_missed

Number of cycles that were missed due to the cycle time being set too low and the current cycle being too long. Is influenced by cycle_duration and max_cycle_deviation.

last_cycle

The time it took to complete the last cycle.

Read out Cycle Time #

▷ Log in to the RevPi via a terminal.

▷ Read the cycle time from with:

cat /sys/class/piControl/piControl0/cycle_duration

❯ The default value 500 is semantically interpreted as "as fast as possible".

Adjust Cycle Time (persistent) #

▷ Define a new kernel module parameter to adjust cycle time by creating a file with the file extension .conf under /etc/modprobe.d.

▷ Define a cycle time cycle_duration in microseconds.

▷ Reset the driver with:

piTest -x

Example:

For a cycle time of 20 milliseconds, create a file /etc/modprobe.d/picontrol-cycle-duration.conf with:

options piControl picontrol_cycle_duration=20000

The new kernel module parameter is only applied after resetting the piControl driver or after restarting the RevPi.

Adjust Cycle Time (non-persistent) #

Alternatively, the cycle time can be changed during the runtime of the piControl driver via the file cycle_duration.

▷ Set a non-persistent cycle time of e.g. 20 milliseconds with:

echo "20000" | sudo tee /sys/class/piControl/piControl0/cycle_duration

Communication Errors #

The RevPi I/O modules exchange data with the RevPi base module via a serial line. The data is transmitted electrically according to the RS485 standard. The status byte RS485ErrorCnt counts the number of communication errors via this internal RS485 bus.

At the end of each cycle, the error counter is compared with the two limit values RS485ErrorLimit1 and RS485ErrorLimit2. If it has reached RS485ErrorLimit1, a message is output in kern.log.

As default, RS485ErrorLimit1 is set to 10 and RS485ErrorLimit2 is set to 1000.

See also: Status bytes RS485ErrorCnt and RS485ErrorLimit

Disabling piControl #

In special applications, it may be necessary to deactivate piControl.

▷ Log in to the RevPi via a terminal.

▷ Deactivate piControl with:

sudo rmmod piControl

▷ Reactivate piControl with:

sudo modprobe piControl

After rebooting a RevPi, piControl is restarted automatically.

To deactivate piControl permanently, the configuration must be adapted:

▷ Log in to the RevPi via a terminal.

▷ Open the file /etc/modules-load.d/picontrol.conf in an editor.

▷ Comment out the line for piControl with #.

▷ Save and close the file.

Further Resources #