How to stream data to Matlab

How to stream data from a Gantner controller over Ethernet to Matlab software

There are 2 different ways to read buffered data from a Gantner Controller (for e.g. Q.station) or a PostProcess Buffer (GI.bench) into Matlab:

Call Gantner-DLL functions (C-API) directly in Matlab → see Use shared libraries
Use a pre-compiled MEX file (mexw64 for 64-Bit, mexw32 for 32-Bit versions) → see MEX file
This works for both Matlab on Windows and Linux.

mex -setup

To read Gantner-Data directly into Matlab, it is possible to call Gantner-DLLs directly in Matlab code. For example using:
eGateUtility.dll (only 32-bit!!)
giutility.dll (GInsData → C-API: eGateHighSpeedPort API): available in 32/64-bit

Load C/C++ Shared Library

The syntax to load a library is for example

loadlibrary('giutility','eGateHighSpeedPort.h','alias','HighSpeedPortDLL');

See for detailed info for loadlibrary: https://www.mathworks.com/help/matlab/ref/loadlibrary.html

Call Function in Shared Library

A DLL Function can be called from a loaded library for example

calllib('HighSpeedPortDLL','CD_eGateHighSpeedPort_Init',host,timeout,conType,10,hclient,hconnection);

See for detailled info for calllib: https://www.mathworks.com/help/matlab/ref/calllib.html

Pointer

Pointer objects are needed for use with shared libraries.

Examples:

• Int32: Ptr = libpointer('int32Ptr',-1);
• Double: Ptr = libpointer('doublePtr',0);
• cstring: Ptr = libpointer('cstring','000000000000000000000000000000000000000000000000000000');
• cstring null pointer: Ptr = libpointer('cstring');

Get Values from pointers using:

• Ptr.Value

See for detailed info of pointer objects: https://www.mathworks.com/help/matlab/ref/libpointer.html

MEX File

Using a MEX file, it is possible to provide the GInsData functionality (via C-API) directly in Matlab. With simple C-code the interface between Matlab and the DLL functions (written in C/C++) can be realized, and then be called as function in Matlab

• Introduction to MEX-files: Introduction to mex files.

Gantner Instruments provides MEX files for 64/32 bit to load DLL functionality. The files are called:

• “GInsMex.mexw64” for 64-bit Matlab (generated in Matlab R2013a 64bit)
• “GInsMex.mexw32” for 32-bit Matlab

Also be sure to have a “giutility.dll” in 32/64 bit in your working directory beside the GInsMex.mexw32/64 file. (or in Windows System32/SysWOW64 directory)

Workmodes

The MEX-file function is called “GInsMex” and can be executed with different “Workmodes”. It wraps the most important functions of the DLL interface (giutility.dll) to make them easily accessible in Matlab. The workmodes covers for example reading buffer data from a device or from post process buffers (GI.bench) and also file import (UDBF file format).

Usage:

 [ret(, Additional Ret Values) ] = GInsMex(workmode[, Additional Parameters]) 

To get the functions online-help, just type GInsMex into your Matlab Command Window. Most of the functions only make sense in a combination of multiple function calls with different workmodes. An example is provided to demonstrate the usage (HSP_ReadBuffer.m).

The workmodes are:

1 - connect to hardware with specified ip address
2 - set the buffer index to specify which buffer should be used (0-3)
3 - get number of channels of the selected buffer
4 - get channel name
5 - read data (handle this function with care! on high buffer data rates, your Matlab application needs to be able
         to process the received amount of data fast enough. Otherwise a buffer-overrun will occur and connection will be closed! 
         In this case, think about reducing the buffer sample rate or only "post"-proccess the high speed data in Matlab 
         using .DAT files (avoid "online" highspeed data processing in Matlab).
6 - close connection
7 - get samplerate
8 - sleep (ms)
10 - Identify first - Use this Fuction (+ workmode 11) to scan the network for devices...
11 - Identify next - Use this in addition to workmode 10 to scan the network for devices... 
12 - Get Number of available PostProcess buffers. Use this function in combination with workmode 13 
13 - Read PostProcess Buffer information by index 
14 - Initialize connection to a PostProcess Buffer (GI.bench) 
15 - Set Backtime - use this function only in combination with workmode 14. 
101 - Open .DAT file
102 - Read channel data from selected file 

Examples

HSP_ReadBuffer.m

 >> HSP_ReadBuffer 

%% load file data -> workmode = 101
GInsMex(101, 'backup___0_2018-10-02_05-11-00_000000.dat')
 
%% read channel data of channelindex 5 to "data" -> workmode = 102
[ret, data] = GInsMex(102,5);
 
%% close file -> workmode = 6
GInsMex(6)
 
%% plot channel data
plot(data.XData, data.YData)

%% load file data -> workmode = 101
GInsMex(101, 'backup___0_2018-10-02_05-11-00_000000.dat')
 
%% read number of channels -> workmode = 3
[ret, numChannels] = GInsMex(3);
 
%% create struct for all channels
channelstruct = struct();
 
for i=1:numChannels
   %read channel name -> workmode = 4
   [ret, strChannel] = GInsMex(4, i-1);
 
   %read channel data -> workmode = 102
   [ret, data] = GInsMex(102,i-1);
 
   %write to struct -> remove invalid characters from string!
   channelstruct.(regexprep(strChannel, {'#' '/' ' '}, '_')) = data;
end
 
%% close file -> workmode = 6
GInsMex(6)
 
%% plot channel data of a single channel
plot(channelstruct.sine3.XData,channelstruct.sine3.YData)