qli14 / alp41_api_matlab

A simple MATLAB API for connecting and controlling Digital Micromirror Device (DMD) based on the basic API from ViALUX.

API for controlling DMD

This API controls Digital Micro-mirror Devices (DMD) device controlled by ViALUX ALP controller. The library is provided by ViALUX GmbH, which is loaded into the environment. Since the library is in C++, there needs to be a working C++ compiler installed and setup with MATLAB. Compatible compilers could be found at http://www.mathworks.com/support/compilers/R2014b/index.html (careful about the version).

Necessary documentation and libraries can be found in accompanying media (CDs, Drives etc,) from ViALUX. Read about the original VIALUX API in documentation.

• This API was developed with grateful aid from Dr. Martin Vogel (Max Planck Institute of Biophysics) and VIALUX. This is a simpler subset of the ALP Tool provided by Dr. Vogel. (http://www.mathworks.com/matlabcentral/fileexchange/46673-alptool)

• Get ALP drivers at (http://www.vialux.de/transfer/alp-4.2/ALP42_install.exe OR http://www.vialux.de/transfer/alp-4.1/ALP41_install.exe)

• Careful about the versions of library you load - x64/ x86. This API is for basic - not high speed.

• Comments/ correspondence should be addressed to nakulbende [at] gmail [dot] com

• Following functions can be used. An example code with a typical routine is included as api_control.m. This code contains all the functions to be used, in the right order to load library, connect the mirrors and load images.

Contents

1. Load libraries in MATLAB (api_library)
2. Connect/ Allocate a DMD device (api_allocate)
3. Inquire device/ controller parameters (api_inquire)
4. Reset the DMD device (api_reset)
5. Clear the DMD mirrors (api_clear)
6. Load image on the mirrors (api_load)
7. Free the DMD Device after use (api_free)
8. Return: Success / error reporting (return_check)

Load libraries in MATLAB (api_library)

Loads a shared library and it's functions in MATLAB environment.

INPUTS: (both without file extensions)

dll_name = name of the dll file

dll_header = name of the header file

OUTPUTS:

return_lib = 'Library is loaded'; or 'Error: Library was not loaded'

(Opens a list of functions available in library in a separate window)

Figure. 1 Loaded library and available functions

function [return_lib] = api_library(dll_name, dll_header)

Connect/ Allocate a DMD device (api_allocate)

Connects the device with MATLAB, and generates a device handle which will be used as an address for subsequent operations

INPUTS: (both without file extensions)

dll_name = name of the dll file

OUTPUT:

hdevice = device handle generated by allocate function

function [return_allocate, hdevice] = api_allocate(dll_name)

Inquire device/ controller parameters (api_inquire)

Sends a query to the device, and stores the value in an out pointer. The query types can be (found in documentation):

Table.1 Queries to be used in alp_inquiry, alp_control

INPUTS:

dll_name = Loaded control library hdevice = device handle generated by allocate function

query = Query type: Pg 6, returns in Pg. 7, Pg. 16, Pg. 17

Common query commands (Pg. 16), non-exhaustive, please refer to documentation

• 0: Timeout
• 1: dll Version, driver version
• 2. Halt, firmware date
• 3. Configuration date
• 4. Device serial
• 5. DMD Type (return values in Pg 7)
• 6. Hardware version
• 7. Chipset version
• 8. DIP switches
• 9. DDC Signals

OUTPUT:

return_queryptr = C style pointer with the readout from device/ controlled about the specific query. Data type depends on the query, and can be found out by using the command get(return_queryptr)

function [return_inquiry, return_query] = api_inquire(dll_name, hdevice, query)

Reset the DMD device (api_reset)

Reset the DMD device to load another image. Should be performed before any clear function. The reset operation itself takes the same time to finish, independent of how many mirrors are affected.

INPUTS:

dll_name = Loaded control library hdevice = device handle generated by allocate function reset_mode = first block to be cleared Pg. 22 of API guide,

• 1 : Single
• 2 : Pair
• 3 : Quad
• 4 : Global

reset_address = address of block to be reset (0 for global), see guide for others

Table.2 Reset block assignment for different options

OUTPUT:

return_reset = Return for success/ error reporting

function [return_reset] = api_reset(dll_name, hdevice, reset_mode, reset_address)

Clear the DMD mirrors (api_clear)

The clear operation sets the memory content of whole reset blocks to logic ’0’

INPUTS:

dll_name = Loaded control library

hdevice = device handle generated by allocate function

first_block = first block to be cleared (0)

last_block = last block to be cleared (15)

OUTPUT:

return_clear = Return for success/ error reporting

function [return_clear] = api_clear(dll_name, hdevice, first_block, last_block)

Load image on the mirrors (api_load)

Send an image to the mirrors, and display it. Careful about the lags, if using this in a loop. This should always be performed in following to Reset > Clear command.

INPUTS:

dll_name = Loaded control library hdevice = device handle generated by allocate function

image = image matrix should be in 0/1. Dimensions 768X1024 (rowsXcolumns). Note that C style structures are transpose equivalent of the MATLAB counterparts.

first_row = first row to be loaded (0)

last_row = last row to be loaded (767)

OUTPUT:

return_load = Return for success/ error reporting

function [return_load] = api_load(dll_name, hdevice, image, first_row, last_row)

Free the DMD Device after use (api_free)

Frees the device, and returns the mirrors to a floating position. !!Alwyas perform this beofre shutting off the mirrors!!

INPUTS:

dll_name = Loaded control library

hdevice = device handle generated by allocate function

OUTPUT:

return_free = Return for success/ error reporting

function [return_free] = api_free(dll_name, hdevice)

Return: Success / error reporting (return_check)

Check the return from other functions - Check documentation (Pg. 9)

INPUTS:

return_value = Return for success/ error reporting

OUTPUT:

out_signal = Return for success/ error reporting

Table.3 Return codes

function [out_signal] = return_check(return_value);

Published with MATLAB® R2014a