3385 Scott Blvd, Santa Clara, CA 95054 Tel: +1/408.727.6600 Fax: +1/408.727.6622 Automation API for CATC Bluetooth Analyzers Reference Manual Manual Version 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 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. CATC reserves the right to revise the information presented in this document without notice or penalty.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 TABLE OF CONTENTS Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Support Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Installing Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Setting Up Automation for Local Use . . . . . . . . . . . . . . . . . . .
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 ITrace::AnalyzerErrors . . . . . . . . . . . . . . . . . . . . . . 48 Primary dual interface for recording options . . . . . . . . . . . . . 49 IRecOptions::Load . . . . . . . . . . . . . . . . . . . . . . . . . 50 IRecOptions::Save . . . . . . . . . . . . . . . . . . . . . . . . . 51 IRecOptions::SetRecMode . . . . . . . . . . . . . . . . . . . 52 IRecOptions::SetBufferSize . . . . . . . . . . . . . . . . . .
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 Setting When and How Authentication Should Occur . . . 91 Set the Host Name or IP Address of the Host Controller . 93 Set Merlin Commands to Execute on the Host Controller 94 Set the Default Network Protocol . . . . . . . . . . . . . . . . . . . 95 Samples for Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Testing Your Automation Setup with AnalyzerClient.exe 97 How to Contact CATC . . . . . . . . . . . . . . . . . . . .
CATC Automation API for CATC Bluetooth Analyzers vi Ver. 1.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 1. Introduction CATC Bluetooth Analyzer Automation is an Automation Application Program Interface (API) for the CATC Bluetooth analyzers BTTracer, Merlin, Merlin II and Merlin Mobile. This API is designed to allow users to create scripts or programs of CATC analyzer 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.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 For additional tips, ideas and support for how to use the Automation API, please check the CATC's Bluetooth Community at: http://bluenews.catc.com/ 1.3 Installing Automation The Automation Kit provided with the Analyzer software includes this reference manual, readme file with release notes for the specific software version and a set of examples demonstrating the use of the Automation API.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 1.4 Setting Up Automation for Local Use If you intend to run Automation on the Host Controller (i.e., 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 will run the analyzer. 1.5 Setting Up Automation for Remote Use If you intend to run automation remotely over a network, you will need to perform DCOM configuration.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 1.7 Termination When the application is started in automation mode, the last client to disconnect will automatically cause the application to terminate. In the case that the application was started by the user on the server-side in GUI mode, a client is connected (even though it cannot retrieve tool interfaces), and the user attempts to close the application, a dialog will be presented indicating that a client is running and should be shut down.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 2. Automation API Description This chapter describes the commands in the BTTracer, Merlin, & Merlin Mobile Automation API. 2.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 diagram represents objects dependance: All interfaces are dual interfaces, which allows simple use from typeless languages as well as from C++. All objects implement ISupportErrorInfo interface for easy error handling from the client. The examples of C++ code given in this document assume using “import” technique of creating COM clients: For BTTracer: #import "BTAutomationTracer.
Automation API for CATC Bluetooth Analyzers CATC • Primary Dual Interface for Trace • Primary Dual Interface for Recording Options • Errors Collection Interface • Bluetooth Neighborhood Collection Interface • Primary Dual Interface for Bluetooth Device • Analyzer Events Callback Interface 7 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3 Primary Dual Interface for Analyzer The IBTAnalyzer interface derives from IAnalyzer interface and is the primary interface for the BTAnalyzer object. The IAnalyzer interface implements the common functionality for all CATC analyzers. 2.3.1 IAnalyzer interface definitions For BTTracer: Class ID: (5FC1BF5F-61C8-44E8-ABFF-AB587274BB26) App ID: CATC.BTTracer For Merlin II: Class ID: (865E00A9-AABC-4A14-85EF-82EB373F4EEB), App ID: CATC.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 , MB_OK ); else ::MessageBox(NULL, er.ErrorMessage(), _T("BTAnalyzer client"), MB_OK ); return 1; } TCHAR buffer[20]; _stprintf( buffer, _T("Software version:%X.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.3 IAnalyzer::GetSerialNumber HRESULT GetSerialNumber ( [out, retval] WORD* serial_number ); Retrieves serial number of analyzer device Parameters Return values ANALYZERCOMERROR_INVALIDVERSIONTYPE – specified version type is invalid device is not connected ANALYZERCOMERROR_ANALYZERNOTCONNECTED - analyzer Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.4 IAnalyzer::OpenFile HRESULT OpenFile ( [in] BSTR file_name, [out, retval] IDispatch** trace ); Opens trace file Parameters file_name trace - string providing the full pathname to trace file - address of a pointer to the BTTrace object primary interface Return values ANALYZERCOMERROR_UNABLEOPENFILE – unable to open file Remarks BTTrace object is created via this method call, if call was successful.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.5 IAnalyzer::StartGeneration HRESULT StartGeneration ( [in] BSTR gen_file_name, [in] short gen_mode ); Starts traffic generation from the file Parameters gen_file_name - string gen_mode - generation mode, 0 providing the full pathname to generation file – plays generation file once, 1 – plays generation file in the loop Return values E_NOTIMPL Remarks Not implemented yet.
Automation API for CATC Bluetooth Analyzers CATC 2.3.6 IAnalyzer::StopGeneration HRESULT StopGeneration ( ); Stops generation Return values E_NOTIMPL Remarks Not implemented yet. Example 14 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 try { bt_analyzer->StartRecording( ro_file_name ) } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("BTAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.
CATC Automation API for CATC Bluetooth Analyzers // query for VTBL interface IBTTrace* bt_trace; hr = trace->QueryInterface( IID_IBTTrace, (LPVOID *)&bt_trace ); trace->Release(); 19 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.10 IAnalyzer::CreateRecordingSnapshot HRESULT CreateRecordingSnapshot ( ) Causes the analyzer to create a temporary trace file without stopping the recording. Parameters None. Return values ANALYZERCOMERROR_UNABLEOPENFILE - Unable to create the snapshot trace file. Remarks The snapshot trace file includes all the recorded Bluetooth traffic from the beginning of the recording or from the previous call of this command to the present calls.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.11 IAnalyzer::LoadDisplayOptions HRESULT LoadDisplayOptions ( [in] BSTR do_file_name ); Loads display options that will apply for trace opened or recorded later Parameters do_file_name - string providing the full pathname to display options file Return values ANALYZERCOMERROR_UNABLELOADDO - unable to load display options file Remarks Use this method if you want to filter traffic of some type.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.12 IAnalyzer::GetRecordingOptions HRESULT GetRecordingOptions ( [out, retval] IDispatch** recording_options ); Retrieves primary interface for access to recording options Parameters recording_options - address of a pointer to the BTRecOptions object primary interface Return values Remarks BTRecOptions object is created via this method call, if call was successful. Example WSH: Set Analyzer = WScript.CreateObject("CATC.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.13 IBTAnalyzer::GetBTNeighborhood HRESULT GetBTNeighborhood ( [out, retval] IBTNeighborhood** bt_neighborhood ); Retrieves collection interface for access to bluetooth devices Parameters bt_neighborhood- address of a pointer to the BTNeighborhood object primary collection interface Return values Remarks BTNeighborhood object is created via this method call, if call was successful. Example WSH: Set Analyzer = WScript.CreateObject("CATC.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.14 IBTAnalyzer::SetLinkKey HRESULT SetLinkKey ( [in] BSTR addr, [in] BSTR link_key ); Sets link key for specified address Parameters addr - device link_key - link address (12 hex digits) key (32 hex digits) Return values Remarks Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") Analyzer.ResetEncryption Analyzer.SetPinCode "123456789012", "abcdefg" Analyzer.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.15 IBTAnalyzer::SetPinCode HRESULT SetPinCode ( [in] BSTR addr, [in] BSTR pin_code ); Sets pin code for specified address Parameters addr - device pin_code - pin address ( 12 hex digits ) code ( up to 16 characters ) Return values Remarks Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") Analyzer.ResetEncryption Analyzer.SetPinCode "123456789012", "abcdefg" Analyzer.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.16 IBTAnalyzer::ResetEncryption HRESULT ResetEncryption (); Clears all previously set link keys and pin codes Parameters Return values Remarks Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") Analyzer.ResetEncryption Analyzer.SetPinCode "123456789012", "abcdefg" Analyzer.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.3.17 IAnalyzer::SetConnectorsConfiguration HRESULT SetConnectorsConfiguration ( EBTAnalyzerConnectorsRole EBTAnalyzerRecChannel EBTAnalyzerRadioDataDirection EBTAnalyzerRecChannel role, radio_data_channel, radio_data_dir, clock_cal_channel) Sets the connectors configuration. Supported only in BTTracer. Parameters role - Sets the role of the configuration connectors of the connectors.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 "- 'G.P' (Breakout board)\n"; Radio data In this configuration the connectors are going to be used to output the radio signals (Rx, Tx, or both) as follows: EXT OUT' (BNC): In 'BTTrainer' mode - Outputs the radio Tx data for transmit slots of the selected channel. In 'BTTracer' modes - Outputs the radio Rx data for master slots of the selected channel (when synchronized to a piconet).
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 Both directions = 3 clock_cal_channel - Reserved. Currently not used. Return values Not Supported ANALYZERCOMERROR_INVALIDVERSIONTYPE -specified ANALYZERCOMERROR_ANALYZERNOTCONNECTED -analyzer version type is invalid device is not connected Remarks Look at the description in SetConnectorsConfiguration() for further details.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 2.4 Primary dual interface for trace IBTTrace interface is the primary interface for BTTrace object. It derives from ITrace interface that implements the common functionality for all CATC analyzers. The following section describes the ITracer interface supported by the Bluetooth analyzers.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.1 ITrace::GetName HRESULT GetName ( [out, retval] BSTR* trace_name ); Retrieves trace name Parameters trace_name - the name of the trace Return values Remarks This name can be used for presentation purposes. Do not forget to free the string returned by this method call. Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.2 ITrace::ApplyDisplayOptions HRESULT ApplyDisplayOptions ( [in] BSTR do_file_name ); Applies specified display options to the trace Parameters do_file_name - string providing the full pathname to display options file Return values ANALYZERCOMERROR_UNABLELOADDO - unable to load display options file Remarks Use this method if you want to filter traffic of some type in the recorded or opened trace.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("BTAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 _______|___________________________________________________________________ ____ 19_____| T(S) Freq(2430) Addr(0x7) DM1(0x3) L_CH(...UA/UI) L2FL(1) Len(0) _______| CRC(0x57BB) Ack'd(Yes) Idle(455.000 µs) Time Stamp(00010.833 9576) _______|___________________________________________________________________ ____ Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.5 ITrace::Close HRESULT Close ( ); Closes the trace Parameters Return values Remarks Closes current trace, do not releases interface pointer. Call IUnknown::Release method right after this method call. No one ITrace method call will succeeded after calling ITrace::Close method. (Currently there is no need to call ITrace::Close directly since IUnknown::Release will close the trace.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.6 ITrace::ReportFileInfo HRESULT ReportFileInfo ( [in] BSTR file_name ); Saves trace information into specified text file Parameters - string providing the full pathname to file where trace information report is created file_name Return values ANALYZERCOMERROR_UNABLESAVE - unable to create trace information report Remarks Creates trace information file if necessary. Stores trace information in specified file.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") Trace.ReportFileInfo CurrentDir & "Output\file_info.txt" C++: IBTTrace* bt_trace; TCHAR file_name[_MAX_PATH]; . . . try { bt_trace->ReportFileInfo( file_name ); } catch ( _com_error& er) { if (er.Description().
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.7 ITrace::ReportErrorSummary HRESULT ReportErrorSummary ( [in] BSTR file_name ); Saves trace error summary information into specified text file Parameters file_name - string providing the full pathname to file where error summary report is created Return values ANALYZERCOMERROR_UNABLESAVE - unable to create trace information report Remarks Creates error summary file if necessary. Stores error summary in specified file.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") Trace.ReportErrorSummary CurrentDir & "Output\error_summary.txt" C++: IBTTrace* bt_trace; TCHAR file_name[_MAX_PATH]; . . . try { bt_trace->ReportErrorSummary( file_name ); } catch ( _com_error& er) { if (er.Description().
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.8 ITrace::ReportTrafficSummary HRESULT ReportTrafficSummary( [in] BSTR file_name ); Saves trace traffic summary information into specified text file Parameters file_name - string providing the full is created Return values E_NOTIMPL Remarks Not implemented yet.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.
Automation API for CATC Bluetooth Analyzers CATC Next PacketStr = Left( PacketStr, NumberOfBits ) StatusText.innerText = "Packet ( " & NumberOfBits & PacketStr End If End Sub --> Ver. 1.40 & " bits ): " C++: IBTTrace* bt_trace; LONG packet_number; . . . VARIANT packet; VariantInit( &packet ); long number_of_bits; try { number_of_bits = bt_trace->GetPacket( packet_number, &packet ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.10 ITrace::GetPacketsCount HRESULT GetPacketsCount ( [out, retval] long* number_of_packets ); Retrieves total number of packets in the trace Parameters number_of_packets- points to long value where number of packets in the trace is retrieved Return values Remarks Example WSH: Set Analyzer = WScript.CreateObject("CATC.Merlin") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.11 ITrace::GetTriggerPacketNum HRESULT GetTriggerPacketNum ( [out, retval] long* packet_number ); Retrieves trigger packet number Parameters packet_number - points to long value where trigger packet number is retrieved Return values Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.Merlin") Set Trace = Analyzer.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.4.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 2.5 Primary dual interface for recording options IBTRecOptions interface is the primary interface for IBRecOption object. It derives from IRecOptions interface that implements the common functionality for all CATC analyzers.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.1 IRecOptions::Load HRESULT Load ( [in] BSTR ro_file_name ); Loads recording options from specified file Parameters ro_file_name - string providing the full pathname to the recording options file Return values ANALYZERCOMERROR_UNABLEOPENFILE – unable to open file Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.2 IRecOptions::Save HRESULT Save ( [in] BSTR ro_file_name ); Saves recording options into specified file Parameters ro_file_name - string providing the full pathname to the recording options file Return values ANALYZERCOMERROR_UNABLEOPENFILE – unable to open file Remarks If specified file does not exists it will be create, if it exists it will be overwritten. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.4 IRecOptions::SetBufferSize HRESULT SetBufferSize ( [in] long buffer_size ); Sets the size of buffer to record Parameters buffer_size - buffer size in bytes Return values E_INVALIDARG – invalid buffer size was specified Remarks This command sets the size of the buffer allocated in the internal memory of the system.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.5 IRecOptions::SetPostTriggerPercentage HRESULT SetPostTriggerPercentage ( [in] short posttrigger_percentage ); Sets the posttrigger buffer size Parameters posttrigger_percentage - the size of post trigger buffer in percents of the whole recording buffer ( see 4.5 ) Return values E_INVALIDARG – invalid percentage was specified Remarks This method call has no effect if recording mode was set to RMODE_SNAPSHOT ( see 4.4 ).
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.6 IRecOptions::SetTriggerBeep HRESULT SetTriggerBeep ( [in] BOOL beep ); Sets the flag indicating to make a sound when trigger occurs Parameters beep - TRUE – beep when trigger occurs, FALSE – do not beep when trigger occurs Return values Remarks The default state of the beeper is FALSE. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.7 IRecOptions::SetDataTruncate HRESULT SetDataTruncate ( [in] long length ); Sets the flag indicating that recorded data is to be truncated and the length of data to truncate Parameters length - length of data in bytes, could not be less then 108 Return values Remarks By default data is not truncating. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.
CATC Automation API for CATC Bluetooth Analyzers 2.5.8 IBTRecOptions:: SetDataTruncate This method is not implemented for IBTRecOptions interface. 57 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.9 IRecOptions::SetAutoMerge HRESULT SetAutoMerge ( [in] BOOL auto_merge ); Sets the flag indicating that recorded traces on different channels will be merged automatically after recording done. Parameters auto_merge - TRUE – perform merge automatically; FALSE – do not perform merge Return values Remarks By default automatic merge is not performing Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.
CATC Automation API for CATC Bluetooth Analyzers 2.5.10 IBTRecOptions::SetAutoMerge This method is not implemented for IBTRecOptions interface. 59 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.11 IRecOptions::SetSaveExternalSignals HRESULT SetSaveExternalSignals ( [in] BOOL save ); Sets the flag indicating to save external signals Parameters save - TRUE – save external signals, FALSE – do not save external signals Return values Remarks By default external signals are not saved. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.12 IRecOptions::SetTraceFileName HRESULT SetTraceFileName ( [in] BSTR file_name ); Sets the path to the file where trace will be stored after recording Parameters file_name - string providing the full pathname to the file where recording wiil be stored Return values Remarks If specified file does not exists it will be create, if it exists it will be overwritten. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.13 IRecOptions:: SetFilterPolarity HRESULT SetFilterPolarity ( [in] BOOL filter_out ); Sets the whether to filter in or out the recording events Parameters filter_out - TRUE - fTilter out, FALSE -filter in Return values E_INVALIDARG – operation code and/or connection was specified Remarks By default all events are filtered out Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.14 IBTRecOptions::SetMasterAddr HRESULT SetMasterAddr ( [in] BSTR master_addr ); Sets the option master address used by the Analyzer to implement all Piconet recordings options. Parameters master_addr - device address (12 hex digits) Return values E_INVALIDARG – invalid address was specified Remarks The address can be obtained dynamically using the Bluetooth neighborhood interface Example WSH: Set Analyzer = WScript.CreateObject("CATC.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.15 IBTRecOptions::SetPageTargetAddr HRESULT SetPageTargetAddr ( [in] BSTR target_addr ); Sets the page target used by the Analyzer when performing Passive Sync and Page Sync Piconet recording. Parameters target_addr - device address (12 hex digits) Return values E_INVALIDARG – invalid address was specified Remarks The address can be obtained dynamically using the Bluetooth neighborhood interface Example WSH: Set Analyzer = WScript.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.5.16 IRecOptions::Reset HRESULT Reset ( ); Resets recording options to its initial state Parameters Return values Remarks For default values of recording options see the remaks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.Merlin") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.SetRecMode 2 ' Event trigger RecOptions.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 2.6 Errors Collection Interface The IAnalyzerErrors dispinterface is a standard collection interface for collection of errors of specified type (see ITrace::AnalyzerErrors).
Automation API for CATC Bluetooth Analyzers CATC 2.6.1 IAnalyzerErrors::get_Item HRESULT get_Item( [in] long index, [out, retval] long* packet_number ); Parameters index - index packet_number - points of error in the collection to long value where error packet number is retrieved 67 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.6.2 IAnalyzerErrors::get_Count HRESULT get_Count( [out, retval] long* number_of_errors ); Parameters number_of_errors - points to long value where number of elements in the collection is retrieved Remarks Example WSH: ' makes recording, saves the portions of the recorded trace where "Bad VCRCs" errors occured CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 } for ( long i=0; iGetItem(i); TCHAR cur_error[32]; _stprintf( cur_error, _T(" %ld"), analyzer_error ); _tcscat( all_errors, cur_error ); } if ( i>2048/32 ) _tcscat( all_errors, _T(" ...") ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("BTAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 2.7 Bluetooth neighborhood collection interface The IBTNeighborhood dispinterface is a standard collection interface. The elements of this collection are the BTDevice objects.
Automation API for CATC Bluetooth Analyzers CATC 2.7.1 IBTNeighborhood::get_Item HRESULT get_Item( [in] long index, [out, retval] Idispatch** bt_device ); Parameters index - index bt_device - address of error in the collection of a pointer to the BTDevice object primary interface 71 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.7.2 IBTNeighborhood::get_Count HRESULT get_Count( [out, retval] long* bt_device_count ); Parameters bt_device_count - points to long value where number of elements in the collection is retrieved Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.Merlin") Set Neighborhood = Analyzer.GetBTNeighborhood MsgBox "Number of devices:" & Neighborhood.
CATC Automation API for CATC Bluetooth Analyzers 2.8 Primary dual interface for bluetooth device IBTDevice interface is the primary interface for BTDevice object. 73 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.8.1 IBTDevice::GetAddress HRESULT GetAddress ( [out, retval] BSTR* address ); Retrieves the address of device Parameters address - device address (12 hex digits) Return values Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.Merlin") Set Neighborhood = Analyzer.GetBTNeighborhood MsgBox "Number of devices:" & Neighborhood.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.8.2 BTDevice:: GetClockHz HRESULT GetClockHz ( [out, retval] LONG* clock_hz ); Retrieves the clock frequency of device Parameters clock_hz - device clock frequency (in Hz) Return values Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.Merlin") Set Neighborhood = Analyzer.GetBTNeighborhood MsgBox "Number of devices:" & Neighborhood.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.8.3 IBTDevice:: GetCoD HRESULT GetCoD ( [out, retval] LONG* cod ); Retrieves class of device Parameters cod - class of device Return values Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.Merlin") Set Neighborhood = Analyzer.GetBTNeighborhood MsgBox "Number of devices:" & Neighborhood.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 2.9 Analyzer events callback interface In order to retrieve the events from BTAnalyzer application you must implement _IAnalyzerEvents interface. Since this interface is default source interface for BTAnalyzer object there is very simple implementation from such languages like Visual Basic, VBA, VBScript, WSH etc.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.9.1 IAnalyzerEvents::OnTraceCreated HRESULT OnTraceCreated ( [in] IDispatch* trace ); Fired when trace is created; this event is a result of IAnalyzer::StartRecording/ IAnalyzer::StopRecording method call Parameters - address trace of a pointer to the BTTrace object primary interface Return values Remarks Make sure the event handlers have __stdcall calling convention.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 2.9.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.
CATC Automation API for CATC Bluetooth Analyzers 82 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 Appendix A: DCOM Configuration BTTracer, Merlin, & Merlin Mobile Automation can be run locally or remotely. This appendix describes how to configure Automation to run over a network in Windows 98. Automation uses Distributed Component Object Model (DCOM) to manage the transmission of automation commands over a network.
Automation API for CATC Bluetooth Analyzers CATC Step 5 Ver. 1.40 If you write a program in C++, make sure that the Merlin Host Controller is registered on both the client and server machine. A.4 DCOM Configuration for Merlin Host Controller To configure DCOM on the Merlin Host Controller, you will run a DCOM configuration utility called dcomcnfg. On Windows 2000 and Windows NT 4.0, DCOM and the dcomcnfg are bundled into the operating sytems.
Automation API for CATC Bluetooth Analyzers CATC Step 2 Select Run ... The Run dialog appears. Step 3 In the Open edit box within the Run dialog, type dcomcnfg. Step 4 Click OK. The DCOM configuration dialog box opens. The dialog box presents four tabs. 85 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 Step 5 In the Applications tab, scroll down the list of applications and select Merlin. Step 6 Click the Properties button. The Properties dialog box opens. The options in this dialog box allow you to configure security on the selected application. Step 7 From the Authentication Level menu, select Default. The Authentication Level menu lets you set packet-level security on communications for the selected application.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 The following settings display: You see three options: Access Permissions - Determines who may execute commands on the application once it has been started Launch Permissions - Determines who may launch the application Configuration Permissions - Determines who may configure permissions for the application Step 2 Click the User Custom Access permissions option. You are going to give all users permission to execute commands on the server.
Automation API for CATC Bluetooth Analyzers CATC Step 3 Click the Edit ... button. The Registry Value Permissions dialog box appears. Step 4 Click the Add ... button. The Add Users and Groups dialog box appears. 88 Ver. 1.
Automation API for CATC Bluetooth Analyzers CATC Step 5 Select the group called Everyone. Step 6 Click the Add button. Step 7 Select the group System. Step 8 Click the Add button. Step 9 Click OK. Ver. 1.40 The Add Users dialog box closes. Step 10 Click OK. T he Add Users and Groups dialog box closes. The Registry Key Permissions dialog box remains on the screen. Step 11 Click OK. The Registry Key Permissions dialog box closes. The Merlin Properties dialog box remains on the screen.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 Configuring Configuration Permissions You are going to give everyone permission to configure permissions the Merlin application on the Host Controller. Step 1 In the Security tab of the server Properties dialog box, select the option User Custom Configuration Permissions. Step 2 Click the Edit ... button. The Registry Value Permissions dialog box appears. Step 3 Click the Add ... button. The Add Users and Groups dialog appears.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 The following screen displays: Step 2 Make sure that the Interactive User option is selected.. A.5 DCOM Client Configuration DCOM client configuration is a four-step process: Step 1 Set authentication to occur upon connection with the Host Controller. Step 2 Set the Host name or IP address of the server that the client will be connecting to. Step 3 Set Merlin commands to run on the Merlin Host Controller.
Automation API for CATC Bluetooth Analyzers CATC Step 2 Ver. 1.40 Select Run ... The Run dialog appears. Step 3 In the Open edit box within the Run dialog, type dcomcnfg Step 4 Click OK. The following dialog box will appear: This dialog box presents a list of applications on the PC that support DCOM. Step 5 Select Merlin from the list of applications.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 Step 6 Click the Properties button. Step 7 Click the Authentication drop-down menu and select Default. Default tells the client to connect to the Merlin Host Controller using the Host Controller’s Authentication Level. Set the Host Name or IP Address of the Host Controller You need to identify the device upon which the client will be executing its commands.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 The Location window displays. Step 2 Select the option Run application on the following computer. Step 3 In the text box below the selected option, enter the Host Name or IP address of the Merlin Host Controller. If you do not know the name of the Host Controller, you can browse to it using the Browse ... button. Step 4 Click OK. The Properties dialog box closes. You will see the Distributed COM Configuration Properties dialog box.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 You should see the following settings. If the settings are not the same as those shown, change them to match the screenshot. Step 2 Note Select the option Enable Distributed COM on this computer. You will need to perform this step on both computers - the DCOM server and DCOM client. Set the Default Network Protocol Step 1 In the Distributed COM Configuration Properties dialog box, click the Default Protocols tab.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 The following screen will display. TCP/IP should appear at the top of the list. If it does not, use the Move Up button to move it to the top of the list. If the protocol does not appear at all, you will need to add it using the Add button. Step 2 Click OK to close the Distributed COM Configuration Properties dialog box. Your PC is now configured to run Merlin Automation. A.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 • html - Contains a directory with an HTML-based client application called analyzer1.html that is a simple interface to the Merlin Automation API. • wsh - This is a directory containing Visual Basic script files. You can run these script files by double-clicking on them. The To test your Automation setup, execute AnalyzerClient.exe (after compiling it first) or analzyer1.html, or double-click on one of the wsh files.
Automation API for CATC Bluetooth Analyzers CATC Step 2 Ver. 1.40 Double-click AnalyzerClient.exe. The application will start. If you prefer, you can copy the executable to your hard drive and launch it from there. Step 3 Enter the IP address or Host Name of the Merlin Host Controller. Step 4 Press Connect. The status message at the bottom of the window should change from ’Ready’ to a message that reads something like ’Merlin: Version 1.61’.
Automation API for CATC Bluetooth Analyzers CATC Ver. 1.40 sure that the account that you are using on the Host Controller is the same as the one you are using on the client PC and that both have Administrator privileges. Step 5 Click the button next to the Trace File text box. You are going to browse for a trace file. If you are going to run the comands over a network, you will need to supply the network path. Step 6 Browse for a trace file of your choice.
CATC Automation API for CATC Bluetooth Analyzers 100 Ver. 1.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 How to Contact CATC Contact Type of Service Call for technical support… US and Canada: 1 (800) 909-2282 Worldwide: 1 (408) 727-6600 Fax your questions… Worldwide: 1 (408) 727-6622 Write a letter… Computer Access Technology Corp. Customer Support 3385 Scott Blvd Santa Clara, CA 95054-3115 Send e-mail… support@CATC.com Visit CATC’s web site… http://www.CATC.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 altered by someone other than CATC, Products with missing or altered service tags or serial numbers, and Products for which CATC has not received payment in full. Coverage During Warranty Period During the Warranty Period, CATC or its authorized representatives will repair or replace Products, at CATC's sole discretion, covered under this limited warranty that are returned directly to CATC's facility or through CATC's authorized representatives.
CATC Automation API for CATC Bluetooth Analyzers Ver. 1.40 to have the Product repaired by CATC, you agree to pay CATC for the cost to return the Product to you and that CATC may require payment in advance of shipment. General Provisions THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE ADDITIONAL RIGHTS THAT VARY BY JURISDICTION. CATC'S RESPONSIBILITY FOR DEFECTS IN MATERIALS AND WORKMANSHIP IS LIMITED TO REPAIR AND REPLACEMENT AS SET FORTH IN THIS LIMITED WARRANTY STATEMENT.
CATC Automation API for CATC Bluetooth Analyzers 104 Ver. 1.
