Using the Euvis API Through Matlab

Euvis module products, such as AWG’s, DSM’s, and DAQ’s, can be controlled through companion API. Users can develop their own applications with several CLR-based languages, such as C++, Java, Visual Basic, etc, to control the modules via the API. These examples can be found on the individual download pages of each product listed here. Alternatively, the modules can also be controlled through widely used computation platform Matlab.

Requirements

The Euvis API is developed with .NET Framework 4.0 and with Common-Language-Runtime (CLR) support. Not all Matlab versions can successfully access Euvis API. To use Euvis API in Matlab, first check to see if the Matlab version being used is compatible with .NET Framework 4.0 such as versions R2011a or later.

Procedure

The Euvis API is in the companion DLL file, Euvis_Module_V2p0.dll. The API can be found in the program folder for the module, C:\Euvis\AWG, C:\Euvis\DSM, or C:\Euvis\DAQ. If the Matlab version is compatible, the Euvis API can be loaded into Matlab using the NET.addAssembly() function with the file path for the Euvis_Module_V2p0.dll file within the parentheses. For the example shown below, the file path to Euvis_Module_V2p0.dll is C:\Module\BIN\Euvis_Module_V2p0.dll. For your own project, make sure that it is being pointed to the correct folder.

		NET.addAssembly('C:\Module\BIN\Euvis_Module_V2p0.dll');
		import MOL.*;

The command import imports the desired class or namespace to work with from the API. In the example above the desired namespace is MOL. To see all the classes in the Euvis API, type the following two commands in the Command Window in Matlab.

		variable=NET.addAssembly('filepath')
		variable.Classes

After typing in the above you should see the output as shown below:

To create the objects and access to functions from the classes, users can assign the desired class to a variable as shown below.

		awg_group = MOL.AWG.AWG_Group_API;
		awg = MOL.AWG.AWG_API;

awg_group and awg are Matlab variables and MOL.AWG.AWG_Group_API and MOL.AWG.AWG_API are two classes of the Euvis API. The two lines assign the classes necessary to get the serial number from the module and control the module. The detailed Matlab script for using Euvis API can be found in the Application Note PDF file and the example codes downloadable below.

Memory Issue

To limit the memory consumed, delete and clear all the variables and classes when they are used by the function and then clear the imported namespace and the function. This is done by the following lines of code.

		delete(awg_group)
		clear awg_group
		delete(awg)
		clear awg
		clear MOL
		clear FunctionName

The variables need to be deleted before they are cleared or else the information they held will still be in memory.

The script will run successfully several times before an error may occur. It will not run repeatedly forever due to memory leakage. In each iteration of running the Matlab script, available memory is reduced. When first starting Matlab, the available memory can be monitored using the function memory.

After running the script once, the available memory decreases and the memory used by Matlab increases.

When there is not enough available memory, the script will not be executed successfully and the following error message will be displayed.

There is no longer enough available memory for the script to run. To regain the available memory, please close and restart Matlab. A similar issue can be found in the thread “Clearing a cell array does not release memory held by cell contents” on the Matlab Central website.

Example Memory Leakage

This issue is not due to memory leakage on the Euvis API side. For instance, given a simple .dll library and Matlab script shown following, memory leakage is an issue.

C++ code to test memory leakage

		// Matlabtest.h
		#pragma once
		using namespace System;
		
		namespace Matlabtest 
		{
			public ref class Test
			{
				unsigned char *u1;
				public:
				Test()
				{
					u1 = new unsigned char[ 32 * 0x100000 ]; 
				}
				~Test()
				{
					delete u1; 
				}
			};
		}

Matlab script

		NET.addAssembly('filepath\Matlabtest.dll');
		import Matlabtest.*
		t=Matlabtest.Test;
		delete(t);
		clear t
		clear Matlabtest
		clear tester

The example C++ code creates a namespace, a class, and a 32 MB object, which is deleted by the end so that the memory is released and the code does not create memory leakage.

The Matlab script adds the .dll file and imports the namespace, Matlabtest. It assigns the class Test to t and immediately deletes the information in t. Then the script clears the variable t, the imported namespace Matlabtest and the script tester.

After running the script once, there is jump in memory used by Matlab with no clear source. However, after the second run, the memory used by Matlab increases by 32 MB and the memory available for all arrays decreases by 32 MB. These two jumps in memory are both about the same size as the object u1 in the Test class.

After running the code several times, the same error message from before is displayed in the Command Window. The error occurs when Matlab is assigning the class to the variable t and from looking at the memory after the last run, the maximum possible array size is 30 MB. This is too small for the object u1 to be loaded to t, so the exception is thrown preventing Matlab from successfully running through the entire script.

Downloads

A PDF version of the instructions can be downloaded below. Example codes mentioned in the instructions can also be downloaded as a ZIP file as well.

Name	Download	Size
Using Euvis API Through Matlab Application Note	PDF	1.48 MB
Matlab Example Codes	ZIP	734 KB