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.
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.
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
.
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
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.
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 |
|
| Returns the identification string of the instrument |
Reset |
|
| Returns the instrument to a known state |
Self test |
|
| Tests the instrument's interface |
Error |
|
| 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.
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:
Enter Tektronix
in the Manufacturer field.
Enter TDS 210
in the Model field.
Select Oscilloscope
in the Instrument type field.
Enter 1.0
in the Driver
version field.
In the Common commands pane:
Leave the Identify field
with *IDN?
.
Leave the Reset field
with *RST
.
Leave the Self test field
with *TST?
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.
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])
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
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.
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.
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])
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.
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.
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])
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.
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.
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])