MAUI Oscilloscopes Remote Control Manual And Automation

maui-remote-control-and-automation-manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 388

Download
Open PDF In Browser	View PDF

Oscilloscopes
Remote Control and
Automation Manual

MAUI Oscilloscopes Remote Control and Automation Manual
© 2017 Teledyne LeCroy, Inc. All rights reserved.

Unauthorized duplication of Teledyne LeCroy documentation materials other than for internal sales and
distribution purposes is strictly prohibited. However, clients are encouraged to duplicate and distribute Teledyne
LeCroy documentation for their own internal educational purposes.
Teledyne LeCroy is a trademark of Teledyne LeCroy, Inc. Other product or brand names are trademarks or
requested trademarks of their respective holders. Information in this publication supersedes all earlier versions.
Specifications are subject to change without notice.

925131 Rev A
January 2017

Resources

Resources
Teledyne LeCroy provides many free resources to help you receive the greatest value from your
instrument. Most of the software and documentation mentioned in this manual can be downloaded from
our website; links are provided to other sites where relevant. In addition, many manuals and code
examples for further reference are installed when you install our software.

Software
Download software from: teledynelecroy.com/support/softwaredownload.
Under Oscilloscope Downloads, click the link to Software Utilities and browse the list of tools.

Manuals
Download manuals, application notes, and lab briefs from: teledynelecroy.com/support/techlib.
Use the sidebar at the left of the page to select the document category, then browse the list of links.

Technical Support
Registered users can contact their local Teledyne LeCroy service center at the number listed on our
website.
You can also submit Technical Support requests via the website at:
teledynelecroy.com/support/techhelp
Select the oscilloscope model you are using and the category into which your question falls.

MAUI Oscilloscopes Remote Control and Automation Manual

Notational Conventions
Notational Symbols
Commands shown in this reference make use of the following notational symbols:
Symbol

Function

Example

Encloses header paths or placeholders

:VOLT_DIV

Separates a placeholder from a description of the
type and range of values that may replace it

:= 5.0 mV to 2.5 V

{}

Encloses required values, one of which must be used
in the command

TRMD {SINGLE, AUTO, NORM, STOP}

[]

Encloses optional values

…

Indicates the items to its left or right can be repeated
any number of times

Sources
The character x is used to denote the greatest number of an oscilloscope object, such as input channels
or math function traces, supported by your instrument. Thus, on a two-channel oscilloscope, C1 through
Cx should be taken to mean C1 and C2, whereas on an eight-channel oscilloscope, C1 through C8, and so
forth.
The following characters may be used wherever a is indicated:
Object

Mnemonic

Channels

C1, C2, C3, C4,....Cx

Math Functions

F1, F2, F3, F4,....Fx,
TA, TB, TC, TD

Math trace names TA, TB, TC, and TD used on legacy
LeCroy instruments have been replaced by F1, F2, F3 and
F4, respectively. Existing programs that utilize the old trace
names will work with MAUI oscilloscopes, but these mnemonics are not returned in query responses. Instead, the
query will return the corresponding F1, F2, F3, and F4.

User-Defined
Parameters

P1,....Px
CUST1, CUST2, CUST3, CUST4,
CUST5

Parameter names CUST1 through CUST5 used on legacy
LeCroy instruments have been replaced by P1, etc. As with
math traces, these mnemonics may be used in programs
but are not returned by queries.

Memories

M1,...Mx

Note

Notational Conventions

Units and Multipliers
Numeric values can be expressed as numeric fixed point or exponential. Units may be expressed using the
following mnemonics.
Mnemonic

Unit

Amperes

CEL

Degrees Celsius

Coulombs

DAY

Days

Decibels

DBC

Decibels Referred to Carrier

DBM

Decibel Milliwatts

DBV

Decibel Volts

DBUZ

Decibel Microamps

DEC

Decades

DEG

Degrees of Arc

DIV

Divisions

EVENTS

Events

Farads

FAR

Degrees Fahrenheit

Feet

Grams

Henrys

HOUR

Hours of Time

Hertz

Inches

Joules

Degrees Kelvin

Liters

Meters

MIN

Minutes of Time

MNT

Minutes of Arc

OHM

Ohms

PAL

Pascals

PCT

Percent

POISE

Poise

PPM

Parts per Million

Newtons

RAD

Radians

iii

MAUI Oscilloscopes Remote Control and Automation Manual
Mnemonic

Unit

Seconds of Time / Samples

SAMPLE

Samples

SEC

Seconds of Arc

SIE

Siemens

SWEEP

Sweeps

Teslas

Unit Intervals

Volts

Volt Amps

Watts

Webers

Units can be prefixed with multipliers modifying the value of the numeric expression. The following table of
multipliers is recognized:
Mnemonic

Multiplier

Exponential
Notation

Exa-

1E18

Tera-

1E12

M/m*

Mega- / milli-

1E6 / 1E-3

nano-

1E-9

femto-

1E-15

Peta-

1E15

Giga-

1E9

kilo-

1E3

micro-

1E-6

pico-

1E-12

atto-

1E-18

Note: * While usually case doesn't matter when specifying units, as the system assumes certain
units based on the type of waveform or measurement, in some instances case will change the
meaning of the mnemonic and may or may not be accepted. Follow standard IEEE practice for
denoting units of measure.

Part 1: Making the Remote Connection

Part 1: Making the Remote Connection
You can fully control your instrument remotely using either:
l

COM Automation commands

IEEE 488.2 General Purpose Interface Bus (GPIB) commands

The remote connection can be made over a variety of physical interfaces such as ENET, GPIB, LSIB, or
USBTMC, using several interface drivers and protocols.
This section describes the software tools for remote control and procedures for making the remote
connection from a controller to an oscilloscope.
Understanding Remote Control Layers

1-2

Software Tools for Remote Control

1-3

Connecting via ENET

1-5

Connecting via USBTMC

1-9

Connecting via GPIB

1-10

Connecting via LSIB

1-11

Configuring DCOM Connections

1-12

Testing the Remote Connection

1-20

Remote Control Assistant

1-21

ActiveDSO

1-22

VISA

1-25

WaveStudio

1-28

1-1

MAUI Oscilloscopes Remote Control and Automation Manual

Understanding Remote Control Layers
It is helpful to understand some high-level concepts regarding how the oscilloscope is operated through
remote control and the terminology employed throughout this section.

From bottom to top, the components interact in the following manner:
The cable is the physical conduit between the controller (usually a PC) and the oscilloscope, connected on
either end to the hardware interface. Interfaces vary based on oscilloscope model and include ENET
(often labeled LAN on the oscilloscope), USBTMC, GPIB, and LSIB.
Depending on the interface selected, you may require a PC adapter in order to connect the cable. This is
particularly true for LSIB and GPIB. ENET ports are typically standard and do not require special adapters.
The oscilloscope may also require an oscilloscope adapter to make the connection.
Different protocols can be used for transmitting messages between the controller and the oscilloscope.
This selection again depends on the hardware interface. Available protocols include VICP (based on
TCP/IP), VXI-11 (for the LXI standard), USBTMC, GPIB, and LSIB.
PC instrument drivers are programs that enable the controller to interface with the oscilloscope, such as
ActiveDSO, VISA drivers, IVI drivers and LabVIEW drivers. They are the software complement to the
hardware interface. These programs do the work of encapsulating your programs messages into the
requisite interface messages that manage the exchange between device and controller.
The oscilloscope Remote Control Manager includes the drivers needed to make the software interface
from the oscilloscope side. Teledyne LeCroy oscilloscopes are shipped with everything necessary for
remote control functionality pre-installed. All you have to do to is select which protocol you want to use for
remote control from the instrument's Remote dialog.
The oscilloscope application (XStream) is the program that displays, transforms, and measures digitized
input signals and enables you to control the instrument. It is also the program that exchanges information
with the PC applications over the remote connection.
PC applications are programs residing on the controller that exchange data with the oscilloscope
application or function as a remote command console, such as WaveStudio, LabVIEW, MATLAB, and
custom applications.

1-2

Part 1: Making the Remote Connection

Software Tools for Remote Control
Many free software tools are available to help you make and manage the remote connection. See
Resources for download information. This software is to be installed on the PC/controller. Teledyne
LeCroy oscilloscopes are pre-installed with all necessary software for remote control.

Interface Drivers
ActiveDSO
Based on Microsoft's ActiveX technology, ActiveDSO simplifies programming for Teledyne LeCroy
oscilloscopes within the Microsoft environment. ActiveDSO provides interface drivers and a client library
to make the remote connection over ENET, GPIB or USBTMC interfaces. It also supports many
Automation features besides remote control. See ActiveDSO.

VISA
VISA-compliant drivers also provide the necessary software interface for remote control over ENET, GPIB,
or USBTMC. Add-on tools like NI-VISA handle device communications for many programming languages,
such as C++, LabVIEW, and Python. An installation of NI-VISA (or a VISA driver that behaves exactly like it)
is required if you cannot use ActiveX technologies such as ActiveDSO or WaveStudio. NI-VISA is always
required if you are uisng the USBTMC interface for remote control.

LeCroy VICP Passport and VICP Client Library
The VICP Passport was developed specifically for those using NI-VISA with the Teledyne LeCroy VICP
protocol. It provides the requisite VISA Passport functions for VICP communications.
Not technically a driver, the VICP Client Library provides the necessary toolkit for developing a VICP
interface to the oscilloscope from machines that are not running Windows.

LeCroyScope IVI Driver
The VISA-based LeCroyScope IVI Driver is an Interchangeable Virtual Instrument technology that provides
a standard API for communication with instruments. Provided to meet LXI standard requirements, the
driver strictly adheres to the IVI-Scope instrument class and includes both IVI-C and IVI-COM drivers. See
Introducing the LXI Interface for instructions on using the driver.
Note: Although provided for LXI compliance, you can use the IVI Driver even if your remote control
setting is TCP/IP (VICP), rather than LXI (VXI-11).

LabVIEW Drivers
The LeCroy_Wave_Series driver, created using the LabVIEW project architecture, is available for Windows
users who wish to control their oscilloscope through a LabVIEW™ program. The lcwave driver, an llb
LabView library, is available for those using pre-Windows oscilloscope models. Both drivers can be used
over an ENET, GPIB, or USBTMC connection. See Lab Brief WM832: Getting Started with the "lcwave" and
"LeCroy Wave Series" LabVIEW Drivers for instructions.

1-3

MAUI Oscilloscopes Remote Control and Automation Manual

Connectivity Tools
XStreamBrowser
The XStreamBrowser utility enables you to view, copy, and modify the COM object hierarchy of the
connected oscilloscope application. See XStreamBrowser.

WaveStudio
For PCs running Windows 10, 7, VISTA, or XP, WaveStudio is a remote control console that provides a
graphical user interface for oscilloscope setup, waveform inspection, and data transfer. It supports TCPIP,
LXI, GPIB, LSIB, or USBTMC/USB488 connections. See WaveStudio.

ScopeExplorer
For PCs running Windows 2000 or XP, ScopeExplorer is a connectivity tool that interfaces legacy model
Teledyne LeCroy oscilloscopes (e.g., LCxxx, LTxxx, 93xx) to the Windows desktop.

1-4

Part 1: Making the Remote Connection

Connecting via ENET
Teledyne LeCroy oscilloscopes employ a standard Ethernet interface for utilizing the TCP/IP transport
layer.

Hardware
For purposes of remote control, you may either:
l

Connect the oscilloscope to a LAN port or hub using a straight Ethernet cable

Connect the oscilloscope directly to the controller using a crossover cable
Tip: If you are concerned mainly with system throughput, a LAN connection is not recommended
as network traffic may slow down oscilloscope data transfer rates. Use a direct connection, or
consider using LSIB if your oscilloscope supports it.

IP Address
The oscilloscope accepts DHCP addressing. Be sure the controller and the oscilloscope are on the same
subnet.
If connected via LAN, you may optionally assign a static IP address to the oscilloscope. You must assign a
static IP address if using a crossover cable to connect.
Tip: Use the standard Windows networking dialogs to set the instrument IP address. To access
the Windows control panel, choose File > Minimize or go to Utilities > Utilities Setup > Remote
and select Net Connections.
If both controller and oscilloscope are connected to a name server, you may use the string for
addressing. The string must be the instrument name that is recognizable to the name server.

Protocol Selection
There are two protocol options for remote control via ENET:
l

VICP, for which you select the TCP/IP remote control setting

VXI-11, for which you select the LXI remote control setting

1-5

MAUI Oscilloscopes Remote Control and Automation Manual

Connecting with VICP
The TCP/IP (VICP) remote control setting uses port 1861 and the proprietary VICP protocol for
transmitting messages.
Note: LabVIEW programmers should use the TCP/IP (VICP) setting with an installation of NI-VISA
and VICP Passport to communicate with Teledyne LeCroy oscilloscopes.

Controller Set Up
Open port 1861 on the controller for TCP/IP communications.
If the controller runs Windows, install NI-VISA to manage the interface functions of the VICP connection.
NI-VISA users should also install the VICP Passport.
Those who are not running Windows should install the LeCroyVICP Client Library. This library can be
downloaded free of charge from www.SourceForge.net. You will need to use the library to program your
own VICP interface.
If you are running Windows and can utilize ActiveX controls, we highly recommend installing ActiveDSO on
the controller to simplify communications with the oscilloscope.
Optionally, install the LeCroyScope IVI driver or a LabVIEW driver.

Oscilloscope Set Up
Go to Utilities > Utilities Setup > Remote and choose TCP/IP (VICP).

Note the instrument's IP address for use in VISA resource strings and function calls.

VICP Protocol
VICP is the Versatile Instrument Control Protocol, the proprietary protocol used by the TCP/IP (VICP)
remote control setting on Teledyne LeCroy oscilloscopes. This protocol aims to emulate IEEE488.2 and
includes operation bits corresponding to SRQ, EOI, Clear, and others in a header that is defined by the VICP
protocol.
VICP is registered with IANA to communications port 1861.
Code to parse VICP packets is publicly available at: http://www.SourceForge.net.
See the Application Brief LAB_WM827: Understanding VICP and the VICP Passport.

1-6

Part 1: Making the Remote Connection
VICP Headers
The format of the header sent before each data block of a VICP transmission, both to and from the
instrument, is set out in the following table:
Byte Number

Purpose

Operation

Header Version

Sequence Number*

Spare (reserved for future expansion)

Block Length, (bytes of data), MSB

Block Length (bytes of data)

Block Length, (bytes of data), LSB

* The sequence number is used to synchronize write/read operations to simulate 488.2 “discard unread response”
behavior. Valid range is 1 to 255 (zero is omitted intentionally).

VICP Operation Bits
Operation bits are as follows:
Data Bit

Mnemonic

Purpose

DATA

Data block (D0 indicates termination with/without EOI)

REMOTE

Remote Mode

LOCKOUT

Local Lockout (Lock out front panel)

CLEAR

Device Clear (if sent with data, clear occurs before data block is passed to parser)

SRQ

SRQ (Device to PC only)

SERIAL POLL

Request a serial poll

Reserved

Reserved for future expansion

EOI

Block terminated in EOI
Logic 1 = use EOI terminator
Logic 0 = no EOI terminator

VISA Addressing
Code strings such as "TCPIP0::::1861::SOCKET" may or may not work when using VICP
depending on how the application handles instrument responses. The data returned will include header
information that needs to be parsed, and allowances must be made to trap situations where a transfer is
not complete, or where there is an unread response from the instrument. SOCKET connections should
work properly if you are using the VICP Client Library.
Teledyne LeCroy developed the VICP Passport to handle socket connections more reliably when using NIVISA. Instead of "TCPIP:: . . .", use "VICP::" to make the connection.

1-7

MAUI Oscilloscopes Remote Control and Automation Manual

Connecting With VXI-11
LXI is an industry-standard specification for LAN-based instruments that utilizes the VXI-11 protocol for
TCP/IP communications and instrument discovery. For information, visit www.lxistandard.org.
Teledyne LeCroy oscilloscopes are LXI Class-C compliant. We have implemented a full-featured stack that
allows any command or query to be sent using the VXI-11 protocol, beyond the LXI requirements for
discovery and execution of simple *IDN? queries.
Note: You can use the VXI-11 protocol for remote control of Teledyne LeCroy oscilloscopes even if
your network is not LXI compliant. For those who cannot utilize ActiveX or VICP, LXI (VXI-11) is the
best remote control setting.

Resources
The LXI specification stipulates that vendors supply:
l

An IVI driver for the instrument. Download and install the LeCroyScope IVI driver if you wish to
implement the IVI standard API. See Resources.
Note: An IVI driver is required to connect to MATLAB applications using LXI (VXI-11).

A web server to simplify remote control configuration. To access this page from the controlling PC,
enter the oscilloscope IP address in URL field of a browser.

Controller Setup
Install NI-VISA to manage the interface functions of the underlying TCP/IP connection.
If you are running Windows and can utilize ActiveX controls, we highly recommend installing ActiveDSO on
the controller to simplify communications with the oscilloscope.
Optionally, install the LeCroyScope IVI driver or LabVIEW driver.

Oscilloscope Setup
Go to Utilities > Utilities Setup > Remote and choose LXI (VXI-11).

We recommend that you modify the password for LAN access. The default username is lxi.lecroyuser
and password is lxi. You can reset to these defaults by pressing LAN Configuration Reset.
Note the instrument's IP address for use in VISA resource strings and function calls.

1-8

Part 1: Making the Remote Connection

Connecting via USBTMC
USBTMC is a protocol built on top of USB that allows GPIB-like communication with USB devices. The
USBTMC protocol supports service requests, triggers, and other GPIB-specific operations.
Some (not all) MAUI oscilloscopes offer a USBTMC remote control setting. Check your product datasheet
to confirm if this is supported.

Hardware
Connect a USB A-B cable from any host port on the controller to the device port on the oscilloscope, which
is usually specifically marked USBTMC.

Controller Set Up
Install NI-VISA v 3.0 or later on the controller PC.
Note: NI-VISA is always required for the USBTMC connection.
If you are running Windows and can utilize ActiveX controls, we highly recommend installing ActiveDSO on
the controller to simplify communications with the oscilloscope.
Optionally, install a LabVIEW driver.

Oscilloscope Set Up
Go to Utilities > Utilities Setup > Remote and select the USBTMC remote control setting.

Note the USBTMC VISA Address for use in VISA resource strings.

1-9

MAUI Oscilloscopes Remote Control and Automation Manual

Connecting via GPIB
The IEEE 488.2 General Purpose Interface Bus, or GPIB, interconnects independent devices by means of a
cable bus. Although largely replaced by other serial buses, Teledyne LeCroy's IEEE 488.2 command set is
still supported by all MAUI oscilloscopes. See the IEEE 488.2 Command Reference.
GPIB is offered as an optional, factory-installed interface on most MAUI oscilloscopes over 350 MHz
bandwidth. You can send Automation commands over the GPIB interface using the VBS command, it is
not restricted to the IEEE 488.2 commands.
Caution: Do not install third-party GPIB driver software on Teledyne LeCroy oscilloscopes; this can
result in a non-functional GPIB interface. The only GPIB driver designed to operate on the
instrument is included with your oscilloscope's firmware.
The optional USB2-GPIB Converter enables you to take advantage of high-speed transfer from the
oscilloscope using the USB2 interface on newer MAUI oscilloscopes. However, this is still treated as a
GPIB connection in VISA resource strings. See the USB2-GPIB Converter User's Manual.

Hardware
If both controller and oscilloscope have a GPIB port, connect them using a GPIB cable.
If using the USB2-GPIB Converter, connect the converter from the GPIB port on the controller to a USB2
port on the oscilloscope. On the first connection, accept and install the device driver. The driver is located
at: C:\Program files\LeCroy\XStream\Drivers_X86(or X64)\GPIB2USB. The installer is called dpinst.exe.
Reboot the instruments.

Controller Set Up
Install NI-VISA to manage the interface functions of the GPIB connection.
If you are running Windows and can utilize ActiveX controls, we highly recommend installing ActiveDSO on
the controller to simplify communications with the oscilloscope.
Optionally, install a LabVIEW driver.

Oscilloscope Set Up
On the oscilloscope, go to Utilities > Utilities Setup > Remote and select the GPIB option. If necessary,
modify the oscilloscope's GPIB Address.

1-10

Part 1: Making the Remote Connection

Connecting via LSIB
The LeCroy Serial Interface Bus, or LSIB, is a proprietary standard for high-speed data transfer from the
oscilloscope with speeds up to 325 MB/s. Teledyne LeCroy’s exclusive LSIB solution is based on the wired
PCI Express standard that uses a 4-lane bus for remote data transfer. An LSIB API is published.
While LSIB offers significant improvements in data transfer rate over 100Base-T ENET, USBTMC, and
GPIB, the LSIB API is geared toward waveform and data transfer and does not provide for many other
common remote control functions such as remote set up, "hardcopy" screen capture, etc.
LSIB is an optional, factory-installed interface on WavePro, WaveMaster, and LabMaster series
oscilloscopes.

Hardware
Install the LSIB host board or host card on the controller PC, then connect the controller to the
oscilloscope using the LSIB cable.
See the LSIB Host Interfaces Operator's Manual for instructions on making the LSIB connection.

Controller Set Up
Run the LSIB installer for Windows or Linux on the controller. After installation, the online LSIB API (LSIBAPI-Ref-OLH-E.chm), can be found in:
C:\Program Files\LeCroy\XStream\LSIB\Docs

Oscilloscope Set Up
On the oscilloscope, go to Utilities > Utilities Setup > Remote and select the LSIB remote control option.
Shut down both the oscilloscope and the controller. Restart the oscilloscope first, followed by the
controller. You do not have to wait for the oscilloscope's boot cycle to complete to restart the controller.

1-11

MAUI Oscilloscopes Remote Control and Automation Manual

Configuring DCOM Connections
The Windows Distributed Component Object Model (DCOM) permits the distribution of different
components of a single application across two or more networked computers and the remote display and
control of applications. Accessing a networked oscilloscope remotely via DCOM is equivalent to logging on
to the oscilloscope itself and executing programs "locally."
In order to access the oscilloscope's object hierarchy without ActiveDSO or a VISA driver, or to use
XStreamBrowser remotely, Windows DCOM settings must be configured to permit the controller and
oscilloscope to control applications residing on the other.
Note: DCOM is pre-configured on WaveSurfer 3000 oscilloscopes, which run the Windows CE
platform and do not allow access to a desktop. Install the WaveStudio software, which displays the
COM hierarchy of a connected device when Automation Browser is selected.
To complete this process, you will:
1. Configure the remote PC to permit DCOM connections.
2. Configure the oscilloscope DCOM settings, including creating user accounts (if required).
3. Test the connection.
Note: You must have Administrator privileges on both the PC and the oscilloscope to complete
DCOM configuration.

A. Determine Windows OS
If you do not know the operating system running on the controller or the oscilloscope, go to the Windows
desktop, right-click on the My Computer icon and choose Properties. Follow the procedures below
indicated for your operating system.

B. Determine Network Domain and User Accounts
If the oscilloscope is not on the same NT domain as the controller PC, you will need to set up an account
for the PC user in the oscilloscope domain using the exact same user name and password as on the PC.
That same user must also be allowed into the oscilloscope DCOM section. Before proceeding, consult
your Network Administrator regarding your network configuration.
If the machines are on different domains, verify the user name and password for each user account that
will be used to send Automation commands to the oscilloscope. You will need this information to complete
the configuration on the oscilloscope.

C. Install XStreamBrowser
Download and install the XStreamBrowser on the controller PC.
Note: XStreamBrowser is installed by default on the oscilloscope.

1-12

Part 1: Making the Remote Connection

D. Configure Component Services
Windows 7 and 10
On the Controller
Follow these steps if the PC is running the Windows 7 or Windows 10 operating system.
1. Go to the Windows Start menu and type dcomcnfg.exe in Search programs and files.
2. Expand Component Services until you see My Computer. Right-click on My Computer and choose
Properties.

3. On the Options tab, enter 0 for Transaction timeout, then click Apply.

4. Open the Default Properties tab. Make sure Enable distributed COM on this computer is
checked. If not check it and click Apply.

1-13

MAUI Oscilloscopes Remote Control and Automation Manual

On the Oscilloscope
All Zi series, HDO series, MDAs, WaveRunner 8000s, and HROs use the 64-bit Windows 7 platform.
We recommend connecting a keyboard and mouse to the oscilloscope before beginning this procedure.
Use any USB ports.
Create Users
1. Choose File > Minimize to display the Windows desktop.
2. Windows 7: Go to Start > Control Panel > User Accounts > Manage User Accounts.
Windows 10: Go to Start > Settings > Accounts > Other People.
3. For each user that is to access the oscilloscope remotely, Add a user ("Another work or family user")
with the same user name and password as on the PC. Be sure the user is created as a Local
Administrator.
Configure DCOM Settings
1. Go to the Windows Start menu and enter dcomcnfg.exe in Search programs and files.
2. Expand Component Services until you see My Computer. Right-click on My Computer and choose
Properties.

1-14

Part 1: Making the Remote Connection
3. On the Options tab, enter 0 for Transaction timeout, then click Apply.

4. Open the Default Properties tab. Make sure Enable distributed COM on this computer is
checked. If not check it and click Apply. Close the dialog when done.

1-15

MAUI Oscilloscopes Remote Control and Automation Manual
5. On the Component Services window, navigate to Component Services > Computers > My
Computer > DCOM Config and select it.
6. From the list on the right, right-click on LeCroyXStreamDSO and choose Properties.

7. On the Properties dialog, open the Identity tab and select The interactve user. Apply and close
Properties and Component Services.
Open Firewall
1. Go to the Windows Start menu and enter wf.msc in Search programs and files.
2. Open Inbound Rules. For both Inbound rules named Windows Management Instrumentation
(DCOM-In), right-click and choose Enable Rule. Close Windows Firewall dialog.

3. Choose Start > Shutdown > Log Off, then log back in as the new user that was created on the
oscilloscope.

1-16

Part 1: Making the Remote Connection

Windows XP or Vista
On the Controller
Follow these steps if the controller PC is running Windows XP or Vista operating system.
1. Go to Start > Run, enter dcomcnfg.exe and click OK.
Note: If Run is not in your Start menu, open a terminal and run dcomcnfg.exe.
2. Expand Component Services > Computers.
3. If you see a Windows Security Alert pop-up, click Unblock.
4. In the Computers folder, right-click My Computer and choose Properties.
5. On the Properties dialog, open the Options tab and change Transaction Timeout to 0. Click Apply.

On the Oscilloscope
Follow these steps if your legacy model LeCroy oscilloscope is still running Windows XP or Vista operating
system.
Contact Technical Support for assistance if your oscilloscope is running Windows XP Embedded.
Open Firewall
1. Go to Start > Control Panel > Firewall. For Vista machines, click Change Settings.
2. On the Windows Firewall dialog, open the Exceptions tab.
3. Select LeCroyXStreamDSO Main Application.
4. Click Add Port.
5. On the Add Port dialog, make the following settings, then click OK:
l

Name: DCOM

Port number: 135

TCP: selected

1-17

MAUI Oscilloscopes Remote Control and Automation Manual
Turn Off Simple File Sharing
This procedure is required only for Windows XP and Vista oscilloscopes that are on the same NT domain as
the controller.
1. Go to Start > Control Panel > Folder Options.
2. On the Folder Options dialog, open the View tab and clear the checkbox Use simple file sharing.
3. Click OK.
Create Users
If the oscilloscope is on the same NT domain as the controller, you can skip this procedure.
If the oscilloscope is not on the same NT domain as the controller, each PC user that is to send
Automation commands to the oscilloscope must have a corresponding user account on the oscilloscope,
configured with the identical user name and password. Both accounts must have Administrator privileges.
1. On the Windows desktop, right-click on My Computer and choose Manage.
2. Expand the hierarchy to display Local Users and Groups > Users. Select Users
3. Right-click on a blank area of the dialog and choose New User.
4. Enter the User name and Password exactly as they appear on the controller PC. Confirm password.
5. Deselect User must change password at next logon.
6. Click Close.
Configure DCOM Settings
1. Go to Start > Run, enter dcomcnfg.exe and click OK.
Note: If Run is not in your Start menu, open a terminal and run dcomcnfg.exe.
2. Expand Component Services.
3. If a Windows Security Alert pop-up appears, click Unblock.
4. Expand Computers, right-click on My Computer, and select Properties.
5. Open the Options tab and set the Transaction timeout to 0. Click Apply.
6. Open the Default Properties tab, select Enable Distributed COM on this computer, and choose a
Default Authentication Level of Connect.
7. Open the COM Security tab and under Launch and Activation Permission click Edit Limits.
8. On the Launch Permission dialog, click Add.
9. On the Select Users… dialog:

1-18

Part 1: Making the Remote Connection
l

If the PC and oscilloscope are on the same NT domain, select the PC user account.
If the PC and oscilloscope are not on the same NT domain, enter the PC user account name
and click Check Names.

Click OK.
10. On the Launch Permissions dialog, check Allow for all permissions. Click OK.
11. On the Component Services window, expand My Computer > DCOM Config. Right-click on
LeCroyXStreamDSO and choose Properties.
12. Open the Identity tab and select The interactive user.
13. Open the Security tab, under Launch and Activation Permissions select Customize, then click Edit.
14. On the Select Users… dialog:
l

If the PC and oscilloscope are on the same NT domain, select the PC user account.
If the PC and oscilloscope are not on the same NT domain, enter the PC user account name
and click Check Names.

Click OK.
15. On the Launch Permissions dialog, check Allow for all permissions. Click OK.
16. On the Security tab, under Access Permissions, select Customize and click Edit. Repeat Steps 14
and 15.
17. Choose Start > Shut Down > Restart to reboot the oscilloscope.

Testing the DCOM Connection
Install the XStreamBrowser on the PC and use it to Connect to Remote Instrument (DCOM).
If the connection is properly configured, you should now see the oscilloscope application object hierarchy
appear in the XStreamBrowser window.
Note: WaveSurfer 3000 users should instead install the WaveStudio software, which will display
the COM hierarchy of a connected device when Automation Browser is selected.

1-19

MAUI Oscilloscopes Remote Control and Automation Manual

Testing the Remote Connection
Once you have completed all the steps required to make the remote connection to your oscilloscope, test
that you can "see" it from the controller and send remote commands.

Using WaveStudio
The free WaveStudio software is capable of testing several types of remote connection as well as serving
as a remote command terminal for controlling the oscilloscope. A trial copy is installed on the oscilloscope,
and another may be installed on Windows-based PCs. For download information, see Resources.
Follow these steps to test the connection:
1. Click the Add Scope

button on My Scope Explorer or the Scope menu ribbon.

2. On the Add Device dialog, select the remote connection type.
3. Enter the oscilloscope's network name or address and click OK.
If the oscilloscope is found, an entry is added to the My Scope Explorer window. The status should indicate
the device is "Alive." This confirms the connection is working.
If the oscilloscope is found but cannot be connected, after a brief time out an entry is added to My Scope
Explorer indicating the selected device is "Dead." Check the address and physical connection again. If you
still cannot connect, consult with your Network Administrator.

Using the PING Command
For LAN users, both the physical cable connection and proper host TCP/IP configuration can be verified
using the Ping command.
Note: PING is a good way to check the network connection, but it doesn't guarantee the socket
connection to the oscilloscope at port 1861. Connecting via WaveStudio or XStreamBrowser is a
better test.
At an MS-DOS prompt, type:
ping

where is the address assigned to the oscilloscope.
The Command Prompt window shows an exchange similar to that below if the Ping is successful. The
Ethernet connection is shown as established and the ping command has sent a message to the
instrument and waited for a response. If a timeout occurs, the IP address used for the destination (the
oscilloscope) is incorrect or not within the subnet mask of the host's IP.

1-20

Part 1: Making the Remote Connection

Successful ping showing reply.

Remote Control Assistant
The Remote Control Assistant (RCA) feature of MAUI oscilloscopes maintains a log of remote control
commands received and responses issued (which would include Automation controls sent within the VBS
command), allowing the programmer to receive feedback on errors in his or her source code.
The RCA has several modes of operation: Off, Errors Only, and Full Dialog.
l

In Errors Only mode (the default), the RCA will keep a log of any mistakes in the commands
received, and display the error detected.
In Full Dialog mode, all commands and responses are logged.

This selection can be made by going to Utilities > Utilities Setup > Remote on the oscilloscope.
Touch Show Remote Control Log on the Remote dialog to pop up a window showing the log file. From
there you can clear the log or save it as a text file.
The RCA can also be set by using the remote commands COMM_HELP (CHLP) and
COMM_HELP_LOG (CHL).

1-21

MAUI Oscilloscopes Remote Control and Automation Manual

ActiveDSO
ActiveDSO is a proprietary ActiveX™ control that enables Teledyne LeCroy oscilloscopes to be controlled
by and exchange data with a variety of Windows applications that support the ActiveX standard. Microsoft
Office suite, Internet Explorer, Visual Basic, Visual C++, and Visual Java are a few of the many applications
and languages that support ActiveX controls.
ActiveDSO hides the intricacies of programming in ActiveX and provides a simple and consistent interface
to the controlling application. The ActiveDSO control may be used as either:
An "invisible" object accessed via a scripting language, for example, VBS.

A visible object embedded in an OLE Automation compatible client, such as a VBA macro launched
by a Windows application button.

Note: Many of our Automation examples utilize Visual Basic Script (VBS) as the "built in"
Automation language, as it is syntactically identical to our LeCroy Setup Script (.LSS). Visual Basic
for Applications (VBA) is a subset of Visual Basic that makes it very easy to utilize the services of
OLE Automation Servers and ActiveX Controls as a macro "programming" language.
A great benefit of ActiveDSO is that it is completely independent of the remote hardware interface. The
connection via ENET (TCP/IP), GPIB, or USBTMC is made by a single command near the start of a
program. It may be used to send Automation commands or legacy IEEE 488.2 remote control commands.
Download the ActiveDSO software free of charge from our website (see Resources) and install ActiveDSO
on the controller PC. The driver installs with the ActiveDSO Developer's Guide. This manual documents all
the methods and properties used to program ActiveDSO objects. Following are some simple examples.
More extensive examples are installed in the ActiveDSO program folder.

Instantiating the ActiveDSO Control
The control's external name is always: LeCroy.ActiveDSOCtrl.1
The control's CLSID is 450A9897-D9C9-11D1-9966-0000F840FC5E
Following are instantiations of the control as an "invisible" object used to pass remote commands in
several commonly used languages. In each case, the control is aliased as "dso", although for this you may
substitute whatever you wish.
Language
VBA

Dim dso As Object
Set dso = CreateObject("LeCroy.ActiveDSOCtrl.1")

Python

import win32com.client
dso=win32com.client.Dispatch("LeCroy.ActiveDSOCtrl.1")

Visual C++

CActiveDSO dso;
RECT dummyRect;
dso.Create("LeCroy.ActiveDSOCtrl.1","HiddenWindowForDSOControl",0,dummyRect,
this,0);

1-22

Part 1: Making the Remote Connection

ActiveDSO Methods for Remote Control
Following are several ActiveDSO methods that are particularly useful for remote control. See the
ActiveDSO Developer's Guide for an explanation of all ActiveDSO methods.

MakeConnection
This method establishes the connection from controller to oscilloscope. It is a single line of code that
requires only that you pass the oscilloscope interface and address to which to connect.
The following table shows the MakeConnection string for each remote interface type.
Interface

Syntax

Example

TCP/IP

MakeConnection("IP: ")

MakeConnection("IP: 172.25.9.22")

GPIB

MakeConnection("GPIB[x]: ")
x:= 0 to 3 (optional)

MakeConnection("GPIB: 4")

USBTMC

MakeConnection("USBTMC: ")

MakeConnection("USBTMC:
USB0::0x05FF::0x1023::2807N59057::INSTR")

Note: TCP/IP includes the TCP/IP (VICP) and LXI (VXI-11) remote control settings. When the VISA
resource string is used with ActiveDSO, it is preceded by a single colon space instead of the double
colon used with a VISA driver.

Disconnect
The Disconnect method disconnects the control from the device. This method performs the necessary
termination functions, which will cleanup and disconnect the interface connection.

WriteString
The WriteString method sends a command string to the connected device with or without a terminating
EOI (End or Identify). It can be used with Automation or legacy remote commands.
WriteString follows the syntax:
.WriteString("", )
:=

name used to instantiate the ActiveDSO control

:= command string sent to the device
:= {1, 0}

If EOI is set to 1 (TRUE), the command terminates with EOI, and the device interprets the command right
away. This is normally the desired behavior.
If EOI is set to 0 (FALSE), a command may be sent in several parts with the device starting to interpret the
command only when it receives the final part, which should have EOI set to TRUE.

1-23

MAUI Oscilloscopes Remote Control and Automation Manual

ReadString
The ReadString method reads a string response from the instrument and can be used to read the results
of queries.
' Read the amplitude parameter measurement, store in cell L3 of Excel worksheet
Call o.WriteString("c1:pava? ampl", 1)
Worksheets("Sheet1").Cells(3, 12).Value = o.ReadString(500)
' Read the rise time parameter measurement into variable
Call o.WriteString("c1:pava? rise", 1)
RiseTime = o.ReadString(500)

1-24

Part 1: Making the Remote Connection

VISA
VISA refers to the Virtual Instrument Software Architecture, an API widely used in Test & Measurement for
communicating with instruments from a PC. With the installation of a VISA driver, the programmer needs
only provide a VISA resource string to create a connection to a remote instrument, and VISA passes
subsequent write or read data requests and the corresponding VISA passport to the instrument.
A VISA driver that behaves exactly like NI-VISA is required for remote connection to Teledyne LeCroy
oscilloscopes over the ENET, USBTMC, and GPIB interfaces if you cannot utilize ActiveX technology (such
as ActiveDSO and WaveStudio) on your network. Programmers should download and read the IVI VISA
specification document for their programming language to fully understand the VISA API. It is always a
good idea to install the IVI VISA API in order to decouple your Automation program from the driver used.
We have tested our instruments with National Instrument's implementation of VISA, NI-VISA, and
recommend an installation of this if you are making the remote connection from a Windows machine. NIVISA can be downloaded from: https://www.ni.com/visa/
Note: For NI-VISA licensing requirements and fees, see https://www.ni.com/visa/license.htm.
Unless you install NI-VISA, you will have to program your own remote control interface. We supply the VICP
Client Library for those who wish to use the VICP protocol but cannot use NI-VISA because they are not
working in the Windows environment.

VICP Passport for NI-VISA
Those using NI-VISA for VICP connections in the Windows environment should install the VICP Passport.
The passport is a plug-in DLL for NI-VISA that provides a translation layer between the standard NI-VISA
API and Teledyne LeCroy's VICP protocol. See the Application Brief LAB_WM827: Understanding VICP and
the VICP Passport for more information.
Note: NI-VISA provides the necessary VISA passports for LXI, GPIB, and USBTMC connections;
VICP Passport is only necessary if you're using VICP protocol.
Download VICP Passport from teledynelecroy.com. See Resources.

1-25

MAUI Oscilloscopes Remote Control and Automation Manual

VISA Resource Strings
Use one of the following VISA resource strings to make the remote connection:
Protocol VISA Resource String
VICP
(TCP/IP)

VICP::
VICP::
Examples:
VICP::172.29.9.22
VICP::LCRY4201N10003

VXI-11
(LXI)

TCPIP::::INSTR
TCPIP::::INSTR
Examples:
TCPIP::172.29.9.22::INSTR
TCPIP::LCRY4201N10003::INSTR

GPIB

GPIB::::INSTR
Example:
GPIB::4::INSTR

USBTMC

USBTMC::::INSTR
Example:
USBTMC::USB0::0x05FF::0x1023::2807N59057::INSTR

The suffix ::INSTR is not necessary for VICP, but those using other protocols should continue to use the full
syntax.
The string is the name by which the DNS server knows the instrument (often the serial
number) and can be used only if the oscilloscope and controller are both connected by LAN to a name
server.
On the oscilloscope, go to Utilities > Utilities Setup > Remote to find the instrument address and serial
number.

1-26

Part 1: Making the Remote Connection

Using VISA Aliases
For LXI (VXI-11), GPIB, and USBTMC connections, VISA aliases can be used instead of the full VISA
resource string, allowing you to decouple your remote control programs from DHCP changes or long,
cumbersome device addresses.
Note: VISA aliases cannot be used with the VICP protocol.
Tools like NI-MAX (Measurement & Automation Explorer) make it very easy to assign aliases to any device
in your system, which are automatically updated whenever the address is changed.

Once the alias is assigned, simply replace the full VISA connect string with the alias in your code. For
example, in this Python script, instead of:
import visa
rm = visa.ResourceManager()
lecroy = rm.open_resource("TCPIP0::HDO-LCRY::inst0::INSTR")

You could send:
import visa
rm = visa.ResourceManager()
lecroy = rm.open_resource("HDO6104MS")

1-27

MAUI Oscilloscopes Remote Control and Automation Manual

WaveStudio
WaveStudio is a PC-based connectivity tool that interfaces a Teledyne LeCroy oscilloscope to a Windows
XP, Vista, 7 or 10 operating system, with support for 32- and 64-bits. It is a fast and easy way to analyze
acquired waveforms offline, or to remotely control an oscilloscope from your desktop.
Unlike XStreamBrowser, which works solely within the Windows COM architecture, WaveStudio can be
connected to a device over most of the available remote control interfaces—ENET (using TCP/IP or LXI),
GPIB, or USBTMC—making it a good way to test different remote connections.
Note: WaveStudio does not support LSIB connections to the instrument. Choose another remote
connection if you wish to use WaveStudio for remote control.
See the WaveStudio online help or WaveStudio User's Manual for more information.

Connecting to a Device
To use WaveStudio to make the remote connection to an oscilloscope:
1. Configure both the PC running WaveStudio and the oscilloscope to support the remote control
method you wish to use.
2. Launch WaveStudio and click the Add Scope icon
the My Scope Explorer window.

either on the Scope ribbon or at the top of

3. Select the remote control method in use.
4. Enter the oscilloscope's domain name or address, depending on the remote connection type (e.g.,
IP address for TCP/IP, GPIB address for GPIB).
5. The device should now appear in the My Scope Explorer window with a status of Alive.
If it does not appear or is not Alive, select it and click the Edit icon
the correct name or address. Change it if necessary.

. Check that you have entered

Tip: Go to Utilities > Utilities Setup > Remote on the oscilloscope to check the remote
control method and the device name or address. These must match what is entered in
WaveStudio. If DHCP is in use, the address may have changed since the oscilloscope was
originally added to WaveStudio.

1-28

Part 1: Making the Remote Connection

Sending Remote Commands
WaveStudio includes a terminal window from which you can execute IEEE 488.2 remote control
commands. Use the VBS command to send Automation commands.
1. Follow the procedure above to connect to the oscilloscope. If the device is already added to My
Scope Explorer, just select it from the list.
2. When the connection is Alive, select Terminal from the list of objects/folders belonging to the
device in My Scope Explorer.
3. At the top of the Terminal window, immediately below the words "LeCroy WaveStudio," enter the
remote command or query and Return.
Replies to queries appear in the bottom section of the Terminal window.

Automation Browser
For WaveSurfer3000 oscilloscopes, which cannot be accessed by XStreamBrowser due to differences in
the Windows operating system that preclude the necessary configuration, WaveStudio includes an
Automation Browser feature that exposes the instrument's COM object hierarchy, the same as does
XStreamBrowser for other oscilloscope models.

1-29

MAUI Oscilloscopes Remote Control and Automation Manual

1-30

Part 2: Automation Programming Reference

Part 2: Automation Programming Reference
This section is a guide to the Automation capabilities of Teledyne LeCroy’s MAUI™ (also known as
XStream) oscilloscopes.
While Teledyne LeCroy has always striven to maximize compatibility, the underlying technologies used by
Automation require the Microsoft Windows® operating system (minimum 32-bit), and this system was
introduced only with our MAUI instruments. Automation is not available on the older oscilloscope families.
These instruments can be controlled remotely using legacy IEEE 488.2 remote control commands.
Automation Overview

2-2

XStreamBrowser

2-4

Viewing/Modifying XStream Objects

2-6

VBS Command

2-10

Approach 1: Control from XStreamBrowser

2-11

Approach 2: Program in VBS

2-13

Approach 3: Program Using ActiveDSO

2-17

Approach 4: Program Using VISA

2-20

Control Variables

2-24

Result Interfaces

2-27

Exposing Result Interfaces

2-30

Synchronization

2-35

Application Interactions

2-37

Early and Late Binding

2-38

Automation Programming Rules

2-39

Automation in MATLAB

2-43

Automation in Python

2-46

Automation in C#

2-49

2-1

MAUI Oscilloscopes Remote Control and Automation Manual

Automation Overview
Automation (formerly referred to as “OLE Automation”) is a Microsoft technology that is primarily used to
enable cross-application macro programming. It is based upon the Component Object Model (COM),
which is similar in nature to CORBA more commonly found in the UNIX world. In addition to supporting the
familiar ASCII-based remote commands that have been used to control all Teledyne LeCroy oscilloscopes
for many years, all Windows-based MAUI instruments fully support control by Automation interfaces.
Using COM, the controlling application can run directly on the instrument without requiring an external
controller. Alternatively, it can run from a remote, networked computer using Microsoft’s distributed COM
standard (DCOM).
It is important to note that Automation itself is not language dependent; it can be performed using any
programming language that supports COM.

General Architecture
An application that “exposes Automation objects” is referred to as an “Automation server.” Automation
objects expose “Automation interfaces” to the controlling “Automation client.” The oscilloscope application
on MAUI oscilloscopes (XStream) is an Automation server that can be controlled locally or remotely by
Automation clients.
Automation objects can take the form of:
l

"Invisible" objects created by script, such as a Visual Basic script to change oscilloscope settings
and read back the new measurement results
Visible objects embedded in an application, such as a button that launches a macro containing an
Automation subroutine

Uses of Automation
Automation has many uses:
l

Instrument setup (panel files)

Remote Control from external Windows applications

Exposing waveform data and measurement results to external Windows applications

Custom math/measurement processing and user interface customizations (with XDEV)

This section concentrates on using Automation for remote set up, control, and waveform/data transfer,
the functions traditionally performed by GPIB remote control.

2-2

Part 2: Automation Programming Reference

Automation Compared to IEEE 488.2 Remote Control
Automation does not necessarily replace the IEEE 488.2 legacy remote command set, which is also
supported by MAUI instruments (and will continue to be). Rather, it augments it and allows another class
of application to be created that can be executed locally or remotely.
Automation, however, can be considered as the “native language” of MAUI instruments. All of the
instrument’s controls and features are available to the Automation client, whereas only some of the
instrument features have been implemented in the 488.2 remote command set.
The following table summarizes the differences between the two approaches to remote control:
IEEE 488.2 Remote Control

Automation Remote Control

Physical transport

TCP/IP and LXI over Ethernet, GPIB,
LSIB, or USBTMC*

Inter-process using COM, inter-PC using
DCOM (TCP/IP)

Textual parsing of instrument
responses required

Yes, all instrument responses need
‘parsing’ to extract useful information

No, each element in the Automation
hierarchy appears as a “variable” to the
Automation client

Compatibility with legacy
programs/instruments

Yes, in most cases remote control
applications written for legacy
instruments will work without
modification

No, Automation is a standard first
introduced with MAUI (XStream)

Ability to control the oscilloscope
application from “inside the box”

Yes, by using the VICP (TCP/IP) protocol
to talk to the “localhost”

Yes, natively

Ease of use

Not trivial, although easier using a tool
such as ActiveDSO** that hides some of
the complexities

Very easy with scripting languages and
MS Office productivity tools

Format of waveform results

Binary or ASCII; both require parsing
before use

Arrays of floating point values

Control from MS Office suite

Possible via ActiveDSO utility

Yes, natively

* Not all interfaces available on all models. GPIB and LSIB available with hardware option.
** ActiveDSO is an ActiveX based driver for Teledyne LeCroy oscilloscopes

2-3

MAUI Oscilloscopes Remote Control and Automation Manual

XStreamBrowser
The XStreamBrowser utility enables you to view, copy, and modify the COM object hierarchy of a
Windows-based MAUI™ oscilloscope from a remote PC. It is essential for writing Automation programs, as
it always shows all the Automation objects on the instrument at the exact current configuration—including
those objects belonging to software options. It can also be used as a remote control console, enabling you
to directly alter the configuration of Automation control variables.
XStreamBrowser is installed on all MAUI oscilloscopes for local browsing, but it may also be installed on
any PC for remote control. You must first allow a DCOM connection between the PC and oscilloscope,
then connect the XStreamBrowser to the device. The browser window is populated when the connection
is successful.
Note: WaveSurfer 3000 users should install the WaveStudio software instead of
XStreamBrowser. The COM object hierarchy of a connected device is shown in the WaveStudio
Automation Browser.
Caution: The version of XStreamBrowser available for download on our website is a 32-bit version
that will run on 64-bit machines. It is intended only for installation on remote PCs, not on
oscilloscopes. A 64-bit version of XStreamBrowser is already installed on 64-bit MAUI
oscilloscopes. Installing the 32-bit version over this will cause registry conflicts. Likewise, if you
have installed the 64-bit MAUI firmware on your PC, you already have a copy of the 64-bit
XStreamBrowser. If it was uninstalled, reinstall the MAUI firmware, rather than install the 32-bit
version of XStreamBrowser.

Connecting to a Local Device
To launch XStreamBrowser on the oscilloscope:
1. Choose File->Minimize to display the Windows desktop.
2. Double-click the XStream Browser icon.
3. Select the

connection icon.

Connecting to a Remote Device
1. Be sure the device is configured to allow a DCOM connection from the PC.
2. Launch the XStreamBrowser.
3. Select the

connection icon.

4. Enter the network IP Addressof the device, then click OK.

2-4

Part 2: Automation Programming Reference
Note: Use the IP Address, not the DNS or UNC name. If the oscilloscope application of the device
is not running, initiating the connection from XStreamBrowser will start it; however, it will not
power on a device that is powered off. Be sure the device is turned on before connecting.
When the connection to a device is established, the XStreamBrowser window is populated with the
oscilloscope application object hierarchy.

Root application object hierarchy of XStream, the "engine" of MAUI oscilloscopes.

Refreshing the Display
If you change the state of the oscilloscope in any way while connected to XStreamBrowser, select the
icon to refresh the object hierarchy. While settings you "push" from XStreamBrowser will appear
immediately, settings changed elsewhere must be "pulled" into the XStreamBrowser browser display.

Disconnecting
Only one connection may be made at one time. To disconnect from the device, choose
File > Close Session.
Use the window closebox or choose File > Exit to close the XStreamBrowser application.

2-5

MAUI Oscilloscopes Remote Control and Automation Manual

Viewing/Modifying XStream Objects
The number of different objects in a complete oscilloscope setup is obviously large and changes with the
installation of new firmware and software options. XStreamBrowser helps you quickly find the object path
and valid values corresponding to any instrument control.
The object hierarchy exposed by MAUI instruments is rooted at the Application object. This object is
always named LeCroy.XStreamDSO.
All major instrument subsystems are available from this object, and many of these subsystems
themselves may be broken down further. As new software options are activated on the oscilloscope,
these subsystems are added to the Application object hierarchy.
Anything exposed by the object hierarchy can be controlled or read back via Automation.

Object Hierarchy
The left-hand pane of the XStreamBrowser window contains an
expandable navigation "tree." The object hierarchy is tiered; for
example, the Acquisition subsystem is comprised of a variety of
objects, each with child objects.
The right-hand pane shows the Control Variables or Properties
related to the object selected from the navigation tree.

Control Variables
The majority of the items you will find as you expand the navigation tree are Control Variables, or CVARs
for short. These are shown as yellow folders in the XStreamBrowser window.
CVARs provide an interface for accessing scope configurations and for executing methods and actions.
When viewed from XStreamBrowser, many CVARs appear to be properties, but are actually objects with
properties such as Name, Value, and Type, to name a few. See Control Variables for a description of CVAR
Types, Properties, and Methods.

2-6

Part 2: Automation Programming Reference

CVAR properties shown in the right-hand pane of XStreamBrowser window.

The Range/Helpstring column provides short form information about the possible values the variable can
take.
The Flags/Status column contains coded information about the object.
Flag/Status

Indicates

For CVARs: Read only.
For Properties: Readable.

For CVARs: Wrapping, incrementing the value will "wrap around" from max. to min., or vice versa.
For Properties: Writable.

Hidden: not visible on any GUI dialog or menu.

Grey: appears "greyed out" on GUI indicating it is
disabled or not settable.

Backwards: incrementing the CVAR value will decrease the value.

Nonvolatile: value is saved in the application's "nonvolatile" settings file. These CVARs are typically
user preferences and are not affected by Recall Default Setup.

AutoRepeat: the CVAR action should be repeated if a button on the GUI is held down.

MultiLine: the CVAR value may be rendered on
multiple lines of the GUI.

LateUpdate: the CVAR value may be updated when it is read/refreshed.

2-7

MAUI Oscilloscopes Remote Control and Automation Manual

Actions and Methods
Besides the configuration CVARs, automation also provides for Actions that may be applied at the
application or subsystem level.
For example, to clear sweeps for all subsystems, the Automation command would be:
app.ClearSweeps

Methods are similar to Actions but may take parameters from the caller and may possibly return a value,
whereas, Actions do not support any parameters or return values. An example of a Method is
app.Acquisition.Acquire, which takes both "timeout" and "force trigger" arguments.

Result Interfaces
The grey folders are Result Interfaces. Result Interfaces contain more than just the basic results of
oscilloscope operations, such as waveform data and measurement values; they include information about
horizontal and vertical resolution, event times, number of sweeps, histogram peaks, etc. The Type column
of the XStreamBrowser window shows the result interface type. See Result Interfaces for a description of
the Types and Variables.

Collections
Collections, which are shown as pink folders in XStreamBrowser, contain sets of similar objects. For
example, the app.Acquisition.Channels collection contains input channel objects (C1, C2, etc.). Objects in
Collections folders are dynamically linked to those in the yellow folders; changing the value in either place
changes it everywhere. Collection subfolders are referenced by indexing the collection name with the
subfolder name.

2-8

Part 2: Automation Programming Reference

Copying from XStreamBrowser
When a variable is selected from the right-hand pane, the message bar at the bottom of the screen shows
the full object path in correct notation for sending as an Automation command:

Right-click and choose Copy Path. The text is automatically placed in the clipboard, from where it can be
easily copied into remote control programs.

2-9

MAUI Oscilloscopes Remote Control and Automation Manual

VBS Command
For users who wish to harness the power of Automation, but are currently using “traditional” GPIB remote
control commands, there is a solution: the VBS command. This will enable you to control the advanced
features of MAUI oscilloscopes that are not supported by GPIB commands.
VBS is also used to encapsulate Automation commands whenever there is a remote connection to the
oscilloscope other than DCOM (ActiveDSO, VISA driver, etc.).
Below are two, equivalent methods for setting the V/Div of Channel 1. The first examples uses a GPIB
command, VDIV; the second uses the VBS command:
C1:VDIV 0.5
VBS 'app.Acquisition.C1.VerScale = 0.5'

In its query form, the following are equivalent:
C1:VDIV?
VBS? 'return = app.Acquisition.C1.VerScale'

Note: For the query form, including 'return = object' is important, as it indicates which value you
wish to be returned to the caller.
The VBS Command/Query is documented in more detail in the GPIB command reference.

2-10

Part 2: Automation Programming Reference

Approach 1: Control from XStreamBrowser
When a PC has a DCOM connection to a networked oscilloscope, a copy of XStreamBrowser running on
the PC has the same read/write capabilities as the version that is running locally on the oscilloscope. The
oscilloscope's entire XStream object hierarchy is exposed and editable from XStreamBrowser. This is
perhaps the simplest way to remotely control the oscilloscope.
This exercise modifies the oscilloscope channel C1 Vertical Scale setting directly from XStreamBrowser
installed on the PC.

Make the Connection
1. Connect the oscilloscope to your LAN, or directly to the PC using a cross-over cable.
2. Turn on the oscilloscope and go to Utilities > Utilities Setup > Remote and choose control from
TCP/IP.
3. Create a DCOM connection to the oscilloscope.
4. Download and install a copy of XStreamBrowser on the PC.
5. Open XStreamBrowser on the PC and connect to the oscilloscope.
6. When the oscilloscope appears in the Devices list, click on it to show the application hierarchy.

Find and Modify the Object
The Vertical settings associated with channels are part of the Acquisition subsystem, as they control the
characteristics of the ADCs at the input, directly affecting acquisition.
Since we're looking to modify a setting that affects the Acquisition subsystem, expand the Acquisition
folder to display the C1 object. Select the C1 object folder so that the C1 CVARs appear in the right-hand
window pane.
As you scroll down, you'll see the VerScale CVAR, showing whatever value was last set for that channel on
the oscilloscope, in this example, 50.0 mV.

XStreamBrowser tell us the following about this control:
l

The Type column shows it is a DoubleLockstep
The Flags/Status column shows B, meaning it is Backwards and incrementing the CVAR will
decrease the value.

2-11

MAUI Oscilloscopes Remote Control and Automation Manual
l

The Range/Helpstring column shows an acceptable range of 0.002 to 1 step 0.0005. meaning it
can be set anywhere from 0.002 to 1 in increments as small as .0005. If Variable Gain is left on, the
next value possible is 0.0025.
The additional statement that it is "locked to 1 2 5, fine grain..." is fully visible if we right-click on the
VerScale line and choose Copy to display the Set Control Variable dialog:

While fine grain (Variable Gain) adjustments are allowed on this oscilloscope (true), the Var. Gain
setting is currently off (on=false), so the control would adjust in stepped increments of 1, 2, or 5
units (in sequence) were it being operated from the oscilloscope touch screen. Starting at 0.002,
the next value would be 0.005.
Enter a new Value of 100 mV and choose to Set this value.
Back on the XStreamBrowser window, you will see that the C1 VerScale setting has changed:

And the oscilloscope immediately reflects this change, as well:

Note that here we can see the Var. Gain setting is deselected.
That's all that is required to remotely set up a MAUI oscilloscope from your PC.

2-12

Part 2: Automation Programming Reference

Approach 2: Program in VBS
Setup (or Panel) files, which are used to save and recall the state of the instrument between sessions, are
traditionally binary files with an internal structure that is neither documented nor obvious to the user. In
MAUI oscilloscopes, however, this is not the case. Setups are ASCII text files that contain a complete
Visual Basic Script “program”. In effect, each time a panel is saved, the instrument writes a program that,
when executed, returns the instrument to the saved state.
VBS programs function like Setup files that are written and executed remotely.
Note: Setup files stored by the instrument have file extension “.lss” (LeCroy Setup Script). These
files are syntactically identical to Microsoft VBS files, which have a “.vbs” extension.
In this exercise, we'll create and execute a simple VBS program on the PC that:
l

Connects to a networked oscilloscope

Performs an AutoSetup

Changes the oscilloscope grid mode

Reads back the Grid Mode and Vertical Scale

Disconnects

Preliminary Setup
1. As with Exercise 1, it is assumed there is a DCOM connection between the PC and an oscilloscope
on the same network, and that XStreamBrowser is installed on the PC.
2. On the oscilloscope, go to Utilities > Utilities Setup > Remote and confirm that the TCP/IP (VICP)
setting is selected. Note the oscilloscope's IP address.
3. Open XStreamBrowser and NotePad or another text editor on the PC.

Program
Note: Characters in angle brackets are placeholders. Omit the brackets from your code.

Connect
CreateObject is the Visual Basic function that creates an instance of a COM Server. The argument
“LeCroy.XStreamDSO” refers to the oscilloscope application. Once it has instantiated (connected to) the
oscilloscope application, it requires some kind of ‘handle’ (pointer) so that it can later be used to
communicate with the instrument. CreateObject returns a handle, which is stored in the app variable.
In the text editor, write the VBS connect string:
Set app = CreateObject("LeCroy.XStreamDSO")

2-13

MAUI Oscilloscopes Remote Control and Automation Manual
Note: Only a single instance of the XStream software can run on a system at one time. If the
software is already running when CreateObject is called, a handle to that running instance is
returned. If XStream is not running, it will be started.

AutoSetup
AutoSetup is an Action that utilizes default Vertical and Timebase settings and a 50% level Edge trigger to
quickly set up an acquisition on the oscilloscope. The first active input channel is used as the triggger
source.
AutoSetup occurs "above" the individual subsystems in the XStream application hierarchy, at the root
object LeCroy.XStream.DSO. In XStreamBrowser, you will find it in the root folder. Had this command
involved only C1, for example, you would have navigated to Acquisition > C1 and selected it to show the C1
CVARs.

You can see AutoSetup is an Action from the Type column. Most of what occurs at this top level are
Actions.
Right-click on AutoSetup and choose Copy Path.
Go back to the text editor window, and paste the AutoSetup command into your program:
app.AutoSetup

Change Grid Mode
The Grid Mode determines how many grids appear on the oscilloscope display at once. This is one setting
where a change can be perceived without an input signal. Grid Mode affects the oscilloscope display, so it
is found within the Display subsystem.
In XStreamBrowser, expand the Display folder until you see the CVARs in the right-hand window pane.
Navigate to the object GridMode. You can see the valid settings in Range/Helpstring include Auto, Single,
Dual, Quad, etc.
Right-click on GridMode and choose Copy Path. You'll see from the XStreamBrowser window message
bar that the object path is:
app.Display.GridMode

Note that the controls are arranged in a hierarchy, with each level delimited by a decimal point ( . ).
Paste the line into your remote control program, then set the new value of Quattro:
app.Display.GridMode = “Quattro”

2-14

Part 2: Automation Programming Reference
Using the app handle, this line of code sets the Grid Mode control of the Display system to the value
“Quattro”.
Note: WaveSurfer 3000, WaveSurfer 10, and HDO4000 oscilloscopes only support Auto, Single,
and XY Grid Modes. You can choose any of these for the exercise, but note that if you go from
Auto to Single, the change will only be evident by looking at the Display setup dialog.

Read Back Grid Mode and Vertical Scale
Create a variable to read back the value currently set in the equivalent control. In the text editor, write the
line:
myGridMode = app.Display.GridMode

This line of code retrieves the current value of the app.Display.GridMode CVAR and stores it within the
variable myGridMode.
Note: In Visual Basic Script it is not necessary to “Dimension” variables before using them (for
example, using statements like “Dim myVerScale as Double”).
To get the value of the C1 Vertical Scale, create a new line for the variable myVerScale.
In XStreamBrowser, navigate to the Acquisition > C1 folder and click on it to show the CVARs. Right click
on VerScale and Copy Path. Paste it behind the "myVerScale" variable:
myVerScale = app.Acquisition.C1.VerScale

For this exercise, the "read back" method will be the standard Visual Basic Message Box dialog. Add two
lines using the MsgBox function to display the values of the two variables you created:
MsgBox myGridMode
MsgBox myVerScale

Disconnect
Add a line of code to end the program and close the connection to the oscilloscope:
Set app = Nothing

2-15

MAUI Oscilloscopes Remote Control and Automation Manual

Execute
You should see the following script in your text editor:
'Connect to the XStream application
Set app = CreateObject("LeCroy.XStreamDSO")
'Perform action AutoSetup and change grid mode setting
app.AutoSetup
app.Display.GridMode = "Quattro"
'Read back grid mode and vertical scale
myGridMode = app.Display.GridMode
myVerScale = app.Acquisition.C1.VerScale
MsgBox myGridMode
MsgBox myVerScale
'Disconnect
Set app = Nothing

Save the file as Exercise2.vbs.
Open Windows Explorer and navigate to Exercise2.vbs. Double-click on the file to execute it.
If these steps were followed correctly, you should observe the oscilloscope perform an AutoSetup and
enter the Quattro-grid display mode. The new grid mode will be evident from the four grids, one in each
quadrant of the display.

2-16

Part 2: Automation Programming Reference

Approach 3: Program Using ActiveDSO
As not all controllers can utilize the Windows DCOM architecture, there is another simplified method for
remote control of the XStream application: ActiveDSO, Teledyne LeCroy's proprietary Active-X control.
ActiveDSO can be used for much more than just remote control programs, but this exercise shows how
the same Automation commands used for remote control in Exercise 2 could be sent using ActiveDSO,
instead.
ActiveDSO also has the advantage of working with programming languages besides Visual Basic, such as
Python and Visual C++, making it easy to utilize as a remote control/waveform transfer subroutine within
other programs, or as part of a custom remote control interface. For more information, see the ActiveDSO
topic in the "Making the Remote Connection" section.

Preliminary Setup
1. Download ActiveDSO from teledynelecroy.com (see Resources) and install it on the PC.
2. Open XStreamBrowser and NotePad or another text editor on the PC.
3. Turn on the oscilloscope. For this exercise, we'll continue to use VBS and a LAN connection, so
confirm the oscilloscope is connected to LAN (or has a cross-over connection to your PC).
4. Go to Utilities > Utilities Setup > Remote and confirm the TCP/IP (VICP) setting.
5. Note the oscilloscope's IP address.

Program
Note: Characters in angle brackets are placeholders. Omit the brackets from your code.

Connect
In the text editor, instantiate the ActiveDSO control:
Set dso = CreateObject("LeCroy.ActiveDSOCtrl.1")

Then, invoke the MakeConnect method, in this case using the oscilloscope's IP address:
Call dso.MakeConnection("IP:")

This method could have used USBTMC, GPIB, or any other supported connection type. You would want to
be sure to choose control from that same interface on the oscilloscope Remote dialog.

AutoSetup
Besides the instantiation method, the most obvious difference between using native VBS and using
ActiveDSO is in how commands are sent. With ActiveDSO, Automation controls are nested within the VBS
command. Write the line:
Call dso.WriteString("VBS 'app.AutoSetup'", 1)

The Boolean "1" is telling the XStream application to interpret the command immediately.

2-17

MAUI Oscilloscopes Remote Control and Automation Manual
You could also use WriteString with the legacy IEEE 488.2 command set. For example, write:
Call dso.WriteString("C1:VDIV 200 mV", 1)

This command will reset the Vertical Scale, same as did the "app.C1.VerScale" Automation command sent
in Exercise 1. Either legacy commands or VBS Automation commands can be sent using WriteString.

Change Grid Mode
Add another line to the program to change the Grid Mode from Quattro back to Auto, or any other grid
mode supported by your oscilloscope model:
Call dso.WriteString("VBS 'app.Display.GridMode = "Auto"'", 1)

If you wish, add lines for any other setup changes you'd like to make, using the XStreamBrowser to find the
CVAR and copying the path into the VBS command.

Read Back Grid Mode and Vertical Scale
There are several ActiveDSO methods to read back parameter results and waveform data, but a simple
way to read setup values is to use the VBS? query with the Automation control.
In your program, write:
Call dso.WriteString("VBS? 'app.Display.GridMode'", 1)
Call.dso.WriteString("VBS? 'app.Acquisition.C1.VerScale'", 1)

Notice we're still using WriteString to "read back," as what we're doing is writing the string that is the VBS
query. The query, by its nature, returns information. Again, we're including the Boolean 1 that tells the
oscilloscope to interpret the instruction immediately.
What we still need to specify is how to display the result text:
Call dso.WriteString("VBS? 'return = app.Acquisition.C1.VerScale'", 1)
myString = ReadString(numbytes)
MsgBox (myString)

Disconnect
Write the following lines to disconnect from the XStream application and end the program:
dso.Disconnect
Set dso = Nothing

2-18

Part 2: Automation Programming Reference

Execute
You should now see the following program, or similar, in your text editor:
'Connect to the XStream application
Dim dso As Object
Set dso = CreateObject("LeCroy.ActiveDSOCtrl.1")
Call dso.MakeConnection("IP:")
'Send commands to AutoSetup, change grid mode and vertical scale
Call dso.WriteString("VBS 'app.AutoSetup'", 1)
Call dso.WriteString("C1:VDIV 200 mV", 1)
Call dso.WriteString("VBS 'app.Display.GridMode = "Auto"'", 1)
'Query grid mode and vertical scale, show result in Message Box
Call dso.WriteString("VBS? 'app.Display.GridMode'", 1)
Call.dso.WriteString("VBS? 'app.Acquisition.C1.VerScale'", 1)
Call dso.WriteString("VBS? 'return = app.Acquisition.C1.VerScale'", 1)
myString = ReadString(numbytes)
MsgBox (myString)
'Disconnect
dso.Disconnect
Set dso = Nothing

Save the file as Exercise3.vbs.
Open Windows Explorer and navigate to Exercise3.vbs. Double-click on the file to execute it.
If these steps were followed correctly, you should again observe the oscilloscope perform an AutoSetup
then change display mode and vertical scale. Check the C1 descriptor box to see that the Vertical Scale
has changed.

2-19

MAUI Oscilloscopes Remote Control and Automation Manual

Approach 4: Program Using VISA
If you do not wish to utilize ActiveX controls like ActiveDSO, any programming language that can connect
through VISA can be used to send Automation commands. Teledyne LeCroy oscilloscopes are designed to
work with VISA drivers for ENET, USBTMC, or GPIB remote connections. It is not necessary to have a
DCOM connection when you are using a VISA driver.
In this exercise, we'll create a Python script designed to connect over the LAN, as in the previous exercise,
but using LXI remote control settings.
Note: All the code examples given here use the LXI VISA resource string, not the TCP/IP VISA
resource string. Both the TCP/IP and LXI settings utilize the TCP/IP layer, but the higher-level
protocol is different, as is the VISA resource string. You can use the LXI option to communicate
with the oscilloscopes even if your network is not set up to be LXI compliant.

Preliminary Setup
This exercise requires a bit more setup than the previous, but by doing so, it will better demonstrate how
you may use Automation to set up and retrieve measurement data.
1. On the PC, install a VISA driver , Python, and the compatible Python for Windows extensions.
2. Turn on the oscilloscope. Be sure it is connected to your LAN (do not use a cross-over cable for this
exercise).
3. Connect one of the passive probes delivered with your oscilloscope to the Cal Out/Aux Out on the
front of the instrument (what it is named will vary by model) and the C1 input.
4. Go to Utilities > Utilities Setup > Aux Output and choose to output a 1 KHz, 1 Volt Square Wave
or whatever is the default selection for your oscilloscope (there should be a button).
5. Adjust your timebase until you see a stable pulse on the oscilloscope.
6. Go to Utilities > Utilities Setup > Remote and select the LXI (VXI-11) setting. Note the
oscilloscope's IP address.
7. On the PC, open XStreamBrowser and Notepad or another text editor.

2-20

Part 2: Automation Programming Reference

Program
Note: Characters in angle brackets are placeholders. Omit the brackets from your code.

Connect to the Oscilloscope
In your text editor, write these lines to make the remote connection to VISA and to the oscilloscope:
import visa
rm = visa.ResourceManager()
lecroy = rm.open_resource("TCPIP0::::INSTR")
lecroy.timeout = 5000
lecroy.clear()

If your oscilloscope and PC are both known to the same network name server, you can use the hostname
syntax (e.g., "TCPIP0::LCRY0450N70355::INSTR") instead of the actual IP address.
The timeout of 5000 milliseconds ensures the oscilloscope will wait 5000 milliseconds for operations to
complete whenever writing commands or reading responses. Reading continues until the entire response
is received (EOI is reached) or for 5 full seconds. After 5 seconds, there will be a "time out" error.
The clear is intended to clear out the buffers on the oscilloscope listing the commands sent to it and also
responses sent from it. Clear removes anything leftover from a previous use and is a good practice as a
first step in any program.
Several other preliminary settings can be made to prepare the general oscilloscope "environment" prior to
writing new setups or reading measurements. In your program, type:
lecroy.write("COMM_HEADER OFF")
lecroy.write(r"""vbs 'app.settodefaultsetup' """)

The command "COMM_HEADER OFF" is a legacy 488.2 command that tells the oscilloscope "don't return
the command header with query result." This helps to read back values in a format that is more friendly to
being viewed on screen or imported into other programs.
Recalling the default setup, while not required, ensures that all setups are at a known baseline value before
you begin.
Notice that the method 'app.settodefaultsetup' is the first actual Automation command being passed to
the oscilloscope. It is enclosed in the VBS command wrapper, as are all Automation commands sent by
remote connection, rather than through a COM/DCOM connection.
Note: The triple quotes around the VBS command are required because quotes around the values
within the command could be interpreted by Python as the end of the command string. You would
probably create a function to put the VBS wrapper around whatever automation commands you
wanted to send. Here, we're showing each full line of code for demonstration.

2-21

MAUI Oscilloscopes Remote Control and Automation Manual

Timing and Synchronization
In any remote control program, it is important to set up "checks," periodically querying that processes are
complete before starting new ones, or that old measurements are cleared before taking new ones, etc.
Querying the 'app.WaitUntilIdle' method can tell your program when it is safe to proceed.
In your program, enter the query:
r = lecroy.query(r"""vbs? 'return=app.WaitUntilIdle(5)' """)

This will inform the program when the Recall Default setup has been completed and the oscilloscope
application is idle for 5 milliseconds (the default unit for this command) before going on to set up the new
acquisition.

Set Up Acquisition
Every program that is to acquire new data, whether raw waveform data or post-processing measurement
results, must set up an acquisition. It is important before taking any new acquisition to stop the previous
one. Failure to do this is a principal reason for inaccurate measurements. Add the line:
lecroy.write(r"""vbs 'app.acquisition.triggermode = "stopped" ' """)

Using XStreamBrowser, find suitable replacements for in following acquisition CVARs, and add
these lines to your program:
lecroy.write(r"""vbs 'app.acquisition.trigger.edge.level = ' """)
lecroy.write(r"""vbs 'app.acquisition.triggermode = "single" ' """)
lecroy.write(r"""vbs 'app.acquisition.horizontal.maximize = "" ' """)

Be sure not to forget the double quotes around those values that are String or Enum types.

Set Up Measurements
As with the default setup, it is a good idea to clear all measurement definitions and previous sweeps before
proceeding with new measurements:
lecroy.write(r"""vbs 'app.measure.clearall ' """)
lecroy.write(r"""vbs 'app.measure.clearsweeps ' """)

As you may have noticed by now, Automation commands are more granular than legacy 488.2
commands. Generally, more lines of code must be sent to achieve the same end result, because every
relevant application object must be set to a particular state. However, this granularity is also what makes
Automation more powerful.
To set up measurements, we have to first turn on measurements, then turn on statistics, then turn on the
parameter, then set what we want the parameter to measure, then set the parameter source (what input
it will measure), etc. Using XStreamBrowser, find a suitable for 'app.measure.p1.paramengine'.
Tip: Select a single source measurement appropriate to your 1 KHz, 1 V pulse wave.
lecroy.write(r"""vbs 'app.measure.showmeasure = true ' """)
lecroy.write(r"""vbs 'app.measure.statson = true ' """)
lecroy.write(r"""vbs 'app.measure.p1.view = true ' """)

2-22

Part 2: Automation Programming Reference
lecroy.write(r"""vbs 'app.measure.p1.paramengine = "" ' """)
lecroy.write(r"""vbs 'app.measure.p1.source1 = "C1" ' """)

Acquire
Now write code to arm the acquisition. Again, timing is important: this example takes 10 acquisitions,
forcing a trigger if none occurs after 0.1 seconds (the second and first arguments, respectively, of
'app.acquisition.acquire'), then uses the 'app.WaitUnitIdle' method to wait for 5 seconds after all
acquisition processing is complete before measuring.
for i in range(0,10):
r = lecroy.query(r"""vbs? 'return=app.acquisition.acquire( 0.1 , True )' """)
r = lecroy.query(r"""vbs? 'return=app.WaitUntilIdle(5)' """)
if r==0:
print "Time out from WaitUntilIdle, return = {0}".format(r)

Read Back Measurement Results
Read the Out.Result object of the P1 parameter into a variable of your choosing, and print the value.
Just as the Automation commands were sent within the VBS command wrapper, the Automation query is
sent within the VBS? query wrapper. For , you can substitute the name of the measurement you
choose earlier.
= lecroy.query(r"""vbs? 'return=app.measure.p1.out.result.value' """)
print " = {0}".format()

Disconnect
Finally, close the remote connections to the scope and to VISA, in the reverse of the order in which you
opened them:
lecroy.close()
rm.close()

Execute
Save the file as Exercise4.py. Navigate to the file on your PC and execute it.
If these steps were followed correctly, you should observe the oscilloscope resume the Default Setup. The
Measure table should appear below the waveform, showing the results of the measurement you set in P1.
Meanwhile, the following should appear in your console:
Time out from WaitUntilIdle =
=

2-23

MAUI Oscilloscopes Remote Control and Automation Manual

Control Variables
Traditionally, properties presented to an Automation client are simple “variables” with types such as
Integer (int), String (BSTR), Floating Point (single, double), etc. However, on MAUI oscilloscopes, CVARs
are an extension of the traditional Automation pattern, without affecting how they appear to most
Automation clients (see the topic on early/late binding). This enables an Automation client to not only set
and query the current value of a control, but also to query its limits. This is useful in the generation of
instrument-independent applications, or applications that present scope controls in a graphical user
interface in which limits are required.
Take a CVAR such as VerScale (Volts/Div). This may be set and queried in Visual Basic as follows:
app.Acquisition.C1.VerScale = 0.5
CurrentValue = app.Acquisition.C1.VerScale

The following are also supported:
minValue = app.Acquisition.C1.VerScale.GetMinValue
maxValue = app.Acquisition.C1.VerScale.GetMaxValue

Control Variable Types
Control variable type designations are defined as follows:
Type

Definition

Action

Action (no arguments or value)

Bool

Boolean value given as { false| true} or { 0| -1 }

Color

RGB value triplex "R,G,B"

Double

Double-precision floating point value

DoubleLockstep

Double-precision floating point value locked to a non- linear (e.g., 1, 2, 5) stepped sequence.

Enum

List value (e.g., “Orange,” “Apple,” “Pear”)

FileName

Legal DOS path

Integer

32-bit Integer value

String

String value

The Type column of the XStreamBrowser window shows the control type.

2-24

Part 2: Automation Programming Reference

Properties and Methods
The properties and methods available for each control are type-specific. Listed below are the most
commonly used:
Type

Properties and Methods

Integer

VARIANT Value
Value(VARIANT)
int GetAdaptedValue
SetRequestedValue(int)
int GetRequestedValue
int GetDefaultValue
int GetGrain
int GetMax
int GetMin
Increment(int)

Double

VARIANT Value
Value(VARIANT)
double GetAdaptedValue
SetRequestedValue(double)
double GetRequestedValue
double GetDefaultValue
double GetGrainValue
double GetMaxValue
double GetMinValue
Increment(int)

DoubleLockstep

See Double

Enum

VARIANT Value
Value(VARIANT)
int GetAdaptedValue
SetRequestedValue(int)
int GetRequestedValue
int GetDefaultValue
int GetMax int GetMin
int GetNumberOfValueStates
Increment(int)
BSTR GetRangeStringScreen
BSTR GetRangeStringRemote

String

VARIANT Value
Value(VARIANT)
int GetMaxLength
BSTR GetRequestedValue
BSTR GetAdaptedValue
SetRequestedValue(BSTR)

2-25

MAUI Oscilloscopes Remote Control and Automation Manual
Type

Properties and Methods

Bool

VARIANT Value
Value(VARIANT)
BOOL GetAdaptedValue
BOOL GetRequestedValue
BOOL GetDefaultValue
Set
Clear

Action

2-26

ActNow

Part 2: Automation Programming Reference

Result Interfaces
"Out.Result" properties are results of the last completed acquisition. They are not affected if other controls
are changed after that acquisition was completed. This distinction between "Out.Result" properties and
other controls is most important when the trigger mode is Single or Stopped. You should treat "Out.Result"
properties as read-only.
Tip: In almost all remote control applications, it is highly recommended that you STOP acquisitions
before accessing result data. Most remote control problems are caused by failure to follow this
practice.
Several of the Out.Result properties mention the "frame": this is the term used to describe the visible
portion of the trace, which is generally smaller than the acquired waveform. The frame could be used, for
example, to display a 500 point window onto a 1Mpt. trace, or to show the Vertical center 10 mV of a 100
mV peak trace.
Several properties, most significantly the DataArray object, are variants containing either a one or two
dimensional array. Dimension the target variable as a variant type, and assign the DataArray property to it.
See DataArray for examples of its use within each of the Result interfaces.

Result Interface Types
Result Interface type designations are as follows:
TYPE

DEFINITION

Digital

Digital (bi-state) waveform generated by mixed-signal oscilloscope.

Histogram

Histogram trace.

Param

Individual results and result arrays for measurement parameters and Pass/Fail test qualifiers.

Persist

Eye diagrams or other waveshapes that are the result of overlaying multiple waveforms.

Table

Tabular results primarily used in conjunction with the various low-speed serial decoding options.

Waveform

Basic Voltage vs. Time waveforms.

XY waveforms.

Digital
The Digital interface is found when using one of the mixed-signal oscilloscope options to generate digital
(bi-state) waveforms. These waveforms are contained in the Digitalx trace name, where x = 1, 2, 3 etc.
Each Digitalx trace is a bus that may contain multiple digital lines, with a maximum number dependent on
the capabilities of the mixed-signal oscilloscope option. The key property in the Digital interface is the
DataArray, which is a 2D array containing the value of each sample of each digital line in the bus.
Example paths to Digital Result interfaces:
app.LogicAnalyzer.Digital1.Out.Result
app.LogicAnalyzer.Digital2.Out.Result

2-27

MAUI Oscilloscopes Remote Control and Automation Manual

Histogram
The Histogram interface is used for all histogram traces. Histograms can be configured on most
oscilloscopes as a math function (Fx). Histograms are also used in various analysis modes, especially on
Serial Data Analyzers, where the HTIE trace is the source data for the algorithm to calculate Total jitter
(Tj). The key property is BinPopulations, which is a 1D array of the bin populations.
Example paths to HTIE Result interfaces:
app.Math.F1.Out.Result
app.SDA.Htie.Out.Result

Note: This example assumes that F1 is set up as a Histogram.

Param
The Parameter interface is used in the Measurement and Pass/Fail systems to hold both individual results
and result arrays. The key properties for the Parameter interface are Value and ValueArray. Value holds
the last measurement or P/F result, while ValueArray holds all measurements taken for the last
acquisition.
Example paths to Param Result interfaces:
app.Measure.P1.Out.Result
app.Measure.P1.Sdev.Result
app.Measure.Measure("P1").Out.Result

Persist
The Persist interface is most often found when using software options that create eye diagrams or other
waveshapes that are the result of overlaying multiple waveforms. (Note that this does not apply to the
Persistence display mode.) The key property in the Persist interface is the DataArray, which is a 2D array
containing the population of each pixel of the persistance map.
Example paths to Persist Result interfaces:
app.SDA.Eye.Out.Result
app.SDA.Eye2.Out.Result

Table
Table results interfaces are used primarily used in conjunction with the various low-speed serial decoding
options, such as CAN, I2C, SPI, UART, etc. When the table is displayed, the user has access to information
about the messages decoded for the last acquisition. Retrieving data from the Table interface involves
some knowledge of the table’s structure, in terms of the columns that are displayed and the cell types.
The CellType and CallValue are the key properties to use to retrieve the table’s data. See the information in
the CellValue property for more information.

2-28

Part 2: Automation Programming Reference
Example paths to Table Result interfaces:
app.SerialDecode.Decode1.Out.Result.
app.SerialDecode.Objects("Decode2").Out.Result

Waveform
Waveform Results interfaces can be found wherever there are basic Voltage vs. Time waveforms.
Examples include channel (Cx), memory (Mx), math function (Fx) and zoom (Zx) traces, as well as others
that are associated with specific analysis packages, such as the Power waveform used in the PMA2
package. In general, these waveforms are usual voltage vs time, unless a current probe or other method of
changing the vertical units (e.g. the Rescale Math function) is employed. The key property in the
Waveform interface is the DataArray, which is a 1D array containing the value of each sample in the
waveform.
Example paths to Waveform Result interfaces:
app.Acquisition.C1.Out.Result
app.Acquisition.Channels("C1").Out.Result
app.Math.F2.Out.Result
app.Zoom.Z3.Out.Result
app.SDA.Btub.Out.Result

Note: Traces like F2 and Z3 can hold waveforms like histograms, which do not use the Waveform
interface.

XY
The XY interface is used on XY waveforms. Users can create an XY waveform by selecting this option in
the Display Setup… screen. XY waveforms allow you to see how the signal on one channel moves in
relation to another. The key property is the DataArray, which is a 2D array that returns the voltages on the
X and Y sources for each XY pair.
Example path to the XY Result interface:
app.Math.XY.Out.Result

Result Variable Types
TYPE

DEFINITION

Integer

16-bit signed integer

Long

32-bit signed integer

Double

8-byte floating point type

String

Array of characters

Object

Object with its own interface

Variant

Variable that is dimensioned without indicating a variable type

2-29

MAUI Oscilloscopes Remote Control and Automation Manual

Exposing Result Interfaces
Waveform Data
Waveform data is exposed as a simple array, no deciphering of proprietary binary formats is performed, as
was necessary in the past.
This example is coded as an Excel macro in VBA that would be assigned to a button. The macro reads the
number of samples in the waveform and places it in cell B1 of the Excel spreadsheet. It then reads all
available sample data values and copies them into cells in the first column (A) of the spreadsheet
(A1...Axx). The green comment text explains what each section of the script accomplishes.
Sub Button1_Click()
' Connect to the oscilloscope
Set app = CreateObject("LeCroy.XStreamDSO")
' Query the number of samples in C1 and store in cell "B1"
numSamples = app.Acquisition.C1.Out.Result.Samples
Cells(1, 2)
Value = numSamples
' Access waveform data array, fill first column of the spreadsheet
wave = app.Acquisition.C1.Out.Result.DataArray
For i = 0 To numSamples - 1
Cells(i + 1, 1).Value = wave(i)
Next i
End Sub

Note: When moving result data into Excel, ensure that the record length is < 64 k samples, since
Excel has a limit on the number of rows in a spreadsheet. Ideally, you should start experimenting
with short (500 point) records.

Result Status
The waveform result object described above includes a status property (bit-field) that reflects the current
status of the trace. This includes both ‘warning’ and ‘error’ conditions, as described below.

2-30

Part 2: Automation Programming Reference
Description

Value

Bit #

LEC_Valid

0x0

N/A

LEC_Invalid

0x0000000000001

LEC_Overflow

0x0000000000002

LEC_Underflow

0x0000000000004

LEC_ContainsUndefinedValues

0x0000000000008

LEC_LessThan

0x0000000000010

LEC_GreaterThan

0x0000000000020

LEC_NotAPulse

0x0000000000040

LEC_NotCyclic

0x0000000000080

LEC_Averaged

0x0000000000100

LEC_UnlockedPLL

0x0000000000200

LEC_OtherError

0x0000000000400

LEC_OtherWarning

0x0000000000800

LEC_OtherInfo

0x0000000001000

LEC_InputsIncompatible

0x0000100000000

LEC_AlgorithmLimitsReached

0x0000200000000

LEC_BadDefinition

0x0000400000000

LEC_TooFewData

0x0000800000000

LEC_TooManyData

0x0001000000000

LEC_UniformHorizIntervalRequired

0x0002000000000

LEC_BadUnits

0x0004000000000

LEC_DataRangeTooLow

0x0008000000000

LEC_DataUndersampled

0x0010000000000

LEC_PoorStatistics

0x0020000000000

LEC_SlowTransitionTime

0x0040000000000

LEC_DataResampled

0x0080000000000

LEC_DataInterpolated

0x0100000000000

LEC_MeasurementScaleImprecise

0x0200000000000

LEC_NoDataAvailable

0x0400000000000

LEC_SomeCummulatedResultsInvalid

0x0800000000000

LEC_InsufficientMemory

0x1000000000000

LEC_ChannelNotActive

0x2000000000000

LEC_UseStatusDescription

0x4000000000000

2-31

MAUI Oscilloscopes Remote Control and Automation Manual

Measurements
Measurement results are read in the same way as Waveforms. The following VBA example, when copied
into an Excel macro, enables the Standard Vertical parameters, then transfers the eight measurement
values into the spreadsheet (at cells C1 to C8).
' Create Button in Excel
Sub Button1_Click()
' Connect to the oscilloscop
Set app = CreateObject("LeCroy.XStreamDSO")
' Enable Standard Vertical Parameters
app.Measure.MeasureMode = "StdVertical"
' Transfer the 8 parameter values into the spreadsheet
Cells(1, 3).Value = app.Measure.P1.Out.Result.Value
Cells(2, 3).Value = app.Measure.P2.Out.Result.Value
Cells(3, 3).Value = app.Measure.P3.Out.Result.Value
Cells(4, 3).Value = app.Measure.P4.Out.Result.Value
Cells(5, 3).Value = app.Measure.P5.Out.Result.Value
Cells(6, 3).Value = app.Measure.P6.Out.Result.Value
Cells(7, 3).Value = app.Measure.P7.Out.Result.Value
Cells(8, 3).Value = app.Measure.P8.Out.Result.Value
' Clean up
Set app = Nothing
End Sub

Statistics
Statistics are also available for each parameter using two different calls:
result
result
result
result
result

=
=
=
=
=

app.Measure.P1.mean.Result.Value
app.Measure.P1.max.Result.Value
app.Measure.P1.min.Result.Value
app.Measure.P1.num.Result.Value
app.Measure.P1.sdev.Result.Value

result = app.Measure.P1.Statistics("mean").
Result.Value result = app.Measure.P1.Statistics("max").
Result.Value result = app.Measure.P1.Statistics("min").
Result.Value result = app.Measure.P1.Statistics("num").
Result.Value result = app.Measure.P1.Statistics("sdev").
Result.Value

2-32

Part 2: Automation Programming Reference
In addition, the data used to display the Histicon is available using the “histo” statistic:
Sub Button1_Click()
Set app = CreateObject("LeCroy.XStreamDSO")
bins = app.Measure.P5.Statistics("histo").Result.BinPopulations
numBins = app.Measure.P5.Statistics("histo").Result.bins
For i = 0 To numBins - 1
Cells(i + 1, 4).Value = bins(i)
Next I
Set App = Nothing
End Sub

Programming Examples
Populate Spreadsheet with Waveform Result Data
This VBA macro attached to a button (in an application that supports VBA) performs an FFT of C1 then
populates an Excel spreadsheet with the resulting waveform data.
Sub Button1_Click()
' Connect to the oscilloscope
Set app = CreateObject("LeCroy.XStreamDSO")
' Restore the instrument to its default state
app.SetToDefaultSetup
' Stop acquisitions during setup
app.Acquisition.TriggerMode = "Stopped"
' Turn C2 off (default state leaves C1 and C2 On)
app.Acquisition.C2.View = False
' Configure F1=FFT(C1) using a Blackman-Harris filter
app.Math.F1.View = True
app.Math.F1.Source1 = "C1"
app.Math.F1.Operator1 = "FFT"
app.Math.F1.Operator1Setup.Window = "BlackmanHarris"
' Take a single acquisition, force after 2 seconds if no trigger
app.Acquisition.Acquire 2, True
' Read the FFT, query numSamples in F1 and store in cell "B1"
numSamples = app.Math.F1.Out.Result.Samples
Cells(1, 2).Value = numSamples
' Access waveform data array and fill first column of the sheet
wave = app.Math.F1.Out.Result.DataArray
For i = 0 To numSamples - 1
Cells(i + 1, 1).Value = wave(i)
Next
End Sub

2-33

MAUI Oscilloscopes Remote Control and Automation Manual

Store Waveform Result Data in a Text File
The VBScript example is very similar to the VBA macro example above, the most notable difference being
the use of a standard system ActiveX control, Scripting.FileSystemObject, to enable the creation of files
containing waveform data in ASCII format. Comment text explains what each section of the script
accomplishes.
' Connect to the oscilloscope
Set app = CreateObject("LeCroy.XStreamDSO")
' Restore the instrument to its default state
app.SetToDefaultSetup
' Stop acquisitions during setup
app.Acquisition.TriggerMode = "Stopped"
' Turn C2 off (default state leaves C1 and C2 on)
app.Acquisition.C2.View = False
' Configure F1=FFT(C1) using a Blackman-Harris filter
app.Math.F1.View = True
app.Math.F1.Source1 = "C1"
app.Math.F1.Operator1 = "FFT"
app.Math.F1.Operator1Setup.Window = "BlackmanHarris"
' Take a single acquisition, force after 2 seconds if no trigger
app.Acquisition.Acquire 2, True
' Readout the FFT
numSamples = app.Math.F1.Out.Result.Samples
' Write the FFT power spectrum into the file, sample by sample
Set fso = CreateObject("Scripting.FileSystemObject")
Set MyFile= fso.CreateTextFile("c:\XStreamFFT.txt", True)
wave = app.Math.F1.Out.Result.DataArray
For i = 0 To numSamples - 1
MyFile.WriteLine(wave(i))
Next
' Clean up
MyFile.Close
Set fso = Nothing
Set app = Nothing

2-34

Part 2: Automation Programming Reference

Synchronization
Synchronization—or, more specifically, knowing when to read results—is critical when operating a digital
oscilloscope remotely (it is just as important for Automation as for GPIB remote control ). This is especially
true when working with an oscilloscope that uses a multithreaded architecture.
A classic problem seen in the majority of custom applications that control Teledyne LeCroy oscilloscopes
is that the scope is left to free-run in Auto-trigger mode, while simultaneously (and asynchronously) results
are queried.
Several techniques can be used to guarantee the synchronization and consistency of results, whether
they be waveform or parameter measurements, when using the Automation interface.

Timeouts
The following Excel macro example demonstrates the use of a timeout, a useful technique for ensuring
synchronization.
Sub Button1_Click()
' Connect to the oscilloscope
Set app = CreateObject("LeCroy.XStreamDSO")
' Enable Standard Vertical parameters
app.Measure.MeasureMode = "StdVertical"
' Stop the free-running trigger and take a single acquisition
' Use a 10 second timeout in case the acquisition is not complete
app.Acquisition.TriggerMode = "Stopped"
app.Acquisition.Acquire (10, True)
' Read the first parameter value and transfer into the spreadsheet
Cells(1, 3).Value = app.Measure.P1.Out.Result.Value
End Sub

Synchronizing Triggers
The Acquire method arms the acquisition system and waits for a user-specified time for a trigger. The
second argument, a Boolean, specifies whether or not to force a trigger before returning if a trigger
doesn’t arrive within the allotted time period. The method also returns a Boolean value signifying whether
or not a trigger arrived. See the reference section for more information on this useful method.
Note: The Acquire method is equivalent to setting the Trigger Mode to “Single”, then executing
WaitUntilIdle.

2-35

MAUI Oscilloscopes Remote Control and Automation Manual

Synchronizing Setups
Another scenario where synchronization is necessary is between changing settings and reading results,
even when no acquisition took place. For this the WaitUntilIdle method is used. This method is “blocking”
and will not return control until the setup request has completed.
An example of WaitUntilIdle usage follows.
Note: WaitUntilIdle is not for use when in Normal or Auto trigger mode.
Sub Button1_Click()
' Connect to the oscilloscope
Set app = CreateObject("LeCroy.XStreamDSO")
' Enable Standard Vertical parameters
app.Measure.MeasureMode = "StdVertical"
' Wait for the change to take place for a max. of 5 seconds
app.WaitUntilIdle(5)
' Read the value of P1 (pkpk) and transfer into the spreadsheet
Cells(1, 2).Value = app.Measure.P1.Out.Result.Value
' Enable Standard Horizontal parameters
app.Measure.MeasureMode = "StdHorizontal"
' Wait for the change to take place for a max. of 5 seconds
app.WaitUntilIdle(5)
' Read the value of P1 and transfer into the spreadsheet
Cells(1, 3).Value = app.Measure.P1.Out.Result.Value
End Sub

Best Practices for Synchronization
l

2-36

In almost all Automation applications, it is highly recommended that you stop acquisitions before
accessing result data. Most synchronization problems are caused by failure to follow this practice.
Use the app.SetToDefaultSetup action to restore the instrument to its default state before setting
the controls required by an application. This eliminates any dependency on the previous
configuration of the instrument. Teledyne LeCroy strives to ensure that the default state of the
instrument is constant from one software release to the next.
When using a result object, verify that the status is valid to ensure that the acquisition and/or
processing was valid.

Part 2: Automation Programming Reference

Application Interactions
It is not possible to run two simultaneous instances of the oscilloscope application. More than one
simultaneous connection to the instrument via Automation will be accepted, but simultaneous
connections are not recommended. When the final client has been disconnected from the instrument
(server), the oscilloscope application will remain running and will accept further client connections.
Operations that cause Modal Dialogs to appear in the instrument’s display will, by default, disrupt access
from Automation. This behavior can be changed using the app.SystemControl.ModalDialogTimeout and
app.SystemControl.EnableMessageBox controls.
The instrument application can be minimized in order to allow the controlling application to take over the
display and touch panel by means of the app.Minimize control. It can also be resized and repositioned on
the display by means of the app.Top, app.Left, app.Bottom, and app.Right controls.
When an application is running locally on the instrument and requests a connection to the oscilloscope via
Automation, one of two things will happen:
l

If the oscilloscope application is already running, the object returned will be a “pointer” to the
running application.
If the oscilloscope application is not running, it will be started.

2-37

MAUI Oscilloscopes Remote Control and Automation Manual

Early and Late Binding
The COM standard on which Automation is built supports two kinds of “binding” between client and server:
early (static), and late (dynamic, dispatch). Static binding usually involves a type library and is used
primarily by compiled languages such as C++. In this case, function entry points are resolved at compile
time. Dynamic binding (also known as late binding) involves resolving method and property calls at run
time, as opposed to compile time.
The Automation interfaces in XStream based DSOs use primarily the latter: Dynamic binding. From many
programming languages (VB, VBScript, etc.) this is transparent. But when you are developing applications
in C++, which does not provide late-binding natively, the use of a “helper” class is required. This is
demonstrated below:
#include "stdafx.h"
#include "AtlBase.h" CComModule _Module;
#include "AtlCom.h"
CComPtr spDso;
// dispatch ptr. to root of object model (app)
CComDispatchDriver ddDso;
int main(int argc, char* argv[])
{
printf("Hello XStream World!\n");
::CoInitialize(NULL);
HRESULT hr = spDso.CoCreateInstance(L"LeCroy.XStreamDSO");
if(SUCCEEDED(hr))
{
ddDso = spDso;
// perform an Auto-Setup (app.Autosetup)
hr = ddDso.Invoke0(L"AutoSetup");
// retrieve a Dispatch ptr. to the app.Display object
CComVariant displayPtr;
hr = ddDso.GetPropertyByName(L"Display", &displayPtr);
CComDispatchDriver ddDisplay(displayPtr.pdispVal);
// enter Dual-grid mode(app.Display.GridMode = "Dual")
hr = ddDisplay.PutPropertyByName(L"GridMode", &CComVariant("Dual"));
}
return 0;
}

2-38

Part 2: Automation Programming Reference

Automation Programming Rules
Follow these rules when writing Automation programs for remote control. See Control Variables and
Result Interfaces for more information about the types and supported methods.
Variables are indicated by italicized text in the examples below.

Values
Enum, String, and Color type values must have double quotes around them, for example:
app.Display.GridMode = "Quad"

Integer, Double, DoubleLockstep, and Bool values do not require quotes:
app.Display.Persisted = false
app.Acquisition.Horizontal.NumSegments = 10

Where objects take multiple arguments, values are given in comma-delimited lists:
app.Acquisition.Acquire(5,true)
app.Acquisition.C1.LabelsText = "Hello,World"

The first Acquisition object above is a Method with both Integer and Bool type arguments; the second is a
CVAR with a multi-value String argument.
To see the correct format and syntax, query the object's current setting. This command can be sent very
easily using the WaveStudio Terminal with a remote connection to the oscilloscope:
VBS? 'return = object'

Units
Generally, units are optional when giving Automation commands. Units are already determined by the
input trace and type of any math functions applied to the trace.
An exception is the Rescale math function command, which creates a second trace that explicitly
changes the vertical units in which the source trace is calculated. Use the following CVARs to reset units:
app.Math.Fx.Equation = rescale(trace)
app.Math.Fx.Operator1Setup.Unit = "menemonic"
See the list of acceptable unit mnemonics in Units and Multipliers

2-39

MAUI Oscilloscopes Remote Control and Automation Manual

Special Cases
Equations
CVARs app.Math.Fx.Equation, app.Math.Fx.EquationRemote, and
app.Measure.Px.Equation are text Strings containing the summary of the math or measure operation.
They can be used to query the current settings, but not to set the function or parameter.
To set up a Math function, use the CVARs app.Math.Fx.Sourcex and app.Math.Fx.Operatorx, and any
objects in the app.Math.F1.OperatorxSetup folders.
To set up a Parameter, use the CVARs app.Measure.Px.Sourcex and
app.Measure.Px.ParamEngine, plus any objects in the app.Measure.Px.Operator subfolder.

Labels
The CVARs LabelsText and LabelsPosition (which appear in the hierarchy for any waveform object)
specify the text and position of custom labels placed on a waveform. LabelsText takes a single String
argument for which you can specify a comma-delimited list of values each representing a separate label:
app.Acquisition.C1.LabelsText = "Hello,World"

The above control creates two labels, "Hello" and "World." Note that later sending the same control with
only a single value will erase all but the first label in the list (which will remain at its current position),
changing it to the new text string.
LabelsPosition is also a String where each list value is a pipe-delimited pair specifying the horizontal and
vertical position of the corresponding label in the LabelsText string. Placing parentheses around the
vertical value in the pair turns on "Use Trace Vertical Position". The following control would position both
labels "Hello" and "World", placing "Hello" adjacent to the trace, and "World" at the vertical position specified:
app.Acquisition.C1.LabelsPosition = "0.000002|(0.02),0.000002|0.01"

Colors
Color type CVARs set/query the color of traces and other display objects, using a number in the range 0 to
FFFFFF in hexadecimal. The possible colors are made from any combination of the primary colors, which
are set in hexadecimal as Blue = &HFF0000, Green = &HFF00, Red = &HFF. For example:
app.Display.C1Color = "255,255,0"

The value may be entered in decimal or in hexadecimal, though hexadecimal is usually more convenient.
Note that if the intensity of a color is to be reduced or increased by a numerical factor, an AND operation
must be used afterwards, to prevent corruption of other primary colors.

File Names
CVARs of the Filename type generally do not require the full path to be given as part of the value, but in
most cases, the directory in which the files will be saved is set using a separate CVAR, which does require
the full path. Check the parent objects within the subsystem in XStreamBrowser to find the CVAR for
setting the file path.

2-40

Part 2: Automation Programming Reference

Persistence
When applied to any trace, the CVARs Persisted, PersistDotJoined, Persistence3D, Persist3DQuality,
PersistenceMonochrome, and PersistenceSaturation determine the status and appearance of the
persistence display.
Persistence sets/queries the persistence state. If the Display.LockPersistence CVAR is set to 'AllLocked'
then the persisted state of all displayed waveforms will be the same. If the Display.LockPersistence
control is set to 'PerTrace' then the persisted state of each waveform may be independently controlled.
If PersistDotJoined is False (the default state), samples are put into the persistence map as dots. The
advantage of that is that any lit pixel in the pmap actually corresponds to a sample of the data taken at
that time. The disadvantage of dots is that there is no way to associate a dot with any other dot; there is no
history of which dots were part of the same acquisition. If this control is set True, then each acquisition
draws lines into the persistence map that connect the dots at the sample positions. Clearly the advantage
of that is that it is now possible to see if some outlier samples were all part of the same acquisition, or not.
The disadvantage is that lit points in the persistence map no longer correspond to actual samples, the
lines between the samples are also lit.
If the persistence map is going to be analyzed it is probably preferable to leave Dot Joined off so that only
actual samples are considered in the analysis. If there are very few points in a persistence map, there may
columns with no points, that is, there are gaps horizontally between points. In that case, Dot Joined will
connect them starting with the last trace, and for all subsequence traces accumulated.
The action of turning on or off Dot Joined clears the accumulated persistence map.
Persistence3D puts the persistence display into a 3D surface map.
Persistence3DQuality selects the 3D quality, which determines how the display is rendered. This CVAR is
only relevant when Persistence3D is True.
If PersistenceMonoChrome is set True, the display will be monochromatic, regardless of whether 2D or
3D.

Placeholders
In some cases, the value that appears in XStreamBrowser is only a placeholder that will appear on the
oscilloscope GUI until you make an actual setting. Placeholders will usually be indicated by angle brackets
surrounding the text string. For example, the Value of app.Utility.Remote.AllowControlFrom is , which appears inside the control on the GUI indicating you should substitute the remote client
IP address or DNS name. If you provided an actual IP address or DNS name, that node would have
exclusive remote control of the oscilloscope.

Serial Decoder Table Columns
The CVAR app.SerialDecode.Decodex.Decode.ColumnState contains a pipe-delimited list of all the table
columns that are selected for display. For example:
app.SerialDecode.Decode1.Decode.ColumnState = "Idx=On|Time=On|Data=On|..."

If you wish to change the table configuration by hiding or displaying columns, send the full string with the
state changed from "on" to "off", or vice versa, rather than remove any column from the list.

2-41

MAUI Oscilloscopes Remote Control and Automation Manual

Using Variables to Reference Objects
One way to increase the readability and simplicity of your source code is to use variables to reference
objects that are at each level of the hierarchy. For example, here is the VB code to read out the Sweeps
property for channel 1:
Dim numSweeps as Long
numSweeps = app.Acquisition.C1.Out.Result.Sweeps

If you are reading out more than just the Sweeps property, you might find it easier to read the following:
Dim
Dim
Dim
Dim
Dim
Dim
Dim
Dim

C1Res as Object
C1 as Object
numSweeps as Long
HorizontalOffset As Double
HorizontalPerStep As Double
VerticalOffset As Double
VerticalPerStep As Double
wform

C1 = app.Acquisition.C1
C1.AverageSweeps = 200 numSweeps = C1
Res.Sweeps HorizontalOffset = C1
Res.HorizontalOffset HorizontalPerStep = C1
Res.HorizontalPerStep VerticalOffset = C1
Res.VerticalOffset VerticalPerStep = C1
Res. VerticalPerStep

The panel setup files make heavy use of object variables, making them far more readable and editable:
Set Acquisition = XStreamDSO.Acquisition
Set C1 = Acquisition.C1
C1.View = True
C1.UseGrid = "YT1"
C1.Persisted = False
C1.PersistenceSaturation = 50
C1.PersistenceMonoChrome = True
C1.Persistence3d = False
. . .

2-42

Part 2: Automation Programming Reference

Automation in MATLAB
On oscilloscopes equipped with the XDEV option, MATLAB applications can use Automation to exchange
data with the oscilloscope application. For more information, see Lab 831: X-Stream COM Object
Programming with MATLAB and Using LeCroy Digital Oscilloscopes with MATLAB.

Connecting and Disconnecting
MATLAB applications use the actxserver keyword to connect to the instrument. MATLAB supports
TCP/IP connections.
app = actxserver('LeCroy.XstreamDSO.1', '')

Use 127.0.0.1 when running MATLAB on the oscilloscope, rather than accessing it remotely.
To disconnect, end with:
Set app = Nothing

Creating Object Variables
Given the complexity of MATLAB's syntax for handling multi-tiered Automation objects, it is highly
recommended to create object variables ("handles") at each level of the hierarchy. For example:
% creation of object variables 1 level down from top-level
acq = app.Object.Item('Acquisition');
math = app.Object.Item('Math');
meas = app.Object.Item('Measure');
PF = app.Object.Item('PassFail');
% creation of object variables 1 level further
c1 = acq.Object.Item('C1');
f1 = math.Object.Item('F1');
p1 = meas.Object.Item('P1');
p1Operator = p1.Object.Item('Operator')
% creation
c1_results
f1_results
p1_results

of object variables to results
= c1.Out.Result;
= f1.Out.Result;
= p1.Out.Result;

When using object variables, the code to access results and to get or set properties becomes much easier
to read and debug:
% Set some properties for P1 (assumes P1=per@level)
set(p1Operator, 'LevelType', 'Percent');
set(p1Operator, 'PercentLevel', 66);
set(p1Operator, 'Slope', 'Neg');
% Read back and display some results
p1_Val = p1_results.Value
p1_status = p1_results.Status
p1_time = p1_results.FirstEventTime

2-43

MAUI Oscilloscopes Remote Control and Automation Manual

Accessing Control Variables (CVARs)
These instructions apply to CVARs (object selected from a yellow folder in XStreamBrowser).
Using the syntax:
= Object.Item('

MAUI Oscilloscopes Remote Control Manual And Automation

maui-remote-control-and-automation-manual

Navigation menu

Versions of this User Manual:

Views

Navigation