libximc: How to use with...

libximc 3.0.3

How to use with...

To acquire the first skills of using the library, a simple testappeasy_C test application has been created. Languages other than C are supported using calls with conversion of arguments of the stdcall type. A simple C test application is located in the 'examples/test_C' directory, a C# project is located in 'examples/test_CSharp', on VB.NET - in 'examples/test_VBNET', for matlab - 'examples/test_MATLAB', for Java - 'examples/test_Java', for Python - 'examples/test_Python'. Libraries, header files and other necessary files are located in the directories 'ximc/win32', 'ximc/win64','ximc/macosx' and the like. The developer kit also includes already compiled examples: testapp and testappeasy x32 and x64 bits for windows and only x64 bits for macOS, test_CSharp, test_VBNET, test_Java - cross-platform, test_MATLAB and test_Python do not require compilation.

Note
  SDK requires Microsoft Visual C++ Redistributable Package (provided with SDK - vcredist_x86 or vcredist_x64)
  On Linux both the libximc7_x.x.x and libximc7-dev_x.x.x target architecture in the specified order. For install packages, you can use the .deb command: dpkg -i filename.deb, where filename.deb is the name of the package (packages in Debian have the extension .deb). You must run dpkg with superuser privileges (root).

## Visual C++

Testapp can be built using testapp.sln. Library must be compiled with MS Visual C++ too, mingw-library. Make sure that Microsoft Visual C++ Redistributable Package is installed.

Open solution examples/testapp/testapp.sln, build and run from the IDE.

In case of the 8SMC4-USB-Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in testapp.c file before build (see enumerate_hints variable).

## CodeBlocks

Testappeasy_C and testapp_C can be built using testappeasy_C.cbp and testapp_C.cbp respectively. Library must be compiled with MS Visual C++ too, mingw-library. Make sure that Microsoft Visual C++ Redistributable Package is installed. *

Open solution examples/test_C/testappeasy_C/testappeasy_C/testappeasy_C.cbp or examples/test_C/testapp_C/testapp_C.cbp, build and run from the IDE.

## MinGW

MinGW is a port of GCC to win32 platform. It's required to install MinGW package.

MinGW-compiled testapp can be built with MS Visual C++ or mingw library.

mingw32-make -f Makefile.mingw all

Then copy library libximc.dll to current directory and launch testapp.exe.

In case of the 8Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in testapp.c file before build (see enumerate_hints variable).

## C++ Builder

First of all, you should create a library suitable for C++ Builder. Visual C++ and Builder libraries are not compatible Invoke:

implib libximc.lib libximc.def

Then compile test application:

bcc32 -I..\..\ximc\win32 -L..\..\ximc\win32 -DWIN32 -DNDEBUG -D_WINDOWS testapp.c libximc.lib

In case of the 8Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in testapp.c file before build (see enumerate_hints variable).

There is also an unsupported example of using libximc in a C++ Builder project

## XCode

testapp should be built with XCode project testapp.xcodeproj. Library is a macOS framework, and at example application it's bundled inside testapp.app

Then launch application testapp.app and check activity output in Console.app.

In case of the 8Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in testapp.c file before build (see enumerate_hints variable). There is also an example of using the libximc library in a C++ Builder project, but it is not supported.

## GCC

Make sure that libximc (rpm or deb) is installed at your system. Installation of package should be performed with a package manager of operating system. On macOS a framework is provided.

Note that user should belong to system group which allows access to a serial port (dip or serial, for example).

Test application can be built with the installed library with the following script:

make

In case of cross-compilation (target architecture differs from the current system architecture) feed -m64 or -m32 flag to compiler. On macOS it's needed to use -arch flag instead to build an universal binary. Please consult a compiler documentation.

Then launch the application as:

make run

Note: make run on macOS copies a library to the current directory. If you want to use library from the custom directory please be sure to specify LD_LIBRARY_PATH or DYLD_LIBRARY_PATH to the directory with the library.

In case of the 8SMC4-USB-Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in testapp.c file before build (see enumerate_hints variable).

## .NET

Wrapper assembly for libximc.dll is ximc/winX/wrappers/csharp/ximcnet.dll. It is provided with two different architectures. Tested on platforms .NET from 2.0 to 4.5.1

Test .NET applications for Visual Studio 2013 is located at test_CSharp (for C#) and test_VBNET (for VB.NET) respectively. Open solutions and build it.

In case of the 8SMC4-USB-Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in testapp.cs or testapp.vb file (depending on programming language) before build (see enumerate_hints variable for C# or enum_hints variable for VB).

## Java

How to run example on Linux. Go to to examples/test_Java/compiled-winX/ and run:

java -cp /usr/share/java/libjximc.jar:test_Java.jar ru.ximc.TestJava

How to run example on Windows. Go to to examples/test_Java/compiled-winX/. Then run:

java -classpath libjximc.jar -classpath test_Java.jar ru.ximc.TestJava

How to modify and recompile an example. Go to to examples/test_Java/compiled. Sources are embedded in a test_Java.jar. Extract them:

jar xvf test_Java.jar ru META-INF

Then rebuild sources:

javac -classpath /usr/share/java/libjximc.jar -Xlint ru/ximc/TestJava.java

or for Windows or macOS

javac -classpath libjximc.jar -Xlint ru/ximc/TestJava.java

Then build a jar:

jar cmf META-INF/MANIFEST.MF test_Java.jar ru

In case of the 8Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in TestJava.java file before build (see ENUM_HINTS variable).

## Python

Change current directory to the examples/test_Python/xxxxtest. NB: For libximc usage, the example uses the wrapper module ximc/crossplatform/wrappers/python/libximc.

To run:

python xxxx.py

In case of the 8Eth1 Ethernet adapter usage, it's necessary to set correct IP address of the Ethernet adapter in test_Python.py file before launch (see enum_hints variable).

## MATLAB

Sample MATLAB program testximc.m is provided at the directory examples/test_MATLAB. On windows copy ximc.h, libximc.dll, bindy.dll, xiwrapper.dll and contents of ximc/(win32,win64)/wrappers/matlab/ directory to the current directory.

Before launch:

On macOS: copy ximc/macosx/libximc.framework, ximc/macosx/wrappers/ximcm.h, ximc/ximc.h to the directory examples/test_MATLAB. Install XCode compatible with Matlab.

On Linux: install libximc*deb and libximc-dev*dev of target architecture. Then copy ximc/macosx/wrappers/ximcm.h to the directory examples/matlab. Install gcc compatible with Matlab.

For XCode and gcc version compatibility check document https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/SystemRequirements-Release2014a_SupportedCompilers.pdf or similar.

On Windows before the start nothing needs to be done

Change current directory in the MATLAB to the examples/test_MATLAB. Then launch in MATLAB prompt:

testximc

In case of the 8Eth1 Ethernet adapter usage it is necessary to set correct IP address of the Ethernet adapter in testximc.m file before launch (see enum_hints variable).

# Generic logging facility

If you want to turn on file logging, you should run the program that uses libximc library with the "XILOG" environment variable set to desired file name. This file will be opened for writing on the first log event and will be closed when the program which uses libximc terminates. Data which is sent to/received from the controller is logged along with port open and close events.

# Required permissions

libximc generally does not require special permissions to work, it only needs read/write access to USB-serial ports on the system. An exception to this rule is a Windows-only "fix_usbser_sys()" function - it needs elevation and will produce null result if run as a regular user.

# C-profiles

C-profiles are header files distributed with the libximc library. They enable one to set all controller settings for any of the supported stages with a single function call in a C/C++ program.
You may see how to use C-profiles in the example directory "examples/test_C/testprofile_C".

# Python-profiles

Python-profiles are sets of configuration functions distributed with the libximc library. They allow to load the controller with settings of one of the supported stages using a single function call in a Python program.
You may see how to use Python-profiles in the example "examples/test_Python/profiletest/testpythonprofile.py".