Functions

On this page…
Understanding Functions Function Components Examples of Functions

Understanding Functions

Functions allow you to call the instrument to perform some task or tasks, which may return results as text data or numeric data. The function may involve a single command to the instrument, or a sequence of instrument commands. A function may include the MATLAB software code to determine what commands are sent to the instrument or to perform analysis on data returned from the instrument. For example, a function may request that a meter run its self-calibration, returning the status as a result. Another function may read a meter's scaling, request a measurement, adjust the measured data according to the scale reading, and then return the result.

Back to Top

Function Components

The behavior of the function is defined by the components described below.

MATLAB Code

The MATLAB code defines the code that is executed when the function is evaluated with the invoke function. The code can be defined as an instrument command that will be written to the instrument or it can be defined as the MATLAB software code.

If the code is defined as an instrument command, the instrument command can be defined to take an input argument. All occurrences of <input argument name> in the instrument command are substituted with the input value passed to the invoke function. For example, if a function is defined with an input argument, start, and the instrument command is defined as Data:Start <start>, and a start value of 10 is passed to the invoke function, the command Data:Start 10 is written to the instrument.

If the code is defined as an instrument command, the instrument command can also be defined to return an output argument. The output argument can be returned as numeric data or as text data.

If the code is defined as the MATLAB software code, you can determine which commands are sent to the instrument, and the data results from the instrument can be manipulated, adjusted, or analyzed as needed.

Note   The code used for your function's MATLAB software code cannot include calls to the fclose or fopen functions on the interface object being used to access your instrument.

Help Text

The help text provides information on the function.

Back to Top

Examples of Functions

This section includes several examples of functions, and steps to verify the behavior of these functions.

Example: Simple Function

This example creates a function that will cause the Tektronix TDS 210 oscilloscope to adjust its vertical, horizontal and trigger controls to display a stable waveform. In the MATLAB instrument driver editor,

1. Select the Functions node in the tree.

2. Enter the function name, autoset, in the Add function text field and click the Add button. The new function's name, autoset, appears in the Function Name table.

3. Expand the Functions node to display all the defined functions.

4. Select the autoset node from the functions displayed in the tree.

5. Select the Code tab to define commands executed for this function.

   • Select Instrument Commands in the Function style field.

   • In the Define function commands pane, enter AUTOSet EXECute in the Add command field and click the Add button.

     

6. Select the Help tab to define the help text for this function.

   • In the Help text field, enter INVOKE(OBJ, 'autoset') causes the oscilloscope to adjust its vertical, horizontal, and trigger controls to display a stable waveform.

7. Click the Save button.

Verifying the Behavior of the Function.  This procedure verifies the behavior of the function. In this example, the driver name is tektronix_tds210_ex.mdd. Communication with the Tektronix TDS 210 oscilloscope at primary address 2 is done via a Keithley GPIB board at board index 0. From the MATLAB command line,

1. Create the device object, obj, using the icdevice function.

   g = gpib('keithley', 0, 2);
   obj = icdevice('tektronix_tds210_ex.mdd', g);

2. View the method you created.

   methods(obj)
   
   Methods for class icdevice:
   
   Contents         error            instrhwinfo      open
   class            fieldnames       instrnotify      openvar
   close            get              instrument       propinfo
   connect          geterror         invoke           selftest
   ctranspose       horzcat          isa              set
   delete           icdevice         isequal          sim
   devicereset      igetfield        isetfield        size
   disconnect       inspect          isvalid          subsasgn
   disp             instrcallback    length           subsref
   display          instrfind        methods          vertcat
   end              instrfindall     ne
   eq               instrhelp        obj2mfile
   
   Driver specific methods for class icdevice:
   
   autoset

3. View the help you wrote.

   instrhelp(obj, 'autoset')
   INVOKE(OBJ, 'autoset') causes the oscilloscope to adjust its 
   vertical, horizontal, and trigger controls to display a stable 
   waveform.

4. Using the controls on the instrument, set the scope so that its display is unstable. For example, set the trigger level outside the waveform range so that the waveform scrolls across the display.

5. Connect to your instrument and execute the function. Observe how the display of the waveform stabilizes.

   connect(obj)
   invoke(obj, 'autoset')

6. Disconnect from your instrument and delete the object.

   disconnect(obj)
   delete([obj g])

Example: Function with Instrument Commands that Use Input and Output Arguments

This example creates a function that configures which waveform will be transferred from the Tektronix TDS 210 oscilloscope, and configures the waveform's starting and ending data points. In the MATLAB instrument driver editor,

1. Select the Functions node in the tree.

2. Enter the function name, configureWaveform, in the New function text field and click the Add button. The new function's name, configureWaveform, appears in the Function Name table.

3. Expand the Functions node to display all the defined functions.

4. Select the configureWaveform node from the functions displayed in the tree.

5. Select the Code tab to define commands executed for this function.

   • Select Instrument Commands in the Function style field.

   • Enter the input arguments source, start, stop in the Input arguments field.

   • Enter Data:Source <source> in the Add command field and click the Add button. In the table, select an Output type of None and a Format type of N/A.

   • Similarly, add the command: Data:Source? with ASCII Output and text Format.

   • Similarly, add the command: Data:Start <start> with NONE Output and N/A Format.

   • Similarly, add the command: Data:Start? with ASCII Output and numeric Format.

   • Similarly, add the command: Data:Stop <stop> with NONE Output and N/A Format.

   • Similarly, add the command: Data:Stop? with ASCII Output and numeric Format.

     

6. Select the Help tab to define the help text for this function.

   • In the Help text field, enter [SOURCE, START, STOP] = INVOKE(OBJ, 'configureWaveform', SOURCE, START, STOP) configures the waveform that will be transferred from the oscilloscope.

7. Click the Save button.

Verifying the Behavior of the Function.  This procedure verifies the behavior of the function. In this example, the driver name is tektronix_tds210_ex.mdd. Communication with the Tektronix TDS 210 oscilloscope at primary address 2 is done via a Keithley GPIB board at board index 0. From the MATLAB command line,

1. Create the device object, obj, using the icdevice function.

   g = gpib('keithley', 0, 2);
   obj = icdevice('tektronix_tds210_ex.mdd', g);

2. View the method you created.

   methods(obj)
   
   Methods for class icdevice:
   
   Contents         error            instrhwinfo      open
   class            fieldnames       instrnotify      openvar
   close            get              instrument       propinfo
   connect          geterror         invoke           selftest
   ctranspose       horzcat          isa              set
   delete           icdevice         isequal          sim
   devicereset      igetfield        isetfield        size
   disconnect       inspect          isvalid          subsasgn
   disp             instrcallback    length           subsref
   display          instrfind        methods          vertcat
   end              instrfindall     ne
   eq               instrhelp        obj2mfile
   
   Driver specific methods for class icdevice:
   
   autoset configureWaveform

3. View the help you wrote.

   instrhelp(obj, 'configureWaveform')
   
   [SOURCE, START, STOP] = INVOKE(OBJ, 'configureWaveform', SOURCE, 
   START, STOP) configures the waveform that will be transferred from 
   the oscilloscope.

4. Connect to your instrument and execute the function.

   connect(obj)
   [source, start, stop] = invoke(obj, 'configureWaveform', 'CH1', 
   1, 500)
   source =
   CH1
   
   start =
        1
   
   stop =
      500
   [source, start, stop] = invoke(obj, 'configureWaveform', 'CH2', 
   0, 3500)
   source =
   CH2
   
   start =
        1
   
   stop =
           2500

5. Disconnect from your instrument and delete the object.

   disconnect(obj)
   delete([obj g])

Example: MATLAB Code Style Function

This example creates a function that will transfer and scale the waveform from the Tektronix TDS 210 oscilloscope. In the MATLAB instrument driver editor,

1. Select the Functions node in the tree.

2. Enter the function name, getWaveform, in the Add function text field and click the Add button. The new function's name, getWaveform, appears in the Function Name table.

3. Expand the Functions node to display all the defined functions.

4. Select the getWaveform node from the functions displayed in the tree.

5. Select the Code tab to define commands executed for this function.

   • Select M-Code in the Function style field.

   • Update the function line in the Define MATLAB function text field to include an output argument.

     function yout = getWaveform(obj)

   • Add the following MATLAB software code to the Define MATLAB function text field. (The instrument may require a short pause before any statements that read a waveform, to allow its completion of the data collection.)

     % Get the interface object.
     g = get(obj, 'Interface');
     
     % Configure the format of the data transferred.
     fprintf(g, 'Data:Encdg SRIBinary');
     fprintf(g, 'Data:Width 1');
     
     % Determine which waveform is being transferred.
     source = query(g, 'Data:Source?');
     
     % Read the waveform.
     fprintf(g, 'Curve?');
     ydata = binblockread(g, 'int8');
     
     % Read the trailing terminating character.
     fscanf(g);
     
     % Scale the data.
     fprintf(g, ['WFMPre:' source ':Yoff?']);
     yoffset = fscanf(g, '%g');
     
     fprintf(g, ['WFMPre:' source ':YMult?']);
     ymult = fscanf(g, '%g');
     
     yout = (ydata*ymult) + yoffset;

     

6. Click the Help tab to define the help text for this function.

   • In the Help text field, enter DATA = INVOKE(OBJ, 'getWaveform') transfers and scales the waveform from the oscilloscope.

7. Click the Save button.

Verifying the Behavior of the Function.  This procedure verifies the behavior of the function. In this example, the driver name is tektronix_tds210_ex.mdd. Communication with the Tektronix TDS 210 oscilloscope at primary address 2 is done via a Keithley GPIB board at board index 0. From the MATLAB command line,

1. Create the device object, obj, using the icdevice function.

   g = gpib('keithley', 0, 2);
   obj = icdevice('tektronix_tds210_ex.mdd', g);

2. View the method you created.

   methods(obj)
   
   Methods for class icdevice:
   
   Contents         error            instrhwinfo      open
   class            fieldnames       instrnotify      openvar
   close            get              instrument       propinfo
   connect          geterror         invoke           selftest
   ctranspose       horzcat          isa              set
   delete           icdevice         isequal          sim
   devicereset      igetfield        isetfield        size
   disconnect       inspect          isvalid          subsasgn
   disp             instrcallback    length           subsref
   display          instrfind        methods          vertcat
   end              instrfindall     ne
   eq               instrhelp        obj2mfile
   
   Driver specific methods for class icdevice:
   
   autoset configureWaveform getWaveform

3. View the help you wrote.

   instrhelp(obj, 'getWaveform')
   DATA = INVOKE(OBJ, 'getWaveform') transfers and scales the 
   waveform from the oscilloscope.

4. Connect to your instrument and execute the function.

   connect(obj)

   Configure the waveform that is going to be transferred.

   invoke(obj, 'configureWaveform', 'CH1', 1, 500);

   Transfer the waveform.

   data = invoke(obj, 'getWaveform');

   Analyze and view the waveform.

   size(data)
   ans =
      500     1
   
   plot(data)

5. Disconnect from your instrument and delete the object.

   disconnect(obj)
   delete([obj g])

Back to Top

Properties

Groups

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS