Python Integration

The CETONI SDK comes with full Python integration. For Windows you find the Python integration in the subfolder lib/python and for Linux in the subfolder python. The Python integration is based on the CETONI SDK shared libraries and uses the Python ctypes module to access the C interface of the SDK libraries.

Running Python Console Tests

With the test cases you can quickly check, if the CETONI SDK Python integration runs properly on your system. To run a test case, you should open a terminal and change into the python folder that contains the runtest.bat or runtest.sh file. Now you can execute the test cases on Windows with

1 run_pytest.bat test_qmixpump.py

or on Linux with

1 ./run_pytest.sh test_qmixpump.py

For all tests a valid device configuration is required. You can pass in the device configuration folder as a parameter for a test. The runtest.bat or runtest.sh files use the simulated test configuration config/testconfig_qmixsdk. All devices in this test configuration are simulated.

Running Python GUI Tests

The CETONI SDK Pyside Demo allows you to quickly get started with GUI development in the context of the CETONI SDK for Python. You can run the project by first creating a virtual environment in root folder with

1 virtualenv venv

Next you need to activate the virtual environment on Windows with

1 .\\venv\\Scripts\\activate

or on Linux with

1 source venv/bin/activate

Now you can install all Python requirements (including PySide) by calling

1 pip install -r requirements.txt

Finally you can run the code with

1 python mainwindow.py

The device configuration is passed in the mainwindow.py file in the deviceconfig variable. The mainwindow.py file uses the simulated test configuration config/testconfig_qmixsdk. All devices in this test configuration are simulated.

Using the Python Integration

To use the CETONI SDK you need to create a valid device configuration. Read the Getting Started section to learn how to create a device configuration and what a device configuration is.

The python integration is essentially a wrapper for the C interface of the SDK. That means, you can use the C API documentation for the Python integration. The Python integration wraps the C interface into Python classes. That means, the functions in the qmixbus.Bus class are documented in the labbCAN Bus API, the functions in the qmixpump.Pump class are documented in the labbCAN Pump API and so on.

If you use the Python integration, then you need to ensure that Python finds the Python modules and the shared libraries of the SDK. To ensure that the qmixsdk module is found, the path to the module folder needs to be in the Python module search path. There are two ways to achieve that. The first way is, to write code in your python script before any CETONI SDK module import. In the following example we have installed the CETONI SDK on a Windows machine into the folder C:/QmixSDK. Now you need to write the following code into your Python file before you import anything from the qmixsdk module.

 import sys
 
 sys.path.append("C:/QmixSDK/lib/python")

The code appends the CETONI SDK module path C:/QmixSDK/lib/python to the module search path to enable Python to find the SDK modules.

The second way is to modify the PYTHONPATH environment variable to contain the directory where the qmixsdk module is located before starting the interpreter.

1 set PYTHONPATH=C:\temp\QmixSDK64\lib\python;%PYTHONPATH%;

If you are working on Windows, then you are finished now and everything should work. The qmixsdk module contains code that ensures, that the shared libraries are found.

If you use the Python integration on Linux, then you need to set the LD_LIBRARY_PATH environment variable properly to enable the ctypes module to find the shared libraries of the CETONI SDK. It is not possible to do this inside of your Python script, you need to do this before you run your python scripts. The LD_LIBRARY_PATH needs to point to the lib folder of the CETONI SDK. Look into run_pytest.sh to see how the script calls the python tests. So that means, on Linux you need to export the following environment variables:

 export QMIXSDK_PATH="$HOME/QmixSDK_Linux"
 export PYTHONPATH="$QMIXSDK_PATH/python":"$PYTHONPATH"
 export LD_LIBRARY_PATH="$QMIXSDK_PATH/lib":"$LD_LIBRARY_PATH"

Alternatively you can use the provided wrapper script qmixsdk_py_wrapper.sh instead of calling python when executing your scripts:

1 ~/QmixSDK_Linux/python/qmixsdk_py_wrapper my_qmix_python_script.py

Now you can import the CETONI SDK modules and use them:

 from qmixsdk import qmixbus
 from qmixsdk import qmixpump
 from qmixsdk import qmixvalve
 from qmixsdk.qmixbus import UnitPrefix, TimeUnit
 
 bus = qmixbus.Bus()
 ...

Note: Make sure to use the correct SDK version (32-bit or 64-bit) for your Python installation. If you are using the 64-bit version of Python, you also need the 64-bit version of the CETONI SDK.

The Python integration was developed and tested with Python 3.6.5. and Python 3.8.2

Getting Started

Read the Getting Started section to get started using the CETONI SDK functions of the Python integration. The source code of the tests will also help you to understand how to use the Qmix Python integration.