The toolbox consists of two dll-mex
files (an executable module that runs within Matlab),
that connect to EZKit Lite (SHARC
based developing board). The plug-in is designed for Matlab 5.x and Simulink
3, and uses modules from the well known Tim Wall's communicator.
The tool is useful when you develop and debug new algorithms within Matlab before their porting to the DSP. In a later stage you can use Matlab/Simulink to visualise data, and to change parameters and coefficients. In addition, you can experiment using Simulink within a control loop, however, because the real time is not guaranteed, this mode is useful only for lab-based experiments.
How to use the toolbox
The toolbox consists of two dll files:
and ezsf.dll. The first dll is designed for
Matlab, while the second is for Simulink. In addition, four m-files are
and DSPWrite. These
interface ezmex.dll, and
their function is described in the following section.
EZKit Lite to Matlab: To send and receive data to/from Matlab, use ezmex.dll in one of its four modes; these are grouped as follows:
DSPOpen This function initialises a communication link with the kernel on the DSP board. The format is: Handle=ezmex('COM1','DSPOpen'); The dll module accepts two parameters and returns one. The first input parameter is the communication port on the host, and accepts values: 'COM1' or 'COM2'; the second parameter specifies the operation (DSPOpen). A return parameter is the serial port's handle. All other functions use this parameter. By default the module uses the maximum communication speed of 115200b/s. However, if by any reason you want to connect with speed of 9600 b/s, use the format: Handle=ezmex('COM1','DSPOpen',9600);
Instead of using the dll file directly, you may use the provided m-file DSPOpen, with format: DSPOpen('COMx'); The default speed in this case is 115200b/s, and the serial port's handle is stored within the Matlab's workspace as a global variable.DSPClose This function closes the communication link that has been previously opened with DSPOpen. The format is: ezmex(Handle,'DSPClose'); The input parameters are: the serial port's handle (returned by DSPOpen), and the parameter that specifies this operation. The m-file provided for this function is: DSPClose;DSPReadWith this function you can read 32-bit data from the SHARC's internal memory. The format is: Data=ezmex(Handle,'DSPRead',ADDRESS,LENGTH); In this mode, the dll file accepts four parameters: the serial port's handle; the parameter that specifies the operation; ADDRESS is a valid address from the SHARC's internal memory space, and LENGTH is the number of words we want to transfer. For example, if you are performing 512 point FFT, and your MyFFTResult buffer is located at address 0x25000, you can observe the result by calling: MyFFTResult=ezmex(Handle,'DSPRead',hex2dec('25000'),512);
You can also use the provided m-file, which has a format: MyFFTResult=DSPRead('25000',512); The first parameter specifies the address, and the second specifies the number of words to be transferred.DSPWrite With this function you can write 32-bit data to the SHARC's internal memory. The format is: ezmex(Handle,'DSPWrite',ADDRESS,DATA); The serial port's handle is the first input to the function; ADDRESS specifies the internal address where the DATA will be transferred. The number of words to be transferred is equal to the length(DATA); DATA must be a row-vector and a single precision. For example, if you want to update the coefficients, organised as a vector, of your FIR filter starting at address 0x25010, the format is: ezmex(Handle,'DSPWrite',hex2dec('25010'),single(MyFIRCoef)); The vector MyFIRCoef is in the form: MyFIRCoef=[a1, a2, a3, ..., an];
An m-file is provided that performs the same operations. It format is: DSPWrite('25010',MyFIRCoef); where the first parameter is the address, and the second is the data to be transferred.
A quick start: This set of operations demonstrates the basic use of the toolbox. It opens the communication, writes 10 variables, and reads 10 variables from the same location. The operations are:
1. Open the communication: DSPOpen('COMx').
2. Write the data: vTx=0.123*[1:10]; DSPWrite('25000',vTx);
3. Read the data: vRx=DSPRead('25000',10);
4. Do your own reading and writing.
5. Close the communication: DSPClose;
EZKit Lite to Simulink: If you want to send and receive data from/to EZKit Lite using Simulink use ezsf.dll. This S-function accepts four parameters, as shown in the figure bellow. The first parameter determines the direction of the operation; value 1 determines operation reading from the kit, while value 0 specifies writing to the kit. The second parameter determines the communication port on the host: value 0 for COM1, and value 1 for COM2. The third parameter determines the address from(to) where data will be transferred. The last parameter is necessary only for reading, and determines the number of variables to be transferred from EZKit to Simulink (up to 500 points/block are supported in this version). The number of data transferred to EZKit Lite is determined from the width of the input bus to the S-block.
A quick start: There are three Simulink files provided together with the toolbox that demonstrate the basic features and give an idea how to use the toolbox. One of these demonstrations is shown in the figure bellow. Here Simulink writes to three memory locations and reads from the same three memory locations.
Notes and tips
1. The function
converts a variable
x from a double to a single precision (see double(x)
2. To find where your variables are located within the DSP's internal memory, generate a map-file during the linking by adding the option -m or -map (check your documentation for more information).
3. If you want to observe a given location in a hexadecimal format, type format hex in Matlab, read and visualise the data.
4. If the DSP is reset before closing the communication with DSPClose, restart the DSP and clear the dll by executing clear ezmex in Matlab.
5. Before using Simulink for communication, you have to close (if opened) the communication initialised from Matlab.
6. Before using the dlls, you MUST close all programs that use the serial port !!! If the KIT is booted from a DOS-mode software, you have to close the DOS-window after booting. If you are using the dll for MATLAB, and you want to start a communication with Simulink, you have to first close the MATLAB link with DSPClose. After a resynchronisation in the communication, restart the board, close all software that use the serial port, clear the ezmex.dll from MATLAB by: clear ezmex, and then start another session.
Downloads and installation:
Download and unzip the file: EZMEX.ZIP in any directory, for example in ...\Matlab\toolbox\EZMex\. The archive consists of: two dll files, four m-files, three Simulink demo-files, and this help file. When you start Matlab, change your default path to the location where these files are installed or add this location to the Matlab's Path list. For a test, perform the "quick start" steps given above.
Please note that this software is designed and meant to be used only for research and educational purposes.
Please send any comments or questions