MAUI Oscilloscopes Remote Control Manual And Automation

maui-remote-control-and-automation-manual

User Manual:

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

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 B
October 2017

Introduction

Introduction
This manual documents the requirements for remote control of Teledyne LeCroy's MAUI™ oscilloscopes
using either traditional IEEE 488.2 (GPIB) commands or Windows® Component Object Model (COM)
Automation commands.
The manual is divided into the following sections:
Part 1: Making the Remote Connection describes all the methods for gaining access to a MAUI
oscilloscope (device) from a remote computer (controller). It details the software and hardware
requirements for each method.
Part 2: Automation Programming Reference describes the MAUI COM architecture and explains how to
use Automation to control the oscilloscope remotely using manual methods or remote control programs.
Part 3: Automation Control Variable Reference details the MAUI COM architecture for configuring and
controlling the oscilloscope. It is most useful for developers of remote control applications.
Part 4: Automation Result Interface Reference details the MAUI COM architecture for reading back data
from the oscilloscope. It is most useful for developers of remote control applications.
Part 5: IEEE 488.2 Programming Reference describes the LeCroy legacy remote control implementation
and provides an overview of GPIB programming conventions. It also provides information for
understanding MAUI waveform transfer and the waveform template.
Part 6: IEEE 488.2 Command Reference details the legacy remote control commands supported by MAUI
oscilloscopes.

MAUI Oscilloscopes Remote Control and Automation Manual

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.

Notational Conventions

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 n is used to denote the greatest number of an oscilloscope object, such as input channels
or math function traces, supported by your instrument. On a two-channel oscilloscope, C1 through Cn
should be taken to mean C1 and C2, whereas on an eight-channel oscilloscope, C1 through C8, and so
forth.
The following mnemonics may be used where is indicated in commands.
Note: These are the sources supported by legacy commands. Other sources may be available with
the addition of software options (Views, Streams, Histograms, etc.), depending on the operation.
Use XStreamBrowser to check the application Automation object hierarchy.
Object

Mnemonic

Note

Analog Channels

C1, C2, C3, C4,....Cn

Sensor Channels

SE1,....SEn

Digital Groups

Digital1,....Digital4

Math Functions

F1,....Fn,
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,....Pn
CUST1,...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,...Mn

Zooms

Z1,....Zn

iii

MAUI Oscilloscopes Remote Control and Automation Manual

Units
Numeric values can be expressed in code as numeric fixed point or exponential. However, only the fixed
point value is displayed in tables and on descriptor boxes.
Note: This manual reflects the units supported in MAUI XStreamDSO software v.8.5.0.0 and later.
Many, but not all, of the units listed here are supported in earlier versions of XStreamDSO.

Table of Mnemonics
Units may be expressed using the following mnemonics.
Note: Specify only the base unit in code, do not add prefixes. Units are automatically scaled up or
down within the list of standard, SI prefixes (atto to Exa) based on the relative size of the source
signal(s). For example a 1000 V reading is shown as 1 kV, while a .1 V reading is shown as 100 mV.
When the multiplication factor is 1 V = 1 Pascal, a 1 millivolt (mV) reading is displayed as 1 mPa
rather than .001 Pa or 100e-3 Pa.
Note: Time and Dimensionless units are available only for certain measurements and acquisition
commands.
Category

Unit

Mnemonic

Mass

gram

slug

SLUG

liter

cubic meter

cubic inch

IN3

cubic foot

FT3

cubic yard

YARD3

radian

RAD

arcdegree

DEG

arcminute

MNT

arcsecond

SEC

cycle

CYCLE

revolution

REV

turn

TURN

Volume

Angle

Notational Conventions
Category

Unit

Mnemonic

Force/Weight

Newton

grain

ounce

pound

meter/second

M/S

inch/second

IN/S

foot/second

FT/S

yard/second

YARD/S

mile/second

MILE/S

meter/second2

M/S2

inch/second2

IN/S2

foot/second2

FT/S2

standard gravity

Pascal

PAL

bar

BAR

atmosphere, technical

atmosphere, standard

ATM

Torr

TORR

pound/square inch

PSI

degree Kelvin

degree Celsius

CEL

degree Fahrenheit

FAR

Joule

British Thermal Unit

BTU

calorie

CAL

Velocity

Acceleration

Pressure

Temperature

Energy

MAUI Oscilloscopes Remote Control and Automation Manual
Category

Unit

Mnemonic

Rotating Machine

radian/second

RADPS

frequency (Hertz)

revolution/second

RPS

revolution/minute

RPM

torque N•m

torque in•oz

INOZ

torque in•lb

INLB

torque ft•lb

FTLB

power, mechanical (Watt)

horsepower

Weber

Tesla

inductance (Henry)

magnetic field strength

A/M

permeability

HENRYPM

Ampere

Volt

Watt

power, apparent

power, reactive

VAR

power factor

capacitance (Farad)

Coulomb

Ohm

OHM

Siemen

SIE

electrical field strength

V/M

electrical displacement field

CPM2

permittivity

FARADPM

conductivity

SIEPM

second

minute

MIN

hour

HOUR

day

DAY

week

WEEK

Magnetic

Electrical

Time

Notational Conventions
Category

Unit

Mnemonic

Dimensionless

percent

PCT

percent min-max

PCTMNMX

decibel

decibel milliwatt

DBM

decibel Volt

DBV

decibel millivolt

DBMV

decibel microvolt

DBUV

decibel microampere

DBUA

decibel referred to carrier

DBC

decade

DECADE

unit interval

Q-scale

bit

BIT

byte

BYTE

baud

BAUD

least significant bit

LSB

poise

POISE

parts per million

PPM

pixel

PIXEL

division

DIV

event

EVENT

sample

SAMPLE

segment

SEG

sweep

SWEEP

Combining Units
SI units may be combined following these rules:
l

For the quotient of two units, use the character " / "

For the product of two units, use the character " . "

For exponents, append the digit to the unit with no space (e.g., " S2 " for seconds squared).
Note: Some units are converted to simple units (e.g., " V.A " becomes " W ").

vii

MAUI Oscilloscopes Remote Control and Automation Manual

viii

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 (XStreamDSO) 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 National Instruments 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 (ENET) cable
Connect the oscilloscope directly to the controller using a crossover cable or a straight cable
capable of directional switching (most modern, standard ENET cables do this).
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 is preset to accept DHCP addressing. Be sure the controller and the oscilloscope are on
the same subnet.
The oscilloscope is delivered with a default IP address, which is pulled from our network prior to shipment.
You can find this address by navigating to Utilities > Utilities Setup > Remote. Keep in mind this address will
likely change as soon as the instrument is connected to your network.
You may also address the oscilloscope using the hostname. The default hostname is the serial number
printed on the back of the instrument and on the registration card. If your network is served by a DNS
server, the hostname must be the instrument name that is recognizable to the name server. For direct
(coaxial or straight ENET) connections, it may be easiest to make the initial connection using the
hostname.
You may optionally assign a static IP address to the oscilloscope using the standard Windows networking
dialogs .
Tip: To access the Windows control panel, choose File > Minimize or go to Utilities > Utilities Setup
> Remote and select Net Connections.

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).

Record 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 "TCPIP::::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 are programming in
newer languages such as C#, LXI (VXI-11) is the best remote control setting.

Resources
The LXI specification stipulates that vendors supply:
l

An IVI driver for the instrument.
Note: Some newer versions of NI-VISA install with IVI drivers. The LeCroyScope IVI driver is
required to connect to MATLAB applications using LXI (VXI-11). See Resources.

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
Open port 111 on the controller for TCP/IP communications.
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.
Record 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.

Record 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.

1-18

Part 1: Making the Remote Connection
9. 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.
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.

E. Test the DCOM Connection
Install the XStreamBrowser on the PC and use it to Connect to Remote Instrument (DCOM).
If the DCOM 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:
l

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), the "built in" Automation
language, as it is syntactically identical to our LeCroy Setup Script (.LSS). Do not confuse VBS with
Visual Basic for Applications (VBA), a subset of Visual Basic used extensively within Windows
applications, such as Excel, as a macro "programming" language. Some things that work in VBS do
not work in VBA.

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 an 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")

LXI

MakeConnection("VXI11: ")

MakeConnection("VXI11: 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: When the VISA resource string is used with ActiveDSO for remote control, 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)

TCPIP0::::INSTR
TCPIP0::::INSTR
Examples:
TCPIP0::172.29.9.22::INSTR
TCPIP0::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.

Setting Permissions
WaveStudio is preset so that only users with Administrator rights can run it. If you wish to use WaveStudio
from a PC that does not have Administrator privileges:
1. Navigate to C:\Program Files\LeCroy\XStream\WaveStudio.exe, then right-click and choose
Properties.
2. Open the Compatibility tab and deselect Run this program as an Administrator.

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
My Scope Explorer window.

either on the Scope ribbon or at the top of the

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 XStreamDSO 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

Synchronization

2-39

Application Interactions

2-41

Early and Late Binding

2-42

Automation Programming Conventions

2-43

Using Programming Variables

2-46

Automation in MATLAB

2-47

Automation in Python

2-50

Automation in C#

2-53

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 (XStreamDSO) 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 (XStreamDSO)

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 DCOM
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 XStreamBrowser icon.
3. Select the

connection icon.

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

connection icon.

4. Enter the network IP Address of the oscilloscope, then click OK.

2-4

Part 2: Automation Programming Reference
Note: It is best to use the IP Address, not the DNS or UNC name. If the oscilloscope application 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 XStreamDSO, 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 XStreamDSO 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 XStreamDSO 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: Customization and 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 XStreamDSO 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 XStreamDSO 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 XStreamDSO application hierarchy, at the root
object LeCroy.XStreamDSO. 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”

Using the app handle, this line of code sets the Grid Mode control of the Display system to the value
“Quattro”.

2-14

Part 2: Automation Programming Reference
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 VBS 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 XStreamDSO 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 XStreamDSO 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 XStreamDSO 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)

Note: When using ActiveDSO with Excel VBA, arguments must be placed inside two double quotes,
so the above call would be: 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 XStreamDSO 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 XStreamDSO 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 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.
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 three double-quotes around the VBS command are required because the double-quotes
around the arguments 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 = "" ' """)

Note: 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.

2-22

Part 2: Automation Programming Reference
lecroy.write(r"""vbs
lecroy.write(r"""vbs
lecroy.write(r"""vbs
lecroy.write(r"""vbs
lecroy.write(r"""vbs

'app.measure.showmeasure = true ' """)
'app.measure.statson = true ' """)
'app.measure.p1.view = true ' """)
'app.measure.p1.paramengine = "" ' """)
'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.

Setting Control Variables
All CVARs have the default property of Value. A CVAR such as VerScale (Volts/Div) may be set in VBS as
follows:
app.Acquisition.C1.VerScale = 0.5

Its current value may be queried with:
CurrentValue = app.Acquisition.C1.VerScale

The following methods are also supported (for this CVAR type) :
double GetAdaptedValue
SetRequestedValue(double)
double GetRequestedValue
double GetDefaultValue
double GetGrainValue
double GetMaxValue
double GetMinValue

For example:
app.Acquisition.C1.VerScale.SetRequestedValue(1.0)
minValue = app.Acquisition.C1.VerScale.GetMinValue
maxValue = app.Acquisition.C1.VerScale.GetMaxValue

The sample file D:\Scripts\Automation\ExampleCvarTypes.vbs contains code for querying and displaying
CVAR properties for each type of control variable, including the status flags. Commands such as these are
useful for ascertaining the state of the oscilloscope prior to changing setups or taking other actions.
Note: In the sample file, after instantiating the app object, the programming variable "acq" was set
to take the place of "app.acquisition" in all commands, and other variables are set at the beginning
of each type, depending on the child objects being substituted (e.g., acqHorz replaces
app.Acquisition.Horizontal). This is to simplify coding.

2-24

Part 2: Automation Programming Reference

Control Variable Types
The Type column of the XStreamBrowser window shows the control type. 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

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)

2-25

MAUI Oscilloscopes Remote Control and Automation Manual
Type

Properties and Methods

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)

Bool

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

Action

2-26

ActNow

Part 2: Automation Programming Reference

Result Interfaces
Tip: The sample scripts for exposing results that are referred to in this section are installed with
XStreamDSO v.8.5.x.x. and later.
"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. Treat "Out.Result" properties
as read-only.
Note: Although you can write the properties of a result, it is not advisable, as the result properties
and data will be updated on next acquisition.
Caution: 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 pt window onto a 1 Mpt trace, or show the center 10 mV of a 100 mV trace.
Several properties, most significantly the DataArray object, are Variants containing either a one- or twodimensional 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 a mixed-signal input to generate digital (bi-state) waveforms.
These waveforms are contained in the Digitaln trace name, where x = 1, 2, 3 etc. Each Digitaln 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.

2-27

MAUI Oscilloscopes Remote Control and Automation Manual
Example paths to Digital Result interfaces:
app.LogicAnalyzer.Digital1.Out.Result
app.LogicAnalyzer.Digital2.Out.Result

Histogram
The Histogram interface is used for all histogram traces. Histograms can be configured on most
oscilloscopes as a math function (Fn). 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. This is an important distinction to remember depending on the measurement assigned to the
parameter, as the values may or may not be the same. For example: if the source waveform is 1000
cycles of square wave, then the Frequency measurement will have 1000 values in the ValueArray and
Value will be the same as the 1000th (last). Whereas, Min or Max measurements on that same waveform
will only have one value in the ValueArray, and Value will be that same value.
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

2-28

Part 2: Automation Programming Reference

Table
Table results interfaces are 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 CellValue are the key properties to use to retrieve the table’s data. See the information in
the CellValue property for more information.
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 (Cn), memory (Mn), math function (Fn) and zoom (Zn) traces, as well as others
that are associated with specific analysis packages, such as the Power waveform used in the PAS
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 plots, 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

2-29

MAUI Oscilloscopes Remote Control and Automation Manual

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

Exposing Waveforms
Waveform data is exposed as a simple array using app.Subsystem.Wfmn.Out.Result.Samples. Wfmn can
be any object defined within the XStreamDSO object hierarchy that produces a waveform trace (generally
Cn, Fn, Mn, SEn, and Zn).
The sample script D:\Scripts\Automation\ExampleWaveform.vbs gets the sample points in analog trace
C1 by accessing app.Acquisition.C1.Out.Result.Samples and dumps them into a text file.

Digital Waveforms
Digital waveforms are two-dimensional arrays, the DataArray being the samples and the TimeArray being
the time associated with the samples. As each digital bus may have up-to-18 lines (D0-D17), the DataArray
has at least two columns, being the Sample Number and the Digital Line from which it was taken.
Each sample has a time, but it is not easily calculated from the timebase, as with analog waveforms, as
the digital pulses on each line may have different widths. To accurately expose a digital waveform, you
must access both arrays and correlate the times with the samples from each line.
The sample script D:\Scripts\Automation\ExampleDigital.vbs gets the arrays in a digital trace that has
been stored in M1, determines the number of lines in the bus, correlates the times with the samples, and
dumps the results in a text file.
Tip: To see how this works, recall the Digital entry from
D:\Scripts\Automation\AutomationExamplesLabNotebook.lnb. This will copy a 3-line digital trace
into M1, which is accessed by the script.

Sequence Mode Waveforms
In MAUI firmware version 7.7.x.x and later, the segment index is supported as an argument to the
Out.Result property. For example, the following commands return results for segment 1 of the respective
waveform (which is a Sequence Mode acquisition):
set myResult = app.Acquisition.C1.Out.Result(1)
set myResult = app.Math.F1.Out.Result(1)

Zero (0) or no argument returns the result related to the last segment. A segment index greater than the
total number of segments also returns the result related to the last segment.

2-30

Part 2: Automation Programming Reference

Waveform Status Property
The waveform result includes a Status property (bit-field) that reflects ‘warning’ and ‘error’ conditions.
There is no bit for "valid."
Bit #

Value

Description

0x0000000000001

LEC_Invalid

0x0000000000002

LEC_Overflow

0x0000000000004

LEC_Underflow

0x0000000000008

LEC_ContainsUndefinedValues

0x0000000000010

LEC_LessThan

0x0000000000020

LEC_GreaterThan

0x0000000000040

LEC_NotAPulse

0x0000000000080

LEC_NotCyclic

0x0000000000100

LEC_Averaged

0x0000000000200

LEC_UnlockedPLL

0x0000000000400

LEC_OtherError

0x0000000000800

LEC_OtherWarning

0x0000000001000

LEC_OtherInfo

0x0000100000000

LEC_InputsIncompatible

0x0000200000000

LEC_AlgorithmLimitsReached

0x0000400000000

LEC_BadDefinition

0x0000800000000

LEC_TooFewData

0x0001000000000

LEC_TooManyData

0x0002000000000

LEC_UniformHorizIntervalRequired

0x0004000000000

LEC_BadUnits

0x0008000000000

LEC_DataRangeTooLow

0x0010000000000

LEC_DataUndersampled

0x0020000000000

LEC_PoorStatistics

0x0040000000000

LEC_SlowTransitionTime

0x0080000000000

LEC_DataResampled

0x0100000000000

LEC_DataInterpolated

0x0200000000000

LEC_MeasurementScaleImprecise

0x0400000000000

LEC_NoDataAvailable

0x0800000000000

LEC_SomeCummulatedResultsInvalid

0x1000000000000

LEC_InsufficientMemory

0x2000000000000

LEC_ChannelNotActive

0x4000000000000

LEC_UseStatusDescription

2-31

MAUI Oscilloscopes Remote Control and Automation Manual

Copying Waveform Data to Excel
This Excel macro reads the number of samples in a waveform and places it in cell B1 of the spreadsheet,
then reads all waveform sample values and copies them into column A (A1...Axx). The example is coded in
VBA, and would be launched by a button in a spreadsheet.
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: Ensure that the record length is < 64 k samples, since Excel has a limit on the number of rows
in a spreadsheet. Ideally, start experimenting with short (500 point) records.

Storing Waveform Data in a Text File
This 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.
' Connect to the oscilloscope
Set app = CreateObject("LeCroy.XStreamDSO")
' Code to take acquisition and generate FFT in F1
. . .
' 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-32

Part 2: Automation Programming Reference

Exposing Measurements
Measurement results are read similar to Waveforms, using the appropriate app.Measure.Pn.Out.Result
object.
The Value is the default property of all Out.Results, so getting the above result delivers the last measured
value in the acquisition for that parameter.

Statistics
In addition to the last measured value, statistics are 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
result
result
result
result

=
=
=
=
=

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

The data used to display the Histicon is available using the “histo” statistic. For example:
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

Measurements on Sequence Mode Waveforms
In MAUI firmware version 7.7.x.x and later, the segment index is supported as an argument to the
app.Measure.Pn.Out.Result property. For example:
set myResult = app.Measure.P1.Out.Result(1)

returns the result of the measurement on segment 1 of the P1 source waveform (which is a Sequence
Mode acquisition).
Zero (0) or no argument returns the result related to last segment. A segment index greater than the total
number of segments also returns the result related to last segment.

2-33

MAUI Oscilloscopes Remote Control and Automation Manual
The following code from the sample file D:\Scripts\Automation\ExampleMeasureSeg.vbs loops over each
parameter specified, returning the result for each segment:
numSegs = 10
for iSeg = 1 to numSegs
set p1Result = app.Measure.P1.Out.Result(iSeg)
set p2Result = app.Measure.P2.Out.Result(iSeg)
set p3Result = app.Measure.P3.Out.Result(iSeg)
outputFile.Write iSeg & "," & p1Result.Value & "," & p2Result.Value & "," &
p3Result.Value & "," & VbCrLf
next

Tip: To see how this works, recall the MeasureSegs entry from
D:\Scripts\Automation\AutomationExamplesLabNotebook.lnb. This will set up P1-P3 and copy a
segment trace into measurement source C1.

Reading from the Measure Table
The sample file D:\Scripts\Automation\ExampleTableMeasure.vbs contains code for iterating over the
Measure table to read results for all active parameters.
Similar code is available for iterating over the Pass/Fail table in
D:\Scripts\Automation\ExampleTablePassFail.vbs, and the WaveScan table in
D:\Scripts\Automation\ExampleTableWaveScan.vbs.
Tip: To see how these work, recall the Table WaveScan, Measure, PassFail entry from
D:\Scripts\Automation\AutomationExamplesLabNotebook.lnb. This will copy a source trace into
C1, set up P1-P6, a Pass/Fail test, and the WaveScan table view.

2-34

Part 2: Automation Programming Reference

Copying Measurements to Excel
The following Excel macro enables the Standard Vertical parameters, then transfers the eight
measurement values into cells C1 to C8. The example is coded in VBA, and would be launched by a button
in a spreadsheet.
' 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

2-35

MAUI Oscilloscopes Remote Control and Automation Manual

Exposing Table Data
Tables are data arrays that may be one- or two-dimensional, and this is impossible to tell from looking at
the table as it is presented in MAUI.
Many tables have Variant cell types, which may contain other tables that also need to be indexed in order
to see the correct values. For example, were you to send this simple VBS query to get results from the
Spectrum Analyzer table:
vbs? 'return =app.SpecAnalyzer.SpecAnTable.Out.Result.CellValue(3,2)'

(3,2) represents the table (row,column) to return, but to specifically return the frequency value, you'd have
to send something like:
vbs? 'return =app.SpecAnalyzer.SpecAnTable.Out.Result.CellValue(3,2)(0,0)'

The first index indicates the row of table data wanted (3) from the Frequency column (2), but that single
cell contains an array of the Amplitude value (0,0), Start Frequency (1,0) and Stop Frequency (2,0). You
have to index first the principle table then the array inside that particular cell, hence the extra (0,0) to get
the amplitude value.
Likewise, the table that presents the results of any serial decoder software,
app.SerialDecode.Decoden.Out.Result, is a table with a table in each cell that you need to index at
(line,col). However, it only has a numeric value in (0,0) that needs to be indexed, as well.
Note: If the data in a cell of the Serial Decoder Result table is a string, there is no
(datatype,dataidx); if it is a number, there is an array to be indexed and it is always at (0,0).
The Serial Decode table presents a number of challenges in exposing results. See the sample script
D:\Scripts\Automation\ExampleTableSerialDecode.vbs, which iterates over the Serial Decode table and
dumps the data to a text file.
Tip: To see how this works, recall the Table Serial Decode entry from
D:\Scripts\Automation\AutomationExamplesLabNotebook.lnb. This will copy two waveforms into
M1 and M2 and apply the USB2 decoder to them.

Handling Different Cell Types
There are four cell "types" that may appear in a table. Each type must be handled differently in code.
l

2-36

CellType 0 is a Variant (as in the Spectrum Analyzer and Serial Decoder tables). These cells may
hold different things, such as other table arrays, which may be either one- or two-dimensional.
CellType 2 is a Param result (as in the Measure table). These are cells with single values.
CellType 3 is a Boolean result. These are cells containing single, Boolean values, either 1|0 or
True|False.
CellType 4 is the histicon cell of the Measure table. This not commonly used.

Part 2: Automation Programming Reference
Each of the D:\Scripts\Automation\ExampleTable*.vbs scripts contain code used to iterate over a table to
determine its actual structure and cell types. We recommend that you adapt this code to your programs
whenever accessing results from table objects.
Tip: The file D:\Scripts\TableExport.lss also includes code for determining whether CellType 0
cells contain an array and uses the appropriate method for reading the data.

Error Handling for Table Results
Error handling is especially important for tables with Parameter and Boolean cell types, as an error is
generated if a cell has no data. The following snippet shows the use of VBS function "on error resume next"
applied to table data:
' get the Parameter or Boolean Value property (handle error case if no data in the
value)
strThisVal = "-"
on error resume next
set cellVal = myResult.CellValue(rowIdx, columnIdx)
strThisVal = cellVal.value
on error goto 0 ' Reset Error handling state
strRowData = strRowData & strThisVal

Discovering Number of Array Dimensions
You can discover the number of dimensions in a table array by adding the following helper function to
VBScripts:
function getArrayDims(arr1)
dimensions = 0
if IsArray(arr1) then
on error resume next
Err.clear
do while Err.number = 0
dimensions = dimensions + 1
UBound arr1, dimensions
loop
Err.clear
dimensions = dimensions - 1
end if
getArrayDims = dimensions
end function

Tip: This function appears at the end of the sample scripts
D:\Scripts\Automation\ExampleTable*.vbs, from which you can copy it.
Note: This function will not work in VBA scripts.

2-37

MAUI Oscilloscopes Remote Control and Automation Manual

Using Join to Read from Tables
The VBS query Join can be used to read table value arrays into a comma-delimited list of values. For
example, sending the following command from the terminal in WaveStudio returns a list of all the specified
values for the measurement parameter P2:
VBS? 'return=join(app.Measure.P2.Out.Result.ValueArray(-1,0,1), chr(44))

2-38

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.

Synchronizing Triggers Using Timeouts
The Acquire method arms the acquisition system and waits a user-specified time for a trigger. The second
argument, an optional Boolean, specifies whether or not to force a trigger then return the value if a trigger
doesn’t arrive within the allotted time period.
Note: The Acquire method is equivalent to setting the Trigger Mode to “Single”, then executing
WaitUntilIdle.The return of the Boolean causes the method to function logically like a query and
requires it to be read into a variable, whether or not the returned value is actually displayed.
The following Excel VBA 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"
Dim Acquired as Boolean
Acquired = app.Acquisition.Acquire (10, True)
' Read the first parameter value and transfer into the spreadsheet
' Display the Acquired value to show the oscilloscope has triggered
Cells(1, 3).Value = app.Measure.P1.Out.Result.Value
MsgBox Acquired
End Sub

2-39

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 a “blocking”
mechanism 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-40

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 controls:
l

app.SystemControl.ModalDialogTimeout

app.SystemControl.EnableMessageBox

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-41

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 XStreamDSO based instruments use primarily 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-42

Part 2: Automation Programming Reference

Automation Programming Conventions
Follow these guidelines 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 placeholder 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, as 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, which creates a second trace that explicitly changes the vertical units in which the source trace
is calculated, and therefore requires that a unit be specified:
app.Math.Fn.Equation = rescale(trace)
app.Math.Fn.Operator1Setup.Unit = "menemonic"

See the list of acceptable mnemonics in Units.
The vertical unit of analog and sensor input channels (Cn and SEn) can be changed by setting the CVAR
Unit to "Other":
app.Acquisition.Cn.Unit = "OTHER"
app.AcquisitionPMU.SEn.Unit = "OTHER"

Then, follow with the unit Type (category) and displayed Units. For example:
app.Acquisition.Cn.Type = "MASS"
app.Acquisition.Cn.Units = "SLUG"

2-43

MAUI Oscilloscopes Remote Control and Automation Manual
Note: You can only select Units from the list of values that appears following the Type selection.

Equations
CVARs app.Math.Fn.Equation, app.Math.Fn.EquationRemote, and
app.Measure.Pn.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.Fn.Sourcen and app.Math.Fn.Operatorn, and any
objects in the app.Math.F1.OperatornSetup folders.
To set up a Parameter, use the CVARs app.Measure.Pn.Sourcen and
app.Measure.Pn.ParamEngine, plus any objects in the app.Measure.Pn.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-44

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.

Visible 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-45

MAUI Oscilloscopes Remote Control and Automation Manual
Note: Even though columns are hidden, they are still calculated in the decoding, and any time you
access the Out.Result objects of serial decode tables, all the columns are returned. If you seek to
access a specific column, use the getDataArray function to first determine the depth and order of
the table and the actual number of the column.

Using Programming Variables
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 C1:
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-46

Part 2: Automation Programming Reference

Automation in MATLAB
On instruments equipped with the CustomDSO (XDEV) option, MATLAB applications can use Automation
to control and exchange data with the oscilloscope application. For more information, see Lab 831: XStream COM Object Programming with MATLAB and Using LeCroy Digital Oscilloscopes with MATLAB.
Note: An installation of MATLAB is required on the controller for remote execution of MATLAB
scripts. An installation of MATLAB is required both on the controller and oscilloscope when
implementing custom MATLAB math and measurements in the processing of remote control
programs. If you have a site license, the oscilloscope will occupy one seat when connected. For
individual licenses, the oscilloscope can be one of the three allowed installations.

Connecting and Disconnecting
The LeCroy-MATLAB interface is based on Active X technology and is greatly assisted by using the
ActiveDSO library. MATLAB applications use the actxserver keyword to connect to the instrument over
TCP/IP, for example:
app = actxserver('LeCroy.XstreamDSO.1', '')

Note: Use address 127.0.0.1 when the MATLAB application accessing the oscilloscope
application is running locally on the oscilloscope, rather than 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;

2-47

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