QmixSDK for Python
python_logo.svg

Python Integration

The QmixSDK 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 Qmix SDK shared libraries and uses the Python ctypes module to access the C interface of the SDK libraries.

To use the QmixSDK 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 shared libraries of the SDK and that it finds the python modules of the SDK. There are two different ways to accomplish this. The first way is, to write code in your python script before any Qmix SDK module import. In the following example we have installed the Qmix SDK on a Windows machine into the folder C:/QmixSDK. Now you need to write the following code into your python file to access the QmixSDK:

import sys
import os
qmixsdk_dir = "C:/QmixSDK"
sys.path.append(qmixsdk_dir + "/lib/python")
os.environ['PATH'] += os.pathsep + qmixsdk_dir

The code appends the Qmix SDK module path C:/QmixSDK/lib/python to the module search path to enable Python to find the SDK modules. Then the directory C:/QmixSDK is appended to the environment 'PATH' variable. This enables Python to find and load the required shared libraries (DLLs) from the SDK folder.

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 QmixSDK. It is not possible to do this inside of you 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 QmixSDK. Look into runtest.sh to see how the script calls the python tests:

LD_LIBRARY_PATH=QMIXSDK_DIR/lib:"$LD_LIBRARY_PATH"
export LD_LIBRARY_PATH

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

~/QmixSDK_Linux/python/python-wrapper my_qmix_python_script.py

Now you can import the Qmix 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()
...

If you don't want do this in your Python source file, then you can also use environment variables that you set before you execute your Python file.

set PATH=C:/QmixSDK;%PATH%
set PYTHONPATH=%PYTHONPATH%;C:/QmixSDK/lib/python
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 Qmix SDK.

The Python integration was developed and tested with Python 3.6.5.


Running Python tests

With the test cases you can check, if the QmixSDK 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

runtest.bat test_qmixpump.py

or on Linux with

./runtest.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.


Getting Started

Read the Getting Started section to get started using the Qmix 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.