Qmix SDK  20180626
The software libraries for integration of all CETONI devices.
Overview

Introduction

QmixSDK_Tiles.png

This documentation provides the instructions for the implemented functions. The library is arranged in groups of functions and helps to simplify the programming of the control software based on Windows. This document describes the interface between a program and the Windows DLL (Dynamic Link Library).

THERE IS NO WARRANTY FOR THIS LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THIS LIBRARY IS WITH YOU. SHOULD THIS LIBRARY PROVE DEFECTIVE OR INSUFFICIENT, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

The latest edition of these documentation, additional documentation and software for the labCAN library may also be found on the Internet under https://www.cetoni.de/fileadmin/user_upload/Documents/Manuals/QmixSDK/index.html


Architecture

The labbCAN C API provides a native C API for using the object oriented labbCAN libraries. It is essentially a set of C wrappers for the C++ class member functions. The intention is to provide an API for programming languages that do not support an object oriented interface like Visual Basic or National Instruments LabVIEW. This C API also forms the base for the Qmix SDK LabVIEW integration that is based on the Windows DLLs that are compiled from this C API.

The following picture illustrates the labbCAN Library architecture.

labbCAN_Architecture.png
labbCAN Architecture

The labbCAN library consists of a number of ready to use Windows DLLs (Dynamic Link Libraries). Each single DLL covers a certain kind of device. All device DLLs are glued together by a common labbCAN Bus DLL . This labbCAN Bus DLL hides the real physical connection of the devices from the user and presents a "software bus" to the application engineer. All devices that are supported by these device DLLs are attached to this "software bus". Whenever a user wants to control a device he always needs the labbCAN Bus DLL because this DLL manages the imaginary "bus" and provides common device independent functions. The labbCAN Bus library offers a device independent, clean and well defined API to control the attached devices in a common way independent from the physical bus.

The following types of devices are currently supported by the labbCAN library:


Qmix SDK for Windows

Installation Directory Content

The Qmix SDK for Windows setup installs a number of files into the final installation folder. The following overview shows which files are installed into which folders:

  • Root Installation Folder - contains all the Windows DLL files needed for the API in order to run properly and all unit test cases (*.exe). You have to copy the DLLs to the working directory of your system or to the application directory that contains your application EXE file.
    • config - provides the configuration files for running the provided tests (the configuration use simulated devices only)
    • doc - contains the compiled version of this HTML documentation
    • examples - here you find a number of C examples that show how to use the different labbCAN libraries
    • include - contains an C language files for each single labbCAN library
    • lib - Contains the import libraries for various compilers and IDEs
      • delphi - Contains some examples that show how to integrate the SDK into Delphi
      • labview - Contains the Qmix SDK LabVIEW integration with all VI's
      • matlab - Contains a matlab example file
      • mingw - Contains the import libraries for MinGW compiler (GCC 5.3.0)
      • python - Contains the complete Python integration for the Qmix SDK
    • plugins - contains the LED array plugin and may be used for later addition of custom plugins

Running the unit tests

With the test cases you can check, if the SDK runs properly on your system. To run a test case, you should open a command line window and change into the root installation directory. Now you can execute the test cases with the runtest.bat test runner like in the following example:

runtest capi_nemesys_test.exe
Note
All tests run with a device configuration with simulated devices. That means, if you have real devices connected, then nothing will move.

Qmix SDK for Linux

Installation Directory Content

The Qmix SDK for Linux archive extracts a number of files into the final SDK folder. The following overview shows which files are available in which directories;

  • Root SDK Folder - contains all unit test cases.
    • config - provides the configuration files for running the provided tests (the configuration use simulated devices only)
    • device_driver Contains the SocketCAN device drivers for the USB-CAN interfaces from IXXAT and SysTec that have been tested with the SDK.
    • doc - contains this HTML documentation
    • examples - here you find a number of C examples that show how to use the different labbCAN libraries
    • include - contains the C include files for each single labbCAN library
    • lib - Contains all shared Linux libraries of the SDK. The SDK does not use the system libraries but ships its own libraries to prevent incompatibilities. The SDK has been compiled on an Ubuntu 14.04 VM.
    • plugins - contains the LED array plugin and may be used for later addition of custom plugins
    • python Contains the complete Python integration for the Qmix SDK

Use the SDK's shared libraries

To link against the SDK's shared libraries and to use the SDK's shared libraries you need to ensure, that the lib folder of the SDK is the first folder in the library search paths. You can do this by prepending the lib folder to the LD_LIBRARY_PATH environment variable.

LD_LIBRARY_PATH=$(pwd)/../lib:"$LD_LIBRARY_PATH"
export LD_LIBRARY_PATH

Running the unit tests

With the test cases you can check, if the SDK runs properly on your Linux system. To run a test case, you should open a terminal and change into the root SDK directory. Now you can execute the test cases

./capi_nemesys_test
Note
All tests run with a device configuration with simulated devices. That means, if you have real devices connected, then nothing will move.