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

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.


Qmix Python SDK for Linux

The Qmix Python SDK for Linux supports the Linux SocketCAN driver. That means, all CAN devices that support the SocketCAN layer are supported by the SDK. The SDK folder device_driver contains the SocketCAN drivers for the IXXAT USB-to-CAN interface and for the SYSTEC USB-CANmodul1. Follow the instructions in the device driver archives to install the device driver for you USB-CAN hardware.

Note
The Qmix SDK depends on the Qt5 libraries Qt5Core and Qt5SerialPort. You need to ensure that both libraries are properly installed on your Linux system.

SYSTEC USB-CANmodul driver for Linux

After disconnecting and plugging in the USB cable or after each restart/hibernation the correct CAN bitrate must be set and the CAN interface needs to get started. This can be done with:

ip link set can0 type can bitrate 1000000
ip link set can0 up

If necessary, the interface can also be restarted:

ip link set can0 type can restart

For more information please use the included readme.txt from SysTec (e.g. to use candump).


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.