Main Content

Functions

Note

The MATLAB® instrument driver functions makemid, midedit, and midtest will be removed in a future release. Use the ividev interface from the Instrument Control Toolbox™ Support Package for IVI® and VXIplug&play Drivers instead. For more information, see IVI and VXIplug&play Drivers.

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.

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.

Examples of Functions

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

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 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 Measurement Computing™ Corporation GPIB board at board index 0. From the MATLAB command line,

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

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

  2. View the method you created.

    methods(obj)
    Methods for class icdevice:

class          display        icdevice       instrnotify    methods        size           
connect        end            inspect        instrument     ne             subsasgn       
ctranspose     eq             instrcallback  invoke         obj2mfile      subsref        
delete         fieldnames     instrfind      isa            openvar        vertcat        
devicereset    get            instrfindall   isequal        propinfo                      
disconnect     geterror       instrhelp      isvalid        selftest                      
disp           horzcat        instrhwinfo    length         set                           

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])

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 Add function text field and click the Add button. The new function's name, configureWaveform, appears in the Function Name pane.

  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 Measurement Computing Corporation GPIB board at board index 0. From the MATLAB command line,

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

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

  2. View the method you created.

    methods(obj)
    Methods for class icdevice:

class              fieldnames         instrhwinfo        obj2mfile          
connect            get                instrnotify        openvar            
ctranspose         geterror           instrument         propinfo           
delete             horzcat            invoke             selftest           
devicereset        icdevice           isa                set                
disconnect         inspect            isequal            size               
disp               instrcallback      isvalid            subsasgn           
display            instrfind          length             subsref            
end                instrfindall       methods            vertcat            
eq                 instrhelp          ne                                    

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])

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 = 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 Measurement Computing Corporation GPIB board at board index 0. From the MATLAB command line,

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

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

  2. View the method you created.

    methods(obj)
    Methods for class icdevice:

class              fieldnames         instrhwinfo        obj2mfile          
connect            get                instrnotify        openvar            
ctranspose         geterror           instrument         propinfo           
delete             horzcat            invoke             selftest           
devicereset        icdevice           isa                set                
disconnect         inspect            isequal            size               
disp               instrcallback      isvalid            subsasgn           
display            instrfind          length             subsref            
end                instrfindall       methods            vertcat            
eq                 instrhelp          ne                                    

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])