libximc  2.13.6
How to use with...

Library usage can be examinated from test application testapp. Non-C languages are supported because library supports stdcall calling convention and so can be used with a variety of languages.

C test project is located at 'examples/testapp' directory, C# test project - at 'examples/test_CSharp', VB.NET - 'examples/test_VBNET', Delphi 6 - 'examples/test_Delphi', sample bindings for MATLAB - 'examples/test_MATLAB', for Java - 'examples/test_Java', for Python - 'examples/test_Python'. Development kit also contains precompiled examples: testapp and testappeasy as 32 and 64-bit applications for Windows and 64-bit application for osx, test_CSharp, test_VBNET, test_Delphi - 32-bit only, test_Java is architecture-independent, test_MATLAB and test_Python are runtime-interpreted.

NOTE: SDK requires Microsoft Visual C++ Redistributable Package (provided with SDK - vcredist_x86 or vcredist_x64)

NOTE: 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).

Usage with C

Visual C++

Testapp can be built using testapp.sln. Library must be compiled with MS Visual C++ too, mingw-library isn't supported. 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

Testapp can be built using test_CodeBlocks.cbp. Library must be compiled with MS Visual C++ too, mingw-library isn't supported. Make sure that Microsoft Visual C++ Redistributable Package is installed. *

Open solution examples/test_CodeBlocks/test_CodeBlocks.cbp, build and run from the IDE.

MinGW

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

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 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).

C++ Builder

First of all you should create C++ Builder-style import library. Visual C++ library is not compatible with BCB. 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 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).

XCode

Test app should be built with XCode project testapp.xcodeproj. Library is a Mac OS X 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 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).

GCC

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

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

Copy file /usr/share/libximc/keyfile.sqlite project directory:

$ cp /usr/share/libximc/keyfile.sqlite .

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 OS X 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 OS X 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 wrappers/csharp/ximcnet.dll. It is provided with two different architectures. Supports the platform .NET from 2.0. to 4.0.

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.

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).

Delphi

Wrapper for libximc.dll is a unit wrappers/delphi/ximc.pas

Console test application for is located at test_Delphi. Tested with Delphi 6 and only 32-bit version.

Just compile, place DLL near the executable and run program.

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

Java

How to run example on Linux. Navigate to ximc-2.x.x./examples/test_Java/compiled/ and run:

$ cp /usr/share/libximc/keyfile.sqlite .
$ java -cp /usr/share/java/libjximc.jar:test_Java.jar ru.ximc.TestJava

How to run example on Windows or Mac. Navigate to ximc-2.x.x./examples/test_Java/compiled/. Copy contents of ximc-2.x.x/ximc/win64 or ximc-2.x.x/ximc/macosx accordingly to the current directory. Then run:

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

How to modify and recompile an example. Navigate 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 mac

$ 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 8SMC4-USB-Eth1 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. For correct usage of the library libximc, the example uses the file wrapper, crossplatform\wrappers\python\pyximc.py with a description of the structures of the library.

Before launch:

On OS X: copy library ximc/macosx/libximc.framework to the current directory.

On Linux: you may need to set LD_LIBRARY_PATH so Python can locate libraries with RPATH. For example, you may need:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`pwd`

On Windows before the start nothing needs to be done. All necessary communication and dependencies are registered in the example code. Libraries used: bindy.dll libximc.dll xiwrapper.dll. Located in the folder for the respective versions of Windows.

Launch Python 2 or Python 3:

python test_Python.py

In case of the 8SMC4-USB-Eth1 Ethernet adapter usage it is 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 OS X: copy ximc/macosx/libximc.framework, ximc/macosx/wrappers/ximcm.h, ximc/ximc.h * to the directory examples/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 compability 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/matlab. Then launch in MATLAB prompt:

testximc

In case of the 8SMC4-USB-Eth1 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 "testcprofile" example directory.