Below is a description of the installation steps to follow at the MS-DOS prompt. C:\MATLAB\DAP is used as the example working directory.

Transcription

1 M ICROSTAR LABORATORIES TM th Avenue N.E., Bellevue, WA Sales & Customer Support: (425) Finance & Administration: (425) Fax: (425) World Wide Web: Technical Note TN-176 Version DAPtools for MATLAB DAPtools for MATLAB allows a user to communicate with a Data Acquisition Processor using the MATLAB programming environment. It integrates the processing power of a Data Acquisition Processor with the powerful technical computing environment of MATLAB. MATLAB performs high-level numeric computation and visualization of data sets. DAPtools for MATLAB allows acquired and processed data from a Data Acquisition Processor to be further manipulated and molded under MATLAB. This exts the capabilities of data manipulation to suit the specific requirements of an application. New Features for Version 2.00 DAPtools for MATLAB now works with MATLAB 5.x. Functions and examples have been updated to 32-bit code utilizing the DAPIO32 DLL interface. DAP MEX function names remain unchanged. There are, however, some functionality changes relating to the new more powerful features of DAPIO32 for Windows. See the function reference and examples for details. Installation Please copy all of the files provided on the disk to a directory of your choice, for example C:\MATLAB\DAP. You should then make C:\MATLAB\DAP the working directory of MATLAB. If you choose not to make C:\MATLAB\DAP the working directory of MATLAB, you will have to app or add your working directory to the MATLAB search path using the MATLAB path command. MATLAB s search path is established in the MATLABRC.M file, which resides in your <MATLAB> directory. You can change MATLABRC.M to include the path C:\MATLAB\DAP or create a STARTUP.M file (if not yet created) that MATLABRC.M invokes automatically. STARTUP.M should reside in your <MATLAB> directory. Even if you choose not to make C:\MATLAB\DAP the working directory of MATLAB, all of the *.DAP files still have to be in the current MATLAB working directory. Below is a description of the installation steps to follow at the MS-DOS prompt. C:\MATLAB\DAP is used as the example working directory. 1. Copy all *.DLL, *.M, and *.DAP files to C:\MATLAB\DAP PROMPT:\> COPY A:\*.* C:\MATLAB\DAP 2. Create STARTUP.M in your <MATLAB> directory if C:\MATLAB\DAP is not the working directory. PROMPT:\> EDIT <MATLAB>\STARTUP.M Add the following lines to it. path( c:\matlab\dap, path); Note: All *.DAP files have to be in the current MATLAB working directory. Contents copyright , Microstar Laboratories, Inc. All rights reserved. No part of this publication may be photocopied, reproduced, or translated to another language without prior written consent of Microstar Laboratories, Inc. Microstar Laboratories assumes no responsibility for damages due to errors or omissions. Microstar Laboratories, Accel32, Data Acquisition Processor, DAP, and DAPL are trademarks of Microstar Laboratories, Inc. Other brand names and product names are trademarks of their respective holders.

2 DLL MEX Functions The DAPIO32 DLL contains functions that make it easy to create a Data Acquisition Processor application under Microsoft Windows. MATLAB cannot directly call the DAPIO32 DLL, however MATLAB can call and execute DLL MEX functions. The DLL MEX functions provided with DAPtools for MATLAB use the DAPIO32 DLL. For this reason, the DAPIO32 DLL must already be installed in a directory that Windows can find. Not all routines provided in the DAPIO32 DLL were made into DLL MEX functions. The name of each DLL MEX function differs from the routine name in DAPIO32 DLL. Also, the usage of some of the functions may vary slightly. The table below shows the comparison between DLL MEX functions and DAPIO32 DLL routines. Please refer to the DLL MEX function reference provided at the of this technical note for a description of each function. You can obtain help on any function by typing help dapopen, help dapclose, help dapcnfig, etc. at the MATLAB command prompt. DLL MEX Functions for MATLAB handle = dapopen( unc_path, function code ) <code> = dapclose(handle) <code> = dapcnfig(handle, daplfile ) <code> = dapflush(handle, <timout>, <timewait>) numbytes = dapgavl(handle) numbytes = dappavl(handle) [datamatrix, <numbytes>] = dapgbuf(handle, length, <timwait>, <timeout>) [string, <code>] = dapgstr(handle) <numbytes> = dappbuf(handle, <length>, datamatrix, <timewait, timeout>) <numbytes> = dappstr(handle, string ) <code> = dapsetpa(paramnumber, parameter ) <code> = dapclrpa <code> = daprecnf( outputfilename ) DAPIO32 DLL Routines DapHandleOpen DapHandleClose DapConfig DapInputFlushEx DapInputAvail DapOutputSpace DapBufferGetEx DapStringGet DapBufferPutEx DapLinePut DapConfigParamSet DapConfigParamsClear DapConfigRedirect The above table and other references to the DLL MEX functions use handle, code, numbytes, datamatrix, and string as the names of the returned arguments. You may choose any name you prefer. Some of the DLL MEX functions have optional return arguments. If you do not specify names for these, you will not be able to access the returned arguments. Also, it is important to use all of the string input arguments with single quotes. Most of the returned arguments are message or error codes, specifying if the functions have executed successfully or not. The DLL MEX function reference section and the DAPIO32 reference explain these codes. 2 DAPtools for MATLAB

3 Example Set 1 Several examples were created to demonstrate the use of a Data Acquisition Processor with MATLAB. Example Set 1 reads 100 data values each from input channels 0 and 1 of the DAP into two matrices in MATLAB. The example shows how to initialize communication, get data, and terminate communication with a Data Acquisition Processor. All of the DLL MEX functions used are saved in several M files. 1. Running the example To run the example, type the following at the MATLAB command prompt: >> init >> data >> stop 2. File INIT.M This file initializes communication with the Data Acquisition Processor. %% File INIT.M %% % Open text and binary handles to ACCEL device texthandle = dapopen('\\.\dap0\$sysin', 'write') if texthandle == -1 error('error opening DAP text handle') binaryhandle = dapopen('\\.\dap0\$binout', 'read') if binaryhandle == -1 error('error opening DAP binary handle') dappstr(texthandle, 'RESET'); % S a command to reset the DAP dapflush(binaryhandle); % Flush old DAP data in binary pipe 3. File DATA.M This file configures the Data Acquisition Processor with the DAPL file and reads data from the Data Acquisition Processor. %% File DATA.M %% % Configure DAP using DAPL command file DATA.DAP cnfg = dapcnfig(texthandle, 'data.dap'); if cnfg >=200 error('error configuring DAP') % Print error message % Get DAP data while dapgavl(binaryhandle)<400 % Wait for data to be available channel0 = dapgbuf(binaryhandle,200) % Read 200 bytes of data from DAP channel1 = dapgbuf(binaryhandle,200) 4. File STOP.M This file terminates communication and closes all handles to the Data Acquisition Processor. DAPtools for MATLAB 3

4 %% File STOP.M %% % Stop DAP communication dappstr(texthandle,'stop'); % S a command to stop the DAP % Close text and binary handles to ACCEL device textclose = dapclose(texthandle) if textclose==-1 error('error closing DAP text handle') binclose = dapclose (binaryhandle) if binclose==-1 error('error closing DAP binary handle') 5. DAPL Command File, DATA.DAP This file has the DAPL listing. ;; DAPL file, DATA.DAP ;; reset idef a 2 set ip0 s0 set ip1 s1 time 5000 count 1000 pdef b ; Sample analog input, s0 ; Sample analog input, s1 ; Time of 5 msec ; Take 1000 samples bmerge(ip0,ip1,100,$binout); S data through binary ; communication pipe start a, b 4 DAPtools for MATLAB

5 Example set 2 Several other examples are described below. These examples try to exercise most of the commands provided in DAPtools for MATLAB. The examples can be run by typing logfile, string, biway, etc. at the MATLAB command prompt. 1. LOGFILE.M Logs one channel of data from the DAP to the PC s hard disk. 2. DSTRING.M Writes and reads strings and error messages from the DAP. 3. BIWAY.M Writes matrix data to the DAP and reads processed data from the DAP. 4. WAVES.M Uses the DAP as a function generator to generate a sine wave and triangular wave of different frequencies. 5. FOURIER.M Gets FFT data from the DAP and performs 3-D plots of the data using MATLAB s graphics. All the above examples open the DAP file handles, get DAP data, and close the DAP file handles. If you want to force a running example to stop, you can use CTRL-C to exit the example. When you do this, not all of the M file is executed and it is probable that the opened DAP file handles were not closed. If this is the case, you must run STOP.M to close both the text and binary file handles. Importing logged data from a DAP into MATLAB You can use MATLAB with logged binary data. You can log a binary data file in DAPview or DAPview for Windows. The following MATLAB commands show how to do this. DATABIN.LOG has logged binary data. Logged binary data At the MATLAB command prompt, type the following: >> fid = fopen('databin.log', 'rb'); >> bindata = (fread (fid, [n,inf], 'short'))' >> fclose(fid); n is the number of channels or the number of pipes merged to $BINOUT. inf reads to the of the file. DAPtools for MATLAB 5

6 DLL MEX Reference Below is a complete description of all the DLL MEX functions that are provided with DAPtools for MATLAB. Input arguments that are strings use single quotes. The string input arguments must have single quotes to work properly. All the names for the returned arguments like handle, code, numbytes, datamatrix, and string are chosen by the user. Some of the returned arguments are optional. If a name is not given for these, the optional returned arguments are inaccessible. Some functions have optional TimeWait and TimeOut parameters. If values for these parameters are not given the default is TimeWait of 100 ms and TimeOut of 20 seconds. Please see the corresponding function in the DAPIO32 reference for the meaning of the time out parameters. handle = dapopen( unc_path, function code ) Opens a handle to the communication pipe defined by the UNC (Universal Naming Convention) path. Examples include: textinhandle = dapopen('\\.\dap0\$sysin','write') ; write text textouthandle = dapopen( \\.\dap0\$sysout, read ) ; read text bininhandle = dapopen('\\.\dap0\$binin','write') ; write binary datap binouthandle = dapopen('\\.\dap0\$binout','read') ; read binary data And the function code is one of: 'write' opens the pipe for writing 'read' opens the pipe for reading The return value in handle is a valid handle to the communication pipe. If the value is 0, an error occurred. <code> = dapclose(handle) Closes the handle to the ACCEL device specified by handle. The return value in code is 1 if the handle was closed or 0 if an error occurred. Code is an optional return argument. <code> = dapcnfig(handle, daplfile ) Reads the DAPL command file specified by daplfile from disk and ss the contents to the Data Acquisition Processor. The handle parameter to the ACCEL device has to be a text handle opened for write. The return value in code is 1 for success or 0 if an error occurred. Code is an optional return argument. <code> = dapflush(handle, <timout>, <timewait>) Flushes old data from the ACCEL device specified by handle. The return value is the number of bytes flushed or -1 if an error occurred. Code is an optional return argument. numbytes = dapgavl(handle) Returns the number of bytes of data available for reading from the input buffer of the ACCEL device. The handle parameter contains a handle to the ACCEL device. If the return value is -1 an error occurred. numbytes = dappavl(handle) Returns the number of bytes of space available for writing to the output buffer of the ACCEL device. The handle parameter contains a handle to the ACCEL device. If the return value is -1 an error occurred. [datamatrix, <numbytes>] = dapgbuf(handle, length, <timwait>, <timeout>) Reads length values of data from the Data Acquisition Processor into datamatrix. The handle parameter contains a handle to the ACCEL device. Each item in datamatrix corresponds to two bytes. The return value in numbytes is the number of bytes read or -1 if an error occurred. Numbytes is an optional return argument. 6 DAPtools for MATLAB

7 [string, <code>] = dapgstr(handle) Reads text data from the Data Acquisition Processor into string. This function continuously reads text data until it finds a carriage-return - linefeed combination. If dapgstr does not find both carriage return and linefeed characters, it will wait for up to 20 seconds and then return what it was able to read or an error. The handle parameter to the ACCEL device has to be a text handle. The return value in code is either positive or 0 if an error occurred. Each character read corresponds to one byte. Numbytes is an optional return argument. <numbytes> = dappbuf(handle, <length>, datamatrix, <timewait, timeout>) Ss the values in datamatrix to the Data Acquisition Processor. If optional parameter length is specified, dappbuf ss only length values. The handle parameter contains a handle to the ACCEL device. Each item in datamatrix is converted to a 16-bit integer before being sent to the DAP. The return value in numbytes is the number of bytes written or -1 if an error occurred. Numbytes is an optional return argument. Dappbuf optionally accepts timewait and timeout parameters. See the DAPIO32 reference on DapBufferPutEx for details. If used, both timewait and timeout must be present. If the values in datamatrix are floating point numbers, they are truncated toward zero before they are sent to the Data Acquisition Processor. <numbytes> = dappstr(handle, string ) Ss text data in string to the Data Acquisition Processor. dappstr apps a terminating carriage-return character. The handle parameter to the ACCEL device has to be a text handle. The return value in numbytes is the number of bytes written including the carriage-return character or 0 if an error occurred. Each character written corresponds to one byte. Numbytes is an optional return argument. <code> = dapsetpa(paramnumber, parameter ) Sets a parameter string that is used by dapcnfig to replace corresponding %x parameters in the DAPL command file. The paramnumber parameter specify which %x parameter to replace. Paramnumber can be a value from 1 to 100. The value parameter replaces the corresponding %x parameter in the DAPL command file with that value. All %x parameters set by dapsetpa can be cleared using dapclrpa. The optional return value code is positive for success and 0 for an error. <code> = dapclrpa Clears all the parameter information that was set by dapsetpa. The default parameters in the DAPL command file are used again. Optional return value code is positive for success and 0 for an error. <code> = daprecnf( outputfilename ) Changes the output of dapcnfig from the Data Acquisition Processor to a text file defined by outputfilename. This function is useful for debugging DAPL command files that use replaceable parameters. Each call to daprecnf overrides all earlier calls. To change the output of dapcnfig back to the Data Acquisition Processor, outputfilename has to be an empty string, e.g., daprecnf(''). An option return value code is positive for success or 0 for file could not be opened. DAPtools for MATLAB 7