Mathworks INSTRUMENTCONTROL TOOLBOX 2 user guide

Download

Instrument Contro

User’s Guide

l Toolbox™ 2

How to Contact The MathWorks

www.mathworks. comp.soft-sys.matlab Newsgroup www.mathworks.com/contact_TS.html T echnical Support

suggest@mathworks.com Product enhancement suggestions

bugs@mathwo doc@mathworks.com Documentation error reports service@mathworks.com Order status, license renewals, passcodes

info@mathwo

com

rks.com

Web

Bug reports

Sales, prici

ng, and general information

508-647-7000 (Phone)

508-647-7001 (Fax)

The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098

For contact information about worldwide offices, see the MathWorks Web site.

Instrument Control Toolbox™ User’s Guide

The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathW orks, Inc.

FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this s oftware or docume n tation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern theuse,modification,reproduction,release,performance,display,anddisclosureoftheProgramand Documentation by the federal government (or other entity acquiring for or through the federal government) and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the government’s needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Docu mentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See

www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand

names may be trademarks or registered trademarks of their respective holders.

Patents

The MathWorks products are protected by one or more U.S. patents. Please see

www.mathworks.com/patents for more information.

Revision History

November 2000 First printing New for V ersion 1.0 (Release 12) June 2001 Second printing Revised for Version 1.1 (Release 12.1) July 2002 Online only Revised for Version 1.2 (Release 13) August 2002 Third printing Revised for Version 1.2 June 2004 Online only Revised for Version 2.0 (Release 14) October 2004 Fourth printing Revised for Version 2.1 (Release 14SP1) March 2005 Online only Revised for Version 2.2 (Release 14SP2) June 2005 Fifth printing Minor revision for Version 2.2 September 2005 Online only Revised for Version 2.3 (Release 14SP3) March 2006 Online only Revised for Version 2.4 (Release 2006a) September 2006 Online only Revised for Version 2.4.1 (Release 2006b) March 2007 Online only Revised for Version 2.4.2 (Release 2007a) September 2007 Sixth printing Revised for Version 2.5 (Release 2007b) March 2008 Online only Revised for Version 2.6 (Release 2008a) October 2008 Online only Revised for Version 2.7 (Release 2008b) March 2009 Online only Revised for Version 2.8 (Release 2009a) September 2009 Online only Revised for Version 2.9 (Release 2009b) March 2010 Online only Revised for Version 2.10 (Release 2010a)

Getting Started

Product Overview ................................. 1-2

Getting to Know the Instrument Control Toolbox

Software Exploring the Instrument Control Toolbox Software Learning About the Instru m ent Control Toolbox

Software Using the Documentation Examples

....................................... 1-2

....................................... 1-3

.................. 1-4

Contents

..... 1-3

Toolbox Components

Passing Information Between the MATLAB Workspace and

Your Instrument MATLAB F unctions Interface Driver Adaptor

Understanding the Toolbox Capabilities

Overview H elp Documentation Examples Demos

Installation In formation

Installation Requirements Toolbox Installation Hardware and Driver Installation

Examining Your Hardware Resources

instrhwinfo Function Test & Measurement Tool Viewing the IVI Configuration Store

Communicating with Your Instrument

Instrument Control Session Examples Example: Communicating with a GPIB Instrument Example: Communicating with a GPIB-VXI Instrument

.......................................... 1-9

............................... 1-5

................................ 1-5

............................... 1-7

........................... 1-8

............. 1-9

.................................... 1-9

........................... 1-9

........................... 1-10

.......................... 1-10

............................... 1-10

.................... 1-11

............... 1-12

.............................. 1-12

.......................... 1-16

.................. 1-18

.............. 1-21

................ 1-21

..... 1-21

.. 1-22

Example: Communicating with a Serial Port

Instrument

Example: Communicating with a GPIB Instrument Using a

Device Object

.................................... 1-24

................................... 1-25

General Preferences for Instrument Control

Accessing General Preferences MATLAB Instrument Driver Editor MATLAB Instrument Driver Testing Tool Device Objects IVI Configuration Store

Getting Help

instrhelp Function propinfo Function instrsupport Function Online Support

.................................... 1-29

...................................... 1-31

................................. 1-31

................................. 1-32

.............................. 1-33

................................... 1-33

....................... 1-27

.................. 1-28

............................ 1-30

......... 1-27

............. 1-28

Instrument Control Session

Creating Instrument Objects ....................... 2-2

Overview Interface Obj ects Device Objects

........................................ 2-2

.................................. 2-2

.................................... 2-3

vi Contents

Connecting to the Instrument

Configuring an d Returning P roperties

Configuring Property Names and Property Values Returning Property Names and Property Values Property Inspector

Communicating with Your Instrument

Interface Objects and Instrument Commands Device Objects and Instrument Drivers

Disconnecting and Cleaning Up

................................. 2-6

...................... 2-4

.............. 2-5

.............. 2-7

............... 2-7

..................... 2-8

...... 2-5

........ 2-5

.......... 2-7

Disconnecting an Instrument Object .................. 2-8

Cleaning Up the MATLAB Workspace

................ 2-8

Summary

Advantages of Using Device Objects When to Use Interface Objects

......................................... 2-9

.................. 2-9

....................... 2-9

Using Interface Objects

Creating an Interface Object ....................... 3-2

Object Creatio n Functions Configuring Properties During Object Creation Creating an Array of Instrument Objects

Connecting to the Instrument

Configuring an d Returning P roperties

Base and Interface-Specific Properties Returning Property Names and Property Values Configuring Property Values Specifying Property Names Default Property Values Property Inspector

................................. 3-11

.......................... 3-2

......... 3-3

.............. 3-3

...................... 3-5

.............. 3-6

................ 3-6

........ 3-6

........................ 3-9

......................... 3-10

............................ 3-10

Writing and Reading Data

Before Performing Read/Write Operations Writing Data Reading Data

Disconnecting and Cleaning Up

Disconnecting an Instrument Object Cleaning Up the MATLAB Workspace

..................................... 3-13

..................................... 3-19

.......................... 3-12

..................... 3-24

............. 3-12

.................. 3-24

................ 3-24

vii

Controlling Instruments Using GPIB

GPIB Overview .................................... 4-2

What Is GPIB? Important GPIB Features GPIB Lines Status and Event Reporting

.................................... 4-2

.......................... 4-3

...................................... 4-4

......................... 4-8

Creating a GPIB Object

Using the gpib Function GPIB Object Display

Configuring the GPIB Address

Writing and Reading Data

Rules for Completing Write and Read Operations Example: Writing and Reading Text Data Example: Reading Binary Data Example: Parsing Input Data Using scanstr Example: Understanding EOI and EOS

Events and Callbacks

Example: Introduction to Events and Callbacks Event Types and Callback Properties Responding To Event Information Creating and Executing Callback Functions Enabling Callback Functions After They Error Example: Using Events and Callbacks to Read Binary

Data

.......................................... 4-32

Triggers

Using the trigger Function Example: Execu ting a Trigger

.......................................... 4-35

............................ 4-14

............................... 4-15

...................... 4-17

.......................... 4-18

............. 4-19

...................... 4-21

........... 4-23

............... 4-24

.............................. 4-27

................. 4-28

.................... 4-29

............ 4-31

.......................... 4-35

....................... 4-35

....... 4-18

......... 4-27

......... 4-32

viii Contents

Serial Polls

Using the spoll Function Example: Executing a Serial Poll

........................................ 4-38

............................ 4-38

.................... 4-38

Controlling Instruments Using VISA

VISA Overview .................................... 5-2

What Is VISA? Interfaces Used with VISA Supported Vendor and Resource Names

.................................... 5-2

.......................... 5-2

............... 5-3

Working with the GPIB Interface

Understanding VISA-GPIB Creating a VISA-GPIB Object VISA-GPIB Address

Working with the VXI and the PXI Interfaces

Understanding VISA-VXI Understanding VISA-PXI Creating a VISA-VXI Object VISA-VXI Address Register-Based Communication

Working with the GPIB-VXI Interface

Understanding VISA-GPIB-VXI Creating a VISA-GPIB-VXI Object VISA-GPIB-VXI Address

Working with the Serial Port Interface

Understanding the Serial Port Creating a VISA-Serial Object Configuring Communication Settings

Working with the USB Interface

Creating a VISA-USB Object VISA-USB Address

............................... 5-8

................................. 5-12

................................ 5-34

......................... 5-5

.......................... 5-9

........................... 5-10

......................... 5-10

........................... 5-25

................... 5-5

....................... 5-5

...................... 5-13

............... 5-22

..................... 5-22

................... 5-23

.............. 5-28

....................... 5-28

................. 5-30

.................... 5-32

........................ 5-32

........ 5-9

Working with the TCP/IP Interface

Understanding VISA-TCP/IP Creating a VISA-TCPIP Object VISA-TCPIP Address

Working with the RSIB Interface

.............................. 5-38

........................ 5-36

...................... 5-36

.................. 5-36

................... 5-40

Understanding VISA-RSIB .......................... 5-40

Creating a VISA-RSIB Object VISA-RSIB Address

............................... 5-42

....................... 5-40

Controlling Instruments Using the Serial Port

Serial Port Overview ............................... 6-2

What Is Serial Communication? Serial Port Interface Standard Supported Platforms Connecting Two Devices with a Serial Cable Serial Port Signals and Pin Assignments Serial Data Format Finding Serial Port Information for Your Platform

............................... 6-3

................................ 6-9

...................... 6-2

....................... 6-3

........... 6-4

.............. 6-5

...... 6-13

Serial Port Object

Creating a Serial Port Object Serial Port Object Display

Configuring Communication Settings

Writing and Reading Data

Asynchronous Write and Read Operations Rules for Completing Write and Read Operations Example: Writing and Reading Text Data

Events and Callbacks

Event Types and Callback Properties Responding To Event Information Example: Using Events and Callbacks

Using Control Pins

Control Pins Signaling the Presence of Connected Devices Controlling the Flow of Data: Handshaking

................................. 6-16

........................ 6-16

.......................... 6-18

............... 6-19

.......................... 6-20

.............................. 6-26

................. 6-26

.................... 6-27

................ 6-29

................................. 6-32

...................................... 6-32

............. 6-20

....... 6-21

............. 6-23

........... 6-32

............ 6-35

x Contents

Controlling Instruments Using TCP/IP and UDP

TCP/IP and UDP Overview ......................... 7-2

Creating a TCP/IP Object

TCP/IP Object TCP/IP Object Display Example: Communicating with a Remote Host Example: Server Drops the Connection

Creating a UDP Object

UDP Object The UDP Object Display Example: Communicating Between Two Hosts

Writing and Reading Data

Rules for Completing Write and Read Operations Example: Writing and Reading Data with a TCP / IP

Object

Example: Writing and Reading Data with an UDP

Object

Events and Callbacks

Event Types and Callback Properties Responding To Event Information Example: Using Events and Callbacks

.................................... 7-4

...................................... 7-10

......................................... 7-15

......................................... 7-18

........................... 7-4

............................. 7-5

................ 7-7

............................. 7-10

............................ 7-11

.......................... 7-14

.............................. 7-21

................. 7-21

.................... 7-22

................ 7-24

......... 7-6

......... 7-12

....... 7-14

Using Device Objects

Device Objects .................................... 8-2

Overview What Are Device Objects? Device Objects for MATLAB Instrument Drivers

Creating an d Connecting D evice Objects

........................................ 8-2

........................... 8-2

........ 8-3

............ 8-5

Device Objects for MATLAB Interface Drivers .......... 8-5

Device Objects for VXIplug&play and IVI Drivers Connecting the Device Object

........................ 8-7

....... 8-7

Communicating with Instruments

Configuring Instrument Settings Calling Device Object Methods Control Commands

Device Groups

Working w ith Group Objects Example: Using Device Groups to Access Instrument

Data

.......................................... 8-15

................................ 8-12

..................................... 8-14

........................ 8-14

.................. 8-9

..................... 8-9

....................... 8-10

Using V XI plug&play Drivers

Overview ......................................... 9-2

Instrument Control Toolbox Software and VXIplug&play

Drivers VISA Setup Other Software Requirements

VXIplug&play Drivers

Installing VXI plug&play Drivers Creating a MATLAB VXIplug&play Instrument D river Constructing Device Objects Using a MATLAB

VXIplug&play Instrument Driver

....................................... 9-2

...................................... 9-2

....................... 9-3

............................. 9-4

.................... 9-4

.................. 9-8

.. 9-5

xii Contents

Using IVI Drivers

IVI Drivers Overview .............................. 10-2

Instrument Control Toolbox Software and IVI Drivers IVI-C and IVI-COM

................................ 10-2

... 10-2

Instrument Interchangeability ...................... 10-3

Minimal Code Changes Effective Use of Interchangeability Examples of Interchangeability

............................. 10-3

................... 10-3

...................... 10-3

Getting Started with IVI Drivers

Introduction Requirements to Work with MATLAB MATLAB IVI Instrument Driver Using MATLAB IVI Wrappers

IVI Configuration Store

Benefits of an IVI Configuration Store Components of an IVI Configuration Store Configuring an IVI Configuration Store

...................................... 10-6

............................ 10-16

.................... 10-6

................. 10-7

..................... 10-10

....................... 10-14

................ 10-16

............. 10-16

............... 10-18

Using Generic Instrument Drivers

Generic Drivers: Overview ......................... 11-2

Example: Writing a Generic Driver

Creating the Driver and Defining Its Initialization

Behavior Defining Properties Defining Functions

...................................... 11-3

................................ 11-5

................................ 11-8

.................. 11-3

Example: Using a Generic Driver with the Test &

Measurement Tool

Creating and Connecting the Device Object Accessing Properties Using Functions

Example: Using a Generic Driver at the Command

Line

Creating and Connecting the Device Object Accessing Properties Using Functions

............................................ 11-13

............................... 11-9

............ 11-9

............................... 11-11

.................................. 11-11

............ 11-13

............................... 11-14

.................................. 11-15

xiii

Saving and Loading the Session

Saving and Loading Instrument Objects ............. 12-2

Saving Instrument Objects to a File Saving Objects to a MAT-File

........................ 12-4

.................. 12-2

Debugging: Recording Information to Disk

Using the record Function Example: Introduction to Recording Information Creating Multiple Record Files Specifying a File Name Record File Format Example: Recording Information to Disk

................................ 12-8

.......................... 12-6

...................... 12-7

............................. 12-8

.......... 12-6

........ 12-7

.............. 12-10

Test & Measurement Tool

Test & Measurement Tool: Overview ................ 13-2

Instrument Control Toolbox Software Support Navigating the Tree

Using the Test & Measurement Tool

Overview o f the Examples Hardware Instrument Objects Instrument Drivers

........................................ 13-4

............................... 13-3

................. 13-4

.......................... 13-4

................................ 13-12

................................ 13-17

.......... 13-2

xiv Contents

Using the Instrument Driver Editor

MATLAB Instrument Driver Editor: Overview ....... 14-2

What Is a MATLAB Instrument D river? How Does a MATLAB Instrument Driver Work? Why Use a MATLAB Instrument Driver?

............... 14-2

........ 14-3

.............. 14-3

Creating MATLAB Instrument Drivers .............. 14-5

Driver Components MATLAB Instrument Driver Editor Features Saving MATLAB Instrument Drivers Driver Summary and Common Commands Initialization and Cleanup

................................ 14-5

.......... 14-6

................. 14-6

............. 14-6

.......................... 14-11

Properties

Properties: Overview Property Components Examples of Properties

Functions

Understanding Functions Function Components Examples of Functions

Groups

Group Components Examples of Groups

UsingExistingDrivers

Modifying MATLAB Instrument Drivers Importing VXIplug&play and IVI Drivers

........................................ 14-18

.............................. 14-18

............................. 14-21

......................................... 14-34

........................... 14-34

.............................. 14-34

............................. 14-35

........................................... 14-46

................................ 14-46

............................... 14-47

............................. 14-65

Using the Instrument Driver Testing Tool

.............. 14-65

............. 14-66

Instrument Driver Testing Tool: Overview ........... 15-2

Functionality Drivers Test Structure Starting Example

Setting Up Your T est

Test File Providing a Name and Description

..................................... 15-2

.......................................... 15-2

.................................... 15-3

......................................... 15-3

......................................... 15-4

............................... 15-5

......................................... 15-5

................... 15-5

Specifying the Driver .............................. 15-5

Specifying an Interface Setting Test Preferences Example: Setting Up a Driver Test

............................. 15-5

............................ 15-6

................... 15-7

Defining Test Steps

Test Step: Set Property Test Step: Get P r operty Test Step: Properties Sweep Test Step: Function

Saving Your Test

Saving the Test as MATLAB Code Saving the Test as a Driver Function

Testing and Results

Running All Steps Partial Testing Exporting Results Saving Results

................................ 15-11

............................. 15-11

............................ 15-15

......................... 15-17

................................ 15-21

.................................. 15-25

.................... 15-25

................. 15-25

................................ 15-28

................................. 15-28

.................................... 15-30

................................. 15-30

.................................... 15-31

Using the Instrument Control Toolbox Block

Library

xvi Contents

Overview ......................................... 16-2

Opening the Instrument Control Block Library

Using the instrumentlib Command from the MATLAB

Command Window

Using the Simulink Library Browser

Building Simulink Models to Send and Receive Data

Example: Sending and Receiving Data Through a Serial

Port Loopback

Example: Sending and Receiving Data Via a TCP/IP

Network

....................................... 16-18

.............................. 16-3

.................. 16-4

.................................. 16-8

...... 16-3

.. 16-8

Function Reference

Instrument Object Creation ........................ 17-2

Interface Obj ect Device Object

................................... 17-2

..................................... 17-2

State Change

Interface Obj ect Device Object

Property Display and Configuration

Data Reading

Data Writing

Information and Help

Graphical Tools

Interface Obj ect Device Object

Utilities

Interface Objects

GPIB Serial Port TCP/IP UDP VISA-GPIB VISA-GPIB-VXI VISA-Serial VISA-VXI

............................................ 17-8

...................................... 17-2

................................... 17-3

..................................... 17-3

...................................... 17-3

...................................... 17-4

.............................. 17-5

................................... 17-5

..................................... 17-5

........................................... 17-6

.................................. 17-7

........................................... 17-7

....................................... 17-8

.......................................... 17-8

...................................... 17-8

................................... 17-8

...................................... 17-9

........................................ 17-9

................ 17-3

Device Objects

IVI Configuration Store Objects

.................................... 17-10

..................... 17-10

xvii

Functions — Alphabetical List

Property Reference

Interface Object Base Properties .................... 19-2

Writing Data Reading Data Recording Data Callbacks General Purpose

..................................... 19-2

................................... 19-3

........................................ 19-3

.................................. 19-4

Interface-Specific Prop erties

GPIB Serial Port TCPIP UDP VISA-GPIB VISA-GPIB-VXI VISA-RSIB VISA-Serial VISA-TCPIP VISA-USB VISA-VXI

Device Object Base Properties

IVI Configuration Store Object Properties

........................................... 19-5

....................................... 19-6

.......................................... 19-7

............................................ 19-7

...................................... 19-8

................................... 19-8

....................................... 19-9

...................................... 19-10

..................................... 19-10

....................................... 19-11

........................................ 19-11

....................... 19-5

...................... 19-13

........... 19-14

xviii Contents

Properties — Alphabetical List

Block Reference

Vendor Driver Requirements and Limitations

Driver Requirements .............................. A-2

GPIB Driver Limitations by Vendor

Advantech Agilent Technologies Capital Equipment Corporation ICS Electronics IOTech Keithley Measurement Computing Corporation

VISA Driver Limitations

Agilent Technologies National Instruments

....................................... A-4

............................... A-4

................................... A-5

.......................................... A-6

......................................... A-6

............................... A-8

.............................. A-8

................. A-4

...................... A-5

................ A-7

........................... A-8

Bibliography

Index

xix

xx Contents

Getting Started

• “Product Overview” on page 1-2

• “Toolbox Components” on page 1-5

• “Understanding the Toolbox Capabilities” on page 1-9

• “Installation Information” on page 1-10

• “Examining Your Hardware Resources” on page 1-12

• “Communicating with Your Instrument” on page 1-21

• “General Preferences for Instrument C ontrol” on page 1-27

• “Getting Help” on page 1-31

1 Getting Started

Product Overview

Getting to Know the Instrument Control Toolbox Software

Instrument Control Toolbox™ software is a collection of MATLAB®functions built on the MATLAB technical computing environment. The toolbox provides you with these features:

In this section...

“Getting to Know the Instrument Control Toolbox Software” on page 1-2

“Exploring the Instrument Control Toolbox Software” on page 1-3

“Learning About the Instrument Control Toolbox Software” on page 1-3

“Using the Documentation Examples” on page 1-4

• A framework for communicating with instruments that support the GPIB

interface (IEEE protocols. Note that the toolbox extends the basic serial port featur es included with the MATLAB software.

• Support for IVI, VXIplug&play, and MATLAB instrument drivers.

• Functions for transferring data between the MATLAB workspace and your

instrument:

-488), the VISA standard, and the TCP/IP and UDP

- The d ata can be binary (numerical) or text.

- The transfer can be synchronous and block access to the M ATLAB

Command Window, or asynchronous and allow access to the MATLAB Command Window.

• Event-based communication.

• Functions for recording data and event information to a text file.

• Tools that facilitate instrume nt control in an easy-to -u se grap h ical

environment.

The MathWorks™ provides several related products that are especially relevant to the kinds of tasks you can perform with the Instrument Control Toolbox software. For more information about any of these products, see

1-2

Product Overview

http://www.mathworks.com/products/instrument/related.jsp.

Exploring the Instrument Control Toolbox Software

For a list of the toolbox functions, type

help instrument

For the code of a function, type

type function_name

For help f or any function, type

instrhelp function_name

You can change the way any toolbox function works by copying and renaming the file, then modifying your copy. You can also extend the toolbox by adding your own files, or by using it in combination with other products such as MATLAB

Report Generator™or Data Acquisition Toolbox™ product.

To use the Instrument Control Toolbox product, you should be familiar with the:

• Basic features of MATLAB.

• Appropriate commands used to communicate with your instrument.

These commands might use the SCPI language or they might be methods associated with an IVI, VXIplug&play, or MATLAB instrument driver.

• Features of the interface associated with your instrument.

Learning About the Instrument Control Toolbox Software

Start with this chapter, which describes how to examine your hardware resources, how to communicate with your instrument, how to get online help, and so on. Then read Chapter 2, “Instrument Control Session”, which provides a framework for constructing instrument control applications. Depending on the interface used by your instrument, you m ight then want to read the appropriate interface-specific chapter.

1-3

1 Getting Started

If you want detailed information about a specific function, refer to Functions — Alphabetical List. If you want detailed information about a specific property, refer to Properties — Alphabetical List.

Using the Documentation Examples

The examples in this guide use specific instruments such as a Tektronix TDS 210 two-channel oscilloscope or an Agilent®33120A function generator. Additionally, the GPIB examples use a National Instruments controller and the serial port examples use the Windows

specific COM1 se ria l

GPIB

port. The string commands written to these instruments are often unique to the vendor, and the address information such as the board index or primary address associated with the hardware reflects a specificconfiguration.

These documentation examples are collected in the exam ple index, which is available through the Help browser. You should modify the examples to work with your specific hardware configuration.

1-4

Toolbox Components

In this section...

“Passing Information Between the MATLAB Workspace and Your Instrument” on page 1-5

“MATLAB Functions” on page 1-7

“Interface Driver Adaptor” on page 1-8

Passing Information Between the MATLAB Workspace and Your Instrument

Instrument Control Toolbox software consists of two distinct components: MATLAB functions and interface driver adaptors. These components allow you to pass information between the MATL AB workspace a n d your instrument. For example, the following diagram shows how information passes from the MATLAB software to an instrument via the GPIB driver a nd the GPIB controller.

Toolbox Components

1-5

1 Getting Started

1-6

This diagram illustrates how information flows from component to component. Information consists of

• Property values

You define the behavior of your instrument control application by configuring property values. In general, you can think of a property as a

Toolbox Components

characteristic of the toolbox or of the instrument that can be configured to suit your needs.

• Data

You can write data to the instrument and read data from the instrument. Data can be binary (numerical) or formatted as text. Writing text often involves writing string commands that change hardware settings, or prepare the instrument to return data or status information, while writing binary data involves writing numerical values such as calibration or waveform data.

• Events

An event occurs after a condition is met and might result in one or more callbacks. Events can be generated on ly after you configure the associated properties. For example, you can use events to analyze data after a certain number of bytes are read from the instrument, or display a message to the MATLAB command line after an error occurs.

MATLAB Functions

To perform any task within your instrument control application, you must call MATLAB functions from the MATLAB workspace. Among other things, these functions allow you to:

• Create instrument objects, which provide a gateway to your instrument’s

capabilities and allow you to control the behavior of your application.

• Connect the object to the instrument.

• Configure property values.

• Write data to the instrument, and read data from the instrument.

• Examine your hardware resources and evaluate your application status.

For a listing of all Instrument Control Toolbox software functions, refer to Functions — Alphabetical List . You can also display the toolbox functions by typing

help instrument

1-7

1 Getting Started

Interface Driver Adaptor

The interface driver adaptor (or just adaptor) is the link between the toolbox and the interface driver. The adaptor’smainpurposeistopassinformation between the MATLAB workspace and the interface driver. Interface drivers are provided by your instrument vendor. For example, if you are communicating with an instrument using a National Instruments GPIB controller, then an interface driver such as NI-488.2 must be installed on your platform. Note that interface drivers are not installed as part of the Instrument Control Toolbox software.

Instrument Control Toolbox software provides adaptors for the GPIB interface and the VISA standard. The serial port, TCP/IP, and UDP interfaces do not require an adaptor.

Interface Adaptor Name

GPIB

Serial port N/A

advantech, agilent, cec, contec, ics, iotech, keithley, mcc, ni

1-8

TCP/IP N/A

UDP

VISA standard

As described in “Examining Your Hardware Resources” on page 1-12, you can list the supported interfaces and adaptor names with the function. For a list of vendor driver requirements and limitations, refer to Appendix A, “Vendor Driver Requirements and Limitations”.

N/A

agilent, ni, tek

instrhwinfo

Understanding the Toolbox Capabilities

In this section...

“Overview Help” on page 1-9

“Documentation Examples” on page 1-9

“Demos” on page 1-9

Overview Help

The overview help lists the toolbox functions grouped by usage. You can display this information by typing

help instrument

Forthecodeforanyfunction,type

type function_name

Understanding the Toolbox Capabilities

Documentation Examples

This guide provides detailed examples that show you how to communicate with all supported interface types. These examples are collected in the example index, which is available through the Help browser.

The examples u se specific peripheral instruments, GPIB controllers, string commands, address information, and so on. If your instrument accepts different string commands, or if your hardware is configured to use different address i nformatio n, you should modify the examples accordingly.

Demos

The toolbox includes a large collection of tutorial demos, which you can access through the Help browser Demos pane. Use the following command to open the Help browser to the toolbox demos:

demo toolbox 'Instrument Control'

You do not need an instrument connected to your computer to use tutorials as they use prerecorded data.

1-9

1 Getting Started

Installation Information

In this section...

“Installation Requirements” on page 1-10

“Toolbox Installation” on page 1-10

“Hardware and Driver Installation” on page 1-11

Installation Requirements

To communicate with your instrument from the MATLAB workspace, you must install these components:

• MATLAB 7

• Instrument Control Toolbox software

Additionally, you might need to install hardware such as a GPIB controller and vendor-specific software such as drivers, support libraries, and so on. For a complete list of all supported vendors, refer to “Interface Driver Adaptor” on page 1-8.

1-10

Toolbox Installation

To determine if Instrument Control Toolbox software is installed on your system, type

ver

at the MATLAB Command Window. The MATLAB Command Window displays information about the version of the MATLAB software you are running, including a list of installed add-on products and their version numbers. Check the list to see if Instrument Control Toolbox appears.

For information about installing the toolbox, refer to the installation documentation for your platform. If you experience installation difficulties, look for the installation and license information at the MathWorks Web site (

http://www.mathworks.com/support).

Installation Information

Hardware and Dri

Installation of support librari instrument ven Web site. For a l Appendix A, “V

You must inst instrument v

hardware devices such as GPIB controllers, instrument drivers, es, and so on is described in the documentation provided by the

dor. Many vendors provide the latest drivers through their

ist of vendor driver requirements and limitations, refer to

endor Driver Requirements and Limitations”.

all all necessary device-specific software provided by the

endor in addition to the Instrument Control Toolbox software.

ver Installation

1-11

1 Getting Started

Examining Your Hardware Resources

In this section...

“instrhwinfo Function” on page 1-12

“Test & Measurem ent Tool” on page 1-16

“Viewing the IVI Configuration Store” on page 1-18

instrhwinfo Function

You can examine the hardware-related res ou rces visible to the toolbox with the

instrhwinfo function. The specific information returned by instrhwinfo

depends on the supplied arguments, and is divided into these categories:

• “General Toolbox Information” on page 1-12

• “Interface Information” on page 1-13

• “Adaptor Information” on page 1-13

1-12

• “Instrument Object Information” on page 1-15

• “Installed Driver Information” on page 1-16

General Toolbox Information

For general information about the Instrument Control Toolbox, type:

instrhwinfo

MATLABVersion: '7.0 (R14)'

SupportedInterfaces: {'gpib' 'serial' 'visa' 'tcpip' 'udp'}

SupportedDrivers: {'matlab' 'vxipnp' 'ivi'}

ToolboxName: 'Instrument Control Toolbox'

ToolboxVersion: '2.0 (R14)'

The SupportedInterfaces and SupportedDrivers fields list the interfa ces and drivers supported by the toolbox, and not necessarily those installed on your computer.

Examining Your Hardware Resources

Interface Information

To display information about a specific interface, you supply the interface name as an arg ument to

serial, tcpip, udp,orvisa.

For the GPIB and VISA interfaces, the information includes installed adaptors. For the serial port interface, the information includes the available ports. For the TCP/IP and UDP interfaces, the information includes the local host address. For example, to display the GPIB interface information:

out = instrhwinfo('gpib') out =

InstalledAdaptors: {'mcc' 'ni'}

JarFileVersion: 'Version 2.0 (R14)'

The InstalledAdaptors field indicates that the Measurement Computing™ Corporation and National Instruments drivers are installed. Therefore, you can communicate with instruments using GPIB controllers from these vendors.

instrhwinfo. The interface name can be gpib,

Adaptor Information

To display information about a specific installed adaptor, you supply the interfacenameandtheadaptornameasargumentsto

Interface

Adaptor Name

Name

gpib advantech, agilent, cec, contec, ics, iotech, keithley,

mcc, ni

visa agilent, ni, tek

The returned information describes the adaptor, the vendor driver, and the object constructors. For example, to display information for the National Instruments GPIB adaptor,

ghwinfo = instrhwinfo('gpib','ni')

ghwinfo =

instrhwinfo.

1-13

1 Getting Started

AdaptorDllName: [1x82 char]

AdaptorDllVersion: 'Version 2.0 (R14)'

AdaptorName: 'NI'

InstalledBoardIds: 0

ObjectConstructorName: {'gpib('ni', 0, 2);'}

VendorDllName: 'gpib-32.dll'

VendorDriverDescription: 'NI-488'

The ObjectConstructorName field provides the syntax for creating a GPIB object for the National Instruments adaptor. In this example, the GPIB controller has board index

g = gpib('ni',0,2);

0 and the instrument has primary address 2.

To display information for the Tektronix VISA adaptor,

vhwinfo = instrhwinfo('visa','tek') vhwinfo =

1-14

AdaptorDllName: [1x83 char]

AdaptorDllVersion: 'Version 2.0 (R14 Beta 1)'

AdaptorName: 'TEK'

AvailableChassis: []

AvailableSerialPorts: {2x1 cell}

InstalledBoardIds: 0

ObjectConstructorName: {3x1 cell}

SerialPorts: {2x1 cell}

VendorDllName: 'visa32.dll'

VendorDriverDescription: 'Tektronix VISA Driver'

VendorDriverVersion: 2.0500

The available VISA object constructor names are shown below.

vhwinfo.ObjectConstructorName ans =

'visa('tek', 'ASRL1::INSTR');' 'visa('tek', 'ASRL2::INSTR');' 'visa('tek', 'GPIB0::1::INSTR');'

Examining Your Hardware Resources

The ObjectConstructorName field provides the syntax for creating a VISA object for the GPIB and serial port interfaces. In this example, the GPIB controller has board index

vg = visa('tek','GPIB0::1::INSTR');

0 and the instrument has primary address 1.

Instrument Object Information

To display information about a specific instrument object, you supply the object as an argument to for the GPIB object created in the (“Adaptor Information” on page 1-13), type:

ghwinfo = instrhwinfo(g) ghwinfo =

AdaptorDllName: [1x82 char]

AdaptorDllVersion: 'Version 2.0 (R14)'

VendorDriverDescription: 'NI-488'

instrhwinfo. For example, to display information

AdaptorName: 'NI'

VendorDllName: 'gpib-32.dll'

To display information for the VISA-GPIB object created in the (“Adaptor Information” on page 1-13), type:

vghwinfo = instrhwinfo(vg) vghwinfo =

AdaptorDllName: [1x83 char]

AdaptorDllVersion: 'Version 2.0 (R14)'

AdaptorName: 'TEK'

VendorDllName: 'visa32.dll'

VendorDriverDescription: 'Tektronix VISA Driver'

VendorDriverVersion: 2.0500

Alternatively, you can return hardware information via the Workspace browser by right-clicking an i ns trume nt object, and selecting Display

Hardware Info from the context menu.

1-15

1 Getting Started

Installed Driver Information

To display information about a supported driver type, you supply the driver type as an argument to the IVI configuration, type:

instrhwinfo('ivi')

ans =

LogicalNames: {'MyIviCLogical' 'MyScope' 'TekScope'}

ConfigurationServerVersion: '1.3.1.0'

MasterConfigurationStore: 'D:\Apps\IVI\Data\IviConfigurationStore.xml'

IVIRootPath: 'D:\Apps\IVI\'

To display inform ation about a specific driver or resource, you supply the driver name in addition to the type as an argument to example, to display information about the

instrhwinfo('vxipnp', 'ag3325b') ans =

Manufacturer: 'Agilent Technologies'

Model: 'Agilent 3325B Synthesizer/Func. Gen.' DriverVersion: '4.1' DriverDllName: 'C:\VXIPNP\WINNT\bin\ag3325b_32.dll'

instrhwinfo. For example, to display information for

ProgramIDs: {'TekScope.TekScope'}

Modules: {'ag3325b'}

instrhwinfo.For

ag3325b VXIplug&play driver:

1-16

Test & Measurement Tool

You can use the Test & Measurement Tool (tmtool) to manage the resources of your instrument control session. You can use this tool to:

• Search for installed adaptors.

• Examine available hardware.

• Examine installed drivers.

• Examine instrument objects.

To open the Test & Measure ment Tool, type:

tmtool

Examining Your Hardware Resources

Hardware

Expand the Hardware node in the tree to list the supported interfaces.

Right-click the

Hardware node to scan for instrument hardware. The interface

nodes expand to include entries for each instrument found by the scan.

Installed Drivers

The Test & Measurement Tool can display your installed drivers. The three categories of drivers are

Drivers

,andIVI, as shown below under the expanded Instrument Drivers

node.

MATLAB Instrument Drivers, VXIplug&play

Right-click the

Instrument Drivers node to scan for installed drivers. The

driver-type nodes ex pand to include entries for each driver found by the scan. Note that for MATLAB instrument drivers and VXIplug&play drivers, the installation of a driver requires only the presence of a driver file. For IVI, installation involves an IVI configuration store; see “Viewing the IVI Configuration Store” on page 1-18.

1-17

1 Getting Started

The Test & Measurement Tool GUI includes embedded help. For further details abo ut the T est & Measurement Tool and its capabilities, see Chapter 13, “Test & Measurement Tool”.

1-18

Viewing the IVI Configuration Store

An IVI configuration store greatly enhances instrument interchangeability by providing the means to configure the relationship between drivers and I/O interface references outside of the application. For details of the components of an IVI configuration store, see “IVI Configuration Store” on page 10-16.

Command-Line Configuration

You can use command-line functions to examine and configure your IVI configuration store. To see what IVI configuration store elements are available, use

instrhwinfo('ivi') ans =

ConfigurationServerVersion: '1.3.1.0'

instrhwinfo to identify the existing logical names.

LogicalNames: {'MainScope', 'FuncGen'}

ProgramIDs: {'TekScope.TekScope','Agilent33250'}

Modules: {'ag3325b', 'hpe363xa'}

Examining Your Hardware Resources

MasterConfigurationStore: 'C:\Program Files\IVI\Data\

IviConfigurationStore.xml'

IVIRootPath: 'C:\Program Files\IVI\'

Use instrhwinfo with a logical name as an argument to see the details of that logical name’s configuration.

instrhwinfo('ivi','MainScope') ans =

DriverSession: 'TekScope.DriverSession'

HardwareAsset: 'TekScope.Hardware'

SoftwareModule: 'TekScope.Software'

IOResourceDescriptor: 'GPIB0::13::INSTR'

SupportedInstrumentModels: 'TekScope 5000, 6000 and 7000 series'

ModuleDescription: 'TekScope software module desc'

ModuleLocation: ''

You create and configure elements in the IVI configuration store by using the IVI configuration store object functions

add, commit, remove,andupdate.For

further details, see the reference pages for these functions.

Using the Test & Measurement Tool

You can use the Test & Measurement Tool to examine or configure your IVI configuration store. To open the tool, type:

tmtool

Expand the Instrument Drivers node and click IVI.

1-19

1 Getting Started

1-20

YouseeatabforeachtypeofIVIconfigurationstoreelement. This figure shows the available driver sessions in the current IVI configuration store. For the selected driver session, you can use any available software module or hardware asset. This figure shows the configuration for the driver session

TekScope.Software and the hardware asset TekScope.Hardware.

TekScope.DriverSession, which uses the software module

Communicating with Your Instrument

In this section...

“Instrument Control Session Examples” on page 1-21

“Example: Communicating with a GPIB Instrument” on page 1-21

“Example: Communicating with a GPIB-VXI Instrument” on page 1-22

“Example: Communicating with a Serial Port Instrument” on page 1-24

“Example: Communicating with a GPIB Instrument Using a Device Object” on page 1-25

Instrument Control Session Examples

Each example illustrates a typical instrument control session.The instrument control session comprises all the steps you are likely to take when communicating with a supported instrument. You should keep these steps in mind when constructing your own instrument control applications.

Communicating with Your Instrument

The examples also use specific instrument addresses, SCPI commands, and so on. If your instrument requires different parameters, or if it does not support the S CPI language, you should modify the examples accordingly.

If you want detailed information about any functions that are used, refer to Functions — By Category. If you want detailed information about any properties that are used, refer to Properties — By Category.

Example: Communicating with a GPIB Instrument

This example illustrates how to communicate with a GPIB instrument. The GPIB controller is a National Instruments AT-GPIB card. The instrument is an Agilent 33120A Function Generator, which is generating a 2 volt peak-to-peak signal.

You should modify this example to suit your specific instrument control application needs. If you want detailed information about commu n i cating with an instrument via GPIB, refer to Chapter 4, “Controlling Instruments Using GPIB”.

1-21

1 Getting Started

1 Create an interface object — Create the GPIB object g associated with a

National Instruments GPIB board with board index 0, and an instrument with primary address 1.

g = gpib('ni',0,1);

2 Connect to the instrument — Connect g to the instrument.

fopen(g)

3 Configure property values —Configureg to assert the EOI line when

thelinefeedcharacteriswrittentothe instrument, and to complete read operations when the line feed character is read from the instrument.

set(g,'EOSMode','read&write') set(g,'EOSCharCode','LF')

4 Write and read data — Change the instrument’s peak-to-peak voltage

to three volts by writing the

Volt 3 command, query the peak-to-peak

voltage value, and then read the voltage value.

1-22

fprintf(g,'Volt 3') fprintf(g,'Volt?') data = fscanf(g) data = +3.00000E+00

5 Disconnect and clean up — When you no longer need g, you should

disconnect it from the instrument, remove it from memory, and remove it from the M ATLA B workspace.

fclose(g) delete(g) clear g

Example: Communicating with a GPIB-VXI Instrument

This example illustrates how to communicate with a VXI instrument via a GPIB controller using the VISA standard provided by Agilent Technologies.

Communicating with Your Instrument

The GPIB controller is an Agilent E1406A comm and module in VXI slot

0. The instrument is an Agilent E1441A Function/Arbitrary Waveform Generator i n VXI slot 1, which is outputting a 2 volt peak-to-peak signal. The GPIB controller communicates with the instrument over the VXI backplane.

You should modify this example to suit your specific instrument control application needs. If you want detailed information about commu n i cating with an instrument using VISA, refer to Chapter 5, “Controlling Instruments Using VISA”.

1 Create an instrument object — Create the V ISA-GPIB-VXI object v

associated with the E1441A instrument located in chassis 0 with logical address 80.

v = visa('agilent','GPIB-VXI0::80::INSTR');

2 Connect to the instrument — Connect v to the instrument.

fopen(v)

3 Configure property values —Configurev to complete a read operation

when the line feed character is read from the instrument.

set(v,'EOSMode','read') set(v,'EOSCharCode','LF')

4 Write and read data — Change the instrument’s peak-to-peak voltage

to three volts by writing the

Volt 3 command, query the peak-to-peak

voltage value, and then read the voltage value.

fprintf(v,'Volt 3') fprintf(v,'Volt?') data = fscanf(v) data = +3.00000E+00

5 Disconnect and clean up — When you no longer need v, you should

disconnect it from the instrument, remove it from memory, and remove it from the M ATLA B workspace.

fclose(v) delete(v)

1-23

1 Getting Started

clear v

Example: Communicating with a Serial Port Instrument

This example illustrates how to communicate with an instrument via the serial port. The instrument is a Tek tronix TDS 210 two-channel digital oscilloscope connected to the s erial port of a PC, and configured for a baud rate of 4800 and a carriage return (CR) terminator.

You should modify this example to suit your specific instrument control application needs. If you want detailed information about commu n i cating with an instrument connected to the serial port, refer to Chapter 6, “Controlling Instruments Using the Serial Port”.

Note This example isWindows specific.

1 Create an instrument object — C reate the serial port object s associated

with the COM1 serial port.

1-24

s = serial('COM1');

2 Configure property values —Configures to match the instrument’s

baud rate and terminator.

set(s,'BaudRate',4800) set(s,'Terminator','CR')

3 Connect to the instrument — Connect s to the instrument. This step

occurs after property values are configured because serial port instruments can transfer data immediately after the connection is established.

fopen(s)

4 Write and read data — Write the *IDN? command to the instrument and

then read back the result of the command.

*IDN? queries the instrument

for identification information.

fprintf(s,'*IDN?') out = fscanf(s)

Communicating with Your Instrument

out = TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04

5 Disconnect and clean up — When you no longer need s, you should

disconnect it from the instrument, remove it from memory, and remove it from the M ATLA B workspace.

fclose(s) delete(s) clear s

Example: Communicating with a GPIB Instrument Using a Device Object

This example illustrates how to communicate with a GPIB instrument through a device object. The GPIB controller is a Keithley instrument is an Agilent 33120A Function Generator, which you set to produce a 1 volt peak-to-peak sine wave at 1,000 Hz. Device objects use instrument drivers; this example uses the driver

agilent_33120a.mdd.

card, and the

You should modify this example to suit your specific instrument control application needs. If you want detailed information about commu n i cating through device objects, see Chapter 8, “Using Device Objects”.

1 Create instrument objects — Create the GPIB object g associated with a

Keithley GPIB board with board index 0, and an instrument with primary address 4. Then create the device object object

g, a nd with the instrument driver agilent_33120a.mdd.

g = gpib('keithley',0,4); d = icdevice('agilent_33120a.mdd',g);

2 Connect to the instrument — Connect d to the instrument.

connect(d)

3 Call device object method —Usethedevicereset method to set the

d associated with the interface

generator to a known configuration. The behavior of the generator for this method is defined in the instrument driver.

devicereset(d)

1-25

1 Getting Started

4 Configure property values —Configured to set the amplitude and

frequency for the signal from the function generator.

set(d,'Amplitude',1.00,'AmplitudeUnits','vpp') set(d,'Frequency',1000)

5 Disconnect and clean up — When you no longer need d and g,you

should disconnect from the instrument, remove the objects from memory, and remove them from the MATLAB workspace.

disconnect(d) delete([d g]) clear d g

1-26

General Preferences for Instrument Control

In this section...

“Accessing General Preferences” on page 1-27

“MATLAB Instrument Driver Editor” on page 1-28

“MATLAB Instrument Driver Testing Tool” on p age 1-28

“Device Objects” on page 1-29

“IVI Configuration Store” on page 1-30

Accessing General Preferences

You access the general preferences from your MATLAB Command Window by selecting File > Preferences. The Preferences dialog box opens. There are two options listed for Instrument Control. Under the

Confirmation Dialogs in the tree.

General node, select

1-27

1 Getting Started

MATLAB Instrume

The first option Driver Editor (

When the option selected, if y adriverfilet a new driver fi

For example,

midedit ('newdriver')

generates the prompt

If you select Donotshowthispromptagain, the corresponding check box in the Preferences dialog box is cleared, in which case the MATLAB Instrument Driver Editor creates new driver files without prompting. To reactivate the prompt, select the option on the Preferences dialog box.

for Instrument Control is related to the MATLAB Instrument

idedit

Prompt when editing drivers that do not exist is

ou open the MATLA B Instrument Driv er Editor w hile specifying

hat does not ex ist, you g et a prompt asking if you wa nt to create

le.

the command

nt Driver Editor

1-28

MATLAB Instrument Driver Testing Tool

The second option for Instrument Control is related to the MATLAB Instrument Driver Testing Tool (

When the option Prompt when editing driver tests that do not exist is selected, if you open the MATLAB Instrument Driver Testing Tool while specifying a driver test file that does not exist, you get a prompt asking if you want to create a new test file.

For example, the command

midtest ('newtest')

midtest).

General Preferences for Instrument Control

generates the prompt

If you select Do not show this prompt again, the corresponding check box in the Preferences dialog box is cleared, in which case the MATLAB Instrument Driver Testing Tool create s new driver test files w ithout prompting. To reactivate the prompt, check the option on the Preferences dialog box.

Device Objects

You access other Instrument Control Preferences by selecting the

Instrument Control node in the tree.

The Device Objects section of the dialog box contains preferences related to theconstructionanduseofdeviceobjectsforVXIplug&play and IVI-C drivers.

1-29

1 Getting Started

Here you set the minimum number of properties and functions required to create a device object group, and the default size of character arrays passed as output arguments to device object functions.

Set the default size for these character arrays in the Preferences dialog box to ensure that they are large enough to accommodateanystringreturnedto them by any device object functions. You can reduce the default character array size to avoid unnecessary memory usage, as long as they are still large enough to accommodate any expected strings.

IVI Configuration Store

The IVI Configuration Store section of the dialog box contains preferences related to the construction and use of IVI configuration store objects when you are working in the Command Window or in the Test & Measurement Tool (

tmtool).

You can select either a master configuration store or a user-defined configuration store. If you choose a user-defined configuration store, you must provide its file name.

1-30

Getting Help

In this section...

“instrhelp Function” on page 1-31

“propinfo Function” on page 1-32

“instrsupport Function” on page 1-33

“Online Support” on page 1-33

instrhelp Function

You can use the instrhelp function to:

• Display command-line h elp for functions and properties.

• List all the functions and properties associated with a specific instrument

object.

An instrument object is not only for you to obtain this information. For example, to display all functions and properties associated with a GPIB object, as well as the constructor help, type:

instrhelp gpib

To display help for the EOIMode property, type:

instrhelp EOIMode

You can also display help for an existi ng instrument object. For example, to display help for the object, type:

v = visa('agilent','GPIB-VXI0::80::INSTR'); out = instrhelp(v,'MemorySpace');

Alternatively, you can display help via the Workspace browser by right-clicking an instrument object and selecting Instrument Help from the context menu.

MemorySpace property associated with a VISA-GPIB-VXI

1-31

1 Getting Started

propinfo Function

You can use the propinfo function to return the characteristics of the Instrument Control Toolbox properties. For example, you can find the default value for any property using this function. containing the following fields:

Field Name Description

Type

Constraint

ConstraintValue

The property data type. Possible values are any,

ASCII value, callback, double, string,andstruct.

The type of constraint on the property value. Po ssible values are and

ASCII value, bounded, callback, enum,

none.

The property value constraint. T h e constraint can be a rang e of values or a list of string values.

DefaultValue

ReadOnly

The property default value.

The condition under which a property is read only. Possible values are

whileRecording.

InterfaceSpecific

If the property is interface-specific, a 1 is returned. If the property is supported for all interfaces, a returned.

propinfo returns a structure

always, never, whileOpen,and

0 is

1-32

For example, to display the property characteristics for the EOIMode property associated with the GPIB object

g = gpib('ni',0,2); EOIinfo = propinfo(g,'EOIMode')

EOIinfo =

Type: 'string'

Constraint: 'enum'

ConstraintValue: {2x1 cell}

DefaultValue: 'on'

ReadOnly: 'never'

InterfaceSpecific: 1

This information tells you the following:

• The property value data type is a string.

• The property value is constrained as an enumerated list of values.

• There are two possible property values.

Getting Help

• The default value is

• The property c an b e configured at any time (it is never read-on ly).

• The property is not supported for all interfaces.

To display the property value constraints,

EOIinfo.ConstraintValue ans =

'on' 'off'

on.

instrsupport Function

Execute this function to get diagnostic information for all installed hardware adaptors on your system. The information is stored in a text file,

instrsupport.txt in your current folder and you can use this information

to troubleshoot issues.

Online Support

For online support of Instrument Control Toolbox software, visit the Web site

http://www.mathworks.com/support/product/IC/. This site includes

documentation, examples, solutions, downloads, system requirements, and contact information.

1-33

1 Getting Started

1-34

Instrument Control Session

The instrument control session consists o f the steps you are likely to take when comm unicating with your instrument. This chapter highlights some of the differences between interface objects and device objects for each of these steps, to help you decide which to use in communicating with your instrument. Whether you use interface objects or device objects, the basic steps of the instrument control session remain the same, as outlined in this chapter.

• “Creating Instrument Objects” on page 2-2

• “Connecting to the Instrument” on page 2-4

• “Configuring and Returning Properties” on page 2-5

• “Communicating with Your Instrument” on page 2-7

• “Disconnecting and Cleaning Up” on page 2-8

• “Summary” on page 2-9

2 Instrument Control Session

Creating Instrument Objects

In this section...

“Overview” on page 2-2

“Interface Objects” on page 2-2

“Device Objects” on page 2-3

Overview

Instrument objects are the toolbox components you use to access your instrument. They provide a gateway to the functionality of your instrument and allow you to control the behavior of your application. The Instrument Control Toolbox software supports two types of instrument o bjects:

• Interface objects — Interface objects are associated with a specific interface

standard such as GP IB or VISA. They allow you to communicate with any instrument connected to the interface.

2-2

• Device objects — Device objects are associated with a MATLAB instrument

driver. They allow you to communicate with your instrument using properties and functions defined in the driver for a specific instrument model.

Interface Objects

An interface object represents a channel of communication. For example, an interface object might represent a device at address 4 on the GPIB, even though there is nothing specific about what kind of instrument this may be.

To create an instrument object, you call the constructor for the type of interface ( interface i nformation, such as address for GPIB, remote host for TCP/IP, or port number for serial.

For detailed information on interface objects and how to create and use them, see Chapter 3, “Using Interface Objects”.

gpib, serial, tcpip, udp,orvisa), and provide appropriate

Device Objects

A device object r of that represen driver.

epresents an instrument rather than an interface. As part

tation, a device object must also be aware of the instrument

Creating Instrument Objects

You create a de a MA TLAB instr canbeaninter an IVI config

For detailed see Chapter

uration.

information on device objects and how to create and use them, 8, “Using Device Objects”.

vice object with the

ument driver and some form of instrument interface, which

face object, a VISA resource name, or an interface implied in

icdevice function. A device object requires

2-3

2 Instrument Control Session

Connecting to the Instrument

Before you can use an instrument object to write or read data, you must connect it to the instrument. You connect a n interface object to the instrument with the the

fopen function; you connect a device object to the instrument with

connect function.

You can examine the connected to the instrument.

obj.Status ans = open

Some properties of the object are read-only while the object is connected and must be configured before connecting. Examples of interface object properties that are read-only when the object is connected include

OutputBufferSize. You can determine w hen a property is configurable with

the

propinfo function or by referring to Properties — Alphabetical L ist .

Status property to verify that the instrument object is

InputBufferSize and

2-4

Configuring and Returning Properties

In this section...

“Configuring Property Names and Property Values” on page 2-5

“Returning Property Names and Property Values” on page 2-5

“Property Inspector” on page 2-6

Configuring Property Names and Property Values

You e stablish the des ired instrument object behavior by configu ring property values. You can configure property values using the notation, or by specifying property name/property value pairs during object creation. You can return property values using the notation.

Interface objects possess two types of properties: base properties and interface-specific properties. (These properties pertain only to the interface object itself and to the interface, not to the instrument.) Base properties are supported for all interface objects (serial port, GPIB, VISA-VXI, and so on), while interface-specific properties are supported only for objects of a given interface type. For example, the serial port and VISA-serial objects.

BaudRate property is supported only for

Configuring and Returning Properties

set function or the dot

get function or the dot

Device objects also possess two types of properties: base properties and device-specific properties. While device objects possess base properties

pertaining to the object and interface, they also po sses s any number of device-specific properties as defined in the instrument driver for configuring the instrument. For example, a device object representing an oscilloscope might posses such properties as

MeasurementMode. When you set these properties you are directly configuring

the oscilloscope settings.

DisplayContrast, InputRange,and

Returning Property Names and Property Values

Once the instrument object is created, you can use the set function to return all its configurable properties to a v aria ble or to the command line. Additionally, if a property has a finite set of string values, values.

set returns these

2-5

2 Instrument Control Session

Property Inspector

The Property Inspector enables you to inspect and set properties for one or more instrument objects. It provides a list of all properties and displays their current values.

Settable properties in the list are associated with an editing device that is appropriate for the values accepted by the particular property. For example, a callback configuration GUI to set set

RecordMode, and a text field to specify the TimerPeriod.Thevaluesfor

read-only properties are grayed out.

ErrorFcn, a pop-up menu to

YouopenthePropertyInspectorwiththe can open the Property Inspector via the Workspace browser by right-clicking an instrument object and selecting Call Property Inspector from the context menu, or by double-clicking the object.

inspect function. Alternatively, you

2-6

Communicating with Your Instrument

In this section...

“Interface Objects and Instrum ent Commands” on page 2-7

“Device O bjects and Instrument Drivers” on p age 2-7

Interface Objects and Instrument Commands

Communicating with your instrument invo lves sending and receiving commands, settings, responses, and data. The level of communication depends on the type of instrument object you use.

To communicate through the interface object, you need to send instrument commands, and you receive information as the instrument sends it. Therefore, you have to know the syntax specific to the instrument itself. For example, if the instrument requires the command is exactly the command that must be sent to the interface object.

'*RST' to initiate its action, then that

Communicating with Your Instrument

Text commands and binary data are sent directly to the instrument and received from the instrument with such functions as

fread, and others.

fprintf, fwrite, fgets,

Device Objects and Instrument Drivers

To communicate through a device object, you access obje ct properties with the

set and get commands, and you execute driver functions with the invoke

command. The invoke command for a device object employs methods and arguments defined by the instrument driver. So using device objects does not require you to use instrument-specific commands and syntax.

For information on creating, editing, and importing instrument drivers, see Chapter 14, “Using the Instrument Driver Editor”.

2-7

2 Instrument Control Session

Disconnecting and Cleaning Up

In this section...

“Disconnecting an Instrument Object” on page 2-8

“Cleaning Up the MATLAB Workspace” o n page 2-8

Disconnecting an Instrument Object

When you no longer need to communicate with the instrument, you should disconnect the object. I nterface objects are disconnected with the function; device objects are disconnected with the disconnect function.

fclose

You can examine the from the instrument.

obj.Status ans = closed

Status property to verify that the object is disconnected

Cleaning Up the MATLAB Workspace

When you no longer need the instrument object, you should remove it from memory with the

delete(obj)

A deleted instrument object is invalid, which means that you cannot connect it to the instrument. In this case, you should remove the object from the MATLAB workspace. To remove instrument objects and other variables from the MATLAB workspace, use the

clear obj

If you use clear on an object that is connected to an instrument, the object is removed from the workspace but remains connected to the instrument. You can restore cleared instrument objects to the MATLAB workspace with the

instrfind function.

delete function.

clear command.

2-8

Summary

In this section...

“Advantages of Using Device Objects” on page 2-9

“When to Use Interface Objects” on page 2-9

Advantages of Using Device Objects

Should you use interface o bj ects or device objects to communicate with your instrument? Generally, device objects make instrument control easier and they offer greater flexibility to the user compared to using interface objects.

Because of the advantages offered by using device objects for communicating with y our instrument, you should use device objects whenever possible. Some of these advantages are

• You do not need to know instrument-specific co mmands

• You can use standard VXIplug&play or IVI instrument drivers provided by

your instrument vendor or other party

• You can use a MATL AB instrument driver to control your instrument. To

get a MATLAB instrument d river, you can

- Convert a VXIplug&play or IVI driver

- Use a MATLAB driver that is shipped with the toolbox

- Create it yourself or modify a similar driver

- Install it from a third party, such as MATLAB Central

You can create, convert, or customize a MATLAB instrument driver with the MATLAB Instrument Driver Editor tool (

When to Use Interface Objects

In some circumstances, using device objects to communicate with your instrument would be impossible or impractical. You might need to use interface objects if

midedit).

2-9

2 Instrument Control Session

• Your instrument does not have a standard instrument driver supported by

the Instrument Control Toolbox software.

• You are using a streaming application (typically serial, UDP, or TCP/IP

interface) to notify you of some occurrence.

• Your application requires frequent changes to communication channel

settings.

2-10

Using Interface Objects

The instrument control session using interface objects consists of all the steps described in the following sections.

• “Creating an Interface Object” on page 3-2

• “Connecting to the Instrument” on page 3-5

• “Configuring and Returning Properties” on page 3-6

• “Writing and Reading Data” on page 3-12

• “Disconnecting and Cleaning Up” o n page 3-24

3 Using Interface Objects

Creating an Interface Object

In this section...

“Object Creation Functions” on page 3-2

“Configuring Propertie s During Object Creation” on page 3-3

“Creating an Array of Instrument Objects” on page 3-3

Object Creation Functions

To create an interface object, you call functions called object creation functions (or object constructors). Thes e fil es ar e implemented using MATLA B object-oriented programming capabilities, which are described in MATLAB Classes in the MATLAB documentation.

Interface Object Creation Functions

Constructor Description

gpib

serial

tcpip

udp

visa

Create a GPIB object.

Create a serial port object.

Create a T CPIP object.

Create a UDP object.

Create a VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, or VISA-serial object.

3-2

You can find out how to create an interface object for a particular interface and adaptor with the function. For example, to find out how to create a GPIB object for a National Instruments GPIB controller,

out = instrhwinfo('gpib','ni'); out.ObjectConstructorName ans =

'gpib('ni', 0, 1);'

ObjectConstructorName field of the instrhwinfo

Creating an Interface Object

Configuring Properties During Object Creation

Instrument objects contain properties that reflect the functionality of your instrument. You control the behavior of your instrument control application by configuring values for these properties.

As described in “Configuring and Returning Properties” on page 3-6, you configure properties using the

set function or the dot notation. You can

also configure properties during object creation by specifying property name/property value pairs. For example, the following command configures the

EOSMode and EOSCharCode properties for the GPIB object g:

g = gpib('ni',0,1,'EOSMode','read','EOSCharCode','CR');

If you specify an invalid property name or property value, the object is not created. For detailed property descriptions, refer to Properties — Alphabetical List .

Creating an Array of Instrument Objects

In the MATLAB workspace, you can create an array from existing variables by concatenating those variables. The same is true for instrument objects. For example, suppose you create the GPIB objects

g1 and g2:

g1 = gpib('ni',0,1); g2 = gpib('ni',0,2);

You can now create an instrument object array consisting of g1 and g2 using the usual MATLAB syntax. To create the row array

x=[g1g2] Instrument Object Array

Index: Type: Status: Name: 1 gpib closed GPIB0-1 2 gpib closed GPIB0-2

To create the column array y:

y = [g1;g2];

3-3

3 Using Interface Objects

Note that you cannot create a matrix of instrument objects. For example, you cannot create the matrix

z = [g1 g2;g1 g2]; ??? Error using ==> gpib/vertcat Only a row or column vector of instrument objects can be created.

Depending on your a pplication, you mightwanttopassanarrayofinstrument objects to a function. For example, using one call to the configure b oth

set(x,'EOSMode','read')

g1 and g2 to the same property value.

set function, you can

Refer to Functions — Alphabetical List to see which functions accept an instrument object array as an input argument.

3-4

Connecting to the Instrument

Before you can use the instrument object to write or read data, you must connect it to the instrument whose address or port is specified in the creation function. You connect an interface object to the instrument with the function.

fopen(g)

Some properties are read-only while the object is connected and mus t be configured before using the

OutputBufferSize properties. You can determine when a property is

configurable with the Alphabetical List .

Note You can create any number of instrument objects. However, at any time, you can connect only one instrument object to an instrument with a given address or port.

fopen.ExamplesincludetheInputBufferSize and

propinfo function, or by referring to Properties —

Connecting to the Instrument

fopen

You can examine the Status property to verify that the instrument object is connected to the instrument.

g.Status ans = open

As illustrated below, the connection between the instrument object and the instrument is comp lete, and you can write and read data.

3-5

3 Using Interface Objects

Configuring and Returning Properties

In this section...

“Base and Interface-Specific Properties” on page 3-6

“Returning Property Names and Property Values” on page 3-6

“Configuring Property Values” on page 3-9

“Specifying Property Names” on page 3-10

“Default Property Values” on page 3-10

“Property Inspector” on page 3-11

Base and Inter face-Specific Properties

set function or the dot

get function or the dot

3-6

Interface objects possess two types of properties:

• Base Properties: These are supported for all interface objects (se r ial port,

GPIB, VISA-VXI, and so on). For example, the supported for all interface objects.

• Interface-Specific Properties: These are supported only for objects of a given

interface type. For example, the serial port and VISA-serial objects.

BaudRate property is supported only for

BytesToOutput property is

Returning Property Names and Property Values

Once the instrument object is created, you can use the set function to return all configurable properties to a variable or to the command line. Additionally, if a property has a finite set of string values, then values.

set also returns these

Configuring and Returning Properties

For example, the configurable properties for the GPIB object g are shown below. The base properties are listed first, followed by the GP I B- specific properties.

g = gpib('ni',0,1); set(g)

ByteOrder: [ {littleEndian} | bigEndian ] BytesAvailableFcn BytesAvailableFcnCount BytesAvailableFcnMode: [ {eosCharCode} | byte ] ErrorFcn InputBufferSize Name OutputBufferSize OutputEmptyFcn RecordDetail: [ {compact} | verbose ] RecordMode: [ {overwrite} | append | index ] RecordName Tag Timeout TimerFcn TimerPeriod UserData

GPIB specific properties: BoardIndex CompareBits EOIMode: [ {on} | off ] EOSCharCode EOSMode: [ {none} | read | write | read&write ] PrimaryAddress SecondaryAddress

You can use the get function to return one or more properties and their current values to a variable or to the command line.

For example, all the properties and their current values for the GPIB object

g are shown below . The base properties are listed first, followed by the

GPIB-specific properties.

get(g)

3-7

3 Using Interface Objects

ByteOrder = littleEndian BytesAvailable = 0 BytesAvailableFcn = BytesAvailableFcnCount = 48 BytesAvailableFcnMode = eosCharCode BytesToOutput = 0 ErrorFcn = InputBufferSize = 512 Name = GPIB0-1 OutputBufferSize = 512 OutputEmptyFcn = RecordDetail = compact RecordMode = overwrite RecordName = record.txt RecordStatus = off Status = closed Tag = Timeout = 10 TimerFcn = TimerPeriod = 1 TransferStatus = idle Type = gpib UserData = [] ValuesReceived = 0 ValuesSent = 0

3-8

GPIB specific properties: BoardIndex = 0 BusManagementStatus = [1x1 struct] CompareBits = 8 EOIMode = on EOSCharCode = LF EOSMode = none HandshakeStatus = [1x1 struct] PrimaryAddress = 1 SecondaryAddress = 0

To display the current value for one property, you supply the property name to

get.

Configuring and Returning Properties

get(g,'OutputBufferSize') ans =

512

To display the current values for multiple properties, you include the property names as elements of a cell array.

get(g,{'BoardIndex','TransferStatus'}) ans =

[0] 'idle'

You can also use the dot notation to display a single property value.

g.PrimaryAddress ans =

Configuring Property Values

You can configure property values using the set function

set(g,'EOSMode','read')

or the dot notation.

g.EOSMode = 'read';

To configure values for multiple p r operties, you can supply multiple property name/property value pairs to

set(g,'EOSCharCode','CR','Name','Test1-gpib')

set.

Note that you can configure only one property value at a time using the dot notation.

In practice, you can configure many of the properties at any time while the instrument object exists — including during object creation. However, some properties are not configurable while the object is connected to the instrument or when recording information to disk. Use the

propinfo function, or refer

to Properties — Alphabetical List to understand when you can configure a property.

3-9

3 Using Interface Objects

Specifying Property Names

Instrument object property names are presentedusingmixedcase.Whilethis makes property names easier to read, you can use any case y ou want when specifying property names. Additionally, you need use only enough letters to identify the property name uniquely, so you can abbreviate most property names. For example, you can configure the ways.

set(g,'EOSMode','read') set(g,'eosmode','read') set(g,'EOSM','read')

However, when you include property names in a file, you should use the full property name. T his practice can prevent problems with future releases of the Instrument Control Toolbox software if a shortened name is no longer unique because of the addition of new properties.

EOSMode property in any of these

Default Property Values

If you do not explicitly define a value for a property, then the default value is used. All configurable properties have default values.

3-10

Note Default values are provided for all instrument object properties. For serial port objects, the default values are provided by your operating system. For GPIB and VISA instrument objects, the default values are provided by vendor-supplied tools. However, these settings are overridden by your MATLAB code, and will have no effect on your instrument control application.

If a property has a finite set of string values, then the default value is enclosed by property is none.

set(g,'EOSMode') [ {none} | read | write | read&write ]

You can also use the propinfo function, or refer to Functions — Alphabetical List to find the default value fo r any property.

{} (curly braces). For example, the default value for the EOSMode

Configuring and Returning Properties

Property Inspector

The Property Inspector enables you to inspect and set properties for one or more instrument objects. It provides a list of all properties and displays their current values.

Settable properties in the list are associated with an editing device that is appropriate for the values accepted by the particular property. For example, a callback configuration GUI to set set

RecordMode, and a text field to specify the TimerPeriod.Thevaluesfor

read-only properties are grayed out.

ErrorFcn, a pop-up menu to

inspect function. Alternatively, you

3-11

3 Using Interface Objects

Writing and Reading Data

In this section...

“Before Performing Read/Write Operations” on page 3-12

“Writing Data” on page 3-13

“Reading Data” on page 3-19

Before Performing Read/Write Operations

Communicating with your instrument involves writing and reading data. For example, you might write a text command to a function generator that queries its peak-to-peak voltage, and then read back the voltage value as a double-precision array.

Before performing a write or read operation, you should consider these three questions:

3-12

• What is the process by which data flows from the MATLAB w orkspace to

the instrument, and from the instrument to the MATLAB workspace?

The Instrument Control Toolbox automatically manages the data transferred between the MATLAB workspace and the instrument. For many common applications, you can ignore the buffering and data flow process. However, if you are transferring a large number of values, executing an asynchronous read or write operation, or debugging your application, you might need to be aware of how this process works.

• Isthedatatobetransferredbinary(numerical)ortext(ASCII)?

For many instruments, writing text data means writing string commands that change instrument settings, prepare the instrument to return data or status information, and so on. Writing binary data means writing numerical values to the instrument such as calibration or waveform data.

• Will the

Window?

You control access to the MATLAB Command Window by specifying whether a read or write operation is synchronous or asynchronous.A synchronous operation blocks acces s to the command line until the read or

write or read function block access to the MATLAB Command

Writing and Reading Data

write function completes execution. An asynchronous operation does not block access to the command, and you can issue additional commands while the

read or write function executes in the background.

There are other issues to consider when you read and write data, like the conditions under which a read or write operation completes. These issues vary depending upon the supported interface and are described in the respective interface-specific chapters.

Writing Data

Functions Associated with Writing Data

Function Name Description

binblockwrite

fprintf

fwrite

stopasync

Write b inblock data to the instrument.

Writetexttotheinstrument.

Write binary data to the instrument.

Stop as ynchronous read and write operations.

Properties Associated with Writing Data

Property Name Description

BytesToOutput

Indicate the number of bytes currently in the output buffer.

OutputBufferSize

Timeout

Specify the size of the output buffer in bytes.

Specify the waiting time to complete a read or write operation.

TransferStatus

Indicate if an asynchronous read or write operation is in progress.

ValuesSent

Indicate the total number of values written to the instrument.

3-13

3 Using Interface Objects

Output Buffer and Data Flow

The output buffer is computer memory allocated by the instrument object to store data that is to be written to the instrument. The flow of data from the MATLAB workspace to your instrument follows these steps:

1 The data specified by the write function is sent to the output buffer.

2 The data in the output buffer is sent to the instrument.

The

OutputBufferSize property specifies the maximum number of bytes that

you can store in the output buffer. The the number of bytes currently in the output buffer. The default values for these properties are:

g = gpib('ni',0,1); get(g,{'OutputBufferSize','BytesToOutput'}) ans =

[512] [0]

BytesToOutput property indicates

3-14

If you attempt to write more data than can fit in the output buffer, an error is returned and no data i s written.

Note When writing data, you might need to specify a value, which can consist of one or more bytes. This is because some write functions allow you to control the number of bits written for each value and the interpretation of those bits as character, integer or floating-point values. For example, if you write one value from an instrument using the

int32 format, then that value consists

of four bytes.

For example, suppose you write the string command *IDN? to an instrument using the

fprintf function. As shown below, the string is first written to the

output buffer as six values.

Writing and Reading Data

The *IDN? command consists of six values because the End-Of-String character is w ritten to the instrument, as specified by the

EOSCharCode properties. Moreover, the default data format for the fprintf

EOSMode and

function specifies that one value corresponds to one byte.

As shown below, after the string is stored in the output buffer, it is then written to the instrument.

Example: Writing Text Data Versus Writing Binary Data

For many instruments, writing text data means writing string commands that change instrument settings, prep are the instrument to return data or status information, and so on. Writing binary data means writing numerica l values to the instrument such as calibration or waveform data.

3-15

3 Using Interface Objects

You can write text data with the fprintf function. By default, fprintf uses the %s\n format, which formats the data as a string and includes the terminator. You can write binary data with the

fwrite writes data using the uchar precision, which translates the data

fwrite function. By default,

as unsigned 8-bit characters. Both of these functions support many other formats and precisions, as described in their reference pages.

The following example illustrates writing text data and binary data to a Tektronix TDS 210 oscilloscope. The text data consists of string commands, while the binary data is a waveform that is to be downloaded to the scope and stored in its memory:

1 Create an instrument object — Create the GPIB object g associated

with a National Instruments GPIB controller with board index 0, and an instrument with primary address 1. The size of the output buffer is increased to accommodate the waveform data. You must configure the

OutputBufferSize property while the GPIB object is disconnected from

the instrument.

g = gpib('ni',0,1); g.OutputBufferSize = 3000;

3-16

2 Connect to the instrument — Connect g to the instrument.

fopen(g)

3 Write and read data — Write string commands that configure the scope

to store binary waveform data in memory location A.

fprintf(g,'DATA:DESTINATION REFA'); fprintf(g,'DATA:ENCDG SRPbinary'); fprintf(g,'DATA:WIDTH 1'); fprintf(g,'DATA:START 1');

Create the waveform data.

t = linspace(0,25,2500); data = round(sin(t)*90 + 127);

Write the binary waveform data to the scope.

cmd = double('CURVE #42500');

Writing and Reading Data

fwrite(g,[cmd data]);

The ValuesSent property indicates the total number of v alu es that were written to the instrument.

g.ValuesSent ans =

2577

4 Disconnect and clean up — When you no longer need g, you should

disconnect it from the instrument, remove it from memory, and remove it from the M ATLA B workspace.

fclose(g) delete(g) clear g

Synchronous Versus Asynchronous Write Operations

By default, all write functions operate synchronously and block the MATLAB Command Window until the operation completes. To perform an asynchronous w rite operation, you supply the

fprintf or fwrite function.

async input argumen t to the

For example, you use the following syntax to modify the

fprintf commands

used in the preceding example to write text data asynchronously.

fprintf(g,'DATA:DESTINATION REFA','async');

Similarly, you use the following syntax to modify the fwrite command used in the preceding example to write binary data asynchronously.

fwrite(g,[cmd data],'async');

You can monitor the status of the asynchronous write operation with the

TransferStatus property. A value of idle indicates that no asynchronous

operations are in progress.

g.TransferStatus ans = write

3-17

3 Using Interface Objects

You can use the BytesToOutput property to indicate the numbers of bytes that exist in the output buffer waiting to be written to the instrument.

g.BytesToOutput ans =

2512

3-18

Reading Data

Writing and Reading Data

Functions Assoc

iated with Reading Data

Function Name Description

binblockread

fgetl

Read binblock data from the instrument.

Readonelineoftextfromtheinstrumentand discard the terminator.

fgets

Readonelineoftextfromtheinstrumentand include the terminator.

fread

fscanf

readasync

scanstr

Read binary data from the instrument.

Read data from the instrument, and format as text.

Read data asynchronously from the instrument.

Read data from the instrument, format as text, and parse

stopasync

Stop asynchronous read and write operations.

Properties Associated with Reading Data

Prope

Byte

Inp

Rea

ValuesReceived

rty Name

sAvailable

utBufferSize

dAsyncMode

imeout

ransferStatus

iption

Descr

cate the number of bytes available in the input

Indi

er.

buff

cifythesizeoftheinputbufferinbytes.

Spe

cify whether an asynchronous read is

Spe

tinuous or manual (serial port, TCPIP, UDP,

con

d VISA-serial objects only).

ecifythewaitingtimetocompleteareadorwrite

peration.

ndicate if an asynchronous read or write operation

sinprogress.

Indicate the total number of values read from the instrument.

3-19

3 Using Interface Objects

Input Buffer and Data Flow

The input buffer is computer memory allocated by the instrument object to store data that is to be read from the instrument. The flow of data from your instrument to the MATLAB workspace follows these steps:

1 The dat a read from the instrument is stored in the input buffer.

2 The data in the input buffer is returned to the MATLAB variable specified

by a read function.

The

InputBufferSize property specifies the maximum number of bytes that

you can store in the input buffer. The number of bytes currently available tobereadfromtheinputbuffer. The default values for these properties are:

g = gpib('ni',0,1); get(g,{'InputBufferSize','BytesAvailable'}) ans =

[512] [0]

BytesAvailable property indicates the

3-20

If you attempt to read more data than can fit in the input buffer, an error is returned and no data is read.

For example, suppose you use the response of the

*IDN? command previously written to the instrument. The

fscanf function to read the text-based

data is first read into the input buffer.

Note that for a given read operation, you might not know the number of bytes returned by the instrument. Therefore, you might need to preset the

Writing and Reading Data

InputBufferSize property to a sufficiently large value before connecting

the instrument object.

As shown below, after the data is stored in the input buffer, it is then transferred to the output variable specified by

fscanf.

Example:

Reading Text Data Versus Reading Binary Data

For many instruments, reading text data means reading string data that reflect instrument settings, status information, and so on. Reading binary data means reading numerical values from the instrument.

You can read text data with the default, these functions return data using the data with the

fread function. By default, fread returns numerical values as

double-precision arrays. Both the

fgetl, fgets,andfscanf functions. By

%c format. You can read binary

fscanf and fread functions support many

other formats and precis ions, as described in their reference pages.

The following example illustrates reading text data and binary data from a Tektronix TDS 210 oscilloscope, which is displaying a periodic input signal with a nominal frequency of 1.0 kHz.

1 Crea

2 Co

te an instrument object — Create the GPIB object

a National Instruments GPIB controller with board index 0, and an

with

trument with primary address 1.

ins

g = gpib('ni',0,1);

nnect to the instrument — Connect

g to the instrument.

g associated

3-21

3 Using Interface Objects

fopen(g)

3 Write and read data —Writethe*IDN? command to the scope, and read

back the identification information as text.

fprintf(g,'*IDN?') idn = fscanf(g) idn = TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04

Configure the scope to return the period of the input signal, and then read the period as a binary value. The output display format is configured to use short exponential notation for doubles.

fprintf(g,'MEASUREMENT:MEAS1:TYPE PERIOD') fprintf(g,'MEASUREMENT:MEAS1:VALUE?') format short e period = fread(g,9)' period =

49 46 48 48 54 69 45 51 10

3-22

period

consists of positive integers representing character codes, where 10

isalinefeed. Toconverttheperiodvaluetoastring,usethechar function.

char(period) ans =

1.006E-3

The ValuesReceived property indicates the total number of values that were read from the instrument.

g.ValuesReceived ans =

4 Disconnect and clean up — When you no longer need g, you should

disconnect it from the instrument, remove it from memory, and remove it from the M ATLA B workspace.

fclose(g) delete(g) clear g

Writing and Reading Data

SynchronousVersusAsynchronousReadOperations

The fgetl, fgets, fscanf,andfread functions operate synchronously and block the MATLAB Command Window until the operation completes. To perform an asynchronous read operation, you use the

readasync asynchronously reads data from the instrument and stores it in

the input buffer. To transfer the data from the input buffer to a MATLAB variable, you use one of the synchronous read functions.

Note For serial port, TCPIP, UDP, and VISA-serial objects, you can also perform an asynchronous read operation by configuring the property to continuous.

For example, to modify the preceding example to asynchronously read the scope’s identification information, you would issue the after the

*IDN? command is written.

fprintf(g,'*IDN?') readasync(g)

readasync function.

ReadAsyncMode

readasync function

You can mo nitor the status of the asynchronous read operation with the

TransferStatus property. A value of idle indicates that no asynchronous

operations are in progress.

g.TransferStatus ans = read

You can use the BytesAvailable property to indicate the number of bytes that exist in the input buffer waiting to be transferred to the MATLAB workspace.

g.BytesAvailable ans =

When the read completes, you can transfer the data as text to a MATLAB variable using the

idn = fscanf(g);

fscanf function.

3-23

3 Using Interface Objects

Disconnecting and Cleaning Up

In this section...

“Disconnecting an Instrument Object” on page 3-24

“Cleaning Up the MATLAB Workspace” on page 3-24

Disconnecting an Instrument Object

When you no longer need an instrument object, you should disconnect it from the instrument, and clean up the MATLAB workspace by removing the object from memory and from the workspace.

To disconnect your communication with the instrument, use the function.

fclose(g)

You can examine the Status property to verify that the object and the instrument are d isconnected.

g.Status ans = closed

After fclose is issued, the resources associated with g aremadeavailable, and you can once again connect an instrument object to the instrument with

fopen.

fclose

Cleaning Up the MATLAB Workspace

To remove the instrument object from memory, use the delete function.

delete(g)

clear command.

3-24

clear g

Disconnecting and Cleaning Up

instrfind function.

3-25

3 Using Interface Objects

3-26

Controlling Instruments Using GPIB

This chapter describes specific issues related to controlling instru ments that use the GPIB interface.

• “GPIB Overview” on page 4-2

• “Creating a GPIB Object” on page 4-14

• “Configuring the GPIB Address” on page 4-17

• “Writing and Reading Data” on page 4-18

• “Events and Callbacks” on page 4-27

• “Triggers” on page 4-35

• “Serial Polls” on page 4-38

4 Controlling Instruments Using GPIB

GPIB Overview

In this section...

“WhatIsGPIB?”onpage4-2

“Important GPIB Features” on page 4-3

“GPIB Lines” on page 4-4

“Status and Event Reporting” on page 4-8

What Is GPIB?

GPIB is a standardized interface that allows you to connect and control multiple devices from various vendor s. GPIB is also referred to by its original name HP-IB, or by its IEEE designation IEEE-488. The GPIB functionality has evolved over time, and is described in several specifications:

• The IEEE 488.1-1975 specification defines the electrical and mechanical

characteristics of the interface and its basic functional characteristics.

4-2

• The IEEE-488.2-1987 specification builds on the IEEE 488.1 specification to

define an acceptable minimum configuration and a basic set of instrument commands and common data formats.

• The Standard Commands for Programmable Instrumentation (SCPI)

specification builds on the commands given by the IEEE 488.2 specification to define a standard instrument command set that can be used by GPIB or other interfaces.

For many GPIB applications, you can communicate with your instrument without detailed knowledge of how GPIB works. Communication is established through a GPIB object, which you create in the MATLAB workspace.

If your application is straightforward, or if you are already familiar with the topics mentioned above, you might want to begin with “Creating a GPIB Object” on page 4-14. If you want a high-level description of all the steps you are likely to take when communicating with your instrument, refer to Chapter 2, “Instrument Control Session”.

GPIB Overview

Some of the GPIB functionality is required for all GPIB devices, while other GPIB functionality is optional. A dditionally, many devices support only a subset of the SCPI command set, or use a different vendor-specific command set. Refer to your device documentation for a complete list of its GPIB capabilities and its command set.

Important GPIB Features

The important GPIB features are described below. For detailed information about GPIB functionality, see the appropriate references in the Appendix B, “Bibliography”.

Bus and Connector

The GPIB bus is a cable with two 24-pin connectors that allow you to connect multiple devices to each other. The bus and connector have these features and limitations:

• You can connect up to 15 devices to a bus.

• You can connect devices in a star configuration, a linear co nfig uration,

or a combination of configurations.

• To achieve maximum data transfer rates, the cable length should not

exceed 20 meters total or an average of 2 meters per device. You can eliminate these restrictions by using a bus extender.

GPIB Devices

Each GPIB device must be some combination of a Talker,aListener,ora Controller. A Controller is typically a board that you ins tall in your computer.

Talkers and Listeners are ty pically instruments such as oscilloscopes, function generators, multimeters, and so on. Most modern instruments are both Talkers and Listeners.

• Talkers — A Talker transmits data over the interface when addressed to

talk by the C ontroller. There can be only one Talker at a given time.

• Listeners — A Listener receives data over the interface when addressed to

listen by the Controller. There can be up to 14 Listeners at a given time. Typically, the Controller is a Talker while one or more instruments on the GPIB are Listeners.

4-3

4 Controlling Instruments Using GPIB

• Controllers — The Controller specifies which devices are Talkers or

Listeners. A GPIB system can contain multiple Controllers. One of them is designated the Syste m Controller. Howev er, only one Controller can be active at a given time. T he current active controller is the Controller-In-Charge (CIC). The CIC can pass control to an idle Controller, but only the System Controller can make itself the CIC.

When the Controller is not sending messages, then a Talker can send messages. Typically, the CIC is a Listener while another device is enabled as a Talker.

Each Controller is identified by a unique board index number. Each Talker/Listener is identified by a unique primary address ranging fro m 0 to 30, and by an optional secondary address, which can be 0 or can range from 96 to 126.

GPIB Data

There are two types of data that can be transferred over GPIB: instrument data and interface messages:

4-4

• Instrument data — Instrument data consists of vendor-specific commands

that configure your instrument, return measurement results, and so on. For a complete list of commands supported by your instrument, refer to its documentation.

• Interface messages — Interface messages are defined by the GPIB standard

and consist of commands that clear the GPIB bus, address devices, return self-test results, and so on.

Data transfer consists of one byte (8 bits) sent in parallel. The data transfer rate across the interface is limited to 1 megabyte per second. However, this data rate is usually not achieved in practice, and is limited by the slowest device on the bus.

GPIB Lines

GPIB consists of 24 lines, which are shared by all instruments connected to the bus. 16 lines are used for signals, while eight lines are for ground. The signal lines are divided into these groups:

GPIB Overview

• Eight data lines

• Five interface managem ent lines

• Three handshake lines

The signal lin es use a low-true (negative) logic convention with TTL levels. This means that a line is low (true or asserted) when it is a TTL low level, and a line is high (false or unasserted) when it is a TTL high level. Th e pin assignment scheme for a GPIB connector is shown below.

GPIB Pin an

d Signal Assignments

Pin Label Signal Name Pin Label Signal Name

DIO1 Data transfer

DIO2 Data transfer

DIO3 Data transfer

DIO4 Data transfer

EOI End Or Identify

Valid

DAV

NRFD

Data

Ready For Data

Not

NDAC Not Data Accepted

IFC Interface Clear

SRQ Service Request

ATN Attention

Shield Chassis ground

DIO5 Data transfer

DIO6 Data transfer

DIO7 Data transfer

DIO8 Data transfer

REN

Remot

eEnable

GND DAV ground

D ground

GND

NRF

GND NDAC ground

GND IFC ground

GND SRQ ground

GND ATN ground

GND Signal ground

4-5

4 Controlling Instruments Using GPIB

Data Lines

The eight data lines, DIO1 through DIO8, are used for transferring data onebyteatatime. DIO1istheleastsignificantbit,whileDIO8isthemost significant bit. T he transferred data can be an instrument command or a GPIB interface command.

Data formats are vendor-specific and can be text-based (AS CII) or binary. GPIB interface commands are defined by the IEEE 488 standard.

Interface Management Lines

The interface management lines control the flow of data across the GPIB interface.

GPIB Interface Management Lines

Line Description

ATN Used by the Controller to inform all devices on the GPIB that

bytes are being sent. If the ATN line is high, the bytes are interpreted as an instrument command. If the ATN line is low, the bytes are interpreted as an interface message.

4-6

IFC Used by the Controller to initialize the bus. If the IFC line is

low, the Talker and Listeners are unaddressed, and the System Controller becomes the Controller-In-Charge.

REN

SRQ Used by Talkers to asynchronously request service from the

EOI If the ATN line is high, the EOI line is used by Talkers to identify

Used by the Controller to place instruments in remote or local program mode. If REN is low, all Listeners are placed in remote mode, and you cannot change their settings from the front panel. If REN is high, all Listeners are placed in local mode.

Controller. If SRQ is low, then one or more Talkers require service (for example, an error such as inv alid command was received). You issue a serial poll to determine which Talker requested service. The poll automatically sets the SRQ line high.

the end of a byte stream such as an instrument command. If the ATN li n e is low, the EOI line is used by the Controller to perform a parallel poll (not supported by the toolbox).

GPIB Overview

You can examine the state of the interface management lines with the

BusManagementStatus property.

Handshake Lines

The three handshake lines, DAV, NRFD, and NDAC, are used to transfer bytes over the data lines from the Talker to one or more address ed Listeners.

Before data is transferred, all three lines must be in the proper state. The active Talker controls the DAV line and the Listener(s) control the NRFD and NDAC lines. The handshake process allows for error-free data transmission.

Line Description

DAV

UsedbytheTalkertoindicatethatabytecanbereadbythe Listeners.

NRFD

NDAC

Indicates whether the Listener is ready to receive the byte.

Indicates whether the Listener has accepted the byte.

The handshaking process follows these steps:

1 Initially, the Talker holds the DAV line high indicating no data is available,

while the Listeners h old the NRFD line high and the NDAC line low indicating they are ready for data and no data is accepted, respectively.

2 When the Talker puts data on the bus, it sets the DAV line low, which

indicates that the data is valid.

3 The Listeners set the NRFD line low, which indicates that they are not

ready to accept new data.

4 The Listeners set the NDAC line high, which indicates that the data is

accepted.

5 When all Listeners indicate that they have accepted the data, the Talker

sets the DAV line high indicating that thedataisnolongervalid. Thenext byte of data can now be transmitted.

6 TheListenersholdtheNRFDlinehighindicatingtheyarereadytoreceive

data again, and the NDAC line is held low indicating no data is accepted.

4-7

4 Controlling Instruments Using GPIB

Note If the ATN line is high during the handshaking process, the information

is considered data such as an instrument command. If the ATN line is low, the information is considered a GPIB interface message.

The handshaking steps are shown below.

4-8

You can examine the state of the handshake lines with the HandshakeStatus property.

Status and Event Reporting

GPIB provides a system for reporting status and event inform ation. With this system, you can find out if your instrument has data to return, whether a command error occurred, and so on. For many instruments, the reporting

GPIB Overview

system consists of four 8-bit registers and two queues (output and event). T he four registers are grouped into these two functional categories:

• Status Registers — The Status Byte Register (SBR) and Standard Event

Status Register (SESR) contain information about the state of the instrument.

• Enable Registers — The Event Status Enable Register (ESER) and the

Service Request Enable Register (SRER) determine which types of e vents are reported to the status registers and the event queue. ESER enables SESR, while SRER enables SBR.

The status registers, enable registers, and output queue are shown below.

4-9

4 Controlling Instruments Using GPIB

4-10

Mathworks INSTRUMENTCONTROL TOOLBOX 2 user guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Getting Started

Product Overview

Getting to Know the Instrument Control Toolbox Software

Exploring the Instrument Control Toolbox Software

Learning About the Instrument Control Toolbox Software

Using the Documentation Examples

Toolbox Components

MATLAB Functions

Interface Driver Adaptor

Understanding the Toolbox Capabilities

Overview Help

Documentation Examples

Demos

Installation Information

Installation Requirements

Toolbox Installation

Examining Your Hardware Resources

instrhwinfo Function

General Toolbox Information

Interface Information

Adaptor Information

Instrument Object Information

Installed Driver Information

Test & Measurement Tool

Hardware

Installed Drivers

Viewing the IVI Configuration Store

Command-Line Configuration

Using the Test & Measurement Tool

Communicating with Your Instrument

Instrument Control Session Examples

Example: Communicating with a GPIB Instrument

Example: Communicating with a GPIB-VXI Instrument

Example: Communicating with a Serial Port Instrument

General Preferences for Instrument Control

Accessing General Preferences

MATLAB Instrument Driver Testing Tool

Device Objects

IVI Configuration Store

Getting Help

instrhelp Function

propinfo Function

instrsupport Function

Online Support

Instrument Control Session

Creating Instrument Objects

Overview

Interface Objects

Device Objects

Connecting to the Instrument

Configuring and Returning Properties

Configuring Property Names and Property Values

Returning Property Names and Property Values

Property Inspector

Communicating with Your Instrument

Interface Objects and Instrument Commands

Device Objects and Instrument Drivers

Disconnecting and Cleaning Up

Disconnecting an Instrument Object

Cleaning Up the MATLAB Workspace

Summary

Advantages of Using Device Objects

When to Use Interface Objects

Using Interface Objects

Creating an Interface Object

Object Creation Functions

Interface Object Creation Functions

Configuring Properties During Object Creation

Creating an Array of Instrument Objects

Connecting to the Instrument

Configuring and Returning Properties

Base and Inter face-Specific Properties

Returning Property Names and Property Values

Configuring Property Values

Specifying Property Names

Default Property Values