Creating MATLAB Instrument Drivers

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.

Driver Components

A MATLAB instrument driver contains information about an instrument and defines the functionality supported by the instrument.

Driver Component	Description
Driver Summary and Common Commands	Basic information about the instrument, e.g., manufacturer or model number.
Initialization and Cleanup	Code that is executed at various stages in the instrument control session, e.g., code that is executed upon connecting to the instrument.
Properties	A property is generally used to configure or query an instrument's state information.
Functions	A function is generally used to control or configure an instrument.
Groups	A group combines common functionality of the instrument into one component.

Depending on the instrument and the application for which the driver is being used, all components of the driver may not be defined. You can define the necessary driver components needed for your application with the MATLAB Instrument Driver Editor.

Note

The Instrument Driver Editor is unable to open MDDs with non-ascii characters either in their name or path on Mac platforms.

MATLAB Instrument Driver Editor Features

The MATLAB Instrument Driver Editor is a tool that creates or edits a MATLAB instrument driver. Specifically, it allows you to do the following:

Add/remove/modify properties.
Add/remove/modify functions.
Define the MATLAB code to wrap around commands sent to instrument.

Open the MATLAB Instrument Driver Editor with the following command.

midedit

In the rest of this section, each driver component will be described and examples will be shown on how to add the driver component information to a new MATLAB instrument driver called tektronix_tds210_ex.mdd. The tektronix_tds210_ex.mdd driver will define basic information and instrument functionality for a Tektronix^® TDS 210 oscilloscope.

Saving MATLAB Instrument Drivers

You can save an instrument driver to any directory with any name. It is recommended that the instrument driver be saved to a directory in the MATLAB path and that the name follows the format manufacturer_model.mdd. For example, an instrument that is used with a Tektronix TDS 210 oscilloscope should be saved with the name tektronix_tds210.mdd.

Driver Summary and Common Commands

You can assign basic information about the instrument to the MATLAB instrument driver. Summary information can be used to identify the MATLAB instrument driver and the instrument that it represents. Common commands can be used to reset, test, and read error messages from the instrument. Together, this information can be used to initialize and verify the instrument.

Topics in this section include

Driver Summary
Common Commands
Defining Driver Summary and Common Commands
Verifying Driver Summary and Common Commands

Driver Summary

You can assign basic information that describes your instrument in the instrument driver. This information includes the manufacturer of the instrument, the model number of the instrument and the type of the instrument. A version can also be assigned to the driver to assist in revision control.

Common Commands

You can define basic common commands supported by the instrument. The common commands can be accessed through device object properties and functions.

Common Commands	Accessed with Device Object's	Example Instrument Command	Description
Identify	`InstrumentModel` property	`*IDN?`	Returns the identification string of the instrument
Reset	`devicereset` function	`*RST`	Returns the instrument to a known state
Self test	`selftest` function	`*TST?`	Tests the instrument's interface
Error	`geterror` function	`ErrLog:Next?`	Retrieves the next instrument error message

The MATLAB Instrument Driver Editor assigns default values for the Common commands. The common commands should be modified appropriately to match the instrument's command set.

Defining Driver Summary and Common Commands

This example defines the basic driver information and Common commands for a Tektronix TDS 210 oscilloscope using the MATLAB Instrument Driver Editor:

Select the Summary node in the tree.
In the Driver summary pane:
1. Enter Tektronix in the Manufacturer field.
2. Enter TDS 210 in the Model field.
3. Select Oscilloscope in the Instrument type field.
4. Enter 1.0 in the Driver version field.
In the Common commands pane:
1. Leave the Identify field with *IDN?.
2. Leave the Reset field with *RST.
3. Leave the Self test field with *TST?
4. Update the Error field with ErrLog:Next?
Click the Save button. Specify the name of the instrument driver as tektronix_tds210_ex.mdd.

Note

For additional information on instrument driver nomenclature, refer to Saving MATLAB Instrument Drivers.

Verifying Driver Summary and Common Commands

This procedure verifies the summary information defined in the Driver Summary and Common commands panes. 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 Window,

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

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

View the defined driver information.

obj

   Instrument Device Object Using Driver : tektronix_tds210_ex.mdd
 
   Instrument Information
      Type:               Oscilloscope
      Manufacturer:       Tektronix
      Model:              TDS210
 
   Driver Information
      DriverType:         MATLAB interface object
      DriverName:         tektronix_tds210_ex.mdd
      DriverVersion:      1.0
 
   Communication State
      Status:             closed

instrhwinfo(obj)

ans = 

  struct with fields:

    Manufacturer: 'Tektronix'
           Model: 'TDS210'
            Type: 'Oscilloscope'
      DriverName: 'C:\Program Files\MATLAB\R2019b\toolbox\instrument\instrument\drivers\tektronix_tds210_ex.mdd'

Connect to the instrument.
```
connect(obj)
```

Verify the Common commands.

obj.InstrumentModel

ans =

    TEKTRONIX,TDS 210,0,CF:91.1CT FV:v2.03 TDS2MM:MMV:v1.04

devicereset(obj)

selftest(obj)

ans =

    0

geterror(obj)

ans = 

    ''

Disconnect from the instrument and delete the objects.
```
disconnect(obj) 
delete([obj g])
```

Initialization and Cleanup

This section describes how to define code that is executed at different stages in the instrument control session, so that the instrument can be set to a desired state at particular times. Specifically, you can define code that is executed after the device object is created, after the device object is connected to the instrument, or before the device object is disconnected from the instrument. Depending on the stage, the code can be defined as a list of instrument commands that will be written to the instrument or as MATLAB code.

Topics in this section include

Definitions of the types of code that can be defined
Examples of code for each supported stage
Steps used to verify the code

Create Code

You define create code to ensure that the device object is configured to support the necessary properties and functions:

Create code is evaluated immediately after the device object is created.
Create code can only be defined as a MATLAB software code.

Defining Create Code

This example defines the create code that ensures that the device object can transfer the maximum waveform size, 2500 data points, supported by the Tektronix TDS 210 oscilloscope. In the MATLAB instrument driver editor,

Select the Initialization and Cleanup node in the tree.

Click the Create tab and enter the MATLAB software code to execute on device object creation.

% Get the interface object and disconnect from instrument.
g = obj.Interface;
fclose(g);

% Configure the interface object's buffers to handle up to 
% 2500 points (two bytes per point requires 5000 bytes). 
g.InputBufferSize = 5000;
g.OutputBufferSize = 5000;

Click the Save button.

Verifying Create Code

This procedure verifies the MATLAB software create code defined. 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, create the interface object, g; and verify the default input and output buffer size values.
```
g = gpib('mcc',0,2);
g.InputBufferSize
```
```
ans =

   512
```
```
g.OutputBufferSize
```
```
ans =

   512
```
Create the device object, obj, using the icdevice function.
```
obj = icdevice('tektronix_tds210_ex.mdd',g);
```

Verify the create code by querying the interface object's buffer sizes.

g.InputBufferSize

ans =

        5000

g.OutputBufferSize

ans =

        5000

Delete the objects.
```
delete([obj g])
```

Connect Code

In most cases you need to know the state or configuration of the instrument when you connect the device object to it. You can define connect code to ensure that the instrument is properly configured to support the device object's properties and functions.

Connect code is evaluated immediately after the device object is connected to the instrument with the connect function. The connect code can be defined as a series of instrument commands that will be written to the instrument or as MATLAB software code.

Defining Connect Code

This example defines the connect code that ensures the Tektronix TDS 210 oscilloscope is configured to support the device object properties and functions. Specifically, the instrument will be returned to a known set of instrument settings (instrument reset) and the instrument will be configured to omit headers on query responses.

From the MATLAB instrument driver editor, select the Initialization and Cleanup node in the tree.
Click the Connect tab and enter the instrument commands to execute when the device object is connected to the instrument.
- Select Instrument Commands from the Function style menu.
- Enter the *RST command in the Command text field, and then click Add.
- Enter the HEADER OFF command in the Command text field, and then click Add.
Click the Save button.

Verifying Connect Code

This procedure verifies the instrument commands defined in the connect code. 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, create the device object, obj, using the icdevice function.
```
g = gpib('mcc',0,2); 
obj = icdevice('tektronix_tds210_ex.mdd',g);
```
Connect to the instrument.
```
connect(obj)
```
Verify the connect code by querying the Header state of the instrument.
```
query(g,'Header?')
```
```
ans =

        0
```
Disconnect from the instrument and delete the objects.
```
disconnect(obj) 
delete([obj g])
```

Disconnect Code

By defining disconnect code, you can ensure that the instrument and the device object are returned to a known state after communication with the instrument is completed.

Disconnect code is evaluated before the device object's being disconnected from the instrument with the disconnect function. This allows the disconnect code to communicate with the instrument. Disconnect code can be defined as a series of instrument commands that will be written to the instrument or it can be defined as MATLAB software code.

Defining Disconnect Code

This example defines the disconnect code that ensures that the Tektronix TDS 210 oscilloscope is returned to a known state after communicating with the instrument using the device object.

From the MATLAB instrument driver editor, select the Initialization and Cleanup node in the tree.
Click the Disconnect tab and enter the MATLAB software code to execute when the device object is disconnected from the instrument.
- Select M-Code from the Function style menu.
- Define the MATLAB software code that will reset the instrument and configure the interface object's buffers to their default values.
  % Get the interface object. g = obj.Interface; % Reset the instrument to a known state. fprintf(g, '*RST');
Click the Save button.

Verifying Disconnect Code

This procedure verifies the MATLAB software code defined in the disconnect code. 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,

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

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

Connect to the instrument.
```
connect(obj)
```
Alter some setting on the instrument so that a change can be observed when you disconnect. For example, the oscilloscope's contrast can be changed by pressing its front pane Display button, and then the Contrast Decrease button.
Disconnect from the instrument and observe that its display resets.
```
disconnect(obj)
```
Delete the objects.
```
delete([obj g])
```