Linux HOWTO

Getting the MOTOM toolbox to work on Linux requires additional steps and is considerably more difficult than on Windows. Usually, Matlab's supported gcc version is considerably older than what is bundled with current Linux distribution.

For instance, Matlab R2017a supports gcc 4.9, which is available directly from the repositories of Debian Jessie.
As of Matlab R2018a, gcc 6.3 is supported. It is also possible to successfully compile with gcc 6.4 as well!

Windows is strongly recommended to run the MOTOM toolbox. If Linux is required, install Debian Jessie, or Ubuntu 18.04 or later.

Be prepared for unforeseen difficulties when trying to get the code to work, because most likely your system-wide C-libraries are different from what Matlab uses!

Steps to set up for a Debian-based system

-1. Follow NDI's instructions on using the Optotrak API on Linux.

Ethernet should be the most straightforward, only the IP address of the SCU needs to be added. The default path for the API is /usr/NDIoapi/ndigital/*, and make sure that you add it along with the include directory to your $PATH environment variable, and declare the ND_DIR environment variable too:

export ND_DIR=/usr/NDIoapi/ndigital
export PATH=$ND_DIR/programs:$PATH

Add these lines to your .bashrc to make it permanent for the user using the toolbox.
If the USB interface is used, the kernel will most probably not load the ftdi module. It is required to have a specific udev rule to make sure the correct driver loads when the USB device is plugged in:

• Copy the included ndi-udev.rules to /etc/udev/rules.d
• Reload rules as root by: # udevadm control --reload-rules
• Edit /usr/NDIoapi/ndigital/settings/optotrak.ini, and change etherlink.so to usblink.so or usblink.i386.so, depending on your architecture. All the .so files have to be in /usr/NDIoapi/ndigital.

Make sure liboapi is globally available in the system:
Perhaps the easiest to create a symlink, assuming the files have been copied to the default path:

sudo ln -s /usr/NDIoapi/ndlib/lib/liboapi.so /usr/lib/liboapi.so

• Check if the connection and the shared library access works by executing

$ ./usr/NDIoapi/ndigital/programs/optstetup -v

0. Make sure Matlab detects the C compiler

If you haven't already done so and are using Debian Linux, install and old version of gcc by typing as root:

# apt-get install gcc-4.9

...or, if you are using Ubuntu, and Matlab R2018a or later:

$ sudo apt-get install gcc-6

You might need additional packages, such as build-essential too.
In Matlab, type >> mex -setup C++. You should now see the C compiler, without any warnings.

1. Copy the API files to their respective locations

Just like how it's done as if you used Windows, copy all the other files to the relevant directories, i.e.:

.../oapi/dll/x86/oapi.dll   -> <toolboxpath>/bin/oapi.dll
.../oapi/dll/x86/oapi.lib   -> <toolboxpath>/bin/oapi.lib
.../oapi/dll/x64/oapi64.dll -> <toolboxpath>/bin/oapi64.dll
.../oapi/dll/x64/oapi64.lib -> <toolboxpath>/bin/oapi64.lib

.../ndlib/include/ndopto.h  -> <toolboxpath>/source/ndopto.h
.../ndlib/include/ndtypes.h -> <toolboxpath>/source/ndtypes.h
.../ndlib/include/ndhost.h  -> <toolboxpath>/source/ndhost.h
.../ndlib/include/ndpack.h  -> <toolboxpath>/source/ndpack.h

...while the .dll and .lib files are not needed in Linux, the script checks if they are in the correct place. Sorry! :)

2. Edit the header files

We need to tell the compiler to use the local files here in the toolbox. The simplest way to do this is with Matlab's editor is with the 'Find and Replace' function, in all the header files:

• Replace all instances of #include <ndtypes.h> with #include "ndtypes.h"
• Replace all instances of #include <ndpack.h> with #include "ndpack.h"
• Replace all instances of #include <ndhost.h> with #include "ndhost.h"
  Also, additionally, copy and paste the following lines to the top of ndopto.h:

#include "ndtypes.h"
#include "ndpack.h"
#include "ndhost.h"

Furthermore, add the lines to the beginning of ndhost.h, so that the compiler will not fail:

/* Added define for Linux. */
#define PLATFORM_LINUX

3. Run RUNME.m

The shared library files should build without problems. I tested this on Ubuntu MATE 18.04 LTS, with everything pretty much stock settings. However, different Linux environments might have slightly different settings, so be ready for all sorts of surprises. From my experience, I would say this is considerably easier to get to work than a software distributed as a tarball and having to do the configure - make - make install steps.

Currently, the Linux compiler settings are stored in compilers.m, and the compiler_flags string prepared for gcc-6, with liboapi available as a shared library throughout the system. Please adapt compiler_flags to your system/taste!

Assuming everything went well and everything was compiled, using the toolbox should now be platform-independent. The Matlab code that was written in the Windows version of Matlab should now work perfectly on Linux, and vice versa.

One thing to look out for is that sometimes the OAPI functions are creating files with a 600 attribute mask, and then they crash when trying to write into it. If such a thing happens, Matlab will crash too. Try running Matlab from a terminal, and you should see an error message about not being able to write or some file not being found, and use the 666 attribute mask on generated files such as standard.cam and system.nif is required.

Good luck!