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.

should contain this copyright notice.

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

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

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

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.

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.

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

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

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

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.

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;

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)

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

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>

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

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; }

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

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

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.

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;

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.

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

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.

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.

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.

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

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.

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

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

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; }

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>

+ 114 hidden pages

Teledyne USB Analyzer Automation User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

1 Introduction

1.1 System Requirements

1.2 Setting Up Automation for Local Use

1.3 Setting Up Automation for Remote Use

2 Primary Dual Interface for Analyzer

2.1 IUsbAnalyzer Dual Interface

2.1.1 IAnalyzer::GetVersion

2.1.2 IAnalyzer::GetSerialNumber

2.1.3 IAnalyzer::OpenFile

2.1.4 IAnalyzer::StartGeneration

2.1.5 IAnalyzer::StopGeneration

2.1.6 IAnalyzer::StartRecording

2.1.7 IAnalyzer::StopRecording

2.1.8 IAnalyzer::MakeRecording

2.1.9 IAnalyzer::LoadDisplayOptions

2.1.10 IAnalyzer::GetRecordingOptions

2.1.11 IUsbAnalyzer::StopRecordingAndWaitForTrace

2.1.12 IUsbAnalyzer::get_ApplicationFolder (property)

2.1.13 IUsbAnalyzer::get_ApplicationDataFolder (property)

2.1.14 IUsbAnalyzer::StartUsb3Generation

2.1.15 IUsbAnalyzer::StopUsb3Generation