NiMex Overview

Here we provide an overview of NiMex, with an emphasis on the C portion of the @nimex and @nimexEngine classes for Matlab. This documentation is intended for those familiar with C, specifically C in a Matlab environment (MEX functions), and with the NIDAQmx API. To view documentation of the Matlab portion of the code use Matlab's `help` command. For further information on the C code see documentation in the relevant *.c, and *.h files.

A note on naming conventions:
NiMex refers to whole package, including C-functions and the Matlab classes.
NIMEX refers to the C-code only.
@nimex and @nimexEngine are Matlab classes.
All other forms are assumed to refer to Matlab code.

What is NiMex?

NiMex is a Matlab toolkit for data acquisition, using the NIDAQmx drivers from National Instruments. The functionality of the drivers is exposed through and wrapped by C code. It is made accessible to Matlab via MEX functions. The MEX functions are further wrapped by Matlab classes @nimex and @nimexEngine. NiMex provides relatively direct and straight-forward access to the National Instruments NIDAQmx ANSI C driver API. This is done via a set of Matlab MEX functions that act as wrappers for the API. Whenever possible, consistent naming conventions were used ('nimex' in the .m files; 'NIMEX' in the .c files).

NiMex supports all National Instruments hardware that is compatible with the NIDAQmx drivers. Most, but not all, features of the NIDAQmx drivers are accessible (access to features has been added on an as-needed basis); other functionality can be added rapidly. 

Why did we create NiMex?

Performance
The Matlab daqtoolbox must work with drivers from multiple vendors, which is associated with considerable overhead (such as emulating hardware behavior in software, to ensure it works the same across devices). NiMex is not subject to these constraints. NiMex therefore shows much improved efficiency and stability. 

Reliability
Event-driven programming also gets around some of the limitations imposed by Matlab's single-threadedness. However, the passing of events from NIDAQmx into Matlab is non-deterministic in the Matlab daqtoolbox. In contrast, NiMex event callbacks are guaranteed to execute in the order that they are generated. This is a crucial feature when writing event-driven software, which is a standard model of efficient programming for GUIs, hardware sensors, and multiple threads. 

Support 
The Matlab daqtoolbox was slow in adapting the new NIDAQmx standard. Furthermore, support for the full functionality is not planned. As an extensible, open-source package NiMex provides access to the full cpabilities of the data acqusition hardware.

Functionality
NiMex supports all of the functions provided by the Matlab daqtoolbox and significantly more. For example, NiMex supports the use of counter/timers and buffered/clocked digital IO (as opposed to static lines that can only be updated once per functional call). These features allow a single board to do significantly more work than an equivalent board under the control of the Matlab daqtoolbox. 

Some extra concepts and features were added on top of the standard NIDAQmx model to help design event-driven (asynchronous) applications. These include new event-driven callbacks, enhanced state information, the ability to re-use a task, a flexible 'data source' model (allowing both arrays of data and runtime callbacks which generate data on the fly). Additional features, including Matlab-configurable C-level data preprocessors, generators, and listeners, could be easily implemented. Because NiMex is open source, it may be easily expanded or modified to suit a specific goal.

 How is NIMEX built?

The NIMEX library was originally developed with the lcc compiler in mind, because this is the compiler included with win32 Matlab distributions. That was part of the motivation for writing the library in C as opposed to C++. However, we experienced unexpected problems during the linking stage when using lcc (or gcc). This is due to some third party libraries, provided in binary form, not being compatible with non-Microsoft compilers. A small toolchain may be used to convert some libraries into a form that may be accessed by lcc, but there are cases in which this is challenging. Due to these considerations, compilation on Windows machines is now done using MS Visual Studio 2008 Express Edition, which is freeware. The IDE is not used, nor is it recommended. Instead, builds are done using batch files and/or Apache Ant build scripts. Only the compiler/linker portion of Visual C/C++ is used when building NIMEX. 

What libraries are required by NIMEX?

The National Instruments NIDAQmx ANSI C library and the Matlab C development (MEX) library are required to build NIMEX. These are included with the National Instruments NIDAQmx driver installation and Matlab installation, respectively.

Low-level data structures are currently handled by GLib (not to be confused with glibc, the core of the Linux kernel), which is part of the larger GTK+ and GNOME libraries. The utility library, GLib, is thinly wrapped, mostly using compile time replacements through macros. This allows it to be relatively easily swapped with another library (requiring changes in only two files). The datastructures which are used from GLib include hash tables and linked lists. In the future, multithreading may be made to depend on this library as well.

The Microsoft Windows Server 2003 Platform SDK is required for use with Windows. This is not included as part of Microsoft Visual C/C++ (the full version nor the Express Edition). It is a rather large and tedious download, but is a one-time affair when setting up a build environment. The reason for the requirement of the Platform SDK is for the Windows message passing functionality. This is needed to implement cross-thread callbacks to Matlab (as discussed further below).

What paradigms are used in the NIMEX design?

The class follows the NIDAQmx task model. Any given data acquisition subsystem action is represented by a task. The task is created, its parameters are set (this configures the task for the desired measurement), the task is started (data is collected or sent), the task is stopped. The nimex task is re-usable, each subsequent use applies the current parameters, i.e. a task may be configured once and used many times. 

Each task consists of a set of task-specific properties (task properties), channel-specific properties (channel properties), and registered callbacks. In addition, a task contains internal variables in the C code (not exposed to Matlab).

In terms of design patterns, the publisher/subscriber pattern and visitor pattern are used extensively. Understanding these will help with following the general model of control flow throughout the code.

The registered callbacks require further comment: The NIDAQmx library provides access to events which may cause code to be executed upon their occurence. Specifically, it provides an EveryN event (which is initiated after every N samples are aqcuired/sent) and a done event (which is initiated when the task has completed). The @nimex class allows multiple Matlab functions to be tied to each of these events. To tie a Matlab function to an event, a function_handle must be passed to the appropriate 'bind' function. If arguments are required for the Matlab code, a cell array may be provided instead. The cell array's first element must be a function_handle (the function to be executed), all subsequent elements will be passed into the called function as arguments. The @nimex class does not pass any of its own arguments when calling events, it is the responsibility of the registering code to specify all arguments. An example of how to use this functionality may be found in the "continuous analog input demo" section of nimexDemo.m.

What do you need to know to use NiMex?

Familiarity with the daqtoolbox and/or NIDAQmx libraries is helpful, but not necessary. Where possible, parameters in the @nimex class are mapped directly to their NIDAQmx equivalents. An understanding of object-oriented programming in general, and Matlab's implementation of object oriented programming in particular, is required for a full understanding and effective use of the code. A discussion of these topics can be found in the Matlab documentation itself ('Using object-oriented programming in MATLAB').

Specific examples are given in nimexDemo.m.

What do you need to know to program NiMex?

Understanding of C programming, specifically managing multifile builds, pointers, Windows messaging, multithreading, hardware interrupts, the Matlab GUI queue, memory management. Consultation with the NIDAQmx ANSI C documentation should provide any necessary detail on the precise meaning of the parameters.