all | frequencies |
|
|
|
exhibits | applications |
---|---|---|---|---|---|---|
manuals |
app s | submitted / available | |||||||
---|---|---|---|---|---|---|---|---|
1 2 |
|
Main User Manual | Users Manual | 3.94 MiB | ||||
1 2 |
|
WAND Manual 1 of 2 | Users Manual | 2.19 MiB | ||||
1 2 |
|
WAND Manual 2 of 2 | Users Manual | 1005.70 KiB | ||||
1 2 | Cover Letter(s) | April 10 2002 | ||||||
1 2 | External Photos | April 10 2002 | ||||||
1 2 | ID Label/Location Info | April 10 2002 | ||||||
1 2 | Internal Photos | April 10 2002 | ||||||
1 2 | Test Report | April 10 2002 | ||||||
1 2 | Test Setup Photos | April 10 2002 | ||||||
1 2 | Parts List/Tune Up Info | |||||||
1 2 | Operational Description | |||||||
1 2 | Cover Letter(s) | |||||||
1 2 | Operational Description |
1 2 | Main User Manual | Users Manual | 3.94 MiB |
2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622 CATC BTTracer Bluetooth Protocol Analyzer Users Manual For Software Version 1.0 Manual Version 1.0 8 February, 2002 CATC Merlin Protocol Analyzer Users Manual Version 1.0 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. Trademarks and Servicemarks CATC, Merlin, Merlins Wand, NetMate, Advisor, Chief, FireInspector, Inspector, Detective, Traffic Generator, BusEngine, USB4DOS, UPT, HPT, UHT, Galaxy, IBTracer, SATracer, and Andromeda are trademarks of Computer Access Technology Corporation. Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Inc. All other trademarks are property of their respective companies. Copyright Copyright 2002, Computer Access Technology Corporation (CATC); All Rights Reserved. This document may be printed and reproduced without additional permission, but all copies should contain this copyright notice. FCC Conference Statement This equipment has been tested and found to comply with the limits for a Class A digital device and an intentional radiator, pursuant to Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference when the equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. Operation of this equipment in a residential area is likely to cause harmful interference in which case the user will be required to correct the interference at their own expense. The end user of this product should be aware that any changes or modifications made to this equipment without the approval of CATC could result in the product not meeting the Class A limits, in which case the FCC could void the user's authority to operate the equipment. 2 CATC Merlin Protocol Analyzer Users Manual Version 1.0 Important Notice: To comply with FCC RF exposure requirements
(sections 1.1307 and 1.310 of the Rules) only the antenna supplied by CATC must be used for this device. The antenna must be located at least 20 cm away from all persons. EU Conference Statement This equipment complies with the R&TT Directive 1999/5/EC. It has been tested and found to comply with EN55022:1994/A1:1995/A2:1997 Class A, EN61000-4-2:1995, EN61000-4-3:1995, EN61000-4-4:1995, EN61000-4-5:1995, EN61000-4-6:1995, EN61000-4-11:1994, EN61010-1:1993, and ESTI EN 300 328-1 V1.2.2 (2000-07). Manual Version 1.8 Part number: 730-0017-00 3 CATC Merlin Protocol Analyzer Users Manual Version 1.0 4 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 TABLE OF CONTENTS Chapter 1 Overview . 1 Bluetooth Overview . 1 General Description . 2 Automation. 4 Features . 4 General . 4 Physical Components . 5 Display Options . 5 Recording Options . 5 Traffic Generation . 5 Bluetooth BusEngine . 6 Specifications . 7 Package . 7 Power Requirements . 7 Environmental Conditions . 7 Switches . 7 LEDs . 7 Recording Memory Size . 7 Certification . 7 Chapter 2 Quick Installation . 9 Setting Up the Analyzer . 9 Installing the Software . 9 Your First Bluetooth Recording . 10 Chapter 3 Detailed Installation . 13 System Components/Packing List . 13 The Installed Merlin Unit. 13 Merlin System Setup . 14 AC Power Source . 14 External Interface Breakout Board. 15 Breakout Board External Output Signalling Pins . 16 Prototype Rework Area. 17 PC Connection . 17 Antenna Information . 17 Analyzer PC Requirements . 17 Merlin Program Installation . 18 Loading the Merlin USB Drivers . 18 Installing the Merlin Application Program . 18 Merlin Program Startup . 19 Making a Recording. 20 Chapter 4 Updates . 21 Software, Firmware, and BusEngine Revisions. 21 Software Updates . 22 iii CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Software License Updates . 22 Viewing licensing information . 23 BusEngine and Firmware UpdateUpdates . 23 Automatic Updates . 24 Manual Updates to BusEngine and Firmware . 25 Updating the BusEngine . 26 Updating the Firmware . 27 Chapter 5 Software Overview . 29 The Main Display Windows. 29 View Options . 31 Tool Bar. 31 Status Bar . 33 Recording Progress . 33 Recording Status . 34 Analyzer Status . 34 Search Status . 35 Zoom In. 35 Zoom Out . 35 Tool Tips. 35 Merlin Analyzer Keyboard Shortcuts . 36 Chapter 6 Recording Wizard . 37 Starting Recording Wizard . 37 Recording a Traffic on a New Piconet . 38 Recording an Existing Piconet
. 49 Recording in Test Mode . 58 Recording in Reduced Hopping Mode . 58 Recording in Single Frequency Mode . 62 Chapter 7 Recording Options . 63 Opening the Recording Options Dialog Box . 63 Recording Options - General . 64 Recording type . 64 Options . 65 Buffer Size . 65 Trigger Position. 65 Recording Options - Modes . 66 Recording Mode . 67 Inquiry Recording . 67 Piconet Recording . 68 Hop Sequence . 68 Sync Methods . 69 Force Re-synchronization . 72 Follow Master/Slave Switch . 73 Match Clock Rate . 73 Show Paging Traffic . 73 iv CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Piconet Addresses (MSB -> LSB) . 73 Other Parameters. 74 Debug/Test . 75 Recording Options - Events . 75 Events Options . 75 Payload Length Error . 81 Recording Options - Actions . 82 Actions Window Layout . 82 Action Buttons - Their Functions . 83 Counting Buttons - Their Functions . 83 Blue Dot Menus . 85 Saving Recording Options . 91 Recording Bluetooth Traffic . 92 Chapter 8 Display Options . 95 General Display Options . 95 Trace Viewing Level . 96 Creating New Display Options Files . 96 Color Display Options . 97 Formats Display Options . 99 Hiding. 100 Saving Display Options . 101 Chapter 9 Reading a CATC Trace . 103 Trace View Features. 103 Interpreting the Displayed Information . 103 Tooltips. 104 Set Marker . 104 Edit or Clear Marker . 105 Expanded and Collapsed Data Formats . 106 Hide Frequency Hops. 107 Hide Nulls and Polls. 108 Menus in Clicked Fields. 108 Hide Unassociated Traffic . 108 Chapter 10 Decoding Higher Protocols . 109 Introduction . 109 LMP and L2CAP Messages . 109 Decoding and Viewing Higher Protocol Data . 110 Decoding Via the Decoding Toolbar. 110 Decoding Via the Display Options Dialog Box . 111 Tooltips. 112 Viewing Packets in LMP and L2CAP Messages . 112 Types of LMP and L2CAP Messages . 112 Viewing L2CAP Channel Connections . 113 Viewing Protocol Messages and Transactions . 114 Viewing L2CAP Messages in Protocol Messages . 115 v CATC BTTracer Protocol Analyzer Users Manual Version 1.0 How to Decode . 115 Expanding Protocol Messages . 115 Changing Protocol Assignments . 116 Using the Decoding Assignments Dialog Box . 116 Removing User-Assigned Protocol Assignments . 117 Manually Assigning Protocols . 118 Other Assignments: OBEX Client/Server Status . 118 Changing an OBEX Client or Server Status . 119 Decoding BNEP . 119 Decoding HID . 119 Chapter 11 Other Features . 121 Search . 121 Go to Trigger. 121 Go to Packet/Message/Protocol . 121 Go to Marker. 122 Go to . 122 Error . 126 Soft Bit Error. 126 Loss of Sync . 126 Find . 126 Event Groups . 128 Union, Intersection, and Exclusion . 132 Using Find. 132 Find Next . 134 Edit Comment . 135 Reports . 135 File Information . 135 Error Summary . 136 Timing Calculations . 136 Traffic Summary . 137 BT Neighborhood. 139 Encryption . 139 Configuring Merlin for Encryption. 140 Chapter 12 How to Contact CATC. 143 Chapter 13 Warranty and License . 143 Index . 145 vi CATC BTTracer Protocol Analyzer Users Manual Version 1.0 1. Overview The CATC BTTracer Protocol Analyzer is a member in CATC's industry-leading line of high performance, serial bus protocol analyzers. Preceded by CATCs USB Chief and IEEE 1394 FireInspector Analyzers, BTTracer has been designed using the same modular software and hardware architecture that made its predecessors highly successful in the serial bus protocol analyzer market worldwide. 1.1 Bluetooth Overview The Bluetooth wireless technology is set to revolutionize the personal connectivity market by providing freedom from wired connections. It is a specification for a small-form factor, low-cost radio solution providing links between mobile computers, mobile phones and other portable handheld devices, and connectivity to the internet. The Bluetooth Special Interest Group (SIG), comprised of leaders in the telecommunications, computing, and network industries, is driving development of the technology and bringing it to market. The Bluetooth SIG includes promoter companies 3Com, Ericsson, IBM, Intel, Lucent, Microsoft, Motorola, Nokia and Toshiba, and more than 2500 SIG members. Bluetooth is a radio technology specification designed to transmit both voice and data wirelessly, providing an easier way for a variety of mobile computing, communications and other devices to communicate with one another without the need for cables. Bluetooth could make possible what is being called the personal-area network by allowing users to transmit small amounts of data at 1M bit/sec with a range of 10 to 100 meters, depending the power of the radio, over the 2.4-GHz radio frequency. The key benefits of the Bluetooth technology are robustness, low complexity, low power and low cost. Bluetooth employs a rapid frequency hopping mechanism to minimize the effects of collisions with other protocols and devices operating in the same frequency band. Mechanisms exist for a Bluetooth device to determine all devices in range as well as to request connection to a piconet as either a master or a slave. Please refer to the Bluetooth Specification, version 1.1 for details on the protocol. The Bluetooth specification is available from the Bluetooth SIG at its web site http://www.bluetooth.org/
1 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 1.2 General Description The BTTracer Protocol Analyzer is designed as a stand-alone unit that can be easily configured and controlled by a portable or desktop PC connected via its USB port. BTTracer provides customers with the familiar CATC Trace user interface that is the de facto industry standard for documenting the performance of high-speed serial protocols. BTTracer supports the functionality required to analyze all levels, including the baseband, of the Bluetooth wireless protocol. The featured Radio Interface allows users to probe and analyze transactions at the lowest level within the Bluetooth architecture. By creating this "Point of Observation"
or probing point within the radio level packet view, the user can analyze all levels of the protocol stack. BTTracer is a non-intrusive testing tool for Bluetooth piconets providing network traffic capture and analysis. Hardware triggering allows real-time events to be captured from a piconet. Hardware filtering allows the filtering out of fields, packets, and errors from the recording. Filtering allows users to focus recordings on events of interest and to preserve recording memory so that the recording time can be extended. Recorded data is presented in colored graphics in a trace viewer application. This application has advanced search and viewing capabilities that allow the user to quickly locate specific data, errors and other conditions, thereby focussing the users attention on events of interest. The BTTracer Protocol Analyzer functions with any personal computer using the Windows 98, Windows 98SE, Windows 2000, Windows NT 4.0, Windows ME, or Windows XP operating systems and equipped with a functional USB interface. For an updated set of system requirements for the host machine, please refer to the readme file. The Analyzer is configured and controlled through a personal computer USB port. It can be used with portable computers for field service and maintenance as well as with desktop units in a development environment. The Analyzer is easily installed by connecting a cable between the computers USB port and the Analyzers USB port. 2 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Sample Bluetooth Piconet with BTTracer Protocol Analyzer BTTracer provides on-the-fly detection of and triggering on such events as Packet Headers and Errors. Whether recording manually or with a specified trigger condition, BTTracer continuously records the bus data in a wrap-around fashion until manually stopped or until the Trigger Event is detected and a specified post-Trigger amount of bus data is recorded. Upon detection of a triggering event, the analyzer continues to record data up to a point specified by the user. Real-time detection of events can be individually enabled or disabled to allow triggering on events as they happen. This includes predefined exception or error conditions and a 3 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 user-defined set of trigger events. The unit can also be triggered by an externally supplied signal. An external DB-9 connector provides a path for externally supplied data or timing data to be recorded along with bus traffic. This DB-9 connector also provides a path for BTTracer to transmit externally two control, timing, or recovered signals for purposes of probing and use by other circuitry. The BTTracer software provides powerful search functions that enable investigation of particular events and allow the software to identify and highlight specific events. In addition to immediate analysis, you can print any part of the data. Use the Save As feature to save the data on disk for later viewing. The program also provides a variety of timing information and data analysis reports. 1.3 Automation The BTTracer software includes an Application Program Interface (API) for developing testing programs and scripts in C++ and Visual Basic. The API reproduces most of the commands embodied in the BTTracer trace viewer software. This API allows users to automate procedures that otherwise have to be run manually via the trace viewer software. The Automation API can be run locally on the PC attached to BTTracer or remotely over a network connection. For further details, download the BTTracer Automation Application Programming Interface Users Manual from the CATC website:
http://www.catc.com/support.html 1.4 Features General Flexible design - reconfigurable hardware for future enhancements.
User friendly - the Graphical User Interface software of BTTracer Analyzer is designed to be consistent with the CATC Trace using color and graphics to display Bluetooth traffic.
Radio Level Point of Observation and Capture - traffic capture at the Radio Level for comprehensive analysis.
Complies with Bluetooth v1.1 specification.
Automatic tracking of changes in the hopping scheme. Supports point-to-point and point-to-multipoint Bluetooth piconets. Supports both 79 frequency hop and 23 frequency hop standards. 4 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
Automatic tracking of whitened and non-whitened packets and traffic.
Compliant with FCC class A requirements / meets all CE mark Free non-recording, view-only software available. Power-on self-diagnostics. Internal 100V to 240 V AC power supply. requirements.
One year warranty and hot-line customer support. Physical Components Note For an updated description of requirements for the host machine, please refer to the readme file.
Trace viewer software support for all of the above plus Windows 95.
Recording memory of 128MB - enough to record twenty five minutes of high volume traffic. Display Options
Analyzes and displays a transaction-level view of piconet traffic with
accurate time-stamps and frequency hop information. Software analysis and data presentation at several protocol levels:
Baseband, LMP, L2CAP, SDP, RFCOMM, TCS, OBEX, HDLC, BNEP, PPP, AT, and HID Commands. Recording Options
Flexible advanced triggering capabilities including - multiple triggering modes, selective views, timing analysis, search functions, protocol packet errors, transaction errors, packet type and destination device, data patterns, or any of these trigger types in combination.
User defined trigger position.
Support for various piconet characteristics by enabling the user to configure the synchronization method and recording parameters.
Real-time hardware filtering of captured traffic for optimizing analyzer memory usage. Traffic Generation Traffic generation capability is provided by BTTrainer. 5 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Bluetooth BusEngine CATCs BusEngine Technology is at the heart of the new BTTracer Analyzer. The revolutionary BusEngine core uses state-of-the-art EPLD technology and incorporates both the real-time recording engine and the configureable building blocks that implement data/state/error detection, triggering, capture filtering, external signal monitoring and event counting
& sequencing. And like the flash-memory-based firmware that controls its operation, all BusEngine logic is fully field upgradeable, using configuration files that can be downloaded from the CATC Website. 6 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 1.5 Specifications Package Dimensions:
Connectors:
9.2 x 8.4 x 2.5 inches
(23.4 x 21.3 x 6.4 cm) AC power connection external clock input (EXT CLK, BNC) host connection (USB, type B) data connector (Data In/Out, 9-pin DB) Weight:
2.8 lbs. (1.2 kg) Power Requirements 90-264VAC, 47-63Hz (universal input), 100W maximum Environmental Conditions Operating Range:
Storage Range:
Humidity:
0 to 55 C (32 to 131 F)
-20 to 80 C (-4 to 176 F) 10 to 90%, non-condensing Switches Power:
Manual Trigger:
LEDs Power (PWR):
Recording (REC):
Triggered (TRG):
Synchronized
(SYNC):
on/off when pressed forces a trigger event illuminated when the analyzer is powered on. illuminated when the analyzer is actively recording traffic data. illuminated during power-on testing, and when the analyzer has detected a valid trigger condition. flashes during acquisition of the traffic hop sequence, illu-
minated when the analyzer is locked to the hop sequence. Recording Memory Size 128M x 8-bit DRAM for traffic data capture, timing, state and other data. Certification FCC (Class A), CE Mark 7 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 8 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 2. Quick Installation The BTTracer Protocol Analyzer components and software are easily installed and quickly ready to run on most Windows-based personal computer systems. You can begin making Bluetooth recordings after following these initial steps. However, if you are new to personal computers and protocol analyzers, or if you are unsure about what to do after reading the Quick Installation instructions, or if your analyzer does not work after you follow these instructions, read through the subsequent sections in this manual. 2.1 Setting Up the Analyzer Step 1 Attach the Antenna to the ANT connection point. The antenna should point up. Step 2 Connect the AC power cable to the rear of the analyzer. Step 3 Turn on the power switch on the rear of the analyzer. Step 4 Insert the BTTracer CD into the CD ROM drive of the PC that will be administering the Analyzer. If you prefer to install from diskette, insert the first BTTracer diskette (Disk 1 of 6) into the floppy disk drive. Step 5 Connect the USB cable between the USB port on the back of the analyzer and a USB port on the analyzing PC. Step 6 Follow Windows on-screen Plug-and-Play instructions for the automatic installation of the BTTracer Analyzer as a USB device on your analyzing PC (the required USB files are included on the BTTracer CD and the first BTTracer diskette). 2.2 Installing the Software Step 1 From the setup directory, run setup, and follow the on-screen instructions to install the BTTracer application on the analyzing PC hard disk. Step 2 To start the application, launch the CATC BTTracer program from the Start Menu:
Start>Programs>CATC>BTTracer. 9 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 2.3 Your First Bluetooth Recording After installing and launching the software, you can test BTTracer by creating a recording of a General Inquiry. In this test, BTTracer will issue a General Inquiry that asks local devices to identify themselves. BTTracer then records the responses. Step 1 Select Recording Options under Setup on the Menu Bar. The Recording Options dialog box will open showing factory default settings such as manual trigger and 1 Mbytes buffer size. For the General Inquiry recording you are about to create, these settings can be left unchanged. 10 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Select the Modes tab. The following dialog box will open showing factory default settings. BTTracer defaults to General Inquiry. For this recording, leave most of these settings unchanged. If you are recording a Hop Frequency that is not 79 Hops Standard, you will need to select the appropriate standard from the Hop Frequency menu below. Step 3 Click OK to close the Recording Options window and activate the recording options you selected. At this point, BTTracer will be ready to record. Step 4 Click on the Tool Bar. BTTracer starts to record the Bluetooth traffic immediately. The Bluetooth Inquiry process will proceed for 20 seconds. After 20 seconds has elapsed, the analyzer uploads the data and displays the packets. Step 5 If you wish to terminate the recording before the snapshot 11 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 automatically completes, click on the Tool Bar. After a few moments, the recording will terminate and the results will display. The screen should look like the sample recording below which shows the FHS packets generated during the Inquiry process. When the recording session is finished, the bus traffic is saved to the hard drive as a file named data.blt or whatever name you assign as the default filename. While the file is being saved, you should see a brown progress bar at the bottom of the screen. When the bar turns white, it indicates that the data has been saved to disk. Step 6 To save a current recording for future reference, Select Save As under File on the Menu Bar. OR Click on the Tool Bar. You see the standard Save As screen. Step 7 Give the recording a unique name and save it to the appropriate directory. 12 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 3. Detailed Installation 3.1 System Components/Packing List
One stand-alone BTTracer Analyzer module
One Antenna
One External Interface Breakout Board with a 9-pin ribbon cable
One 6-foot (2-meter) USB cable
BTTracer software program installation CD and diskettes
Product documentation 3.2 The Installed BTTracer Unit The BTTracer Analyzer has several user-accessible controls and LEDs on its front and rear panels of the OmniBus. Figure 1: Front Panel
Red PWR (power) indicator LED (lights when the unit power is switched on).
Green REC (recording) LED (lights when the unit is recording).
Yellow TRG (triggered) LED (lights when the unit triggers an event). Note TRG also lights during power-on testing and will be turned off at the end of the power on cycle. If the LED blinks at the end of this cycle, the hardware is faulty.
Green SYNC (synchronized) LED (lights when the unit is locked onto a specific piconet, based on the Master Address).
Manual Trigger push-button (allows a manual Trace capture) After beginning a recording session, press the Manual Trigger switch to force a Trigger condition. The session completes when a specified post-Trigger amount of bus data is recorded or when you manually stop a recording session.
ANT Bluetooth Antenna connector 13 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Figure 2: Rear Panel
Wide range AC connector module Power socket Enclosed 5x20 mm 2.0A 250 V fast acting glass fuse Warning: For continued protection against fire, replace fuse only with the type and rating specified above. Power on/off switch
External Clock (EXT CLK) input for future enhancement (Note: THIS PORT IS NOT USED)
USB type B host computer connector
Data In/Out DB-9 (9-pin) external interface connector Warning: Do not open the BTTracer Analyzer enclosure. There are no operator servicable parts inside. Refer servicing to CATC. 3.3 BTTracer System Setup The BTTracer Analyzer is designed to work with either desktop or laptop computers equipped with a functional USB interface. To set up the system hardware,
Attach the Antenna to the ANT connector. Set the antenna to point up.
Connect the Analyzer to an AC power source.
Connect the External Interface Breakout Board to the Data In/Out connector (optional).
Connect to the analyzing PC via USB. 3.4 AC Power Source Step 1 Connect the Analyzer box to a 100-volt to 240-volt, 50 Hz to 60 Hz, 100 W power outlet using the provided power cord. 14 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Note The Analyzer is capable of supporting supply voltages between 100-volt and 240-volt, 50 Hz or 60 Hz, thus supporting all known supply voltages around the world. Step 2 Use the power switch located on the rear panel to turn the analyzer unit on and off. Note At power-on, the analyzer initializes itself in approximately ten seconds and performs an exhaustive self-diagnostic that lasts about five seconds. The Trigger LED illuminates during the power-on testing and turns off when testing is finished. If the diagnostics fail, the trigger LED blinks continuously, indicating a hardware failure. If this occurs, call CATC Customer Support for assistance. 3.5 External Interface Breakout Board The External Interface Breakout Board is an accessory that allows convenient access to several potentially useful standard fast TTL output and input signals. It also offers a simple way to connect logic analyzers or other tools to the BTTracer Analyzer unit. Four ground pins and one 5-volt pin are provided. The Breakout Board connects via a ribbon cable to the Data In/Out connector located on the rear of the analyzer box. Each pin is isolated by a 100 series resistor and a buffer inside the Analyzer box. Figure 3: Data In/Out Connector Table 1 lists the pin-out and signal descriptions for the Data In/Out connector. Table 1: Data In/Out Connector Pin-Out Pin 1 2 3 4 5 Signal Name
+5V TRG IN GP IN TRG OUT GP OUT Signal Description
+5 Volts, 250mA DC source Trigger Input General Purpose Input Trigger Output General Purpose Output 15 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Pin 6 7 8 9 Signal Name GND GND GND GND Signal Description Ground Ground Ground Ground Table 2: External Interface Breakout Board Breakout Board External Output Signalling Pins The "TRG OUT" and "G.P. OUT" pins found on the Analyzers Breakout Board have similar functions. Both pins serve to transmit output signals when a trigger event occurs. The main differences between the two pins is in the number of signals that the Analyzer will send through them (TRG OUT will transmit just one signal whereas G.P. OUT may transmit several sequential signals), and in their initial state (TRG OUT is always enabled by the Analyzer whereas G.P. OUT must be enabled in the recording options before it can be utilized). TRG OUT When an event trigger occurs, TRG OUT transitions from ground to a continuous 5 V signal on the first instance of a trigger event. TRG OUT is a one-time event: it will not re-signal or change signals with subsequent triggering events. When this first trigger event occurs, the Trigger LED will illuminate (so this pin can be thought of as a reflection of the state of this LED). 16 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 G.P. OUT G.P. OUT needs to be enabled before it will output signalling. See Blue Dot Menus for the Event Buttons on page 88 for details on how to enable output signalling. If enabled, G.P. OUT will provide signalling each time a trigger event is detected by the Analyzer. G.P. OUTs signalling can be set to three different formats - "Pulse High" provides a 16.66 ns (ground to +5V) signal, "Pulse Low" a 16.66 ns (+5 V to ground) signal or "Toggle", a signal with an initial High (+5V) state that alternates with each trigger event between continuous High (+5 V) and continuous Low (Ground). "Pulse High" is the default condition. To change the format, see Enabling High Pulse, Low Pulse or Pulse Toggle Signal Outputs on page 88 for details. Prototype Rework Area The Breakout Board contains a prototype rework area for making custom circuits for rapid development. The area consists of plated-through holes, 20 columns wide by 27 rows long. The top row of holes is connected to GND and the bottom row is connected to +5V. The remaining holes are not connected. Use the rework area to insert custom components and wire-wrap their respective signal, power, and ground pins. 3.6 PC Connection Use the USB cable provided to connect the host computer to the BTTracer Analyzer. 3.7 Antenna Information According to the Bluetooth specifications, Bluetooth Antennas should be placed at least 10 cm apart. It is recommended that BTTracer be placed at least 1 meter away from the nearest device in the piconet under observation. 3.8 Analyzer PC Requirements For an updated description of requirements, please refer to the readme file. Note If installing BTTracer software on a Windows NT 4.0 system, you will need a separate set of diskettes, which is available from CATC. 17 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 3.9 BTTracer Program Installation The CATC BTTracer software is provided on a CD and also on six 3 inch diskettes. The software is also available on zip files at the CATC web site:
http://www.catc.com/support.html If you are downloading the files from the CATC web site, you will be retrieving several zipped files. The first of these has an executable called install.exe. Double-click on this file and follow the on-screen instructions. Installation of the analyzer software requires a Windows 98, Windows 98SE, Windows 2000, Windows ME, or Windows XP operating system. If you are loading BTTracer onto Windows NT 4.0 you will need to get a separate diskette and instructions from CATC. Loading the BTTracer USB Drivers Before you can install the BTTracer Windows application, you will need to install BTTracer as a USB device:
Step 1 Insert the BTTracer program CD into the CD ROM drive of the PC that will be administering the Analyzer. If you prefer to install from floppy diskette, install the floppy for your operating system labeled Disk 1 of 6 into the a: drive. Step 2 Power-on the BTTracer Analyzer. Step 3 Connect the USB cable to the rear of the analyzer and to the personal computer. The host operating system detects the analyzer and begins to install the USB driver. Step 4 Follow the installation instructions provided on your screen to complete the installation of the driver. Note When Windows prompts you for a file, browse to the CATC floppy in the a: drive. Installing the BTTracer Application Program Run Setup.exe from the BTTracer CD or from the BTTracer floppy disk 1 of 6. The CATC BTTracer Install Wizard automatically installs the necessary files to the computers hard drive. BTTracer software is installed in the C:\Program Files\CATC\BTTracer directory unless you specify otherwise. Follow the installation instructions on your screen. 18 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 3.10 BTTracer Program Startup You can start the BTTracer program from the Desktop or from the installed directory. The program always begins with its main screen active:
The software may be used with or without the analyzer box. When used without an analyzer box attached to the computer, the program functions in a Trace Viewer mode to view, analyze, and print captured protocol traffic. When the program is used with the BTTracer Protocol Analyzer attached to the computer, you can set trigger conditions, record, monitor and analyze the activity of your Bluetooth device or piconet. 19 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 3.11 Making a Recording After installation, the software is configured to make a manual recording
("Manual Trigger") of General Inquiry traffic. To make your first recording of this traffic, Step 1 Click on the Tool Bar. After 20 seconds, Inquiry timeout occurs and the analyzer will upload the data and display the packets. Step 2 Click To terminate the recording before Inquiry timeout occurs, on the Tool Bar at any time before recording automatically terminates. When the recording session is finished, the traffic is saved to the hard drive as a file named data.blt or whatever name you assign as the default filename. To save a current recording for future reference, Step 3 Select Save As under File on the Menu Bar. OR Click on the Tool Bar. You see the standard Save As screen. Step 4 Give the recording a unique name and save it to the appropriate directory. 20 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 4. Updates From time to time as modifications are made to BTTracer, it is necessary to update the Firmware and/or BusEngine for optimal performance. Updates can be performed two ways: either automatically or manually. This chapter describes both procedures. 4.1 Software, Firmware, and BusEngine Revisions The Readme.htm or Readme.txt file on the first installation disk and in the installed directory gives last-minute updates about the current release. Included with each release are the most recent downloadable images of the Firmware and the BusEngine. The Readme file lists the latest versions and informs you if new Firmware or a new BusEngine needs to be updated in your hardware. Once the Analyzer has completed the self diagnostics and is connected to the PC, you can check the latest revision of the software and BusEngine:
Selecting About Merlin in the Help Menu. You see this screen:
About Merlin details revisions of the following software and hardware:
Merlin Software Version
Merlin Firmware Version
BusEngine Version
Unit Serial Number Note When contacting CATC for technical support, please have available all the revisions reported in the About Merlin window. 21 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 4.2 Software Updates When a new software release is available, it is posted on the Support page of the CATC website at www.catc.com/support.html. To update the software, Step 1 In the About Merlin screen, verify which version of BTTracer Software you are currently running. Step 2 Find the latest released software version on the CATC website under Support. If you are running the latest version of the software, no further action is needed. If you are not running the latest version, continue to Step 3. Step 3 Click on the first link to download the zipped Disk 1 files for your operating system. Step 4 Click on the second link to download the zipped Disk 2 files. Step 5 Unzip the files into your choice of directory. Step 6 Click Start, then Run, and browse to where you unzipped the files. Step 7 Select the program named Setup and click Open. Step 8 Click OK to run the Setup and begin the installation. Step 9 Follow the on-screen instructions to complete the installation. Step 10 Read the Readme file for important information on changes in the release. 4.3 Software License Updates A license key is a file that CATC provides to you when you enter a maintenance agreement. You use this file when you make updates to your CATC software. 22 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 1 From the Help menu, select Update License. Step 2 Type the path and filename to the license key or click the Browse button to map to the directory containing the license key. Step 3 Click Update Device. Viewing licensing information You can also view licensing information to see what version of the license you are running. From the Help menu, select Display License Information. The following window appears containing information about the current status of your analyzers license:
4.4 BusEngine and Firmware UpdateUpdates BusEngine and Firmware updates often need to be performed when you update the BTTracer software. These updates can be performed automatically or manually. Both processes are described. 23 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Automatic Updates When BTTracers software is updated, the software may become incompatible with the BusEngine and Firmware. If a recording is attempted, BTTracer will display an error message and then automatically begin an update process for the BusEngine and Firmware. If you prefer, you can abort this update and undertake the steps manually as described later in this chapter. To perform an automatic BusEngine and Firmware update, Step 1 If needed, update the BTTracer software using the steps outlined in "Software Updates" described above. Step 1 Turn on the Analyzer. Step 2 On the toolbar, click the button. Since the BusEngine and/or the Firmware are incompatible with the current BTTracer software version, an error message will appear displaying your current versions and indicating what versions you need to install. Step 3 Click Yes. The above window closes and the Analyzer Setup window opens. Step 4 Click Update BusEngine or Update Firmware on the 24 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Analyzer Setup screen. You can select only one item at this point. If both the BusEngine and the Firmware need to be updated, the update will complete for the first item and then return to the above screen so the second update can be performed. When the second update has finished, you will see the following message telling you that the update is complete. Step 5 Power cycle BTTracer to complete the update. Manual Updates to BusEngine and Firmware You can manually update BTTracers Firmware and/or BusEngine by performing the following steps:
Step 1 Select Analyzer under Setup on the Menu Bar. You see the Analyzer Setup screen:
Step 2 Click Reset Analyzer The Analyzer resets, performs self-diagnostics, and returns to service. Note The self-diagnostics should complete about five seconds after the trigger LED lights. If the diagnostics fail, the trigger LED blinks on and off continually, indicating faulty hardware. If this occurs, contact CATC for customer support. 25 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Updating the BusEngine The BusEngine core is the heart of the Merlin Analyzer. Using state-of-the-art PLD technology, it incorporates both the high speed recording engine and the configurable building blocks that implement data/state/error detections, triggering, capture filtering, external signal monitoring, and event counting and sequencing. Both the BusEngine program and the Firmware that manages the internal microcontroller are fully field updateable. Within a new software release, it may be necessary to update the Analyzers BusEngine hardware for proper operation. The Readme file lets you know if this is necessary. To update the BusEngine, Step 1 Click Update BusEngine on the Analyzer Setup screen. You see the Select engine file window:
The program has already automatically searched for the correct file and displays it in the File name field. Note The most current Primary BusEngine file (BTTracer.rbf) was copied to your
\CATC\BTTracer directory when you installed the program. Step 2 Click Open. It is not necessary to restart the Analyzer. Once updated, the Analyzer takes approximately 15 seconds to reinitialize, with Time Remaining displayed on the screen. During this time the Trigger LED is on, indicating that 26 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 power-on diagnostics are being run. If there is a hardware failure, the Trigger LED continues to blink after initialization is complete. If this occurs, contact CATC for customer support. Updating the Firmware Within a new software release, it may also be necessary to update the Analyzers firmware for proper operation. The Readme file informs you if this is necessary. To update the firmware, Step 1 Click Update Firmware on the Analyzer Setup screen. You see the Select firmware file window:
The program has already automatically searched for the correct file and displays it in the File name field. Step 2 Click Open. The Analyzer updates the Firmware. Step 3 Unplug the USB cable from the back of the Analyzer box and then reinsert it so the new Firmware update can take effect. 27 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 28 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 5. Software Overview 5.1 The Main Display Windows While some of the analyzers Main Display window options are familiar, many contain options specific to the analyzer program. Table 3: Main Display Pull-Down Windows Function Menu File Open Close Save As Opens a file Closes the current file Saves all or a specified range of packets from the current file with a specified name Prints part or all of the current traffic data file Produces an on-screen preview before printing Sets up your current or new printer Print Print Preview Print Setup Edit Comment Creates or edits the Trace file comment field Export Packets to Text (Packet View Format) Export Packets to CSV Text Last File Exit Setup Saves all or part of a trace to a Comma Separated Values (CSV) file suitable for viewing in a spreadsheet application Lists the last files that were opened Exits the BTTracer program Saves all or part of a trace to a text file or to a Comma Separated Values
(CSV) file suitable for viewing in a spreadsheet application Display Options Provides the control of various display options such as color, formats, Recording Options Encryption Options ... Recording Wizard ... Analyzer and filters. Provides setup options for recording, triggering events and filtering events. Allows a pin code to be assigned to a device to facilitate encryption decoding. Starts a sequence of interactive dialog boxes that configures BTTracer for a recording. This utility provides an alternative to the Recording Options dialog box. Allows the operator to reset the Analyzer or update the BusEngine and Firmware. Record Start Stop Inquiry Piconet Causes the Analyzer to begin recording Bluetooth activity. Causes the Analyzer to stop recording. Provides a fast setting of the frequency hopping scheme and the inquiry mode. Provides a fast way for setting the frequency hopping scheme and the synchronization method. 29 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Menu Report Function File Information Error Summary Timing Calculation Traffic Summary Details such information about the recording as number of packets and triggering setup. Displays an error summary of the current trace file and allows you to go to a specific packet, and save the error file to a uniquely named file. Starts the calculator dialog for calculating various timing and bandwidth parameters in the recording file. Details the number and type of packets were transferred during the recording, as well as message-level statistics. Search Go to trigger Go to Packet/Message/
Protocol ... Go to Marker Go to Find Find Next Search Direction View Toolbars Status Bar Unhide cells Positions the display to show the first packet that follows the trigger event. Positions the display to the indicated packet, LMP/L2CAP message, or Protocol Message (RFCOMM, TCS, or SDP protocols). Positions the display to a previously marked packet. Enables quick searching for specific events using a cascade of pop-up windows. Allows complex searches. Repeats the previous Find operation. Can also use F3 to find next. Allows you to specify a forward or backward search of a trace file. Displays list of available toolbars. Switches display of the Status Bar on or off. Allows you to unhide cells. Zoom In Zoom in increases the size of the displayed elements. Zoom Out Zoom out decreases the size of the displayed elements. Wrap Allows the display to wrap. BT Neighborhood Displays Bluetooth Address and clock frequency for devices in range. The expected Bluetooth clock frequency is 3200 Hz +/- 250 ppm. Displays current decoding assignments and provides options for changing them. Decoding Assignments L2CAP connections Displays current L2CAP connections and provides options for RFCOMM Channel Assignments Levels changing them. Displays current RFCOMM Channel Assignments and provides options for changing them. Displays the level you select. 30 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Menu Window New Window Cascade Tile Function Switches display of the Tool Bar on or off. Displays all open windows in an overlapping arrangement. Displays all open windows in a side-by-side arrangement. Arrange Icons Arranges minimized windows at the bottom of the display. Windows Displays a list of open windows. Help Help Topics... Update License... Display License Information... About BTTracer... Displays online help. Opens a dialog box for entering license key information for the analyzer. Displays current license information for the analyzer. Displays version information about BTTracer. 5.2 View Options The View feature in the Menu Bar allows you to
Control the display of the Tool Bar and the Status Bar. Tool Bar The Tool Bar provides access to the most popular program functions. Tool tips describe icon functionality as the mouse arrow is moved over the icon/item. Open file Save As Preview Print Hide Nulls & Polls Hide Unassociated Traffic Complex Find Find Next Setup Record Options File Information Report 31 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Setup Display Options Traffic Summary Start Recording View Packet Level (Baseband) Stop Recording View/Hide LMP Message Level Bluetooth Neighborhood View/Hide L2CAP Message Level Setup Encryption Options View/Hide SDP Message Protocol Level Recording Wizard View/Hide SDP Transaction Protocol Level Zoom In Zoom Out Wrap View/Hide TCS Protocol Level View/Hide RFCOMM Protocol Level View/Hide OBEX Protocol Level Hide Frequency Hops View AT Commands Protocol Level Error Summary View/Hide PPP Timing Calculatons View/Hide HDLC Protocol Start BTTracers Wand View/Hide BNEP Protocol View HID Protocol Layer 32 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 5.3 Status Bar The Status Bar is located at the bottom of the main display window. Depending on the current activity, the bar can be divided into as many as four segments. Recording Progress When you begin recording, the left-most segment of the Status Bar displays a Recording Progress Indicator:
As recording progresses, the Progress Indicator changes to reflect the recording progress graphically:
In the Progress Indicator, a black vertical line illustrates the location of the Trigger Position you selected in Recording Options. Pre-Trigger progress is displayed in the field to the left of the Trigger Position in the before-Trigger color specified in the Display Options. When the Trigger Position is reached, the progress indicator wiggles as it waits for the trigger. After the trigger occurs, the field to the right of the Trigger Position fills in the post-Trigger color specified in the Display Options. When recording is complete, the upper half of the progress indicator fills in white, indicating the progress of the data upload to the host computer. You should be aware of two exceptional conditions:
If a Trigger Event occurs during the before-Trigger recording, the before-Trigger color changes to the after-Trigger color to indicate that not all the expected data was recorded pre-Trigger.
When you click Stop before or after a Trigger Event, the Progress Bar adjusts accordingly to begin uploading the most recently recorded data. The Progress Bar fills with color in proportion to the specified size and actual rate at which the hardware is writing and reading the recording memory. However, the Progress Indicator is normalized to fill the space within the Status Bar. 33 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Recording Status During recording activity, the current Recording Status is temporarily displayed in the next segment. When you activate the Record function, this segment flashes one of the following messages (depending on the selected Recording Options):
Trigger?
Triggered!
Uploading After recording stops, The flashing message changes to Uploading datax% done (x%
indicates the percentage completion of the data uploading process). The traffic data is copied to disk (overwriting any previous version of this file) using the default file name data.blt or a new name specified in the Recording options. To abort the upload process,
Press Esc on your keyboard OR Again click in the Tool Bar. You are prompted to choose whether to keep the partially uploaded data or to throw it away. When the data is saved, the Recorded Data file appears in the main display window and the Recording Status window is cleared.
If the recording resulted from a Trigger Event, the first packet following the Trigger (or the packet that caused the Trigger) is initially positioned second from the top of the display. If the recording did not result from a Trigger Event, the display begins with the first packet in the traffic file. Analyzer Status The third segment in the status bar displays analyzer status. During synchronization, the analyzer status will read:
Inquiring BTTracer is conducting a General Inquiry Syncing BTTracer is syncing to the Master device No Sync BTTracer has not yet started syncing to the Master device After the analyzer has synchronized to the Bluetooth piconet under observation, the Status Bar will display activity bars. The activity bars will increase or decrease with activity. If there are no vertical bars, there is no recorded activity. 34 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 During uploading, this segment displays the percent of the upload process completed. Note If packets are filtered from the recording or data are truncated, the recording activity is reduced. In addition to showing activity, the third segment of the Status Bar will also display the radio signal strength in dBm received by the analyzer. BTTracer can display five possible values:
below -60 dBm
- 60 dBm
- 50 dBm
- 40 dBm above - 40 dBm
The valid range for a signal is between -70 and - 20 dBm. Search Status The rightmost segment displays the current search direction: Fwd (forward) or Bwd (backward). Zoom In Zoom In increases the size of the displayed elements, allowing fewer (but larger) packet fields per screen.
Click on the Tool Bar. Zoom Out Zoom Out decreases the size of the displayed elements, allowing more (but smaller) packet fields per screen.
Click on the Tool Bar. 5.4 Tool Tips Throughout the application, tool tips provide useful information. To display a tool tip, position the mouse pointer over an item. The tool tip displays in a short moment if present. Tool tips can also be found over the Tool Bar and in areas of the packet view screen. 35 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 5.5 BTTracer Analyzer Keyboard Shortcuts Several frequently-used operations are bound to keyboard shortcuts. Table 4: Keyboard Shortcuts Key Combination Operation Ctrl+O Ctrl+Home Ctrl+F F3 Shift+I Shift+P Shift+M Shift+1 Shift+3 Shift+A Shift+5 Shift+7 Shift+S Open file Jump to First packet Search Forward Find Next Goto ID packet Goto Poll packet Goto DM1 packet Goto HV1 packet Goto HV3 packet Goto AUX1 packet Goto DH3 packet Goto DH3 packet Search for Soft Error Key Combination Operation Ctrl+P Ctrl+End Ctrl+B Ctrl+L Shift+R Shift+N Shift+F Shift+H Shift+2 Shift+V Shift+4 Shift+6 Shift+E Print... Jump to Last packet Search Backward Search for Loss of Sync Goto Freq Hop packet Goto Null packet Goto FHS packet Goto DH1 packet Goto HV2 packet Goto DV packet Goto DM3 packet Goto DM5 packet Search Error 36 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 6. Recording Wizard Recording Wizard is an interactive utility that presents a series of user-friendly dialog boxes for setting up a recording session. Recording Wizard serves as an alternative method of configuring the Recording Options dialog box. When you are finished using the Wizard, you can view your settings in the Recording Options window. By providing data to the prompts in the Wizards dialog boxes, you configure BTTracer for a recording session. Starting Recording Wizard To start the Recording Wizard,
Click on the Tool Bar or select Recording Wizard under Setup on the Menu Bar. You see the Recording Options window:
The Recording Options window has three buttons marked Next, Back, and Cancel that allow you to move forward or backward through the wizard or to cancel the wizard. To begin advancing through the wizard,
Click Next to see the options for the three types of recordings that the Recording Wizard can make. 37 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The Wizard advances to the next screen which presents three options:
Establish a new piconet and have BTTracer record traffic on that piconet. This option causes BTTracer to perform an Inquiry so it can discover local devices and then establish a new piconet and record the piconet traffic.
Record traffic on a piconet that has already been established. This option lets BTTracer record traffic from an already established piconet.
Record traffic in Test Mode on a test piconet. This option lets BTTracer create either a single frequency range recording of a range that you specify or create a recording of a limited hop frequency range consisting of 5 frequency hops. 6.1 Recording a Traffic on a New Piconet The New Piconet option shown in the previous screen presents users with the means of recording the traffic from a new piconet. This option will cause a sequence of screens to prompt you for information such as the piconet Master address. 38 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The following steps shows you how to configure BTTracer to record a new piconet. Step 1 From the screen shown in the previous screenshot, select the first option: I want to establish a new piconet and have BTTracer record traffic on that piconet, then press Next. The following screen displays. Step 2 Select the Frequency Hopping Mode for your country, then press Next. 39 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The following screen displays. Step 3 Select Perform Inquiry Now, then press Next. Selecting Perform Inquiry Now will cause BTTracer to perform a General Inquiry and collect addresses and other details about local Bluetooth devices. If you already have address information for your Bluetooth devices you can choose Skip Inquiry. Choosing Skip Inquiry will cause the Recording Wizard to advance to Step 6. If you are not sure what option to select, choose Perform Inquiry Now. The following screen will display. You will see two options:
40 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
I want to search for all Bluetooth devices within range This option will cause BTTracer to search for all Bluetooth devices that are in range and ready to transmit and receive data (i.e., in Inquiry Scan Mode)
I want to search only for devices corresponding to the following (hexadecimal) DIAC:
This option will cause BTTracer to search for the class of devices that you specify in the DIAC text box. DIAC stands for Device Inquiry Access Code. Values are entered in hexadecimal format. You can get DIAC values from the Bluetooth Specification. Step 4 Select the first option: I want to search for all Bluetooth devices within range, then press Next. The following screen will display. You will see two options:
Step 5 In the text box, enter the length of time you want BTTracer to search for nearby devices. The default value is 20. If you do not sure what time value to enter, use the default value. 41 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 6 Press Next. Before the Inquiry, BTTracer tests the hardware connection. In the case of failure, the following screen will display. Clicking OK will close the message box. If BTTracer passes the hardware test, it will search for devices. The Recording Wizard will display a progress bar and a message telling you that a search is under way:
42 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 If no device is found, the Recording Wizard will display the following screen:
If devices found, the Recording Wizard will display the following screen:
Two buttons will display:
Repeat - This button will cause BTTracer to repeat the General Inquiry
Show Devices Found - This button will cause a window to open and display details about the found devices. 43 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 7 Press the button marked Show Devices Found. The following screen will display:
Step 8 Click OK to close the window. Step 9 Press Next. The following window will display:
Step 10 Select from the drop-down menu the hexadecimal address for your Master device. If you do not see your devices address, you may type it into the text box yourself. 44 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The following window will display:
Step 11 Select from the drop-down menu the hexadecimal address for your slave device into the box labeled Piconet Slave Address. If you do not see your slaves address, you can type it into the box. Step 12 Press Next. The following screen will display. This screen displays the settings you selected. 45 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The Advanced button on the right will open the Recording Options dialog box shown below. This screen will show the settings you selected through the Recording Wizard have been applied to the Recording Options dialog. Step 13 Press Next to advance the Recording Wizard to the next screen. The following screen displays:
BTTracer pages the Master and if specified in Step 8, the Slave devices. 46 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 If BTTracer is unable to complete its pages, the following screen will display:
If BTTracer is able to complete its pages, it will enter into a synchronizing state and then wait for you to create the piconet. During this waiting period, BTTracer will display the following screen:
47 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Once you have created the piconet, BTTracer will synchronize to the piconet and begin recording. During the recording, BTTracer will display the following screen:
At the completion of the recording, BTTracer will display the following screen:
You can repeat the recording by pressing the Repeat button. Step 14 To close the wizard, press the Close button. 48 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The wizard will close and your trace will display. 6.2 Recording an Existing Piconet Using Recording Wizard to record an existing piconet is similar to recording a new piconet. The main difference is that you will be asked if your Master device can support multiple slave devices and whether it can respond to pages once it has created a piconet with another device. Step 1 To start the Recording Wizard, press Recording Wizard from the menu. or select Setup >
The Recording Wizard introductory page will open:
49 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Press Next to advance to the next screen. You will see three choices:
Step 3 Select the second option: I want BTTracer to record traffic on a piconet that has already been established. Step 4 Press Next. You will see four choices:
Select the hop mode appropriate to your area. Step 5 Select the hop mode appropriate to your area, then press Next. 50 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 You will see two choices:
Step 6 Select Perform Inquiry Now. You will see two choices:
Step 7 Select the first option: I want BTTracer to search for all Bluetooth devices within range. If you want to limit the inquiry to a class of devices, select the second option and enter the hexadecimal value for the device class in the text box. 51 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 8 Press Next. You will see two choices:
Step 9 If you want to change the search duration, type in a new value into the text box. Otherwise, use the default value (20 seconds), then press Next. The PC-BTTracer hardware connection will be tested. If BTTracer cannot be detected, the following message will display:
52 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 If BTTracer passes the hardware test, it will then goes onto conduct a General Inquiry to locate local Bluetooth devices. If BTTracer finds Bluetooth devices, it will display the following message:
Step 10 To display a list of the discovered devices, press the button 53 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 marked Show Devices Found. A screen will display showing the devices that BTTracer discovered through the General Inquiry:
If you feel that the list is incomplete, you can close this window and press the button marked Repeat. This will cause BTTracer to repeat the General Inquiry and recollect information on local Bluetooth devices. Step 11 Press OK to close the Bluetooth Neighborhood window. Step 12 Press Next to advance to the next screen. The following screen will prompt you for the Master devices address. The address can be selected from the drop-down menu or typed into the box:
Step 13 Select or type in the Master devices address into the box 54 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 next to the label Piconet Master Address. Step 14 Press Next. The following screen will display. This screen asks you which of the following two options apply to your Master device. For some devices, both options will apply. You can select either or both options. They are not mutually exclusive:
If the Master supports inquiries while in a connected state, select the first option. This will set BTTracer to use the 'Sync & Record' mode in its attempts to synchronize to the Master. This will also cause the wizard to skip to step 8. If the Master can support piconets with multiple slaves, select the second option. If you select this box alone (i.e., you leave the first box unchecked), BTTracer will use the 'Passive Sync & Record' mode to synchronize to the Master. The wizard will then advance to Screen 8*. If the first checkbox was selected, BTTracer will use 'Sync & Record' no matter what was set in the second box. Step 15 If you want to skip the Master verification, put a check in the box. If you are in doubt, leave the box unchecked. 55 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 If you selected only the second option in Step 15 (=Passive Sync &
Record), the following screen will display. This screen asks you for the address of the Page Target device -- which in this case is BTTracer. Since the devices in your piconet are not able to respond to inquiries, BTTracer will not be able to page the devices and join the piconet. Instead, you will assign BTTracer an address here in this screen, then direct your piconet Master device to connect to BTTracer. The Master will attempt to connect to BTTracer and therein give BTTracer the information it needs to record the Master and slave devices. Step 16 Type in an address of your choosing for BTTracer (= Page Target). You are making up an address for BTTracer that the Master will use to try to connect to BTTracer. 56 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 17 Press Next BTTracer will then display your current settings. The Advanced button will open the Recording Options dialog box shown on page 46 and described in detail in Chapter 7. Step 18 Press Next to begin the recording. If the BTTracer hardware is not ready or connected or is in the process of booting up, the following information message box will display:
Step 19 If the above information box opened, press OK to close it. 57 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The following dialog box will display:
Step 20 Press Retry or Back to re-attempt the process. If the hardware failure described in Steps 20 and 21 do not occur, BTTracer will conduct an inquiry. The screen will show that BTTracer is going to attempt a recording in either Passive Sync & Record mode as shown below or in Sync & Record mode depending on the options you selected in Step 15. Step 21 If you are recording in Passive Sync & Record mode, you will need to direct your Master device to attempt a connection to BTTracer. This will provide BTTracer with the information it needs to record the piconet. 58 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Once BTTracer has the information it needs, it will begin recording. The following screen will display:
The recording will end following a trigger event or when you press Stop Recording button on the screen shown above or when you press the button on the toolbar. Step 22 When finished, press Close to close the Recording Wizard. 6.3 Recording in Test Mode A Test Mode recording allows you to limit the frequency hopping range that BTTracer will record. Two Test Modes are available: Reduced Hopping Mode and Single Frequency Mode. Reduced Hopping Mode limits BTTracers recording to the five frequency hops that are described in the Bluetooth Specification. Single Frequency Mode limits BTTracers recording to a single frequency range that you specify in the Recording Wizard. Recording in Reduced Hopping Mode To record in Reduced Hopping Mode, perform the following steps:
Step 1 Start the Recording Wizard by either pressing the button or selecting Setup > Recording Wizard from the menu. The Recording Wizard greeting screen will open. 59 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Press Next to advance to the Recording Type screen. The following screen will display:
Step 3 Select the third option: I am using Bluetooth Test Mode and want BTTracer to record traffic on my test piconet. Step 4 Press Next. The following screen will display:
60 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 5 Select the option Reduced-hopping mode, then press Next. The following screen will display:
Step 6 Select the address for your piconets Master device from the drop-down menu. If you prefer, you can type in the address into the box. Step 7 Press Next. The following screen will display. This screen will show the current settings for the recording:
The Advanced button will open the Recording Options dialog box. See Chapter 7 for details on the Recording Options dialog box. 61 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 8 Press Next to begin the recording. The following screen will display:
Step 9 When the recording finishes, the following screen will display. You can repeat the recording by pressing the Repeat button. Step 10 To close the wizard, press Finish. 62 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 6.4 Recording in Single Frequency Mode Step 1 In the Recording Type window, select the third radio button and click Next. Step 2 In the Frequency Hopping Mode, window select the Single-Frequency Mode radio button, enter the appropriate values in the text boxes, and click Next. 63 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 64 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 7. Recording Options The Recording Options dialog box lets you configure BTTracer for recording Bluetooth data. This dialog box offers an alternative to the Recording Wizard described in the previous chapter. At the top of the Recording Options dialog box are four tabs that provide access to dialog boxes called General, Modes, Events, and Actions. Using these dialog boxes, you can configure BTTracer to create event triggers, increase or decrease memory allocation for recording, and interact with other Bluetooth devices in different ways. Opening the Recording Options Dialog Box To open the Recording Options menu, click Recording Options under Setup on the Menu Bar. on the Tool Bar or select You see the Recording Options window:
The Recording Options window has four tabs marked 63 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
General
Modes
Events
Actions 7.1 Recording Options - General The General tab is displayed by default when the Recording Options dialog box is oppened. It is shown in the previous illustration. The General tab display four boxes marked Recording Type, Buffer Size, Trigger Position, and Options. Recording type The Recording Type box presents three options that allow you to set how BTTracer begins and ends a recording. The options are: Snapshot, Manual Trigger, and Event Trigger. Snapshot A Snapshot is a fixed-length recording whose size is determined by the
"Buffer Size" box in the Recording Options dialog or by a manual click of the Stop button. Recording begins by clicking on the Tool Bar and ends when either the selected buffer size is filled or you press the Stop button. Manual Trigger A Manual Trigger recording is a one that is manually begun and ended. on the Tool Bar. Recording continues Recording is begun by pressing in a circular manner within the limits set by the buffer size. Recording ends when is clicked on the Tool Bar or the Trigger button is pressed on the analyzer's front panel. If you press the Trigger button, recording will continue until the post-trigger memory has been filled. Event Trigger An Event Trigger recording is one that uses an event trigger to end the recording. Before recording begins, you define the event trigger in the Trigger Options dialog box. You begin the recording by clicking the Tool Bar. Recording continues in a circular manner within the limits set by the buffer size. Once the trigger event occurs, some post-trigger recording occurs, then the recording ends. on Note In this mode, the recording can be stopped manually in the same way as for
"manual trigger" mode. 64 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Options The Options box contains two options:
Beep When Trigger Occurs Will cause the PC to beep when a trigger event has occurred. Save External Interface Signals Will enable BTTracer to record input signals from a breakout board as fields in a trace. Buffer Size The Buffer Size box has a slide bar for adjusting the recording buffer size from 0.1 megabytes to 128 megabytes. The Recording Type option determines how this buffer is used. Although there are 128 megabytes of physical memory in the analyzer, the efficiency of the recording ranges from 2:1 to 4:1 ratios of physical memory to actual Bluetooth traffic. Shorter Bluetooth packets yield a less efficient recording. The non-traffic portion of physical memory is utilized for control and timing information. Note The scale is not linear and affords more granularity in the smaller buffer sizes. Trigger Position The Trigger Position slide bar sets the amount of post-trigger recording that BTTracer will perform. It also allows adjustment of the location of the trigger within the defined buffer. You can adjust the Triggering Position between 1 and 99% post-Trigger. Trigger Position is available only when Manual Trigger or Event Trigger is selected as Recording type. As an example, if the buffer size is set to 16MB, then for the following Trigger Position settings, the amount of pre- and post-Trigger data is 65 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
95% post-triggering: 0.8MB pre-trigger, 15.2MB post-trigger
75% post-triggering: 4MB pre-trigger, 12MB post-trigger
50% post-triggering: 8MB pre-trigger, 8MB post-trigger
25% post-triggering: 12MB pre-trigger, 4MB post-trigger
5% post-triggering: 15.2MB pre-trigger, 0.8MB post-trigger Note When a Trigger occurs, recording continues until the post-Trigger amount of the buffer is filled. 7.2 Recording Options - Modes The tab marked Modes opens a window for setting recording mode options. This window is divided into six boxes marked Recording Mode, Piconet Addresses, Hop Frequency, Other Parameters, and Debug/Test. 66 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Recording Mode To record Bluetooth traffic, the BTTracer analyzer needs to synchronize to the piconet under observation. BTTracer does not participate in the piconet and behaves as a passive listener. It needs, however, to communicate briefly with the devices in the piconet to learn the Master clock and frequency hopping sequence. To synchronize to the piconet under observation, BTTracer can be set up in different recording modes: Inquiry Recording and Piconet Recording. The option you select affects the types of settings that display in the window. Inquiry Recording Selecting the "Inquiry Redcording" button causes the Modes window to display the options shown in the previous screenshot. The "Inquiry Recording" option presents two choices for recording Inquiries: "General (Unlimited)" and "Dedicated (Limited)."
General (Unlimited)
"General" means "General Inquiry" and is used to search for ALL Bluetooth devices that are within range, for the amount of time specified in the Inquiry Timeout field. Completion of the inquiry process is indicated by illumination of the "trigger" light on the front of the analyzer. All responding packets will be displayed when data upload from the analyzer completes. Dedicated (Limited)
"Dedicated" means a specific class or group of Bluetooth devices
(designated by the DIAC field of the Recording Options dialog). Selecting
"Dedicated" causes BTTracer to search for all devices from a specific class or group that are within range, for the amount of time specified in the Inquiry Timeout field. Completion of the inquiry process is indicated by illumination of the "trigger" light on the front of the analyzer. All responding packets will be displayed when stop is selected. 67 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Piconet Recording The "Piconet Recording" option presents three choices for recording piconet traffic: Sync and Record, Passive Sync & Record, and Page Sync & Record. A Help button next to the menu briefly explains these options. Page Sync & Record is the preferred option and should be used whenever possible. If Page Sync & Record can not be used, then Sync & Record should be used. Passive Sync and Record should be used only if the first two options can not be used. Hop Sequence Until recently, local regulations in Japan, France, and Spain defined a Bluetooth frequency range that was different than the range used by the rest of the world. We have included the selections for organizations for testing of devices developed before all frequencies were made available on a world-wide basis. To set BTTracer to the correct Hop Frequency, select from the drop-down menu one of the following choices:
68 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
79 Hops Standard
23 Hops Japan
23 Hops Spain
23 Hops France
Reduced Hop - Restricts BTTracer to five hop frequencies defined in the test mode specification of the Bluetooth Specification. When Reduced Hop or Single Frequency is selected, the Sync method is set to Test Mode and cannot be modified by the user.
Single Frequency - Allows the the transmit and receive frequency ranges to be specified. Selecting this option highlights the "DUT Xmit" and "DUT Recv" text boxes. When Reduced Hop or Single Frequency is selected, the Sync method is set to Test Mode and cannot be modified by the user.
Enter values into the two text boxes to the set the transmit and receive frequency ranges:
DUT Xmit Freq, MHz (+2402) Allows the setting of the transmit signal for the Device Under Test
DUT Recv Freq, MHz (+2404) Allows the setting of the receive signal for the Device Under Test Sync Methods Note If the selected Hop Sequence is "Reduced Hop" or "Single Frequency," the Sync Method is set to "Test Mode" and cannot be modified by the user. Page Sync & Record
"Page Sync and Record" is the recommended method of recording. "Page Sync and Record" should be implemented before a piconet is established. This mode causes BTTracer to perform a General Inquiry and collect sync information from the specified slave device when it responds. BTTracer then waits for the Master to begin paging the Slave devices. When paging begins, BTTracer synchronizes to the Master and begins recording. Note In order for this mode to work, the intended Slave must support "inquiry scan". The following steps describe the simplest way to use this mode:
Step 1 Place both the "intended master" as well as its first "intended slave"
into inquiry scan mode. 69 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Have BTTracer perform a General Inquiry. You do this by selecting
"General (Unlimited)" from the "Inquiry Recording" drop-down menu on the "Modes" tab in the "Recording Options" window, and then depressing the "REC" button found on BTTracer's toolbar. Step 3 After the General Inquiry completes, as indicated by the automatic uploading and displaying of a CATC trace (approximately 20 seconds), reselect the "Modes" tab in the "Recording Options". At this point, the addresses of all Bluetooth devices that were in range will be listed in the pull-down windows in the "Piconet Addresses" area of this window. Using the pull-down windows select both your "Intended BT Master" as well as your "Intended Slave" address for display in their appropriate windows. Step 4 After closing this window by pressing the "OK" button at the bottom of the window, once again depress the "REC" button found on BTTracer's toolbar. After approximately 20 seconds, the "SYNC"
light on the front of BTTracer will begin to flash, meaning that BTTracer has acquired all the information it needs to fully synchronize with the piconet about to be established. At this point, you should establish the piconet using the devices previously defined as master and slave. Step 5 When the piconet is established, the "Sync" light on the front of BTTracer will change from flashing to solid, indicating that BTTracer is fully synchronized to the piconet and is currently recording all traffic within that piconet. Note If the "sync" light on the front of BTTracer does not change from flashing to solid it means that BTTracer did not synchronize with the piconet when it was established. Sync & Record Sync and Record works just like "Page Sync and Record" except that BTTracer takes its sync data directly from the Master instead of the Slave devices. With Sync and Record, BTTracer conducts a General Inquiry to get hop frequency and clock information from the Master. BTTracer then waits to detect piconet traffic from the Master devices piconet. When the piconet is established, BTTracer is able to synchronize to the Master and begin recording. In contrast to "Page Sync and Record", "Page Sync and Record" can be run with or without an established piconet. Note This mode can only be used to find master devices that support Inquiry Scan. 70 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 To perform a "Sync and Record", follow the steps below:
Step 1 Turn on the Bluetooth devices under observation, and set up the master device so it is ready to respond to Inquiry scan. For a typical recording, ensure that the Master and Slave device(s) are not yet connected. Step 2 In the Modes tab under Recording Options, enter the Master Devices address. Step 3 Start BTTracer recording by pressing REC icon in the toolbar. Step 4 When the analyzer is able to Sync up to the Piconet Master Clock, the Green Sync LED in the BTTracer front panel will start blinking. Step 5 Establish connection between the Bluetooth devices under analysis. Step 6 When BTTracer senses Piconet traffic, the Green Sync light goes ON solid, recording starts and the status bar in the bottom of the analyzer screen shows activity. Recording may be stopped manually or when the recording buffer is filled. Note After the Sync light starts blinking, a connection between the Bluetooth devices should be established within one (1) minute. Passive Sync & Record Passive Sync and Record is used in situations where the Master device and slave devices do not support Inquiry Scan mode. When selected, BTTracer enters Inquiry Scan and Page Scan mode and waits for a page from the Master device. When the piconet Master pages BTTracer, BTTracer obtains the information necessary for synchronization and then attempts to synchronize to the piconet controlled by that Master.
"Passive Sync and Record" is designed to be used with established piconets or private device networks. Running "Passive Sync and Record" with Established Piconets For most situations, "Passive Sync and Record" will be run after a piconet has been established. The steps are as follows:
Step 1 Establish a connection between two or more Bluetooth devices. Step 2 Under General Recording Options, select "Passive Sync & Record."
Step 3 Under the Modes tab in Recording Options, enter the address for the 71 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 piconets master device. Step 4 Make up an address for BTTracer and enter it into the Page Target address in the Modes tab in Recording Options. Make sure you do not select an address for any other local device. Step 5 Press the REC button on the toolbar in BTTracer to start a recording session. Step 6 If necessary, have Master "discover" BTTracer through a General Inquiry. Step 7 From the Master device, initiate a page to BTTracers address. This action will enable BTTracer to synchronize to the piconet. However, the analyzer will not complete the page sequence from the Master. This will cause the Master to time out in this request. Step 8 At the end of this sequence, the green Sync light will go on solid, recording will begin and activity will be displayed on the status bar in the bottom of the analyzer screen. Running "Passive Sync and Record" with Private Device Piconets Because private device networks do not allow other devices to join the network, BTTracer needs to temporarily assume the identity of a slave in the network in order to join that network. To do this requires disabling the slave and beginning the operation without an established piconet. The following steps show the process. Step 1 Turn the Master device on and the slave device off. You need the slave device turned off so that BTTracer can take its place in the piconet. Step 2 Enter the slaves address into BTTracers "Page Target" field in the Modes tab in the Recording Options dialog box. Step 3 Run "Passive Sync and Record." The Master will then page the slaves address and BTTracer will be able to sync. Step 4 When BTTracer synchronizes to the Master, turn the slave back on. When the Master re-pages the address the slave will be admitted into the private network. Since BTTracer is passive in this mode, the slave and BTTracer do not conflict over the shared address. BTTracer is then able to record the traffic between the Master and 72 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 slave. Force Re-synchronization
"Force Re-Synchronization" forces BTTracer to re-synchronize at the beginning of each "Page Sync & Record," "Passive Sync & Record," or
"Sync & Record" operation. By default, "Force Re-Synchronization" is disabled (i.e., unchecked). Unchecking the "Force Re-Synchronization" checkbox tells BTTracer to use its existing data on Bluetooth devices, thereby bypassing the synchronization process and saving a few seconds from the beginning of the trace. If you know that BTTracers data is correct, you can uncheck this checkbox and cause BTTracer to try to use the existing data. If the data is incomplete or incorrect, however, BTTracer will automatically perform a refresh. To examine BTTracers Bluetooth data, open "BT Neighborhood" under the View menu. Follow Master/Slave Switch If enabled, this option allows BTTracer to follow a role switch between a Master and Slave. This capability allows BTTracer to keep track of changes in a devices role when it changes from one role to another. BTTracer is able to follow a role change by listening to the Slave devices Bluetooth clock and hop frequency as soon as it becomes a Master. Match Clock Rate Match Clock Rate is a useful option if the Master devices clock is inaccurate. Match Clock Rate causes BTTracer to do a General Inquiry to determine the Page Target's clock rate prior to synchronizing to the piconet. If unchecked, BTTracer will begin piconet synchronization without first doing a General Inquiry. This option only works with Page Sync and Record mode. Show Paging Traffic Show Paging Traffic causes BTTracer to capture paging traffic between the Master and Page Target devices. This option is used only with Page Sync and Record Mode. Piconet Addresses (MSB -> LSB)
Master Addr - Piconet Master Address for device under observation. Used for all Piconet recording modes.
Page Target - User selectable address for the BTTracer Analyzer. Used for Passive Sync & Record and Page Sync &
73 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Record.
DIAC LAP- Device Inquiry Access Code. Used for Device Inquiry.
Swap - The "swap" button swaps the addresses between the Master Addr and Page Target text boxes. This button will allow addresses to be swapped even if the boxes are grayed out. Note GIAC - General Inquiry Access Code is hard-coded in the analyzer and does not require user selection. Other Parameters Correlation Value (33-64) This value tells BTTracer how many bits in the sync word of each received packet must be matched in order for BTTracer to consider the packet valid and start recording. Inquiry Timeout (0-80 secs) Default value is 20 seconds. This value specifies how long BTTracer should perform the Inquiry process for the General (unlimited) and Dedicated (limited) recording modes. After the specified time has elapsed, BTTracer will illuminate the trigger light on the front of the analyzer. Loss of Sync Timeout (1-16 secs) This value specifies the amount of time that BTTracer will wait for piconet traffic before determining that synchronization has been lost. Sync Window The Sync Window slide bar controls the amount of time that BTTracer should wait between receiving an Inquiry Response (which will cause the Sync LED to blink) and detecting Master-Slave piconet traffic (which will cause the Sync LED to turn solid.) A "Narrow" setting means that the wait time will be minimal, a "Wide"
setting means it will be "maximal." The default is "Narrow" and this is suitable for most recordings. However, if significant drift occurs between BTTracers clock and that of the Master, BTTracer may not be able to sync properly to the piconet. Under these conditions, you should move the slide bar towards the "Wide" Setting. The slide bar has five discrete settings. 74 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 After sync is established, BTTracer will remain in sync as long as there is piconet traffic. Debug/Test Enable CATC debug file Checking this box enables the creation of a file that can be used by CATC Support to aid in debugging. This option should always be disabled unless you are requested to enable it by CATC personnel. 7.3 Recording Options - Events If you have selected Event Trigger mode under the General tab in the Recording Options screen, you may now select specific Bluetooth events using the Events tab on the Recording Option Screen. You can also use the Actions tab to define specific event sequences that will trigger BTTracer to record a Bluetooth session. In addition, the Events and Actions screens allow you to specify which packets you want to include or exclude from the recording. Events Options
Click the Events tab on the Recording Options screen. You see the Event Groups window:
75 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The Event triggering and filtering options allow you to set event conditions for errors and/or a variety of packet characteristics. Clicking a check box causes further options to display in the right side of the window. Additional Timeslot Filtering By default, BTTracer records frequency hop and timestamp information for all time slots in the Piconet under analysis, regardless of whether the time slot contained a Bluetooth packet. This means that in instances where there is little piconet traffic, BTTracer will display row after row of empty packets -- each representing an empty time slot. Through the use of timeslot filtering, these empty packets can be filtered out. Filtering out this information has the benefit of freeing memory so that more traffic can be recorded. Filter Empty Slots If "Filter Empty Slots" is checked, BTTracer will exclude all empty time slots from a recording except for those that lie immediately in front of Bluetooth communications packets. These remaining empty packets are preserved to give timestamp and frequency hop reference data to the packets that follow. Filter Slots on Packet Filter If filters are used to exclude FHS, DM1 or other packets, BTTracer will exclude these packets from a trace and mark their locations with empty packets. The result can be rows and rows of empty packets. The option
"Filter Empty Slots" will not exclude these empty slots because they lie immediately in front of Bluetooth communications packets - even though those packets were not recorded. To eliminate these empty packets, select
"Filter Slots on Packet Filter."
Packet Headers Clicking "Packet Headers" opens three sets of check boxes and menus on the right that represent fields within packet headers: Packet Type, Active Member Address, Flow Control, Acknowledgment, and Sequence Number. 76 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
Select Packet Headers under Event Groups. You see the Packet Headers window:
Packet Type The Packet Type drop down menu lets you select the following packet types for filtering or triggering: NULL, POLL, FHS, DM1, DH1, HV1, HV2, HV3, DV, AUX1, DM3, DH3, 1100, 1101, DM5, or DH5. Select Dont Care if you want BTTracer to ignore this field. AM_ADDR
(Active Member Address) The AM_ADDR is a three bit slave address. To select packets from a particular slave device for filtering or triggering, enter an address into the AM_ADDR text box. You can target up to three devices using the three text boxes. SEQN, ARQN, and Flow Control Bits To set event conditions on SEQN, ARQN, and Flow control, uncheck
"Don't Care." Unchecking "Don't Care" sets the event condition to SEQN=0 AND ARQN=0 AND Flow=0. This action also puts a checkmark in the box marked "Packet Headers." A checkmark next to SEQN, ARQN, 77 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 or Flow changes the value of this field from zero to one. For example, if SEQN is checked, the event condition becomes "SEQN=1 AND ARQN=0 AND Flow=0. To cause BTTracer to ignore this set of check boxes, choose "don't care."
Payload Headers Clicking "Payload Headers" causes a series of options to display on the right for setting conditions on payload headers. You will see two sets of options
- one for single slot packets such as DM1 packets and a second for multi-slot packets such as DM3 packets. Within each set is a menu for the Logical Channel and sub-options for Flow Control, and Payload length. These latter two options allow you to modify searches based on the Logical Channel. An example would be "Trigger on a start L2CAP message whose flow control bit is 1 and whose data field length is less than 20."
Select Payload Headers under Event Groups. You see the Payload Headers window L_CH (Logical Channel) The "L_CH" drop down menu presents five options for setting conditions on the Logical Channel:
Dont care
00 Undefined 78 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
01 L2CAP continue
10 L2CAP start
11 LMP message Select "Dont care" if you do not want to set conditions on Logical Channel. Flow Three "radio buttons" are presented for setting conditions based on Flow control:
0
1
Dont care Flow works in conjunction with the Logical Channel (L_CH) menu - you select an option from the L_CH menu and then select an option under Flow. Select "Dont care" if you do not want to set conditions on Flow control. Length (in bytes) Using both the drop down menu and the text box, you can set conditions based on data field length. The maximum length for a single slot packet is 29 bytes. The maximum length for multi-slot packets is 339 bytes. The drop-down menu gives you options for selecting operators such as "greater than" and "equal to." The text box to the right of the drop-down menu lets you enter values. The Length option works in conjunction with the Logical Channel (L_CH) menu - you first select an option from the L_CH menu and then select an option under Length. Data Patterns Clicking "Data Patterns" causes a text box to appear for entering patterns to be matched in the raw payload data. Patterns of up to eight hexidecimal bytes can be entered. Errors Clicking "Errors" causes check boxes to appear for setting conditions for triggering or filtering based on packet/signaling/protocol errors. You can select one or a combination of errors. 79 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
Select Errors under Event Groups. You see the Errors window:
Use any combination of the listed packet/signaling/protocol errors as a Trigger. CRC Error A CRC error in the packet data payload of the previous Bluetooth data packet. HEC Error An HEC (header error check) error in the packet header for the previous Bluetooth data packet. FEC Error An uncorrectable FEC (Forward Error Correction) error in the packet header for the previous Bluetooth data packet. Threshold Exceeded Indicates that the number of single-bit FEC errors detected since the current recording started has exceeded the specified value. Invalid Packet Type An invalid value was detected in the 'packet type' field of the packet header for the previous Bluetooth data packet. 80 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Header Length Error Indicates that a received Bluetooth data packet was terminated before all bits of the packet header were received. Payload Length Error Indicates that the payload of a received Bluetooth data packet was either longer than expected, or that a Bluetooth data packet terminated before the expected end of the payload data. Sync Loss When set, indicates that a loss of piconet synchronization occurred during the frequency slot prior to this slot. External Input Signals Clicking "External Input Signals" causes two check boxes to appear for setting conditions based on breakout board input signals. The names of the two check boxes are the same ones you will find on the break out board:
Trigger Input [TRIG IN]
General Purpose Input [G.P. IN]
81 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 7.4 Recording Options - Actions The Actions screen allows you to specify the type of action that BTTracer should perform when it encounters the events specified in the Events window. Actions Window Layout The Actions window divides into three sections: a left, a center, and a right section. The left section displays Event buttons such as Header buttons and Error buttons. The number of Event buttons displayed depends on the number of Events you selected in the Events window. If you selected no Events, no Event buttons will display. If all Events were selected, eight Event buttons will display. The center section displays two Counter buttons marked Count1 and Count2. These buttons are used for counting events and are permanent features of this section. 82 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 This center section can also hold Event buttons such as Errors and Payload Hdr1. Event buttons in this section are used to create triggers based on a sequence of Events. Event Sequencing is explained later in the chapter. The right section has three permanent buttons for setting actions. These buttons are Trigger, Filter Out/In, and Restart. These buttons allow you to set actions such as triggering or filtering. Arrows connect Event, Counting, and Action buttons. Arrows represent the current associations between actions and events. As will be described further on, these associations can be easily changed with the mouse. Action Buttons - Their Functions The Action buttons in the right side of the window provide the means of setting triggers, filters, and restarts. To set an action, you simply drag your mouse from an Event to an Action. As described further on, this movement will link the two via an arrow. Trigger The Trigger button enables event triggering. Filter In/Out The Filter In/Out button allows events to be filtered in or out of the recording. Restart The Restart button causes the two counters Count1 and Count2 to be reset to zero. Counting Buttons - Their Functions The center section of the Actions window has two buttons for counting events called Count1 and Count2. Below these buttons, you can add Event buttons to create Event Sequencing. Count1, Count2 Count1 and Count2 are counters for specifying how many events must occur before an event can cause a trigger. Counters allow conditions to be made such as "Trigger after the 21st Poll packet" (see screenshot below). 83 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The Actions window showing a condition based on a Poll packet and a counter. This condition reads "Trigger after the 21st Poll packet."
Connecting Events to Counters To connect an event to a counter, click an Event button, then click one of the two counter buttons. An arrow will appear that will join the Event to the Counter and then to a trigger. This latter connection between the Counter button and the Trigger button occurs because counters always work in association with triggers. Counters act as assistants to triggers. Setting Multiple Conditions with Counters You can create multiple event conditions by linking a counter to multiple events or by linking two counters to two or more events. Linking Multiple Events to One Counter - When two or more Events are connected to a counter, it creates a condition that reads "Trigger when the counter value is reached by any combination of the specified events."
84 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The following example reads "Trigger after any combination of 5 Poll packets and FHS packets have occurred."
Linking Two Events to Two or More Counters - If an Event is linked to Count1 and a second event is linked to Count2, it creates an "or" statement. This statement reads "Trigger when Count1 OR Count2 has reached their specified values."
This example reads "Trigger when Count1 has counted 5 Poll packets or Count2 has counted 10 FHS packets."
Blue Dot Menus Count1, Count2 and a few other buttons in the Actions window have blue dots in their top left-hand corners that indicate the presence of context-sensitive menus. These menus let you set the buttons values and/or operations. Click the left mouse button on a dot to open the menu. 85 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Counters Blue Dot Menu The Count1 and Count2 blue dot menus allow the value of their counters to be changed. The value you specify here tells BTTracer how many instances of an event must take place before a trigger occurs. The counter can be set between 1 and 65,535. To set a Counter, Step 1 Click on the blue dot in the upper left corner of the Count button. You see the Change Counter Value menu:
Step 2 Click Change Counter Value You see the Input Counter Value menu Step 3 Enter an input value to tell the Analyzer how many times this event must occur before triggering the end of a recording Step 4 Click OK. You may connect as many Event buttons to a counter as you like. However, the Counter does not treat each event as a discrete specification but treats them all as one event. 86 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 As an example, look at the specifications set in the following screen:
Counter 1 has been set to trigger four events after 15 occurrences. But the Counter does not count 15 occurrences for EACH event. It counts ALL events as they happen to occur until it reaches a total of 15 and then triggers. Filter Out/In Blue Dot Menu The Filter Out/In button toggles between "Filter Out" and "Filter In".
Filter In records ONLY those packets related to the specified event.
Filter Out records all packets EXCEPT those related to the specified event. To filter an event in or out of a recording, Step 1 Click the blue dot on Filter Out. (Note: the button may say Filter In depending on the last action specified.) You see the Filter Out/In menu:
Use this menu to toggle the selection between Filter Out and Filter In. Step 2 Select "Filter In". The button changes to read "Filter In". 87 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Blue Dot Menus for the Event Buttons The Errors button and the first Headers button (marked "Hdr1") have the same Blue Dot menus. These menus allow BTTracer to trigger external output. To enable or disable external trigger output, Step 1 Click the Blue Dot on an Event button such as Hdr1 or Errors. A menu similar to the one below will open. Your menu may say
"Disable" instead of "Enable."
Step 2 Select "Enable External Trigger Output" (or "Disable External Trigger Output" if that is the choice presented.) If you have chosen "Enable External Trigger Output", a small arrow will appear on the right side of the button. This arrow indicates that a condition has been set for creating an external output signal. Choosing "Disable External Trigger" will cause the arrow to disappear. Enabling High Pulse, Low Pulse or Pulse Toggle Signal Outputs Once External Trigger Output has been enabled, you can configure the output signal to one of three formats:
Pulse High - This is the default format. The Pulse High setting causes the Analyzer to transmit a 5 volt, 16.66 nanosecond signal. Pulse Low - This format causes the Analyzer to transmit a -5 volt, 16.66 nanosecond signal. Toggle - This format causes the Analyzer to transmit a signal that will toggle with each trigger event between a continuous 5 volt signal and a continuous -5 volt signal. 88 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 To configure the output signal, Step 1 Click the blue dot on an Event button that has a small arrow attached to it like the one shown above. A Blue Dot Menu will open. "External Trigger Form" should be a choice available. If it is not, you will need to choose "Enable External Trigger" and then reopen the menu. Step 2 Choose "External Trigger Form"
A menu will appear with choices for "Pulse Low", "Pulse High", and
"Toggle". Step 3 Choose an option not currently selected. The menu closes. Step 4 Reopen the menu. Note that your new selection is now checked. Elastic Arrow Elastic arrows allow you to associate Events, Counters, and Actions. To make an association, Step 1 Click the left mouse button on an Event button such as Hdr1 or Errors. 89 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The elastic arrow appears. Step 2 Drag the arrow to the desired Action button. Step 3 With the pointer over an Actions button, click again the left mouse button again. The arrow is replaced with a black line connecting the Event button to the Action button. Event Sequencing If you drag your mouse from one event button to another, you will create a compound condition known as an Event Sequence. An event sequence is a condition that says "Trigger when you see the following sequence of packets." The example below may help to clarify. This example means "Trigger when you see a packet with an Null Header followed by a packet with a FHS Header."
90 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 To create an event sequence, perform the following steps:
Step 1 Select two events from the Events window Step 2 Open the Actions window and click on one of the two Event buttons. An elastic arrow should appear. Step 3 Click on the other event. The arrow should connect to the second button and the second button should instantly change locations to the center section of the window. 7.5 Saving Recording Options To complete your Recording Options settings, use the features at the bottom of the Recording Options screen. These features remain the same no matter which of the three Recording Options screens you are working in.
Click Save to save the currently specified Recording Options for use in future recording sessions. Any file name can be specified, 91 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 though use of the .rec is recommended; if no extension is specified, .rec is added by default.
Click Load to load a previously saved *.rec file, thus restoring a previous set of Recording Options.
The Save as Default function is equivalent to the Save function, specifying the file name default.rec. Whenever you start up the Analyzer, it automatically loads the default.rec file if one exists.
Click OK to apply any changes and close this dialog box.
Click Cancel to cancel any immediate changes you have made and exit the Recording Options menu. 7.6 Recording Bluetooth Traffic To start recording Bluetooth traffic once the appropriate Recording Options have been set, Step 1 Select Start under Record on the Menu Bar OR Click on the Tool Bar. Your recording session can continue until it has finished naturally or you may need to stop manually by clicking how you set the Recording Options. on the Tool Bar, depending on To manually stop recording, Step 2 Select Stop under Record on the Menu Bar OR Click on the Tool Bar. Note The manual Stop Recording feature is primarily of use when recording low-volume traffic, which can take a long time to fill the recording buffer. When the recording session is finished, the bus traffic is saved to the hard drive as a file named data.blt or whatever name you assign as the default filename. To save a current recording for future reference, Step 3 Select Save As under File on the Menu Bar. OR 92 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Click on the Tool Bar. You see the standard Save As screen. Step 4 Give the recording a unique name and save it to the appropriate directory. 93 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 94 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 8. Display Options Use the Display Options menu to specify the way CATC Trace information is displayed. To open the Display Options menu,
Select Display Options under Setup on the Menu Bar OR
Click on the Tool Bar You see the Display Options window:
The Display Options window always opens with the screen for the General tab displayed. 8.1 General Display Options Use the General Display Options to specify the basic appearance of a Trace View.
Zoom Level: Adjustable in discrete increments from 10% to 200% percent.
Enable Tool Tips: Select to enable tool tips with explanation text to pop up when you position your cursor over various fields in the Trace View. 95 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
Wrap: Inhibits carriage returns in packets when they exceed the width of the window.
Trace Viewing Level: Enables different levels of transaction to be displayed.
Display Configuration Name: A Comment field associated with the *.opt file containing the current Display Options values. You can also create and store your unique Display Options for future use.
Fonts: Allows field fonts and data fonts to be changed. The fonts can be italisized and/or bolded by pressing the I and/or B buttons. Trace Viewing Level Trace Viewing Level allows BTTracer to display ten levels of transaction:
Packet Packet is the default selection.
LMP Messages
L2CAP Messages
STP Messages
STP Protocol
TCS Messages
TCS Protocol
RFCOMM Protocol
OBEX Protocol
AT Commands Protocol
HDLC Frames
PPP
BNEP Changing the Trace View Level To change the Trace Viewing Level, use the decode buttons on the toolbar or select a checkbox in the Display Options dialog box. For further details on these viewing levels, see the Chapter 7: Decoding Higher Protocols. Creating New Display Options Files To create a new Display Options file, Step 1 Enter a comment for the new file in the Display Configuration Name field. 96 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Click Save... You see the Save As window. Step 3 Specify a filename (*.opt). Step 4 Click Save. 8.2 Color Display Options
Click the Colors tab on the Display Options screen. You see the Colors screen:
Use this menu to customize the colors associated with each field in the Trace View. You can experiment with this option to achieve the color combination best suited to a particular graphic system. A brighter color might be appropriate for a specific field that should stand out in the display (e.g. the Packet Types). Note The colors of the following packet types cannot be changed: Invalid Data (packet error) field (red) and Softbit Errors (yellow.) Two color fields are provided for packet number displays to differentiate between pre-Trigger traffic and post-Trigger traffic. 97 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
The packet that causes the Trigger and all the packets before it are colored with the - color.
The packet that follows a Trigger is colored with the + color.
All packets are colored with a + color when there is no Trigger. Use the color buttons labeled + and - under the Packet # section of the Colors screen to select a Trigger color. To select or change a color,
Click the appropriate color button. You see the color palette:
Use this palette to choose the desired color for the Packet Types, Miscellaneous, Integrity, Handshake, Packet #, Access Codes, Data, Idle and Timestamp. 98 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 8.3 Formats Display Options
Click the Formats tab on the Display Options screen. You see the Formats window:
Select a number format corresponding to the column labels along the top of the screen for each number field that labels the rows along the left of the screen. The number format changes in the respective location in the packet view window. You can also select the bit ordering to be displayed. Not every number format is available for every number field. 99 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 8.4 Hiding
Click the Hiding tab on the Display Options screen. You see the Hiding window:
Use the Hiding window to hide various fields, packets, messages, and protocols from the Trace View screen. You can modify these settings at will to display a specific area of a Trace. Hiding Fields The "Hide Fields" checkboxes allow individual fields to be hidden within a trace. Click the checkbox(es) of your choice to hide one or more fields. Hiding Packets, Messages, and Protocols The "Hide Packets and Transactions" box contains two grids of checkboxes for hiding whole packets, messages, protocols, and traffic from individual devices. The grids are labeled "Devices to Hide" and "Levels to Hide". Devices to Hide The "Devices to Hide" grid lets you hide traffic according to device address. The grid devides into columns which represent different devices. 100 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Columns labeled "0" through "7" and "All" represent the Active Member Address of a device. By checking one of the boxes in a column, you hide the traffic of the selected device (or traffic from all devices if you have selected All.) The row in which you place your checkmark determines whether you are hiding traffic going to or from a device.
Master - Hide traffic from a Master to selected Slaves
Slave - Hide traffic from selected Slaves to the Master
Both - Hide all traffic between the Master and selected Slave Example: to hide all traffic from a Master to a Slave device with an address of six, click the checkbox under column 6 on the row marked Master. Levels to Hide The "Levels to Hide" grid divides into rows which represent the different packet, message, and protocol levels. Clicking a checkbox will cause BTTracer to hide all traffic of a selected level. Hiding Packets At the bottom of the Hiding tab of the Display Options window, check boxes are available for hiding HOPs, POLLs, NULLs, and other kinds of traffic. 8.5 Saving Display Options To complete your Display Options settings, use the features at the bottom of the Display Options screen. These features remain the same no matter which of the four Display Options screens you are working in.
Click Save to save the currently specified Display Options for use in future sessions. Any file name can be specified, but you must use the .opt extension. If no extension is specified, .opt is added by default.
Click Load to load a previously saved *.opt file, thus restoring a previous set of Display Options. 101 CATC BTTracer Protocol Analyzer Users Manual Version 1.0
The Save as Default function is equivalent to the Save function, specifying the file name default.opt. Whenever you start up the analyzer, it automatically loads the default.opt file if one exists.
Click OK to apply any changes you have made to Display Options and close this dialog box.
Click Cancel to cancel any immediate changes you have made and exit the Display Options menu.
Click Apply to apply your changes. 102 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 9. Reading a CATC Trace 9.1 Trace View Features
The BTTracer packet view display makes extensive use of color and graphics to fully document the captured traffic.
Packets are shown on separate rows, with their individual fields both labeled and color coded.
Packets are numbered (sequentially, as recorded), time-stamped, and highlighted to show the device status (master or slave).
Display formats can be named and saved for later use.
Pop-up Tool Tips annotate packet fields with detailed information about their contents.
Data fields can be collapsed to occupy minimal space in the display (which can in turn be zoomed in and out to optimize screen utilization).
The display software can operate independent of the hardware and so can function as a stand-alone Trace Viewer that may be freely distributed. 9.2 Interpreting the Displayed Information The following table describes the abbreviations used in the Merlin display. Packet #0 is described from left to right:
Packet:#
T/M, T/S Freq Pre Packet/Event Number M =Master Device Transmitting S = Slave Device Transmitting Current Hop Frequency (in MHz) Preamble of the Sync word 103 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Packet:#
Packet/Event Number CAC Trail Addr DM1 Flow Arqn Seqn HEC L_CH L2FL Len TID Opcode CRC Ackd Idle Time Stamp Channel Access Code Access Code Trailer of the Sync word Active Member Address DM1 Packet Type ACL Link Flow Control Acknowledgment Indication Flag Sequential Numbering Header Error Correction Code LMP Message L2CAP Flow Control Flag Message Length in Bytes including Opcode LMP Transition initiated by Master LMP-host_connection_req Cyclic Redundancy Check Packet Acknowledgment based on subsequent packets ARQN with same AM_ADDR Idle Time in nanoseconds Decimal in Seconds.Milliseconds.Microseconds*10 This is the analyzer internal clock as a reference with resolution of 100 ns. 9.3 Tooltips You can get additional information about each field in a trace by holding your mouse pointer over a field. A tooltip will appear with details about the field. 9.4 Set Marker Note The Set Marker works in conjunction with the Go to Marker feature. You can define a unique Marker for each packet. To place a marker on a packet, Step 1 Left-click on Packet # for the packet you wish to mark. 104 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 You see the Packet menu:
Step 2 Select Set Marker. You see the Edit Marker Comment window where you can enter a unique comment about this packet.:
Step 3 Enter your comment. Step 4 Click OK. A marked packet is indicated by a vertical red bar along the left edge of the packet # block:
9.5 Edit or Clear Marker To clear or edit the comments associated with a packet marker, Step 1 Left-click on Packet # for the chosen packet. You see the Packet menu:
To edit the Marker Comment, 105 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Select Edit marker. You see the Edit marker comment window:
Step 3 Edit the comment as desired. Step 4 Click OK. To clear a Marker, Step 5 Click Clear marker. The vertical red Marker bar disappears. 9.6 Expanded and Collapsed Data Formats The data field can be expanded to display greater detail or collapsed to a compact view. The Expand/Collapse Data feature operates as a toggle. There are three ways to toggle between the two views. Double-Clicking You can expand or collapse a Data field by double-clicking anywhere in the Data field of a packet. Left-clicking a Field Arrow Many fields have small arrows in the top left corner. If you left-click this arrow, the field will toggle back and forth between collapsed and expanded views. Left-facing field arrow will collapse the field Expanded Data Right-facing arrow will expand data Collapsed data If you click and hold down the left mouse button on one of these arrows, you can collapse or expand the field for ALL packets, messages or protocols. Using the Shortcut Menu If you left-click on a Data field, a menu will open for expanding or collapsing data fields. Step 1 Left-click on Data in the Data packet you want to expand or collapse. 106 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 If your Data Trace View is currently expanded, you see the Collapse Data menu:
If your Data Trace View is currently collapsed, you see the Expand Data menu:
Note that you can choose to expand or collapse
Only the Data in the selected Data packet OR
All Data Fields in the Trace View. Step 2 Select the desired Expand Data or Collapse Data menu item. The Trace View is repositioned with the selected packet(s) adjusted in the format you have specified. 9.7 Hide Frequency Hops You can hide Frequency Hops (Hops) from a trace by pressing the Hide Hops button on the Tool Bar:
107 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 From the Tool Bar
Click to hide all Hop packets. 9.8 Hide Nulls and Polls You can hide Nulls and Polls from a trace by pressing the Hide Nulls and Polls button on the Tool Bar. From the Tool Bar
Click to hide all Nulls and Polls. 9.9 Menus in Clicked Fields You can display the following menu when you click in a field in a trace. 9.10 Hide Unassociated Traffic You can hide all traffic that is not associated with the current decode level by pressing the Hide Unassociated Traffic button on the Tool Bar. From the Tool Bar
First, click one or more decode buttons such as the View L2CAP Messages
. This button will cause BTTracer to decode the trace and display selected level of decode.
Next, click to hide all unassociated traffic. The Hide Unassociated Traffic button will cause BTTracer to hide all traffic except for the selected decode messages or protocols. In the example above, all packets would be hidden and only L2CAP messages would display. 108 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 10. Decoding Higher Protocols 10.1 Introduction BTTracer can decode LMP and L2CAP messages, and RFCOMM, SDP, TCS, HDLC, PPP, and OBEX protocols. The default is packet level decoding, which means that baseband packets will be displayed when you first view a trace. If these packets are carrying LMP, L2CAP or higher protocols, the protocols will display as undecoded fields such as the L2CAP packet below. Undecoded L2CAP fields By issuing a decode command, BTTracer can decode these LMP and higher fields and display the data in summary statements called LMP/L2CAP Messages, Protocols Messages, and Protocol Transactions. 10.2 LMP and L2CAP Messages LMP and L2CAP Messages are lines in a trace that summarize LMP and L2CAP actions such as an LMP connection request. LMP and L2CAP Messages summarize the type of action, the number of packets involved in 109 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 the action, and the device performing the action. If the message is carrying higher protocol data such as RFCOMM, TCS, OBEX or SDP data, the message displays this data in an undecoded format that can be decoded later. Undecoded higher protocol data 10.3 Decoding and Viewing Higher Protocol Data Higher protocol data can be decoded two ways: by clicking a decode button on the toolbar or by selecting a decode command from a pull down menu. Decoding Via the Decoding Toolbar The Decoding Toolbar has ten buttons for decoding packets, messages, and protocols:
Pkt (Display Packets)
LMP (Display LMP Messages)
L2CAP (Display L2CAP Messages)
SDP Msg (Display SDP Protocol Messages)
SDP Tra (Display SDP Transactions)
TCS (Display TCS Protocol messages)
RFCOMM (Display
OBEX (Display OBEX Protocol)
AT (Display AT Commands Protocol)
HDLC (Display HDLC Protocol)
PPP (Display Point to Point Protocol)
BNEP (Display Bluetooth Network Encapsulation Protocol)
HID (Display HID Protocol) For example, to display LMP messages, click
. Note Once a decode has been performed, it will probably be necessary to scroll through the display to find the decoded messages or protocols. You can shorten your search by first clicking the Hide Unassociated Traffic button
. 110 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Decoding Via the Display Options Dialog Box The Display Options dialog box has three options for issuing decode commands. To issue a command, Step 1 From the menu bar, select Setup>Decoding Options Step 2 Select the option for the desired level of decoding. Step 3 Click OK or Apply. 111 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 10.4 Tooltips Additional information about fields can be attained by positioning your mouse pointer over a field of interest. A tooltip will appear that will provide details about the field. In some cases, there can be a considerable amount of information available. 10.5 Viewing Packets in LMP and L2CAP Messages LMP and L2CAP Messages can be "opened" to reveal their constituent packets by double-clicking the first cell in of the message or clicking once on the small arrow on that same cell. The packets will then display below the message. The following screenshot shows an example of a message and its packets. Message Packets making up the message 10.6 Types of LMP and L2CAP Messages If you scroll through a trace, you will see three kinds of message:
LMP Signalling Message L2CAP signalling Message L2CAP Data Transfer Message 112 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Each message has the same basic message header but differs in its payload. LMP Signalling Message Header Payload L2CAP Signalling Message Header Payload L2CAP Data Transfer Message Header Payload LMP and L2CAP Signalling messages have payloads of commands for establishing LMP and L2CAP channels. L2CAP Data-Transfer messages have a payload that may include RFCOMM, SDP, or TCS data. In order to view higher protocol data, you will need to decode the messages (shown in the next section). The decoded data will appear as new lines in the trace called "Protocol Messages."
10.7 Viewing L2CAP Channel Connections Once L2CAP messages have been decoded and displayed, you can check or change their L2CAP channel connections by opening the L2CAP Decoding Connections dialog box. To view or change an L2CAP channel connection, Step 1 Select from the menu bar View>Decoding Assignments 113 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The following dialog box will open. Step 2 Click on a channel assignment and then look at the Connect and Disconnect buttons on the far right of the dialog box. If the Connect and Disconnect buttons are grayed-out, it means that BTTracer made the channel assignments using data in the trace. You can verify that BTTracer performed the assignments by looking at the text in the "Slave Channel" box in the lower left corner of the dialog box. If you see "Connection Recorded" it means that BTTracer performed the channel assignments. If BTTracer was not able to make these channel assignments, then the Connect and Disconnect buttons on the right side of the dialog box will be active. You can then assign and edit channel connections. Step 3 Open the drop-down menu labeled AM_Addr (Active Member Address). If possible, select an address other than the currently displayed address. The connections for the new device should now display. 10.8 Viewing Protocol Messages and Transactions or By pressing a button such as the higher level protocol data contained within L2CAP messages and display them as packet-like rows called Protocol Messages. Protocol Messages have headers marked "protocol" and fields that vary in appearance and content depending on the type of protocol.
, you can cause BTTracer to decode Some Protocol Messages can be grouped into a higher level entity called a Protocol Transaction. A Protocol Transaction is a row in a trace that summarizes the higher level protocol data that is transmitted between a Master and Slave device when one sends a request and the other sends back 114 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 a response. For example, if you press requests and responses between a Master and Slave device summarize their data.
, BTTracer will locate SDP Viewing L2CAP Messages in Protocol Messages If the protocol heading is double-clicked, the L2CAP data-transfer messages that make up the protocol will display below the protocol. You can also expand the protocol by left-clicking the small downward pointing arrow on the protocol header. How to Decode Decoding Protocol messages is the same process as decoding LMP and L2CAP messages. Using the Toolbar - To decode using the Toolbar, press one of the protocol decode buttons such as:
. Using the Menu - To decode using the menu, select:
Setup>Display Options Then select one of the decode checkboxes. Once a decode command has been issued, BTTracer will create Protocol Messages in the trace. You will probably have to hide hops, polls, and null packets and then scroll through the trace in order to find Protocol messages. Expanding Protocol Messages Protocol messages can be expanded to reveal their constituent packets using any of the following methods:
Left-click the small downward pointing arrow in the message/protocol header
Double-click a message/protocol header
Left-click the message/protocol header and choose "Expand Transaction"
from the short-cut menu 115 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 10.9 Changing Protocol Assignments If a sequence of messages is assigned the wrong protocol, errors will display. To change or remove a protocol assignment, you will need to access the Assignment menu and issue an Add Assignment command. Step 1 Click to display L2CAP messages. Note You need to view L2CAP Messages in order to have access to the "A" field that permits reassigning protocols. Step 2 Scroll through the trace until you have located an L2CAP message with a field marked "A."
Step 3 Left-click the field marked "A."
Left-click An Assignment menu will open for assigning, re-assigning, or un-assigning protocols to messages. This menu is context-sensitive and will vary in content depending on the protocols in the trace. The Assignment Menu Current assignment Select another assignment to change assignment from this point downward through the trace Will let one or all protocol assignments be removed Step 4 From the menu, select one of the "Add Assignment" options not already selected. At this point, the protocol assignment will change to your selection. Using the Decoding Assignments Dialog Box You can get a complete list of all protocol assignments by opening the Decoding Assignments dialog box. This dialog box will tell you which protocol assignments were made by BTTracer and which are user-assigned. User-assigned protocols can be reassigned if need be using this dialog box. 116 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 To open the Decoding Assignments dialog box and reassign a protocol, Step 1 Select from the menu View>Decoding assignments The Decoding Assignments dialog box will open. A status message in the bottom left corner of the dialog box will indicate who assigned the protocol. Step 2 Click on one of the displayed assignments. If the protocol was assigned by BTTracer, the Assign buttons on the right will be grayed out and unavailable. If you want to change these assignments, you will have to use the pop-up menus described in the previous section. If a protocol has been manually assigned by a user, the Assign buttons will become active and allow you to make a change in assignment. Step 3 If possible, click the appropriate Assign button. Removing User-Assigned Protocol Assignments As you practice assigning and reassigning protocols, you will find that one of the more useful commands is "Remove All User Assignments." This command allows you to undo all of your assignments. To remove some or all user-assigned protocol assignments, Step 1 Double-click any Protocol Message header to open view L2CAP messages. Step 2 Locate a message with a field marked "A."
Step 3 Left-click on the "A" field to open the Assignment menu. Step 4 Select "Remove All User assignments" or "Remove this assignment."
117 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Manually Assigning Protocols If a recording does not capture the beginning of a dialog between a Master and Slave devices, BTTracer may not have the L2CAP messages it needs to determine the correct protocol assignments. In this case, L2CAP messages will display an "N" in the Assignment field that means "Not Assigned."
An L2CAP message without a protocol assignment for the higher protocol data. N=Protocol not assigned If you know what the protocol assignment should be for the missing assignments, you can manually add them by right-clicking your mouse over the A field shown above and selecting from the pop-up Assignment menu shown on the previous page. Other Assignments: OBEX Client/Server Status OBEX messages carry a status that indicates whether the transmitting device is an OBEX client or OBEX server. To view an OBEX messages client/server status, Step 1 Open an OBEX trace file such as the sample file
"OBEXsample.blt" in C:\Program files\CATC\BTTracer. Step 2 Press traffic.
, and to hide Hops, NAKs, and unassociated Step 3 Press to decode OBEX. Step 4 Left-click your mouse over the field marked Type. A pop-up menu will appear indicating whether the message was produced by an OBEX client or server. If the menu items appear Left-click over the Type field to open the OBEX Client/Server Assign menu. grayed-out (as they do in this example) it means that BTTracer assigned the client or server status based on data it found in the trace. If the menu items appear in black, it means that the user assigned the status and is therefore free to change the assignment. 118 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Changing an OBEX Client or Server Status If the beginning sequence of traffic is not recorded in a trace, the client/server status of the transmitting devices will not be preserved in the trace. In this case, the OBEX Client/Server pop-up menu will become active and you will be able to change the assignment. Decoding BNEP BNEP (Bluetooth Network Encapsulation Protocol) is a protocol that allows devices to encapsulate network protocols such as IP. Since BNEP can carry different types of network protocols, you need to tell BTTracer what protocol the BNEP is going to be carrying. You do this via a script file called bnep.dec that is read during the initialization of the BTTracer software. This file tells BTTracer how to decode BNEP fields. Once read, BNEP can be correctly decoded by pressing the button on the toolbar. If the decode file is not read at initialization, BTTracer will display the data in an undecoded format. For more information on BNEP decoding, see a supplemental document on BNEP in the support directory on the CATC web site:
http://www.catc.com/products/support/sup_BTTracerbluetooth.html Decoding HID HID (Human Interface Device) is a profile associated with traffic from devices such as a mouse or a keyboard. To decode HID traffic, you will need to tell BTTracer what types of HID traffic it will be recording. You do this by editing a script file called hid.dec. BTTracer reads this file during the initialization of the BTTracer software. This file tells BTTracer how to decode the HID fields. Once read, HID can be correctly decoded by pressing the button. If the decode file is not read at initialization, BTTracer will display the data in an undecoded format. BTTracer has the capability to decode HID (Human Interface Device profile) based on version 0.90b of the specifications. 119 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 120 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 11. Other Features 11.1 Search The Search feature provides several options for searching through recorded traffic, allowing you to find specific packets based on triggering status, packet number, marking, or content. To view the Search options,
Click Search in the Menu bar. You see the Search drop-down menu:
Go to Trigger To display a triggering event, select Go to Trigger under Search on the Menu bar. The Trace Viewer display will reposition the trace to show the triggering event at the top of the screen. Go to Packet/Message/Protocol To display a specific packet, Message or Protocol Step 1 Select Go to Packet/Message/Protocol under Search on the Menu Bar. You see the Go to Packet/Message/Protocol window:
121 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Enter the number of the packet, message or protocol you want to display. Step 3 Click OK. The Trace View repositions to show the packet at the top of your screen. Go to Marker To instruct the analyzer to display a marked packet, Step 1 Select Go to Marker under Search on the Menu Bar. You see a drop-down menu listing the marked packets in that Trace View:
Step 2 Select the desired packet from the displayed list. The Trace View repositions to show the packet at the top of your screen. Note The Go to Marker feature functions in conjunction with the Set Marker feature. The comments within the parentheses following each marked packet are added or edited with the Set Marker feature. Go to The Go To feature takes you directly to an event in a Trace. Step 1 Select Go To under Search on the Menu Bar. 122 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 You see the Go To drop-down menu:
Step 2 Select the event you want to go to and enter the necessary information. Packet Types Select the type of packet you want to go to. 123 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Header AM_Addr Select an Active Member Address from the list. DataLength Allows searching based on data length in bytes from the recording. 124 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Lmp Opcode Select the Link Management Protocol Operational Code (Lmp Opcode) that you want to go to. L2Cap Signalling Command Select the type of L2Cap Signalling Command that you want to go to. 125 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 L2Cap CID Select the L2Cap Channel ID (L2 Cap CID) that you want to go to. Error Moves trace view to next uncorrected error. Soft Bit Error Moves trace view to next soft (corrected) error. Loss of Sync Moves trace viewer to the next loss of sync. Find Find is a utility within MBTTracerat allows you to conduct searches of one or more events within a trace. Find allows you to search different hierarchical levels within the trace - packets, LMP Messages, L2CAP messages etc. To start find,
Select Find... under Search on the Menu Bar OR Click in the Tool Bar. 126 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 You see the User-Defined Find Events screen:
The Find window divides into three areas:
Left area -- Controls the search level, search direction and search origin. Find All - Extracts the results and place them in a separate trace. Search In Hidden - Searches all packets including packets that have been hidden. Center area -- Controls the event groups to be searched. The selection you make will display further choices on the right side of the Find window. At the bottom are three options called Union, Intersection, and Exclusion that are used with multi-criteria searches. These options are explained below. Right area -- Controls the specific events to be searched within the trace. The box in this right section displays events from the selected Event Group. The right area is context sensitive -- the Event Group selected in the Center area will determine what events will display on the right. For example, if you select Packet Type, the Right area will show you a list of packet types. Bold entries in the list represent items that actually occurred in the trace. 127 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 In the screenshot shown above, for example, AM Address is selected. On the right, you see that only Address 1 is in bold. This indicates that only a single device was transmitting traffic in the displayed trace. Event Groups Event Groups are categories of events that can occur in a trace. Clicking on an Event Group will display a list of Event types on the right side of the Find window that occur within each Event Group. AM Address Contains a list of seven Active Member addresses. Bold entries represent devices that occur in the trace. Master/Slave Contains two options labeled Master and Slave. Selecting an option will cause BTTracer to search for traffic based on the selected role. Packet Type Contains a list of all Bluetooth packet types. If a packet type occurs in the trace, it will appear in bold. Acknowledge Contains a list of three Acknowledge types: Explicit NACK, Implicit NACK, and ACK. The three Acknowledge types are responses a device can issue to attempts to transmit packets to it. A device can send an Acknowledgment in two ways: through setting the ARQN field to 0 (= explicitly not acknowledged), to 1 (explicitly acknowledged) or by sending an empty packet that does not have an ARQN field (= implicitly not acknowledged). Explicit NACK - Explicitly not acknowledged. An Explicit NACK is an explicit response by a device that it did not receive a data packet. The Explicit NACK is transmitted in the ARQN field (=Acknowledgment Request Negotiation field). ARQN=0 means Explicit NACK. Implicit NACK - Implicitly not acknowledged. An Implicit NACK is a NACK that is implied rather than explicitly stated. If a device responds to a data packet by sending an empty packet, the NACK is implied. ACK - Acknowledged. If a data packet is successfully transmitted to a target device, the target device acknowledges the received packet by setting the ARQN field to 1. 128 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Acknowledgments are easily seen in BTTracer traces because BTTracer adds an Ackd field on data packets of the transmitting device. This means that you do not have to hunt through the trace to see if the packet was acknowledged. The following screenshot shows two examples of Acknowledgments. Implicit NACK - Packet 14577 is a data packet sent by the piconet Master device. Packet 14579 should have been a data packet with an acknowledgment. Instead, it is an empty packet. This Master interprets this empty packet as an Implicit NACK (i.e., implicitly not acknowledged). BTTracer summarizes this packet exchange by adding an Ackd field to the Masters data packet and setting the Ackd field to Imp Nak. ACK - Packet 14580 is the Masters retransmission of the data sent in packet 14577. Packet 14582 is the reply by the Slave device. This reply contains an ARQN field with a value of (= Acknowledge). BTTracer summarizes this packet exchange by setting the Ackd field on packet 14580 to Ack. 129 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Data Length Contains a list of all data lengths that occur in the trace. 130 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Data Pattern Searches for the next packet that has a specified data pattern. Searching for Bit Patterns You search for a bit pattern by using the box labeled Bitmask. Enter one of the three following values:
X = 'Don't care,'
0 = 'Match a 0',
1 = 'Match a 1.'
Example -- xxxxxx01 means 'Look for a data pattern where the first 6 bits can be any value but the last two bits must be 01.'
Searching for Long Patterns You can search for long pattern sequences by entering patterns into multiple rows within the editor. Entering a pattern on one row and skipping several rows before entering the second pattern tells BTTracer to search for the entire pattern between the two specified rows. Example - Enter xxxxxx01 in row 1 and 11xxxxxx in row 2. This pattern means 'Look for the pattern xxxxxx0111xxxxxx.'
131 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Example - If you enter xxxxxx01 into row 0 and 11xxxxxx into row 4, it means 'Look for the pattern xxxxxx01 xxxxxxxx xxxxxxxx xxxxxxxx 11xxxxxx.'
Searching for Hexadecimal Patterns The columns marked Match and Mask allow you to specify a pattern in hex. You enter the pattern you want to match in the column marked Match, and enter the mask in the column marked Mask. The Mask column allows you to specify which bits you are searching for. Example - A Match of 03 and a Mask of '0F' tells BTTracer that you are looking for the hex pattern of 03 occurring in the last four bits of the pattern. If you enter these values in the Match and Mask columns, the Bitmask section will automatically display the equivalent bit values: XXXX0011. Union, Intersection, and Exclusion If you select multiple events, you will need to use the options Union or Intersection to conduct the search. Union is used to search for any selected event: "Find x or y." Union lets you tell the analyzer to search the trace for any of any of the selected items. Intersection is used to search for all selected events: "Find x and y."
Intersection lets you tell the analyzer to search the trace for any packet having all of the selected events. Exclusion is used to exclude selected traffic from the trace. Exclusion is used with Union and Intersection --i.e., you select Exclusion with Union or Intersection.
Exclusion + Union -- tells BTTracer to exclude packets with any of the specified events.
Exclusion + Intersection -- tells BTTracer to exclude packets with all of the specified events. Using Find Step 1 Select the display level to be searched from the Search For box on the left side of the window. For example, to search through L2CAP messages, select L2CAP. The display level that you select will affect options presented in the Events Group box. 132 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 2 Select a search direction and origin. Step 3 Select one or more events from the Events Group box. Your choices will affect options presented in the box on the right side of the screen. Step 4 If you have selected two or more criteria, then select either :
Union: Find all packets that match ANY of the specified events. An example would be to find packets with either X or Y.
Intersection: Find all packets that match ALL of the specified events. An example would be to find all packets with X and Y. If you want to selected events from the trace, then select:
Exclusion: Exclude all packets that match any of the specified events. This option works in cunjunction with Union and Intersection. Select an exclusion plus one of the other two options. If you select Exclusion and Union, it means Exclude packets in any of the following events. An example would be to exclude packets with either X or Y. Step 5 Click OK. The search will then occur. Afterwards, the packets meeting the search criteria will display. Some Find Examples Search for all DM1 and Poll packets with an Active Member Address of 7. Step 1 From the Event Group, select Packet Types. Step 2 From the box on the right, select DM1 and Poll. Step 3 From the Event Group, select Header AM_Addr. Step 4 From the box on the right, select AM_Addr=7. Step 5 From the Center area, select Intersection. Selecting Intersection tells BTTracer to find packets with ALL of the selected traits. 133 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Step 6 Press OK. The trace should reposition to the first DM1 or Poll packet that has an Active Member address of 7. Exclude all DM1 and Poll Packets with Active Member Addresses of 7. Step 1 Select Packet Types from the From the Event Group Step 2 Select DM1 and Poll from the box on the right. Step 3 Select Header AM_Addr from the Event Group. Step 4 Select AM_Addr=7 from the box on the right. Step 5 From the Center area, select Intersection and Exclusion Step 6 Press OK. The trace will redisplay so that it excludes DM1 packets with AM_Addr=7 and Poll packets with AM_Addr=7. Exclude all packets with ANY of the following attributes: DM1, Poll, or AM_Addr=7. Step 1 Select Packet Types from the Event Groups. Step 2 Select DM1 and Poll from the box on the right. Step 3 Select Header AM_Addr from Event Group. Step 4 Select AM_Addr=7 from the box on the right Step 5 Select Union and Exclusion. Selecting Union causes the analyzer to search for any of the selected events. Step 6 Press OK. The trace will redisplay so that it excludes DM1s, Polls, or any packet with AM_Addr=7. Find Next To apply the previous Find parameters to the next search,
Select Find Next under Search on the Menu Bar OR Click on the Tool Bar. 134 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 11.2 Edit Comment You can create, view, or edit the 100-character comment field associated with each Trace file. Step 1 Select Edit Comment under File on the Menu Bar. You see the Edit comment for trace file window:
Step 2 Create, view, or edit the comment. Step 3 Click OK. 11.3 Reports The Report menu provides several reports to assist you in analyzing Bluetooth traffic recorded by the analyzer. File Information To display a File Information report,
Select File Information under Report in the Menu Bar OR Click in the Tool Bar. You see the File Information screen:
135 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The File Information report provides valuable information about how the recording was made, what the buffer settings were, what the trigger options were, and what version of all the analyzer hardware was used to make the recording. Error Summary The Error Summary command displays an error summary of the current trace file and allows you to go to a specific packet, and save the error file to a uniquely named file. Timing Calculations Starts the modeless calculator dialog for calculating various timing and bandwidth parameters in the recording file. To display a File Information report,
Select Timing Calculations under Report in the Menu Bar OR Click in the Tool Bar. 136 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 You see the Timing and Bus Usage Calculator screen:
To calculate bus usage and bit rate errors, Step 1 Enter the range of packets to be examined in the text boxes marked "From packet" and "To packet."
Step 2 If you wish to limit your calculations to a single device, select the devices address from the AM Address drop-down menu. Step 3 Click the "Calculate" button. At this point, bus usage will be calculated. Traffic Summary The Traffic Summary dialog box displays a text summary of traffic captured in the current trace. The Traffic Summary window divides into two main sections: a short top section (shown above in the top left corner of the window) that summarizes traffic for each protocol level, and a long section below describing the traffic details for each protocol level. 137 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 The second section is scrollable: click on an item below one of the headings to display scroll arrows. The arrows will allow you to scroll through the packets or transactions within that section. As you scroll, the trace will simultaneously jump to the packet or transaction that is listed. At the bottom of the Traffic Summary window is a button marked "Textual Summary." Clicking this button will cause WordPad to open and display the current Traffic Summary, as shown below. This data can then be printed or saved. 138 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 11.4 BT Neighborhood The BT Neighborhood status box displays information about known Bluetooth devices. This command is accessible through the View menu in the menu bar. Three types of data are displayed: Device Address, Class of Device (COD), and the Bluetooth Clock Frequency for each discovered device. The expected Bluetooth clock frequency is 3200 Hz
+/- 250 PPM. 11.5 Encryption Bluetooth encryption is a multi-staged process that provides devices with secure, encrypted communications. The process begins with a device prompting the user for a Personal Identification Number (PIN). When the right PIN is entered, the Slave begins an encryption setup dialogue with the Master. At the beginning of this dialogue, the Slave and the Master agree on a Link Key. A Link Key is a 128-bit value that the two devices use for authentication. When the Slave and Master agree on a Link Key, the Slave then negotiates for the transfer of the Encryption Key from the Master device. The Encryption Key is used to encrypt and decrypt messages. Once the Encryption Key is transferred, both devices use it to encrypt all subsequent communications. In order for BTTracer to decode encrypted traffic, it needs the Link Key for each Master-Slave connection for which encryption will be used. If you know the Link Key, you can enter the Key into the Encryption Options dialog box. If you do not know it, you give BTTracer the PIN for a device 139 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 and allow BTTracer to discover the Link Key on its own. Once BTTracer has the Link Key, it can capture the rest of what it needs by listening to the Master and Slave devices as they negotiate for the Encryption Key. Configuring BTTracer for Encryption For BTTracer to successfully decrypt traffic, two steps need to be performed: 1) BTTracer needs to be given the PIN or Link Key for each Master-Slave connection; and 2) Recording needs to be begun before the Slave connects to the Master. If recording is begun prior to the creating the Master-Slave connection, BTTracer will be able to obtain the encryption key and decode encrypted traffic. The following steps show how to configure BTTracer for encrypted traffic. Note Be sure to begin the following process prior to connecting your Slave device to the Master or BTTracer will not be able to capture the Link Key. Step 1 Select Setup >Encryption Options ... The following dialog box opens. Step 2 Click the button marked Add Slave Device. When you click this button, a list of devices will appear in the Slave Device Address drop-down menu. Step 3 Select an address from the drop-down menu marked Slave Device Address or enter the Device Address manually if it is not in the list. Step 4 Enter the appropriate Personal Identification Number (PIN) for the selected device to the box marked PIN Code. This PIN allows BTTracer to learn the Link Key. If you do not 140 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 have the PIN, skip to Step 5. Note The PIN you provide should be the same used by the Slave. For example, if your Slave device requires a PIN of "1234", then enter the same PIN in the dialog box shown above. Step 5 If you do not have the PIN, or if the Master and Slave have already agreed upon the Link Key, manually enter a Link Key as a 128 bit
(sixteen byte) hex value into the box marked Current Link Key. If you have the PIN, you can skip this step. Note If the Master and Slave were previously connected, they may already agree on the Link Key. In this case, you will need to provide BTTracer with the Link Key and not simply the PIN. Step 6 Click Apply The changes you have made are applied and the information is displayed in the dialog box as shown below. Four fields will display: Device Address, PIN, the Link Key, and Link Key status. Link Key status may read:
Mstr (=Master units Link Key) Slve (=Slave units Link Key) Comb (=Combination Key) Init (=Initialization Key) Temp (=Temporary Key) User (=User-defined Key) Step 7 Click OK. The dialog box closes. 141 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 142 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 How to Contact CATC Type of Service Call for technical support Fax your questions Write a letter Send e-mail Visit CATCs web site Contact 1 (800) 909-2282 1 (408) 727-6600 1 (408) 727-6622 US and Canada:
Worldwide:
Worldwide:
Computer Access Technology Corp. Customer Support 2403 Walsh Avenue Santa Clara, CA 95051-1302 support@CATC.com http://www.CATC.com/
Warranty and License Computer Access Technology Corporation
(hereafter CATC) warrants this product to be free from defects in material, content, and workmanship, and agrees to repair or replace any part of the enclosed unit that proves defective under these terms and conditions. Parts and labor are warranted for one year from the date of first purchase. The CATC software is licensed for use on a single personal computer. The software may be copied for backup purposes only. This warranty covers all defects in material or workmanship. It does not cover accidents, misuse, neglect, unauthorized product modification, or acts of nature. Except as expressly provided above, CATC makes no warranties or conditions, express, implied, or statutory, including without limitation the implied warranties of merchantability and fitness for a particular purpose. CATC shall not be liable for damage to other property caused by any defects in this product, damages based upon inconvenience, loss of use of the product, loss of time or data, commercial loss, or any other damages, whether special, incidental, consequential, or otherwise, whether under theory of contract, tort (including negligence), indemnity, product liability, or otherwise. In no event shall CATC's liability exceed the total amount paid to CATC for this product. CATC reserves the right to revise these specifications without notice or penalty. 143 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 144 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 INDEX Numerics 1100 packet 77 1101 packet 77 A Abort upload 34 About Merlin 21 Acknowledge 128 Action buttons 31, 83 Actions tab 82 Addr 104 Addresses AM_ADDR 77 Bluetooth 54 piconet 73 slave device 44 swap 74 target 55 AM Address 128 Analyzer describing Bluetooth 2 requirements 17 set up 9 status 34 updates 24 API 4 Application installation 9, 18 Architecture of Piconet 3 Arqn 104 ARQN condition 77 AT 110 AT commands protocol 96 Authentication 139 Automatic updates 24 Automation Feature 4 AUX1 packet 77 B Basic installation 9 Bit pattern, searching 131 Blue dot menus 85 Bluetooth antenna 13 BusEngine 6 described 1 device address 54 first recording 10 limited search 67 neighborhood 139 recording traffic 92 search for device 51 searching for devices 40 target address 55 BNEP 96, 110 Breakout board 15 BT neighorhood 139 Bubble help 35 Buffer size 10, 65 BusEngine automatic updates 24 Bluetooth 6 general updates 21, 23 manual updates 25 Buttons counting 83 toolbar 31 C CAC 104 Calculations, timing 136 Capturing a trace 20 CATC Technical Support 143 Certification 7 Changing trace view 96 Channel connections, L2CAP 113 Circuits, custom 17 Clicked fields, menus in 108 Clock rate, match 73 Collapse data 106 Colors 97 Comments, editing 135 Components, physical 5 Configuring encryption 140 Connecting events 84 Connectors 145 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 data 7, 15 physical 7, 15 Correlation Value 74 Counters connecting events 84 value 85, 86 Counting buttons 83 CRC 104 CRC error 80 Creating Display Option Files 96 Custom circuits 17 D Data connector 15 decoding 110 expand, collapse 106 filename 10 length 79 pattern 75, 79 searching by length 124 searching by pattern 131 transfer message 112 DB-9 15 Debug file 11, 75 Decoding 110 Dedicated inquiry 11 Description of Merlin 2 Detailed installation 13 Device address 139 Bluetooth address 54 general search 42 hiding 100 inquiry 74 search 40 search for Bluetooth 51 search results 53 slave address 44 DH1, 2, 3 packet 77 DIAC LAP 74 Display configuration name 96 Display options colors 97 creating files 96 formats 99 general 95 hiding 100 saving 101 Displaying information 103, 135 DM1 104 DM1, 2, 3 packet 77 Drivers, loading USB 18 Duration of search 51 DUT Recv/Xmit Freq 69 DV packet 77 E Editing comments 135 Enable debug file 75 tooltips 95 Encryption 139, 140 Environmental Conditions 7 Error summary 136 Errors CRC 80 FEC 80 header length 81 HEC 80 invalid packet 80 payload length 81 Searching for 126 setting conditions for 80 sync loss 81 threshold exceeded 80 types of 75 Established Piconets 71 Events conditions 77 connecting 84 options 75 sequencing 90 tab 75 trigger 10, 64 Exclusion search 132 Existing Piconet, recording 49 Expand data 106 146 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Explicit NACK 128 External input signals 75, 81 interface 15 trigger form 89 F Features 4 FEC Error 80 FHS packet 77 File information, displaying 135 File menu 29 Filename and data 10 Filter In/Out button 83 Filter Out/In 87 Filtering 76, 77 Find feature, using 132 Finding 126 Finding devices 40 Firmware updates 21, 23, 24, 25, 27 Flow 104 Fonts 96 Force resynchronization 73 Formats tab 99 Found devices 43, 53 France hops 69 Frequencies, DUT 69 Frequency hops, hiding 107 frequency mode 50 G G.P. OUT 17 General description 2 General features 4 General inquiry 11, 67, 70 General options display 95 recording 63 General purpose output 89 Generating reports 135 Go to DataLength 124 error 126 Header AM_Addr 124 L2Cap CID 126 Lmp Opcode 125 marker 122 packet types 123 packet/Message/Protocol 121 Groups, events 75 H HDLC 110 HDLC frames 96 Headers AM_Addr 124 length error 81 packets 76 payload 78 HEC 104 HEC Error 80 Help menu 31 Hexadecimal patterns, searching 131 HID 110 Hiding 100, 107, 108 Higher protocols, decoding 109 High-pulse output 88 Hop 50 Hops hiding 107 reduced mode 58 sequence 11, 68 Hot keys 36 Humidity 7 HV1, 2, 3 packet 77 I Idle 104 Implicit NACK 128 In/Out connector 15 Information, interpreting 103 Input signals 75, 81 Inquiry dedicated 11 general 67 perform/skip 39 recording 11, 67 timeout 11, 74 147 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Installation basic 9 detailed 13 Merlin 18 Interpreting a trace 103 Intersection search 132 Introduction 1 Invalid packet type error 80 J Japan hops 69 K Keyboard shortcuts 36 L L_CH (Logical Channel) 78, 104 L2CAP channel connections 113 CID, searching 126 described 110 messages 96, 108, 109, 112 L2FL 104 Len 104 Length of data 79 License 143 information 23 update software 22 Limited inquiry 11 Linking events 84 LMP described 110 messages 96, 109, 112 Opcode 125 Logical Channel 78 Long pattern, searching 131 Loss of sync searching for 126 timeout 74 Low-pulse output 88 M Manual trigger 7, 10, 64 Manual updates 25 Markers editing and clearing 105 searching 122 setting 104 Master address 73 and slave 128 device, syncing to 34 switch 73 Master/address 54 Match clock rate 73 Memory, Recording 7 Menus blue dots in events 85 clicked fields 108 pulldown 29 Merlin configure encryption 140 description of 2 installation 18 installing software 18 program startup 19 rear panel 14 setup 14 Message searching 121 Messages hiding 100 LMP, L2CAP 109, 112 transfer 112 Mode, recording 67 Modes test, recording in 58 Modes tab 66 N Neighborhood, BT 139 Nine-pin connector 15 NULL packet 77 Nulls, hiding 108 O OBEX 110 OBEX protocol 96 Opcode 104 148 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Operating temperature 7 Options general display 95 general recording 63 name 10 Piconet recording 68 search 56 Output signaling pins 16 Output signals, enabling 88 Overview 1, 29 P Package dimensions 7 Packets 1100, 1101 77 AUX1 77 DM1, 2, 3 77 DV 77 FHS 77 headers 75, 76 headers in 76 hiding 100, 101 HV1, 2, 3 77 invalid type error 80 NULL 77 POLL 77 searching 121, 123 types 77, 128 viewing 112 Page sync and record 68, 69 target 73 Paging traffic 73 Passive sync and record 71 Patterns, data 79 Payload headers 75, 78 length error 81 PC requirements 17 Percentage of triggering 66 Perform inquiry 50 Phone numbers, Technical Support 143 Physical Components 5 Piconet 149 addresses 73 established devices 71 master address 54 private device 72 recordiing 68 recording 11, 45, 49 recording traffic on 38 sample 3 search options 56 slave address 44 sync and record 71 synchronizing 45 target address 55 Wizard 46 PIN 139 Pin-out description 15 Pins, output signaling 16 Pkt 110 Polls hiding 108 POLL packet 77 Position of trigger 65 Post triggering, percentage 66 Power LED 7 Switch 7 PPP 96, 110 Pre-triggering 66 Private Device Piconets 72 Program installation 9, 18 starting Merlin 19 Progress indicator, recording 33 Protocol Analyzer 2 Architecture 3 decoding 110 hiding 100 searching 121 Prototype rework area 17 Pull-down menus 29 Pulse low signal 88 Pulse toggle signal 88 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 R Radio strength 35 Reading a trace 103 Record inquiry 67 Record menu 29 Recording a trace 20 Bluetooth traffic 10, 92 existing Piconet 49 LED 7 memory 7 mode 11 mode, inquiry 67 Piconet 45 piconet 68 progress indicator 33 reduced hop mode 58 session 12 type 64 Recording Options events 75 general 10, 63, 64 in Wizard 45 Piconet 68 saving 91 synchronization methods 66 Recording type 49 Recv, DUT freq 69 Reduced hops 58, 69 Reports generating 135 menu 29 Requirements, Analyzer and PC 17 Restart button 83 Results of search 53 Resynchronization, forced 73 Revisions 21 Rework area, for prototype 17 RFCOMM 110 RFCOMM protocol 96 S Sample Piconet 3 recording 12 Saving display options 101 recording options 91 SDP Msg 110 Search 42 duration of 51 general 52 Search menu 29 Search options 56 Search results 53 Search type 40, 51 Searching by data pattern 131 complex 126 data length 124 for bit pattern 131 for bit patterns 131 for errors 126 Header AM_Addr 124 L2Cap CID 126 Lmp Opcode 125 packet types 123 recorded traffic 121 Security 139 SEQN condition 77 Sequence event 90 hop 68 Set marker 104 Setup menu 29 Merlin 14 Shortcuts, keyboard 36 Signalling message 112 output pins 16 Signals input 75, 81 outputs, enabling 88 strength, radio 35 Single frequency hops 69 150 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Size of buffer 65 Skip inquiry 50 Slave device, address 44 Slave switch 73 Snapshot 10, 64 Soft Bit Error, searching 126 Software automatic updates 24 installation 9, 18 license updates 22 overview 29 regular updates 21 starting Merlin 19 Spain hops 69 Special Interest Groups (SIGs) 1 Specifications 7 Standard hops 69 Starting Merlin 19 Status bar 33 Status of Analyzer 34 Storage temperature 7 STP messages, protocol 96 Strength of signal 35 Summary error 136 traffic 137 Support, technical 143 Swapping addresses 74 Switches 7, 73 Sync and record 70, 71 loss error 81 loss of, searching 126 methods 68, 69 timeout, loss of 74 to a master device 34 window 74 Synchronization, forced 73 Synchronize Piconet 45 Synchronized LED 7 System setup, Merlin 14 T Tabs display colors 97 display formats 99 general display 95 hiding display 100 recording events 75 recording, general 10, 63 recording, modes 11, 66 recording, options 63 Target, page 73 TCS messages, protocol 96 Technical Support 143 Temperature tolerances 7 Test debug 75 Test mode, recording in 58 Threshold Exceeded error 80 TID 104 Time Stamp 104 Timeout inquiry 74 loss of sync 74 Timeslot filtering 76 Timing calculations 136 Tips, tool 35, 95 Toggle signal 88 Toolbar 31 Tooltips 35, 95, 104, 112 Trace addresses 74 filename 10 reading 103 recording 20 sample 12 view level, changing 96 Traffic Bluetooth 92 generation 5 hiding 108 on Piconet 49 paging 73 recording 20, 56 recording on piconet 38 searching 121 summary 137 151 CATC BTTracer Protocol Analyzer Users Manual Version 1.0 Trail 104 Transfer message, data 112 TRG OUT 16 Trigger event 64 external form 89 LED 7 position 10, 65 post triggering 66 recording, manual 64 Type of recording 64 U Unassociated traffic, hide 108 Union search 132 Updates automatic 24 firmware, BusEngine 23 software license 22 software, firmware, BusEngine 21 USB drivers, loading 18 V Values, changing counters 85 View menu 29 options 31 packets 112 W Warranty 143 Weight 7 Window menu 31 Wizard Piconet 46 Wrap 96 X Xmit, DUT freq 69 Z Zoom 35, 95 152
1 2 | WAND Manual 1 of 2 | Users Manual | 2.19 MiB |
2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622 CATC Merlins Wand 1.22 Bluetooth Test Generator Users Manual Document Revision 1.22 June 18, 2002 730-0019-00 CATC MERLINS WAND 1.22 Users Manual CATC Merlins Wand 1.22 Bluetooth Test Generator Users Manual, Document Revision 1.22 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. Trademarks and Servicemarks CATC, Merlins Wand, and Merlin are trademarks of Computer Access Technology Corporation. Bluetooth is a trademark owned by Bluetooth SIG, Inc. and is used by Computer Access Technology Corporation under license. Microsoft, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. RadioShack is a registered trademark of RadioShack Corporation. GN Netcom is a registered trademark of GN Netcom, Inc. Motorola is a registered trademark of Motorola, Inc. Belkin is a registered trademark of Belkin Components. Coby is a registered trademark of Coby Electronics Corporation. Plantronics is a registered trademark of Plantronics, Inc. Intel, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. AMD, Athlon, Duron, and AMD-K6 are trademarks of Advanced Micro Devices, Inc. All other trademarks are property of their respective companies. Copyright Copyright 2002, Computer Access Technology Corporation (CATC). All rights reserved. This document may be printed and reproduced without additional permission, but all copies should contain this copyright notice. ii Part number: 730-0019-00 CATC MERLINS WAND 1.22 Users Manual Merlins Wand Conformance Statements FCC Conformance Statement This equipment has been tested and found to comply with the limits for both a Class A and Class B digital device, pursuant to Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference when the equipment is operated in a commercial or residential environment. This equipment generates, uses, and can radiate radio frequency energy, and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. The end user of this product should be aware that any changes or modifications made to this equipment without the approval of CATC could result in the product not meeting the Class A or Class B limits, in which case the FCC could void the user's authority to operate the equipment. Important Notice This equipment contains Transmitter Module FCC ID PNI8001001. To comply with FCC RF exposure requirements (sections 1.1307 and 1.310 of the Rules) only the antenna supplied by CATC must be used for this device. The antenna must be located at least 20 centimeters away from all persons. EU Conformance Statement This equipment complies with the R&TT Directive 1999/5/EC. It has been tested and found to comply with EN55022:1998 Class B
(EN61000-3-2:1998, EN61000-3-3:1995), EN55024:1998
(EN61000-4-2:1995, EN61000-4-3:1995, EN61000-4-4:1995, EN61000-4-5:1995, EN61000-4-6:1995, EN61000-4-11:1994), and EN60950:1999. The transmitter module was tested and found to comply with ETS 300 328 (1997). iii CATC MERLINS WAND 1.22 Users Manual iv CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS TABLE OF CONTENTS Document Disclaimer . ii Trademarks and Servicemarks . ii Copyright . ii FCC Conformance Statement . iii Important Notice . iii EU Conformance Statement . iii Table of Contents . v Chapter 1 Overview. 1 Applications . 1 Merlins Wand User Interface. 2 Key Features . 3 Audio Connections - Important Information . 4 Limitations . 5 Specifications . 6 Chapter 2 Getting Started. 7 System Requirements . 7 Setting Up Merlins Wand . 8 Installing the Software and Starting the Program . 8 Install from CD-ROM. 8 Install from installation download . 9 Start the program. 9 Displaying the On-Screen Help . 9 Application Layout . 10 Menus . 12 Toolbars. 14 Merlins Wand Toolbar . 14 Merlin Bluetooth Analyzer Toolbar . 15 Tool Tips . 15 Merlins Wand Keyboard Shortcuts . 15 License Keys. 16 License Information . 16 Chapter 3 Bluetooth Wizard. 17 Starting Bluetooth Wizard . 17 Connect to a Device: Headset. 18 Connect to a Device: Headset Audio Gateway. 22 Connect to a Device: Object Push . 27 Device Emulation: Headset . 30 Device Emulation: Headset Audio Gateway . 33 Device Emulation: Object Push. 35 v CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS Restarting the Wizard . 38 Chapter 4 Command Generator . 39 Layout of the Command Generator . 39 Using Command Generator . 40 Customizing the List of HCI Commands . 41 Tables of Available Commands . 42 HCI Commands . 42 Link Control Commands . 42 Link Policy Commands . 44 Host Controller & Baseband Commands . 44 Informational Commands . 46 Status Commands . 46 Testing Commands . 47 CATC-Specific Commands. 47 L2CAP Commands . 48 SDP Commands . 48 RFCOMM Commands . 49 TCS Commands . 50 OBEX Commands . 50 Chapter 5 Script Manager . 53 Layout of the Script Manager Window. 53 Running Scripts. 54 Writing Scripts . 55 Sample Scripts . 56 sample.script . 57 Sample-2.script . 59 Script Controlling Merlin Interface . 60 Chapter 6 Device Search and Device List Pop-Up Menu . 63 Device Search . 63 Device List Pop-Up Menu . 64 Create an ACL Connection. 64 Establish an Audio Connection. 65 Display Device Information . 66 Delete a Device. 67 Disconnect All . 68 Chapter 7 Data Transfer Manager and Data Pipes . 69 Creating Data Pipes . 69 Using Data Pipes. 70 Transfer Data Using Command Generator . 71 Access Pipes Using Script Manager . 72 Receive Pipes . 72 vi CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS Closing Pipes . 73 Saving Data Pipes . 73 Saving Data Transmit Pipe Lists. 74 Saving a Default List . 74 Saving Data Receive Pipes . 74 Deleting Pipes . 74 Opening Pipe Lists . 75 Renaming Pipes . 75 Modifying Pipes . 76 Chapter 8 Using Merlin to Record Merlins Wand Traffic . 77 Set Up a Remote Machine . 77 Windows 98/Me Operating Systems. 77 Windows NT/2000 Operating Systems . 78 Set Up Connection Options . 80 Start Merlin . 81 Connect to Merlin with Merlins Wand . 81 Set Merlin Recording Options . 81 Set Merlin Display Options . 83 Set Merlin Encryption Options . 84 Start a Merlin Recording Session . 85 Stop a Merlin Recording Session . 85 Disconnect from Merlin Bluetooth Protocol Analyzer. 85 Troubleshooting . 86 Server Busy When Attempting to Launch Merlin . 86 Server Execution Failed When Attempting to Launch Merlin . 86 The Object Exporter Specified Was Not Found When Attempting to Launch Merlin . 86 Chapter 9 Contact and Warranty Information . 89 Contact Information . 89 Warranty and License . 89 Appendix A: Command Generator Command Descriptions. 91 HCI Command Descriptions. 91 HCI Link Control Commands. 91 Accept_Connection_Request . 91 Add_SCO_Connection . 91 Authentication_Requested . 92 Change_Connection_Link_Key . 92 Change_Connection_Packet_Type . 92 Create_Connection . 93 Disconnect . 93 vii CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS Exit_Periodic_Inquiry_Mode . 93 Inquiry. 93 Inquiry_Cancel . 94 Periodic_Inquiry_Mode . 94 PIN_Code_Request_Negative_Reply. 95 PIN_Code_Request_Reply . 95 Read_Clock_Offset. 95 PIN_Code_Request_Negative_Reply. 95 PIN_Code_Request_Reply . 95 Read_Clock_Offset. 95 Read_Remote_Supported_Features . 96 Read_Remote_Version_Information . 96 Reject_Connection_Request. 96 Remote_Name_Request . 96 Set_Connection_Encryption . 97 HCI Link Policy Commands. 98 Exit_Park_Mode . 98 Exit_Sniff_Mode. 98 Hold_Mode . 98 Park_Mode . 98 QoS_Setup . 99 Read_Link_Policy_Settings . 99 Role_Discovery . 99 Sniff_Mode . 100 Switch_Role . 100 Write_Link_Policy_Settings. 100 HCI Host Controller & Baseband Commands . 101 Change_Local_Name . 101 Delete_Stored_Link_Key . 101 Host_Buffer_Size . 102 Read_Authentication_Enable . 102 Read_Class_of_Device. 102 Read_Connection_Accept_Timeout . 103 Read_Current_IAC_LAP . 103 Read_Encryption_Mode . 103 Read_Link_Supervision_Timeout . 104 Read_Local_Name . 104 Read_Number_Of_Supported_IAC . 104 Read_Page_Scan_Mode . 104 Read_Page_Scan_Period_Mode. 105 Read_Page_Timeout . 105 Read_PIN_Type . 105 Read_Scan_Enable . 106 viii CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS Read_SCO_Flow_Control_Enable. 106 Read_Stored_Link_Key . 106 Read_Voice_Setting . 107 Reset . 107 Set_Event_Filter . 107 Set_Event_Mask . 108 Write_Authentication_Enable. 109 Write_Class_of_Device . 109 Write_Connection_Accept_Timeout . 110 Write_Current_IAC_LAP. 110 Write_Encryption_Mode . 111 Write_Link_Supervision_Timeout . 111 Write_Page_Timeout . 112 Write_PIN_Type . 112 Write_Scan_Enable. 113 Write_Stored_Link_Key. 113 Write_Voice_Setting . 113 HCI Informational Commands . 114 Read_BD_ADDR . 114 Read_Buffer_Size . 114 Read_Country_Code. 114 Read_Local_Supported_Features . 115 Read_Local_Version_Information . 115 HCI Testing Commands . 115 Enable_Device_Under_Test_Mode . 115 Read_Loopback_Mode. 116 Write_Loopback_Mode . 116 CATC-Specific HCI Commands. 116 CATC_BER_Test . 116 CATC_Change_Headset_Gain . 117 CATC_Read_Headset_Gain . 117 CATC_Read_Revision_Information. 118 CATC_Self_Test . 118 CATC_Write_Country_Code . 118 Other HCI Events . 118 L2CAP Command Descriptions . 119 ConfigurationResponse. 119 ConfigurationSetup. 119 ConnectRequest . 120 ConnectResponse . 120 DeregisterPsm. 120 DisconnectRequest . 120 EchoRequest . 121 ix CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS InfoRequest. 121 RegisterPsm . 121 SendData. 122 Other L2CAP Events . 122 SDP Command Descriptions . 122 AddProfileServiceRecord . 122 AddServiceRecord . 123 ProfileServiceSearch. 123 RequestServiceAttribute . 124 RequestServiceSearch. 125 RequestServiceSearchAttribute . 125 ResetDatabase. 125 RFCOMM Command Descriptions . 126 AcceptChannel . 126 AcceptPortSettings . 126 AdvanceCredit . 126 CloseClientChannel . 127 CreditFlowEnabled . 127 DeregisterServerChannel . 127 OpenClientChannel. 128 RegisterServerChannel . 128 RequestPortSettings . 128 RequestPortStatus . 129 SendData. 129 SendTest . 130 SetLineStatus . 130 SetModemStatus . 131 SendATCommand. 131 Other RFCOMM Events . 132 TCS Command Descriptions . 132 RegisterIntercomProfile . 132 Open_TCS_Channel . 132 Start_TCS_Call . 133 Disconnect_TCS_Call . 133 Send_Info_Message . 133 OBEX Command Descriptions. 134 ClientConnect . 134 ClientDisconnect. 134 ClientGet. 134 ClientPut . 135 ClientSetPath . 135 ServerDeinit . 135 ServerInit . 136 x CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS ServerSetPath . 136 Appendix B: Command Generator Examples. 137 Device Discovery and Remote Name Request . 138 Procedure . 138 Establish Baseband Connection . 139 Procedure . 139 Baseband Disconnection. 140 Procedure . 140 Create Audio Connection . 141 Procedure . 141 L2CAP Connection. 142 Procedure . 142 L2CAP Channel Disconnect. 144 Procedure . 144 SDP Profile Service Search . 145 Procedure . 145 SDP Reset Database and Add Profile Service Record . 146 Procedure . 146 RFCOMM Client Channel Establishment . 147 Procedure . 147 RFCOMM Client Channel Disconnection . 148 Procedure . 148 RFCOMM Register Server Channel. 149 Procedure . 149 Establish TCS Connection . 150 Procedure . 150 OBEX Server Init . 152 Procedure . 152 OBEX Client Connection and Client Get & Put. 153 Procedure . 153 Appendix C: Merlins Wand Scripting Commands . 155 Bluetooth Addresses . 155 Basic Commands . 155 Main() . 155 Clock() . 156 Connect() . 156 Disconnect() . 157 DoInquiry() . 157 GetDeviceClass() . 158 GetRemoteDeviceName() . 158 MessageBox() . 159 SetDeviceClass() . 159 xi CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS Sleep() . 160 Pipe Commands . 160 ClosePipe() . 160 DeletePipe() . 161 OpenPipe() . 161 ReadPipe() . 162 WritePipe() . 163 HCI Commands . 164 HCIAcceptConnectionRequest() . 164 HCIAddSCOConnection() . 164 HCIAuthenticationRequested() . 165 HCICatcBerTest() . 165 HCICatcChangeHeadsetGain() . 166 HCICatcEnterTestMode() . 168 HCICatcReadHeadsetGain() . 168 HCICatcReadRevisionInformation() . 169 HCICatcSelfTest() . 170 HCICatcTestControl() . 170 HCICatcWriteCountryCode() . 171 HCIChangeConnectionLinkKey() . 171 HCIChangeConnectionPacketType() . 172 HCIChangeLocalName() . 173 HCIDeleteStoredLinkKey() . 173 HCIEnableDeviceUnderTestMode() . 174 HCIExitParkMode() . 175 HCIExitSniffMode() . 175 HCIHoldMode() . 176 HCIMasterLinkKey() . 177 HCIParkMode() . 177 HCIPINCodeRequestNegativeReply() . 178 HCIPINCodeRequestReply() . 179 HCIQoSSetup() . 180 HCIReadAuthenticationEnable() . 181 HCIReadBDADDR() . 182 HCIReadBufferSize() . 182 HCIReadClockOffset() . 184 HCIReadConnectionAcceptTimeout() . 184 HCIReadCountryCode() . 185 HCIReadCurrentIACLAP() . 186 HCIReadEncryptionMode() . 187 HCIReadLinkPolicySettings() . 187 HCIReadLinkSupervisionTimeout() . 188 HCIReadLocalName() . 189 xii CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS HCIReadLocalSupportedFeatures() . 189 HCIReadLocalVersionInformation() . 190 HCIReadLoopbackMode() . 191 HCIReadNumberOfSupportedIAC() . 192 HCIReadPageScanMode() . 192 HCIReadPageScanPeriodMode() . 193 HCIReadPageTimeout() . 194 HCIReadPINType() . 195 HCIReadRemoteSupportedFeatures() . 195 HCIReadRemoteVersionInformation() . 196 HCIReadScanEnable() . 197 HCIReadSCOFlowControlEnable() . 198 HCIReadStoredLinkKey() . 198 HCIReadVoiceSetting() . 200 HCIRejectConnectionRequest() . 200 HCIRemoveSCOConnection() . 201 HCIReset() . 201 HCIRoleDiscovery() . 202 HCISetConnectionEncryption() . 202 HCISetEventFilter() . 203 HCISniffMode() . 204 HCISwitchRole() . 205 HCIWriteAuthenticationEnable() . 206 HCIWriteConnectionAcceptTimeout() . 207 HCIWriteCurrentIACLAP() . 207 HCIWriteEncryptionMode() . 208 HCIWriteLinkPolicySettings() . 209 HCIWriteLinkSupervisionTimeout() . 209 HCIWriteLoopbackMode() . 210 HCIWritePageTimeout() . 211 HCIWritePINType() . 211 HCIWriteScanEnable() . 212 HCIWriteStoredLinkKey() . 212 HCIWriteVoiceSettings() . 213 OBEX Commands . 214 OBEXClientConnect() . 214 OBEXClientDeinit() . 214 OBEXClientDisconnect() . 215 OBEXClientGet() . 215 OBEXClientInit() . 216 OBEXClientPut() . 217 OBEXClientSetPath() . 218 OBEXServerDeinit() . 219 xiii CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS OBEXServerSetPath(Path) . 220 RFCOMM Commands. 221 RFCloseClientChannel() . 221 RFOpenClientChannel() . 221 RFRegisterServerChannel() . 222 RFSendData() . 223 RFSendDataFromPipe() . 223 RFReceiveData() . 224 RFWaitForConnection() . 225 RFAcceptChannel() . 226 RFAcceptPortSettings() . 226 RFCreditFlowEnabled() . 227 RFRequestPortSettings() . 228 RFRequestPortStatus() . 229 RFSetLineStatus() . 230 RFSetModemStatus() . 231 RFSendTest() . 232 RFAdvanceCredit() . 233 TCS Commands . 233 TCSRegisterProfile() . 233 TCSOpenChannel() . 234 TCSStartCall() . 234 TCSDisconnectCall() . 235 TCSSendInfoMessage() . 236 L2CAP Commands . 238 L2CAPConfigurationSetup() . 238 L2CAPConfigurationResponse() . 239 L2CAPConnectRequest() . 240 L2CAPConnectResponse() . 241 L2CAPDeregisterAllPsm() . 241 L2CAPDisconnectRequest() . 242 L2CAPEchoRequest() . 242 L2CAPInfoRequest() . 243 L2CAPRegisterPsm() . 244 L2CAPSendData() . 244 L2CAPSendDataFromPipe() . 245 L2CAPWaitForConnection() . 245 SDP Commands. 246 SDPAddProfileServiceRecord() . 246 SDPQueryProfile() . 247 SDPResetDatabase() . 247 SDPAddServiceRecord() . 248 Merlin Commands . 249 xiv CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS MerlinResetAllEncryptionOptions() . 249 MerlinSetDisplayOptions() . 249 MerlinSetEncryptionLinkKey() . 250 MerlinSetEncryptionPIN() . 250 MerlinSetRecordingOptions() . 251 MerlinStart() . 251 MerlinStartRecording() . 252 MerlinStop() . 252 MerlinStopRecording() . 253 Appendix D: CATC Scripting Language . 255 Values . 255 Literals . 255 Integers . 255 Strings . 256 Escape Sequences . 256 Lists. 257 Raw Bytes . 257 Null . 257 Variables . 257 Global Variables . 258 Local Variables . 258 Constants. 259 Expressions . 259 select expression . 260 Operators. 261 Operator Precedence and Associativity . 262 Comments . 268 Keywords . 268 Statements . 269 Expression Statements . 269 if Statements . 270 if-else Statements . 270 while Statements . 270 for Statements . 271 return Statements . 272 Compound Statements . 273 Preprocessing . 274 Functions. 275 Primitives . 276 Call() . 277 Format() . 277 Format Conversion Characters . 278 GetNBits(). 279 xv CATC MERLINS WAND 1.22 Users Manual TABLE OF CONTENTS NextNBits(). 280 Resolve(). 280 Trace(). 281 xvi CATC MERLINS WAND 1.22 Users Manual 1. Overview CHAPTER 1 Overview The CATC Merlin's Wand Bluetooth Test Generator is the newest member in CATC's industry-leading line of high performance, serial communication protocol analysis tools and test equipment. Preceded by CATC's Merlin, a Bluetooth Protocol Analyzer, Merlin's Wand has been designed as an intelligent Bluetooth wireless technology device that can be used as a verification/validation tester or as an engineering debug and analysis tool. Through its software interface, designers and test technicians will be able to quickly and easily issue protocol commands and test sequences to analyze or validate designs to ensure compliance to the Bluetooth specification. Merlins Wand can be used in conjunction with the Merlin protocol analyzer, allowing for real-time captures of test sequence results, as is required by the Bluetooth SIG to provide evidence of product compliance to the specification. 1.1 Applications Merlin's Wand is a combination of hardware and Microsoft Windows-based application software. The hardware/software combination is capable of acting as a standard Bluetooth master or slave device within a piconet. By allowing this capability, Merlin's Wand can be used to establish or participate in a piconet and to send or receive data within the piconet. Through the Merlins Wand Bluetooth Wizard, users can quickly and easily manage Bluetooth wireless traffic generation. Additionally, via its Command Generator, Merlin's Wand can issue individual Bluetooth commands to a device under test, allowing a designer to focus his or her effort on a specific function or group of functions related to the device. Furthermore, users can quickly create test sequences with Script Manager, thus eliminating the difficulties normally associated with the creation of complex test sequences. 1 CATC MERLINS WAND 1.22 Users Manual CHAPTER 1 Overview 1.2 Merlins Wand User Interface The Merlins Wand user interface consists of the Main window, the Logs window at the bottom of the screen, and the Device Status window on the left side of the screen. The applications primary tools are run within the Main window: Bluetooth Wizard, Command Generator, and Script Manager. If Command Generator and Script Manager are not enabled on your Merlins Wand system, you will need to obtain License Keys from CATC in order to use them. Each tool offers a different means of generating traffic. Note: Only one tool can be run at a time. Bluetooth Wizard is a point-and-click tool for creating connections and transferring data between Merlins Wand and other Bluetooth devices. This tool requires little Bluetooth wireless technology experience and allows you to generate Bluetooth traffic without having to execute specific Bluetooth commands. Bluetooth Wizard is described in Chapter 3, Bluetooth Wizard, on page 17. 2 CATC MERLINS WAND 1.22 Users Manual CHAPTER 1 Overview Command Generator is a tool that presents a menu of protocol commands that can be selected and executed in virtually any sequence. Command Generator thus offers maximum control over the traffic generation process, but also requires familiarity with the Bluetooth commands. Command Generator is described in Chapter 4, Command Generator, on page 39. Script Manager is a tool that provides an editor for writing and/or executing scripts that will generate Bluetooth wireless traffic. With Script Manager, new scripts can be written and saved, or existing scripts may be opened, edited, and run. Script Manager is described in Chapter 5, Script Manager, on page 53. 1.3 Key Features Plug-and-play USB connection between test system and test module External antenna can be removed to create wired piconet Audio connector for connecting audio devices, such as headsets Can operate as either a master or slave device in a piconet Graphical interface allows for easy selection of command parameters Wizard provided to reduce learning curve and memorization of command sequences Test modes provide for these Bluetooth wireless technology protocols:
HCI, L2CAP, SDP, RFCOMM, TCS, and OBEX Scripting capability for establishment of predefined test sequences System information report provides details regarding device under test 3 CATC MERLINS WAND 1.22 Users Manual CHAPTER 1 Overview Can be used with Merlin protocol analyzer Power-on self-diagnostics No external power required -- obtains power from USB connection One year warranty and online customer support Please refer to the Bluetooth Specification, version 1.1 for details on the Bluetooth wireless technology protocol. The Bluetooth specification is available from the Bluetooth SIG at its web site http://www.Bluetooth.com. 1.4 Audio Connections - Important Information Merlins Wand has a 2.5 mm audio stereo jack for plugging in headsets. Headsets need to have a 2.5 mm plug with the following pinout:
1) Microphone (signal from headset; bias power of 2.5 V and maximum 1 mA provided by Merlin's Wand on the same pin) 2) Speaker (signal to headset; speaker impedance needs to be
>16 Ohm) 3) Ground The following headsets have been successfully tested with Merlins Wand:
RadioShack 43-1957 Super Lightweight Hands-Free Headset GN Netcom GNX Mobile M200 Motorola Retractable Hands-Free Headset Model # 98196G Belkin Universal 2.5 mm Personal Hands-Free Kit F8V920-PL Coby CV-M20 Earphone with Built-In Microphone Plantronics CHS122N Hands-Free Headset Plantronics M110 Headset for Cordless and Mobile Phones 4 CATC MERLINS WAND 1.22 Users Manual 1.5 Limitations CHAPTER 1 Overview The only Inquiry Access Code (IAC) supported at inquiry and inquiry scan is the General Inquiry Access Code (GIAC) The Scan_Enable parameter value of 0x01 (inquiry scan enabled and page disabled) is not supported Page scan intervals and inquiry scan intervals other than 1.28s are not supported Page scan windows and inquiry scan windows other than 11.25ms are not supported Optional page scan modes are not supported More than one SCO connection at a time is not supported 5 CATC MERLINS WAND 1.22 Users Manual 1.6 Specifications CHAPTER 1 Overview The following specifications describe a Merlins Wand System. Package Dimensions:
Connectors:
Weight:
3.4 x 2.6 x 1 inches
(8.6 x 6.6 x 2.54 centimeters) Host connection (USB, type B) Audio connection (2.5 millimeter audio stereo jack) 3.0 oz. (84 g) Environmental Conditions Operating Range:
Storage Range:
Humidity:
0 to 55 C (32 to 131 F)
-20 to 80 C (-4 to 176 F) 10 to 90%, non-condensing Host Compatibility Works with any PC equipped with a functioning USB port and a Microsoft Windows 98 SE, Windows Me, Windows 2000, or Windows XP operating system. Hardware Interfaces Standard USB Interface -- connects to the host computer 2.4 GHz (ISM band) External Antenna. 2.5 mm audio stereo jack Product Warranty CATC offers a one-year limited warranty on its products. 6 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started 2. Getting Started This chapter describes how to install Merlins Wand and its software. Both install easily in just a few minutes. The Merlins Wand software can be installed on most Windows-based personal computer systems. 2.1 System Requirements The following is the recommended configuration for the computer that runs the Merlins Wand application and is connected to the Merlins Wand hardware unit. Operating system: Microsoft Windows 98 SE, Windows 2000, Windows Me, or Windows XP operating system. Occasionally, after unplugging the Merlin's Wand hardware on a Windows 2000 system, subsequent attempts to plug in the device cause the computer to recognize the unit as a USB device rather than as Merlin's Wand. If this occurs, you will need to restart the computer so that it will recognize the device properly. To avoid the problem, upgrade to the latest Windows 2000 service pack available from Microsoft. Required setup: Microsoft Internet Explorer 5 or later must be installed. Processor: For optimum performance, use processors of the Intel Pentium III or Pentium 4 family, the AMD Athlon or Duron family, or other compatible processors with clock speed of 500mHz or higher. Must have, as a minimum, a processor from the Intel Pentium II or Celeron family, AMD-K6 family, or equivalent with clock speed of 300mHz. Memory: Minimum of 64 MB of RAM is recommended; more memory generally improves responsiveness. Hard disk: Minimum 20 GB hard disk is required for installation. Additional disk space is needed for storing user-generated script files and log files that are saved by the user. Display: Resolution of 1024 x 768 with at least 16-bit color is recommended (resolution of 800 x 600 with 16-bit color is a minimum). Connectivity: A USB interface is required to connect the computer to the Merlins Wand hardware unit. 7 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started 2.2 Setting Up Merlins Wand The Merlins Wand hardware can be set up using the installation CD-ROM or from installation files downloaded from the CATC website. Step 1 Attach the external antenna to the Merlins Wand hardware unit by screwing it onto the connector labelled ANT. Step 2 Plug one end of the USB cable into the USB port on the Merlins Wand hardware, and plug the other end of the USB cable into a USB port on the host computer. Windows should automatically detect the Merlins Wand hardware and open the Windows Hardware Wizard to install Merlins Wand. If the installation doesnt finish automatically, proceed to Step 3. Step 3 Follow the Hardware Wizards on-screen instructions to complete the installation. If the wizard prompts you for driver information, insert the Merlins Wand installation CD-ROM and direct the wizard to the directory
<drive>:\software\MerlinWand122. Substitute the drive letter of the CD-ROM drive for <drive>. For example, if the CD-ROM drive is drive D, navigate to D:\software\MerlinWand122. Note: If you are using installation files downloaded from the CATC website, you will need to direct the wizard to the Disk 1 directory of the installation files so that it can locate the driver. 2.3 Installing the Software and Starting the Program The Merlins Wand software can be installed from the installation CD-ROM or from installation files downloaded from the CATC website. Install from CD-ROM Step 1 Insert the Merlins Wand installation CD-ROM into the CD-ROM drive of the computer that will be connected to the Merlins Wand hardware. The autorun program should start automatically. If it doesnt start, use Windows Explorer or My Computer to navigate to the CD-ROM drive directory and double-click the file autorun.exe, and proceed to Step 2. If it still doesnt start, navigate to the \software\MerlinWand122 directory on the CD-ROM, double-click the file Setup.exe, and proceed to Step 3. Step 2 Choose Install Software to start the setup program. Step 3 Follow the on-screen instructions to complete the 8 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started installation. Install from installation download Step 1 Select Start > Run... from the Windows taskbar and click the Browse button, then navigate to the Disk 1 directory of the Merlins Wand installation download. Select the file Setup.exe and click Open. Step 2 Follow the on-screen instructions to complete the installation. Start the program Once the software has been installed, be sure that the Merlins Wand hardware is connected to the PC via the USB cable before starting the Merlins Wand application. Otherwise, the application will provide a warning message telling you that the Wand could not be found. To start the application, select Start > Programs > CATC > CATC Merlins Wand. Note that this is the default location for the Merlins Wand application. If it was installed in a different folder, select that folder from the Programs menu. 2.4 Displaying the On-Screen Help Access the on-screen Help included with the Merlins Wand application by selecting Help > Help... from the menu bar. 9 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started 2.5 Application Layout The Merlins Wand window is made up of the following:
The Main window, where the primary tools are run: Bluetooth Wizard, Command Generator, and Script Manager. Bluetooth Wizard -- A simple, easy-to-use tool that guides you through the process of establishing connections and generating traffic between Merlins Wand and other Bluetooth wireless technology devices. Command Generator -- A tool that allows Bluetooth commands to be issued in any chosen sequence. If Command Generator isn't enabled on your Merlins Wand system, a License Key must be obtained from CATC before it can be used. Script Manager -- A notepad-like tool for writing and launching scripts that cause Merlins Wand to generate traffic. This tool is an optional feature. If Script Manager isn't enabled on your Merlins Wand system, a License Key must be obtained from CATC before it can be used. 10 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started Note: When switching between Bluetooth Wizard, Command Generator and Script Manager, all connections that have been established between Merlins Wand and another Bluetooth device should be closed. However, expert users may choose to leave the connections open. If a connection is left open and you attempt to switch tools, Merlins Wand will prompt you to close the connections. Choosing Disconnect All will close the connections. Choosing Cancel will leave the connections open, but some commands might not work properly in the other tool. When switching to Bluetooth Wizard, any open connections must be closed. The Device Status window is on the left side of the interface. It contains three tabs: Device List, Piconet, and Merlins Wand Info. Device List - Displays a list of devices that Merlins Wand has discovered. It also contains information about the devices found, such as the Bluetooth address, the state, the role, the class, and the devices local name. This window is open by default. These symbols in the list indicate a devices state: C = Connected; i = In Range. Right-clicking on a listed device opens the Device List Pop-Up Menu. The menu presents the following options: Connect, Add Audio Connection, Get Device Information, Delete, and Disconnect All. For details on using the Pop-Up Menu, see Chapter 6, Device Search and Device List Pop-Up Menu, on page 63. Piconet -
Displays a hierarchical list of all connections between Merlins Wand and other devices. At the top of the list is the address of the connected device; below it are the various channels established between Merlins Wand and the device. Symbols: C = Connection; H = HCI ACL; S = HCI SCO;
L = L2CAP; R = RFCOMM; O = OBEX. 11 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started Merlins Wand Info - Displays details about Merlins Wand. At the bottom of the interface is the Logs window, which contains tabs for the Event Log and the Script Log:
Event Log - Maintains a log of the commands issued by Merlins Wand and the events that ensue, such as a reply by another device. Script Log - Maintains a record of the commands issued by Script Manager and the events resulting from these commands. If line numbers are referenced in the Script Log, double-clicking on the line number will move the cursor to that line in the Script Manager window. 2.6 Menus The menu bar at the top of the application window contains the following menus of pull-down commands:
Table 1: Menu Bar Commands File Menu Command New Script Open Script... Close Script Save Script Function Creates a new script file Opens a script file Closes a script file Saves a script file 12 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started Table 1: Menu Bar Commands (Continued) Save Script As... Print Setup... Print Script... Exit Edit Menu Command Undo Cut Copy Paste Select All Find... Find Next Replace... View Menu Command Merlins Wand Toolbar Merlin Analyzer Toolbar Device Status Logs Status Bar Log Menu Command Copy Selected Log Text Select All Log Text Clear Log Window Save Log As... Print Log... Tools Menu Command Device Search Bluetooth Wizard Command Generator Script Manager Saves a script file with a specified name Sets up the current or a new printer Prints a script file Exits the Merlin's Wand program Function Undoes last change Cuts text Copies text Pastes copied or cut text Selects all text Finds specified string Repeats last find action Searches for a string and replaces it with a new string Function Shows or hides the Merlin's Wand toolbar Shows or hides the Merlin Analyzer toolbar Shows or hides the Device Status window Shows or hides the Logs window Shows or hides the status bar Function Copies selected log text to the clipboard Selects all log text in the open log window Clears all text from the open log window Saves log file to new name and/or directory Prints all text from the open log window Function Opens the Device Search dialog box Opens Bluetooth Wizard Opens Command Generator Opens Script Manager 13 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started Table 1: Menu Bar Commands (Continued) Data Transfer Manager Opens Data Transfer Manager Help Menu Command Help... Update License... Display License Information... About Merlins Wand Function Displays online Help Opens the Update License dialog, which is used to install License Keys. License Keys must be obtained from CATC. Displays maintenance expiration and features data for Merlin's Wand. Displays version information about Merlin's Wand. 2.7 Toolbars There are two toolbars in the Merlins Wand user interface: Merlins Wand toolbar and Merlin Analyzer toolbar. The Toolbar buttons provide access to frequently-used program functions. Tool tips describe icon functionality as the mouse pointer is moved over an item. Merlins Wand Toolbar Device Search Opens Device Search dialog Bluetooth Wizard Opens Bluetooth Wizard Command Generator Opens Command Generator Script Manager Opens Script Manager Data Transfer Manager Opens Data Transfer Manager dialog 14 CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started Merlin Bluetooth Analyzer Toolbar Connect/Disconnect Merlin Bluetooth Analyzer Connects to or disconnects from Merlin Bluetooth Analyzer Set Merlin Recording Options Displays the Open dialog to choose the Recording Options file for Merlin Bluetooth Analyzer Set Merlin Display Options Displays the Open dialog to choose the Display Options file for Merlin Bluetooth Analyzer Start Recording Starts a Merlin Bluetooth Analyzer recording session Stop Recording Stops a Merlin Bluetooth Analyzer recording session Set Merlin Encryption Options Opens the Encryption Setup window 2.8 Tool Tips For most of the buttons and menus, tool tips provide useful information. To display a tool tip, position the mouse pointer over an item. If a tooltip exists for the item, it will pop up in a moment. 2.9 Merlins Wand Keyboard Shortcuts Several frequently-used operations are bound to keyboard shortcuts. Table 2: Keyboard Shortcuts Key Combination Operation Key Combination Ctrl + A Ctrl + C Ctrl + F Ctrl + G Ctrl + H Operation Select all Copy Find Go to Replace Ctrl + V Ctrl + W Ctrl + X Ctrl + Z Home Ctrl + I Indent End Ctrl + N New script Ctrl + Home 15 Paste Close script Cut Undo Jump to first character of line Jump to last character of line Jump to first character of file CATC MERLINS WAND 1.22 Users Manual CHAPTER 2 Getting Started Table 2: Keyboard Shortcuts (Continued) Key Combination Ctrl + O Operation Open script Key Combination Ctrl + End Ctrl + P Print script... Ctrl + Backspace Ctrl + R Ctrl + S Run script Save script F3 Alt + F4 Operation Jump to last character of file Delete previous word Find next Shut down Merlins Wand application 2.10 License Keys License Keys are necessary to enable software maintenance, and may be necessary to use the Command Generator and Script Manager tools. If these tools are not enabled, a message will appear if you attempt to access them, stating that a License Key is necessary in order to use them. License Keys must be obtained from CATC. Follow these steps to install License Keys:
Step 1 Select Help > Update License from the menu bar. The Update License dialog will come up. Step 2 Enter the path and filename for the License Key or use the Browse button to navigate to the directory that contains the License Key. Select the .lic file, and then click Update Device. 2.11 License Information Licensing information for Merlin's Wand may be viewed by selecting Help > Display License Information... from the menu bar. The License Information window will open, displaying the maintenance expiration and features data for Merlin's Wand. 16 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard 3. Bluetooth Wizard Once Merlins Wand is installed and running, it is ready to generate traffic. The easiest way to generate traffic is to use Bluetooth Wizard, a point-and-click tool for creating connections and transferring data between Merlin's Wand and other Bluetooth wireless technology devices. This tool requires little Bluetooth experience and allows the user to generate Bluetooth traffic without having to execute specific Bluetooth commands. Bluetooth Wizard manages the entire traffic generation process. Merely follow the on-screen instructions and Merlin's Wand will execute the Bluetooth commands needed to make the connection. 3.1 Starting Bluetooth Wizard Step 1 Click the Bluetooth Wizard icon Bluetooth Wizard from the menu. or select Tools >
Bluetooth Wizard will open in the Main Window, displaying the following screen:
When you start Bluetooth Wizard, Merlins Wand gives you the choice of connecting to a device or emulating a device:
Emulate a Device -- Choose this option to configure Merlin's Wand to emulate a Bluetooth wireless device. Merlin's Wand can emulate two types of devices: Bluetooth headsets that comply with the Headset Audio Gateway profile and devices that comply with the Object Push profile (i.e., devices that are capable of transferring files). 17 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Connect to Device -- Choose this option to configure Merlin's Wand to seek out other Bluetooth devices, connect to one of them, and possibly exchange data with that device. Merlin's Wand can connect to and exchange data with two types of devices: Bluetooth wireless headsets that support the Headset Audio Gateway profile and devices that comply with the Object Push profile. 3.2 Connect to a Device: Headset The following steps show how to configure Merlins Wand to connect to and transfer audio with a Bluetooth headset using the Headset profile. An audio headset is connected to Merlins Wand in order to transmit audio between Merlins Wand and a Bluetooth headset. A second Merlins Wand with an audio headset attached can also be used. Step 1 Turn on the Bluetooth headset that Merlins Wand will be connecting to over the air (i.e., the target device). Step 2 Attach a headset to the audio connector on Merlins Wand. Step 3 Click the Bluetooth Wizard icon on the toolbar or select Tools > Bluetooth Wizard from the Menu Bar. The Bluetooth Wizard opening screen opens in the Main Window:
Step 4 Click the button marked Connect to Device. 18 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Clicking this button causes Merlins Wand to perform a General Inquiry and collect information on local devices. The Select Device screen opens, displaying the devices that are found. Step 5 From the list, select the device address to which you want Merlins Wand to connect, and then click Next. 19 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Merlin's Wand will query the selected device to determine its profile. When the query is complete, the Select Profile screen will open and display a list of profiles found. Step 6 Select Headset Gateway, then click Next. The Connection Status screen will open, indicating that Merlin's Wand is not connected to the device.:
20 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Step 7 Select Connect. The Connection Status screen will change to show that Merlin's Wand has established an RFCOMM connection with the device. Merlins Wand will automatically ring the target device and wait for an answer. Pressing the Ring button will cause Merlins Wand to ring the device again. Note The Speaker and Microphone Volume levels can be adjusted by moving the sliders up or down. The level is indicated by a number, from 0 to 15, to the left of each slider. Note If you cannot establish a connection, you can re-attempt the connection by either pressing Back and re-running the previous two steps, or by pressing the Connect button again. Step 8 When the target device answers, Merlins Wand will 21 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard establish an SCO connection with it. Step 9
(Optional) Click the Disconnect button on the Connection Status screen to close the connection. The connection between Merlin's Wand and the device will terminate, and the Connect button will again be available. Selecting Connect will reestablish the connection. 3.3 Connect to a Device: Headset Audio Gateway The following steps show how to configure Merlin's Wand to connect to and transfer audio with a Bluetooth headset using the Headset Audio Gateway profile. An audio headset is connected to Merlins Wand in order to transmit audio between Merlins Wand and a Bluetooth headset. A second Merlins Wand with an audio headset attached can also be used. Step 1 Turn on the Bluetooth headset that Merlins Wand will be connecting to over the air (i.e., the target device). Step 2 Attach a headset to the audio connector on Merlins Wand. Step 3 Click the Bluetooth Wizard icon on the toolbar or select Tools > Bluetooth Wizard from the Menu Bar. 22 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard The Bluetooth Wizard opening screen opens in the Main Window:
Step 4 Click the button marked Connect to Device. Clicking this button causes Merlins Wand to perform a General Inquiry and collect information on local devices. The Select Device screen opens, displaying the devices that are found. 23 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Note the messages that appear in the Event Log. These messages provide details about the actions and responses taken in each step. Step 5 From the list, select the device address to which you want Merlins Wand to connect, and then click Next. Merlin's Wand will query the selected device to determine its profile. When the query is complete, the Select Profile screen will open and display a list of profiles found. Step 6 Select Headset Audio Gateway, then click Next. 24 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard The Connection Status screen will open, indicating that Merlin's Wand is not connected to the device.:
Step 7 Select Connect. The Connection Status screen will change to show that Merlin's Wand is connected to the device. 25 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard The Speaker and Microphone Volume levels can be adjusted by moving the sliders up or down. The level is indicated by a number, from 0 to 15, to the left of each slider. Note If you cannot establish a connection, you can re-attempt the connection by either pressing Back and re-running the previous two steps, or by pressing the Connect button again. Step 8 To verify that Merlin's Wand and the Bluetooth device are successfully connected, speak into the microphone on one device and listen for audio on the other. At this point, the audio signal should transfer to the headset. Listen to the headset to see if the data transfer is successful. Step 9
(Optional) Click the Disconnect button on the Connection Status screen to close the connection. The connection between Merlin's Wand and the device will terminate, and the Connect button will again be available. Selecting Connect will reestablish the connection. 26 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard 3.4 Connect to a Device: Object Push Merlin's Wand can be configured to transfer files to a Bluetooth wireless device that complies with the Object Push profile. This section shows how to configure Merlin's Wand to connect and transfer files to a Bluetooth device that supports Object Push. Step 1 Turn on the target device (the device that will receive the data). The target device will act as the slave unit in this example. Step 2 Start Bluetooth Wizard by clicking the Bluetooth Wizard or by selecting Tools > Bluetooth Wizard from the icon menu bar. Bluetooth Wizard will open in the Main Window. Step 3 Click the Connect to Device button on the Bluetooth Wizard opening screen. Merlin's Wand will perform a General Inquiry and collect information on local Bluetooth devices. When the search is complete, the Select Device screen will appear with a list of available devices. For details about the actions and responses in each step of the Inquiry, view the Event Log. Step 4 Select the device address to which you want Merlins Wand 27 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard to connect, and then double-click or press Next. Merlin's Wand will query the selected device to determine its profile. When the query is complete, the Select Profile screen will open and display a list of profiles found. Step 5 Select Object Push from the list of displayed profiles, and then double-click or press Next. The Select Data for Transfer screen will open:
28 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Step 6 On the Select Data for Transfer screen, there are options to transfer a file or to transfer text. To transfer a file: Select the radio button next to Transfer this file. Type in a filename or locate the file by clicking the browse button to access the Open dialog. By default, the filename in the Send data to the following file on the receiving device box matches the name of the file to be transferred. If desired, enter a different filename in that box. When the desired file and target file's name have been entered, proceed to Step 7. To transfer text: Select the radio button next to Transfer this text. Enter text in the text box. By default, the filename in the Send data to the following file on the receiving device box is mw001.txt. If desired, enter a different target filename. When the desired text and target file's name have been entered, proceed to Step 7. Step 7 Click Next. The Transferring File screen will appear. First, a connection with the remote device will be established, then data will begin transferring. A progress bar will show what percentage of the transfer has gone through. Click Stop Transfer to abort a transfer at any time. 29 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard When the transfer is complete, Merlins Wand will disconnect from the target device:
At this point, you can click Back to transfer a different file, click Retransmit to send the file again, or click Restart Wizard to start a new Bluetooth Wizard session. 3.5 Device Emulation: Headset Merlin's Wand can be configured to emulate a wireless device that conforms to the Bluetooth Headset profile. The following steps show how to set up Merlin's Wand as a Headset device and connect to it with a remote Bluetooth headset. Step 1 Start Bluetooth Wizard by clicking its icon or by selecting Tools > Bluetooth Wizard from the toolbar. The Bluetooth Wizard screen will open in the Main Window. Step 2 Click Emulate Device. 30 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard The Select Profile screen will open. Step 3 Select Headset, then press Next. The Emulation Status screen will open, indicating that Merlin's Wand has been configured to emulate a device that supports the Headset profile and is awaiting connection from a device. Step 4 Direct a remote Bluetooth device to connect to Merlin's Wand. 31 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Once the connection is established, the Emulation Status screen will indicate that Merlin's Wand has an RFCOMM connection to the device. Step 5 Click the Answer button to make an SCO connection with the remote device. If the connection attempt is succesful, the screen will change to indicate that an SCO connection has been established. 32 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Step 6
(Optional) Click the Hang Up button to close the connection. The connection between Merlin's Wand and the device will terminate. 3.6 Device Emulation: Headset Audio Gateway Merlin's Wand can be configured to emulate a wireless device that conforms to the Bluetooth Headset Audio Gateway profile. The following steps show how to set up Merlin's Wand as a Headset Audio Gateway device and connect to it with a remote Bluetooth headset. Step 1 Start Bluetooth Wizard by clicking its icon or by selecting Tools > Bluetooth Wizard from the toolbar. The Bluetooth Wizard screen will open in the Main Window. Step 2 Click Emulate Device. The Select Profile screen will open. Step 3 Select Headset Audio Gateway, then press Next. 33 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard The Emulation Status screen will open, indicating that Merlin's Wand has been configured to emulate a device that supports the Headset Audio Gateway profile and is awaiting connection from a device. Step 4 Direct a remote Bluetooth device to connect to Merlin's Wand. Once the connection is established, the Emulation Status screen will indicate that Merlin's Wand is currently connected to the device. 34 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard Step 5 To verify that Merlin's Wand and the remote device are successfully connected, speak into the microphone on one device and listen for audio on the other. 3.7 Device Emulation: Object Push Merlin's Wand can emulate the file transfer capabilities of wireless devices that support the Object Push profile through the Object Push option. Object Push emulation allows other devices to transfer files to Merlin's Wand. Step 1 Start Bluetooth Wizard. Step 2 Click the Emulate Device button on the Bluetooth Wizard opening screen. The Select Profile screen will open. Step 3 Select Object Push, then press Next. 35 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard The Emulation Status screen will open, indicating that Merlin's Wand has been configured to emulate a Bluetooth device that supports the Object Push profile and is awaiting connection from a device. It is now ready to receive files. If desired, the folder in which transferred files are stored can be changed. To change it, click the Change button and select a new directory in the Browse for Folder dialog. Step 4 Initiate file transfer from the Bluetooth device. Note: If the Bluetooth device is another Merlin's Wand, follow the steps in Connect to a Device: Object Push on page 27. 36 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard The Emulation Status screen will show the file transfer progress:
When the transfer is complete, the Emulation Status screen will show that Merlin's Wand is waiting for a connection after having successfully received the file. 37 CATC MERLINS WAND 1.22 Users Manual CHAPTER 3 Bluetooth Wizard 3.8 Restarting the Wizard When working within Bluetooth Wizard, a new session may be started at any time. Step 1 Click the Restart Wizard button on any screen. If Merlin's Wand is currently emulating a connected device, the connection will be broken, and Bluetooth Wizard will return to the default Bluetooth Wizard screen. If Merlin's Wand is currently connected to a device, a dialog box will ask if the connection should be terminated. Clicking the Yes button will cause the connection to be broken, and Bluetooth Wizard will return to the default Bluetooth Wizard screen. Clicking the No button will cancel the Restart Wizard request. 38 CATC MERLINS WAND 1.22 Users Manual CHAPTER 4 Command Generator 4. Command Generator The Command Generator is a tool in Merlins Wand that presents a menu of protocol commands so that you can select and execute any command in virtually any sequence. Command Generator thus gives maximum control over the traffic generation process. Command Generator requires that you build connections from the Baseband level on up. This means that to establish an OBEX connection, for example, you will need to first start with Baseband and work your way up the protocol stack. You cannot simply start at a higher protocol. The utility displays a window with tabs for these protocols: HCI (which induces Baseband, LMP and Module-Specific Commands), L2CAP, SDP, RFCOMM, TCS, and OBEX. Clicking a tab or a name in the protocol stack graphic opens a window and presents a menu of commands for that protocol. 4.1 Layout of the Command Generator The Command Generator utility is composed of the following:
Tabs -- There is a tab for each of six protocols: HCI, L2CAP, SDP, RFCOMM, TCS, and OBEX. Clicking a tab displays the Command Menu for the chosen protocol. Command Menus -- A list of commands is provided for each protocol. 39 CATC MERLINS WAND 1.22 Users Manual CHAPTER 4 Command Generator Parameters Combo Boxes -- Parameters can be entered via the six combo boxes. One or more of the boxes may be activated, depending on which command is currently selected in the Command Menu. Parameters may either be typed into the box or chosen from a pull-down list within the box. Execute -- Pressing the Execute button Wand to run the selected command. will cause Merlin's Command Generator Tips --
Detailed tips for each command are accessible by positioning the mouse over the question mark detailed information about the selected command will appear. icon. A pop-up window that contains Command Description Box -- A short description will display in the Command Description Box when a command is selected from a Command Menu. Protocol Stack Graphic -- At the bottom of Command Generator is the Protocol Stack Graphic, which illustrates the layers that make up the Bluetooth protocol stack. The protocols in the graphic are also clickable buttons that can be used to access the command menus for each protocol. HCI Customized List Button -- The HCI tab has an additional button to the left of the Execute button. It provides access to an interface that allows the user to customize the list of commands displayed in the HCI command menu. 4.2 Using Command Generator Note: If Command Generator isnt enabled on your Merlins Wand system, you will need to obtain a License Key from CATC before you can use it. See License Keys on page 16 for details. To execute commands with Command Generator:
Step 1 Click the Command Generator button on the toolbar or select the command Tools > Command Generator from the menu bar. The Command Generator utility will open. 40 CATC MERLINS WAND 1.22 Users Manual CHAPTER 4 Command Generator Step 2 Choose a protocol to work with by clicking one of the five tabs or a layer in the Protocol Stack Graphic. The list of available commands for the chosen protocol will display in the Command Menu. Note: The HCI tab is displayed by default. Step 3 Select a command from the Command Menu. A description of the command will display in the Command Description Box. If the selected command is not supported, the message in the Command Description Box will read Not supported. Step 4 Enter parameters, if required, in the Parameters Combo Boxes. Parameter boxes will be activated as appropriate for the command, with the parameter name(s) appearing to the right of the box(es). Data can be typed directly into the Parameters Combo Boxes, and some of the boxes may offer drop-down lists from which to select the appropriate parameter. Note: Numeric values should be entered as hexadecimal unless otherwise specified. Step 5 Click the Execute button to run the command. Note: While Command Generator offers maximum control over Merlin's Wand, there are times when command choices may be limited. Some lower-level connections may prevent access to commands for higher-level protocols. For example, if an L2CAP connection has been established between Merlin's Wand and a device, it is not possible to work with OBEX commands in Command Generator. Merlin's Wand will display a message to indicate that L2CAP connections must be closed before working with OBEX commands. Once the L2CAP connection is closed, the OBEX commands will be accessible. Customizing the List of HCI Commands The list of commands in the HCI command menu in Command Generator may be customized to display only certain commands. Since there are over 100 commands available in the HCI menu, this feature is a handy way to eliminate scrolling through a lengthy list to find commands. 41 CATC MERLINS WAND 1.22 Users Manual CHAPTER 4 Command Generator Clicking the HCI Customized List button
, which is located to the left of the Execute button in Command Generator, will open the Command Group interface. To remove commands from the customized HCI command list, select the radio button beside one of the groups listed in the Command groups section of the interface, then press the Remove button
. The selected command(s) will move into the Other HCI commands list. To add commands to the customized list, select the radio button next to the group of commands that should be moved, then press the Add button
. The selected command(s) will be moved from Other HCI commands to the customized HCI command list. 4.3 Tables of Available Commands The following tables summarize the commands in Command Generator. For detailed descriptions of the commands, see Appendix A: Command Generator Command Descriptions, on page 91. Note N/A means Not Applicable. This indicates that the specified command does not have a parameter. HCI Commands Link Control Commands Two sections of Link Control Commands are presented. The first section lists commands that are supported by Merlins Wand. The second section presents commands that are not supported. 42 CHAPTER 4 Command Generator CATC MERLINS WAND 1.22 Users Manual Supported Commands Accept_Connection_Request Add_SCO_Connection Authentication_Requested Change_Connection_Link_Key Change_Connection_Packet_Type Create_Connection Disconnect Exit_Periodic_Inquiry_Mode Inquiry Inquiry_Cancel Periodic_Inquiry_Mode PIN_Code_Request_Negative_Reply PIN_Code_Request_Reply Read_Clock_Offset Read_Remote_Supported_Features Read_Remote_Version_Information Reject_Connection_Request Remote_Name_Request Set_Connection_Encryption Not supported Commands Link_Key_Request_Negative_Reply Link_Key_Request_Reply Master_Link_Key Parameters N/A HCI_Handle Packet Type HCI_Handle HCI_Handle HCI_Handle Packet_Type BD_ADDR HCI_Handle N/A Inquiry_Length Num_Responses N/A Max Period Length Min Period Length Inquiry Length Num of Responses BD_ADDR PIN Code BD_ADDR HCI_Handle HCI_Handle HCI_Handle N/A BD ADDR Page Scan Rep Mode Page Scan Mode Clock Offset HCI_Handle Encryption_Enable 43 CHAPTER 4 Command Generator CATC MERLINS WAND 1.22 Users Manual Link Policy Commands Supported Commands Exit_Park_Mode Exit_Sniff_Mode Hold_Mode Park_Mode QoS_Setup Read_Link_Policy_Settings Role_Discovery Sniff_Mode Switch_Role Write_Link_Policy_Settings Not supported Parameters HCI_Handle HCI_Handle HCI_Handle Max_Interval Min_Interval HCI_Handle Beacon_Max_Interval Beacon_Min_Interval HCI_Handle ServiceType TokenRate PeakBandwidth Latency DelayVariation HCI_Handle HCI_Handle HCI_Handle Max_Interval Min_Interval Attempt Timeout BD_ADDR HCI_Handle Link_Policy_Settings All Link Policy commands are supported in Command Generator. Host Controller & Baseband Commands Supported Commands Change_Local_Name Delete_Stored_Link_Key Host_Buffer_Size Parameters Name BD_ADDR Delete_All_Flag ACL_Data_Length SCO_Data_Length Total_Num_ACL Total_Num_SCO Read_Authentication_Enable N/A 44 CATC MERLINS WAND 1.22 Users Manual CHAPTER 4 Command Generator Commands Read_Class_of_Device Read_Connection_Accept_Timeout Read_Current_IAC_LAP Read_Encryption_Mode Read_Local_Name Parameters N/A N/A N/A N/A N/A Read_Link_Supervision_Timeout HCI_Handle Read_Number_Of_Supported_IAC Read_Page_Scan_Mode Read_Page_Scan_Period_Mode Read_Page_Timeout Read_PIN_Type Read_Scan_Enable Read_SCO_Flow_Control_Enable Read_Stored_Link_Key Read_Voice_Setting Reset Set_Event_Filter Set_Event_Mask N/A N/A N/A N/A N/A N/A N/A BD_ADDR Read_All_Flag N/A N/A FilterType FilterConditionType Condition Event_Mask Write_Authentication_Enable Authentication_Enable Write_Class_of_Device Write_Connection_Accept_Timeout Write_Current_IAC_LAP CoD Timeout IAC_LAP IAC_LAP IAC_LAP IAC_LAP IAC_LAP IAC_LAP Write_Encryption_Mode Encryption Mode Write_Link_Supervision_Timeout Write_Page_Timeout Write_PIN_Type Write_Scan_Enable Write_Stored_Link_Key Write_Voice_Settings HCI_Handle Timeout Timeout PIN_Type Scan_Enable BD_ADDR Link_Key HCI_Handle Voice_Setting 45 CHAPTER 4 Command Generator CATC MERLINS WAND 1.22 Users Manual Not Supported Commands Create_New_Unit_Key Flush Host_Number_Of_Completed_Packets Read_Automatic_Flush_Timeout Read_Hold_Mode_Activity Read_Inquiry_Scan_Activity Read_Num_Broadcast_Retransmissions Read_Page_Scan_Activity Read_Transmit_Power_Level Set_Host_Controller_To_Host_Flow_Control Write_Automatic_Flush_Timeout Write_Hold_Mode_Activity Write_Inquiry_Scan_Activity Write_Num_Broadcast_Retransmissions Write_Page_Scan_Activity Write_Page_Scan_Mode Write_Page_Scan_Period_Mode Write_SCO_Flow_Control_Enable Informational Commands Supported Commands Read_BD_ADDR Read_Buffer_Size Read_Country_Code Read_Local_Supported_Features Read_Local_Version_Information Not Supported Parameters N/A N/A N/A N/A N/A There are no unsupported Informational commands. Status Commands Supported There are no supported Status commands. 46 CHAPTER 4 Command Generator CATC MERLINS WAND 1.22 Users Manual Not Supported Commands Get_Link_Quality Read_Failed_Contact_Counter Reset_Failed_Contact_Counter Read_RSSI Testing Commands Supported Commands Enable_Device_Under_Test_Mode Read_Loopback_Mode Write_Loopback_Mode Not Supported Parameters N/A N/A Loopback_Mode There are no unsupported Testing commands. CATC-Specific Commands Supported Commands CATC_BER Parameters HCI_Handle Number_Of_Packets BER_Packet_Type Test_Data_Type Test_Data BER_Interval CATC_Change_Headset_Gain CATC_Read_Headset_Gain CATC_Read_Revision_Information CATC_Self_Test Device Gain Device N/A N/A CATC_Write_Country_Code Country_Code Not supported Commands CATC_Enter_Test_Mode CATC_Test_Control 47 CHAPTER 4 Command Generator CATC MERLINS WAND 1.22 Users Manual L2CAP Commands Supported Commands ConfigurationResponse ConfigurationSetup ConnectRequest ConnectResponse DeregisterPsm DisconnectRequest EchoRequest InfoRequest RegisterPsm SendData Not Supported Commands GetRegisteredGroups GroupDestroy GroupRegister SDP Commands Supported Commands AddProfileServiceRecord AddServiceRecord ProfileServiceSearch Parameters Reason ServiceType TokenRate TokenBucketSize PeakBandWidth Latency DelayVariation HCI_Handle PSM Receive MTU Response PSM CID HCI_Handle Data HCI_Handle PSM Receive MTU CID Data Pipe Parameters Profile ServerChannel Filename Record Name Server Channel HCI_Handle Profile 48 CHAPTER 4 Command Generator CATC MERLINS WAND 1.22 Users Manual Commands RequestServiceAttribute RequestServiceSearch RequestServiceSearchAttribute ResetDatabase Not Supported Parameters HCI_Handle ServiceRecordHandle AttributeID AttributeID AttributeID HCI_Handle ServiceClassID ServiceClassID ServiceClassID HCI_Handle ServiceClassID ServiceClassID ServiceClassID N/A All SDP commands in Command Generator are supported. RFCOMM Commands Supported Commands AcceptChannel AcceptPortSettings AdvanceCredit CloseClientChannel CreditFlowEnabled DeregisterServerChannel OpenClientChannel RegisterServerChannel RequestPortSettings RequestPortStatus SendATCommand Parameters Accept Accept
(HCI/DLCI) Credit
(HCI/DLCI)
(HCI/DLCI) ServerChannel HCI_Handle ServerChannel MaxFrameSize Credit N/A
(HCI/DLCI) BaudRate DataFormat FlowControl Xon Xoff
(HCI/DLCI)
(HCI/DLCI) AT_Command 49 CATC MERLINS WAND 1.22 Users Manual CHAPTER 4 Command Generator Commands SendData SendTest SetLineStatus SetModemStatus Not Supported Parameters
(HCI/DLCI) Data Pipe
(HCI/DLCI)
(HCI/DLCI) LineStatus
(HCI/DLCI) ModemSignals Break Length All RFCOMM commands in Command Generator are supported. TCS Commands Supported Commands Register_Intercom_Profile Open_TCS_Channel Start_TCS_Call Disconnect_TCS_Call Send_Info_Message Not Supported Parameters N/A HCI_Handle N/A N/A Phone_Number Current TCS implementation in Merlins Wand supports only the Intercom profile. The Cordless profile that uses TCS is not currently supported by Merlins Wand. OBEX Commands Supported Commands ClientConnect ClientDisconnect ClientGet ClientPut ClientSetPath ServerDeinit ServerInit ServerSetPath Parameters BD_ADDR N/A Object Filename Path Flags N/A N/A Path 50 CATC MERLINS WAND 1.22 Users Manual Not Supported CHAPTER 4 Command Generator There are no unsupported OBEX commands in Command Generator. 51 CATC MERLINS WAND 1.22 Users Manual CHAPTER 4 Command Generator 52 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager 5. Script Manager Script Manager is a tool within Merlins Wand that presents a text editor window for writing and executing scripts. Scripts can be used to automate Bluetooth command sequences, making the testing process more efficient. This chapter introduces the Script Manager interface. There are a number of commands available to you for writing scripts in Merlins Wand. Command descriptions can be found in Appendix C: Merlins Wand Scripting Commands, on page 155. 5.1 Layout of the Script Manager Window The Script Manager utility is composed of the following:
Work Area -- The Work Area is a text editor for writing new scripts or displaying and editing opened scripts. Run Button -- Clicking the Run button saves (if needed) and executes the script that is currently displayed in the Work Area. While the script is running, the label on this button changes to Stop. New Button -- Clicking the New button brings up a new script template in the Work Area, so that a new script may be composed. If a modified script is open when the New button is clicked, Script Manager will ask if it should be saved. Open Button -- Clicking the Open button brings up the Open dialog, so that a script can be loaded into the Work Area. If a modified script is open when the Open button is clicked, Script Manager will ask if it should be saved. 53 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager Save Button -- Clicking the Save button saves the script that is currently open in the Work Area. Go To Button -- Clicking the Go To button opens the Go To dialog box. Here, users may enter a line number to go to a specific part of an open script. Line numbers are displayed on the bottom right of the Merlin's Wand application, on the status bar. Script Name and Path -- The name and path of the script that is currently open in the Work Area are displayed along the top of the Script Manager screen. Script Manager Menu -- Right-clicking within the Work Area brings up the Script Manager menu. All filing and editing commands that can be performed in Script Manager can be accessed via this menu. 5.2 Running Scripts Note: If Script Manager isnt enabled on your Merlins Wand system, you will need to obtain a License Key from CATC before you can use it. See License Keys on page 16 for details. Step 1 Open Script Manager by clicking the Script Manager icon on the toolbar or by selecting Tools > Script Manager from the menu bar. Script Manager will open. Step 2 Open the script by clicking the Open button in the Script Manager window or by selecting File >
Open Script from the menu bar. The Open dialog will appear. 54 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager Step 3 Navigate to the desired file and click Open. The script will display in Script Manager's Work Area. Step 4 Click Run. Script execution will begin, and the label of the Run button will change to Stop. Pressing the Stop button terminates execution of the script. The script's output can be viewed in the Script Log. If line numbers are referenced in the Script Log, double-clicking on the line number will move the cursor to that line in Script Manager. When the script has finished, the Stop button label will change back to Run. 5.3 Writing Scripts Customized scripts can be written directly in Script Manager using Merlins Wand Scripting Commands. This allows for automating sequences of commands. There are over 100 commands available for writing custom test sequences, including basic commands and commands for: pipes, HCI, 55 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager L2CAP, SDP, RFCOMM, OBEX, and Merlin. Detailed descriptions of the commands can be found in Appendix C: Merlins Wand Scripting Commands, on page 155. Step 1 Open Script Manager by clicking the Script Manager icon on the toolbar or by selecting Tools > Script Manager from the menu bar. By default, Script Manager opens an untitled script template in the Work Area for composing a new script. If Script Manager were already open, the Work Area could be cleared by pressing the New button in Script Manager or by selecting File > New Script from the menu bar. Step 2 Write the script in Script Manager's Work Area. Step 3 Save the script via the Save Script As command on the File menu or by clicking the Save button. The Save As dialog will open. Enter a name for the script and save it as a Merlin's Wand Script file (*.script). Step 4 If desired, Close the script by selecting File > Close Script from the menu bar. 5.4 Sample Scripts Two sample scripts have been provided with Merlin's Wand to demonstrate how Script Manager works. Running sample.script will cause Merlin's Wand to attempt to connect to another device. Sample-2.script demonstrates using RFCOMM to wait for and receive data, as well as demonstrating the use of pipes. The default location of the scripts is the directory where the application is installed, which is usually C:\Program Files\CATC\Merlin's Wand. An additional script, Script Controlling Merlin Interface, is included in this section. It shows how to use a script to control the CATC Merlin Bluetooth Analyzer via Merlins Wand. 56 CATC MERLINS WAND 1.22 Users Manual sample.script CHAPTER 5 Script Manager This script demonstrates several common Merlins Wand functions. Main()
Trace("Registering a server channel...\n");
rfChannel = RFRegisterServerChannel();
Trace("Server channel: ", rfChannel, "\n\n");
# Add a profile if we got a server channel if(rfChannel != "Failure")
result = SDPAddProfileServiceRecord(rfChannel,
"ObjectPush");
Trace("SDPAddProfileServiceRecord returned ", result,
"\n");
Trace("Performing inquiry...\n");
Devices = DoInquiry();
Trace(Devices, "\n");
class = GetDeviceClass();
Trace("Device class is: ", class, "\n");
# Set a new device class SetDeviceClass(0x010203);
class = GetDeviceClass();
Trace("Device class is now: ", class, "\n");
# Get the names index = 0;
while(device = Devices[index])
deviceName = GetRemoteDeviceName(device);
Trace("Device ", index, ": ", deviceName, "\n");
index = index + 1;
# Read the current accessible mode Trace("Current accessible mode is: ", HCIReadScanEnable(), "\n");
# Set the accessible mode result = HCIWriteScanEnable("GENERAL_ACCESSIBLE");
Trace("HCIWriteScanEnable returned ", result, "\n");
57 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager
# Read the new accessible mode Trace("Current accessible mode is: ", HCIReadScanEnable(), "\n");
Trace("Connecting to ", Devices[0], "\n");
# Connect to the first device in the list. ACLHandle = Connect(Devices[0]);
Trace("ACL Handle: ", ACLHandle, "\n");
# Get some SDP query information Trace("\nSDP query results:\n");
serverChannel = SDPQueryProfile(Devices[0], "Headset");
Trace("Headset: Server channel is: ", serverChannel,
"\n\n");
# Establish an RFCOMM connection Trace("\nEstablishing RFCOMM connection:\n");
result = RFOpenClientChannel(Devices[0], serverChannel);
Trace("RFCOMM connection: ", result[0], "\n");
DLCI = result[1];
# Send some data over our new RFCOMM connection data = "ATDT5551212";
Trace("Sending ", data, " to ", Devices[0], "...\n");
result = RFSendData(Devices[0], DLCI, data);
Trace("RFSendData returned ", result, "\n\n");
# Close the RFCOMM connection result = RFCloseClientChannel(Devices[0], DLCI);
Trace("RFCOMM disconnection: ", result, "\n");
Trace("\nAttempting to make an SCO connection...\n");
result = HCIAddSCOConnection(Devices[0], ["DM1",
"HV1"]);
Trace("HCIAddSCOConnection returned ", result, "\n");
Trace("\nWaiting 2 seconds...\n");
# Wait for 2 seconds Sleep(2000);
# Close the SCO connection Trace("Close SCO connection: ", HCIRemoveSCOConnection(Devices[0]), "\n");
# Disconnect from the device status = Disconnect(Devices[0]);
58 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager Trace("Disconnect returned: ", status, "\n\n");
Sample-2.script
# Sample2.script
# Demonstrates using RFCOMM to wait for and receive data as well as the use of pipes.
# A Transmit pipe called "SamplePipe" should be created in the Data Transfer Manager
# before the script is run. This pipe should contain a small amount of data that will be sent
# back to the host whenever data is received by the script. Main()
# Do some pipe tests. result = DeletePipe("TestPipe", "receive");
Trace("DeletePipe returned ", result, "\n");
result = OpenPipe("TestPipe", "receive");
Trace("OpenPipe returned ", result, "\n");
# WritePipe only supports receive pipes. result = WritePipe("TestPipe", "This is some data.");
Trace("WritePipe returned ", result, "\n");
result = ClosePipe("TestPipe", "receive");
Trace("ClosePipe returned ", result, "\n");
result = OpenPipe("TestPipe", "receive");
Trace("OpenPipe (2) returned ", result, "\n");
result = ReadPipe("TestPipe", "receive", 100);
Trace("ReadPipe returned ", result, "\n");
#result = ClosePipe("TestPipe", "receive");
#Trace("ClosePipe (2) returned ", result, "\n");
channel = RFRegisterServerChannel();
Trace("Listening on server channel ", channel, "...\n");
result = OpenPipe("DataIn", "receive");
Trace("OpenPipe returned ", result, "\n");
# Wait for a connection status = RFWaitForConnection();
59 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager Trace("RFWaitForConnection returned ", status, "\n");
while(1)
results = RFReceiveData();
Trace("RFReceiveData returned ", results[0], "\n");
if(results[0] != "Success")
ClosePipe("DataIn", "receive");
Trace("Exiting.\n");
return results[0];
Trace("Received ", results[1], " bytes:\n");
Trace(results[2]);
Trace("\n");
result = WritePipe("DataIn", results[2]);
Trace("WritePipe returned ", result, "\n");
# Send some data back from a pipe. result = RFSendDataFromPipe("CONNECTED_DEVICE", channel, "SamplePipe");
Trace("SendData returned ", result, "\n");
Script Controlling Merlin Interface This script demonstrates how to control various Merlin functions via a Merlins Wand script. Main()
result = MerlinStart();
Sleep(2000);
if(result == "Failure") return result;
Trace("Merlin started\n");
MerlinSetRecordingOptions("C:\\Program Files\\CATC\\Merlin\\1.rec");
Trace("MerlinSetRecordingOptions\n");
MerlinSetDisplayOptions("C:\\Program Files\\CATC\\Merlin\\1.opt");
Trace("MerlinSetDisplayOptions\n");
result = MerlinSetEncryptionPIN('000102030405', "1234");
if(result != "Success") 60 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager return result;
Trace("MerlinSetEncryptionPIN\n");
result = MerlinSetEncryptionLinkKey('000102030405',
"123456");
if(result != "Success") return result;
Trace("MerlinSetEncryptionLinkKey\n");
result = MerlinStartRecording();
if(result != "Success") return result;
Trace("MerlinStartRecording\n");
Sleep(10000);
MerlinStopRecording();
Trace("MerlinStopRecording\n");
MerlinResetAllEncryptionOptions();
MerlinStop();
Trace("MerlinStop\n");
61 CATC MERLINS WAND 1.22 Users Manual CHAPTER 5 Script Manager 62 CATC MERLINS WAND 1.22 Users Manual CHAPTER 6 Device Search and Device List Pop-Up Menu 6. Device Search and Device List Pop-Up Menu The Device Search and Device List Pop-Up Menu tools offer shortcut methods for steps that are commonly performed at the beginning of the connection process. They can be used for some commands that would otherwise need to be done in Command Generator. 6.1 Device Search Merlin's Wand can perform an inquiry to find local Bluetooth wireless technology devices via the Device Search tool. Information about the devices that are found are then shown in the Device List. To perform a Device Search:
Step 1 Open the Device Search dialog by clicking the Device Search icon Search from the menu bar. on the toolbar or by selecting Tools > Device The Device Search dialog will open. Device Search presents the following search options:
Search Time -- Sets the duration of the inquiry, in seconds. The default search time is five seconds. Number of Responses -- Sets the maximum number of responses for which data should be collected. The default number of responses is ten. Read Remote Device Name -- Selecting this option will cause Merlin's Wand to collect name information from the remote devices it finds. This option is not selected by default. Note: The reading of names occurs after the search has finished; therefore, processing the entire search will take longer if this option is selected. For example, if the Search Time is set to 5 seconds, and 30 devices are found within 5 seconds, the entire search process will take much longer than 5 seconds because each device will be contacted individually and asked for its name. This could add considerable time to the search, especially if some of the devices found in the search have gone out of range or been turned off. 63 CATC MERLINS WAND 1.22 Users Manual CHAPTER 6 Device Search and Device List Pop-Up Menu Step 2
(Optional) Set the values for Search Time, Number of Responses and Read Remote Device Name. Step 3 Click Do Inquiry. Merlin's Wand will search for devices. Step 4 To see the results of the search, click the Device List tab in the Device Status window. To see the commands and responses from the Inquiry, view the Event Log in the Logs window. 6.2 Device List Pop-Up Menu The Device List Pop-Up Menu presents options for setting up ACL and audio (SCO) connections, displaying remote device information, and terminating connections. The Pop-Up Menu can be accessed by right-clicking on one or more devices in the Device List. It can be used as an alternative to Bluetooth Wizard, Command Generator, and Script Manager for performing some commands. Note: The Device List Pop-Up Menu is not accessible while the Bluetooth Wizard is running. Create an ACL Connection An HCI ACL connection to a remote device can be established via the Device List Pop-Up Menu. 64 CATC MERLINS WAND 1.22 Users Manual CHAPTER 6 Device Search and Device List Pop-Up Menu Note: The following instructions assume that a Device Search has been performed and devices are displayed in the Device List. For information about performing a device search, please see Section 6.1, Device Search, on page 63. Step 1 Open the Pop-Up Menu by right-clicking on the target device in the Device List. The Device List Pop-Up Menu will open. Step 2 Choose Connect from the menu. The status of the target device should change from In Range to Connected in the Device List. The Piconet tab should now indicate that Merlin's Wand has an ACL connection to the target device. Establish an Audio Connection An HCI SCO connection to a device that supports audio connections can be established via the Device List Pop-Up menu. Note: In order to verify that Merlin's Wand and a Bluetooth wireless audio device are successfully connected, a headset will need to be plugged into the audio port on Merlin's Wand. Be sure that the headset is plugged in before initializing the connection between Merlin's Wand and a Bluetooth device. Note: The following instructions assume that a Device Search has been performed and devices are displayed in the Device List. For information about performing a device search, please see Section 6.1, Device Search, on page 63. Step 1 Open the Pop-Up Menu by right-clicking on the target device in the Device List. The Device List Pop-Up Menu will open. Step 2 Choose Connect from the 65 CATC MERLINS WAND 1.22 Users Manual CHAPTER 6 Device Search and Device List Pop-Up Menu menu. The status of the target device should change from In Range to Connected in the Device List. The Piconet tab should now indicate that Merlin's Wand has an ACL connection to the target device. Step 3 Reopen the Pop-Up Menu by right-clicking on the target device in the Device List. The Device List Pop-Up Menu will open. If the remote device supports audio connections and Merlin's Wand is connected to it, then the Add Audio Connection command should be available. Step 4 Select Add Audio Connection from the menu. The status of the target device will not change in the Device List;
however, the Piconet tab should indicate that Merlin's Wand has an SCO connection to the device. Step 5 To verify that Merlin's Wand and the Bluetooth device are successfully connected, speak into the microphone on one device and listen for audio on the other. Display Device Information Note: The following instructions assume that Merlin's Wand is currently connected to a remote device. Step 1 Open the Pop-Up Menu by right-clicking on the target device in the Device List. The Device List Pop-Up Menu will open. 66 CATC MERLINS WAND 1.22 Users Manual CHAPTER 6 Device Search and Device List Pop-Up Menu Step 2 Select Get Device Information. The Supported Services and Protocols window will open. The Service Name, Supported Protocols, and Value for the target device will be displayed in the window. Delete a Device Devices that are not connected may be removed from the Device List via the Device List Pop-Up Menu. This is useful when there are many devices displayed in the Device List -- non-target devices can be deleted from the list, making it easier to navigate. This option can also be used to remove devices that are no longer in range, but are still displayed in the list. Step 1 Open the Pop-Up Menu by right-clicking on one or more devices. The Device List Pop-Up Menu will open. Note: To delete more than one device at a time, either
(a) Select non-consecutive devices by Ctrl + clicking on each device to be deleted, or
(b) Select consecutive devices by Shift + clicking on the first and last devices to be deleted, then right-click on one of the selected devices. Step 2 Select Delete. The device(s) will be removed from the Device List. 67 CATC MERLINS WAND 1.22 Users Manual CHAPTER 6 Device Search and Device List Pop-Up Menu Disconnect All A fast and easy way to terminate all connections that Merlin's Wand has established with remote devices is to use the Disconnect All command on the Device List Pop-Up Menu. Step 1 Open the Pop-Up Menu by right-clicking on a device. Step 2 Select Disconnect All The Existing Connections dialog will open, displaying all pending connections. Step 3 Click the Disconnect All button in the Existing Connections dialog to close the connections, or click Cancel to leave them open. Note: When switching between Bluetooth Wizard, Command Generator and Script Manager, all connections that have been established between Merlin's Wand and another Bluetooth device should be closed. However, expert users may choose to leave the connections open. If a connection is left open and you attempt to switch tools, Merlin's Wand will prompt you to close the connections. Choosing Disconnect All will close the connections. Choosing Cancel will leave the connections open, but some commands might not work properly in the other tool. When switching to Bluetooth Wizard, any open connections must be closed. 68 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes 7. Data Transfer Manager and Data Pipes Data Transfer Manager is a special tool for creating pipes. A pipe is a file or message that has been specially prepared for transmission over an RFCOMM or L2CAP channel. Pipes are necessary with these protocols because RFCOMM and L2CAP only transfer raw data. Pipes are set up to designate the source of the raw data -- either a file or text entered by the user. Data Transfer Manager is designed to work in conjunction with Command Generator and Script Manager. Use Data Transfer Manager to prepare data, then use Command Generator or Script Manager to transfer it. Data Transfer Manager is also used to view any data that is being received by Merlin's Wand over L2CAP or RFCOMM channels. If data is being received, the Data Transfer Manager window will automatically create a Receive Pipe and display the arriving data. Data Transfer Manager contains the following elements:
Data Transmit page -- The Data Transmit page is used to create pipes. Pipes can be created from files or text. For more information on data transmit pipes, see Section 7.1, Creating Data Pipes, on page 69 and Section 7.2, Using Data Pipes, on page 70. Data Receive page -- The Data Receive page is used to view data that has been received by Merlin's Wand. For more information, see Section 7.3, Receive Pipes, on page 72. 7.1 Creating Data Pipes Data Transfer Manager is used to prepare data for transmission over RFCOMM and L2CAP channels. To prepare the data, pipe files are created. Step 1 Open Data Transfer Manager by clicking on the Data Transfer Manager icon
> Data Transfer Manager from the menu bar. on the Toolbar or selecting Tools 69 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes Data Transfer Manager will open, displaying the Data Transmit page. Step 2 Name the pipe by typing a name into the text box labeled Pipe Name. Step 3 To create a pipe from a file:
Select the From file radio button. Type in a filename and path or navigate to the desired file by clicking the browse button bring up the Open dialog. to To create a pipe from text:
Select the From text radio button and type text into the box to its right. Step 4 Click the Create Pipe button. The pipe will be created, and its name, type and length will be displayed in the list at the top of the Data Transmit page. 7.2 Using Data Pipes Data Transfer Manager works in conjunction with Command Generator and Script Manager to provide an easy way to transfer files between Merlin's Wand and a Bluetooth wireless device over an RFCOMM or L2CAP channel. 70 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes Transfer Data Using Command Generator Note: A data pipe needs to be created in Data Transfer Manager before the data can be transferred. See Section 7.1, Creating Data Pipes, on page 69 to learn how to do this. Step 1 Open Command Generator by clicking on the Command Generator icon Command Generator from the menu bar. on the Toolbar or selecting Tools >
Step 2 Establish an RFCOMM or L2CAP connection with the target device. To establish an RFCOMM connection:
(a) Using the Device List pop-up menu, create an ACL connection. To find out how to do this, see Create an ACL Connection on page 64.
(b) In Command Generator, open the RFCOMM tab.
(c) Select OpenClientChannel from the list of commands. Enter the HCI_Handle (this is shown on the Piconet tab) and ServerChannel parameters. The default values for MaxFrameSize and Credit can be used. When the parameter values are all entered, press Execute. The RFCOMM connection will show up in the Piconet. To establish an L2CAP connection:
(a) Using the Device List pop-up menu, create an ACL connection. To find out how to do this, see Create an ACL Connection on page 64.
(b) In Command Generator, open the L2CAP tab.
(c) Select RegisterPsm from the list of commands. Enter the PSM and Receive MTU parameters, then press Execute. Note: RegisterPsm must also be executed for the target device.
(d) Select ConnectRequest from the list of commands. Enter the HCI_Handle, PSM, and Receive MTU parameters, then press Execute. The L2CAP connection will display on the Piconet tab. Step 3 Select SendData from the RFCOMM or L2CAP menu, depending on which type of connection was established in Step 2. The first two Parameters Combo Boxes will become activated, indicating that the (HCI / DLCI) for RFCOMM, or CID for L2CAP, and Data Pipe parameters are required for this command. Step 4 Enter or select the appropriate (HCI / DLCI) or CID channel and Data Pipe name in the Parameters Combo 71 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes Boxes. Step 5 Click the Execute button to send the data pipe. The Event Log will show the transfer of data from Merlin's Wand to the target device. Access Pipes Using Script Manager There are functions available in the scripting API to access pipes. They are:
OpenPipe, ClosePipe, ReadPipe, WritePipe, and DeletePipe. Please see Section C.3, Pipe Commands, on page 160 for more information. For a demonstration of using RFCOMM to wait for and receive a data pipe, see Sample-2.script in Script Manager. Note: A data pipe needs to be created in Data Transfer Manager before the data can be transferred. See Section 7.1, Creating Data Pipes, on page 69 to learn how to do this. 7.3 Receive Pipes Receive pipes are created automatically in the Data Receive page of Data Transfer Manager when Merlin's Wand receives data from an L2CAP or RFCOMM connection. A receive pipe is a pipe that is used to receive data until the connection terminates. At that point, the pipe can be closed, saved to a file, or deleted. Note that unless a receive pipe is closed, any additional data that's received will be put into that pipe, even if the new data represents a different file transfer. To ensure that different files will be put into separate pipes, each pipe should be closed after a connection has completed. This way, a new receive pipe will be created when subsequent data arrives. 72 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes 7.4 Closing Pipes Receive pipes on the Data Receive page of Data Transfer Manager can be closed. Closing a receive pipe prevents additional data from being placed in it. Closing it also allows its contents to be viewed in the bottom window of the Data Receive page. For any pipe that isn't closed, this message will appear in the window: This pipe is open for writing and cannot be viewed. To close a receive pipe:
Step 1 Select the pipe that is to be closed. Step 2 Click Close Pipe. The pipe will be closed, and its contents will be shown in the bottom window. 7.5 Saving Data Pipes Data Transfer Manager can save data pipes that are prepared for transmission as well as data pipes that are received. 73 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes Saving Data Transmit Pipe Lists Step 1
(Optional) Delete all pipes. If pipes are already displayed on the Data Transmit page of Data Transfer Manager, any newly created pipes will be added to the displayed list. To create an entirely new list of pipes, the currently displayed list should be deleted. Note: The default pipe list is automatically loaded into the Data Transmit page when the Merlin's Wand application is opened. If no list has been saved as default, then no list will be loaded. If the application hasn't been shut down since the last time that Data Transfer Manager was used, then the last list that was open in the Data Transmit page will be displayed the next time the tool is opened. Step 2 Create one or more data pipes. Step 3 Click Save Pipe List... to bring up the Save As dialog. Enter a file name and save the list as a Merlin's Wand Pipe File
[*.pipe]. Saving a Default List Step 1 Create one or more data pipes or open a pipe list. Step 2 Click Save List As Default. The list will be saved as default.pipe. That list is loaded into the Data Transmit page when the Merlin's Wand application is opened. However, if the user exits Data Transfer Manager but doesn't exit the application, the last list that was open in the Data Transmit page will be the one displayed when the tool is next accessed. Saving Data Receive Pipes Step 1 Select a pipe in the Data Receive page of Data Transfer manager. Step 2 Click Save Pipe to File. The Save As dialog will come up. Enter a file name, including the file type extension, then click Save. 7.6 Deleting Pipes Note: Deleting pipes removes them from the list displayed in Data Transfer Manager. If the pipes were previously saved in a pipe list file, deleting them in Data Transfer Manager won't delete them from the file. To delete pipes from a pipe list file, first delete the pipes, then save the pipe list. 74 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes To delete a pipe:
Step 1 Select the pipe to be deleted. Step 2 Click Delete Pipe. The pipe will be deleted from the displayed pipe list. To delete all pipes:
Step 1 Click Delete All Pipes. A warning dialog will come up, asking, Are you sure you want to delete all pipes from the list? Click Yes to delete the pipes. All pipes will be cleared from the display. 7.7 Opening Pipe Lists To open a pipe list in the Data Transmit page of Data Transfer Manager:
Step 1 Click Open Pipe List... Note: If pipes are already displayed, a dialog box will ask, Delete current pipes before adding new pipes from pipe list file? Choose Yes to delete the displayed pipes, or click No to leave those pipes displayed. The Open dialog will come up. Step 2 Select a file, then click Open. The selected list will be displayed on the Data Transmit page. 7.8 Renaming Pipes To rename a pipe displayed in the Data Transmit page of Data Transfer Manager:
Step 1 Select the pipe to be renamed. Step 2 Click Rename Pipe... The Rename Pipe dialog will appear. Step 3 Enter a new name for the pipe, then click OK. Note: Renaming a pipe changes its name in Data Transfer Manager. To change a pipe's name in a pipe list file, first rename the pipe, then save the pipe list. 75 CATC MERLINS WAND 1.22 Users Manual CHAPTER 7 Data Transfer Manager and Data Pipes 7.9 Modifying Pipes Existing pipes may be modified on the Data Transmit page of Data Transfer Manager. A pipe created from a file can be modified either by associating it with a different file or by changing it to a text-based pipe. A pipe created from text can be modified either by editing the text or by changing the pipe to a file-based pipe. Note: Modifying pipes changes them in Data Transfer Manager. However, if the pipes were previously saved in a pipe list file, modifying them in Data Transfer Manager won't change them in the saved file. To modify pipes in a pipe list file, first modify the pipes, then save the pipe list. Step 1 Select the pipe that is to be modified. Step 2 To associate a pipe with a different file or change a text-based pipe to a file-based pipe:
With the From file radio button selected, enter a new filename and to path or navigate to the new file by clicking the browse button bring up the Open dialog. Select a new file and click Open. To modify text or change a file-based pipe to a text-based pipe:
With the From text radio button selected, change, add or delete text in the text entry box. Step 3 Click Modify Pipe to implement the changes. 76 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic 8. Using Merlin to Record Merlins Wand Traffic Its possible to control the CATC Merlin Bluetooth Protocol Analyzer via Merlins Wand. The two can be used together to capture real-time test sequence results, as is required by the Bluetooth SIG to provide evidence of product compliance to the specification. Merlin's Wand has built-in functionality for controlling the Merlin protocol analyzer. Through Merlin's Wand, a Bluetooth recording session can be set up on Merlin, even if the Merlin application runs on a remote computer. 8.1 Set Up a Remote Machine If Merlins Wand will be used to run Merlin on a remote machine, DCOM and accessibility properties on the remote machine must be properly configured. The configuration procedures differ slightly for different operating systems. Note: If Merlins Wand will be used only to run Merlin on the same computer that is running Merlins Wand, skip to Connect to Merlin with Merlins Wand on page 81. Windows 98/Me Operating Systems Use this procedure to configure DCOM properties to run a Merlin analyzer remotely on a machine running Windows 98 or Windows Me. All the steps should be performed on the remote machine. Step 1 Open the Merlin application on the remote machine in order to register it with COM, and then close the application. Step 2 Download and install dcom98.exe and dcm95cfg.exe DCOM configuration utilities from Microsoft. They are available via the following links:
http://download.microsoft.com/msdownload/dcom/98/x86/en/dcom98.exe http://download.microsoft.com/msdownload/dcom/98/x86/en/dcm95cfg.exe Step 3 Select Start > Run from the Windows taskbar. The Run dialog will open. Step 4 Enter dcomcnfg in the Open combo box and press OK. The Distributed COM Configuration Properties dialog will open. 77 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic Step 5 On the Applications tab, select Merlin from the list of applications. Step 6 Select the Default Properties tab and make sure that Enable Distributed COM on this computer is checked. Step 7 Select the Default Security tab and make sure that Enable remote connection is checked. Step 8 Click OK. Windows NT/2000 Operating Systems Use this procedure to configure DCOM and accessibility properties to run a Merlin analyzer remotely on a machine running Windows NT 4.0 or Windows 2000. All the steps should be performed on the remote machine. Step 1 Open the Merlin application on the remote machine in order to register it with COM, and then close the application. Step 2 Select Start > Run from the Windows taskbar. The Run dialog will open. Step 3 Enter dcomcnfg in the Open combo box and press OK. The Distributed COM Configuration Properties dialog will open. Step 4 On the Applications tab, select Merlin from the list of applications. Step 5 Click the Properties button. The Merlin Properties dialog will open. Step 6 Go to the Security tab. Step 7 Select the Use custom launch permissions radio button and click the associated Edit... button. The Registry Value Permissions dialog will open. Step 8 Make sure Allow Launch is selected in the Type of Access drop-down list. Step 9 Click Add... The Add Users and Groups dialog will open. Step 10 Select names from the Names list and click Add to include them in the Add Names list. Step 11 When all desired user names have been added, click OK. Step 12 Click OK on each of the three dialogs that are still open. 78 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic Step 13 For Windows NT:
(a) Select Start > Settings > Control Panel on the Windows taskbar. The Control Panel window will open.
(b) Double-click on Services. The Services dialog will open.
(c) Select Remote Procedure Call (RPC) Locator and select Action >
Properties from the menu bar. The Remote Procedure Call (RPC) Locator Properties dialog will open.
(d) Click Start on the General tab, then click OK. The status for Remote Procedure Call (RPC) Locator should now be set to Started in the Services dialog.
(e) Select Remote Procedure Call (RPC) Service and select Action >
Properties from the menu bar. The Remote Procedure Call (RPC) Service Properties dialog will open.
(f) Click Start on the General tab, then click OK. The status for Remote Procedure Call (RPC) Service should now be set to Started in the Services dialog. For Windows 2000:
(a) Select Start > Settings > Control Panel on the Windows taskbar. The Control Panel window will open.
(b) Double-click on Administrative Tools. The Administrative Tools window will open.
(c) Double-click on Services. The Services dialog will open.
(d) Select Remote Procedure Call (RPC) and select Action >
Properties from the menu bar. The Remote Procedure Call (RPC) Properties dialog will open.
(e) Click Start on the General tab, then click OK. The status for Remote Procedure Call (RPC) should now be set to Started in the Services dialog.
(f) Select Remote Procedure Call (RPC) Locator and select Action >
Properties from the menu bar. The Remote Procedure Call (RPC) Locator Properties dialog will open.
(g) Click Start on the General tab, then click OK. The status for Remote Procedure Call (RPC) Locator should now be set to Started in the Services dialog. 79 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic 8.2 Set Up Connection Options In addition to establishing connections, the Connect/Disconnect Merlin Bluetooth Analyzer button the connection between Merlin's Wand and Merlin. To see the options, click on the options arrow on the right side of the button. provides several options for configuring Run Merlin on a Local Machine To run Merlin on a local machine, click the options arrow on the right side of the Connect/Disconnect Merlin button and make sure that Run on local is selected in the Connect/Disconnect options menu. When selected, a checkmark appears next to it. Add a Remote Machine Merlin's Wand can be configured to control a Merlin analyzer that is running on a remote computer. Before Merlin's Wand can connect to Merlin, the remote machine that runs Merlin must be added to the Connect/Disconnect options menu in Merlin's Wand. Step 1 Click the options arrow on the right side of the Connect/Disconnect Merlin button and select Add remote machine... from the options menu. The Remote Machine dialog will open. Step 2 Enter the Internet machine name or IP address for the machine on which Merlin is running and click OK. Note: If the machine name is used and Merlin's Wand is subsequently unable to connect to Merlin, then the IP address must be used instead. 80 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic The machine name/IP address will now be listed on the Connect/Disconnect options menu. By default, it will be selected, as indicated by the checkmark that appears to the left of the name/IP address. 8.3 Start Merlin This step is required only when running Merlin on a remote machine that uses Windows 98 or Windows Me. In such cases, Merlins Wand cannot start or stop the Merlin application, although it can control Merlin once it is running. Be sure to start Merlin before connecting to it on a machine running Windows 98 or Windows Me. 8.4 Connect to Merlin with Merlins Wand Note: Before Merlin's Wand can connect to Merlin, the connection options, DCOM, and accessibility properties may need to be configured. Please refer to Set Up Connection Options on page 80 and Set Up a Remote Machine on page 77 for more information. Step 1 To connect to Merlin Bluetooth Protocol Analyzer, click on the Connect/Disconnect button. Merlin's Wand will connect to Merlin. The status bar at the bottom of the Merlin's Wand application will indicate that Merlin is connected, along with the Merlin software version. The Connect/Disconnect button will remain pressed down connected. while Merlin's Wand and Merlin are 8.5 Set Merlin Recording Options The recording options file [*.rec] that Merlin should use can be specified through Merlin's Wand. If a recording options file isn't specified through Merlin's Wand, Merlin will use either its default .rec file or the options file that was last loaded into the current instance of Merlin. Note: The .rec file has to be configured and saved in Merlin before it can be specified through Merlin's Wand. Step 1 Share the folder that contains the file.
(a) In Windows Explorer or My Computer, navigate to the folder that contains the options file. 81 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic
(b) Right-click on the folder and select Properties, or select File >
Properties from the menu bar. The Properties dialog will open.
(c) Go to the Sharing tab in the Properties dialog.
(d) Enable the Share this folder option and make sure that the folder is accessible by both the machine running Merlin and the machine running Merlin's Wand.
(e) Click OK. Step 2 Click the Set Recording Options button. The Open dialog will be displayed. Step 3 Use the Look in field at the top of the dialog box to browse to the desired file via Network Neighborhood
-or-
In the File name field, type \\ followed by the name of the computer on which the file is located (for example, \\Computer1). Press Enter to display all shared folders, then navigate to the desired file. Note: A full network path must be used in order to specify the options file through Merlin's Wand, whether the file is local to the machine running Merlin or located on a different computer. 82 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic Step 4 Click Open. The path and filename of the recording options file will now be listed on the Set Recording Options drop-down menu. By default, that file will be selected, as indicated by the checkmark that appears to the left of the path and filename. 8.6 Set Merlin Display Options The display options file [*.opt] that Merlin should use can be specified through Merlin's Wand. If a display options file isn't specified through Merlin's Wand, Merlin will use either its default .opt file or the options file that was last loaded into the current instance of Merlin. Note: The .opt file has to be configured and saved in Merlin before it can be specified through Merlin's Wand. Step 1 Share the folder that contains the file.
(a) In Windows Explorer or My Computer, navigate to the folder that contains the options file.
(b) Right-click on the folder and select Properties, or select File >
Properties from the menu bar. The Properties dialog will open.
(c) Go to the Sharing tab in the Properties dialog.
(d) Enable the Share this folder option and make sure that the folder is accessible by both the machine running Merlin and the machine running Merlin's Wand.
(e) Click OK. 83 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic Step 2 Click the Set Display Options button. The Open dialog will be displayed. Step 3 Use the Look in field at the top of the dialog box to browse to the desired file via Network Neighborhood
-or-
In the File name field, type \\ followed by the name of the computer on which the file is located (for example, \\Computer1). Press Enter to display all shared folders, then navigate to the desired file. Note: A full network path must be used in order to specify the options file through Merlin's Wand, whether the file is local to the machine running Merlin or located on a different computer. Step 4 Click Open. The path and filename of the display options file will now be listed on the Set Display Options drop-down menu. By default, that file will be selected, as indicated by the checkmark that appears to the left of the path and filename. 8.7 Set Merlin Encryption Options Merlin's Wand can set up Merlin to decode encrypted transmissions. Step 1 Open the Encryption Setup dialog by pressing the Set Merlin encryption options button. 84 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic The Encryption Setup dialog will open. Step 2 Select the Slave Device Address from the drop-down list, or enter it into the combo box. Step 3 Enter the PIN Number for the slave device in the PIN Code text box. or Enter the Link Key for the master-slave connection in the Link Key text box. Step 4 Press the Set button to apply the encryption setup. 8.8 Start a Merlin Recording Session To begin a Merlin Bluetooth Analyzer recording session, press the Record button on the Merlin toolbar. 8.9 Stop a Merlin Recording Session To stop a Merlin Bluetooth Analyzer recording session, press the Stop button on the Merlin toolbar. 8.10 Disconnect from Merlin Bluetooth Protocol Analyzer To disconnect from Merlin Bluetooth Protocol Analyzer, click on the Connect/Disconnect button. Merlin's Wand will disconnect from Merlin. 85 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic 8.11 Troubleshooting Server Busy When Attempting to Launch Merlin Server Busy" message appears when attempting to launch Merlin on a remote Windows 98 or Windows Me system. Make sure Merlin is running on the remote machine before clicking the Connect/Disconnect Merlin Wand cannot start or stop Merlin on a remote Windows 98 or Windows Me system; it can only control Merlin once Merlin is running on the remote machine. button in Merlins Wand. Merlins Make sure DCOM is properly installed and configured on the remote machine, as described in the section DCOM Configuration for Windows 98/Me Systems. If the message box won't go away, close Merlins Wand (press Ctrl+Alt+Delete and close the program directly or through the Task Manager). Then, restart Merlins Wand and be sure to start Merlin on the remote machine before retrying the operation. Server Busy message appears when attempting to launch Merlin on a remote Windows NT or Windows 2000 system. This message may appear the first time Merlin is launched on the remote machine. It can be safely ignored. Merlin will start normally on the remote machine. Clicking the Switch To button in the message box will cause the message to disappear and the Start menu to appear. Return to Merlins Wand and proceed normally. Server Execution Failed When Attempting to Launch Merlin Server execution failed message appears when attempting to launch Merlin on a remote Windows 98 or Windows Me system. Make sure Merlin is running on the remote machine before clicking the Connect/Disconnect Merlin button in Merlins Wand. The Object Exporter Specified Was Not Found When Attempting to Launch Merlin The object exporter specified was not found message appears when attempting to launch Merlin from a Windows 2000 system. If Merlin is already running on the remote machine, try to close it. If a message appears indicating that an automation client is connected to the application, close Merlin on the remote machine, close Merlins Wand on 86 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic the local machine, and try again. If the problem persists, restart the remote machine. Make sure the local computer (the Windows 2000 system running Merlins Wand) can reach the remote machine by using its full computer name, such as <computername.domain>. Open a command prompt and use the PING command to determine this. If the local computer cannot communicate with the remote machine, consult a system administrator for assistance. If the remote machine is running TCP/IP, make sure it has an assigned IP address. Consult a system administrator for assistance in determining this and, if necessary, assigning an IP address. 87 CATC MERLINS WAND 1.22 Users Manual CHAPTER 8 Using Merlin to Record Merlins Wand Traffic 88 CATC MERLINS WAND 1.22 Users Manual CHAPTER 9 Contact and Warranty Information 9. Contact and Warranty Information 9.1 Contact Information Mailing address Computer Access Technology Corporation Customer Support 2403 Walsh Avenue Santa Clara, CA 95051-1302 USA Online support http://www.catc.com/
E-mail address support@catc.com Telephone support
+1/800.909.2282 (USA and Canada)
+1/408.727.6600 (worldwide) Fax
+1/408.727.6622 (worldwide) Sales information sales@catc.com 9.2 Warranty and License Computer Access Technology Corporation (hereafter CATC) warrants this product to be free from defects in material, content, and workmanship, and agrees to repair or replace any part of the enclosed unit that proves defective under these terms and conditions. Parts and labor are warranted for one year from the date of first purchase. The CATC software is licensed for use on a single personal computer. The software may be copied for backup purposes only. This warranty covers all defects in material or workmanship. It does not cover accidents, misuse, neglect, unauthorized product modification, or acts of nature. Except as expressly provided above, CATC makes no warranties or conditions, express, implied, or statutory, including without limitation the implied warranties of merchantability and fitness for a particular purpose. 89 CATC MERLINS WAND 1.22 Users Manual CHAPTER 9 Contact and Warranty Information CATC shall not be liable for damage to other property caused by any defects in this product, damages based upon inconvenience, loss of use of the product, loss of time or data, commercial loss, or any other damages, whether special, incidental, consequential, or otherwise, whether under theory of contract, tort (including negligence), indemnity, product liability, or otherwise. In no event shall CATC's liability exceed the total amount paid to CATC for this product. CATC reserves the right to revise these specifications without notice or penalty. 90 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Appendix A: Command Generator Command Descriptions A.1 HCI Command Descriptions Note N/A means Not Applicable. This indicates that the specified command does not have a parameter. HCI Link Control Commands Accept_Connection_Request Used to accept a new incoming connection request. Execute this command before connection request from another device. By default, all connection requests are accepted. Command Parameters Examples Comments N/A Return Events Accept_Connection_Request_Complete Add_SCO_Connection Will cause the link manager to create an SCO connection in addition to the existing ACL connection. Command Parameters HCI_Handle Packet Type Examples 0x0001 0x0080 Comments Possible packet types:
HV1=0x0020 HV2=0x0040 HV3=0x0080 Return Events Add_SCO_Connection_Complete Add_SCO_Connection_Error 91 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Authentication_Requested Used to initiate authentication between the two devices associated with the specified HCI_Handle. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Authentication_Error Authentication_Complete Change_Connection_Link_Key Used to force both connected devices to generate a new link key. Command Parameters HCI_Handle Examples 0x0001 Comments Range: 0x0000-0x0EFF Return Events Change_Connection_Link_Key_Error Change_Connection_Link_Key_Complete Change_Connection_Packet_Type Used to change which packet types can be used for a connection that is currently established. Command Parameters HCI_Handle Packet_Type Examples 0x0001 0x0008 Return Events Change_Connection_Packet_Type_Error Change_Connection_Packet_Type_Complete Comments Range: 0x0000-0x0EFF 0x0008 = DM1 0x0010 = DH1 0x0400 = DM3 0x0800 = DH3 0x4000 = DM5 0x8000 = DH5 92 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Create_Connection Create_Connection will cause the link manager to create an ACL connection to the Bluetooth wireless device with the BD_ADDR specified by the command parameters. Command Parameters BD_ADDR Examples 010203040506 Comments Enter in HEX as shown. Return Events Create_Connection_Complete Create_Connection_Error Disconnect Disconnect is used to terminate an existing connection. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Disconnection_Complete Disconnection_Failed Exit_Periodic_Inquiry_Mode Exit_Periodic_Inquiry_Mode is used to end the Periodic Inquiry mode when Merlins Wand is in Periodic Inquiry mode. Command Parameters Examples Comments N/A Return Events Exit_Periodic_Inquiry_Mode_Complete Exit_Periodic_Inquiry_Mode_Error Inquiry Inquiry will cause Merlins Wand to enter Inquiry mode and discover other nearby Bluetooth devices. Command Parameters Examples Comments Inquiry_Length Num_Responses 8 10 93 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Inquiry_Complete Inquiry_Result Inquiry_Error Inquiry_Cancel Inquiry_Cancel will cause Merlins Wand to stop the current Inquiry if the Bluetooth device is in Inquiry mode. Command Parameters Examples Comments N/A Return Events Inquiry_Canceled Inquiry_Error Periodic_Inquiry_Mode Periodic_Inquiry_Mode is used to configure Merlins Wand to perform a periodic Inquiry based on a specified period range. Note: Max_Period_Length > Min_Period_Length > Inquiry Length. Command Parameters Examples Comments Max Period Length Min Period Length Inquiry Length Num of Responses 10 9 8 10 Return Events Periodic_Inquiry_Mode_Complete Periodic_Inquiry_Mode_Error Range: 0x03 0xFFFF Range: 0x02 0xFFFE Range: 0x01 0x30 Range: 0-255 (0=Unlimited number of responses) 94 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions PIN_Code_Request_Negative_Reply PIN_Code_Request_Negative_Reply PIN_Code_Request_Negative_Reply is used to reply to a PIN Code PIN_Code_Request_Negative_Reply is used to reply to a PIN Code Request Request event from the Host Controller when the Host cannot specify a PIN event from the Host Controller when the Host cannot specify a PIN code to code to use for a connection. This command should be executed before use for a connection. This command should be executed before PIN_Code_Request event is received. By default, the PIN_Code_Request PIN_Code_Request event is received. By default, the PIN_Code_Request event is rejected. event is rejected. Command Parameters Command Parameters BD_ADDR BD_ADDR Examples Examples 0x010203040506 0x010203040506 Comments Comments Return Events Return Events Command_Complete Command_Complete PIN_Code_Request_Reply PIN_Code_Request_Reply PIN_Code_Request_Reply is used to reply to a PIN Code Request event PIN_Code_Request_Reply is used to reply to a PIN Code Request event from from the Host Controller and specifies the PIN code to use for a connection. the Host Controller and specifies the PIN code to use for a connection. This This command should be executed before Pin_Code Request event is command should be executed before Pin_Code Request event is received. By received. By default, the Pin_Code Request event is rejected. default, the Pin_Code Request event is rejected. Command Parameters Command Parameters PIN_Code PIN_Code Examples Examples 1234 1234 BD_ADDR BD_ADDR 0x010203040506 0x010203040506 Comments Comments PIN_Code is a string character that can be up to 128 bits in length PIN_Code is a string character that can be up to 128 bits in length Return Events Return Events Command_Complete Command_Complete Read_Clock_Offset Read_Clock_Offset Read_Clock_Offset allows the Host to read the clock offset of remote Read_Clock_Offset allows the Host to read the clock offset of remote devices. devices. Examples Examples 0x0001 0x0001 Comments Comments Command Parameters Command Parameters HCI_Handle HCI_Handle Return Events Return Events Read_Clock_Offset_Complete Read_Clock_Offset_Error Read_Clock_Offset_Complete Read_Clock_Offset_Error 95 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Read_Remote_Supported_Features Read_Remote_Supported_Features requests a list of the supported features of a remote device. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Read_Remote_Supported_Features_Complete Read_Remote_Supported_Features_Error Read_Remote_Version_Information Read_Remote_Version_Information command will read the values for the version information for the remote Bluetooth device. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Read_Remote_Version_Information_Complete Read_Remote_Version_Information_Error Reject_Connection_Request Reject_Connection_Request is used to decline a new incoming connection request. Execute this command before connection request from another device. By default, all connection requests are accepted. Command Parameters Examples Comments N/A Return Events Reject_Connection_Request_Complete Remote_Name_Request Remote_Name_Request is used to obtain the user-friendly name of another Bluetooth device. The BD_ADDR command parameter is used to identify the device for which the user-friendly name is to be obtained. The Page_Scan_Repetition_Mode and Page_Scan_Mode command parameters specify the page scan modes supported by the remote device with the BD_ADDR. This is the information that was acquired during the inquiry 96 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions process. The Clock_Offset parameter is the difference between its own clock and the clock of the remote device with BD_ADDR. Only bits 2 through 16 of the difference are used and they are mapped to this parameter as bits 0 through 14 respectively. A Clock_Offset_Valid_Flag, located in bit 15 of the Clock_Offset command parameter, is used to indicate if the Clock Offset is valid or not. Command Parameters BD ADDR Page Scan Rep Mode Page Scan Mode 0x0 0x0 Examples 0x010203040506 Comments Clock Offset 0x0 0x00=R0; 0x01=R1;
0x02=R2 0x00=Mandatory Page Scan Mode 0x01=Optional Page Scan Mode I 0x02=Optional Page Scan Mode II 0x03=Optional Page Scan Mode III Bit Format:
Bit 14.0 = Bit 16.2 of CLKslave -
CLKmaster. Bit 15 = Clock_Offset_ Valid_Flag where 0= Invalid Clock Offset 1=Valid Clock Offset Return Events Remote_Name_Request_Complete Remote_Name_Request_Error Set_Connection_Encryption Set_Connection_Encryption is used to enable and disable the link-level encryption. Command Parameters HCI_Handle Encryption_Enable Examples 0x0001 1 Comments Range: 0 or 1 Return Events Set_Connection_Encryption_Complete Set_Connection_Encryption_Error 97 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions HCI Link Policy Commands Exit_Park_Mode Stops park mode and enters active mode for the specified ACL link. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Mode_Change Exit_Park_Mode_Error Exit_Sniff_Mode Stops Sniff mode and enters active mode for the specified ACL link. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Mode_Change Exit_Sniff_Mode_Error Hold_Mode Places the specified ACL link into Hold Mode. Examples 0x0001 0xFFFF 0x01 Comments 0x0001 - 0xFFFF 0x0001 - 0xFFFF Command Parameters HCI_Handle Max_Interval Min_Interval Return Events Mode_Change Hold_Mode_Error Park_Mode Places the specified ACL link into Park mode. Command Parameters HCI_Handle Beacon_Max_Interval Beacon_Min_Interval Comments 0x0001 - 0xFFFF 0x0001 - 0xFFFF Examples 0x0001 0xFFFF 0x01 98 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Mode_Change Park_Mode_Error QoS_Setup Used to specify Quality of Service parameters for a connection handle. Examples 0x0001 0x01 0 0 0xFFFFFFFF 0xFFFFFFFF Comments 0=No traffic;
1=Best effort;
2=Guaranteed Token rate in Bytes/second Bytes per second In microseconds In microseconds Command Parameters HCI_Handle ServiceType TokenRate PeakBandwidth Latency DelayVariation Return Events Quality_of_Service_Setup_Complete Quality_of_Service_Setup_Error Read_Link_Policy_Settings Reads Link Policy setting for the specified ACL link. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Read_Link_Policy_Settings_Complete Read_Link_Policy_Settings_Error Role_Discovery Description:
Role_Discovery is used for a Bluetooth device to determine which role the device is performing (Master or Slave) for a particular connection. Command Parameters HCI_Handle Examples 0x0001 Comments 99 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Role_Discovery_Complete Role_Discovery_Error Sniff_Mode Places the specified ACL link into Sniff mode. Command Parameters Examples Comments 0x0001 0xFFFF 0x01 0x3FF6 0x7FFF 0x0001 - 0xFFFF 0x0001 - 0xFFFF 0x0001 - 0x7FFF 0x0000 - 0x7FFF HCI_Handle Max_Interval Min_Interval Attempt Timeout Return Events Mode_Change Sniff_Mode_Error Switch_Role Switches the current role (master/slave) of the calling device with the role of the device specified. Command Parameters BD_ADDR Examples 0x010203040506 Comments Return Events Role_Change_Complete Role_Change_Error Write_Link_Policy_Settings Writes link policy settings for the specified ACL link. Command Parameters HCI_Handle Link_Policy_Settings Examples 0x0001 0xF Comments 0x0000: Disable all LM modes 0x0001: Enable master/slave switch 0x0002: Enable Hold Mode 0x0004: Enable Sniff Mode 0x0008: Enable Park Mode 0xF: Enable all (Default) 100 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Write_Link_Policy_Settings_Complete Write_Link_Policy_Settings_Error HCI Host Controller & Baseband Commands Change_Local_Name Change_Local_Name allows the user-friendly name to be modified for the Merlins Wand. Command Parameters Name Examples Merlins Wand Comments Maximum string length
=32 characters Return Events Change_Local_Name_Complete Change_Local_Name_Error Delete_Stored_Link_Key Delete_Stored_Link_Key removes one or all link keys stored in the Merlins Wand. Command Parameters BD_ADDR Delete_All_Flag Examples 0x010203040506 01 Comments 00=Delete only the Link Key for specified BD_ADDR 01=Delete all stored Link Keys Return Events Delete_Stored_Link_Key_Complete Delete_Stored_Link_Key_Error 101 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Host_Buffer_Size Used by the Merlins Wand to notify the Merlins Wand Host Controller about its buffer sizes for ACL and SCO data. The Merlins Wand Host Controller will segment the data to be transmitted from the Host Controller to Merlins Wand, so that data contained in HCI Data Packets will not exceed these sizes. Examples 0x2A0 0xFF 10 0xFF Comments Only ACL is valid The value of the Host_SCO_Data_Packet_ Length must be > 399 Command Parameters ACL_Data_Length SCO_Data_Length Total_Num_ACL Total_Num_SCO Return Events Host_Buffer_Size_Complete Host_Buffer_Size_Error Read_Authentication_Enable Read_Authentication_Enable will read the value for the Authentication_Enable parameter, which controls whether Merlins Wand will require authentication for each connection with other Bluetooth devices. Command Parameters Examples Comments N/A Return Events Read_Authentication_Enable_Complete Read_Authentication_Enable_Error Read_Class_of_Device Read_Class_of_Device will read the value for the Class_of_Device parameter for Merlins Wand, which is used to indicate its capabilities to other devices. Command Parameters Examples Comments N/A 102 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Read_Class_of_Device_Complete Read_Class_of_Device_Error Read_Connection_Accept_Timeout Read_Connection_Accept_Timeout will read the value for the Connection_Accept_Timeout parameter so that Merlins Wand can automatically deny a connection request after a specified period has occurred, and to refuse a new connection. Command Parameters Examples Comments N/A Return Events Read_Connection_Accept_Timeout_Complete Read_Connection_Accept_Timeout_Error Read_Current_IAC_LAP Read_Current_IAC_LAP will read the LAP(s) used to create the Inquiry Access Codes (IAC) that Merlins Wand is simultaneously scanning for during Inquiry Scans. Command Parameters Examples Comments N/A Return Events Read_Current_IAC_LAP_Complete Read_Current_IAC_LAP_Error Read_Encryption_Mode Read_Encryption_Mode will read the value for the Encryption_Mode parameter, which controls whether Merlins Wand will require encryption for each connection with other Bluetooth devices. Command Parameters Examples Comments N/A Return Events Read_Encryption_Mode_Complete Read_Encryption_Mode_Error 103 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Read_Link_Supervision_Timeout Reads link supervision timeout setting for the specified ACL link. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events Read_Link_Supervision_Timeout_Complete Read_Link_Supervision_Timeout_Error Read_Local_Name Read_Local_Name reads the stored user-friendly name for Merlins Wand. Command Parameters Examples Comments N/A Return Events Read_Local_Name_Complete Read_Local_Name_Error Read_Number_Of_Supported_IAC This command will read the value for the number of Inquiry Access Codes
(IAC) that Merlins Wand can simultaneously listen for during an Inquiry Scan. Command Parameters Examples Comments N/A Return Events Read_Number_Of_Supported_IAC_Complete Read_Number_Of_Supported_IAC_Error Read_Page_Scan_Mode Read_Page_Scan_Mode command is used to read the current Page_Scan_Mode of Merlins Wand. Command Parameters Examples Comments N/A 104 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Read_Page_Scan_Mode_Complete Read_Page_Scan_Mode_Error Read_Page_Scan_Period_Mode Read_Page_Scan_Period_Mode is used to read the Page_Scan_Period_Mode of Merlins Wand. Command Parameters Examples Comments N/A Return Events Read_Page_Scan_Period_Mode_Complete Read_Page_Scan_Period_Mode_Error Read_Page_Timeout Read_Page_Timeout will read the value for the Page_Reply_Timeout configuration parameter, which allows Merlins Wand to define the amount of time a connection request will wait for the remote device to respond before the local device returns a connection failure. Command Parameters Examples Comments N/A Return Events Read_Page_Timeout_Complete Read_Page_Timeout_Error Read_PIN_Type Read_PIN_Type will read the PIN type specified in the host controller of Merlins Wand. Command Parameters Examples Comments N/A Return Events Read_PIN_Type_Complete Read_PIN_Type_Error 105 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Read_Scan_Enable Read_Scan_Enable will read the value for the Scan_Enable configuration parameter, which controls whether or not Merlins Wand will periodically scan for page attempts and/or inquiry requests from other Bluetooth devices. Command Parameters Examples Comments N/A Return Events Read_Scan_Enable_Complete Read_Scan_Enable_Error Read_SCO_Flow_Control_Enable The Read_SCO_Flow_Control_Enable command provides the ability to read the SCO_Flow_Control_Enable setting. By using this setting, Merlin can decide if the Merlins Wand Host Controller will send Number Of Completed Packets events for SCO HCI_Handles. Command Parameters Examples Comments N/A Return Events Read_SCO_Flow_Control_Enable_Complete Read_SCO_Flow_Control_Enable_Error Read_Stored_Link_Key Read_Stored_Link_Key will read one or all link keys stored in the Merlins Wand Host Controller. Command Parameters BD_ADDR Read_All_Flag Examples 0x010203040506 01 Comments 00=Return Link Key for specified BD_ADDR 01=Return all stored Link Keys Return Events Read_Stored_Link_Key_Complete Read_Stored_Link_Key_Error 106 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Read_Voice_Setting Read_Voice_Setting will read the values for the Voice_Setting parameter in Merlins Wand, which controls all the various settings for the voice connections. Command Parameters Examples Comments N/A Return Events Read_Voice_Setting_Complete Read_Voice_Setting_Error Reset Resets the Bluetooth Host Controller, Link Manager, and the radio module of Merlins Wand. After executing this command, the application has to be restarted. Command Parameters Examples Comments N/A Return Events Reset_Complete Set_Event_Filter Will reset to default values for the parameters Set_Event_Filter is used by the Host to specify different event filters. The Host may issue this command multiple times to request various conditions for the same type of event filter and for different types of event filters. Command Parameters FilterType Examples 0x00 FilterConditionType 0x00 Comments 0x00=Clear All Filters 0x01=Inquiry Result 0x02=Connection Setup 0x00=New device responded to the Inquiry process 0x01= Device with a specific Class of Device responded to the Inquiry process. 0x02=Device with specific BD_ADDR responded to the Inquiry process. 107 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Command Parameters Condition Examples 0x01 Comments 0x00=Allow Connections from all devices 0x01=Allow Connections from a device with a specific Class of Device 0x02=Allow Connections from a device with a specific BD_ADDR Return Events Set_Event_Filter_Complete Set_Event_Filter_Error Set_Event_Mask Set_Event_Mask is used to control which events are generated by the HCI for the Host. Command Parameters Examples Comments Event_Mask Return Events Set_Event_Mask_Complete Set_Event_Mask_Error NO_EVENTS INQUIRY_RESULT INQUIRY_COMPLETE INQUIRY_CANCELED LINK_CONNECT_IND SCO_CONNECT_IND LINK_DISCONNECT LINK_CONNECT_CNF LINK_CON_RESTRICT MODE_CHANGE ACCESSIBLE_CHANGE AUTHENTICATED ENCRYPTION_CHANGE SECURITY_CHANGE ROLE_CHANGE SCO_DISCONNECT SCO_CONNECT_CNF ALL_EVENTS 0x0000 0x0001 0x0002 0x0004 0x0008 0x0010 0x0020 0x0040 0x0080 0x0100 0x0200 0x0400 0x0800 0x1000 0x2000 0x4000 0x8000 0xffff 108 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Write_Authentication_Enable This command will write the value for the Authentication_Enable parameter, which controls whether Merlins Wand will require authentication for each connection with other Bluetooth devices. Command Parameters Authentication_Enable Examples 0x0 Comments 0x00=Authentication disabled. Default 0x01=Authentication enabled for all connection Return Events Write_Authentication_Enable_Complete Write_Authentication_Enable_Error Write_Class_of_Device Write_Class_of_Device will write the value for the Class_of_Device parameter, which is used to indicate its capabilities to other devices. Command Parameters CoD Examples 0x000000 Comments Class of Device for the device Return Events Write_Class_of_Device_Complete Write_Class_of_Device_Error 109 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Write_Connection_Accept_Timeout Write_Connection_Accept_Timeout will write the value for the Connection_Accept_Timeout configuration parameter, which allows Merlins Wand to automatically deny a connection request after a specified period has occurred, and to refuse a new connection. Command Parameters Timeout Examples 0x00 Comments Connection Accept Timeout measured in Number of Baseband slots. Interval Length = N * 0.625 msec (1 Baseband slot) Range for N: 0x0001 0xB540 Time Range: 0.625 msec -
29 seconds Default: N = 0x1FA0 Time
= 5 Sec Return Events Write_Connection_Accept_Timeout_Complete Write_Connection_Accept_Timeout_Error Write_Current_IAC_LAP Will write the LAP(s) used to create the Inquiry Access Codes (IAC) that the local Bluetooth device is simultaneously scanning for during Inquiry Scans. Comments 0x9E8B00-0x9E8B3F 0x9E8B00-0x9E8B3F 0x9E8B00-0x9E8B3F 0x9E8B00-0x9E8B3F 0x9E8B00-0x9E8B3F 0x9E8B00-0x9E8B3F Command Parameters IAC_LAP IAC_LAP IAC_LAP IAC_LAP IAC_LAP IAC_LAP Return Events Write_Current_IAC_LAP_Complete Write_Current_IAC_LAP_Error Examples 0x9E8B33 110 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Write_Encryption_Mode Write_Encryption_Mode command will write the value for the Encryption_Mode parameter, which controls whether Merlins Wand will require encryption for each connection with other Bluetooth devices. Command Parameters Encryption Mode Examples 0x0 Comments 0x00=Encryption disabled. Default 0x01=Encryption only for point-to-point packets 0x02=Encryption for both point-to-point and broadcast packets Return Events Write_Encryption_Mode_Complete Write_Encryption_Mode_Error Write_Link_Supervision_Timeout Writes link supervision timeout setting for the specified ACL link. Command Parameters HCI_Handle Timeout Examples 0x0001 0x7D00 Comments 0x0001 - 0xFFFF Return Events Write_Link_Supervision_Timeout_Complete Write_Link_Supervision_Timeout_Error 111 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Write_Page_Timeout Write_Page_Timeout command will write the value for the Page_Reply_Timeout configuration parameter, which allows Merlins Wand to define the amount of time a connection request will wait for the remote device to respond before the local device returns a connection failure. Command Parameters Timeout Examples 0x10 Comments 0=Illegal Page Timeout. Must be larger than 0 N = 0xXXXX Page Timeout measured in Number of Baseband slots. Interval Length = N * 0.625 msec (1 Baseband slot) Range for N: 0x0001 0xFFFF Time Range: 0.625 msec
-40.9 Seconds Default: N = 0x2000 Time
= 5.12 Sec Return Events Write_Page_Timeout_Complete Write_Page_Timeout_Error Write_PIN_Type Write_PIN_Type will specify whether the Host supports variable PIN or only fixed PINs. Command Parameters PIN_Type Examples 0 Comments 0x00=Variable PIN 0x01=Fixed PIN Return Events Write_PIN_Type_Complete Write_PIN_Type_Error 112 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Write_Scan_Enable The Write_Scan_Enable command will write the value for the Scan_Enable configuration parameter into Merlins Wand, which controls whether or not Merlins Wand will periodically scan for page attempts and/or inquiry requests from other Bluetooth devices. Command Parameters Scan_Enable Examples 3 Comments 0x00=No Scans enabled. 0x01=Inquiry Scan enabled Page Scan disabled. 0x02=Inquiry Scan disabled. Page Scan enabled. 0x03=Inquiry Scan enabled Page Scan enabled.
(Default) Return Events Write_Scan_Enable_Complete Write_Scan_Enable_Error Write_Stored_Link_Key Write_Stored_Link_Key command will write a link key to the Merlins Wand host controller. Command Parameters BD_ADDR Link_Key Examples 0x010203040506 0x01020304 Comments Return Events Write_Stored_Link_Key_Complete Write_Stored_Link_Key_Error Write_Voice_Setting The Write_Voice_Setting command will write the values for the Voice_Setting parameter into Merlins Wand, which controls all the various as settings for the voice connections. Command Parameters HCI_Handle Voice_Setting Comments 0x0060=CVSD coding 0x0061=u-Law coding 0x0062=A-law coding Examples 0x0001 0x0062 113 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Write_Voice_Setting_Complete Write_Voice_Setting_Error HCI Informational Commands Read_BD_ADDR Read_BD_ADDR will read the value of Merlins Wands address. The BD_ADDR is a 48-bit unique identifier for a Bluetooth device. Command Parameters Examples Comments N/A Return Events Read_BD_ADDR_Complete Read_BD_ADDR_Error Read_Buffer_Size Read_Buffer_Size returns the size of the HCI buffers in Merlins Wand. These buffers are used by Merlins Wands Host Controller to buffer data that is to be transmitted. Command Parameters Examples Comments N/A Return Events Read_Buffer_Size_Complete Read_Buffer_Size_Error Read_Country_Code Read_Country_Code command will read the value for the Country_Code status parameter in Merlins Wand. The Country_Code defines which range of frequency band of the ISM 2.4 GHz band will be used by the device. Command Parameters Examples Comments N/A Return Events Read_Country_Code_Complete Read_Country_Code_Error 114 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Read_Local_Supported_Features Read_Local_Supported_Features will request a list of the supported features for Merlins Wand. Command Parameters Examples Comments N/A Return Events Read_Local_Supported_Features_Complete Read_Local_Supported_Features_Error Read_Local_Version_Information Read_Local_Version_Information command will read the values for the version information for Merlins Wand. Command Parameters Examples Comments N/A Return Events Read_Local_Version_Information_Complete Read_Local_Version_Information_Error HCI Testing Commands Enable_Device_Under_Test_Mode The Enable_Device_Under_Test_Mode command will allow Merlins Wand to enter test mode via LMP test commands. Merlins Wand issues this command when it wants to become the DUT for the Testing scenarios as described in the Bluetooth Test Mode. Command Parameters Examples Comments N/A Return Events Enable_Device_Under_Test_Mode_Complete Enable_Device_Under_Test_Mode_Error 115 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Read_Loopback_Mode Read_Loopback_Mode will read the value for the setting of the Merlins Wand Host Controllers Loopback_Mode. The setting of the Loopback_Mode will determine the path of information. Command Parameters Examples Comments N/A Return Events Read_Loopback_Mode_Complete Read_Loopback_Mode_Error Write_Loopback_Mode The Write_Loopback_Mode will write the value for the setting of the Host Controllers Loopback_Mode into Merlins Wand. Comments 0x00=No Loopback mode enabled. Default 0x01=Enable Local Loopback 0x02=Enable Remote Loopback Command Parameters Loopback_Mode Examples 0 Return Events Write_Loopback_Mode_Complete Write_Loopback_Mode_Error CATC-Specific HCI Commands CATC_BER_Test This command will measure Bit Error Rate (BER) when fully loaded DH1, DH3, DH5, DM1, DM3 or DM5 packets are sent from master to slave on the link. Command Parameters Examples Comments HCI_Handle Number_Of_Packets 0000 0x0000=Unlimited number of packets will be sent 0x0001=0xFFFF number of packets will be sent 116 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Command Parameters BER_Packet_Type Examples 03 00 FF 10 Test_Data_Type Test_Data BER_Interval Return Events CATC_BER_Test_Complete CATC_BER_Test_Error Comments 0x00=DH1 0x01=DH3 0x02=DH5 0x03=DM1 0x04=DM3 0x05=DM5 0x00=Send PBRS (same as in Bluetooth test mode) 0x01=Every octet that is sent equals Test_Data Data to send A packet is sent every BER_Interval frame CATC_Change_Headset_Gain Controls the gain of the microphone or speaker of the headset. Command Parameters Device Gain Examples Speaker 0 Comments Microphone or Speaker
(Speaker is default) 0x00 - 0x0F Return Events CATC_Change_Headset_Gain_Complete CATC_Change_Headset_Gain_Error CATC_Read_Headset_Gain Reads the gain of the microphone or speaker of the headset. Command Parameters Device Examples Speaker Comments Microphone or Speaker
(Speaker is default) Return Events CATC_Read_Headset_Gain_Complete CATC_Read_Headset_Gain_Error 117 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions CATC_Read_Revision_Information Merlins Wand uses this command to read the revision number of the Merlins Wand baseband controller. Command Parameters Examples Comments N/A Return Events CATC_Read_Revision_Information_Complete CATC_Read_Revision_Information_Error CATC_Self_Test This command will perform self-test of Merlins Wand. Command Parameters Examples Comments N/A Return Events CATC_Self_Test_Complete CATC_Self_Test_Error CATC_Write_Country_Code Writes the value of the Country_Code. Note: this command will not take effect until the device is reset. Command Parameters Country_Code Examples 0x00 Comments 0x00 North America and Europe (default) 0x01 France Return Events CATC_Write_Country_Code_Complete CATC_Write_Country_Code_Error A.2 Other HCI Events Events Command_Complete PIN_Code_Request Paring_Complete 118 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Events Encryption_Change Disconnect_Complete Link_Key_Request_Complete A.3 L2CAP Command Descriptions ConfigurationResponse Response to an incoming configuration request. Command Parameters Reason Examples Accept Comments Accept (Default) Reject Reject - unacceptable params Reject - unknown options Return Events ConfigurationResponse_Complete ConfigurationSetup Sets L2CAP connection options. Command Parameters Examples Comments ServiceType TokenRate TokenBucketSize PeakBandWidth Latency DelayVariation Return Events ConfigurationSetup_Complete Error 0x01 0x00 0x00 0x00 0xFFFFFFFF 0xFFFFFFFF 119 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions ConnectRequest Requests establishment of an L2CAP channel in the remote Bluetooth device. Comments Examples 0x0001 0x1001 0x1B6 Command Parameters HCI_Handle PSM Receive MTU Return Events Connection_Complete Connection_Failed ConnectResponse Indicates the response to the incoming connection request.This command should be executed before Connection Request. Command Parameters Examples Comments Response Accept (Default) Reject_Pending Reject_PSM_Not_Supported Reject_Security_Block Reject_No_Resources Return Events ConnectResponse_Complete DeregisterPsm Deregisters the specified PSM. Command Parameters PSM Examples 0x1001 Comments Return Events DeregisterPsm_Complete DeregisterPsm_Failed DisconnectRequest Requests the disconnection of the specified L2CAP channel. Command Parameters CID Examples 0x0040 Comments 120 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Disconnection_Complete Disconnection_Failed EchoRequest Sends an Echo Request over the L2CAP channel. Examples 0x0001 echo Comments Command Parameters HCI_Handle Data Return Events EchoRequest_Complete EchoRequest_Failed InfoRequest Sends an Info Request over the L2CAP channel. Info requests are used to exchange implementation-specific information regarding L2CAPs capabilities. Command Parameters HCI_Handle Examples 0x0001 Comments Return Events InfoRequest_Complete InfoRequest_Failed RegisterPsm Registers a PSM identifier with L2CAP. Once registered, the protocol can initiate connections and data transfers as well as receive connection requests and data. Examples 0x1001 0x1B6 Comments Command Parameters PSM Receive MTU Return Events RegisterPsm_Complete RegisterPsm_Failed 121 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions SendData Sends data on the specified L2CAP channel. Command Parameters CID Data Pipe Examples 0x0040 Pipe1 Comments Data_Pipe should be created in the Data Transfer Manager. Return Events SendData_Complete SendData_Failed A.4 Other L2CAP Events Events Connection_Indication Disconnection_Indication Data_Indication Write_Configuration_Complete Command_Complete Error A.5 SDP Command Descriptions AddProfileServiceRecord This command will add a pre-defined Service Record according to one of the Bluetooth wireless technology profiles to the SDP database. Command Parameters Profile Examples HeadSet 122 Comments The following are values of the Profile parameter:
HeadsetAudioGateway Headset SerialPort Dialup Fax LAN FileTransfer ObjectPush Sync SyncCommand InterCom Cordless CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Command Parameters ServerChannel Examples 0x01 Comments Server channel has to be entered for all profiles except for InterCom and Cordless. Return Events AddProfileServiceRecord_Complete AddProfileServiceRecord_Error AddServiceRecord This command will add a pre-defined Service Record according to one of the Bluetooth wireless technology profiles to the SDP database. Comments Click the ... button to choose a file. Choosing a file will automatically load the records within that file, and those record names will be in the drop-down for Record Name. Record Names loaded from the Filename file will be in the drop-down for this parameter. To leave the server channel as is, enter 0 or leave this blank. Command Parameters Filename Examples C:/Records.sdp Record Name FTP Test Record ServerChannel Return Events AddServiceRecord_Complete AddServiceRecord_Failed ProfileServiceSearch This command will search for support of one of the Bluetooth wireless technology profiles. Command Parameters HCI_Handle Examples 0x0001 Comments 123 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Command Parameters Profile Examples HeadSet Comments The following are values of the Profile parameter:
HeadsetAudioGateway Headset SerialPort Dialup Fax LAN FileTransfer ObjectPush Sync SyncCommand InterCom Cordless Return Events ProfileServiceSearch_Complete ProfileServiceSearch_Failed RequestServiceAttribute This command will retrieve specific attribute values from a specific service record. The Service Record Handle from a specific Service Record and a list of AttributeIDs to be retrieved from that Service Record are supplied as parameters. Up to three AttributeIDs can be searched in one request. Service Record Handle is usually retrieved by using RequestServiceSearch command. Examples 0x0001 0x00010000 0x1108 0x1203 Comments You can specify between 0 and 3 AttributeIDs. Command Parameters HCI_Handle ServiceRecordHandle AttributeID AttributeID AttributeID Return Events RequestServiceAttribute_Response Search_Failed 124 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions RequestServiceSearch This command will locate Service Records that match the ServiceSearch Pattern of Service Class IDs. The SDP server will return all Service Record Handles of Service Records that match the given Service Search Pattern. Up to three ServiceClassIDs can be searched in one request. Command Parameters Examples Comments 0x0001 0x1204 0x1110 0x1000 Between 0 and 3 Service Class IDs can be specified. HCI_Handle ServiceClassID ServiceClassID ServiceClassID Return Events RequestServiceSearch_Response Search_Failed RequestServiceSearchAttribute This command combines the capabilities of the RequestServiceAttribute and RequestServiceSearch into a single request. This command will retrieve all Attribute values that match the ServiceSearch pattern. Command Parameters Examples Comments HCI_Handle ServiceClassID ServiceClassID ServiceClassID Return Events Note that all Attributes are requested since a range of 0x0000-0xFFFF is specified by default. RequestServiceSearchAttribute_Response Search_Failed ResetDatabase This command will remove all Service Records from the database in Merlins Wand. Command Parameters Examples Comments N/A 125 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events ResetDatabase_Complete ResetDatabase_Failed A.6 RFCOMM Command Descriptions AcceptChannel This command will accept or reject incoming request to open an RFCOMM channel from RFCOMM server. This command should be executed before RFCOMM connection request from another device. By default, all connection requests are accepted. Command Parameters Accept Examples TRUE Comments
(Values: TRUE/FALSE) Return Events AcceptChannel_Complete AcceptPortSettings This command will accept or reject PortSettings received during RequestPortSettings event. This command should be executed before PortSettings request from another device. By default, all requests are accepted. Command Parameters Accept Examples TRUE Comments
(Values: TRUE/FALSE) Return Events AcceptPortSettings_Complete AdvanceCredit Advances a specified number of credits to a particular RFCOMM connection. Command Parameters
(HCI / DLCI) Credit Examples
(0x0001, 0x02) 20 Comments Number of credits to advance 126 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events AdvanceCredit_Complete AdvanceCredit_Error CloseClientChannel This command will close an established RFCOMM channel between Merlins Wand and a remotely connected device. Command Parameters
(HCI/DLCI) Examples
(0x0001, 0x02) Comments The DLCI value is returned by the OpenClientChannel command Return Events CloseClientChannel_Complete CloseClientChannel_Error CreditFlowEnabled This command is used to check if credit-based flow control has been negotiated for the current RFCOMM session. Command Parameters
(HCI/DLCI) Examples
(0x0001, 0x02) Comments The DLCI value is returned by the OpenClientChannel command Return Events CreditFlowEnabled_Complete DeregisterServerChannel Deregisters an RFCOMM server channel. Command Parameters ServerChannel Examples 0x01 Return Events DeregisterServerChannel_Complete DeregisterServerChannel_Error 127 Comments ServerChannel must first be registered via RegisterServerChannel command. CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions OpenClientChannel This command will open an RFCOMM channel. Command Parameters HCI_Handle ServerChannel MaxFrameSize Credit Examples 0x0001 0x01 0x7F 0x20 Comments Range: 1-30 Range: 23-32767 Default is 127 The number of frames that the sender has available Return Events OpenClientChannel_Complete OpenClientChannel_Failed RegisterServerChannel This command will register ServerChannel with an RFCOMM server so that the server can respond to incoming OpenClientChannel requests. Command Parameters Examples Comments N/A Return Events RegisterServerChannel_Complete RegisterServerChannel_Error RequestPortSettings This command will request a change to the current PortSettings. Command Parameters
(HCI/DLCI) BaudRate DataFormat FlowControl Xon Xoff Return Events RequestPortSettings_Complete RequestPortSettings_Failed Examples
(0x0001, 0x02) Comments For values, see below. 9600 0x02 0x00 0x11 0x13 128 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Parameter Values:
BaudRate: Specifies the baud rate. Note that the baud rate setting does not actually affect RFCOMM throughput. Values: 2400, 4800, 7200, 9600, 19200, 38400, 57600, 115200, 230400 DataFormat: The following values identify the number of data bits. Values:
0x00 -- DATA_BITS_5 0x02 -- DATA_BITS_6 0x01 -- DATA_BITS_7 0x03 -- DATA_BITS_8 Flow Control:
Values:
0x00 -- FLOW_CTRL_NONE 0x01 -- XON_ON_INPUT 0x02 -- XON_ON_OUTPUT 0x04 -- RTR_ON_INPUT 0x08 -- RTR_ON_OUTPUT 0x10 -- RTC_ON_INPUT 0x20 -- RTC_ON_OUTPUT Xon:
Value: Default Xon char -- 0x11 Xoff:
Value: Default Xoff char -- 0x13 RequestPortStatus This command will request the status of the PortSettings for the remote device. Command Parameters
(HCI/DLCI) Examples
(0x0001, 0x02) Comments Return Events RequestPortStatus_Complete RequestPortStatus_Error SendData Causes Merlins Wand to send data by pipe value to remote device over the specified channel. Command Parameters
(HCI/DLCI) Examples
(0x0001, 0x02) Comments 129 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Command Parameters Data Pipe Examples Pipe1 Comments Data Pipe should be created in the Data Transfer Manager Return Events SendData_Complete SendData_Failed SendTest This command causes Merlins Wand to sent a test frame to a remote device over the specified channel. Command Parameters
(HCI/DLCI) Examples
(0x0001, 0x02) Comments Return Events SendTest_Complete SendTest_Failed SetLineStatus This command will send the LineStatus command to the remote device. It allows the RFCOMM user to communicate overrun framing and parity errors to the remote device. Command Parameters
(HCI/DLCI) LineStatus Examples
(0x0001, 0x02) 0x0F Comments LineStatus Values:
0x01 -- Set to indicate an error. 0x02 -- Set to indicate an overrun error. 0x04 -- Set to indicate a parity error. 0x08 -- Set to indicate a framing error. Return Events SetLineStatus_Complete SetLineStatus_Failed 130 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions SetModemStatus This command will send the ModemStatus to the remote device. It allows the user to send Flow Control and V.24 signals to the remote device. Command Parameters Examples Comments Modem Signal Values:
0x8c - Ready to communicate, ready to receive, and data valid 0x02 (FLOW) - Set when sender is unable to receive frames 0x04 (RTC) - Set when sender is ready to communicate. 0x08 (RTR) - Set when sender is ready to receive data. 0x40 (IC) - Set when a call is incoming. 0x80 (DV) - Set when valid data is being sent. 0-15 indicates the length of the break signal in 200ms units. 0 indicates no break signal.
(HCI/DLCI) ModemSignals
(0x0001, 0x02) 0x8C BreakLength 0x00 Return Events SetModemStatus_Complete SetModemStatus_Failed SendATCommand This command will send a selected AT command. Command Parameters
(HCI/DLCI) AT_Command Examples
(0x0001, 0x02) RING Comments Values:
AT + CKPD = 200: Headset Button pressed. AT + VGM = 1:
Microphone gain.
+VGM = 1: Microphone gain 1. RING OK ERROR BUSY CONNECT NO_CARRIER NO_DIAL_TONE 131 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Send_AT_Command_Complete Send_AT_Command_Error A.7 Other RFCOMM Events Events OpenClientChannel_Request CloseClientChannel_Indication Data_Indication PortNegotiation_Indication RequestPortStatus_Indication ModemStatus_Indication LineStatus_Indication Flow_Off_Indication Flow_On_Indication A.8 TCS Command Descriptions RegisterIntercomProfile Registers an Intercom identifier with TCS. Once registered, the protocol can initiate connections as well as receive connection requests. Command Parameters Examples Comments N/A Return Events Register_Intercom_Profile_Complete Register_Intercom_Profile_Error Open_TCS_Channel This command opens an L2CAP channel with TCS PSM and initializes a TCS state machine into NULL state. Command Parameters HCI_Handle Examples 0x0001 Comments 132 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions Return Events Open_TCS_Channel_Complete Open_TCS_Channel_Failed Start_TCS_Call This command must be called right after TCSOpenChannel. It automatically sends a sequence of TCS messages according to the Intercom profile specification of the TCS state machine. After successful execution of this command, TCS state machine is in ACTIVE state and SCO connection is opened. Command Parameters Examples Comments N/A Return Events Start_TCS_Call_Complete Start_TCS_Call_Error Disconnect_TCS_Call This command is called to close an existing TCS connection according to the Intercom profile specification of the TCS state machine, close the L2CAP connection, and close the SCO connection. Command Parameters Examples Comments N/A Return Events Disconnect_TCS_Call_Complete Disconnect_TCS_Call_Error Send_Info_Message This command can be called after a TCS channel is opened. It sends an INFORMATION TCS message with a called party number. Command Parameters Phone_Number Examples 408 727 6600 Comments Phone number may contain up to 10 digits. Return Events Send_Info_Complete Send_Info_Error 133 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions A.9 OBEX Command Descriptions ClientConnect This command will create an OBEX connection with a remote device. Command Parameters BD_ADDR Examples 0x010203040506 Comments An HCI Connection has to be established before calling this command. Return Events ClientConnect_Complete ClientConnect_Error ClientDisconnect This command will cause the remote device to close the established OBEX channel. Command Parameters Examples Comments N/A Return Events ClientDisconnect_Complete ClientDisconnect_Error ClientGet This command will initiate an OBEX Get operation in the remote device for the object named in the store handle. This operation is only valid over an OBEX connection. Command Parameters Object Examples VCard.vcf Comments Return Events ClientGet_Complete ClientGet_Error 134
1 2 | WAND Manual 2 of 2 | Users Manual | 1005.70 KiB |
CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions ClientPut This command will initiate an OBEX Put operation in the remote device for the object defined in the FileName parameter. Command Parameters Filename Examples C:\VCard.vcf Comments Return Events ClientPut_Complete ClientPut_Error ClientSetPath This command will initiate an OBEX SetPath operation in the remote device. Flags indicate SetPath option such as Backup. Command Parameters Path Flags Examples C:\OBEX 0x00 Comments Bit 0: Back up a level before applying name
(equivalent to ../ on many systems) Bit 1: Don't create an directory if it not exist. Returns an error instead. Return Events OBEX_Command_Complete ClientSetPath_Error ServerDeinit This command will deinitialize the OBEX server. Command Parameters Examples Comments N/A Return Events ServerDeinit_Complete ServerDeinit_Error 135 CATC MERLINS WAND 1.22 Users Manual APPENDIX A Command Generator Command Descriptions ServerInit This command will initialize the OBEX server. Command Parameters Examples Comments N/A Return Events ServerInit_Complete ServerInit_Error ServerSetPath Sets the path where received OBEX files are stored. Command Parameters Path Examples C:\OBEX Comments Use the ... button to select a path, or type one in. Return Events ServerSetPath_Complete ServerSetPath_Event ServerSetPath_Error 136 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples Appendix B: Command Generator Examples This chapter provides fourteen Command Generator examples. These examples consist of command sequences that are presented in order to illustrate useful scenarios. Please note that these examples do not cover all possible alternatives. Device Discovery and Remote Name Request Establish Baseband Connection Baseband Disconnection Create Audio Connection Establish L2CAP Connection L2CAP Channel Disconnect SDP Profile Service Search SDP Reset Database and Add Profile Service Record RFCOMM Client Channel Establishment RFCOMM Client Channel Disconnection RFCOMM Register Server Channel and Accept Incoming Connection Establish TCS Connection OBEX Server Init and Accept Incoming Connection OBEX Client Connection and Client Get & Put Each example is illustrated with a diagram that shows communications between a host and host controller. Notation used in this chapter:
Hexagon = Condition needed to start the transaction. Solid Arrow represents a command. Dashed Arrow represents optional command. Host = Merlins Wand application Host Controller = Merlins Wand device 137 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.1 Device Discovery and Remote Name Request Procedure In this scenario, Merlins Wand performs a General Inquiry and a Remote Name Request. Step 1 Select HCI tab. Step 2 Select Inquiry from the menu. You can use the default settings for the Inquiry_Length (8 seconds) and Num_Responses (10). Step 3 Click Execute. The Event Log should display an Inquiry_Result for each found device followed by an Inquiry_Complete event. Step 4 Select Remote_Name_Request from the menu. Select the target device from the BD ADDR drop-down menu. You can use the default settings for the other drop-down menus. Step 5 Click Execute. The target device should then respond to the command with its name. 138 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.2 Establish Baseband Connection Procedure In this scenario, Merlins Wand creates a Baseband (ACL) Connection. This procedure assumes that Device Discovery has already been performed. See Device Discovery and Remote Name Request on page 138. Step 1 From the HCI menu select Create_Connection. Step 2 Select the target device from the BD_ADDR drop-down menu or enter a new BD_ADDR. Step 3 Click Execute. The Event Log should display a Connection_Complete or Connection_Failed response. 139 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.3 Baseband Disconnection Procedure In this scenario, Merlins Wand terminates a Baseband connection. These steps continue the connection you established in the preceding scenario. This procedure assumes that an ACL connection exists. See Establish Baseband Connection on page 139. Step 1 From the HCI menu, select Disconnect. Step 2 From the HCI_Handle drop-down menu, select a handle. Step 3 Click Execute. For each Disconnect, you should see a return event in the Event Log that indicates the outcome of the command. 140 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.4 Create Audio Connection Procedure In this scenario, Merlins Wand creates an SCO connection. This procedure assumes that you have established an ACL connection between Merlins Wand and the target device. See Establish Baseband Connection on page 139. Step 1 From the HCI menu, select Add_SCO_Connection from the menu. Step 2 Select the HCI_Handle for the previously established Baseband connection (for example, 0x0001) from the HCI_Handle parameter drop-down menu. Step 3 Select a packet type from the Packet Type parameter drop-down menu. Step 4 Click Execute. The Event Log should indicate that the command was executed and that the target device responded with Add_SCO_Connection_Complete or Add_SCO_Connection_Error. 141 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.5 L2CAP Connection Procedure In this scenario, Merlins Wand establishes an L2CAP connection. This procedure assumes that an ACL connection has been established. See Establish Baseband Connection on page 139. Step 1 Click the L2CAP tab to display the L2CAP drop-down menu. Step 2 Select Register_PSM from the menu. Merlins Wand must register its PSM channel before it can form an L2CAP connection. Step 3 Select or type a PSM from the PSM menu. Step 4 Select or type the Receive MTU from the Receive MTU menu (default value can be used). Step 5 Click Execute. Step 6 Repeat this procedure for the target device. The target device must also select a PSM. Event Log should register RegisterPsm_Complete. 142 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples Step 7 Select ConnectRequest from the L2CAP menu. Step 8 Select an HCI Handle from the HCI_Handle drop-down menu. To determine which HCI_Handle value is correct, open the Piconet window on the far left side of the Merlins Wand application. Step 9 Select or type a PSM from the PSM menu. Step 10 Select or type the Receive MTU from the Receive MTU menu (default value can be used). Step 11 Click Execute. The Event Log should indicate that the command was executed and that a connection has been established. 143 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.6 L2CAP Channel Disconnect Procedure In this scenario, Merlins Wand terminates an L2CAP connection. This procedure assumes that an L2CAP connection has been established. See L2CAP Connection on page 142. Step 1 From the L2CAP menu, select DisconnectRequest. Step 2 Select the appropriate CID from the CID menu. Step 3 Click Execute. The Event Log should indicate that the command was successfully completed, with Disconnection_Complete. 144 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.7 SDP Profile Service Search Procedure In this scenario, Merlins Wand conducts a Profile Service Search. This procedure assumes that an ACL connection has been established. Establish Baseband Connection on page 139. Step 1 Click the SDP tab to display the SDP menu. Step 2 Select ProfileServiceSearch from the menu. Step 3 Select an HCI Handle from the HCI_Handle drop-down list. You can determine the HCI Handle from the Piconet window. Step 4 Select a profile from the Profile menu. Step 5 Click Execute. The Event Log should return ProfileServiceSearch_Complete, as well as the results of the search. 145 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.8 SDP Reset Database and Add Profile Service Record Procedure In this scenario, Merlins Wand resets the SDP database and then adds an SDP Profile Service Record. This procedure assumes that an ACL connection has been established between Merlins Wand and the target device. Establish Baseband Connection on page 139. Note A connection is not necessary to perform a Reset_Database or AddProfileServiceRecord. Step 1 From the SDP tab select ResetDatabase. Step 2 Click Execute. The Event Log should indicate that the database was reset. Step 3 Select AddProfileServiceRecord from the menu. Step 4 Select a profile from the Profile menu. Step 5 Select a server channel from the Channel menu. Step 6 Click Execute. Success will be indicated in the Event Log with AddProfileServiceRecord_Complete and the type of profile added. 146 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.9 RFCOMM Client Channel Establishment Procedure In this scenario, Merlins Wand opens an RFCOMM client channel. This procedure assumes that an ACL connection has been established and that the target device has assumed the role of an RFCOMM server. See Establish Baseband Connection on page 139. Step 1 Click the RFCOMM tab to open the RFCOMM drop-down menu. Step 2 Select OpenClientChannel from the menu. Step 3 Select an HCI Handle from the HCI_Handle drop-down list. Step 4 Select a Server Channel from the ServerChannel menu. Step 5 Select a Max Frame Size from the MaxFrameSize menu. Step 6 Select the number of credits from the Credit menu. Step 7 Click Execute. OpenClientChannel_Complete in the Event Log indicates that a client channel was successfully opened. 147 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.10 RFCOMM Client Channel Disconnection Procedure In this scenario, Merlins Wand closes an RFCOMM client channel. This procedure assumes that an RFCOMM channel has been established. See RFCOMM Client Channel Establishment on page 147. Step 1 From the RFCOMM menu select CloseClientChannel. Step 2 Select the HCI/DLCI combination from the (HCI/DLCI) menu. Step 3 Click Execute. The Event Log should indicate a response to the command such as CloseClientChannel_Complete. 148 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.11 RFCOMM Register Server Channel Procedure In this scenario, Merlins Wand registers a Server Channel. This procedure assumes that an ACL connection has been established. See Establish Baseband Connection on page 139. Note A connection is not necessary to call a RegisterServerChannel command. Step 1 From the RFCOMM menu select RegisterServerChannel. Step 2 Click Execute. The Event Log should indicate successful completion of the command with the response RegisterServerChannel_Complete. On completion of these steps, the application is ready to accept incoming RFCOMM connections. 149 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.12 Establish TCS Connection Procedure In this scenario, Merlin's Wand establishes a TCS connection. This procedure assumes that an ACL connection has been established. See Establish Baseband Connection on page 139. Step 1 Click the TCS tab to display the TCS drop-down menu. Step 2 Select Register_Intercom_Profile from the menu. Merlin 's Wand must register its Intercom profile before it can form a TCS connection. Step 3 Click Execute. The Event Log should display Register_Intercom_Profile_Complete. Step 4 Repeat Steps 1-3 for the target device. Step 5 Select Open_TCS_Channel from the menu and select an HCI handle. Merlin 's Wand must create an ACL connection before it can form a TCS connection. 150 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples Step 6 Click Execute. Event Log should display Open_TCS_Channel_Complete. Step 7 Select Start_TCS_Call from the menu. Step 8 Click Execute. Event Log should display Start_TCS_Call_Complete. 151 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.13 OBEX Server Init Procedure In this scenario, Merlins Wand initializes itself as an OBEX server. This scenario assumes that an ACL connection exists. See Establish Baseband Connection on page 139. Note A connection is not necessary to call an OBEX ServerInit function. Step 1 Click the OBEX tab to display the OBEX menu. Step 2 Select ServerInit from the menu. Step 3 Click Execute. On completion of these steps, the application is ready to accept an incoming OBEX connection. 152 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples B.14 OBEX Client Connection and Client Get & Put Procedure In this scenario, Merlins Wand forms a client connection with the target device and then retrieves a text file from the target and sends one to it. This procedure assumes that an ACL connection has been established (see Establish Baseband Connection on page 139). It also assumes that the target device has been configured as an OBEX server. Note: When the OBEX window is first opened, Merlins Wand will automatically run an OBEX_ClientInit command and initiate itself as an OBEX client. This means that you do not have to manually execute a ClientInit command at the start of this procedure. Step 1 Click the OBEX tab to display the OBEX menu. Step 2 Select ClientConnect from the menu. Step 3 Select the target device from the BD_ADDR parameter menu. 153 CATC MERLINS WAND 1.22 Users Manual APPENDIX B Command Generator Examples Step 4 Click Execute. The Event Log should indicate that a connection was established. Step 5 Select ClientGet from the command menu. Step 6 Type in the name of a file that is to be transferred from the Server into the Object parameter box. Step 7 Click Execute. The Event Log should indicate that the file was transferred. A Save As dialog box should open. Step 8 Enter a name for the file you are retrieving. Select a directory, then click Save. Step 9 Select ClientPut from the command menu. Step 10 In the box marked Filename, type the name of a file that is to be transferred to the server, or use the browse button to locate the file you want to put. The Open dialog will come up, allowing you to navigate to the desired file. Step 11 Click Execute. The Event Log should indicate that the file was transferred. 154 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Appendix C: Merlins Wand Scripting Commands Merlins Wand supports scripting commands to help automate testing pro-
cesses and commonly used sequences of Bluetooth commands. Custom scripts can be written, saved, and run in Script Manager. C.1 Bluetooth Addresses Bluetooth addresses are represented in scripts as binary strings in big-endian byte order. For example, the Bluetooth address 0x010203040506 would be represented in the script as:
DeviceAddress = '010203040506';
Comparisons can be performed using binary strings. For example:
if ( DeviceAddress == '010203040506' )
#do something based on comparison here
C.2 Basic Commands Main() Main() Parameter Meaning Default Value Comments N/A Return value None. Comments This is the entry point into a script. When a script is run, the scripts Main() function will be called. Include this command at the beginning of every script. Example Main()
155 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands
#include body of script here
Clock() Clock() Parameter Meaning Default Value Comments N/A Return value The number of milliseconds that have elapsed since the system was started. Comments This function returns the amount of time that the system has been running. It can be used to find out how long it takes to run a script or a series of commands within a script. Example time1 = Clock();
# Put script commands here time2 = Clock();
Trace("Elapsed time is ", time2-time1, "\n");
Connect() Connect(Address) Meaning Default Value Comments Bluetooth address of device to con-
nect with Parameter Address Return value Success Already connected Timed out Failed: Disconnection in progress Failure Comments Establishes an ACL connection with the specified device 156 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands result = Connect(Devices[0]);
if(result != "Success")
MessageBox("Failed to connect!");
Disconnect() Disconnect(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device to con-
nect with Return value Success Failure Timed out Comments Closes the ACL connection with the specified device Example result = Disconnect(Devices[0]);
if(result != "Success")
MessageBox("Failed to disconnect!");
DoInquiry() DoInquiry(IAC, Timeout) Parameter Meaning Default Value Comments IAC Timeout Inquiry Access Code Timeout in units of 1.2 seconds GIAC GIAC, or a 32-bit integer value 5 157 CATC MERLINS WAND 1.22 Users Manual Return value APPENDIX C Merlins Wand Scripting Commands Array of Bluetooth addresses that were found during the inquiry. Comments Calling DoInquiry() will block for the duration specified by Timeout. The function returns an array of devices that were found during the inquiry. These can be addressed individually. The current version of Merlin's Wand hardware only supports GIAC inquiries. Example
# Use default parameters Devices = DoInquiry();
Trace("First device was: ", Devices[0]);
GetDeviceClass() GetDeviceClass() Parameter Meaning Default Value Comments N/A Return value Class of device Failure Comments Returns the current device class of Merlins Wand Example Trace("Merlin's Wand device class: ", GetDeviceClass());
GetRemoteDeviceName() GetRemoteDeviceName(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device in question 158 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Return value Device name Not connected Failure Comments Queries the specified device for its name. An ACL connection must be established before calling GetRemoteDevice-
Name(). Example Trace("Device ", Devices[0], "is named ", GetRemoteDeviceName(Devices[0]));
MessageBox() MessageBox(Message, Caption) Parameter Message Meaning Default Value Comments Text to display in the mes-
sage box Caption Caption of the message box Script Mes-
sage Return value None. Comments Bring up a simple message box function with one OK button. This is a good way to pause execution of the script or indicate errors. Example MessageBox("Failed to connect", "Connection Failure");
SetDeviceClass() SetDeviceClass(Class) Parameter Meaning Default Value Comments Class Device class for Merlin's Wand Device class is a 3-byte value 159 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Return value Success Failure Comments Sets the device class of Merlins Wand Example SetDeviceClass(0x010203);
Sleep() Sleep(Time) Parameter Meaning Default Value Comments Time Time in ms Return value None. Comments Delays program execution for Time in milliseconds. Example Sleep(1000); # Sleep for one second C.3 Pipe Commands ClosePipe() ClosePipe(PipeName, PipeType) Parameter PipeName Meaning Default Value Comments Name of the data pipe to open PipeType Transmit or Receive Receive pipe Return value Success 160 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failure Pipe Not Found Invalid parameter Comments Closes the specified data pipe. Example ClosePipe("Data1", "Receive");
DeletePipe() DeletePipe(PipeName, PipeType) Parameter PipeName Meaning Default Value Comments Name of the data pipe to open PipeType Transmit or Receive Receive pipe Return value Success Invalid parameter Pipe not found Comments Removes a pipe from the Data Transfer Manager pipe list. In the case of Receive pipes, all data associated with the pipe is lost. Transmit pipes will only be removed from the Data Transfer Manager list. Example DeletePipe("Data1", "Receive");
OpenPipe() OpenPipe(PipeName, PipeType) Parameter PipeName Meaning Default Value Comments Name of the data pipe to open 161 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter PipeType Meaning Default Value Comments Transmit or Receive Receive pipe Return value Success Failure Pipe Not Found Comments Opens a data pipe for reading or writing. If the data pipe type is Receive and the pipe does not exist, a new pipe will be created. All open pipes will be automatically closed upon script termination. Example OpenPipe("Data1", "Receive");
ReadPipe() ReadPipe(PipeName, PipeType, ByteCount) Meaning Default Value Comments Name of the data pipe to open Transmit or Receive pipe Number of bytes to read 1-65535 Parameter PipeName PipeType ByteCount Return values Returns a list with three values: result, bytes read, and data. Result (element 0) is one of the following:
Success Failure Invalid parameter Pipe not found Pipe not open Bytes read (element 1) is the number of bytes read in this transaction. Valid only if result is Success. 162 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Data (element 2) is the raw data received in the transaction. Valid only if result is Success. Comments Reads the specified amount of data from an open pipe. Example result = ReadPipe("Data1", "Receive", 1024);
if(result[0] == "Success")
Trace("Read ", result[1], "bytes:\n");
Trace(result[2]);
WritePipe() WritePipe(PipeName, Data) Parameter PipeName Data Meaning Default Value Comments Name of the data pipe to open Data to write to the pipe This can be a string, integer, list or raw data. Return value Success Failure Pipe not found Pipe not open Not supported Comments Writes data to the specified pipe. Note that only Receive pipes can be written to. Example result = WritePipe("Data1", "This is a string written to a pipe");
result = WritePipe("Data1", '3C7EFFFF7E3C');
result = WritePipe("Data1", 0x01020304);
163 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands C.4 HCI Commands HCIAcceptConnectionRequest() HCIAcceptConnectionRequest() Parameter Meaning Default Value Comments N/A Return value Success Comments Sets the accept connection request variable to True. Example status = HCIAcceptConnectionRequest();
HCIAddSCOConnection() HCIAddSCOConnection(Address, Type) Parameter Address Type Meaning Default Value Comments Bluetooth address of device to con-
nect with Type of SCO connection to establish
[HV3]
A list of one or more of the following strings:
DM1, HV1, HV3 or DV Return value Success Not connected Not supported Failure Comments Attempts to establish an SCO connection with the specified device. An ACL connection must already be established with the device before calling HCIAddSCOConnection. 164 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands result = HCIAddSCOConnection(Devices[0], ["DM1", "HV1"]);
if(result != "Success")
MessageBox(result, "Failed to add SCO connection!");
HCIAuthenticationRequested() HCIAuthenticationRequested(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device to authenticate with A connection must exist with this device for an authentication request to work. Return value Success Failure Failed: Device not found Timed Out Not connected Comments Attempts to authenticate an existing link with the specified device. Example result = HCIAuthenticationRequested (Devices[0]);
if(result != "Success")
MessageBox(result, "Failed to authenticate!");
HCICatcBerTest() HCICatcBerTest(Address, NumberOfPackets, BERPacketType, TestDataType, TestData, BERInterval) Parameter Address Meaning Default Value Comments Bluetooth address of the remote device 165 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter NumberOf Packets BERPacket Type TestDataType TestData BERInterval Meaning Default Value Comments The number of baseband packets to be transmitted 0x0000 - an unlimited number of packets 0x0001 - 0xFFFF - number of packets 0x00 - DH1 0x01 - DH3 0x02 - DH5 0x03 - DM1 0x04 - DM3 0x05 - DM5 0x00 - send Bluetooth test mode PRBS 0x01 - every octet equals TestData Data to send A packet is sent every BERInterval frame Return value Success Failure Not connected Comments This command is used to measure BER when fully loaded baseband pack-
ets are sent from master to slave on the link. Example Trace("Test Control : ", HCICatcTestControl(Address,1,1,2,2,4), "\n");
Trace("Enter Test Mode : ", HCICatcEnterTestMode(Address),
"\n");
Trace("BER Test : ", HCICatcBerTest(Address,1,3,0,0xFF,10),
"\n");
HCICatcChangeHeadsetGain() HCICatcChangeHeadsetGain(Device, Gain) Parameter Meaning Default Value Comments Device Speaker or microphone Values: Speaker, Microphone 166 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter Meaning Default Value Comments Gain New gain of the device Values: 0 0xF Return value Success Failure Not connected No SCO connection Comments This command is used to change gain of connected speaker or microphone. In order to use this command, an SCO connection must exist. Example Main()
result = Connect('00803713BDF0');
Trace("Connection result : ", result, "\n");
if( result == "Success")
result = HCIAddSCOConnection( '00803713BDF0',
["HV1"]);
Trace("SCO Connection result : ", result, "\n");
if( result == "Success")
index = 0;
while(index < 16)
index);
index);
result = HCICatcChangeHeadsetGain("Speaker", Trace("Change speaker gain: ", result, "\n");
result = HCICatcReadHeadsetGain("Speaker", Trace("Read speaker gain: ", result, "\n");
index = index + 1;
Sleep(2000);
index = 0;
while(index < 16)
result =
HCICatcChangeHeadsetGain("Microphone", index);
Trace("Change microphone gain: ", result,
"\n");
result = HCICatcReadHeadsetGain("Microphone");
Trace("Read microphone gain : ", result, "\n");
index = index + 1;
167 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Sleep(2000);
status = HCIRemoveSCOConnection('00803713BDF0');
Trace("SCO disconnect result: ", status, "\n");
status = Disconnect('00803713BDF0');
Trace("Disconnect result: ", status, "\n");
HCICatcEnterTestMode() HCICatcEnterTestMode(Address) Parameter Address Meaning Default Value Comments Bluetooth address of remote device Return value Success Failure Not found Not connected Comments This command is used to put the remote device identified by its Bluetooth address into test mode. Example See the example for HCICatcBerTest command. HCICatcReadHeadsetGain() HCICatcReadHeadsetGain(Device) Parameter Meaning Default Value Comments Device Speaker or microphone Values: Speaker, Microphone Return values Returns a list with two values: status and gain. Status (element 0) is one of the following:
168 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Success Failure Not found No SCO connection Gain (element 1) is the one-byte value of the headset gain. Range is 0 to 15. Comments This command is used to read current gain of connected speaker or micro-
phone. In order to use this command, an SCO connection must exist. Example See the example for the HCICatcChangeHeadsetGain command. HCICatcReadRevisionInformation() HCICatcReadRevisionInformation() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and revision. Status (element 0) is one of the following:
Success Failure Revision (element 1) is the Merlins Wand revision information. Comments This command returns the information about the current firmware. Example Revision = HCICatcReadRevisionInformation();
if( Revision[0] == "Success") Trace("Merlin's Wand Revision Info : ", Revision[1], "\n");
169 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCICatcSelfTest() HCICatcReadRevisionInformation() Parameter Meaning Default Value Comments N/A Return value Success Failure Comments This command is used to perform a self test on a local device. Example Trace("Merlin's Wand Self Test : ", HCICatcSelfTest(),
"\n");
HCICatcTestControl() HCICatcTestControl(Address, TestScenario, HoppingMode, TxFrequency, RxFrequency, TestPacketType) Meaning Default Value Comments Bluetooth address of the remote device Parameter Address TestScenario HoppingMode TxFrequency RxFrequency TestPacket Type Return value Success Failure Not found 0x00 - DH1 0x01 - DH3 0x02 - DH5 0x03 - DM1 0x04 - DM3 0x05 - DM5 170 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Not connected Comments This command is used to start a specific test for the slave device identified by Bluetooth address. See Bluetooth LMP specification, page 246 for description of the parameters. Example See the example for HCICatcBerTest command. HCICatcWriteCountryCode() HCICatcWriteCountryCode(CountryCode) Meaning Default Value Comments 0x00 North America and Europe 0x01 France Parameter CountryCode Return value Success Failure Comments This command is used to define which range of the ISM 2.4 GHz fre-
quency band will be used by the radio. The device has to be reset after using this command. Example result = HCICatcWriteCountryCode(0);
Trace("Change CountryCode: ", result, "\n");
Trace("Don't forget to reset the device afterward!\n");
HCIChangeConnectionLinkKey() HCIChangeConnectionLinkKey(Address) Meaning Default Value Comments Bluetooth address of the remote Parameter Address Return value Success 171 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failure Not found Not connected Comments This command is used to force both devices associated with a connection to generate a new link key. Example result = HCIChangeConnectionLinkKey('00803713BDF0');
Trace("Change Connection Link Key: ", result, "\n");
HCIChangeConnectionPacketType() HCIChangeConnectionPacketType(Address, PacketType) Parameter Address PacketType Meaning Default Value Comments Bluetooth address of device to con-
nect with DH1 DH3 DH5 DM1 DM3 DM5 AUX1 HV1 HV2 HV3 DV Return value Success Failure Not found Not connected Not supported Comments This command is used to change which baseband packet type can be used for a connection 172 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands result = HCIChangeConnectionPacketType('00803713BDF0',
["DM3","DM5"]);
Trace("Change Connection Packet Type:\n");
Trace(" Status ", result[0], "\n");
HCIChangeLocalName() HCIChangeLocalName(Name) Parameter Meaning Default Value Comments Name String that contains the new name for the local device Return value Success Failure Comments Attempts to change the name of the local device. Example result = HCIChangeLocalName("Joe's Device");
if(result != "Success")
MessageBox(result, "Failed to change name!");
HCIDeleteStoredLinkKey() HCIDeleteStoredLinkKey(Address, DeleteAll) Parameter Address Meaning Default Value Comments Bluetooth address of device that will have its link key deleted 173 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Meaning Default Value Comments 0 0 or 1 Boolean value that indicates whether to delete only the specified address's link key, or all link keys Parameter DeleteAll Return value Success Failure Comments Attempts to delete the stored link key for the specified address or for all addresses, depending on the value of DeleteAll. Example result = HCIDeleteStoredLinkKey('6E8110AC0008', 1);
if(result != "Success")
MessageBox(result, "No link keys were deleted.");
HCIEnableDeviceUnderTestMode() HCIEnableDeviceUnderTestMode() Parameter Meaning Default Value Comments N/A Return value Success Failure Comments This command will allow the local Bluetooth device to enter a test mode via LMP test commands Example result = HCIEnableDeviceUnderTestMode();
Trace("Enabled DUT : ", result, "\n");
174 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIExitParkMode() HCIExitParkMode(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device in question Return value Success Failure Failed: Device not found Not connected Comments Switches the current role of the device in the piconet. Example Device = '010203040506';
result = HCIExitParkMode(Device);
Trace("HCIExitParkMode result is: ", result, "\n");
HCIExitSniffMode() HCIExitSniffMode(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device in question Return value Success Failure Failed: Device not found Not connected Comments Exits Sniff mode. Example Device = '010203040506';
175 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands result = HCIExitSniffMode(Device);
Trace("HCIExitSniffMode result is: ", result, "\n");
HCIHoldMode() HCIHoldMode(Address, MaxInterval, MinInterval) Parameter Address MaxInterval MinInterval Meaning Default Value Comments Bluetooth address of device in question Maximum number of 0.625-msec intervals to wait in Hold mode. Minimum number of 0.625-msec intervals to wait in Hold mode. Range is 0x0001 to 0xFFFF
(0.625 msec to 40.9 sec). Range is 0x0001 to 0xFFFF
(0.625 msec to 40.9 sec). Return value Success Failure Failed: Device not found Not connected Comments Enters Hold mode with parameters as specified. Example Device = '010203040506';
result = HCIHoldMode(Device, 0xFFFF, 0x50);
Trace("HCIHoldMode result is: ", result, "\n");
176 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIMasterLinkKey() HCIMasterLinkKey(KeyFlag) Parameter KeyFlag Return values Meaning Default Value Comments 0x0 use semi-permanent link keys 0x1 use temporary link keys Returns a list with three values: status, HCI handle, and key flag. Status (element 0) is one of the following:
Success Failure HCI handle (element 1) is the handle for the ACL connection. Key flag (element 2) is the key flag (either 0 or 1). Comments This command is used to force the master of the piconet to use temporary or semi-permanent link keys. Example result = HCIMasterLinkKey(0);
Trace("Merlin's Wand MasterLinkKey returned:", result[0],
"\n");
if(result[0] == "Success")
Trace(" Connection Handle : 0x", result[1], "\n");
Trace(" Key Flag : 0x", result[2], "\n");
HCIParkMode() HCIParkMode(Address, BeaconMaxInterval, BeaconMinInterval) Parameter Address Meaning Default Value Comments Bluetooth address of device in question 177 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter Beacon MaxInterval Beacon MinInterval Meaning Default Value Comments Range is 0x0001 to 0xFFFF
(0.625 msec to 40.9 sec). Range is 0x0001 to 0xFFFF
(0.625 msec to 40.9 sec). Maximum number of 0.625-msec intervals between bea-
cons. Minimum number of 0.625-msec intervals between bea-
cons. Return value Success Failure Failed: Device not found Not connected Comments Enters Park mode with parameters as specified. Example Device = '010203040506';
result = HCIParkMode(Device, 0xFFFF, 0x100);
Trace("HCIParkMode result is: ", result, "\n");
HCIPINCodeRequestNegativeReply() HCIPINCodeRequestNegativeReply(Address) Meaning Default Value Comments Bluetooth address of device for which no PIN code will be supplied. Parameter Address Return value Success Failure 178 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands Specifies a device for which no PIN code will be supplied, thus causing a pair request to fail. Example result = HCIPINCodeRequestNegativeReply('6C421742129F9');
Trace("HCIPINCodeRequestNegativeReply returned: ", result,
"\n");
HCIPINCodeRequestReply() HCIPINCodeRequestReply(Address, PINCode) Meaning Default Value Comments Bluetooth address of device for which PIN code will be used. PIN code to use when con-
necting to the device. Must be 1 to 16 characters in length. Parameter Address PINCode Return value Success Failure Comments Specifies the PIN code to use for a connection. Example result = HCIPINCodeRequestReply('6C421742129F9', "New PIN Code");
Trace("HCIPINCodeRequestReply returned: ", result, "\n");
179 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIQoSSetup() HCIQoSSetup(Address, ServiceType, TokenRate, PeakBandwidth, Latency, DelayVariation) Parameter Address ServiceType TokenRate Peak Bandwidth Latency Delay Variation Meaning Default Value Comments Bluetooth address of the remote The one-byte service type:
0=No traffic;
1=Best effort;
2=Guaranteed The four-byte token rate value in bytes per second The four-byte peak band-
width value in bytes per sec-
ond The four-byte latency value in microsec-
onds The four-byte delay varia-
tion value in microseconds Return values Returns a list with eight values: status, HCI handle, flags, service type, token rate, peak bandwidth, latency, and delay variation. Status (element 0) is one of the following:
Success Failure HCI handle (element 1) is the handle for the ACL connection. Flags (element 2) is a one-byte value reserved for future use. Service type (element 3) is the one-byte service type. (0=No traffic; 1=Best effort; 2=Guaranteed.) 180 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Token rate (element 4) is the four-byte token rate value in bytes per second. Peak bandwidth (element 5) is the four-byte peak bandwidth value in bytes per second. Latency (element 6) is the four-byte latency value in microseconds. Delay variation (element 7) is the four-byte delay variation value in micro-
seconds. Comments This command is used to specify Quality of Service parameters for the con-
nection. Example QoS = HCIQoSSetup('00803713BDF0', 2, 0, 0, 0x12345678, 0x23456789);
Trace("Merlin's Wand Link QoS Setup returned: ", QoS[0],
"\n");
if (QoS[0] == "Success")
Trace(" Connection Handle : 0x", QoS[1], "\n");
Trace(" Flags : 0x", QoS[2], "\n");
Trace(" Service Type : 0x", QoS[3], "\n");
Trace(" Token Rate : 0x", QoS[4], "\n");
Trace(" Peak Bandwidth : 0x", QoS[5], "\n");
Trace(" Latency : 0x", QoS[6], "\n");
Trace(" Delay Variation : 0x", QoS[7], "\n\n");
HCIReadAuthenticationEnable() HCIReadAuthenticationEnable() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and authentication enable. Status (element 0) is one of the following:
Success Failure Authentication enable (element 1) is the one-byte authentication enable value. (0=Authentication disabled; 1=Authentication enabled.) 181 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands This command will read the value for AuthenticationEnable parameter. Example result = HCIReadAuthenticationEnable();
if(result[0] == "Success") Trace("Merlin's Wand Authentication Enabled : ", result[1],
"\n");
HCIReadBDADDR() HCIReadBDADDR() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and address. Status (element 0) is one of the following:
Success Failure Address (element 1) is the address of the local device. Comments This command is used to read the value for the BD_ADDR parameter. The BD_ADDR is a 48-bit unique identifier for a Bluetooth device. Example LocalAddress = HCIReadBDADDR();
if(LocalAddress [0] == "Success") Trace("Local BDADDR:", LocalAddress[1], "\n");
HCIReadBufferSize() HCIReadBufferSize() Parameter Meaning Default Value Comments N/A Return values Returns a list with five values: status, ACL packet length, SCO packet length, ACL number of packets, and SCO number of packets. 182 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Status (element 0) is one of the following:
Success Failure ACL packet length (element 1) is the two-byte value of the maximum length (in bytes) of the data portion of each HCI ACL data packet that the Host Controller is able to accept. SCO packet length (element 2) is the one-byte value of the maximum length (in bytes) of the data portion of each HCI SCO data packet that the Host Controller is able to accept. ACL number of packets (element 3) is the total number of HCI ACL data packets that can be stored in the data buffers of the Host Controller. SCO number of packets (element 4) is the total number of HCI SCO data packets that can be stored in the data buffers of the Host Controller. Comments This command is used to read the maximum size of the data portion of SCO and ACL data packets sent from the Host to Host Controller. Example Trace("Local Buffer parameters\n");
result = HCIReadBufferSize();
Trace(" HCIReadBufferSize() returned: ", result[0],
"\n");
if (result[0] == "Success")
Trace(" ACL Data Packet Length : 0x", result[1],
"\n");
Trace(" SCO Data Packet Length : 0x", result[2],
"\n");
Trace(" Total Num ACL Data Packets : 0x", result[3],
"\n");
Trace(" Total Num SCO Data Packets : 0x", result[4],
"\n");
183 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIReadClockOffset() HCIReadClockOffset(Address) Meaning Default Value Comments Bluetooth address of device to con-
nect with. Parameter Address Return values Returns a list with two values: status and offset. Status (element 0) is one of the following:
Success Failure Failed: Device not found Not connected Offset (element 1) is the two-byte value of the clock offset. Comments Reads the clock offset to remote devices. Example result = HCIReadClockOffset();
Trace("HCIReadClockOffset returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Clock offset is: 0x", result[1], "\n");
HCIReadConnectionAcceptTimeout() HCIReadConnectionAcceptTimeout() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and timeout. Status (element 0) is one of the following:
Success Failure 184 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Timeout (element 1) is the two-byte value of the timeout, interpreted as multiples of 0.625-msec intervals. Comments Reads the current timeout interval for connection. The timeout value defines the time duration from when the Host Controller sends a Connec-
tion Request event until the Host Controller automatically rejects an incoming connection. Example result = HCIReadConnectionAcceptTimeout();
Trace("ReadConnectionAcceptTimeout returned: ", result[0],
"\n");
if (result[0] == "Success")
Trace("Timeout value is: 0x", result[1], "\n");
HCIReadCountryCode() HCIReadCountryCode() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and country code. Status (element 0) is one of the following:
Success Failure Country code (element 1) is the one-byte country code value. (0=North America and Europe; 1=France.) Comments Reads the country code value. This value defines which range of frequency band of the ISM 2.4-GHz band is used by the device. Example result = HCIReadCountryCode();
Trace("HCIReadCountryCode returned: ", result[0], "\n");
if (result[0] == "Success")
185 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Trace("Country code is: 0x", result[1], "\n");
HCIReadCurrentIACLAP() HCIReadCurrentIACLAP() Parameter Meaning Default Value Comments N/A Return value Returns a list with two values: status and Current IAC LAP. Status (element 0) is one of the following:
Success Failure Current IAC LAP (element 1) is the 3-byte value of the LAPs (Lower Address Part) that make up the current IAC (Inquiry Access Code). Comments Reads the number and values of the currently used IAC LAPs. Example result = HCIReadCurrentIACLAP();
if(result[0] == "Success")
Trace("Current number of used IAC LAPs is: ", result[1],
"\n");
if(result[1] > 0)
Trace("Currently used IAC LAPs are:");
for(i = 0; i < result[1]; i = i + 1)
Trace(" 0x", result[2 + i]);
Trace("\n\n");
186 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIReadEncryptionMode() HCIReadEncryptionMode() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and encryption mode. Status (element 0) is one of the following:
Success Failure Encryption mode (element 1) is the one-byte encryption mode value.
(0=Encryption disabled; 1=Encryption enabled for point-to-point packets only; 2=Encryption enabled for both point-to-point and broadcast packets.) Comments Reads the encryption mode value. This value controls whether the local device requires encryption to the remote device at connection setup. Example result = HCIReadEncryptionMode();
Trace("HCIReadEncryptionMode returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Encryption mode is: 0x", result[1], "\n");
HCIReadLinkPolicySettings() HCIReadLinkPolicySettings(Address) Parameter Address Return value Meaning Default Value Comments Bluetooth address of device in question Returns the following list of values: status and link policy settings. Status (element 0) is one of the following:
Success 187 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failure Failed: Device not found Not connected Link policy settings (element 1) is the two-byte value of the link policy set-
tings. Comments Reads the value of the Link_Policy_Settings parameter for the device. Example Device = '010203040506';
result = HCIReadLinkPolicySettings(Device);
Trace("HCIReadLinkPolicySettings returned: ", result[0],
"\n");
if (result[0] == "Success")
Trace("Link Policy Settings : ", result[1] ,"\n");
HCIReadLinkSupervisionTimeout() HCIReadLinkSupervisionTimeout(Address) Parameter Address Return value Meaning Default Value Comments Bluetooth address of device in question Returns the following list of values: status and link supervision timeout. Status (element 0) is one of the following:
Success Failure Failed: Device not found Not connected Link supervision timeout (element 1) is the timeout, interpreted as multi-
ples of 0.625-msec intervals. Comments Reads the value for the Link_Supervision_Timeout parameter for the device. 188 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands Device = '010203040506';
result = HCIReadLinkSupervisionTimeout(Device);
Trace("HCIReadLinkSupervisionTimeout returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Link Supervision Timeout is: ", result[1] ,"\n");
HCIReadLocalName() HCIReadLocalName() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and name. Status (element 0) is one of the following:
Success Failure Name (element 1) is a string representing the device name. Comments Reads the user-friendly name of the local Bluetooth device. Example result = HCIReadLocalName();
Trace("HCIReadLocalName returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Local device name is: ", result[1], "\n");
HCIReadLocalSupportedFeatures() HCIReadLocalSupportedFeatures() Parameter Meaning Default Value Comments N/A 189 CATC MERLINS WAND 1.22 Users Manual Return values APPENDIX C Merlins Wand Scripting Commands Returns a list with two values: status and features. Status (element 0) is one of the following:
Success Failure Features (element 1) is the eight-byte bit mask list of Link Manager Proto-
col features. Comments Reads the LMP supported features for the local device. Example result = HCIReadLocalSupportedFeatures();
Trace("HCIReadLocalSupportedFeatures returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Local supported features data is: ", result[1],
"\n");
HCIReadLocalVersionInformation() HCIReadLocalVersionInformation() Parameter Meaning Default Value Comments N/A Return values Returns a list with six values: status, HCI version, HCI revision, LMP ver-
sion, manufacturer name, and LMP subversion. Status (element 0) is one of the following:
Success Failure HCI version (element 1) is the one-byte HCI version value. (0=1.0B, 1=1.1.) HCI revision (element 2) is the two-byte HCI revision value. LMP version (element 3) is the one-byte Link Manager Protocol version value. 190 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Manufacturer name (element 4) is the two-byte manufacturer name of the Bluetooth hardware. LMP subversion (element 5) is the two-byte Link Manager Protocol sub-
version value. Comments Reads the version information for the local device. Example result = HCIReadLocalVersionInformation();
Trace("HCIReadLocalVersionInformation returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("HCI version is: 0x", result[1], "\n");
Trace("HCI revision is: 0x", result[2], "\n");
Trace("LMP version is: 0x", result[3], "\n");
Trace("Manufacturer name is: 0x", result[4], "\n");
Trace("LMP subversion is: 0x", result[5], "\n");
HCIReadLoopbackMode() HCIReadLoopbackMode() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and loopback mode. Status (element 0) is one of the following:
Success Failure Loopback mode (element 1) is the one-byte loopback mode value. (0=No loopback mode; 1=Local loopback mode; 2=Remote loopback mode.) Comments Reads the loopback mode value. This value determines the path by which the Host Controller returns information to the Host. Example result = HCIReadLoopbackMode();
Trace("HCIReadLoopbackMode returned: ", result[0], "\n");
191 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands if (result[0] == "Success")
Trace("Loopback mode is: 0x", result[1], "\n");
HCIReadNumberOfSupportedIAC() HCIReadNumberOfSupportedIAC() Parameter Meaning Default Value Comments N/A Return value Returns a list with two values: status and number of supported IAC. Status is one of the following:
Success Failure Number of supported IAC is a 1-byte value that specifies the number of Inquiry Access Codes that the local Bluetooth device can listen for at one time. Comments Reads the number of supported IACs. Example result = HCIReadNumberOfSupportedIAC ();
Trace("HCIReadNumberOfSupportedIAC returned: ", result[0],
"\n");
if (result[0] == "Success")
Trace("The number of supported IAC is: ", result[1],
"\n\n");
HCIReadPageScanMode() HCIReadPageScanMode() Parameter Meaning Default Value Comments N/A 192 CATC MERLINS WAND 1.22 Users Manual Return values APPENDIX C Merlins Wand Scripting Commands Returns a list with two values: status and page scan mode. Status (element 0) is one of the following:
Success Failure Page scan mode (element 1) is the one-byte page scan mode value.
(0=Mandatory page scan mode; 1=Optional page scan mode I; 2=Optional page scan mode II; 3=Optional page scan mode III.) Comments Reads the page scan mode value. This value indicates the mode used for default page scan. Example result = HCIReadPageScanMode();
Trace("HCIReadPageScanMode returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Page scan mode is: 0x", result[1], "\n");
HCIReadPageScanPeriodMode() HCIReadPageScanPeriodMode() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and page scan period mode. Status (element 0) is one of the following:
Success Failure Page scan period mode (element 1) is the one-byte page scan period mode value. (0=P0; 1=P1; 2=P2.) Comments Reads the page scan period mode value. Each time an inquiry response message is sent, the Bluetooth device will start a timer, the value of which depends on the page scan period mode. 193 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands result = HCIReadPageScanPeriodMode();
Trace("HCIReadPageScanPeriodMode returned: ", result[0],
"\n");
if (result[0] == "Success")
Trace("Page scan period mode is: 0x", result[1], "\n");
HCIReadPageTimeout() HCIReadPageTimeout() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and page timeout. Status (element 0) is one of the following:
Success Failure Page timeout (element 1) is the two-byte page timeout value, in increments of 0.625-msec intervals. Comments Reads the page timeout value. This value defines the maximum time the local Link Manager will wait for a baseband page response from the remote device at a locally initiated connection attempt. Example result = HCIReadPageTimeout();
Trace("HCIReadPageTimeout returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Page timeout is: 0x", result[1], "\n");
194 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIReadPINType() HCIReadPINType() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and PIN type. Status (element 0) is one of the following:
Success Failure PIN type (element 1) is the one-byte PIN type. (0=Variable PIN; 1=Fixed PIN.) Comments Reads the PIN type, which determines whether the Host supports variable PIN codes or only a fixed PIN code. Example result = HCIReadPINType();
Trace("HCIReadPINType returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("PIN type is: 0x", result[1], "\n");
HCIReadRemoteSupportedFeatures() HCIReadRemoteSupportedFeatures(Address) Meaning Default Value Comments Bluetooth address of device to con-
nect with. Parameter Address Return values Returns a list with two values: status and features. Status (element 0) is one of the following:
Success Failure 195 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failed: Device not found Not connected Features (element 1) is the eight-byte bit mask list of Link Manager Proto-
col features. Comments Reads the LMP supported features for the specified device. An ACL con-
nection with the device is required. Example Device = '010203040506';
result = HCIReadRemoteSupportedFeatures(Device);
Trace("HCIReadRemoteSupportedFeatures returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Remote supported features data is: 0x", result[1], "\n");
HCIReadRemoteVersionInformation() HCIReadRemoteVersionInformation(Address) Meaning Default Value Comments Bluetooth address of device to con-
nect with. Parameter Address Return values Returns a list with four values: status, LMP version, manufacturer name, and LMP subversion. Status (element 0) is one of the following:
Success Failure Failed: Device not found Not connected LMP version (element 1) is the one-byte Link Manager Protocol version value. Manufacturer name (element 2) is the two-byte manufacturer name of the Bluetooth hardware. 196 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands LMP subversion (element 3) is the two-byte Link Manager Protocol sub-
version value. Comments Reads the version information for the specified device. An ACL connec-
tion with the device is required. Example Address = '010203040506';
result = HCIReadRemoteVersionInformation(Address);
Trace("HCIReadRemoteVersionInformation returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("LMP version is: 0x", result[1], "\n");
Trace("Manufacturer name is: 0x", result[2], "\n");
Trace("LMP subversion is: 0x", result[3], "\n");
HCIReadScanEnable() HCIReadScanEnable() Parameter Meaning Default Value Comments N/A Return value GENERAL_ACCESSIBLE LIMITED_ACCESSIBLE NOT_ACCESSIBLE CONNECTABLE_ONLY Failure Comments Retrieves the current accessible mode of Merlins Wand. Example Trace("Merlin's Wand accessible mode: ", HCIReadScanEnable());
197 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIReadSCOFlowControlEnable() HCIReadSCOFlowControlEnable() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and SCO flow control enable. Status (element 0) is one of the following:
Success Failure SCO flow control enable (element 1) is the one-byte SCO flow control value. (0=SCO flow control disabled; 1=SCO flow control enabled.) Comments Reads the SCO flow control enable value. This value determines whether the Host Controller will send Number Of Completed Packets events for SCO Connection Handles. Example result = HCIReadSCOFlowControlEnable();
Trace("HCIReadSCOFlowControlEnable returned: ", result[0],
"\n");
if (result[0] == "Success")
Trace("SCO flow control enable is: 0x", result[1],
"\n");
HCIReadStoredLinkKey() HCIReadStoredLinkKey(Address, ReadAll) Parameter Address Meaning Default Value Comments Bluetooth address of device that will have its link key read 198 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter ReadAll Meaning Default Value Comments 0 0 or 1 Boolean value that indicates whether to read only the specified address's link key, or all link keys Return values Returns a list with two values: status and data. Status (element 0) is one of the following:
Success Failure Data (element 1) is a list containing zero or more pairs of the following two values:
BDADDR: the Bluetooth Address that the link key corresponds to LinkKey: the link key for the specified address Comments Attempts to read the stored link key for the specified address or for all addresses, depending on the value of ReadAll. Example result = HCIReadStoredLinkKey('6E8110AC0008', 1);
Trace("HCIReadStoredLinkKey() returned: ", result[0],
"\n\n");
if (result[0] == "Success")
list = result[1];
i = 0;
while (list[(i*2)] != null)
Trace("************************\n");
Trace("BDADDR: ", list[(i*2)], "\n");
Trace("Link Key: ", list[(i*2)+1], "\n");
Trace("************************\n");
i = i + 1;
199 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIReadVoiceSetting() HCIReadVoiceSetting() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and voice setting. Status (element 0) is one of the following:
Success Failure Voice setting (element 1) is the 10-bit voice setting value. Comments Reads the voice setting value. This value controls all settings for voice con-
nections. Example result = HCIReadVoiceSetting();
Trace("HCIReadVoiceSetting returned: ", result[0], "\n");
if (result[0] == "Success")
Trace("Voice setting is: 0x", result[1], "\n");
HCIRejectConnectionRequest() HCIRejectConnectionRequest() Parameter Meaning Default Value Comments N/A Return value Success Comments Sets the accept connection request variable to False. Example status = HCIRejectConnectionRequest();
Trace("HCIRejectConnectionRequest returned: ", status,
"\n\n");
200 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIRemoveSCOConnection() HCIRemoveSCOConnection(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device to con-
nect with Return value Success Not connected Failure Comments Removes an existing SCO connection associated with the specified device. Example result = HCIRemoveSCOConnection(Devices[0]);
HCIReset() HCIReset() Parameter Meaning Default Value Comments N/A Return value Success Failure Invalid parameter Failed: Invalid Type Failed: HCI initialization error Comments Resets the Host Controller and Link Manager. Example result = HCIReset();
201 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIRoleDiscovery() HCIRoleDiscovery(Address) Parameter Address Meaning Default Value Comments A connection must exist with this address for Role Discovery to work. Bluetooth address of device rela-
tive to which we want to know our role Return value Master Slave Failure Failed: Device not found Not connected Comments Attempts to discover the role of our device relative to the specified device. Example result = HCIRoleDiscovery('6E8110AC0108');
if(result != "Success")
MessageBox(result, "Failed to get role!");
else
Trace("Our role is: ", result, "\n\n");
HCISetConnectionEncryption() HCISetConnectionEncryption(Address, SetEncryption) Parameter Address Meaning Default Value Comments Bluetooth address of device whose encryption to enable or dis-
able 202 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter Meaning Default Value Comments 0 0 or 1 A connection must be established and authenti-
cated before you can enable encryption success-
fully SetEncryption Boolean value that indicates whether to enable or dis-
able encryp-
tion Return value Success Failure Timed Out Failed: Device not found Not connected Comments Enables and disables the link-level encryption for the address specified Example result = HCISetConnectionEncryption('6E8110AC0108', 0);
if(result != "Success")
MessageBox(result, "Failed to disable encryption!");
HCISetEventFilter() HCISetEventFilter(FilterType, FilterConditionType, Condition) Parameter FilterType Filter Condition Type Meaning Default Value Comments Filter type:
0 = Clear all filters;
1 = Inquiry result;
2 = Connec-
tion setup;
3-255 =
Reserved Type of filter condition. If value 0 is used, no other parameters should be supplied. This parameter has different meanings depending on the filter type. 203 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter Condition Meaning Default Value Comments Details of the filter to be set. Must be entered as a series of bytes within brack-
ets, e.g., [0x1, 0x12, 0x0F]. Byte values must be entered in hex notation separated by commas. Return value Success Failure Invalid parameter Comments Instructs the Host Controller to send only certain types of events to the Host. Examples
# Clear All Filters result = HCISetEventFilter(0);
Trace("Result of clearing all filters: ", result, "\n");
# Inquiry Result result = HCISetEventFilter(1, 2,
[0xA,0x1,0x24,0x12,0xFB,0xAA]);
Trace("Result of Inquiry Result filter: ", result, "\n");
# Connection Setup result = HCISetEventFilter(2, 0, [0x1]);
Trace("Result of Connection Setup filter: ", result, "\n");
HCISniffMode() HCISniffMode(Address, MaxInterval, MinInterval, Attempt, Timeout) Parameter Address MaxInterval Meaning Default Value Comments Range is 0x0001 to 0xFFFF
(0.625 msec to 40.9 sec). Bluetooth address of device in question Maximum number of 0.625-msec intervals between sniff periods. 204 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter MinInterval Attempt Timeout Meaning Default Value Comments Minimum number of 0.625-msec intervals between sniff periods. Number of receive slots for sniff attempt. Number of receive slots for sniff time-
out. Range is 0x0001 to 0xFFFF
(0.625 msec to 40.9 sec). Range is 0x0001 to 0x7FFF
(0.625 msec to 20.5 sec). Range is 0x0001 to 0x7FFF
(0.625 msec to 20.5 sec). Return value Success Failure Failed: Device not found Not connected Comments Enters Sniff mode with parameters as specified. Example Device = '010203040506';
result = HCISniffMode(Device, 0xFFFF, 100, 0x3FF6, 0x7FFF);
Trace("HCISniffMode result is: ", result, "\n");
HCISwitchRole() HCISwitchRole(Address, Role) Parameter Address Meaning Default Value Comments Bluetooth address of device in question Role Values: Master, Slave Return value Success Failure 205 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failed: Device not found Not connected Invalid parameter Comments Switches the current role of the device in the piconet. Example Device = '010203040506';
result = HCISwitchRole(Device, "Slave");
Trace("HCISwitchRole result is: ", result, "\n\n");
HCIWriteAuthenticationEnable() HCIWriteAuthenticationEnable(AuthenticationEnable) Parameter Meaning Default Value Comments AuthenticationEnable 0 Authentica-
tion value:
0 = Authenti-
cation dis-
abled;
1 = Authenti-
cation enabled for all connec-
tions;
2-255 =
Reserved Return value Success Failure Invalid parameter Comments Controls whether the local device is required to authenticate the remote device at connection setup. Example result = HCIWriteAuthenticationEnable(0);
206 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIWriteConnectionAcceptTimeout() HCIWriteConnectionAcceptTimeout(Interval) Parameter Interval Meaning Default Value Comments 0x1FA0 (= 5 sec) Range is 0x0001 to 0xB540 (0.625 msec to 29 sec). Number of 0.625-msec intervals before the connection request times out. Return value Success Failure Invalid parameter Comments Sets a timeout interval for connection. The parameter defines the time duration from when the Host Controller sends a Connection Request event until the Host Controller automatically rejects an incoming connection. Example result = HCIWriteConnectionAcceptTimeout(0x1234);
HCIWriteCurrentIACLAP() HCIWriteCurrentIACLAP(NumCurrentIACs, IACLAPs) Parameter NumCurrent IACs IACLAPs Meaning Default Value Comments Must be 1 or 2. The number of values in this list must match the NumCurrentIACs parameter. Number of current IACs. List of IAC_LAPs, each with a value in the range 0x9E8B00-0x 9E8B3F. Return value Success Failure Invalid parameter 207 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands Writes the number and values of the IAC LAPs to be used. One of the val-
ues has to be the General Inquiry Access Code, 0x9E8B33. Example result = HCIWriteCurrentIACLAP(2, 0x9E8B33, 0x9E8B34);
Trace("Result of HCIWriteCurrentIACLAP: ", result, "\n\n");
HCIWriteEncryptionMode() HCIWriteEncryptionMode(EncryptionMode) Parameter Encryption Mode Meaning Default Value Comments 0 Encryption mode:
0 = Encryp-
tion disabled;
1 = Encryp-
tion enabled for point-to-point packets only;
2 = Encryp-
tion enabled for both point-to-point and broadcast packets;
3-255=Reserv ed Return value Success Failure Invalid parameter Comments Controls whether the local device requires encryption to the remote device at connection setup. Example result = HCIWriteEncryptionMode(0);
208 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIWriteLinkPolicySettings() HCIWriteLinkPolicySettings(Address, LinkPolicySettings) Meaning Default Value Comments Bluetooth address of device in question Range is 0x0000-0x8000. Parameter Address LinkPolicy Settings Return value Success Failure Failed: Device not found Not connected Comments Writes the value for the Link_Policy_Settings parameter for the device. Example Device = '010203040506';
result = HCIWriteLinkPolicySettings(Device, 0xF);
Trace("HCIWriteLinkPolicySettings result is: ", result,
"\n\n");
HCIWriteLinkSupervisionTimeout() HCIWriteLinkSupervisionTimeout(Address, Timeout) Parameter Address Timeout Meaning Default Value Comments Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec). Bluetooth address of device in question Number of 0.625-msec intervals before con-
nection request times out. 209 APPENDIX C Merlins Wand Scripting Commands CATC MERLINS WAND 1.22 Users Manual Return value Success Failure Failed: Device not found Not connected Comments Writes the value for the Link_Supervision_Timeout parameter for the device. Example Device = '010203040506';
result = HCIWriteLinkSupervisionTimeout(Device, 0x7D00);
Trace("HCIWriteLinkSupervisionTimeout result is: ", result[0], "\n\n");
HCIWriteLoopbackMode() HCIWriteLoopbackMode(LoopbackMode) Parameter Loopback Mode Meaning Default Value Comments 0 Loopback mode:
0 = No loop-
back mode;
1 = Local loopback mode;
2 = Remote loopback mode;
3-255 =
Reserved Return value Success Failure Invalid parameter Comments Determines the path by which the Host Controller returns information to the Host. Example result = HCIWriteLoopbackMode(2);
210 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands HCIWritePageTimeout() HCIWritePageTimeout(Interval) Parameter Interval Meaning Default Value Comments 0x2000 (=
5.12 sec) Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec). Number of 0.625-msec intervals before the connection attempt times out. Return value Success Failure Invalid parameter Comments Sets the maximum time the local Link Manager will wait for a baseband page response from the remote device at a locally initiated connection attempt. Example result = HCIWritePageTimeout(0x4000);
HCIWritePINType() HCIWritePINType(PINType) Parameter PINType Meaning Default Value Comments PIN type:
0=Variable PIN;
1=Fixed PIN Range is 0 to 1. Return value Success Failure Invalid parameter Comments Determines whether the Host supports variable PIN codes or only a fixed PIN code. 211 APPENDIX C Merlins Wand Scripting Commands CATC MERLINS WAND 1.22 Users Manual Example result = HCIWritePINType(0);
HCIWriteScanEnable() HCIWriteScanEnable(AccessibleMode) Parameter Accessible Mode Meaning Default Value Comments Access mode to set Merlin's GENERAL_ ACCESSI-
Wand BLE Mode can be one of:
GENERAL_ACCESSIBLE, NOT_ACCESSIBLE, CONNECTABLE_ONLY Return value Success Timed out Failure Comments Sets the accessible mode of Merlins Wand. Example HCIWriteScanEnable("CONNECTABLE_ONLY");
HCIWriteStoredLinkKey() HCIWriteStoredLinkKey(Address, LinkKey) Parameter Address LinkKey Meaning Default Value Comments Bluetooth address of device that will have its link key stored String contain-
ing the link key to be stored Up to 32 Hex digits Return value Success Failure 212 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands Attempts to store the link key for the specified address. If a link key already exists for the specified address, it will be overwritten. Example result = HCIWriteStoredLinkKey('6E8110AC0108', "ABC123");
Trace("HCIWriteStoredLinkKey() returned: ", result,
"\n\n");
HCIWriteVoiceSettings() HCIWriteVoiceSettings(Address, VoiceSetting) Parameter Address VoiceSetting Meaning Default Value Comments Bluetooth address of device whose voice settings to write Three-digit hex value con-
taining the voice settings Possible values:
0x0060=CVSD coding 0x0061=u-Law coding 0x0062=A-law coding Return value Success Failure Timed Out Failed: Device not found Not connected Comments Attempts to write the voice settings for the specified address. A connection must be established before voice settings can be written. Example result = HCIWriteVoiceSettings('6E8110AC0108', 0x0060);
Trace("HCIWriteVoiceSettings() returned: ", result,
"\n\n");
213 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands C.5 OBEX Commands OBEXClientConnect() OBEXClientConnect(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device to con-
nect with Return value Success Failure Failed: Busy Failed: Not connected Failed: Packet too small Comments Establishes an OBEX client connection with the specified device. Example result = OBEXClientConnect(Devices[0]);
if(result != "Success")
MessageBox("Failed to establish OBEX connection.");
OBEXClientDeinit() OBEXClientDeinit() Parameter Meaning Default Value Comments N/A Return value Failure Comments This command is obsolete. It is provided for backward compatibility only.
(The application is initialized as an OBEX client at startup and cannot be deinitialized.) 214 APPENDIX C Merlins Wand Scripting Commands CATC MERLINS WAND 1.22 Users Manual Example result = OBEXClientDeinit();
OBEXClientDisconnect() OBEXClientDisconnect() Parameter Meaning Default Value Comments N/A Return value Success Failure Failed: Busy Failed: Not connected Failed: Packet too small Comments Breaks the current OBEX client connection. Example result = OBEXClientDisconnect();
OBEXClientGet() OBEXClientGet(RemotePath, LocalPath) Parameter RemotePath LocalPath Meaning Default Value Comments Path and name of object to be retrieved from server. Path and name of object to be created on cli-
ent. RemotePath argument Path is relative to servers OBEX directory. Example: If the OBEX directory is C:\temp, a RemotePath of file.txt would cause the client to retrieve C:\temp\file.txt If omitted, object will be stored to the local OBEX directory with the name it has on the server. If specified as a relative path (i.e., without a drive letter), the path will be considered relative to the OBEX directory. If specified as a full path (i.e., with a drive letter), the object will be stored to the exact name and path specified. Return value Success 215 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failure Failed: Busy Failed: Not connected Failed: Packet too small Failed: Invalid handle Comments Retrieves object from a server and saves it to the client. If directory names are included in either path argument, be sure to use double-slashes to separate components (e.g., temp1\\temp2\\file-
name.txt). Using single slashes will cause errors. Note that the second argument may be omitted, in which case the object will be stored to the clients OBEX directory with the same name it has on the server. Examples In these examples, the local OBEX directory is assumed to be c:\obexdir.
#store file to "file.txt" in local OBEX directory
# (i.e., c:\obexdir\file.txt) OBEXClientGet("file.txt");
#store file to "newfile.txt" in temp dir under OBEX dir
# (i.e., c:\obexdir\temp\newfile.txt) OBEXClientGet("file.txt", "temp\\newfile.txt");
#store file to "file.txt" in C:\temp OBEXClientGet("file.txt", "C:\\temp\\file.txt");
#get file from a directory below the servers OBEX dir,
# and save it with the same name to the same directory
# below the local OBEX dir (i.e.,
"c:\obexdir\temp\file.txt") OBEXClientGet("temp\\file.txt");
OBEXClientInit() OBEXClientInit() Parameter Meaning Default Value Comments N/A Return value Success 216 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands This command is obsolete. It is provided for backward compatibility only.
(The application is initialized as an OBEX client at startup and cannot be deinitialized.) Example result = OBEXClientInit();
OBEXClientPut() OBEXClientPut(LocalPath, RemotePath) Parameter LocalPath RemotePath Meaning Default Value Comments Full (not rela-
tive) path and name of file to be sent from client. Path and name of object to be stored on server. Name-only portion of LocalPath argument Path is relative to servers OBEX directory. Example: If the servers OBEX directory is C:\Temp, a RemotePath of file.txt would cause the server to save the file to C:\Temp\file.txt. Note that you cannot save a file to an absolute path on the server. Return value Success Failure Failed: Busy Failed: Invalid handle Failed: Invalid parameter Failed: Media busy Failed: Not connected Failed: Packet too small Comments Sends a file to the OBEX directory of the server. If directory names are included in either path argument, be sure to use double-slashes to separate components (e.g., temp1\\temp2\\file-
name.txt). Using single slashes will cause errors. Note that the second argument may be omitted, in which case the object will be stored to the servers OBEX directory with the same name it has on the client. 217 CATC MERLINS WAND 1.22 Users Manual Examples APPENDIX C Merlins Wand Scripting Commands In these examples, the servers OBEX directory is assumed to be c:\obexdir.
#store file to "file.txt" in servers OBEX directory
# (i.e., c:\obexdir\file.txt) OBEXClientPut("c:\\temp\\file.txt");
#store file to "newfile.txt" in servers OBEX dir
# (i.e., c:\obexdir\newfile.txt) OBEXClientPut("c:\\temp\\file.txt", "newfile.txt");
#store file to "newfile.txt" in temp dir under OBEX dir
# (i.e., c:\obexdir\temp\newfile.txt) OBEXClientPut("c:\\temp\\file.txt", "temp\\newfile.txt");
OBEXClientSetPath() OBEXClientSetPath(Path, Flags) Parameter Meaning Default Value Comments Path is relative to servers current working direc-
tory. Cannot begin C: or \\\\. When backup is set (flag = 1 or 3), the working directory is backed up one level before the speci-
fied directory is appended (e.g., if the servers current working directory is C:\Temp, a SetPath of Temp2 with a flag of 1 would change the directory to C:\Temp2). To set path to the OBEX root directory, use an empty path and a flag of 0 or 2. Path Flags New path to set SetPath flags:
0=No flags 1=Back up one level 2=Dont cre-
ate specified folder if it doesnt exist 3=Back up one level and don't create specified folder Return value Success Failure Failed: Busy Failed: Not connected Failed: Packet too small Failed: Invalid parameter 218 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands Temporarily changes a server's current working directory, accessed by cli-
ents during ClientGet and ClientPut operations. The device must be connected to an OBEX server before the command can be successfully executed. The change is lost when the connection is broken. Note that the servers OBEX root directory cannot be changed with this command. If the path includes multiple levels, be sure to use double-slashes to sepa-
rate components (e.g., temp1\\temp2). Using single slashes will cause errors. Example
#set path to <root>
status = OBEXClientSetPath("", 0);
Sleep(1000);
#set path to <root>\temp2 status = OBEXClientSetPath("temp2", 0);
Sleep(1000);
#set path to <root>\temp2\temp3 status = OBEXClientSetPath("temp3", 0);
Sleep(1000);
#set path to <root>\temp2 status = OBEXClientSetPath("", 1);
Sleep(1000);
#keep path at <root>\temp2 (assuming <root>\temp2\temp4 doesn't exist) status = OBEXClientSetPath("temp4", 2);
Sleep(1000);
#set path to <root>\temp3\temp4 status = OBEXClientSetPath("temp3\\temp4", 1);
OBEXServerDeinit() OBEXServerDeinit() Parameter Meaning Default Value Comments N/A Return value Success Failure 219 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failed: Busy Comments Deinitializes an OBEX server. Example result = OBEXServerDeinit();
OBEXServerSetPath(Path) OBEXServerSetPath(Path) Parameter Meaning Default Value Comments Path Path to be used as the OBEX root directory on the server Path must be fully specified (e.g., C:\\temp rather than temp) Return value Success Failure Failed: Device must be initialized as a server Comments Sets the OBEX root directory on a server. This path is accessed by clients during remote ClientGet and ClientPut operations. The device must be initialized as a server before the command can be successfully executed. In the path, be sure to use double-slashes to separate components (e.g., C:\\temp\\temp2). Using single slashes will cause errors. Example status = OBEXServerInit();
if ( status == "Success" )
status = OBEXServerSetPath("c:\\temp");
Trace("OBEXServerSetPath returned: ", status, "\n\n");
220 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands C.6 RFCOMM Commands RFCloseClientChannel() RFCloseClientChannel(Address, DLCI) Parameter Address DLCI Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier The DLCI is returned by RFOpenClientChan-
nel() Return value Success Not connected Failure Timed out Comments Closes an RFCOMM channel Example RFCloseClientChannel(Devices[0], DLCI);
RFOpenClientChannel() RFOpenClientChannel(Address, ServerID) Meaning Default Value Comments Bluetooth address of device Service ID for RFCOMM channel Parameter Address ServerID Return value The return value from RFOpenClientChannel is a list containing up to two elements. The first element is the status of the command and is one of the following strings:
221 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Success Failure Timed out Not connected Restricted If the return value is Success, the second element in the list is the DLCI of the established connection. Comments An ACL connection must already be established with the device. Example result = RFOpenClientChannel(Devices[0], 1);
if(result[0] == "Success")
Trace("Successfully connected with DLCI ", result[1],
"\n");
# Send some data over RFCOMM
RFRegisterServerChannel() RFRegisterServerChannel() Parameter Meaning Default Value Comments N/A Return value Server channel ID Failure Comments Example channel = RFRegisterServerChannel();
if(channel != "Failure")
Trace("Channel ID is ", channel);
222 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands RFSendData() RFSendData(Address, DLCI, Data) Parameter Address DLCI Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier Can use CONNECTED_DEVICE to send data to a master RFCOMM connection. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Data Data to send Data can be a string, 32-bit integer value or a list containing either or both types Return value Success Timed out Not supported (invalid data type) Not connected Comments An RFCOMM connection must already be established with the device. Example RFSendData(Devices[0], DLCI, "ATDT 555-1212");
RFSendData("CONNECTED_DEVICE", dlci, "AT+CKPD=200\r\n");
RFSendDataFromPipe() RFSendDataFromPipe(Address, DLCI, PipeName) Parameter Address DLCI PipeName Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier Name of the transmit data pipe to get data to send Can use CONNECTED_DEVICE to send data to a master RFCOMM connection The DLCI is returned by RFOpenClientChan-
nel() This pipe must exist. 223 APPENDIX C Merlins Wand Scripting Commands CATC MERLINS WAND 1.22 Users Manual Return value Success Timed out Not supported (invalid data type) Not connected Pipe not found Internal Error Comments An RFCOMM connection must already be established with the device. The pipe specified must already be set up in the Data Transfer Manager. The pipe should not be open when RFSendDataFromPipe is called. Example RFSendDataFromPipe(Devices[0], dlci, "MyPipe");
RFSendDataFromPipe("CONNECTED_DEVICE", dlci, "Pipe2");
RFReceiveData() RFReceiveData(Address, DLCI, Timeout) Parameter Address DLCI Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier Can use "CONNECTED_DEVICE" to receive data from a master RFCOMM connection The DLCI is returned by RFOpenClientChan-
nel() Timeout Time in ms to 0 (Infinite Use 0 as the timeout value to wait infinitely wait for an RFCOMM connection wait) Return value Returns a list with three values: status, number of bytes, and data array. Status (element 0) is one of the following:
Success Not connected Timed out Number of bytes (element 1) is the number of bytes received. Data array (element 2) is the sequence of data bytes received. 224 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands Receives data from a device connected via RFCOMM. Waits Timeout mil-
liseconds (or infinitely if 0 is specified) for the device to begin sending data to Merlin's Wand. Example
#Get the data; stop when no data is received for 5 secs result = RFReceiveData(Device, DLCI, 5000);
while(result[0] == "Success")
Trace("Number of data bytes received: ", result[1],
"\n");
result = RFReceiveData(Device, DLCI, 5000);
RFWaitForConnection() RFWaitForConnection(ServerID, Timeout) Parameter ServerID Meaning Default Value Comments Service ID for RFCOMM channel Timeout Time in ms to 0 (Infinite Use 0 as the timeout value to wait infinitely. wait for an RFCOMM connection wait) Return value Returns a list with three values: status, DLCI, and BluetoothDevice. Status (element 0) is one of the following:
Success Timed out Failure DLCI (element 1) is the data link connection identifier. BluetoothDevice (element 2) is the address of the connecting device. Comments Waits Timeout milliseconds for a device to establish an RFCOMM connec-
tion with Merlins Wand. This function will block the specified amount of time (or infinitely if 0 is specified) unless a connection is established. If an 225 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands RFCOMM connection is already present when this function is called, it will immediately return Success. Example
# Wait 3 seconds for RFCOMM connection Trace("RFWaitForConnection\n");
result = RFWaitForConnection(1, 3000);
if( result[0] == "Success" )
Trace("Incoming RFCOMM connection DLCI: ", result[1],
"\n");
Trace("Connecting device address: ", result[2], "\n");
RFAcceptChannel() RFAcceptChannel(bAccept) Parameter Meaning Default Value Comments bAccept Boolean value 0 0 or 1 indicating whether to accept the channel or not Return value Success Comments Example status = RFAcceptChannel(1);
Trace("RFAcceptChannel returned: ", status, "\n\n");
RFAcceptPortSettings() RFAcceptPortSettings(bAccept) Parameter Meaning Default Value Comments bAccept Boolean value 0 0 or 1 indicating whether to accept the channel or not 226 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Return value Success Comments Example status = RFAcceptPortSettings(0);
Trace("RFAcceptPortSettings returned: ", status, "\n\n");
RFCreditFlowEnabled() RFCreditFlowEnabled(Address, DLCI) Parameter Address DLCI Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier Can use CONNECTED_DEVICE to check if credit flow is enabled on a master RFCOMM connection. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Return value Enabled Disabled Not Connected Comments Checks to see if credit flow is enabled on a particular RFCOMM connec-
tion. Example result = RFOpenClientChannel(Device, 1);
DLCI = result[1];
if(result[0] == "Success")
status = RFCreditFlowEnabled("CONNECTED_DEVICE", DLCI);
Trace("RFCreditFlowEnabled returned: ", status, "\n\n");
227 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands RFRequestPortSettings() RFRequestPortSettings(Address, DLCI, BaudRate, DataFormat, FlowControl, Xon, Xoff) Meaning Default Value Comments Can use CONNECTED_DEVICE to request port settings on a master RFCOMM connection. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Can be 2400, 4800, 7200, 9600, 19200, 38400, 57600, 115200, 230400 Can be RF_DATA_BITS_5, RF_DATA_BITS_6, RF_DATA_BITS_7, RF_DATA_BITS_8, RF_STOP_BITS_1, RF_STOP_BITS_1_5, RF_PARITY_NONE, RF_PARITY_ON, RF_PARITY_TYPE_ODD, RF_PARITY_TYPE_EVEN, RF_PARITY_TYPE_MARK, RF_PARITY_TYPE_SPACE, RF_DATA_BITS_MASK, RF_STOP_BITS_MASK, RF_PARITY_MASK, RF_PARITY_TYPE_MASK Can be RF_FLOW_CTRL_NONE, RF_XON_ON_INPUT, RF_XON_ON_OUTPUT, RF_RTR_ON_INPUT, RF_RTR_ON_OUTPUT, RF_RTC_ON_INPUT, RF_RTC_ON_OUTPUT, RF_FLOW_RTS_CTS, RF_FLOW_DTR_DSR, RF_FLOW_XON_XOFF Parameter Address DLCI BaudRate DataFormat Bluetooth address of device Data link con-
nection identi-
fier String contain-
ing the baud rate List of strings containing data bits, stop bits, and parity settings FlowControl List of strings indicating port flow control options Xon Xoff Number indi-
cating the XON charac-
ter Number indi-
cating the XOFF charac-
ter 228 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Return value Success Failure Not connected Timed Out Comments Submits a request to change the port settings on a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1);
DLCI = result[1];
if(result[0] == "Success")
status = RFRequestPortSettings("CONNECTED_DEVICE", DLCI,
"57600", ["RF_DATA_BITS_8"], ["RF_FLOW_CTRL_NONE"], 11, 13);
Trace("RFRequestPortSettings returned: ", status,
"\n\n");
RFRequestPortStatus() RFRequestPortStatus(Address, DLCI) Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier Can use CONNECTED_DEVICE to request the port status on a master RFCOMM connec-
tion. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Parameter Address DLCI Return value Returns a list with two values: status and portSettings. Status (element 0) is one of the following:
Success Failure Not Connected Timed Out portSettings (element 1) is a list containing the following five values:
229 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands BaudRate (element 0) is a string containing the baud rate DataFormat (element 1) is a string containing data bits, stop bits, and parity settings Xon (element 3) is a string containing the XON character Xoff (element 4) is a string containing the XOFF character FlowControl (element 2) is a string indicating port flow control options Comments Requests the port settings on a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1);
DLCI = result[1];
if(result[0] == "Success")
res = RFRequestPortStatus(Device, DLCI);
Trace("RFRequestPortStatus returned: ", res[0], "\n\n");
if (res[0] == "Success")
settingsList = res[1];
Trace("BaudRate: ", settingsList[0], "\n");
Trace("DataFormat: ", settingsList[1], "\n");
Trace("Xon: ", settingsList[3], "\n");
Trace("Xoff: ", settingsList[4], "\n");
RFSetLineStatus() RFSetLineStatus(Address, DLCI, LineStatus) Parameter Address DLCI LineStatus Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier List of strings representing the Line Status Can use CONNECTED_DEVICE to set line status on a master RFCOMM connection. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Can be RF_LINE_ERROR, RF_OVERRUN, RF_PARITY, RF_FRAMING Return value Success 230 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Failure Not Connected Timed Out Comments Sets the line status on a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1);
DLCI = result[1];
if(result[0] == "Success")
status = RFSetLineStatus("CONNECTED_DEVICE", DLCI,
["RF_LINE_ERROR", "RF_FRAMING"]);
Trace("RFSetLineStatus returned: ", status, "\n\n");
RFSetModemStatus() RFSetModemStatus(Address, DLCI, ModemSignals, BreakLength) Parameter Address DLCI ModemSignals BreakLength Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier List of strings specifying sig-
nal types Indicates the length of the break signal in 200 ms units Can use CONNECTED_DEVICE to set modem status on a master RFCOMM connec-
tion. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Can be RF_FLOW, RF_RTC, RF_RTR, RF_IC, RF_DV, RF_DSR, RF_CTS, RF_RI, RF_CD, RF_DTR, RF_RTS Must be between 0 and 15 (inclusive). If 0, no break signal was sent. Return value Success Failure Not Connected Timed Out 231 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands Sets the modem status on a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1);
DLCI = result[1];
if(result[0] == "Success")
status = RFSetModemStatus("CONNECTED_DEVICE", DLCI,
["RF_FLOW"], 3);
Trace("RFSetModemStatus returned: ", status, "\n\n");
RFSendTest() RFSendTest(Address, DLCI) Parameter Address DLCI Meaning Default Value Comments Bluetooth address of device Data link con-
nection identi-
fier Can use CONNECTED_DEVICE to send a test frame on a master RFCOMM connection. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Return value Success Failure Not Connected Failure Comments Sends a test frame on a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1);
DLCI = result[1];
if(result[0] == "Success")
status = RFSendTest("CONNECTED_DEVICE", DLCI);
Trace("RFSendTest returned: ", status, "\n\n");
232 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands RFAdvanceCredit() RFAdvanceCredit(Address, DLCI, credit) Parameter Address DLCI credit Meaning Default Value Comments Can use CONNECTED_DEVICE to advance a credit to a master RFCOMM connection. Note that this will work only if exactly one device is connected via RFCOMM. The DLCI is returned by RFOpenClientChan-
nel() Bluetooth address of device Data link con-
nection identi-
fier Number of credits to advance Return value Success Failure Not Connected Comments Advances a specified number of credits to a particular RFCOMM connec-
tion. Example result = RFOpenClientChannel(Device, 1);
DLCI = result[1];
if(result[0] == "Success")
status = RFAdvanceCredit(Device, DLCI, 2);
Trace("RFAdvanceCredit returned: ", status, "\n\n");
C.7 TCS Commands TCSRegisterProfile() TCSRegisterProfile() Parameter Meaning Default Value Comments N/A 233 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Return value Success Failure Comments Register Intercom profile with the application. Example result = TCSRegisterProfile();
Trace("TCSRegisterProfile returned: ", result, "\n");
TCSOpenChannel() TCSOpenChannel(Address) Parameter Address Meaning Default Value Comments Bluetooth address of device to con-
nect with Return value Success Failure Not Found Timed Out Comments This command opens an L2CAP channel with TCS PSM and initializes a TCS state machine into NULL state Example result = TCSOpenChannel(010203040506);
Trace("TCSOpenChannel result : ", result, "\n");
if( result != "Success") return result;
TCSStartCall() TCSStartCall() Parameter Meaning Default Value Comments N/A 234 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Return value Success Failure Comments This command must be called right after TCSOpenChannel. It automati-
cally sends a sequence of TCS messages according to the Intercom profile specification of the TCS state machine. After successful execution of this command, TCS state machine is in ACTIVE state and SCO connection is opened. Example result = TCSStartCall();
Trace("TCSStartCall result : ", result, "\n");
if( result != "Success") return result;
TCSDisconnectCall() TCSDisconnectCall() Parameter Meaning Default Value Comments N/A Return value Success Failure Comments This command is called to close an existing TCS connection according to the Intercom profile specification of the TCS state machine, close the L2CAP connection, and close the SCO connection. Example result = TCSDisconnectCall();
Trace("TCSDisconnectCall result : ", result, "\n");
if( result != "Success") return result;
235 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands TCSSendInfoMessage() TCSSendInfoMessage(Phone_Number) Parameter Meaning Default Value Comments Phone_Number Up to 10-digit Phone Num-
ber Return value Success Failure Invalid Parameter Comments This command can be called after a TCS channel is opened. It sends an INFORMATION TCS message with a called party number. Example result = TCSSendInfoMessage("4088447081");
Trace("TCSSendInfoMessage result : ", result, "\n");
if( result != "Success") return result;
Tested TCS Call initiation, information sending, #
and Call clearing #
Main()
#Device = '838010AC0008';
Device = DoInquiry();
Trace(Device, "\n");
result = Connect(Device[0]);
Trace("Connection result : ", result, "\n");
if( result != "Success") return result;
Sleep(1000);
result = TCSRegisterProfile();
Trace("TCSRegisterProfile result : ", result, "\n");
if( result != "Success") return result;
236 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Sleep(1000);
result = TCSOpenChannel(Device[0]);
Trace("TCSOpenChannel result : ", result, "\n");
if( result != "Success") return result;
Sleep(1000);
result = TCSStartCall();
Trace("TCSStartCall result : ", result, "\n");
if( result != "Success") return result;
Sleep(1000);
result = TCSSendInfoMessage("4088447081");
Trace("TCSSendInfoMessage result : ", result, "\n");
if( result != "Success") return result;
Sleep(1000);
result = TCSDisconnectCall();
Trace("TCSDisconnectCall result : ", result, "\n");
if( result != "Success") return result;
Sleep(1000);
Trace("HCI Disconnect result: ", Disconnect(Device[0]), "\n");
237 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands C.8 L2CAP Commands L2CAPConfigurationSetup() L2CAPConfigurationSetup(FlushTimeout, ServiceType, TokenRate, TokenBucketSize, PeakBandwidth, Latency, DelayVariation) Parameter Meaning Default Value Comments 0xFFFF Time is in milliseconds. 0x01 Possible values: 0x00 (no traffic), 0x01 (best effort),0x02 (guaranteed), Other (reserved) 0x00000000 0x00000000: no token rate is specified. 0xFFFFFFFF: a wild card value that matches the maximum token rate. Rate is in bytes per second. 0x00000000 0x00000000: no token bucket is needed. 0xFFFFFFFF: a wild card value that matches the maximum token bucket. Size is in bytes. 0x00000000 The default value indicates that the maximum bandwidth is unknown. The speed is in bytes per second. 0xFFFFFFFF The default value represents a Do Not Care. The delay is in milliseconds. FlushTimeout ServiceType TokenRate Amount of time that the sender will attempt trans-
mission before flushing the packet The required level of ser-
vice The rate at which traffic credits are granted TokenBucket Size The size of the token bucket PeakBandwidth Latency A value that limits the speed at which packets may be sent con-
secutively The maxi-
mum delay that is accept-
able between transmission of a bit and its initial trans-
mission over the air 238 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Parameter Meaning Default Value Comments DelayVariation This value 0xFFFFFFFF The default value represents a Do Not Care. The difference is in microseconds. represents the difference between the maximum and minimum delay possible that a packet will experi-
ence Return value Success Failure Comments This command is used to request specified configuration for L2CAP chan-
nel. It should be executed before L2CAPConnectRequest(). For a detailed description of parameters, see the L2CAP section of the Bluetooth Specification. Example L2CAPConfigurationSetup(0xFFFF, 1, 0, 0, 0, 0xFFFFFFFF, 0xFFFFFFFF);
L2CAPConfigurationResponse() L2CAPConfigurationResponse(Reason) Parameter Meaning Default Value Comments Reason Configuration Accept response Possible values:
Accept Reject-unknown options Reject-unacceptable params Reject Return value Success Failure Comments This command is used to automatically send the response to an incoming configuration request. It should be executed before an incoming configura-
tion request. 239 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands L2CAPConfigurationResponse("Reject-unknown options");
L2CAPConnectRequest() L2CAPConnectRequest(Address, PSM, ReceiveMTU) Meaning Default Value Comments Bluetooth address of the remote device 0x01C2 Parameter Address PSM ReceiveMTU Return value Returns a list with three values: result, ACL Handle, and a list of all L2CAP CIDs. Result (element 0) is one of the following:
Success Failure Not found Not connected ACL Handle (element 1) is a unique identifier for an ACL connection. List of all L2CAP CIDs (element 2) is a list of all channel identifiers for an L2CAP connection with a particular device. Comments This command is used to establish an L2CAP channel to the specified remote device. Example result = L2CAPConnectRequest('0080370DBD02', 0x1001, 0x1C2);
Trace("L2CAPConnectRequest returned: ", result[0], "\n");
if (result[0] == "Success")
Handle = result[1];
CID = result[2];
240 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands L2CAPConnectResponse() L2CAPConnectResponse(Response) Parameter Response Meaning Default Value Comments Accept Possible values:
Accept Reject_Pending Reject_PSM_Not_Supported Reject_Security_Block Reject_No_Resources Return value Success Failure Comments This command is used to send an automatic response to an incoming L2CAP connection request. Execute this command before an incoming connection request. Example L2CAPConnectResponse("Reject_No_Resources");
L2CAPDeregisterAllPsm() L2CAPDeregisterAllPsm() Parameter Meaning Default Value Comments N/A Return value Success Failure Comments This command is used to deregister all registered PSMs identifiers with L2CAP Example result = L2CAPDeregisterAllPsm();
Trace("DeregisterAllPsm : ", result, "\n");
241 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands L2CAPDisconnectRequest() L2CAPDisconnectRequest(CID) Parameter Meaning Default Value Comments CID L2CAP chan-
nel identifier Return value Success Failure Not connected Comments This command is used to disconnect specified L2CAP channel Example L2CAPDisconnectRequest(0x0040);
L2CAPEchoRequest() L2CAPEchoRequest(Address, Data) Meaning Default Value Comments Bluetooth address of the remote device Parameter Address Data Return value Returns a list with two values: status and data. Status (element 0) is one of the following:
Success Failure Not found Not connected Data (element 1) is the data returned by the remote device. Comments This command sends an Echo Request to the L2CAP protocol on the spec-
ified remote device. The data length should not exceed the default L2CAP signaling MTU (44 bytes). 242 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands result = L2CAPEchoRequest('838010AC0008', "Test");
Trace("L2CAPEchoRequest result : ", result[0], "\n");
if(result[0] == "Success")
Trace("Data : ", result[1], "\n");
L2CAPInfoRequest() L2CAPInfoRequest(Address) Meaning Default Value Comments Bluetooth address of the remote device Parameter Address Return values Returns a list with three values: status, number of bytes, and data. Status (element 0) is one of the following:
Success Failure Not found Not connected Number of bytes (element 1) is the number of bytes of data that follow. Data (element 2) is the raw data. Comments Sends an Info Request to the L2CAP protocol on the specified remote device. Info requests are used to exchange implementation-specific infor-
mation regarding L2CAPs capabilities. Example result = L2CAPInfoRequest('838010AC0008');
Trace("L2CAPInfoRequest result : ", result[0], "\n");
if(result[0] == "Success")
Trace("Data length : ", result[1], "\n");
Trace("Data : ", result[2], "\n");
243 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands L2CAPRegisterPsm() L2CAPRegisterPsm(PSM, ReceiveMTU) Parameter Meaning Default Value Comments 0x1C2 Incoming MTU size for L2CAP connection with that PSM PSM ReceiveMTU Return value Success Failure In use Comments This command is used to register a PSM identifier with L2CAP. Example Trace("Register PSM\n");
result = L2CAPRegisterPsm(0x1001, 0x1C2);
Trace(" Result : ", result, "\n");
L2CAPSendData() L2CAPSendData(ChannelID, Data) Parameter ChannelID Meaning Default Value Comments L2CAP Chan-
nelID to send data to Data Data to send Data can be a string, 32-bit integer value or a list containing either or both types Return value Success Timed out Not supported (invalid data type) Not connected Comments An L2CAP connection must already be established with the device. 244 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands result = L2CAPSendData(0x40, "test data");
Trace("Result : ", result, "\n");
L2CAPSendDataFromPipe() L2CAPSendDataFromPipe(ChannelID, PipeName) Parameter ChannelID PipeName Meaning Default Value Comments L2CAP Chan-
nelID to send data to Name of the transmit data pipe to get data to send This pipe must exist. Return value Success Timed out Not supported (invalid data type) Not connected Pipe not found Comments An L2CAP connection must already be established with the device. The pipe specified must already be set up in the Data Transfer Manager. The pipe should not be open when L2CAPSendDataFromPipe is called. Example L2CAPSendDataFromPipe(0x0040, "Pipe1");
L2CAPWaitForConnection() L2CAPWaitForConnection(Timeout) Parameter Timeout Meaning Default Value Comments Time in ms to 0 (Infinite Use 0 as the timeout value to wait infinitely. wait) wait for an incoming L2CAP con-
nection 245 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands Return value Success Timed out Comments Waits Timeout milliseconds for a device to establish an L2CAP connection with Merlin's Wand. This function will block the specified amount of time
(or infinitely if 0 is specified) unless a connection is established. Example Trace("L2CAPWaitForConnection\n");
result = L2CAPWaitForConnection();
if( result == "Success")
#Do something else
C.9 SDP Commands SDPAddProfileServiceRecord() SDPAddProfileServiceRecord(ServerChannel, Profile) Parameter Meaning Default Value Comments Use the result from RFRegisterServerChannel() here Profile can be one of:
Headset, HeadsetAudioGateway, Seri-
alPort, DialUp, FileTransfer, Fax, LAN, ObjectPush, Intercom, Cordless, Sync, SyncCommand Server Channel Profile RFCOMM server chan-
nel to accept incoming con-
nections to this profile Name of SDP profile Return value Success Failure Comments Adds a profile to Merlins Wand SDP database 246 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands SDPAddProfileServiceRecord(rfChannel, "ObjectPush");
SDPQueryProfile() SDPQueryProfile(Address, Profile) Meaning Default Value Comments Bluetooth address of device to query Name of SDP profile Profile can be one of:
Headset, HeadsetAudioGateway, Seri-
alPort, DialUp, FileTransfer, ObjectPush, Intercom, Cordless, Fax, LAN, Sync or SyncCommand Parameter Address Profile Return value RFCOMM channel of the requested profile (profile is supported) Failure Comments Queries the specified device to see if a profile is supported. An ACL connection must already be established with the device. Example if((RFCommId = SDPQueryProfile(Devices[0], "SerialPort"))
!= "Failure")
RFOpenClientChannel(Devices[0], RFCommId);
SDPResetDatabase() SDPResetDatabase() Parameter Meaning Default Value Comments N/A Return value Success Failure 247 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX C Merlins Wand Scripting Commands Clears all records out of the Merlins Wand SDP profile database. Example SDPResetDatabase();
SDPAddServiceRecord() SDPAddServiceRecord(FileName, RecordName, ServerChannel) Meaning Default Value Comments String contain-
ing the full path of the file that contains the record String contain-
ing the name of the service record to be added RFCOMM server channel 0 If you don't want to change the RFCOMM Server ID, set this value to 0 (or leave it blank) Parameter FileName RecordName ServerChannel Return value Success Failure Failure: Could not load file Failure: Record not found Failure: Could not set RFCOMM server channel X Comments If a server channel is specified, tries to set the RFCOMM server channel. If it succeeds, then it parses the file specified by FileName and tries to add the record specified by RecordName. Example status = SDPAddServiceRecord("C:\Records.sdp", "FTP Test Record", 1);
Trace("SDPAddServiceRecord returned: ", status, "\n\n");
248 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands C.10 Merlin Commands MerlinResetAllEncryptionOptions() MerlinResetAllEncryptionOptions() Parameter Meaning Default Value Comments N/A Return value Success Failure Comments This command is used to remove all previously associated link keys and PIN numbers. Example MerlinResetAllEncryptionOptions();
MerlinSetDisplayOptions() MerlinSetDisplayOptions(DispOptionsFile) Parameter Meaning Default Value Comments DispOptionsFile Name and full path to the dis-
play options file Return value Success Comments This command is used to set the display options file. Example MerlinSetDisplayOptions("C:\\Program Files\\CATC\\Merlin\\default.opt");
249 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands MerlinSetEncryptionLinkKey() MerlinSetEncryptionLinkKey(Address, LinkKey) Parameter Address LinkKey Meaning Default Value Comments Bluetooth Address Correspond-
ing PIN for the address LinkKey length must be no longer than 16 bytes Return value Success Failure Invalid parameter Comments This command is used to associate the LinkKey with the device address used to decrypt and display encrypted traffic. Example MerlinSetEncryptionLinkKey('008037BB2100',
"003344121222ACBBEE6172000FF0");
MerlinSetEncryptionPIN() MerlinSetEncryptionPIN(Address, PIN) Meaning Default Value Comments Bluetooth Address Correspond-
ing PIN for the address Parameter Address PIN Return value Success Failure Comments This command is used to associate the PIN number with the device address used to decrypt and display encrypted traffic. 250 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands MerlinSetEncryptionPIN('008037BB2100', "1234");
MerlinSetRecordingOptions() MerlinSetRecordingOptions(RecOptionsFile) Parameter Meaning Default Value Comments RecOptionsFile Name and full path to the recording options file Return value Success Comments This command is used to set the recording options file to be used for the next recording. Example MerlinSetRecordingOptions("C:\\CATC\\Merlin
\\default.rec");
MerlinStart() MerlinStart(RemoteMachine) Parameter Meaning Default Value Comments RemoteMachine can be a name or an IP address Remote Machine Specify a remote machine to start Merlin Return value Success Failure Already connected Comments This command is used to start Merlin on a specified remote machine or on a local machine by default. 251 CATC MERLINS WAND 1.22 Users Manual Example APPENDIX C Merlins Wand Scripting Commands result = MerlinStart("192.168.2.1");
Trace("Result : ", result, "\n");
MerlinStartRecording() MerlinStartRecording() Parameter Meaning Default Value Comments N/A Return value Success Failure Comments This command is used to start a Merlin recording. Example MerlinStartRecording();
MerlinStop() MerlinStop() Parameter Meaning Default Value Comments N/A Return value Success Comments This command is used to close the Merlin application. Example MerlinStop();
252 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands MerlinStopRecording() MerlinStopRecording() Parameter Meaning Default Value Comments N/A Return value Success Comments This command is used to stop a Merlin recording. Example MerlinStopRecording();
253 CATC MERLINS WAND 1.22 Users Manual APPENDIX C Merlins Wand Scripting Commands 254 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Appendix D: CATC Scripting Language CATC Scripting Language (CSL) was developed to allow users to automate test processes and provide textual output to suit specific needs. CSL is used in Merlins Wand to write traffic-generating scripts, making it possible to automate some Bluetooth command sequences. Scripts are written, saved, and run using the Script Manager utility. Scripts output can be viewed in the Script Log. CSL is based on C language syntax, so anyone with a C programming background will have no trouble learning CSL. The simple, yet powerful, structure of CSL also enables less experienced users to easily acquire the basic knowledge needed to start writing custom scripts. Features of CATC Scripting Language Powerful -- provides a high-level API to the Bluetooth stack while simultaneously allowing implementation of complex algorithms. Self-contained -- needs no external tools to run scripts. Easy to learn and use -- has a simple but effective syntax. Wide range of value types -- provides efficient and easy processing of data. Integrated with over 100 commands -- includes commands for HCI, L2CAP, SDP, RFCOMM, TCS, OBEX, data pipes, and the CATC Merlin Analyzer. General purpose -- is integrated in a number of CATC products. D.1 Values There are five value types that may be manipulated by a script: integers, strings, lists, raw bytes, and null. CSL is not a strongly typed language. Value types need not be pre-declared. Literals, variables and constants can take on any of the five value types, and the types can be reassigned dynamically. D.2 Literals Literals are data that remain unchanged when the program is compiled. Literals are a way of expressing hard-coded data in a script. Integers Integer literals represent numeric values with no fractions or decimal points. Hexadecimal, octal, decimal, and binary notation are supported:
255 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Hexadecimal numbers must be preceded by 0x: 0x2A, 0x54, 0xFFFFFF01 Octal numbers must begin with 0: 0775, 017, 0400 Decimal numbers are written as usual: 24, 1256, 2 Binary numbers are denoted with 0b: 0b01101100, 0b01, 0b100000 Strings String literals are used to represent text. A string consists of zero or more characters and can include numbers, letters, spaces, and punctuation. An empty string ("") contains no characters and evaluates to false in an expression, whereas a non-empty string evaluates to true. Double quotes surround a string, and some standard backslash (\) escape sequences are supported. String Represented text
"Quote: \"This is a string literal.\""
Quote: "This is a string literal."
"256"
"abcd!$%&*"
"June 26, 2001"
"[ 1, 2, 3 ]"
Escape Sequences 256 **Note that this does not represent the integer 256, but only the characters that make up the number. abcd!$%&*
June 26, 2001
[ 1, 2, 3 ]
These are the available escape sequences in CSL:
Character Escape Sequence Example Output backslash double quote horizontal tab newline single quote
\t
\n
"This is a backslash: \\" This is a backslash: \
"\"Quotes!\""
"Quotes!"
"Before tab\tAfter tab" Before tab After tab
"This is how\nto get a newline."
This is how to get a newline.
"\'Single quote\'"
'Single quote'
256 CATC MERLINS WAND 1.22 Users Manual Lists APPENDIX D CATC Scripting Language A list can hold zero or more pieces of data. A list that contains zero pieces of data is called an empty list. An empty list evaluates to false when used in an expression, whereas a non-empty list evaluates to true. List literals are expressed using the square bracket ([]) delimiters. List elements can be of any type, including lists.
[1, 2, 3, 4]
["one", 2, "three", [4, [5, [6]]]]
Raw Bytes Raw binary values are used primarily for efficient access to packet payloads. A literal notation is supported using single quotes:
'00112233445566778899AABBCCDDEEFF'
This represents an array of 16 bytes with values starting at 00 and ranging up to 0xFF. The values can only be hexadecimal digits. Each digit represents a nybble (four bits), and if there are not an even number of nybbles specified, an implicit zero is added to the first byte. For example:
'FFF'
is interpreted as
'0FFF'
Null Null indicates an absence of valid data. The keyword null represents a literal null value and evaluates to false when used in expressions. result = null;
D.3 Variables Variables are used to store information, or data, that can be modified. A variable can be thought of as a container that holds a value. All variables have names. Variable names must contain only alphanumeric characters and the underscore ( _ ) character, and they cannot begin with a number. Some possible variable names are x _NewValue name_2 257 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language A variable is created when it is assigned a value. Variables can be of any value type, and can change type with re-assignment. Values are assigned using the assignment operator ( = ). The name of the variable goes on the left side of the operator, and the value goes on the right:
x = [ 1, 2, 3 ]
New_value = x name2 = "Smith"
If a variable is referenced before it is assigned a value, it evaluates to null. There are two types of variables: global and local. Global Variables Global variables are defined outside of the scope of functions. Defining global variables requires the use of the keyword set. Global variables are visible throughout a file (and all files that it includes). set Global = 10;
If an assignment in a function has a global as a left-hand value, a variable will not be created, but the global variable will be changed. For example set Global = 10;
Function()
Global = "cat";
Local = 20;
will create a local variable called Local, which will only be visible within the function Function. Additionally, it will change the value of Global to "cat", which will be visible to all functions. This will also change its value type from an integer to a string. Local Variables Local variables are not declared. Instead, they are created as needed. Local variables are created either by being in a function's parameter list, or simply by being assigned a value in a function body. Function(Parameter)
Local = 20;
258 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language This function will create a local variable Parameter and a local variable Local, which has an assigned value of 20. D.4 Constants A constant is similar to a variable, except that its value cannot be changed. Like variables, constant names must contain only alphanumeric characters and the underscore ( _ ) character, and they cannot begin with a number. Constants are declared similarly to global variables using the keyword const:
const CONSTANT = 20;
They can be assigned to any value type, but will generate an error if used in the left-hand side of an assignment statement later on. For instance, const constant_2 = 3;
Function()
constant_2 = 5;
will generate an error. Declaring a constant with the same name as a global, or a global with the same name as a constant, will also generate an error. Like globals, constants can only be declared in the file scope. D.5 Expressions An expression is a statement that calculates a value. The simplest type of expression is assignment:
x = 2 The expression x = 2 calculates 2 as the value of x. All expressions contain operators, which are described in Section D.6, Operators, on page 261. The operators indicate how an expression should be evaluated in order to arrive at its value. For example x + 2 says to add 2 to x to find the value of the expression. Another example is 259 CATC MERLINS WAND 1.22 Users Manual x > 2 APPENDIX D CATC Scripting Language which indicates that x is greater than 2. This is a Boolean expression, so it will evaluate to either true or false. Therefore, if x = 3, then x > 2 will evaluate to true; if x = 1, it will return false. True is denoted by a non-zero integer (any integer except 0), and false is a zero integer (0). True and false are also supported for lists (an empty list is false, while all others are true), and strings (an empty string is false, while all others are true), and null is considered false. However, all Boolean operators will result in integer values. select expression The select expression selects the value to which it evaluates based on Boolean expressions. This is the format for a select expression:
select {
<expression1> : <statement1>
<expression2> : <statement2>
The expressions are evaluated in order, and the statement that is associated with the first true expression is executed. That value is what the entire expression evaluates to. x = 10 Value_of_x = select {
x < 5 : "Less than 5";
x >= 5 : "Greater than or equal to 5";
The above expression will evaluate to "Greater than or equal to 5" because the first true expression is x >= 5. Note that a semicolon is required at the end of a select expression because it is not a compound statement and can be used in an expression context. There is also a keyword default, which in effect always evaluates to true. An example of its use is Astring = select {
A == 1 : "one";
A == 2 : "two";
A == 3: "three";
A > 3 : "overflow";
default : null;
260 CATC MERLINS WAND 1.22 Users Manual
APPENDIX D CATC Scripting Language If none of the first four expressions evaluates to true, then default will be evaluated, returning a value of null for the entire expression. select expressions can also be used to conditionally execute statements, similar to C switch statements:
select {
A == 1 : DoSomething();
A == 2 : DoSomethingElse();
default: DoNothing();
In this case the appropriate function is called depending on the value of A, but the evaluated result of the select expression is ignored. D.6 Operators An operator is a symbol that represents an action, such as addition or subtraction, that can be performed on data. Operators are used to manipulate data. The data being manipulated are called operands. Literals, function calls, constants, and variables can all serve as operands. For example, in the operation x + 2 the variable x and the integer 2 are both operands, and + is the operator. Operations can be performed on any combination of value types, but will result in a null value if the operation is not defined. Defined operations are listed in the Operand Types column of the table on page 264. Any binary operation on a null and a non-null value will result in the non-null value. For example, if x = null;
then 3 * x will return a value of 3. A binary operation is an operation that contains an operand on each side of the operator, as in the preceding examples. An operation with only one operand is called a unary operation, and requires the use of a unary operator. An example of a unary operation is 261 CATC MERLINS WAND 1.22 Users Manual
!1 APPENDIX D CATC Scripting Language which uses the logical negation operator. It returns a value of 0. The unary operators are sizeof(), head(), tail(), ~ and !. Operator Precedence and Associativity Operator rules of precedence and associativity determine in what order operands are evaluated in expressions. Expressions with operators of higher precedence are evaluated first. In the expression 4 + 9 * 5 the * operator has the highest precedence, so the multiplication is performed before the addition. Therefore, the expression evaluates to 49. The associative operator () is used to group parts of the expression, forcing those parts to be evaluated first. In this way, the rules of precedence can be overridden. For example,
( 4 + 9 ) * 5 causes the addition to be performed before the multiplication, resulting in a value of 65. When operators of equal precedence occur in an expression, the operands are evaluated according to the associativity of the operators. This means that if an operator's associativity is left to right, then the operations will be done starting from the left side of the expression. So, the expression 4 + 9 - 6 + 5 would evaluate to 12. However, if the associative operator is used to group a part or parts of the expression, those parts are evaluated first. Therefore,
( 4 + 9 ) - ( 6 + 5 ) has a value of 2. In the following table, the operators are listed in order of precedence, from highest to lowest. Operators on the same line have equal precedence, and their associativity is shown in the second column. Operator Symbol
~ ! sizeof head tail
Associativity Left to right Right to left Left to right 262 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Operator Symbol
~ ! sizeof head tail
Associativity Right to left Left to right Right to left Left to right Left to right Left to right Left to right Left to right Left to right Left to right Left to right Left to right Left to right Right to left 263 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Operator Symbol Description Operand Types Result Types Examples Index Operator
Index or subscript Raw Bytes Integer Raw = '001122'
Raw[1] = 0x11 List Any List = [0, 1, 2, 3, [4, 5]]
List[2] = 2 List[4] = [4, 5]
List[4][1] = 5
*Note: if an indexed Raw value is assigned to any value that is not a byte ( > 255 or not an integer), the variable will be promoted to a list before the assignment is performed. Associative Operator
( ) Associative Any Any
( 2 + 4 ) * 3 = 18 2 + ( 4 * 3 ) = 14 Arithmetic Operators
Multiplication Integer-integer Division Modulus Addition Integer-integer Integer-integer Integer-integer String-string Integer Integer Integer Integer String Raw byte-raw byte Raw List-list Integer-list List List Integer-string String 3 * 1 = 3 3 / 1 = 3 3 % 1 = 0 2 + 2 = 4
"one " + "two" = "one two"
'001122' + '334455' =
'001122334455'
[1, 2] + [3, 4] = [1, 2, 3, 4]
1 + [2, 3] = [1, 2, 3]
"number = " + 2 = "number = 2"
*Note: integer-string concatenation uses decimal conversion. String-list List
"one" + ["two"] = ["one", "two"]
Subtraction Integer-integer Integer 3 1 = 2 Increment and Decrement Operators
Increment Integer Integer a = 1
++a = 2
Decrement Integer Integer a = 2
--a = 1 b = 1 b++ = 1
*Note that the value of b after execution is 2. b = 2 b-- = 2
*Note that the value of b after execution is 1. Operators 264 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Operator Symbol Description Operand Types Result Types Examples Equality Operators
Equal Integer-integer String-string Integer Integer 2 == 2
"three" == "three"
Raw byte-raw byte Integer
'001122' == '001122'
List-list Integer
[1, [2, 3]] == [1, [2, 3]]
*Note: equality operations on values of different types will evaluate to false.
Not equal Integer-integer String-string Integer Integer 2 != 3
"three" != "four"
Raw byte-raw byte Integer
'001122' != '334455'
List-list Integer
[1, [2, 3]] != [1, [2, 4]]
*Note: equality operations on values of different types will evaluate to false. Relational Operators
Less than Integer-integer String-string Greater than Integer-integer Less than or equal Greater than or equal String-string Integer-integer String-string Integer-integer String-string Integer Integer Integer Integer Integer Integer Integer Integer 1 < 2
"abc" < "def"
2 > 1
"xyz" > "abc"
23 <= 27
"cat" <= "dog"
2 >= 1
"sun" >= "moon"
*Note: relational operations on string values are evaluated according to character order in the ASCII table. Logical Operators
Negation Logical AND Logical OR All combinations of types All combinations of types All combinations of types Integer Integer Integer
!0 = 1 !"cat" = 0
!9 = 0 !"" = 1 1 && 1 = 1 1 && !"" = 1 1 && 0 = 0 1 && "cat" = 1 1 || 1 = 1 0 || 0 = 0 1 || 0 = 1 "" || !"cat" = 0 Operators (Continued) 265 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Operator Symbol Description Operand Types Result Types Examples Bitwise Logical Operators
Bitwise complement Integer-integer Integer
~0b11111110 = 0b00000001 Bitwise AND Integer-integer Integer Bitwise exclusive OR Bitwise inclusive OR Integer-integer Integer Integer-integer Integer 0b11111110 & 0b01010101 =
0b01010100 0b11111110 ^ 0b01010101 =
0b10101011 0b11111110 | 0b01010101 =
0b11111111 Shift Operators
Left shift Right shift Integer-integer Integer-integer Integer Integer 0b11111110 << 3 = 0b11110000 0b11111110 >> 1 = 0b01111111 Assignment Operators
Assignment Any Any Addition assignment Integer-integer Integer A = 1 B = C = A x = 1 x += 1 = 2 String-string String a = "one "
a += "two" = "one two"
Raw byte-raw byte Raw z = '001122'
z += '334455' = '001122334455'
List-list Integer-list List List Integer-string String x = [1, 2]
x += [3, 4] = [1, 2, 3, 4]
y = 1 y += [2, 3] = [1, 2, 3]
a = "number = "
a += 2 = "number = 2"
*Note: integer-string concatenation uses decimal conversion. String-list List s = "one"
s + ["two"] = ["one", "two"]
Subtraction assignment Multiplication assignment Division assignment Modulus assignment Right shift assignment Left shift assignment Integer-integer Integer Integer-integer Integer Integer-integer Integer Integer-integer Integer Integer-integer Integer Integer-integer Integer y = 3 y = 1 = 2 x = 3 x *= 1 = 3 s = 3 s /= 1 = 3 y = 3 y %= 1 = 0 b = 0b11111110 b >>= 1 = 0b01111111 a = 0b11111110 a <<= 3 = 0b11111110000 Operators (Continued) 266 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Operator Symbol Description Operand Types Result Types Examples Assignment Operators (continued)
Bitwise AND assignment Bitwise exclusive OR assignment Bitwise inclusive OR assignment List Operators Integer-integer Integer Integer-integer Integer a = 0b11111110 a &= 0b01010101 = 0b01010100 e = 0b11111110 e ^= 0b01010101 = 0b10101011 Integer-integer Integer i = 0b11111110 i |= 0b01010101 = 0b11111111 sizeof() Number of Any Integer elements sizeof([1, 2, 3]) = 3 sizeof('0011223344') = 5 sizeof("string") = 6 sizeof(12) = 1 sizeof([1, [2, 3]]) = 2
*Note: the last example demonstrates that the sizeof() operator returns the shallow count of a complex list. head() Head tail() Tail List List Any head([1, 2, 3]) = 1
*Note: the Head of a list is the first item in the list. List tail([1, 2, 3]) = [2, 3]
*Note: the Tail of a list includes everything except the Head. Operators (Continued) 267 CATC MERLINS WAND 1.22 Users Manual D.7 Comments APPENDIX D CATC Scripting Language Comments may be inserted into scripts as a way of documenting what the script does and how it does it. Comments are useful as a way to help others understand how a particular script works. Additionally, comments can be used as an aid in structuring the program. Comments in CSL begin with a hash mark (#) and finish at the end of the line. The end of the line is indicated by pressing the Return or Enter key. Anything contained inside the comment delimiters is ignored by the compiler. Thus,
# x = 2;
is not considered part of the program. CSL supports only end-of-line comments, which means that comments can be used only at the end of a line or on their own line. It's not possible to place a comment in the middle of a line. Writing a multi-line comment requires surrounding each line with the comment delimiters
# otherwise the compiler would try to interpret
# anything outside of the delimiters
# as part of the code. The most common use of comments is to explain the purpose of the code immediately following the comment. For example:
# Add a profile if we got a server channel if(rfChannel != "Failure")
result =
SDPAddProfileServiceRecord(rfChannel,
"ObjectPush");
Trace("SDPAddProfileServiceRecord returned ", result, "\n");
D.8 Keywords Keywords are reserved words that have special meanings within the language. They cannot be used as names for variables, constants or functions. 268 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language In addition to the operators, the following are keywords in CSL:
Keyword Usage select select expression set const define a global variable define a constant return return statement while while statement for if for statement if statement else if-else statement default select expression null in out null value input context output context D.9 Statements Statements are the building blocks of a program. A program is made up of list of statements. Seven kinds of statements are used in CSL: expression statements, if statements, if-else statements, while statements, for statements, return statements, and compound statements. Expression Statements An expression statement describes a value, variable, or function.
<expression>
Here are some examples of the different kinds of expression statements:
Value: x + 3;
Variable: x = 3;
Function: Trace ( x + 3 );
269 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language The variable expression statement is also called an assignment statement, because it assigns a value to a variable. if Statements An if statement follows the form if <expression> <statement>
For example, if (3 && 3) Trace("True!");
will cause the program to evaluate whether the expression 3 && 3 is nonzero, or True. It is, so the expression evaluates to True and the Trace statement will be executed. On the other hand, the expression 3 && 0 is not nonzero, so it would evaluate to False, and the statement wouldn't be executed. if-else Statements The form for an if-else statement is if <expression> <statement1>
else <statement2>
The following code if ( 3 - 3 || 2 - 2 ) Trace ( "Yes" );
else Trace ( "No" );
will cause "No" to be printed, because 3 - 3 || 2 - 2 will evaluate to False (neither 3 - 3 nor 2 - 2 is nonzero). while Statements A while statement is written as while <expression> <statement>
An example of this is x = 2;
while ( x < 5 )
Trace ( x, ", " );
x = x + 1;
The result of this would be 270 CATC MERLINS WAND 1.22 Users Manual 2, 3, 4, APPENDIX D CATC Scripting Language for Statements A for statement takes the form for (<expression1>; <expression2>;
<expression3>) <statement>
The first expression initializes, or sets, the starting value for x. It is executed one time, before the loop begins. The second expression is a conditional expression. It determines whether the loop will continue -- if it evaluates true, the function keeps executing and proceeds to the statement; if it evaluates false, the loop ends. The third expression is executed after every iteration of the statement. The example for ( x = 2; x < 5; x = x + 1 ) Trace ( x, "\n" );
would output 2 3 4 The example above works out like this: the expression x = 2 is executed. The value of x is passed to x < 5, resulting in 2 < 5. This evaluates to true, so the statement Trace (x, "\n" ) is performed, causing 2 and a new line to print. Next, the third expression is executed, and the value of x is increased to 3. Now, x < 5 is executed again, and is again true, so the Trace statement is executed, causing 3 and a new line to print. The third expression increases the value of x to 4; 4 < 5 is true, so 4 and a new line are printed by the Trace statement. Next, the value of x increases to 5. 5 < 5 is not true, so the loop ends. 271 CATC MERLINS WAND 1.22 Users Manual return Statements APPENDIX D CATC Scripting Language Every function returns a value, which is usually designated in a return statement. A return statement returns the value of an expression to the calling environment. It uses the following form:
return <expression>
An example of a return statement and its calling environment is Trace ( HiThere() );
... HiThere()
return "Hi there";
The call to the primitive function Trace causes the function HiThere() to be executed. HiThere() returns the string Hi there as its value. This value is passed to the calling environment (Trace), resulting in this output:
Hi there A return statement also causes a function to stop executing. Any statements that come after the return statement are ignored, because return transfers control of the program back to the calling environment. As a result, Trace ( HiThere() );
... HiThere()
a = "Hi there";
return a;
b = "Goodbye";
return b;
will output only Hi there because when return a; is encountered, execution of the function terminates, and the second return statement (return b;) is never processed. However, Trace ( HiThere() );
272 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language
... HiThere()
a = "Hi there";
b = "Goodbye";
if ( 3 != 3 ) return a;
else return b;
will output Goodbye because the if statement evaluates to false. This causes the first return statement to be skipped. The function continues executing with the else statement, thereby returning the value of b to be used as an argument to Trace. Compound Statements A compound statement, or statement block, is a group of one or more statements that is treated as a single statement. A compound statement is always enclosed in curly braces ( {} ). Each statement within the curly braces is followed by a semicolon; however, a semicolon is not used following the closing curly brace. The syntax for a compound statement is
<first_statement>;
<second_statement>;
<last_statement>;
An example of a compound statement is
x = 2;
x + 3;
It's also possible to nest compound statements, like so:
x = 2;
273 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language y = 3;
x + 3;
Compound statements can be used anywhere that any other kind of statement can be used. if (3 && 3)
result = "True!";
Trace(result);
Compound statements are required for function declarations and are commonly used in if, if-else, while, and for statements. D.10 Preprocessing The preprocessing command %include can be used to insert the contents of a file into a script. It has the effect of copying and pasting the file into the code. Using %include allows the user to create modular script files that can then be incorporated into a script. This way, commands can easily be located and reused. The syntax for %include is this:
%include includefile.inc The quotation marks around the filename are required, and by convention, the included file has a .inc extension. The filenames given in the include directive are always treated as being relative to the current file being parsed. So, if a file is referenced via the preprocessing command in a .script file, and no path information is provided
(%include file.inc), the application will try to load the file from the current directory. Files that are in a directory one level up from the current file can be referenced using ..\file.inc, and likewise, files one level down can be referenced using the relative pathname
(directory\file.inc). Last but not least, files can also be referred to using a full pathname, such as C:\global_scripts\include\file.inc. 274 CATC MERLINS WAND 1.22 Users Manual D.11 Functions APPENDIX D CATC Scripting Language A function is a named statement or a group of statements that are executed as one unit. All functions have names. Function names must contain only alphanumeric characters and the underscore ( _ ) character, and they cannot begin with a number. A function can have zero or more parameters, which are values that are passed to the function statement(s). Parameters are also known as arguments. Value types are not specified for the arguments or return values. Named arguments are local to the function body, and functions can be called recursively. The syntax for a function declaration is name(<parameter1>, <parameter2>, ...)
<statements>
The syntax to call a function is name(<parameter1>, <parameter2>, ...) So, for example, a function named add can be declared like this:
add(x, y)
return x + y;
and called this way:
add(5, 6);
This would result in a return value of 11. Every function returns a value. The return value is usually specified using a return statement, but if no return statement is specified, the return value will be the value of the last statement executed. Arguments are not checked for appropriate value types or number of arguments when a function is called. If a function is called with fewer arguments than were defined, the specified arguments are assigned, and the remaining arguments are assigned to null. If a function is called with more arguments than were defined, the extra arguments are ignored. For example, if the function add is called with just one argument 275 CATC MERLINS WAND 1.22 Users Manual add(1);
APPENDIX D CATC Scripting Language the parameter x will be assigned to 1, and the parameter y will be assigned to null, resulting in a return value of 1. But if add is called with more than two arguments add(1, 2, 3);
x will be assigned to 1, y to 2, and 3 will be ignored, resulting in a return value of 3. All parameters are passed by value, not by reference, and can be changed in the function body without affecting the values that were passed in. For instance, the function add_1(x, y)
x = 2;
y = 3;
return x + y;
reassigns parameter values within the statements. So, a = 10;
b = 20;
add_1(a, b);
will have a return value of 5, but the values of a and b won't be changed. The scope of a function is the file in which it is defined (as well as included files), with the exception of primitive functions, whose scopes are global. Calls to undefined functions are legal, but will always evaluate to null and result in a compiler warning. D.12 Primitives Primitive functions are called similarly to regular functions, but they are implemented outside of the language. Some primitives support multiple types for certain arguments, but in general, if an argument of the wrong type is supplied, the function will return null. 276 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Call() Call( <function_name string>, <arg_list list> ) Parameter Meaning Default Value Comments function_name string arg_list list Return value Used as the list of parameters in the function call. Same as that of the function that is called. Comments Calls a function whose name matches the function_name parameter. All scope rules apply normally. Spaces in the function_name parameter are interpreted as the _ (underscore) character since function names cannot contain spaces. Example Call("Format", ["the number is %d", 10]);
is equivalent to:
Format("the number is %d", 10);
Format() Format (<format string>, <value string or integer>) Meaning Default Value Comments Parameter format string value string or integer Return value None. Comments Format is used to control the way that arguments will print out. The format string may contain conversion specifications that affect the way in which the arguments in the value string are returned. Format conversion characters, flag characters, and field width modifiers are used to define the conversion specifications. Example Format("0x%02X", 20);
would yield the string 0x14. 277 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Format can only handle one value at a time, so Format("%d %d", 20, 30);
would not work properly. Furthermore, types that do not match what is specified in the format string will yield unpredictable results. Format Conversion Characters These are the format conversion characters used in CSL:
Code Type Output c d i o u x X s Integer Character Integer Signed decimal integer. Integer Signed decimal integer Integer Unsigned octal integer Integer Unsigned decimal integer Integer Unsigned hexadecimal integer, using "abcdef."
Integer Unsigned hexadecimal integer, using "ABCDEF."
String String A conversion specification begins with a percent sign (%) and ends with a conversion character. The following optional items can be included, in order, between the % and the conversion character to further control argument formatting:
Flag characters are used to further specify the formatting. There are five flag characters:
A minus sign (-) will cause an argument to be left-aligned in its field. Without the minus sign, the default position of the argument is right-aligned. A plus sign will insert a plus sign (+) before a positive signed integer. This only works with the conversion characters d and i. A space will insert a space before a positive signed integer. This only works with the conversion characters d and i. If both a space and a plus sign are used, the space flag will be ignored. A hash mark (#) will prepend a 0 to an octal number when used with the conversion character o. If # is used with x or X, it will prepend 0x or 0X to a hexadecimal number. A zero (0) will pad the field with zeros instead of with spaces. 278 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language Field width specification is a positive integer that defines the field width, in spaces, of the converted argument. If the number of characters in the argument is smaller than the field width, then the field is padded with spaces. If the argument has more characters than the field width has spaces, then the field will expand to accommodate the argument. GetNBits() GetNBits (<bit_source list or raw>, <bit_offset integer>, <bit_count integer>) Parameter Meaning Default Value Comments Can be an integer value (4 bytes) or a list of inte-
gers that are interpreted as bytes. Index of bit to start reading from Number of bits to read bit_source list, raw, or integer bit_offset integer bit_count Return value None. Comments Reads bit_count bits from bit_source starting at bit_offset. Will return null if bit_offset + bit_count exceeds the number of bits in bit_source. If bit_count is 32 or less, the result will be returned as an integer. Otherwise, the result will be returned in a list format that is the same as the input format. GetNBits also sets up the bit data source and global bit offset used by NextNBits. Note that bits are indexed starting at bit 0. Example raw = 'F0F0';
result = GetNBits ( raw, 2, 4 );
Trace ( "result = ", result );
# 1111000011110000 binary The output would be result = C
# The result is given in hexadecimal. The result in binary is 1100 In the call to GetNBits: starting at bit 2, reads 4 bits (1100) and returns the value 0xC. 279 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language NextNBits() NextNBits (<bit_count integer>) Parameter Meaning Default Value Comments bit_count integer Return value None. Comments Reads bit_count bits from the data source specified in the last call to GetNBits, starting after the last bit that the previous call to GetNBits or NextNbits returned. If called without a previous call to GetNBits, the result is undefined. Note that bits are indexed starting at bit 0. Example
# 1111000011110000 binary raw = 'F0F0';
result1 = GetNBits ( raw, 2, 4 );
result2 = NextNBits(5);
result3 = NextNBits(2);
Trace ( "result1 = ", result1 " result2 = ", result2 "
result3 = ", result3 );
This will generate this trace output:
result1 = C result2 = 7 result3 = 2 In the call to GetNBits: starting at bit 2, reads 4 bits (1100), and returns the value 0xC. In the first call to NextNBits: starting at bit 6, reads 5 bits (00111), and returns the value 0x7. In the second call to NextNBits: starting at bit 11 (=6+5), reads 2 bits
(10), and returns the value 0x2. Resolve() Resolve( <symbol_name string> ) Parameter Meaning Default Value Comments symbol_name string Return value The value of the symbol. Returns null if the symbol is not found. 280 CATC MERLINS WAND 1.22 Users Manual Comments APPENDIX D CATC Scripting Language Attempts to resolve the value of a symbol. Can resolve global, constant, and local symbols. Spaces in the symbol_name parameter are interpreted as the _ (underscore) character since function names cannot contain spaces. Example a = Resolve( "symbol" );
is equivalent to:
a = symbol;
Trace() Trace( <arg1 any>, <arg2 any>, ... ) Meaning Default Value Comments The number of arguments is variable. Parameter arg any Return value None. Comments The values given to this function are given to the debug console. Example list = ["cat", "dog", "cow"];
Trace("List = ", list, "\n");
would result in the output List = [cat, dog, cow]
281 CATC MERLINS WAND 1.22 Users Manual APPENDIX D CATC Scripting Language 282
frequency | equipment class | purpose | ||
---|---|---|---|---|
1 | 2002-10-04 | 2402 ~ 2480 | DSS - Part 15 Spread Spectrum Transmitter | Class II permissive change or modification of presently authorized equipment |
2 | 2002-09-24 | 2402 ~ 2480 | DSS - Part 15 Spread Spectrum Transmitter | Original Equipment |
app s | Applicant Information | |||||
---|---|---|---|---|---|---|
1 2 | Effective |
2002-10-04
|
||||
1 2 |
2002-09-24
|
|||||
1 2 | Applicant's complete, legal business name |
Computer Access Technology Corporation
|
||||
1 2 | FCC Registration Number (FRN) |
0007498272
|
||||
1 2 | Physical Address |
2403 Walsh Avenue
|
||||
1 2 |
Santa Clara, California 95051-1302
|
|||||
1 2 |
United States
|
|||||
app s | TCB Information | |||||
1 2 | TCB Application Email Address |
m******@ccsemc.com
|
||||
1 2 | TCB Scope |
A4: UNII devices & low power transmitters using spread spectrum techniques
|
||||
app s | FCC ID | |||||
1 2 | Grantee Code |
KH7
|
||||
1 2 | Equipment Product Code |
BT004APA-X
|
||||
app s | Person at the applicant's address to receive grant or for contact | |||||
1 2 | Name |
K**** K********
|
||||
1 2 | Title |
Manufacturing Engineering Manager
|
||||
1 2 | Telephone Number |
408-4********
|
||||
1 2 | Fax Number |
408-7********
|
||||
1 2 |
k******@catc.com
|
|||||
app s | Technical Contact | |||||
n/a | ||||||
app s | Non Technical Contact | |||||
n/a | ||||||
app s | Confidentiality (long or short term) | |||||
1 2 | Does this application include a request for confidentiality for any portion(s) of the data contained in this application pursuant to 47 CFR § 0.459 of the Commission Rules?: | No | ||||
1 2 | Yes | |||||
1 2 | Long-Term Confidentiality Does this application include a request for confidentiality for any portion(s) of the data contained in this application pursuant to 47 CFR § 0.459 of the Commission Rules?: | No | ||||
if no date is supplied, the release date will be set to 45 calendar days past the date of grant. | ||||||
app s | Cognitive Radio & Software Defined Radio, Class, etc | |||||
1 2 | Is this application for software defined/cognitive radio authorization? | No | ||||
1 2 | Equipment Class | DSS - Part 15 Spread Spectrum Transmitter | ||||
1 2 | Description of product as it is marketed: (NOTE: This text will appear below the equipment class on the grant) | Bluetooth Protocal Analyzer and Test Generator | ||||
1 2 | Related OET KnowledgeDataBase Inquiry: Is there a KDB inquiry associated with this application? | No | ||||
1 2 | Modular Equipment Type | Does not apply | ||||
1 2 | Purpose / Application is for | Class II permissive change or modification of presently authorized equipment | ||||
1 2 | Original Equipment | |||||
1 2 | Composite Equipment: Is the equipment in this application a composite device subject to an additional equipment authorization? | No | ||||
1 2 | Related Equipment: Is the equipment in this application part of a system that operates with, or is marketed with, another device that requires an equipment authorization? | No | ||||
1 2 | Grant Comments | Class II permissive change filing by including Bluetooth Radio Module in UPAS2500 base unit. The antenna(s) used for this transmitter must be installed to provide a separation distance of at least 20 cm from all persons and must not be co-located or operating in conjunction with any other antenna or transmitter. End-users and installers must be provided with antenna installation and transmitter operating conditions for satisfying RF exposure compliance. | ||||
1 2 | The antenna(s) used for this transmitter must be installed to provide a separation distance of at least 20 cm from all persons and must not be co-located or operating in conjunction with any other antenna or transmitter. End-users and installers must be provided with antenna installation and transmitter operating conditions for satisfying RF exposure compliance. | |||||
1 2 | Is there an equipment authorization waiver associated with this application? | No | ||||
1 2 | If there is an equipment authorization waiver associated with this application, has the associated waiver been approved and all information uploaded? | No | ||||
app s | Test Firm Name and Contact Information | |||||
1 2 | Firm Name |
Compliance Certification Services Inc
|
||||
1 2 | Name |
S**** C****
|
||||
1 2 | Telephone Number |
408-4******** Extension:
|
||||
1 2 | Fax Number |
408-4********
|
||||
1 2 |
s******@ccsemc.com
|
|||||
Equipment Specifications | |||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Line | Rule Parts | Grant Notes | Lower Frequency | Upper Frequency | Power Output | Tolerance | Emission Designator | Microprocessor Number | |||||||||||||||||||||||||||||||||
1 | 1 | 15C | 2402.00000000 | 2480.00000000 | 0.0007000 | ||||||||||||||||||||||||||||||||||||
Line | Rule Parts | Grant Notes | Lower Frequency | Upper Frequency | Power Output | Tolerance | Emission Designator | Microprocessor Number | |||||||||||||||||||||||||||||||||
2 | 1 | 15C | 2402.00000000 | 2480.00000000 | 0.0007000 |
some individual PII (Personally Identifiable Information) available on the public forms may be redacted, original source may include additional details
This product uses the FCC Data API but is not endorsed or certified by the FCC