Running Python scripts on the iCube Controller

Version Number	Description
1.0	First steps to run Python scripts on the iCube Controller.

This application note shows the basics to run Python scripts on the iCube Controller, mainly Python Packages installation and running the scripts from the application code.

1. Supported Components

Component Name	Version
iC9200 series	≥ 2023.9
iCube Engineer	≥ 2023.9
Python	(Version installed on the iCube Controller)

2. Supported Libraries

PLCnextBase_1_5_1

3. Solution details

Integrating Python into an automation project using the iCube Controller can extend the range of functionalities available. However, beware that Python cannot be used to program real-time applications in the Execution and Synchronization Manager (ESM, more info here). Instead, Python scripts can be used on the Operative System (OS) level and they can be launched from a real-time application.

3.1 Verify Python version

The first step to work with Python is knowing which version is installed in the system. For this, create a connection to the controller viaSecure Shell (SSH) and login as an admin user (login as other user should be possible as well, but for this document admin user is assumed). To do that from the command line, type the following command into the shell:

        ssh <username>@<host_ip_address>

After typing the correct password, the connection should be established. Now type the following command to know the Python version installed on the controller:

        python3 --version

The result will show the current Python version, as seen in the following image:

3.2 Install Python Packages offline using pip

Bootstrap pip

The Package Installer for Python (pip) is available in the controller from its factory settings. However, it needs to be bootstrapped in the first use (or after every factory-settings reset) to be accessible from the command line. To do the bootstrap, first create a root user (if root user already exists skip this part) using the following command:

        sudo passwd root

Add the current user's password and then select a password for the root user. To login as a root user simply type the following line when logged in as another user:

        su - root

Or use the following command if the ssh connection is to be created:

        ssh root@<host_ip_address>

Once logged in as a root user, type the following command to ensure the use of pip:

        python3 -m ensurepip --default-pip

Now pip should be ready to use. This can be verified from any user by typing:

        python3 -m pip --version

Or simply:

        pip --version

The result will show the installed pip version, as seen in the following image:

Further information about ensuring pip is available in the official site.

Install Python Packages

After successfully bootstrapping pip, the controller is ready to install packages. You can see the current pip-installed packages using the following command when connected through ssh:

        pip list

Packages that need to be used in Python projects run from the application code using PBCL_SysLinuxShell_1 should be installed with plcnext_firmware or root user access level. This means that the previous command to check the list of installed packages and all the following steps run in the controller's Linux terminal should be executed when logged in with plcnext_firmware or root permissions.

If the package to be used is not installed, the next step is to download the wheel file (.whl extension) and send it to the controller. To download the wheel file go to the official site of the package (for example, to install PyPlcnextRsc for RSC communication go here). Then send the .whl file to the controller using an SSH File Transfer software (like WinSCP) or using the following command from the PC shell:

        scp <origin_filepath_local> <username>@<host_ip_address>:<destination_filepath_controller>

This procedure should look similar to the following image in the command line:

Finally to install the package run the following command inside the controller:

        pip install --no-index --find-links=<whl_filepath_no_filename> <package_name>

The '--no-index' tag disables trying to find the package in PyPI (online) and '--find-links=<path>' specifies where to find the .whl file locally. This procedure should look similar to the following image in the command line:

The package now should be available to program with its components. To test the correct installation type the following command and verify that the package is on the list:

        pip list

Another way is testing directly on the Python environment. Type the following command to open an interactive session:

        python3

When the Python session is opened type the following line (notice the '>>>' to identify Python code in contrast to command line instructions):

    >>> import PyPlcnextRsc

If Python doesn't throw an error, the Python package is now accessible for programming. The wheel file (.whl) can be deleted after installation.

3.3 Run Python scripts from the application code using iCube Engineer

After all the installations are done a Python script can be launched from the application code of iCube Controller. The project needs to include the PLCnextBase_1_5_1 system library to access the PBCL_SysLinuxShell_1 Function Block. With this, it is possible to interact with the Linux shell from the application code similarly as it's done from the command line. This Function Block executes instructions with 'plcnext_firmware' user rights.

The first step is transferring the Python script from the local PC to the controller, use the following command to do so (skip this step if the script is already in the controller):

        scp <origin_filepath_local> <username>@<host_ip_address>:<destination_filepath_controller>

To run the Python script using PBCL_SysLinuxShell_1, set the inputs "anyCommand" and "anyResult" as string data types (preferably as user-defined strings to control the amount of text that can be read as a result). Set "anyCommand" to the following instruction to run the Python code from the application code:

        python3 <filepath_including_filename_and_extension>

Finally set the "xExecute" input to TRUE to execute the Function Block. The "anyResult", "wDiagCode", and "wAddDiagCode" variables will inform about the result of the execution of the Function Block. "anyResult" shows the response from the shell while"wDiagCode" and "wAddDiagCode"are specific to the Function Block (see PBCL_SysLinuxShell_1 documentation for more details).