Teledyne USB Analyzer Automation User Manual
Protocol Solutions Group
3385 Scott Blvd., Santa Clara, CA 95054
Tel: +1/408.653.1260
Fax: +1/408.727.6622
Automation API
Reference Manual
for
Teledyne LeCroy USBTracer™, Advisor
T3™, USB Advisor™, Mercury T2, and
Voyager M3/M3i/M3x™
USB Protocol Suite Software Version 4.70 and above
Manual Version 4.71
September, 2013
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
Document Disclaimer
The information contained in this document has been carefully checked and is believed to be
reliable. However, no responsibility can be assumed for inaccuracies that may not have been
detected.
Teledyne LeCroy reserves the right to revise the information presented in this document without
notice or penalty.
Trademarks and Servicemarks
CATC Trace, USBTracer, USBTrainer, USB Advisor, and Voyager are trademarks of Teledyne
LeCroy
Microsoft and Windows are registered trademarks of Microsoft Inc.
All other trademarks are property of their respective companies.
Copyright
Copyright © 2002 Teledyne LeCroy, Inc. All Rights Reserved.
This document may be printed and reproduced without additional permission, but all copies
should contain this copyright notice.
2
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
Contents
1 Introduction ................................................................................................ 6
1.1 ...... System Requirements ........................................................... 6
1.2 ...... Setting Up Automation for Local Use .................................... 6
1.3 ...... Setting Up Automation for Remote Use ................................ 7
2 Primary Dual Interface for Analyzer ......................................................... 8
2.1 ...... IUsbAnalyzer Dual Interface.................................................. 8
2.1.1 IAnalyzer::GetVersion ......................................................................... 8
2.1.2 IAnalyzer::GetSerialNumber ............................................................. 10
2.1.3 IAnalyzer::OpenFile........................................................................... 11
2.1.4 IAnalyzer::StartGeneration ................................................................ 13
2.1.5 IAnalyzer::StopGeneration ................................................................ 14
2.1.6 IAnalyzer::StartRecording ................................................................. 15
2.1.7 IAnalyzer::StopRecording ................................................................. 17
2.1.8 IAnalyzer::MakeRecording ................................................................ 18
2.1.9 IAnalyzer::LoadDisplayOptions ......................................................... 19
2.1.10 IAnalyzer::GetRecordingOptions ....................................................... 20
2.1.11 IUsbAnalyzer::StopRecordingAndWaitForTrace ............................... 21
2.1.12 IUsbAnalyzer::get_ApplicationFolder (property) ................................ 25
2.1.13 IUsbAnalyzer::get_ApplicationDataFolder (property) ........................ 26
2.1.14 IUsbAnalyzer::StartUsb3Generation ................................................. 27
2.1.15 IUsbAnalyzer::StopUsb3Generation ................................................. 30
2.1.16 IUsbAnalyzer::PauseUsb3Generation............................................... 32
2.1.17 IUsbAnalyzer::ResumeUsb3Generation ........................................... 34
2.1.18 IUsbAnalyzer::UsbUnplugPlug .......................................................... 35
2.2 ...... IUsbAnalyzer3 interface ...................................................... 36
2.2.1 IUsbAnalyzer3:: IssueManualTrig ..................................................... 36
2.3 ...... IUsbAnalyzer4 interface ...................................................... 37
2.3.1 IUsbAnalyzer4::GetRecordingStatus ................................................ 37
2.3.2 IUsbAnalyzer4::ResetUsb3Trainer .................................................... 37
2.3.3 IUsbAnalyzer4::IsUsb3GenerationIdle .............................................. 38
2.3.4 IUsbAnalyzer4::SwitchVBus .............................................................. 38
2.4 ...... IUsbAnalyzer5 interface ...................................................... 39
2.4.1 IUsbAnalyzer5::BindUnit ................................................................... 39
2.4.2 IUsbAnalyzer5::MergeTraceFiles ...................................................... 39
2.5 ...... IUsbAnalyzer6 interface ...................................................... 40
2.5.1 IUsbAnalyzer6::WaitForUsb3GenerationIdle .................................... 40
2.5.2 IUsbAnalyzer6::WaitForRecordingStatus .......................................... 40
3 Primary Dual Interface for Trace ............................................................. 42
3.1 ...... IUsbTrace Dual Interface .................................................... 42
3.1.1 ITrace::GetName .............................................................................. 43
3.1.2 ITrace::ApplyDisplayOptions ............................................................. 44
3
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
3.1.3 ITrace::Save ..................................................................................... 45
3.1.4 ITrace::ExportToText ........................................................................ 46
3.1.5 ITrace::Close .................................................................................... 48
3.1.6 ITrace::ReportFileInfo ....................................................................... 49
3.1.7 ITrace::ReportErrorSummary ........................................................... 51
3.1.8 ITrace::ReportTrafficSummary ......................................................... 53
3.1.9 ITrace::GetPacket ............................................................................ 54
3.1.10 ITrace::GetPacketsCount ................................................................. 57
3.1.11 ITrace::GetTriggerPacketNum .......................................................... 58
3.1.12 ITrace::AnalyzerErrors...................................................................... 59
3.2 ....... IUsbTrace2 interface ........................................................... 60
3.2.1 IUsbTrace2::GotoTime ..................................................................... 61
3.2.2 IUsbTrace2::GotoUnit ....................................................................... 62
3.2.3 IUsbTrace2::ExportToCsv ................................................................ 63
3.2.4 IUsbTrace2::SaveAs ........................................................................ 65
3.3 ....... IUsbTrace3 interface ........................................................... 66
3.3.1 IUsbTrace3:: GetPowerInfoByTime .................................................. 66
3.3.2 IUsbTrace3:: GetPowerInfoByPacket ............................................... 66
3.4 ....... IUsbTrace4 interface ........................................................... 68
3.4.1 IUsbTrace4:: GetFullName ............................................................... 68
3.5 ....... IUsbTrace5 interface ........................................................... 69
3.5.1 IUsbTrace5::GetUsbPacket .............................................................. 69
3.6 ....... IUsbVerificationScript Interface ........................................... 70
3.6.1 IUsbVerificationScript::RunVerificationScript .................................... 71
3.6.2 IUsbVerificationScript::GetVScriptEngine ......................................... 73
4 Primary Dual Interface for Packet .......................................................... 74
4.1 ....... IUsbPacket Interface ........................................................... 74
4.1.1 IUsbPacket::GetTimestamp .............................................................. 74
4.1.2 IUsbPacket::GetDuration .................................................................. 74
4.1.3 IUsbPacket::GetSpeed ..................................................................... 74
4.1.4 IUsbPacket::GetChannel .................................................................. 75
4.1.5 IUsbPacket::GetType ....................................................................... 75
4.1.6 IUsbPacket::GetFieldValue .............................................................. 77
4.1.7 IUsbPacket::GetAllFieldsValues ....................................................... 77
4.1.8 IUsbPacket::GetMarker .................................................................... 78
4.1.9 IUsbPacket::GetErrorsBitmap .......................................................... 78
4.1.10 IUsbPacket::GetRawData ................................................................ . 80
4.1.11 IUsbPacket::GetUsb3ScrambledData .............................................. 80
4.1.12 IUsbPacket::GetUsb3TenBitData ..................................................... 81
5 Primary Dual Interface for USB Verification Script Engine.................. 82
5.1 ....... IVScriptEngine interface ...................................................... 82
5.1.1 IVScriptEngine::VscriptName ........................................................... 83
5.1.2 IVScriptEngine::Tag ......................................................................... 84
5.1.3 IVScriptEngine::RunVScript .............................................................. 85
5.1.4 IVScriptEngine::RunVScriptEx ......................................................... 86
5.1.5 IVScriptEngine::LaunchVScript ........................................................ 87
4
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
5.1.6 IVScriptEngine::Stop ......................................................................... 88
5.1.7 IVScriptEngine::GetScriptVar ............................................................ 89
5.1.8 IVScriptEngine::SetScriptVar ............................................................ 91
6 Verification Script Engine Events Callback Interface ........................... 93
6.1 ...... _IVScriptEngineEvents dispinterface .................................. 93
6.1.1 _IVScriptEngineEvents::OnVScriptReportUpdated ........................... 96
6.1.2 _IVScriptEngineEvents::OnVScriptFinished ...................................... 97
6.1.3 _IVScriptEngineEvents::OnNotifyClient ............................................ 98
7 Primary Dual Interface for Recording Options .................................... 100
7.1 ...... IUsbRecOptions Dual Interface ......................................... 100
7.1.1 IRecOptions::Load .......................................................................... 101
7.1.2 IRecOptions::Save .......................................................................... 102
7.1.3 IRecOptions::SetRecMode .............................................................. 103
7.1.4 IRecOptions::SetBufferSize ............................................................ 104
7.1.5 IRecOptions::SetPostTriggerPercentage ........................................ 105
7.1.6 IRecOptions::SetTriggerBeep ......................................................... 106
7.1.7 IRecOptions::SetDataTruncate ....................................................... 107
7.1.8 IRecOptions::SetAutoMerge ........................................................... 107
7.1.9 IRecOptions::SetSaveExternalSignals ............................................ 109
7.1.10 IRecOptions::SetTraceFileName .................................................... 110
7.1.11 IRecOptions:: SetFilterPolarity ........................................................ 111
7.1.12 IRecOptions::Reset ......................................................................... 112
8 Errors Collection Interface .................................................................... 113
8.1 ...... IAnalyzerErrors dispinterface ............................................ 113
8.1.1 IAnalyzerErrors::get_Item ............................................................... 114
8.1.2 IAnalyzerErrors::get_Count ............................................................. 115
9 Analyzer Events Callback Interface ...................................................... 117
9.1 ...... _IAnalyzerEvents dispinterface ......................................... 117
9.1.1 _IAnalyzerEvents::OnTraceCreated................................................ 117
9.1.2 _IAnalyzerEvents::OnStatusReport ................................................ 118
10 CATCAnalyzerAdapter .......................................................................... 122
10.1 ... IAnalyzerAdapter Interface ................................................ 123
10.1.1 IAnalyzerAdapter::CreateObject ..................................................... 124
10.1.2 IAnalyzerAdapter::Attach ................................................................ 126
10.1.3 IAnalyzerAdapter::Detach ............................................................... 127
10.1.4 IAnalyzerAdapter::IsValidObject ..................................................... 129
Appendix A. DCOM Configuration ................................................................. 130
Appendix B. How to Contact Teledyne LeCroy ............................................ 144
5
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
1 Introduction
USBTracer™, USB Advisor™, and Voyager™ USB Protocol Suite Automation is an Application Program
Interface (API) that allows users to create scripts or programs of commands and run these scripts or
programs locally or remotely over a network. The name Automation is derived from the goal of allowing
engineers to automate test procedures.
The USBTracer, USB Advisor, and Voyager USB Protocol Suite Automation API is composed of a
command set that duplicates most of the functionality of the USBTracer, USB Advisor, and Voyager
Graphical User Interfaces. Automation is implemented through the use of scripts or programs that the
user can write using late binding scripting languages such as VBScript and WSH or early binding
languages such as C++. Teledyne LeCroy provides examples of scripts written in WSH, VBScript, and
C++.
Once an Automation script or program has been created, it can be run on the PC attached to or
transmitted to the PC over a network from a remote location. Automation uses the
Distributed Component Object Model (DCOM) protocol to transmit automation commands over a
network. When run over a network, the Host Controller is configured as a DCOM server and the remote
PC is configured as a DCOM client.
Note:
If you are using any application that uses the Automation Interface to the USB Protocol Suite, and the
system prompts you that it cannot write a trace file to disk:
1. Make sure that the trace-file destination folder has write/create permissions. (For example, the target
directory might be the netwrok file system, which typically does not have write/create permissions.)
2. Make sure that the Windows (or other) Firewall Settings for USB Protocol Suite are set to Public.
1.1 System Requirements
Automation is supported with USBTracer/Trainer and USB Advisor software version 1.7 or higher and
Voyager USB Protocol Suite software version 3.0 or higher. If you have an older version of the software,
you must upgrade. You can get a new version of software from the Teledyne LeCroy web site,
www.teledynelecroy.com/support. You also need a copy of the USBTracer, USB Advisor, and
Voyager USB Protocol Suite Automation software package. This is available from Teledyne LeCroy.
IMPORTANT! To compile with the correct linkage to the USB Automation API code, you must move the
USBAutomation.tlb file from the application's installed directory into a directory from which your
compiler can access the file. For example, for Visual Studio, this typically is the directory that contains
your project file and sources.
1.2 Setting Up Automation for Local Use
If you intend to run Automation on the Analyzer Host Controller (the PC attached to the Analyzer), you
do not need to perform any special configuration. You can simply execute the scripts or programs you
have created, and they run the Analyzer.
6
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Objects
Interfaces
Description
UsbAnalyzer
IUsbAnalyzer
IUsbAnalyzer3
Primary Analyzer interface
_IAnalyzerEvents
Analyzer event source
UsbTrace
IUsbTrace
Trace file interfaces
IUsbTrace2
UsbRecOptions
IUsbRecOptions
Recording options interface
UsbDevice
IUsbDevice
USB device interface
AnalyzerErrors
IAnalyzerErrors
Error collection interface
UsbAnalyzer
UsbRecOptions
UsbTrace
UsbDevice
AnalyzerErrors
Suite
1.3 Setting Up Automation for Remote Use
If you intend to run automation remotely over a network, you must perform DCOM configuration. These
steps are described in the Appendix.
The USB Protocol Suite API exposes the following objects and interfaces:
Only the UsbAnalyzer object is creatable at the top level (that is, via the CoCreateInstance call),
instantiation of an object of other classes requires API calls. The following diagram represents the object
dependencies:
All interfaces are dual interfaces, which allow simple use from typeless languages as well as from C++.
All objects implement the ISupportErrorInfo interface for easy error handling from the client.
The examples of C++ code given in this document assume using the “import” technique of creating COM
clients, using the corresponding include statement:
#import "UsbAutomation.tlb" no_namespace named_guids
and creating appropriate wrapper classes in .tli and .tlh files by the compiler.
Samples of WSH, VBScript, and C++ client applications are provided.
7
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT GetVersion (
[in] EAnalyzerVersionType version_type,
[out, retval] WORD* analyzer_version );
Suite
2 Primary Dual Interface for Analyzer
2.1 IUsbAnalyzer Dual Interface
IUsbAnalyzer interface is the primary interface for the UsbAnalyzer object. It derives from the
IAnalyzer interface that implements the common functionality for all Teledyne LeCroy Analyzers.
Class ID: 136D64A4-3CD5-4b41-974A-C7039E3FC292
App ID: CATC.USBTracer
COM server: UsbSuite.exe
IUsbAnalyzer IID: C37E7603-E3E5-48b4-8F79-080DBB543F0C
2.1.1 IAnalyzer::GetVersion
Retrieves the current version of the specified subsystem.
Parameters
version_type Subsystem whose version is requested;
EAnalyzerVersionType enumerator has the following
values:
ANALYZERVERSION_SOFTWARE ( 0 ) Software
ANALYZERVERSION_BUSENGINE ( 1 ) Bus engine
ANALYZERVERSION_FIRMWARE ( 2 ) Firmware
analyzer_version Current version of subsystem requested
Return values
ANALYZERCOMERROR_INVALIDVERSIONTYPE Specified version type is invalid.
ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer device is not connected.
Remarks
Example
WSH:
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
SwVersion = Analyzer.GetVersion(0)
BEVersion = Analyzer.GetVersion(1)
FwVersion = Analyzer.GetVersion(2)
MsgBox "Software" & SwVersion & "BusEngine" & BEVersion & "Firmware" & FwVersion
8
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
C++:
CLSID_UsbAdvisor,
NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer,
(LPVOID *)&poUsbAnalyzer ) )
return;
HRESULT hr;
IUsbAnalyzer* poUsbAnalyzer;
// create UsbAnalyzer object
if ( FAILED( CoCreateInstance(
WORD sw_version;
try
{
sw_version = poUsbAnalyzer ->GetVersion( ANALYZERVERSION_SOFTWARE );
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );
return 1;
}
TCHAR buffer[20];
_stprintf( buffer, _T("Software version:%X.%X"),
HIBYTE(sw_version),
LOBYTE(sw_version) );
9
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT GetSerialNumber (
[out, retval] WORD* serial_number );
Suite
2.1.2 IAnalyzer::GetSerialNumber
Retrieves the serial number of the Analyzer device.
Parameters
Return values
ANALYZERCOMERROR_INVALIDVERSIONTYPE Specified version type is invalid.
ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer device is not connected.
Remarks
Example
WSH:
C++:
CLSID_UsbAdvisor,
NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer,
(LPVOID *)&poUsbAnalyzer ) )
return;
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
MsgBox "Serial number: " & Analyzer.GetSerialNumber()
HRESULT hr;
IUsbAnalyzer* poUsbAnalyzer;
// create UsbAnalyzer object
if ( FAILED( CoCreateInstance(
WORD serial_number;
try
{
serial_number = poUsbAnalyzer ->GetSerialNumber();
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );
return 1;
}
TCHAR buffer[20];
_stprintf( buffer, _T("Serial number: %X"),
HIBYTE(serial_number),
LOBYTE(serial_number) );
10
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT OpenFile (
[in] BSTR file_name,
[out, retval] IDispatch** trace );
Suite
2.1.3 IAnalyzer::OpenFile
Opens a trace file.
Parameters
file_name String providing the full pathname to the trace file
trace Address of a pointer to the UsbTrace object primary interface
Return values
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file.
ANALYZERCOMERROR_WRONGCALL Error when trying to access the
opened trace when it is being
Remarks
UsbTrace object is created via this method call, if call was successful.
In rare cases, the method may return ANALYZERCOMERROR_WRONGCALL error. This may happen when
client code is trying to open an already opened trace file, while it is being released and destroyed.
Subsequent method calls will reopen the trace file.
released and destroyed.
11
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
Example
WSH:
C++:
CLSID_UsbAdvisor,
NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer,
(LPVOID *)&poUsbAnalyzer ) )
return;
// query for VTBL interface
hr = trace->QueryInterface( IID_IUsbTrace, (LPVOID *)&usb_trace );
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set Trace = Analyzer.OpenFile (CurrentDir & "Input\errors.usb")
HRESULT hr;
IUsbAnalyzer* poUsbAnalyzer;
// create UsbAnalyzer object
if ( FAILED( CoCreateInstance(
// open trace file
IDispatch* trace;
try
{
trace = poUsbAnalyzer->OpenFile( m_szRecFileName );
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );
return 1;
}
IUsbTrace* usb_trace;
trace->Release();
if( FAILED(hr) )
return;
12
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT StartGeneration (
[in] BSTR gen_file_name,
[in] long gen_mode,
[in] long loop_count );
Suite
2.1.4 IAnalyzer::StartGeneration
Starts USB 2.0 traffic generation from the file.
Parameters
gen_file_name String providing the full pathname to the generation file.
If a valid name, the file is opened after any pre-existing
Generation File is closed in accordance with the behavior set
forth by Bit 31 in the gen_mode parameter.
If NULL string, it just closes any existing Generation File.
gen_mode Generation mode:
Bit 0: 0 = bitstream; 1 = IntelliFrame
Bit 31: 0 = Load gen_file_name only if:
1. Different than pre-existing Generation Filename OR
2. The gen_file_name file is already loaded but has
been changed since the time it was loaded OR
3. The generation mode (bit 0) is different than the
previous invocation. Leaving this bit set to 0 allows
a file to be generated repeatedly without having to
be re-parsed or downloaded to the Analyzer
hardware, saving time.
loop_count Number of times to repeat:
-1 = loop forever
1 through 16381 executes generation file that number of times.
Return values
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to start generation
E_INVALIDARG
Remarks
Used to load a .utg file and begin generating traffic.
Example
1 = Reload gen_file_name unconditionally.
(USB 3.0 generation is running,
invalid state, or other)
13
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT StopGeneration ( );
Suite
2.1.5 IAnalyzer::StopGeneration
Stops any current USB 2.0 generation in progress.
Return values
ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to stop generation
(invalid state, etc.).
Remarks
Stop any current traffic generation.
Example
14
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT StartRecording (
[in] BSTR ro_file_name );
Suite
2.1.6 IAnalyzer::StartRecording
Starts recording with specified recording options.
Parameters
ro_file_name String providing the full pathname to recording options file.
If the parameter is omitted, then recording starts with the default
Return values
ANALYZERCOMERROR_EVENTSINKNOTINSTANTIATED Event sink was not instantiated.
ANALYZERCOMERROR_UNABLESTARTRECORDING Unable to start recording.
Remarks
After recording starts, this function returns. The Analyzer continues recording until it is finished
or until a StopRecording method call is performed. During the recording, the events are sent to the
event sink (see the _IAnalyzerEvents interface).
The recording options file is the file with extension .rec created by the USB Protocol Suite
application. You can create such a file by selecting Setup – Recording Options… from the
USB Protocol Suite application menu, changing the recording options in the dialog, and selecting the
Save button.
Example
VBScript:
<OBJECT
RUNAT=Server
ID = Analyzer
CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088"
>
</OBJECT>
<INPUT TYPE=TEXT VALUE="" NAME="TextRecOptions">
<SCRIPT LANGUAGE="VBScript">
<!-Sub BtnStartRecording_OnClick
On Error Resume Next
Analyzer.StartRecording TextRecOptions.value
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
End Sub
-->
</SCRIPT>
recording options.
15
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
C++:
IUsbAnalyzer* usb_analyzer;
BSTR ro_file_name;
. . .
try
{
usb_analyzer->StartRecording( ro_file_name )
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );
return 1;
}
16
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT StopRecording (
[in] BOOL abort_upload );
Suite
2.1.7 IAnalyzer::StopRecording
Stops a recording started by the StartRecording method.
Parameters
abort_upload TRUE, if caller wants to abort upload,
no trace file is created.
Return values
ANALYZERCOMERROR_EVENTSINKNOTINSTANTIATED Event sink was not instantiated.
ANALYZERCOMERROR_UNABLESTOPRECORDING Error stopping recording
Remarks
Stops recording started by the StartRecording method. The event is issued when recording is
actually stopped (via _IAnalizerEvents interface), if the parameter of method call was FALSE.
Example
VBScript:
<OBJECT
RUNAT=Server
ID = Analyzer
CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088"
>
</OBJECT>
<SCRIPT LANGUAGE="VBScript">
<!-Sub BtnStopRecording_OnClick
On Error Resume Next
Analyzer.StopRecording True
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
End Sub
-->
</SCRIPT>
C++:
IUsbAnalyzer* usb_analyzer;
. . .
try
{
usb_analyzer->StopRecording( FALSE )
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );
return 1;
}
FALSE, if you want to upload the recorded trace
17
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT MakeRecording (
[in] BSTR ro_file_name,
[out, retval] IDispatch** trace );
Suite
2.1.8 IAnalyzer::MakeRecording
Makes a recording with the specified recording options file.
Parameters
trace Address of a pointer to the UsbTrace object primary interface
Return values
Remarks
application. You can create such a file by selecting Setup – Recording Options… from the
USB Protocol Suite application menu, changing the recording options in the dialog, and selecting the
Save button.
Example
WSH:
C++:
// query for VTBL interface
hr = trace->QueryInterface( IID_IUsbTrace, (LPVOID *)&usb_trace );
ro_file_name String providing the full pathname to recording options file;
If the parameter is omitted, then recording starts with the
default recording options.
This method acts like StartRecording method but does not return until recording is completed.
UsbTrace object is created via this method call, if call was successful.
The recording options file is the file with extension .rec created by the USB Protocol Suite
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
IDispatch* trace;
IUsbAnalyzer* usb_analyzer;
BSTR ro_file_name;
HRESULT hr;
. . .
try
{
trace = usb_analyzer->MakeRecording( ro_file_name )
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );
return 1;
}
IUsbTrace* usb_trace;
trace->Release();
18
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT LoadDisplayOptions (
[in] BSTR do_file_name );
Suite
2.1.9 IAnalyzer::LoadDisplayOptions
Loads display options that apply for traces opened or recorded later.
Parameters
do_file_name String providing the full pathname to display options file
Return values
Remarks
method call apply only on trace files opened or recorded after this call.
You can create such a file by selecting Setup – Display Options… from the USB Protocol Suite
application menu, changing the display options in the dialog, and selecting the Save button.
Example
See ITrace::ApplyDisplayOptions.
ANALYZERCOMERROR_UNABLELOADDO Unable to load display options file.
Use this method if you want to filter traffic of some type. The display options loaded by this
Display options file is the file with extension .opt created by the USB Protocol Suite application.
19
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT GetRecordingOptions (
[out, retval] IDispatch** recording_options );
Suite
2.1.10 IAnalyzer::GetRecordingOptions
Retrieves the primary interface for access to recording options.
Parameters
recording_options Address of a pointer to the UsbRecOptions object
primary interface
Return values
Remarks
UsbRecOptions object is created via this method call, if call was successful.
Example
WSH:
C++:
CLSID_UsbAdvisor,
NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer,
(LPVOID *)&poUsbAnalyzer ) )
return;
// Query for VTBL interface.
hr = rec_opt->QueryInterface( IID_IUsbRecOptions, (LPVOID *)&ib_rec_opt );
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set RecOptions = Analyzer.GetRecordingOptions
HRESULT hr;
IUsbAnalyzer* poUsbAnalyzer;
// Create UsbAnalyzer object.
if ( FAILED( CoCreateInstance(
// Open trace file.
IDispatch* rec_opt;
try
{
rec_opt = poUsbAnalyzer->GetRecordingOptions();
}
catch (_com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );
return 1;
}
IUsbRecOptions* ib_rec_opt;
rec_opt->Release();
if( FAILED(hr) )
return;
20
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT StopRecordingAndWaitForTrace
( [out, retval] IDispatch** trace );
Suite
2.1.11 IUsbAnalyzer::StopRecordingAndWaitForTrace
Stops recording started by the StartRecording method and returns the pointer to the trace object
created.
Parameters
Return values
Remarks
This method stops recording started by the StartRecording method and does not return until the
recording is uploaded and a trace object related to this recording is created. In contrast, for
StopRecording, no event is issued when recording is stopped by this method.
In rare cases, the method may return ANALYZERCOMERROR_WRONGCALL error. This may happen when
recording stopped by itself (for example, because buffer is full), and the method call occurs when the
recorded trace is being released and destroyed. Subsequent method calls will reopen the recorded
trace. To avoid this issue, use a recording-buffer size that is big enough, so that the method call will
occur when recording is still in progress and recording buffer is not full.
trace Address of a pointer to the UsbTrace object primary interface
ANALYZERCOMERROR_UNABLESTOPRECORDING Error when stopping recording
ANALYZERCOMERROR_WRONGCALL Error when trying to access
trace when it is being destroyed.
21
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
Example
WSH:
' Extract the script name.
ScriptName = Right(WScript.ScriptFullName, Len(WScript.ScriptFullName) -
InstrRev(WScript.ScriptFullName, "\") )
Set Analyzer = WScript.CreateObject( "CATC.UsbTracer" )
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
' In the code below, we perform four sequential recordings and
' save the traces recorded in the current folder.
For I = 1 To 4
'Tell the CATC UWB analyzer to start recording.
Analyzer.StartRecording ( CurrentDir & "Input\test_ro.rec" )
' Imitation of some activity - just sleep for 3 seconds.
' Some real traffic generation code might be put here.
WScript.Sleep 3000
' Tell the analyzer to stop recording and give the trace acquired.
Set Trace = Analyzer.StopRecordingAndWaitForTrace
' Save the trace in the current folder.
Trace.Save CurrentDir & "Output\usb_seqrec_data" & CStr(I) & ".usb"
Next
Set Trace = Nothing
'Release the analyzer.
Set Analyzer = Nothing
MsgBox "Sequential recordings are completed." & String(2, 13) & "Look for recorded traces in the
folder : " & CurrentDir & "Output", 64, ScriptName
22
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
C++: (Raw code without using type library. All error handling is omitted for simplicity)
return;
IUsbAnalyzer* pAnalyzer = NULL;
// Create UsbAnalyzer object.
if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer, (LPVOID *)&pAnalyzer ) )
BSTR ro_file_name = SysAllocString( L"test_ro.rec" );
BSTR bstr_trace_name;
IDispatch* trace = NULL;
for( int i = 0; i < 4; i++ )
{
if( FAILED( pAnalyzer ->StartRecording( ro_file_name ) )
return; // Error handling and resources releasing should be done.
// Fake generation.
Sleep(3000);
if( FAILED( Analyzer->StopRecordingAndWaitForTrace( &trace ) ) )
return; // Error handling and resources releasing should be done.
IUsbTrace2* usbTrace = NULL;
// Query for IUsbTrace2 interface.
if( FAILED( trace->QueryInterface( IID_IUsbTrace2, (LPVOID*)usbTrace ) ) )
return; // Error handling and resources releasing should be done.
OLECHAR trace_name[_MAX_PATH];
swprintf ( trace_name, "test_data%u.usb", i );
SysAllocString( bstr_trace_name );
// Save the trace recorded to the current folder
usbTrace->Save( bstr_trace_name );
// Release the trace object.
trace->Release();
usbTrace->Release();
SysFreeString( bstr_trace_name ); // Free BSTR.
}
pAnalyzer->Release(); // Release the analyzer object.
SysFreeString( ro_file_name ); // Free BSTR.
23
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
C++: (Microsoft® C++ specific, using type library. All error handling is omitted for
simplicity.)
pAnalyzer->StartRecording( _bstr_t("test_ro.rec") );
// Fake generation: just sleep for 3 seconds.
Sleep(3000);
trace = pAnalyzer->StopRecordingAndWaitForTrace();
TCHAR trace_name[_MAX_PATH];
sprintf( trace_name, "test_data%u.uwb", i );
// Save the trace recorded in the current folder.
trace->Save( _bstr_t(trace_name) );
// Release the trace object.
trace = NULL;
}
IUsbAnalyzerPtr pAnalyzer = NULL;
pAnalyzer.CreateInstance( __uuidof(UsbAdvisor) );
if( !pAnalyzer ) return;
IUsbTrace2Ptr trace = NULL;
for( int i = 0; i < 4; i++ )
{
// Start recording using recording options file 'test_ro.rec' located in
// the current folder.
24
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT get_ApplicationFolder( [out, retval] BSTR *app_folder );
Suite
2.1.12 IUsbAnalyzer::get_ApplicationFolder (property)
Retrieves the full local path to the folder where the USB Protocol Suite application was installed and
registered as a COM server.
Parameters
Return values
Remarks
This property allows client applications to access some important files used by the USB Protocol Suite
application, such as recording options, display options, and trace files, in places relative to the USB
Protocol Suite application folder. If later the USB Protocol Suite application is re-installed to another
location, the client code does not have to be changed to reflect this event.
Example
WSH:
C++:
return;
app_folder Pointer to string variable indicating USB Protocol Suite application folder
Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
' Open trace file 'some_trace.usb' in the USB Suite folder.
Set Trace = Analyzer.OpenFile( Analyzer.ApplicationFolder & "some_trace.usb" )
' Save opened trace as 'some_trace1.usb' in the USB Suite folder.
Trace.Save Analyzer.ApplicationFolder & "some_trace1.usb"
...
HRESULT hr;
IUsbAnalyzer* poUsbAnalyzer;
// Create UsbAnalyzer object.
if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) )
BSTR app_folder;
hr = poUsbAnalyzer->get_ApplicationFolder( &app_folder );
// . . . Do something with app_folder.
SysFreeString( app_folder ); // Free BSTR resources.
poUsbAnalyzer->Release(); // Release analyzer object.
25
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT get_ApplicationDataFolder( [out, retval] BSTR *app_folder );
Suite
2.1.13 IUsbAnalyzer::get_ApplicationDataFolder (property)
Retrieves the full local path to the folder for user-alterable data, such as scripts, traces, and default
options files.
Parameters
app_folder Pointer to string variable indicating the
Return values
Remarks
This property allows client applications to access some important files used by the USB Protocol Suite
application, such as recording options, display options, and trace files, in places relative to the USB
Protocol Suite application folder, Windows XP Documents and Settings\All Users folder, and
Windows Vista Users\Public folder. If later the USB Protocol Suite application is re-installed to another
location, the client code does not have to be changed to reflect this event.
Example
WSH:
Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
' Open trace file 'some_trace.usb' in a user-modiable folder.
Set Trace = Analyzer.OpenFile(Analyzer. ApplicationDataFolder & "some_trace.usb")
' Save opened trace as 'some_trace1.usb' in a user-modiable folder.
Trace.Save Analyzer. ApplicationDataFolder & "some_trace1.usb"
...
C++:
HRESULT hr;
IUsbAnalyzer* poUsbAnalyzer;
// Create UsbAnalyzer object.
if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) )
return;
BSTR app_folder;
hr = poUsbAnalyzer->get_ApplicationDataFolder( &app_folder );
// . . . Do something with app_folder.
SysFreeString( app_folder ); // Free BSTR resources.
poUsbAnalyzer->Release(); // Release analyzer object.
USB Protocol Suite user-modifiable data folder
26
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT StartUsb3Generation([in,defaultvalue("")] BSTR gen_file_name);
Suite
2.1.14 IUsbAnalyzer::StartUsb3Generation
Starts generating USB traffic.
Parameters
gen_file_name USB 3.0 Exerciser script file name to execute.
If this parameter is an empty string, the last executed
Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED No Analyzer connected
ANALYZERCOMERROR_UNABLESTARTGENERATION Analyzer cannot start for one of
the following reasons:
Remarks
This function returns after generation starts. Analyzer continues generating until it finishes or until the
StopUsb3Generation or PauseUsb3Generation method call is performed.
During generation, events are sent to the event sink (see the _IAnalyzerEvents interface section).
The script file should have the file extension “.usb3g”. It can be created by either the USB Protocol Suite
text editor or any plain-text editor.
script is repeated.
- Script has compiling error.
- Analyzer is currently running or paused.
- Analyzer is currently used by another client.
- License for trainer device was not purchased.
- USB 2.0 generation is running.
27
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
Example
WSH (1):
See Automation\wsh\Usb3Exerciser.vbs
WSH(2):
Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")
' Tell the USB 3.0 Voyager Exerciser to start generation.
Analyzer. StartUsb3Generation CurrentDir & " \Input\Usb3ScriptExample.usb3g"
Dim doneGeneration
doneGeneration = 0
' Repeat Generation 49 more times.
For RepeatCount = 1 To 49
WScript.Sleep 100
Next
' Release the analyzer.
WScript.DisconnectObject Analyzer
' WScript.Echo "USBAnalyzer object has been disconnected."
Set Analyzer = Nothing
' WScript.Echo "Quitting WScript..."
WScript.Quit
' Handler of the event fired when recorded trace is created
' (after recording and uploading).
'
Sub Analyzer_OnStatusReport(ByVal subsystem, ByVal state, ByVal percent_done )
On Error Resume Next
if state = 400 Then
doneGeneration = 1
WScript.Echo "Generation finished"
End If
End Sub
VBScript:
On Error Resume Next
Analyzer.StartUsb3Generation PathToScript.value
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
Do While doneGeneration = 0
Loop
Analyzer.StartUsb3Generation
DoneGeneration = 0
<OBJECT
RUNAT=Server
ID = Analyzer
CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"
>
</OBJECT>
...<INPUT TYPE=TEXT VALUE="" NAME="PathToScript"> ...
...<INPUT TYPE=BUTTON VALUE="" NAME="BtnStartUSB3Generaion"> ...
<SCRIPT LANGUAGE="VBScript">
<!-Sub BtnStartUSB3Generaion_OnClick
End Sub
-->
</SCRIPT>
28
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
Suite
C++:
IUsbAnalyzerPtr usb_analyzer;
. . .
try
{
const char* gen_script_name = "C:\\Usb3ScriptExample.usb3g";
Usb_analyzer->StartUsb3Generation(_bstr_t( gen_script_name ) );
}
catch (_com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("USBAnalyzer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("USBAnalyzer client"), MB_OK );
return 1;
}
29
Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol
HRESULT StopUsb3Generation ();
Suite
2.1.15 IUsbAnalyzer::StopUsb3Generation
Stops USB 3.0 generation started by the StartUsb3Generation method.
Parameters
Return values
Remarks
Stops generation started by the StartUsb3Generation method. Generation stops if the analyzer is either
running or paused, and the analyzer then returns to the idle state.
Example
WSH:
Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")
' Tell the CATC USB analyzer to start generation.
Analyzer.StartUsb3Generation "example.usb3g"
WScript.Sleep 3000
' Tell the analyzer to stop recording.
Analyzer.StopUsb3Generation()
VBScript:
On Error Resume Next
Analyzer.StopUsb3Generation
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected
<OBJECT
RUNAT=Server
ID = Analyzer
CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"
>
</OBJECT>
<SCRIPT LANGUAGE="VBScript">
<!-Sub BtnStopUsb3Generation_OnClick
End Sub
-->
</SCRIPT>
30
Loading...