T

TN-101

LabVIEW ActiveX Automation for Audio Precision Instruments

Application and Te c h n i c a l Support

Introduction
TECHNOTE 101 describes the basic principles and techniques needed to operate Audio Precision instruments using the instruments Audio Precision control software as an ActiveX automation server within the LabVIEW environment. This TECHNOTE was developed using Microsoft Windows 98, APWIN Version 2.11, an Audio Precision System Two Cascade Plus, and LabVIEW 6.0.
Note: Much of the information contained in TECHNOTE 101 was previously published as Audio Precision TECHNOTE 22. The information in TECHNOTE 22 applies to earlier versions of LabVIEW software.

Although it is possible for LabVIEW to directly control GPIB2 versions of Audio Precision instruments as illustrated in Fig 1, GPIB control of Audio Precision systems is not the subject of this TECHNOTE. Instead, TECHNOTE 101 deals with the capability of LabVIEW to control the standard APIB3 versions of Audio Precision PC-controlled instruments via the instrument control software, using Microsoft ActiveX automation4 as shown in Fig 2. In this implementation, LabVIEW is an ActiveX automation client and the instrument control software becomes the ActiveX automation server.
Note: ActiveX automation can be considered as a renaming and restructuring of OLE automation technology. Commands which were formerly called OLE commands are ActiveX automation commands. Properly, the term OLE commands should no longer be used.

LabVIEW is a graphical programming development environment from National Instruments Corporation (NI)1. Engineers, scientists and technicians create virtual instruments (called VI in LabVIEW) to control and automate a wide variety of test and measurement instruments, and to gather and manipulate the resultant test data.

LabVIEW

LabVIEW
ActiveX

ActiveX

APIB

GPIB

Audio Precision instrument with GPIB Option

Fig 1. NI LabVIEW controlling a GPIB-equipped Audio Precision instrument using the GPIB interface.

Standard Audio Precision instrument (APIB)

Fig 2. NI LabVIEW controlling an Audio Precision instrument (via ActiveX automation control of APWIN) on a standard APIB interface.

pn 0055.0101 r0

pg.

LabVIEW ActiveX Automation

TECHNOTE

101

Learning about LabVIEW and ActiveX

NI LabVIEW is a powerful and comprehensive tool, and this document makes no pretense of instructing a new user in the operation of LabVIEW. If you are new to LabVIEW or if you havent yet used LabVIEW as an ActiveX automation client, use the LabVIEW online help and study the tutorials and other documents provided by National Instruments in the Adobe PDF file LVLIB.pdf. Also refer to the file LVUser.pdf, the users manual provided with LabVIEW. A good place to get started with ActiveX for LabVIEW is the help topic Calling an ActiveX Object from LabVIEW in the online help system provided within LabVIEW. For additional information, visit the National Instruments Web site at www.ni.com and enter ActiveX in the site search engine.

erty, a method or an event name, often followed by specific parameter switches and values. Using these commands, you can get or set an object property value, or execute an object method. The objects are organized hierarchically in a tree structure, and the command string is punctuated with dots (periods) to separate the hierarchical levels. For instance, in the ActiveX command AP.Compute.Normalize.Target(V) = 2.00 the objects are AP, Compute, and Normalize. Target is a method of the Normalize object. The argument V specifies that the result be returned in volts.
AP Anlr Application DoReadings Quit Version Visible WorkingDir BarGraph Compute Center Delta Normalize Horizontal AP.Compute.Normalize.Horizontal AP.Compute.Normalize.PostSweep AP.Compute.Normalize.Target PostSweep Target Sigma Smooth Log Print AP.Application.DoReadings AP.Application.Quit AP.Application.Version AP.Application.Visible AP.Application.WorkingDir

Using APWIN as a LabVIEW ActiveX Server

For APWIN to be controlled as a LabVIEW ActiveX automation server, both programs must be installed and running on the same computer. The Audio Precision instrument must be communicating with APWIN through the standard APIB computer interface.
NOTE: Although the Audio Precision control software for ATS-2 and the 2700 Series instruments can also be controlled from LabVIEW using ActiveX automation, in this TECHNOTE we will limit the discussion to controlling APWIN. LabVIEW control of ATS and AP2700 is very similar.

You may have automated some of your measurements using AP Basic, the programming language provided with Audio Precision instruments. If so, using OLE automation commands to control the instrument will be familiar to you. If you have not yet used AP Basic, refer to the AP Basic Language Manual and the AP Basic Extensions Manual included with your instrument. The AP Basic Extensions Manual for your Audio Precision instrument lists the OLE automation commands created for use in automating the instrument. As explained previously, these commands are also ActiveX automation commands, and user documentation may refer to the commands using either term. You can control the same control software functions using ActiveX automation as you can by using AP Basic macros. Each ActiveX command is expressed as a string with one or more object names followed by a prop-

Fig 3. Hierarchical tree of OLE / ActiveX objects, trimmed.

The hierarchical tree where these commands reside might look like the diagram in Fig 3. The root level of the hierarchy, AP, is called the AP._Global Object.

Creating Virtual Instruments to Control APWIN

We will go through the steps of creating four virtual instruments (VIs) as examples of controlling APWIN from LabVIEW. In these examples, we will create a LabVIEW VI and configure it as an ActiveX client, communicating with APWIN as the server. Our first VI will return the APWIN version number and SysType, and toggle the APWIN Visible

TECHNOTE

101

LabVIEW ActiveX Automation

pg.

property ON and OFF. A diagram of the completed VI, named APWIN Init.vi, is shown in Fig 9. Our second VI, APWIN Close.vi, is diagrammed in Fig 11. This VI will close APWIN as an ActiveX server and close its connection to LabVIEW as the ActiveX client. The third example, APWIN Sample.vi, shown in Fig 14, uses APWIN Init.vi as an object within a larger VI, and also adds the capability to configure the Audio Precision instrument inputs and outputs, set the generator level, and acquire an unsettled Channel A level reading. The fourth example, APWIN Sample 2.vi, shown in Fig 15, illustrates how to acquire sweep data arrays from APWIN and display them in an XY Graph control. Files embodying these VIs are available from the Audio Precision Web site. See page 8 for more information.

To access any of the object properties, methods or events exposed by APWIN, LabVIEW must perform three ActiveX automation steps: Open the APWIN automation server object; Traverse the object tree; Manipulate the property, method or event.

Opening the Automation Object

In LabVIEW, click on the Diagram window and select Show Functions Palette (Fig 4) from the Windows menu. Find the Automation Open function (cascading palettes Function > Communications > ActiveX > Automation Open)

Fig 5. Automation Open (Online Help screen from LabVIEW).

and drag it onto the Diagram window. The online help associated with this function is shown in Fig 5. To connect this function to APWIN, you must attach the APWIN automation reference number.

Attaching the Automation Refnum

Fig 4. Automation Open Function at third level of cascading Functions Palettes in LabVIEW. Automation Close, Invoke Node, Property Node and other ActiveX functions reside here as well.

Example One: APWIN Init.vi

To set up LabVIEW as an ActiveX automation client, first launch LabVIEW and APWIN, and then open a new VI file in LabVIEW.

The automation reference number (or refnum) for an application resides in a type library file (*.tlb) associated with the application. Using the right mouse button, click the Automation Open icon and choose Select ActiveX Class from the menu that drops down, as shown in Fig 6. Then browse to the folder that contains the APWIN type library file, which is normally the in APWIN program folder C:\Program Files\Audio Precision\Apwin(n.nn). Choose the file Apwin.tlb and then select

pg.

LabVIEW ActiveX Automation

TECHNOTE

101

Fig 6. Obtaining the AP._Global Object refnum in LabVIEW.

Global(APWIN.Application) from the objects that appear on the list. This will create an automation refnum control on the diagram (and on the function panel) for the AP._Global Object and attach it to the Automation Open function. You may rename the automation refnum control at this time if you wish. The automation refnum can be used to access any properties or methods at the root of the object tree, or it can serve as a link to other objects.
Note: If you cannot find Apwin.tlb, set the browser to Files of Type: *.* and browse to Apwin.exe, which also contains the object refnum information.

all reside on the same ActiveX Functions Palette where you found the Automation Open function, as shown in Fig 4. After you have dragged the Invoke Node function to your VI diagram, you can pass it the refnum by connecting a LabVIEW wire to the Automation Open function. Right-click the node, select a new object from the next level, and continue. The data output from each Invoke Node function is a new refnum that points to the next level. Fig 7 shows the LabVIEW online help for the Invoke Node function.

Manipulate Properties or Methods

All OLE objects and commands listed in the AP Basic Extensions Reference Manual for your instrument can be accessed by LabVIEW Invoke Node or Property Node functions.

Traversing the Object Tree by Adding Nodes

To traverse the object tree (to open the next level of objects), you simply add Invoke Node functions to your VI. The Invoke Node function, the Property Node function and the Automation Close function

Fig 7. Invoke Node (online help screen from LabVIEW).

Copyright 2003 Audio Precision

Fig 8. Property Node (Online Help screen from LabVIEW).

TECHNOTE

101

LabVIEW ActiveX Automation

pg.

Fig 9. APWIN Init.vi: creating a LabVIEW VI to control APWIN with ActiveX. Start APWIN, set the Visible property, and return the APWIN version and SysType properties.

AP.Application.Version, for example, is listed in the manual as a property belonging to the AP.Application object. This property is a read-only double value that indicates the software version number for APWIN. Fig 8 shows the LabVIEW online help for the Property Node function. Fig 9 shows the complete virtual instrument APWIN Init.vi that creates the Apwin.Application object, reports the APWIN version and System Type, and toggles the Visible property. The VI takes as input an Automation Open refnum, a true / false value from a Boolean control to toggle the APWIN Visible property, and a standard error-in cluster. The VI has four outputs: the refnum, the APWIN version, the SysType, and a standard error cluster output. LabVIEW can use this completed VI as an object in a different VI, as we will see in our third example. However, another VI is needed as well, one that closes APWIN and its automation refnum.

Fig 10. Automation Close (Online Help screen from LabVIEW).

Example 2: APWIN Close.vi Closing the Automation Object

You must close every ActiveX application refnum with the Automation Close function. Drag the Automation Close function icon onto the VI dia-

gram and connect it with a LabVIEW wire. Fig 10 shows the LabVIEW online help file information for this function. The APWIN Close.vi diagram in Fig 11 shows how simple this is. This VI not only connects the Automation Close function directly to the AP._Global Refnum In control, but also closes APWIN as an application with the AP.Application.Quit function using two Invoke Nodes. The Automation Close function will not execute until the AP.Application.Quit function has executed first because its error cluster input must wait for the Case structure to execute. This prevents

Fig 11. APWIN Close.vi diagram. This VI closes APWIN and closes its automation refnum.

pg.

LabVIEW ActiveX Automation

TECHNOTE

101

Fig 13 The LabVIEW control panel associated with the VI diagram in figure 13.

Using a VI as an Object
This process is very similar to the first example. However, we do not need to go through the steps to open APWIN as we did before, because we can simply use the APWIN Init VI as an object within this new VI. We will also use the APWIN Close VI to properly terminate APWIN at the end of execution. Open a new VI file. Click on the Diagram window and right click to bring up the Functions Palette. To use an existing VI as an object, choose Select a VI... , which is the last icon on the palette as shown in Fig 12. Its the function icon which looks like a cartoon balloon next to an ellipsis mark. This icon brings up a file browser where you can select a *.vi file to insert into your new VI as an object.

Fig 12. "Select a VI" on Functions Palette in LabVIEW 6.0.

closing the ActiveX refnum before attempting to invoke the APWIN Quit function, and avoids generating an error.

Example 3: Apwin Sample.vi

In our third example we will design a VI which enables us to set the System Two Cascade Plus input and output configurations, turn the outputs ON or OFF, and acquire a channel A level reading, all from within LabVIEW.

Fig 14. Creating a diagram for the APWIN Sample VI. This VI sets up the generator and analyzer and acquires an unsettled reading from the channel A level meter.

TECHNOTE

101

LabVIEW ActiveX Automation

pg.

From the browser, select the VI file APWIN Init.vi and drop it onto the Diagram window. You'll notice weve added the APWIN icon to our VI; this is easily done by double-clicking on the VIs icon window and designing or pasting an icon. Do the same for the APWIN Close.vi created in example two (or use the file available with this TECHNOTE from the Audio Precision Web site). Once you have the APWIN Init VI object in your diagram, you can add Node functions, connect wires between the nodes and attach refnums (right click a Node function icon to access the browser) as in the previous example. Be sure to terminate execution of the VI with the APWIN Close VI.

Putting Controls on a Panel

To make control settings for your VI, go to the LabVIEW Panel window and right-click to see the Tools Palette. Chose a dial, a switch or an indicator as your control. When the control is on the panel, its corresponding control icon appears on the VI Diagram; an example in this case would be the boolean control Ch A Autorange. Attach the control to the Node function you would like it to affect, and
Fig 16 APWIN Sample 2 vi panel with sweep data. The 22 Hz high pass and 22 kHz low pass filters are enabled resulting in the roll-off at both extremes of the sweep.

very quickly you can build up a VI like the one we've supplied, Apwin Sample.vi shown in Figures 13 and 14.

Fig 15. APWIN Sample 2 vi diagram. Note the use of the Variant To Data function to convert the variant array data from the XferToArray APWIN function into a LabVIEW double array. Execution flow follows the magenta error cluster wire from top left to bottom right

pg.

LabVIEW ActiveX Automation

TECHNOTE

101

Example 4: APWIN Sample 2.vi

In our fourth example, we will deal with arrays of variant data provided by APWIN after a sweep has been completed. This VI provides the frequency and amplitude sweep data as separate arrays, then bundles them into a cluster as input to an X-Y Graph. See Fig 16 for an example of the results of a sweep. This diagram in Fig 15 looks complicated but is straightforward. Execution follows the magenta error cluster wire from top left to bottom right. It starts with the APWIN Init VI function, proceeds to generator setup functions at the top, analyzer setup functions, sweep setup functions, and then Data functions to provide the sweep data. The sweep setup functions accomplish proper setup of the Data and Source sweep properties with the appropriate Property Node and Invoke Node LabVIEW functions. The APWIN data must be acquired from the Apwin.Data node with the XferToArray Invoke Node function. The output of the Invoke Node function is an APWIN variant that cannot be wired directly to a LabVIEW array. Use the Variant To Data function to convert the variant array data to a LabVIEW array. The diagram shows that an empty double array constant must be wired to the Type node on the Variant To Data function in order to accomplish this.

References
[1] National Instruments develops and manufactures hundreds of integrated software and hardware products, which, when combined with standard computers, are used to replace and/or communicate with traditional instrumentation and to monitor and control processes. You can contact National Instruments at 11500 N. Mopac Expressway, Austin, Texas 78759-3504; (512) 794-0100; www.ni.com. [2] GPIB is an acronym for General Purpose Interface Bus, an industry-standard computer interface protocol specified in IEEE-488.2. [3] APIB is the acronym for Audio Precision Interface Bus, the proprietary computer interface protocol that is the standard interconnection between a computer running APWIN and the Audio Precision System it controls. [4] Using ActiveX automation, you can access properties and methods (usuallly grouped into objects) of one Windows application and use them in another Windows application. An application supports automation either as a server or a client. Applications that expose objects and provide methods for operating on those objects are ActiveX automation servers. Applications that use the methods exposed by another application are ActiveX automation clients. More information on ActiveX and OLE automation can be found at this Microsoft site: www.microsoft.com/com/tech/ActiveX.asp.

Listing of Sample LabVIEW Files

The following LabVIEW VI files are available for use with this TECHNOTE: APWIN Init.vi (initializes ActiveX control of APWIN). APWIN Close.vi (closes ActiveX control of APWIN). APWIN Sample.vi (generator and analyzer setup and level reading). APWIN Sample 2.vi (generator and analyzer setup and sweep arrays and graph). These files are provided in a LabVIEW library file (*.llb file) in the zipped archive for this TECHNOTE. Go to the Audio Resources > Technotes area at the Audio Precision Web site at audioprecision.com to download this archive.