Users Manual Instruction Manual

ManualsBrandsTeledyne LeCroy ManualsEquipmentBTTracer_Trainer - BTTrainer

2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622

Document Revision 1.20

6 November, 2003

CATC BTTrainer

Bluetooth Exerciser

User’s Manual

Software Version 2.20

Summary of content (336 pages)

PAGE 1
2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622 CATC BTTrainer Bluetooth Exerciser User’s Manual Software Version 2.20 Document Revision 1.
PAGE 2
CATC BTTRAINER 2.20 User’s Manual CATC BTTrainer 2.20 Bluetooth Exerciser User’s Manual, Document Revision 1.20 Product Part Number: 730-0046-00 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.
PAGE 3
CATC BTTRAINER 2.20 User’s Manual 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.
PAGE 4
CATC BTTRAINER 2.
PAGE 5
CATC BTTRAINER 2.20 User’s Manual Table of Contents TABLE OF CONTENTS Conformance Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .iii FCC Conformance Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii EU Conformance Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii Chapter 1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 6
CATC BTTRAINER 2.20 User’s Manual Pairable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Inquiry Access Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Add an IAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Modify an IAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 7
CATC BTTRAINER 2.20 User’s Manual Table of Contents On Windows 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Ascertain the COM Port Number. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Install a Modem Driver on the Virtual COM Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Installation of Network Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 8
CATC BTTRAINER 2.20 User’s Manual Disconnect All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64 Chapter 8 Contact and Warranty Information . . . . . . . . . . . . . . . . . .65 Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65 Limited Hardware Warranty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 9
CATC BTTRAINER 2.20 User’s Manual Table of Contents Flush. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Host_Buffer_Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Read_Authentication_Enable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Read_Automatic_Flush_Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 10
CATC BTTRAINER 2.20 User’s Manual Write_Stored_Link_Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Write_Voice_Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 HCI Informational Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 Read_BD_ADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Read_Buffer_Size . . .
PAGE 11
CATC BTTRAINER 2.20 User’s Manual Table of Contents CATC_Write_Link_Key_Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 CATC_Write_Local_Supported_Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 CATC_Write_PIN_Response_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 L2CAP Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 ConfigurationResponse . . . . . . . . . .
PAGE 12
CATC BTTRAINER 2.20 User’s Manual TCS Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124 RegisterIntercomProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Open_TCS_Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Start_TCS_Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 13
CATC BTTRAINER 2.20 User’s Manual Table of Contents Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 DoInquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 GetDeviceClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 14
CATC BTTRAINER 2.20 User’s Manual HCICatcWriteEncryptionKeySize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166 HCICatcWriteLinkKeyType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166 HCICATCWriteLocalSupportedFeatures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 HCICatcWritePinResponseEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168 HCIChangeConnectionLinkKey. . . . . . . . . . . . . . . . .
PAGE 15
CATC BTTRAINER 2.20 User’s Manual Table of Contents HCIReadPageTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 HCIReadPINType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 HCIReadRemoteSupportedFeatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 HCIReadRemoteVersionInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 HCIReadScanEnable . . .
PAGE 16
CATC BTTRAINER 2.20 User’s Manual OBEXServerInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 OBEXServerSetPath(Path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226 RFCOMM Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227 RFCloseClientChannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 17
CATC BTTRAINER 2.20 User’s Manual Table of Contents L2CAPConnectRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 L2CAPConnectResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 L2CAPDeregisterAllPsm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 L2CAPDisconnectRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 18
CATC BTTRAINER 2.20 User’s Manual Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293 Raw Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293 Null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 19
CATC BTTRAINER 2.20 CHAPTER 1 User’s Manual Overview CHAPTER 1: OVERVIEW The CATC BTTrainer™ Bluetooth™ Exerciser is a member of CATC's industry-leading line of high performance, serial communication protocol analysis tools and test equipment. Preceded by CATC's BTTracer™, a Bluetooth Protocol Analyzer, BTTrainer has been designed as an intelligent Bluetooth wireless technology device that can be used as a verification and validation tester or as an engineering debug and analysis tool.
PAGE 20
CATC BTTRAINER 2.20 CHAPTER 1 User’s Manual Overview mum control over the traffic generation process, but also requires familiarity with the Bluetooth commands. • 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. 1.
PAGE 21
CATC BTTRAINER 2.20 CHAPTER 1 User’s Manual Overview The following headsets have been successfully tested with BTTrainer: • 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 1.
PAGE 22
CATC BTTRAINER 2.
PAGE 23
CATC BTTRAINER 2.20 CHAPTER 2 User’s Manual Getting Started CHAPTER 2: GETTING STARTED This chapter describes how to install BTTrainer and its software. Both install easily in just a few minutes. The BTTrainer software can be installed on most Windows-based personal computer systems. 2.1 System Requirements Please consult the readme document on the installation CD for the latest information on system requirements. 2.
PAGE 24
CATC BTTRAINER 2.20 CHAPTER 2 User’s Manual Getting Started 2.4 Application Layout Main Window Device Status Window Log Window The BTTrainer window is made up of the following: • The Main window, where the primary tools are run: Profile Wizard, Command Generator, and Script Manager. • Profile Wizard -- A simple, easy-to-use tool that guides you through the process of establishing connections and generating traffic between BTTrainer and other Bluetooth wireless technology devices.
PAGE 25
CATC BTTRAINER 2.20 CHAPTER 2 User’s Manual Getting Started state, the role, the class, and the device’s local name. This window is open by default. These symbols in the list indicate a device’s 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.
PAGE 26
CATC BTTRAINER 2.20 CHAPTER 2 User’s Manual Getting Started Table 2-2: Edit Menu Commands Command Function Paste Pastes copied or cut text Select All Selects all text Find... Finds specified string Find Next Repeats last find action Replace...
PAGE 27
CATC BTTRAINER 2.20 CHAPTER 2 User’s Manual Getting Started 2.6 Toolbars There are two toolbars in the BTTrainer user interface: BTTrainer toolbar and BTTracer 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. 2.6.
PAGE 28
CATC BTTRAINER 2.20 CHAPTER 2 User’s Manual Getting Started 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.8 BTTrainer Keyboard Shortcuts Several frequently-used operations are bound to keyboard shortcuts.
PAGE 29
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Local Device Manager CHAPTER 3: LOCAL DEVICE MANAGER The Local Device Manager is a tool for viewing and configuring generic access profile settings for BTTrainer. Use the the Local Device Manager to control settings such as the Local Device Name, Class of Device, Accessibility Mode, and Security aspects. The Local Device Manager contains three tabs: General, Security, and Device Information.
PAGE 30
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Local Device Manager 3.1.2 Class of Device The Class of Device (COD) settings define the Bluetooth Device Class and Bluetooth Service Type with which BTTrainer will identify itself in response to inquiries from other Bluetooth devices. Select as one value Use “Select as one value” to choose a pre-configured set of COD parameters. To select COD settings as one value: Step 1 Select the radio button marked “Select as one value.
PAGE 31
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Local Device Manager This prevents BTTrainer from responding to paging from other Bluetooth devices. Discoverable BTTrainer can be placed in discoverable or non-discoverable mode. • Place BTTrainer in discoverable mode by checking the Discoverable checkbox, and clicking Apply to apply the settings, or OK to apply the settings and close the Local Device Manager.
PAGE 32
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Step 3 Step 4 Step 5 Local Device Manager Edit the IAC in the text box. Values must be entered in hex, and they must be between 9E8B00–9E8B3F. Click OK. The new value will be displayed in the list of IACs in the Local Device Manager. Click Apply to apply the settings, or click OK to apply the settings and close the Local Device Manager. Delete an IAC Step 1 Select the IAC that you want to delete. Note: You cannot delete the GIAC (0x9E8B33).
PAGE 33
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Local Device Manager 3.2.1 Security Mode There are three Bluetooth security modes: security mode 1, security mode 2, and security mode 3. Another option is not to use a security mode at all. • Security mode 1 is the non-secure mode. When in this mode, devices do not initiate security procedures. • Security mode 2 is service-level enforced security. Devices in this mode initiate security procedures after L2CAP channel establishment has ocurred.
PAGE 34
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Step 3 Step 4 Step 5 Local Device Manager Enter a PIN code in the second text box. Values must contain from 1-16 characters. Click OK. The new address and PIN code will be added to the list in the Local Device Manager. Click Apply to apply the settings, or click OK to apply the settings and close the Local Device Manager. Modify a PIN Code Step 1 Click Modify. The Modify PIN Code dialog will open. Step 2 Edit the PIN code in the text box.
PAGE 35
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Local Device Manager 3.3 Device Information The Device Information tab displays general access profile settings for BTTrainer. Figure 3-3: Device Information tab of the Local Device Manager These parameter values are displayed on the Device Information tab of the Local Device Manger: • Local_BD_ADDR — The Bluetooth device address for BTTrainer. Every device has a 48-bit address (BD_ADDR) that uniquely identifies it.
PAGE 36
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual Local Device Manager • • • • • • • • LMP Version: The Current Link Manager Protocol version (VersNr) in the BTTrainer hardware. Can be 0 (Bluetooth LMP 1.0), 1 (Bluetooth LMP 1.1), or 2-255 (reserved for future use) • Manufacturer Name: The name of the company (CompID) that created the LMP Subversion. • LMP Subversion: The Current Link Manager Protocol subversion in the BTTrainer hardware.
PAGE 37
CATC BTTRAINER 2.20 CHAPTER 3 User’s Manual • • • • Local Device Manager • 0x00: Encryption disabled • 0x01: Encryption only for point-to-point packets • 0x02: Encryption for both point-to-point and broadcast packets • 0x03–0xFF: Reserved PIN_Response_Enable — Specifies whether BTTrainer will supply PINs when requested during authentication. Possible values: • 0x00: Device will not supply PINs when requested during authentication. • 0x01: Device will supply PINs when requested during authentication.
PAGE 38
CATC BTTRAINER 2.
PAGE 39
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard CHAPTER 4: PROFILE WIZARD Once BTTrainer is installed and running, it is ready to generate traffic. The easiest way to generate traffic is to use Profile Wizard, a point-and-click tool for creating connections and transferring data between BTTrainer and other Bluetooth wireless technology devices. This tool requires little Bluetooth experience and allows you to generate Bluetooth traffic without having to execute specific Bluetooth commands.
PAGE 40
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard (Optional) Uncheck “Skip Name Search” so that BTTrainer will not try to discover the devices’ user-friendly names. This will speed up the search. Note: If no devices are found, you can click Search to have BTTrainer repeat the General Inquiry. Step 3 Step 4 Step 5 Step 6 Select device from list From the list, select the device address to which you want BTTrainer to connect.
PAGE 41
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard You can now refer to the section that describes the setup for the particular profile that the target device uses: • Section 4.2.1, “Connect to Device: Dial-Up Gateway” on page 23 • Section 4.2.2, “Connect to Device: Fax Gateway” on page 24 • Section 4.2.3, “Connect to Device: File Transfer” on page 25 • Section 4.2.4, “Connect to Device: HCRP Server” on page 26 • Section 4.2.5, “Connect to Device: Headset” on page 26 • Section 4.2.
PAGE 42
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard To send data: Note: A modem driver must be installed on the virtual COM port in order to use an external application to send data through BTTrainer. See “Install a Modem Driver on the Virtual COM Port” on page 40 to find out how to install the driver. Once the driver is installed, you must configure the external application to use that driver.
PAGE 43
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard Note: A modem driver must be installed on the virtual COM port in order to use a fax application to send data through BTTrainer. See“Install a Modem Driver on the Virtual COM Port” on page 40 to find out how to install the driver. Once the driver is installed, you must create a fax printer and configure it to use the driver that you have installed. Note: A fax application must be installed on the host computer in order to perform this operation.
PAGE 44
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard • Delete a file — To create a new folder in either device’s file directory, right-click on the directory level in which you wish to place the new folder, then choose “Create new folder” from the menu that pops up. The Enter Folder Name dialog will appear. Type in a name for the new folder, then click OK. The new folder will appear in the chosen directory. 4.2.
PAGE 45
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Step 3 Profile Wizard (Optional) Select the Allow Role Switch option on the screen to enable BTTrainer to switch roles during the connection. Click Next. The Wizard will advance to the Connection Status screen, and BTTrainer will attempt to establish an RFCOMM connection to the device. If the connection attempt is successful, the Connection Status screen will show that BTTrainer has established an RFCOMM connection with the device.
PAGE 46
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard 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. 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. Step 4 Step 5 4.2.
PAGE 47
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Step 4 Step 5 4.2.9 Profile Wizard 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.
PAGE 48
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Step 4 Profile Wizard You can now perform the following operations: • Send Control Packet: Use this to select a filter control message to send to the remote device. You may send either a Filter Network Protocol Type message or a Filter Multicast Address Type message control packet to the remote device. Start Range and End Range: Start Range defines the beginning of the range, and End Range defines the end of the range.
PAGE 49
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard • Send Control Packet: Use this to select a filter control message to send to the remote device. You may send either a Filter Network Protocol Type message or a Filter Multicast Address Type message control packet to the remote device. The only types of network filtering allowed are ARP (0806) and IPv4 (0800). Start Range and End Range: Start Range defines the beginning of the range, and End Range defines the end of the range.
PAGE 50
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard Note: A modem driver must be installed on the virtual COM port in order to use an external application to send data through BTTrainer. See “Install a Modem Driver on the Virtual COM Port” on page 40 to find out how to install the driver. Once the driver is installed, you must configure the external application to use that driver. Open the application and send the data.
PAGE 51
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual • • • • • • 4.3.1 Profile Wizard Section 4.3.6, “Emulate Device: Headset Audio Gateway” on page 36 Section 4.3.7, “Emulate Device: LAN” on page 36 Section 4.3.8, “Emulate Device: Object Push” on page 37 Section 4.3.9, “Emulate Device: PAN - GN” on page 37 Section 4.3.10, “Emulate Device: PAN - NAP” on page 38 Section 4.3.
PAGE 52
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard (b) Press Next. At this point, initialize a connection to BTTrainer from a Bluetooth device that uses the Dial-Up Gateway profile. When the connection has been established, you can use an external application to communicate with the device via BTTrainer. 4.3.2 Emulate Device: Fax Gateway The following steps show how to configure BTTrainer to emulate a fax gateway device. Step 1 Complete Steps 1-4 in Section 4.
PAGE 53
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Step 4 4.3.4 Profile Wizard At this point, you may transfer files to the root folder from the remote device. Emulate Device: HCRP Server This section explains how to use Profile Wizard to set up BTTrainer to emulate an HCRP server. Step 1 Complete Steps 1-4 in Section 4.3, “Emulating Devices” on page 32. The Printer Emulation screen will open.
PAGE 54
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard Note: The Speaker and Microphone Volume levels shown in the previous screenshot reflect the volume settings on the Master device. If you adjust the levels on the remote device, the displayed volume levels will change accordingly. Step 2 Step 3 Step 4 4.3.6 Direct a remote Bluetooth device to connect to BTTrainer.
PAGE 55
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual 4.3.8 Profile Wizard Emulate Device: Object Push BTTrainer 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 BTTrainer. Step 1 Complete Steps 1-4 in Section 4.3, “Emulating Devices” on page 32.
PAGE 56
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Profile Wizard For Filter Network Type Set Message, the Start and End Ranges may be in the format nnnn or 0xnnnn. For the Filter Multicast Address Set Message, the Start and End Ranges can be in the format nnnnnnnnnnnn or 0xnnnnnnnnnnnn. • Send Packet: Use this to send an ethernet packet to the remote device. The types of ethernet packets that can be sent are General, Compressed, Compressed Source Only and Compressed Destination Only.
PAGE 57
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual 4.3.11 Profile Wizard Emulate Device: Serial Port These steps describe how to use Profile Wizard to configure BTTrainer to emulate a device that uses the Serial Port profile. Note: To emulate a device that uses the Serial Port profile, you will need to install the virtual COM port driver that is included with the BTTrainer installation. For instructions, see “Installing the Virtual COM Port Driver” on page 39. Step 1 Step 2 Complete Steps 1-4 in Section 4.
PAGE 58
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 Step 9 Step 10 Step 11 Step 12 Profile Wizard Select “Add/Troubleshoot a device” and click Next. The Wizard will look for Plug and Play hardware, then it will display a list of all the hardware it finds on the computer. Select “Add a new device” from the list and click Next. Select “No, I want to select the hardware from a list” and click Next. Select “Ports (COM and LPT)” from the list and click Next.
PAGE 59
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 Step 9 Step 10 Profile Wizard Select Start > Settings > Control Panel from the desktop taskbar, then double-click on Add/Remove Hardware in the Control Panel window. The Add/Remove Hardware Wizard will open. Click Next. Select “Add/Troubleshoot a device” and click Next. The Wizard will look for Plug and Play hardware, then it will display a list of all the hardware it finds on the computer.
PAGE 60
CATC BTTRAINER 2.20 CHAPTER 4 User’s Manual 4.7.1 Profile Wizard Verifying the Driver’s Installation To verify that the drivers installed properly, go to the “Device Manager” utility, and display the properties for the “CATC Bluetooth Trainer PAN virtual NIC” driver under “Network Adapters.” Note: 4.7.2 The MAC address of the NIC driver is based on the BD address of BTTrainer. The MAC addr will be rewritten every time the BNEP_Register is executed.
PAGE 61
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator CHAPTER 5: COMMAND GENERATOR The Command Generator is a tool in BTTrainer 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.
PAGE 62
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual • • • • • Command Generator 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 will cause BTTrainer to run the selected command. Command Generator Tips — Detailed tips for each command are accessible by positioning the mouse over the question mark icon. A pop-up window that contains detailed information about the selected command will appear.
PAGE 63
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Step 5 Command Generator Click the Execute button to run the command. Note: While Command Generator offers maximum control over BTTrainer, 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 BTTrainer and a device, it is not possible to work with OBEX commands in Command Generator.
PAGE 64
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator 5.3 Commands Available in Command Generator The following tables summarize the commands in Command Generator. For detailed descriptions of the commands, see Appendix A: Command Generator Command Descriptions, on page 83. Note: “N/A” means Not Applicable. This indicates that the specified command does not have a parameter. 5.3.1 HCI Commands Link Control Commands Two sections of Link Control Commands are presented.
PAGE 65
CATC BTTRAINER 2.
PAGE 66
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator Table 5-3: Supported HCI Link Policy commands (Continued) Commands Parameters Switch_Role BD_ADDR Write_Link_Policy_Settings HCI_Handle Link_Policy_Settings Table 5-4: Unsupported HCI Link Policy commands Commands All Link Policy commands are supported in Command Generator.
PAGE 67
CATC BTTRAINER 2.
PAGE 68
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator Table 5-7: Supported HCI Informational commands (Continued) Commands Parameters Read_Local_Supported_Features N/A Read_Local_Version_Information N/A Table 5-8: Unsupported HCI Informational commands Commands All Informational commands are supported in Command Generator.
PAGE 69
CATC BTTRAINER 2.
PAGE 70
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator Table 5-13: Supported CATC-Specific HCI commands (Continued) Commands Parameters CATC_Write_Encryption_Key_Size Key_Size CATC_Write_Link_Key_Type Key_Type CATC_Write_Local_Supported_Features LMP_Features CATC_Write_PIN_Response_Enable PIN-Response_Enable 5.3.
PAGE 71
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator 5.3.
PAGE 72
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator Table 5-16: Supported RFCOMM commands (Continued) Commands Parameters RequestPortStatus (HCI/DLCI) SendATCommand (HCI/DLCI) AT_Command SendData (HCI/DLCI) Data Pipe SendTest (HCI/DLCI) SetLineStatus (HCI/DLCI) LineStatus SetModemStatus (HCI/DLCI) ModemSignals Break Length 5.3.
PAGE 73
CATC BTTRAINER 2.20 CHAPTER 5 User’s Manual Command Generator 5.3.7 BNEP Commands in Command Generator Table 5-19: BNEP Commands in Command Generator Commands Parameters Accept AcceptConnection Open BD_ADDR Close BNEP_ADDR SetUpConnectionReq BNEP_ADDR Destination UUID Source UUID SendPkt BNEP_ADDR SendControlPkt BNEP_ADDR Control Packet Type Range Start Range End RegisterBNEP N/A DeregisterBNEP N/A SendPktGeneral BNEP_ADDR SetControlTimeout BNEP_ADDR data_to_send Timeout 5.3.
PAGE 74
CATC BTTRAINER 2.
PAGE 75
CATC BTTRAINER 2.20 CHAPTER 6 User’s Manual Script Manager CHAPTER 6: SCRIPT MANAGER Script Manager is a tool within BTTrainer 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 BTTrainer.
PAGE 76
CATC BTTRAINER 2.20 CHAPTER 6 User’s Manual 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 BTTrainer application, on the status bar.
PAGE 77
CATC BTTRAINER 2.20 CHAPTER 6 User’s Manual Step 2 Step 3 Step 4 Script Manager 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. Navigate to the desired file and click Open. The script will display in Script Manager's Work Area. 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.
PAGE 78
CATC BTTRAINER 2.20 CHAPTER 6 User’s Manual Script Manager 6.4 Sample Scripts Sample scripts are provided with BTTrainer to demonstrate how Script Manager works. These scripts are subject to change and hence are not described here. Running sample.script will cause BTTrainer to attempt to connect to another device. The default location of the scripts is the directory where the application is installed, which is usually C:\Program Files\CATC\BTTrainer.
PAGE 79
CATC BTTRAINER 2.20 CHAPTER 7 User’s Manual Device Search and Device List Pop-Up Menu CHAPTER 7: 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. The Device List in BTTracer shares the same data with the Device List in BTTrainer.
PAGE 80
CATC BTTRAINER 2.20 CHAPTER 7 User’s Manual Step 4 Device Search and Device List Pop-Up Menu 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. 7.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.
PAGE 81
CATC BTTRAINER 2.20 CHAPTER 7 User’s Manual Step 3 Step 4 Step 5 Device Search and Device List Pop-Up 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 BTTrainer has an ACL connection to the target device. Reopen the Pop-Up Menu by right-clicking on the target device in the Device List. The Device List Pop-Up Menu will open.
PAGE 82
CATC BTTRAINER 2.20 CHAPTER 7 User’s Manual Step 2 Device Search and Device List Pop-Up Menu Select Delete. The device(s) will be removed from the Device List. 7.2.5 Disconnect All A fast and easy way to terminate all connections that BTTrainer has established with remote devices is to use the Disconnect All… command on the Device List Pop-Up Menu. Step 1 Step 2 Step 3 Open the Pop-Up Menu by right-clicking on a device.
PAGE 83
CATC BTTRAINER 2.20 CHAPTER 8 User’s Manual Contact and Warranty Information CHAPTER 8: CONTACT AND WARRANTY INFORMATION 8.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.
PAGE 84
CATC BTTRAINER 2.
PAGE 85
CATC BTTRAINER 2.20 CHAPTER 8 User’s Manual Contact and Warranty Information If CATC evaluates and determines there is "no trouble found" in any Product returned or that the returned Product is not eligible for warranty coverage, CATC will inform you of its determination. If you thereafter request CATC to repair the Product, such labor and service shall be performed under the terms and conditions of CATC's then current repair policy.
PAGE 86
CATC BTTRAINER 2.
PAGE 87
CATC BTTRAINER 2.20 APPENDIX A User’s Manual APPENDIX A: COMMAND GENERATOR COMMAND DESCRIPTIONS Note: “N/A” means Not Applicable. This indicates that the specified command does not have a parameter. A.1 HCI Link Control Commands A.1.1 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.
PAGE 88
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Authentication_Error Authentication_Complete A.1.4 Change_Connection_Link_Key Used to force both connected devices to generate a new link key. Command Parameters Examples Comments HCI_Handle 0x0001 Range: 0x0000-0x0EFF Return Events Change_Connection_Link_Key_Error Change_Connection_Link_Key_Complete A.1.5 Change_Connection_Packet_Type Used to change which packet types can be used for a connection that is currently established.
PAGE 89
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Command Parameters Examples Comments Clock_Offset Allow_Role_Switch Return Events Create_Connection_Complete Create_Connection_Error A.1.7 Disconnect Disconnect is used to terminate an existing connection. Command Parameters Examples HCI_Handle 0x0001 Comments Return Events Disconnection_Complete Disconnection_Failed A.1.
PAGE 90
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Success Failure: Device not found Failure A.1.10 Inquiry Inquiry will cause BTTrainer to enter Inquiry mode and discover other nearby Bluetooth devices. Command Parameters Examples Comments LAP Inquiry_Length 8 Num_Responses 10 Return Events Inquiry_Complete Inquiry_Result Inquiry_Error A.1.11 Inquiry_Cancel Inquiry_Cancel will cause BTTrainer to stop the current Inquiry if the Bluetooth device is in Inquiry mode.
PAGE 91
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Command Parameters Examples Comments Inquiry Length 8 Range: 0x01 – 0x30 Num of Responses 10 Range: 0-255 (0=Unlimited number of responses) Return Events Periodic_Inquiry_Mode_Complete Periodic_Inquiry_Mode_Error A.1.13 PIN_Code_Request_Negative_Reply PIN_Code_Request_Negative_Reply is used to reply to a PIN Code Request event from the Host Controller when the Host cannot specify a PIN code to use for a connection.
PAGE 92
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.1.15 Read_Clock_Offset Read_Clock_Offset allows the Host to read the clock offset of remote devices. Command Parameters Examples HCI_Handle 0x0001 Comments Return Events Read_Clock_Offset_Complete Read_Clock_Offset_Error A.1.16 Read_Remote_Supported_Features Read_Remote_Supported_Features requests a list of the supported features of a remote device.
PAGE 93
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Reject_Connection_Request_Complete A.1.19 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.
PAGE 94
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.1.20 Set_Connection_Encryption Set_Connection_Encryption is used to enable and disable the link-level encryption. Command Parameters Examples HCI_Handle 0x0001 Encryption_Enable 1 Comments Range: 0 or 1 Return Events Set_Connection_Encryption_Complete Set_Connection_Encryption_Error A.2 HCI Link Policy Commands A.2.1 Get_Park_Mode Stops park mode and enters active mode for the specified ACL link.
PAGE 95
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Command Parameters Examples Comments Max_Interval 0xFFFF 0x0001 - 0xFFFF Min_Interval 0x01 0x0001 - 0xFFFF Return Events Mode_Change Hold_Mode_Error A.2.4 Set_Park_Mode Places the specified ACL link into Park mode. Command Parameters Examples Comments HCI_Handle 0x0001 Beacon_Max_Interval 0xFFFF 0x0001 - 0xFFFF Beacon_Min_Interval 0x01 0x0001 - 0xFFFF Return Events Mode_Change Park_Mode_Error A.2.
PAGE 96
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.2.6 Read_Link_Policy_Settings Reads Link Policy setting for the specified ACL link. Command Parameters Examples HCI_Handle 0x0001 Comments Return Events Read_Link_Policy_Settings_Complete Read_Link_Policy_Settings_Error A.2.7 Role_Discovery Role_Discovery is used for a Bluetooth device to determine which role the device is performing (Master or Slave) for a particular connection.
PAGE 97
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.2.9 Switch_Role Switches the current role (master/slave) of the calling device with the role of the device specified. Command Parameters Examples BD_ADDR 0x010203040506 Comments Return Events Role_Change_Complete Role_Change_Error A.2.10 Write_Link_Policy_Settings Writes link policy settings for the specified ACL link.
PAGE 98
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.2 Create_New_Unit_Key. Command Parameters Examples Comments NA A.3.3 Delete_Stored_Link_Key Change_Local_Name allows the user-friendly name to be modified for the BTTrainer. Command Parameters Examples Comments Name BTTrainer Maximum string length =32 characters Return Events Change_Local_Name_Complete Change_Local_Name_Error A.3.4 Flush Change_Local_Name allows the user-friendly name to be modified for the BTTrainer.
PAGE 99
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.6 Read_Authentication_Enable Read_Authentication_Enable will read the value for the Authentication_Enable parameter, which controls whether BTTrainer 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 A.3.7 Read_Automatic_Flush_Timeout Command Parameters Examples Comments HCI_Handle A.3.
PAGE 100
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.10 Read_Current_IAC_LAP Read_Current_IAC_LAP will read the LAP(s) used to create the Inquiry Access Codes (IAC) that BTTrainer 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 A.3.
PAGE 101
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Read_Link_Supervision_Timeout_Complete Read_Link_Supervision_Timeout_Error A.3.15 Read_Local_Name Read_Local_Name reads the stored user-friendly name for BTTrainer. Command Parameters Examples Comments N/A Return Events Read_Local_Name_Complete Read_Local_Name_Error A.3.16 Read_Num_Broadcast_Retransmission Command Parameters Examples Comments NA A.3.
PAGE 102
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.18 Read_Page_Scan_Activity Command Parameters Examples Comments N/A A.3.19 Read_Page_Scan_Mode Read_Page_Scan_Mode command is used to read the current Page_Scan_Mode of BTTrainer. Command Parameters Examples Comments N/A Return Events Read_Page_Scan_Mode_Complete Read_Page_Scan_Mode_Error A.3.20 Read_Page_Scan_Period_Mode Read_Page_Scan_Period_Mode is used to read the Page_Scan_Period_Mode of BTTrainer.
PAGE 103
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.22 Read_PIN_Type Read_PIN_Type will read the PIN type specified in the host controller of BTTrainer. Command Parameters Examples Comments N/A Return Events Read_PIN_Type_Complete Read_PIN_Type_Error A.3.23 Read_Scan_Enable Read_Scan_Enable will read the value for the Scan_Enable configuration parameter, which controls whether or not BTTrainer will periodically scan for page attempts and/or inquiry requests from other Bluetooth devices.
PAGE 104
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.25 Read_Transmit_Power_Level Command Parameters Examples Comments HCI Handle Type A.3.26 Read_Stored_Link_Key Read_Stored_Link_Key will read one or all link keys stored in the BTTrainer Host Controller. Command Parameters Examples BD_ADDR 0x010203040506 Read_All_Flag 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 A.3.
PAGE 105
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Reset_Complete A.3.29 Set_Event_Filter 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.
PAGE 106
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.30 Set_Event_Mask Set_Event_Mask is used to control which events are generated by the HCI for the Host.
PAGE 107
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.32 Write_Automatic_Flush_Timeout Command Parameters Examples Comments HCI_Handle Flush_Timeout A.3.33 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 Examples Comments CoD 0x000000 Class of Device for the device Return Events Write_Class_of_Device_Complete Write_Class_of_Device_Error A.3.
PAGE 108
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.35 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.
PAGE 109
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.37 Write_Hold_Mode_Activity Command Parameters Examples Comments Activity A.3.38 Write_Inquiry_Scan_Activity Command Parameters Examples Comments Inquiry_Scan_Interval Inquiry_Scan_Window A.3.39 Write_Link_Supervision_Timeout Writes link supervision timeout setting for the specified ACL link.
PAGE 110
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.3.40 Write_Num_Broadcast_Retransmissions Command Parameters Examples Comments Retransmissions A.3.41 Write_Page_Scan_Activity Command Parameters Examples Comments Page_Scan_Interval Page_Scan_Window A.3.42 Write_Page_Scan_Mode Command Parameters Examples Comments Page_Scan_Mode A.3.43 Write_Page_Scan_Period_Mode Command Parameters Examples Page_Scan_Period_Mode 0x0001 Comments A.3.
PAGE 111
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Write_Page_Timeout_Complete Write_Page_Timeout_Error A.3.45 Write_PIN_Type Write_PIN_Type will specify whether the Host supports variable PIN or only fixed PINs. Command Parameters Examples Comments PIN_Type 0 0x00=Variable PIN 0x01=Fixed PIN Return Events Write_PIN_Type_Complete Write_PIN_Type_Error A.3.
PAGE 112
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Write_Stored_Link_Key_Complete Write_Stored_Link_Key_Error A.3.48 Write_Voice_Setting The Write_Voice_Setting command will write the values for the Voice_Setting parameter into BTTrainer, which controls all the various as settings for the voice connections.
PAGE 113
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Read_Buffer_Size_Complete Read_Buffer_Size_Error A.4.3 Read_Country_Code Read_Country_Code command will read the value for the Country_Code status parameter in BTTrainer. 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 A.4.
PAGE 114
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.5 Status Commands A.5.1 Read_Failed_Contact_Counter Command Parameters Examples Comments HCI_Handle A.5.2 Reset_Failed_Contact_Counter Command Parameters Examples HCI_Handle 0x0001 Comments A.6 HCI Testing Commands A.6.1 Enable_Device_Under_Test_Mode The Enable_Device_Under_Test_Mode command will allow BTTrainer to enter test mode via LMP test commands.
PAGE 115
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.6.3 Write_Loopback_Mode The Write_Loopback_Mode will write the value for the setting of the Host Controller’s Loopback_Mode into BTTrainer. Command Parameters Examples Comments Loopback_Mode 0 0x00=No Loopback mode enabled. Default 0x01=Enable Local Loopback 0x02=Enable Remote Loopback Return Events Write_Loopback_Mode_Complete Write_Loopback_Mode_Error A.7 CATC-Specific HCI Commands A.7.
PAGE 116
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Used in Test Cases Test Case TP/LIH/BV-35-C A.7.3 CATC_Disconnect This command will start a modified ACL disconnection procedure in order to verify that the IUT closes the link according to the TP/LIH/BV-04-C test case. During the procedure, LMP_Detach is sent, and after 3 seconds LMP_Features_Req PDUs is sent.
PAGE 117
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Used in Test Cases Test Case Description TP/LIH/BV-26-C Need to exit park mode by sending LMP_unpark_BD_ADDR_req. A.7.5 CATC_Get_Selected_Sco_Connection This command will return parameters for currently selected SCO connection. Command Parameters Examples Comments N/A Return Events Command Complete: Will return after the operation has completed. A.7.
PAGE 118
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.7.7 CATC_MaxSlot This command will send LMP_Max_Slot PDU to the remote device. Command Parameters Examples Comments HCI_Handle MaxSlot Return Events Command Status: Will return after the operation has started. Command complete: Will return after the operation has completed: LMP_Max_Slot PDU was sent. Used in Test Cases Test Case TP/LIH/BV-64-C A.7.8 CATC_MaxSlot_Response This command will start a special Max Slot request/response procedure.
PAGE 119
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.7.9 CATC_Modify_Beacon This command will send LMP_Modify_Beacon PDU to notify parked devices about beacon parameter change. Command Parameters Examples Comments HCI_Handle BeaconMaxInterval BeaconMinInterval Return Events Command Status: Will return after the operation has started. Command complete: Will return after the operation has completed: LMP_Modify_Beacon PDU was sent. Used in Test Cases Test Case TP/LIH/BV-25-C A.7.
PAGE 120
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events Command Status: Will return after the operation has started. Command Complete event will return after the operation has completed: LMP_Page_Mode_Req PDU was sent Used in Test Cases Test Case Description TP/LIH/BV-65-C Need to send LMP_Page_Mode_Req PDU TP/LIH/BV-66-C Need to send LMP_Page_Mode_Req PDU A.7.12 CATC_Page_Scan_Mode_Request This command will send LMP_Page_Scan_Mode_Req PDU to the remote device.
PAGE 121
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Command Parameters Examples N_bc Comments According to the Nbc parameter of LMP_Quality_Of_Service PDU Return Events Command Status: Will return after the operation has started. Command Complete: Will return after the operation has completed. Used in Test Cases Test Case TP/LIH/BV-39-C A.0.1 CATC_QoS_Response This command will configure the local device to accept or reject an incoming LMP_Quality_Of_Service_Request PDU for all connections.
PAGE 122
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.7.15 CATC_Read_Headset_Gain Reads the gain of the microphone or speaker of the headset. Command Parameters Examples Comments Device “Speaker” “Microphone” or “Speaker” (“Speaker” is default) Return Events CATC_Read_Headset_Gain_Complete CATC_Read_Headset_Gain_Error A.7.16 CATC_Read_Link_Key_Type Reads Link Key Type. Command Parameters Examples Comments N/A A.7.
PAGE 123
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.7.19 CATC_Sco_Parameter_Change_Response Configure local device to accept or reject an incoming request to change SCO parameters. Command Parameters Examples Comments Mode Return Events Command Complete Used in Test Cases Test Case TP/LIH/BV-56-C A.7.20 CATC_Select_SCO_Connection This command will select current SCO connection for up to three SCO connections.
PAGE 124
CATC BTTRAINER 2.20 APPENDIX A User’s Manual them is randomly selected to become the current connection. By default, "Data_Path" is set to "PCM", "Data_Length" is set to 0, and "Data_Pattern" is set to PRBS data. At least one SCO connection has to be open before calling this command. Command Parameters Values HCI_Handle Data_Path Description HCI Handle of the SCO connection to be selected.
PAGE 125
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.7.22 CATC_Set_Broadcast_Scan_Window This command will send LMP_Set_Broadcast_Scan_Window PDU to the parked devices to set a new BroadcastScanWindow. Command Parameters Examples Comments HCI_Handle BroadcastScanWindow Integer Return Events Generated Event: Command Status Generated Event: Command Complete A.7.23 CATC_Set_Default_PIN_Code Set the default PIN code, used for authentication purposes whenever a device-specific PIN is unavailable.
PAGE 126
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.7.25 CATC_Timing_Accuracy_Request This command will send LMP_Timing_Accuracy_Req PDU to the remote device. Command Parameters Examples Comments HCI_Handle Return Events Command Status: Will return after the operation has started Command Complete: Will return after the operation has completed. Used in Test Cases Test Case TP/INF/BV-05-C A.7.26 CATC_Write_Encryption_Key_Size Write Encryption Key Size.
PAGE 127
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.7.28 CATC_Write_Local_Supported_Features This command will write new local LMP supported features parameters for the device. . Command Parameters Examples LMP_Features Comments Bit Mask list of LMP features as defined in the Bluetooth 1.1 specification Return Events Command Complete: Will return after the operation has completed. Used in Test Cases Test Case TP/PROT/PIC/BV-03-C TP/PROT/PIC/BV-04-C A.7.
PAGE 128
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Command Parameters Examples Comments Examples Comments Examples Comments TokenRate TokenBucketSize PeakBandwidth Latency DelayVariation Return Events ConfigurationResponse_Complete A.8.2 GroupRegister Command Parameters PSM BD_ADDR A.8.3 GroupDestroy Command Parameters CID A.8.
PAGE 129
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events ConfigurationSetup_Complete Error A.8.6 ConnectRequest Requests establishment of an L2CAP channel in the remote Bluetooth device. Command Parameters Examples HCI_Handle 0x0001 PSM 0x1001 Receive MTU 0x1B6 Comments Return Events Connection_Complete Connection_Failed A.8.7 ConnectResponse Indicates the response to the incoming connection request.This command should be executed before Connection Request.
PAGE 130
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.8.9 DisconnectRequest Requests the disconnection of the specified L2CAP channel. Command Parameters Examples CID 0x0040 Comments Return Events Disconnection_Complete Disconnection_Failed A.8.10 EchoRequest Sends an Echo Request over the L2CAP channel. Command Parameters Examples HCI_Handle 0x0001 Data “echo” Comments Return Events EchoRequest_Complete EchoRequest_Failed A.8.11 InfoRequest Sends an Info Request over the L2CAP channel.
PAGE 131
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Command Parameters Examples Receive MTU 0x1B6 Comments Return Events RegisterPsm_Complete RegisterPsm_Failed A.8.13 SendData Sends data on the specified L2CAP channel. Command Parameters Examples CID 0x0040 Data Pipe “Pipe1” Return Events SendData_Complete SendData_Failed 113 Comments Data_Pipe should be created in the Data Transfer Manager.
PAGE 132
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.9 Other L2CAP Events Events Connection_Indication Disconnection_Indication Data_Indication Write_Configuration_Complete Command_Complete Error A.10 SDP Command Descriptions A.10.1 AddProfileServiceRecord This command will add a pre-defined Service Record according to one of the Bluetooth wireless technology profiles to the SDP database.
PAGE 133
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.10.2 AddServiceRecord This command will add a pre-defined Service Record according to one of the Bluetooth wireless technology profiles to the SDP database. Command Parameters Examples Comments Filename “C:/Records.sdp” 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.
PAGE 134
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.10.4 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.
PAGE 135
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.10.6 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 Note that all Attributes are requested since a range of 0x0000-0xFFFF is specified by default.
PAGE 136
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Return Events AcceptChannel_Complete A.11.2 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 Examples Comments Accept TRUE (Values: TRUE/FALSE) Return Events AcceptPortSettings_Complete A.11.
PAGE 137
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.11.5 CreditFlowEnabled This command is used to check if credit-based flow control has been negotiated for the current RFCOMM session. Command Parameters Examples Comments (HCI/DLCI) (0x0001, 0x02) The DLCI value is returned by the OpenClientChannel command Return Events CreditFlowEnabled_Complete A.11.6 DeregisterServerChannel Deregisters an RFCOMM server channel.
PAGE 138
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.11.8 RegisterServerChannel This command will register ServerChannel with an RFCOMM server so that the server can respond to incoming OpenClientChannel requests. Command Parameters Examples Comments AttachTo Return Events RegisterServerChannel_Complete RegisterServerChannel_Error A.11.9 RequestPortSettings This command will request a change to the current PortSettings.
PAGE 139
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.11.10 RequestPortStatus This command will request the status of the PortSettings for the remote device. Command Parameters Examples (HCI/DLCI) (0x0001, 0x02) Comments Return Events RequestPortStatus_Complete RequestPortStatus_Error A.11.11 SendData Causes BTTrainer to send data by pipe value to remote device over the specified channel.
PAGE 140
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Command Parameters Examples Comments LineStatus 0x0F 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 A.11.14 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.
PAGE 141
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.11.15 SendATCommand This command will send a selected AT command. Command Parameters Examples (HCI/DLCI) (0x0001, 0x02) AT_Command RING Comments Values: AT + CKPD = 200: Headset Button pressed. AT + VGM = 1: Microphone gain. +VGM = 1: Microphone gain 1.
PAGE 142
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.12 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.13 TCS Command Descriptions A.13.1 RegisterIntercomProfile Registers an Intercom identifier with TCS. Once registered, the protocol can initiate connections as well as receive connection requests.
PAGE 143
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.13.3 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 A.13.
PAGE 144
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.14 OBEX Command Descriptions A.14.1 ClientAbort Command Parameters Examples NA Comments . A.14.2 ClientConnect This command will create an OBEX connection with a remote device. Command Parameters Examples Comments BD_ADDR 0x010203040506 An HCI Connection has to be established before calling this command. Return Events ClientConnect_Complete ClientConnect_Error A.14.
PAGE 145
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.14.5 ClientPut This command will initiate an OBEX Put operation in the remote device for the object defined in the FileName parameter. Command Parameters Examples Filename “C:\VCard.vcf” Comments Return Events ClientPut_Complete ClientPut_Error A.14.6 ClientSetPath This command will initiate an OBEX SetPath operation in the remote device. Flags indicate SetPath option such as Backup.
PAGE 146
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.14.8 ServerInit This command will initialize the OBEX server. Command Parameters Examples Comments N/A Return Events ServerInit_Complete ServerInit_Error A.14.9 ServerSetPath Sets the path where received OBEX files are stored. Command Parameters Examples Comments Path “C:\OBEX” Use the “...” button to select a path, or type one in.
PAGE 147
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.15 BNEP Commands A.15.1 Accept Command Parameters Examples Comments Examples Comments AcceptConnection A.15.2 Open Command Parameters BD_ADDR . A.15.3 Close Command Parameters Examples Comments BNEP_ADDR A.15.4 SetUpConnectionReq Command Parameters Examples BNEP_ADDR Comments . Destination UUID Source UUID A.15.5 SentPKT Command Parameters Examples BNEP_ADDR Comments . Packet_Type A.15.
PAGE 148
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.15.7 RegisterBNEP Command Parameters Examples Comments Examples Comments Examples Comments NA A.15.8 DeregisterBNEP Command Parameters NA A.15.9 SetControlTimeout Command Parameters BNEP_ADDR Timeout A.16 TCI Commands A.16.1 CATC_EnterTestMode This command puts a remote slave device into test mode. Command Parameters Examples Comments N/A Return Events Command Status: Will return after the operation has started.
PAGE 149
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Parameters Packet Type - Presents a menu of Packet types. Packet Length - Enter a value in bytes. L_CH=01, L_CH=10, L_CH=11 - Defines payload header L_CH value and type of payload to be sent. Data payload of L_CH=11b is restricted to a pseudo-random value that does not match any existing LMP PDU. Duration - Set time in msec. Time Length - Enter a value in msec. Error Type - Presents a menu of error types. Error Mask - Defines error distribution.
PAGE 150
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Hops Sequence - presents a menu with three options: 79 Hops Standard, Fixed Frequency, and Reduced Hop. Poll Repetion - Presents a text box for entering a time value. Power Control - Presents a menu with two options: Adaptive power control and Fixed Tx Output Power. A.16.3 CATC_CreateConnectionExt This command supports TCI functionality that requires BTTrainer to be connected as a master device to the IUT.
PAGE 151
CATC BTTRAINER 2.20 APPENDIX A User’s Manual L_CH=01, L_CH=10, L_CH=11 - Defines payload header L_CH value and type of payload to be sent. Data payload of L_CH=11b is restricted to a pseudo-random value that does not match any existing LMP PDU. Duration - Set time in msec. Time Length - Enter a value in msec. Error Type - Presents a menu of error types. Error Mask - Defines error distribution. Insert an error into a payload or in to header.
PAGE 152
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Parameters Packet Type - Presents a menu of Packet types. Packet Length - Enter a value in bytes. L_CH=01, L_CH=10, L_CH=11 - Defines payload header L_CH value and type of payload to be sent. Data payload of L_CH=11b is restricted to a pseudo-random value that does not match any existing LMP PDU. Duration - Set time in msec. Time Length - Enter a value in msec. Error Type - Presents a menu of error types. Error Mask - Defines error distribution.
PAGE 153
CATC BTTRAINER 2.20 APPENDIX A User’s Manual Hops Sequence - presents a menu with three options: 79 Hops Standard, Fixed Frequency, and Reduced Hop. Poll Repetion - Presents a text box for entering a time value. Power Control - Presents a menu with two options: Adaptive power control and Fixed Tx Output Power. A.16.5 CATC_SetClock Command Parameters Examples Comments BluetoothClock Return Events Command Complete: Will return after the operation has completed. A.16.
PAGE 154
CATC BTTRAINER 2.20 APPENDIX A User’s Manual A.16.8 CATC_PageScan Enter modified Page Scan mode. Command Parameters Examples TestScenario Comments . ClockOffset Return Events Command Status: Will return after the operation has started. Command Complete: Will return after the operation has completed. A.16.9 CATC_Inquiry Initiate a modified Inquiry procedure to the IUT.
PAGE 155
CATC BTTRAINER 2.11 CHAPTER User’s Manual Appendix B: BTTrainer Scripting Commands BTTrainer supports scripting commands to help automate testing processes and commonly used sequences of Bluetooth commands. Custom scripts can be written, saved, and run in Script Manager. B.1 Bluetooth Addresses Bluetooth addresses are represented in scripts as binary strings in big-endian byte order.
PAGE 156
CATC BTTRAINER 2.11 CHAPTER User’s Manual #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.
PAGE 157
CATC BTTRAINER 2.
PAGE 158
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value 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.
PAGE 159
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • • Device name “Not connected” “Failure” Comments Queries the specified device for its name. An ACL connection must be established before calling GetRemoteDeviceName().
PAGE 160
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • “Success” “Failure” Comments Sets the device class of BTTrainer Example SetDeviceClass(0x010203); Sleep Sleep(Time) Parameter Meaning Time Time in ms Default Value Comments Return value None. Comments Delays program execution for Time in milliseconds. Example Sleep(1000); # Sleep for one second B.
PAGE 161
CATC BTTRAINER 2.11 CHAPTER User’s Manual • • • “Failure” “Pipe Not Found” “Invalid parameter” Comments Closes the specified data pipe. Example ClosePipe("Data1", "Receive"); DeletePipe DeletePipe(PipeName, PipeType) Parameter Meaning PipeName Name of the data pipe to open PipeType “Transmit” or “Receive” pipe Default Value Comments “Receive” Return value • • • “Success” “Invalid parameter” “Pipe not found” Comments Removes a pipe from the Data Transfer Manager pipe list.
PAGE 162
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Default Value PipeType “Transmit” or “Receive” pipe “Receive” Comments 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.
PAGE 163
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 164
CATC BTTRAINER 2.11 CHAPTER User’s Manual B.4 HCI Commands HCIAcceptConnectionRequest HCIAcceptConnectionRequest() Parameter Meaning Default Value Comments N/A Return value • “Success” Comments Sets the accept connection request variable to True.
PAGE 165
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example result = HCIAddSCOConnection(Devices[0], ["DM1", "HV1"]); if(result != "Success") { MessageBox(result, "Failed to add SCO connection!"); } HCIAuthenticationRequested HCIAuthenticationRequested(Address) Parameter Meaning Address Bluetooth address of device to authenticate with Default Value Comments A connection must exist with this device for an authentication request to work.
PAGE 166
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 167
CATC BTTRAINER 2.11 CHAPTER User’s Manual status = Disconnect('00803713BDF0'); Trace("Disconnect result: ", status, "\n"); } } HCICatcDecreasePowerRequest HCICatcDecreasePowerRequest(HCI_Handle) Parameter Meaning Default Value Comments HCI_Handle Return value • • Command Status: Will return after the operation has started Command Complete: will return after the operation has completed. Comments This command will send LMP_Decr_Power_Req PDU to the remote device predefined number of times.
PAGE 168
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • Command Complete event will return after the operation has started. Disconnection Complete event will return after the operation has completed: LMP_Detach and LMP_Features_Req are sent Comments This command will start a modified ACL disconnection procedure in order to verify that the IUT closes the link according to the TP/LIH/BV-04-C test case. During the procedure, LMP_Detach is sent, and after 3 seconds LMP_Features_Req PDUs is sent.
PAGE 169
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCICATCGetSelectedSCOConnection HCICATCGetSelectedSCOConnection() Parameter N/A Meaning Default Value Comments Return Events • Command Complete: Will be returned after the operation has completed. Comments This command will return parameters for currently selected SCO connection.
PAGE 170
CATC BTTRAINER 2.
PAGE 171
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCICATCMaxSlot HCICATCMaxSlot(HCI_Handle,MaxSlot) Parameter HCI_Handle Meaning Default Value 2 Bytes MaxSlot Comments According to the LMP_MaxSlot PDU in the Bluetooth 1.1 HCI specification 1 Byte Return Events • • Command Status event will return after the operation has started Command Complete: Will return after the operation has been completed. Comment Command Complete event will return after the operation has completed: LMP_Max_Slot PDU was sent.
PAGE 172
CATC BTTRAINER 2.
PAGE 173
CATC BTTRAINER 2.11 CHAPTER User’s Manual TP/LIH/BV-64-C HCICATCOverrideRemoteFeatureCheck HCICATCOverrideRemoteFeatureCheck(HCI_Handle) Parameter Values Description HCI_Handle 2 Bytes Return Events • Command Complete: Will return after the operation has been completed. Comment This command will override remote device LMP feature check in case local device needs to initiate a procedure that remote device doesn’t support.
PAGE 174
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return Events • • Command Status event will return after the operation has started Command Complete: Will return after the operation has been completed.
PAGE 175
CATC BTTRAINER 2.11 CHAPTER User’s Manual TP/LIH/BV-71-C HCICATCPageScanModeResponse HCICATCPageScanModeResponse(Mode) Parameter Mode Values Description 0 -- Accept (default) 1 Byte 1 -- Reject 2-0xFF default Return Events • Command Complete: Will return after the operation has been completed. Comment This command will configure local device to respond to an incoming LMP_Page_Scan_Mode_Req PDU.
PAGE 176
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comment: This command will send LMP_Quality_Of_Service PDU over ACL connection according to the test case.
PAGE 177
CATC BTTRAINER 2.11 CHAPTER User’s Manual Trace("HCICatcQoSResponse: ", result , "\n"); } HCICatcReadHeadsetGain HCICatcReadHeadsetGain(Device) Parameter Meaning Device Speaker or microphone Default Value Comments Values: “Speaker”, “Microphone” Return values Returns a list with two values: status and gain. Status (element 0) is one of the following: • • • • “Success” “Failure” “Not found” “No SCO connection” Gain (element 1) is the one-byte value of the headset gain. Range is 0 to 15.
PAGE 178
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments Read the size of the encryption key that is going to be used during an encryption process Example result = HCICatcReadEncryptionKeySize (); Trace(result); HCICatcReadRevisionInformation HCICatcReadRevisionInformation() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and revision.
PAGE 179
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return • • Command Status will return after the operation has started. Command Complete will return after the operation has completed Comment: This command will send data over SCO connection with injected errors according to the test case.
PAGE 180
CATC BTTRAINER 2.11 CHAPTER User’s Manual } HCICATCSelectSCOConnection HCICATCSelectSCOConnection(HCI_Handle, Data_Path, Data_Length) Parameter Meaning Default Value HCI_Handle Comments HCI Handle of the SCO connection to be selected. Data_Path 0 - "PCM" (default) 1 - "HCI" "PCM" -- PCM CODEC is used to send and receive voice data for the current SCO connection. "HCI" -- voice data is sent according to the "Data_Pattern" parameter. The received voice data is routed to the PCM CODEC.
PAGE 181
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example Trace("Merlin's Wand Self Test : ", HCICatcSelfTest(), "\n"); HCICATCSetBroadcastScanWindow HCICATCSetBroadcastScanWindow(HCI_Handle,BroadcastScanWi ndow) Parameter Values Description HCI_Handle 2 Bytes BroadcastScanWindow According to the LMP_Set_Broadcast_Scan_Window PDU in the Bluetooth 1.
PAGE 182
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example PINCode = "12345"; Result = HCICatcSetDefaultPINCode (PINCode) Trace(Result); HCICatcSetParkMode HCICatcSetParkMode(ParkMode) Parameter ParkMode 1 Byte Values 0 (default) - parking by PM_ADDR Description In the ParkMode=1, PM_ADDR is assigned 0.
PAGE 183
CATC BTTRAINER 2.
PAGE 184
CATC BTTRAINER 2.
PAGE 185
CATC BTTRAINER 2.
PAGE 186
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • • • “Success” “Failure” “Not found” “Not connected” Comments This command is used to force both devices associated with a connection to generate a new link key.
PAGE 187
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example result = HCIChangeConnectionPacketType('00803713BDF0', ["DM3","DM5"]); Trace("Change Connection Packet Type:\n"); Trace(" Status ", result[0], "\n"); HCIChangeLocalName HCIChangeLocalName(Name) Parameter Meaning Name String that contains the new name for the local device Default Value Comments Return value • • “Success” “Failure” Comments Attempts to change the name of the local device.
PAGE 188
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments This command is used to create a new unit key. The Bluetooth hardware will generate a random seed that will be used to generate the new unit key. All new connection will use the new unit key, but the old unit key will still be used for all current connections.
PAGE 189
CATC BTTRAINER 2.
PAGE 190
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCIExitSniffMode HCIExitSniffMode(Address) Parameter Meaning Address Bluetooth address of device in question Default Value Comments Return value • • • • “Success” “Failure” “Failed: Device not found” “Not connected” Comments Exits Sniff mode.
PAGE 191
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example Device = '010203040506'; result = HCIFlush (Device); Trace(result); HCIGetSCOConnections HCIGetSCOConnections(HCI_Handle) Parameter Meaning Default Value Comments HCI_Handle Return value • • • “Success” “Failure” “Failed: Device not found” Comments Returns the handles of any active SCO connections to this device.
PAGE 192
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • • • “Success” “Failure” “Failed: Device not found” “Not connected” Comments Enters Hold mode with parameters as specified.
PAGE 193
CATC BTTRAINER 2.11 CHAPTER User’s Manual Trace(" Key Flag : 0x", result[2], "\n"); } HCIParkMode HCIParkMode(Address, BeaconMaxInterval, BeaconMinInterval) Parameter Meaning Default Value Comments Address Bluetooth address of device in question Beacon MaxInterval Maximum number of 0.625-msec intervals between beacons. Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec). Beacon MinInterval Minimum number of 0.625-msec intervals between beacons. Range is 0x0001 to 0xFFFF (0.625 msec to 40.
PAGE 194
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCIPINCodeRequestNegativeReply HCIPINCodeRequestNegativeReply(Address) Parameter Meaning Address Bluetooth address of device for which no PIN code will be supplied. Default Value Comments Return value • • “Success” “Failure” Comments Specifies a device for which no PIN code will be supplied, thus causing a pair request to fail.
PAGE 195
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments Specifies the PIN code to use for a connection.
PAGE 196
CATC BTTRAINER 2.11 CHAPTER User’s Manual • • “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.) 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.
PAGE 197
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.) Comments This command will read the value for AuthenticationEnable parameter.
PAGE 198
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 199
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 200
CATC BTTRAINER 2.11 CHAPTER User’s Manual • • “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.
PAGE 201
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 202
CATC BTTRAINER 2.11 CHAPTER User’s Manual • “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.
PAGE 203
CATC BTTRAINER 2.
PAGE 204
CATC BTTRAINER 2.11 CHAPTER User’s Manual Status (element 0) is one of the following: • • "Success" "Failure" Comments This command will read the value for the Hold_Mode_Activity parameter. Example result = HCIReadHoldModeActivity (); Trace(result); HCIReadInquiryScanActivity HCIReadInquiryScanActivity() Parameter Meaning Default Value Comments N/A Return values Returns a list with three values: status, InquiryScanInterval, InquiryScanWindow.
PAGE 205
CATC BTTRAINER 2.11 CHAPTER User’s Manual if (result[0] == "Success") { Trace("InquiryScanInterval is: 0x", result[1], "\n"); Trace("InquiryScanWindow is : 0x", result[2], "\n"); } HCIReadLinkPolicySettings HCIReadLinkPolicySettings(Address) Parameter Meaning Address Bluetooth address of device in question Default Value Comments Return value Returns the following list of values: status and link policy settings.
PAGE 206
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCIReadLinkSupervisionTimeout HCIReadLinkSupervisionTimeout(Address) Parameter Meaning Address Bluetooth address of device in question Default Value Comments Return value 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 multiples of 0.
PAGE 207
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 208
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 version, 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.
PAGE 209
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 210
CATC BTTRAINER 2.11 CHAPTER User’s Manual • “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.
PAGE 211
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCIReadPageScanActivity HCIReadPageScanActivity() Parameter Meaning Default Value Comments N/A Return values Returns a list with three values: status, PageScanInterval, PageScanWindow. Status (element 0) is one of the following: • • "Success" "Failure" PageScanInterval (element 1) and PageScanWindow (element 2) are the two byte values. Comments This command will read the value for Page_Scan_Activity configuration parameter.
PAGE 212
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return values 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.
PAGE 213
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example 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.
PAGE 214
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 215
CATC BTTRAINER 2.11 CHAPTER User’s Manual • • “Failed: Device not found” “Not connected” Features (element 1) is the eight-byte bit mask list of Link Manager Protocol features. Comments Reads the LMP supported features for the specified device. An ACL connection with the device is required.
PAGE 216
CATC BTTRAINER 2.11 CHAPTER User’s Manual LMP subversion (element 3) is the two-byte Link Manager Protocol subversion value. Comments Reads the version information for the specified device. An ACL connection with the device is required.
PAGE 217
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 218
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Default Value ReadAll Boolean value that indicates whether to read only the specified address's link key, or all link keys 0 Comments 0 or 1 Return values Returns a list with two values: status and data.
PAGE 219
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 connections.
PAGE 220
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCIRemoveSCOConnection HCIRemoveSCOConnection(Address) Parameter Meaning Address Bluetooth address of device to connect with Default Value Comments Return value • • • “Success” “Not connected” “Failure” Comments Removes an existing SCO connection associated with the specified device.
PAGE 221
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCIResetFailedContactCounter HCIResetFailedContactCounter(Address) Parameter Meaning Default Value Comments Address Return value • • • • "Success" "Failure" "Not connected" "Failed: Not found" Comments This command will reset the value for the Failed_Contact_Counter parameter for a particular connection to another device.
PAGE 222
CATC BTTRAINER 2.
PAGE 223
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCISetEventFilter HCISetEventFilter(FilterType, FilterConditionType, Condition) Parameter Meaning Default Value Comments FilterType Filter type: 0 = Clear all filters; 1 = Inquiry result; 2 = Connection setup; 3-255 = Reserved If value 0 is used, no other parameters should be supplied. Filter Condition Type Type of filter condition. This parameter has different meanings depending on the filter type. Condition Details of the filter to be set.
PAGE 224
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCISniffMode HCISniffMode(Address, MaxInterval, MinInterval, Attempt, Timeout) Parameter Meaning Default Value Comments Address Bluetooth address of device in question MaxInterval Maximum number of 0.625-msec intervals between sniff periods. Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec). MinInterval Minimum number of 0.625-msec intervals between sniff periods. Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec).
PAGE 225
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCISwitchRole HCISwitchRole(Address, Role) Parameter Meaning Address Bluetooth address of device in question Default Value Role Comments Values: “Master”, “Slave” Return value • • • • • “Success” “Failure” “Failed: Device not found” “Not connected” “Invalid parameter” Comments Switches the current role of the device in the piconet.
PAGE 226
CATC BTTRAINER 2.
PAGE 227
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Default Value Comments FlushTimeout Return value Returns a list with two values: status and FlushTimeout Status (element 0) is one of the following: • • • • "Success" "Failure" "Not connected" "Failed: Not found" Comments This command will write the value for the Flush_Timeout parameter for the specified connection handle.
PAGE 228
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 Meaning Default Value Comments NumCurrent IACs Number of current IACs. Must be 1 or 2.
PAGE 229
CATC BTTRAINER 2.
PAGE 230
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • • • “Success” “Failure” “Failed: Device not found” “Not connected” Comments Writes the value for the Link_Policy_Settings parameter for the device.
PAGE 231
CATC BTTRAINER 2.
PAGE 232
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value Status is one of the following • • "Success" "Failure" Comments The Page_Scan_Interval configuration parameter defines the amount of time between consecutive page scans.
PAGE 233
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCIWritePageScanPeriodMode HCIWritePageScanPeriodMode (PageScanPeriodMode) Parameter Meaning Default Value Comments PageScanPeriodMode Return value Returns a list with two values: Status and PageScanPeriodMode Status (element 0) is one of the following: • • • "Success" "Failure" "Invalid Parameter" Comments Write the mandatory Page_Scan_Period_Mode of the local device.
PAGE 234
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 Meaning PINType PIN type: 0=Variable PIN; 1=Fixed PIN Default Value Comments Range is 0 to 1.
PAGE 235
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments Sets the accessible mode of BTTrainer. Example HCIWriteScanEnable("CONNECTABLE_ONLY"); HCIWriteStoredLinkKey HCIWriteStoredLinkKey(Address, LinkKey) Parameter Meaning Address Bluetooth address of device that will have its link key stored LinkKey String containing the link key to be stored Default Value Comments Up to 32 Hex digits Return value • • “Success” “Failure” Comments Attempts to store the link key for the specified address.
PAGE 236
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning VoiceSetting Three-digit hex value containing the voice settings Default Value Comments 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.
PAGE 237
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 238
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example result = OBEXClientDisconnect(); OBEXClientGet OBEXClientGet(RemotePath, LocalPath) Parameter Meaning RemotePath Path and name of object to be retrieved from server. LocalPath Path and name of object to be created on client. Default Value Comments Path is relative to server’s OBEX directory. Example: If the OBEX directory is C:\temp, a RemotePath of “file.txt” would cause the client to retrieve “C:\temp\file.
PAGE 239
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 server’s 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.
PAGE 240
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Default Value Comments RemotePath Path and name of object to be stored on server. Name-only portion of LocalPath argument Path is relative to server’s OBEX directory. Example: If the server’s 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.
PAGE 241
CATC BTTRAINER 2.11 CHAPTER User’s Manual OBEXClientSetPath OBEXClientSetPath(Path, Flags) Parameter Meaning Default Value Comments Path New path to set Path is relative to server’s current working directory. Cannot begin “C:” or “\\\\”.
PAGE 242
CATC BTTRAINER 2.
PAGE 243
CATC BTTRAINER 2.11 CHAPTER User’s Manual • “Failure” Comments Initializes an OBEX server. Example result = OBEXServerInit(); OBEXServerSetPath(Path) OBEXServerSetPath(Path) Parameter Meaning Path Path to be used as the OBEX root directory on the server Default Value Comments 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.
PAGE 244
CATC BTTRAINER 2.11 CHAPTER User’s Manual B.
PAGE 245
CATC BTTRAINER 2.11 CHAPTER User’s Manual • • • • • “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.
PAGE 246
CATC BTTRAINER 2.11 CHAPTER User’s Manual RFSendData RFSendData(Address, DLCI, Data) Parameter Meaning Address Bluetooth address of device DLCI Data link connection identifier Data Data to send Default Value Comments 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.
PAGE 247
CATC BTTRAINER 2.11 CHAPTER User’s 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.
PAGE 248
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments Receives data from a device connected via RFCOMM. Waits Timeout milliseconds (or infinitely if 0 is specified) for the device to begin sending data to Merlin's Wand.
PAGE 249
CATC BTTRAINER 2.11 CHAPTER User’s Manual RFCOMM connection is already present when this function is called, it will immediately return “Success”.
PAGE 250
CATC BTTRAINER 2.
PAGE 251
CATC BTTRAINER 2.
PAGE 252
CATC BTTRAINER 2.
PAGE 253
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Xon Number indicating the XON character Xoff Number indicating the XOFF character Default Value Comments Return value • • • • “Success” “Failure” “Not connected” “Timed Out” Comments Submits a request to change the port settings on a particular RFCOMM connection.
PAGE 254
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value Returns a list with two values: status and portSettings.
PAGE 255
CATC BTTRAINER 2.11 CHAPTER User’s Manual RFSendTest() RFSendTest (Address, DLCI, Length, Pattern); Parameter Meaning Address Bluetooth address of device to query DLCI DLCI value to be used for the channel. Length Length of pattern in the command Pattern Pattern to be sent Default Value Comments The DLCI value is used for the channel. Return value Returns "Success", "Failure", "Not Connected", "Timed Out".
PAGE 256
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • • • “Success” “Failure” “Not Connected” “Timed Out” Comments Sets the line status on a particular RFCOMM connection.
PAGE 257
CATC BTTRAINER 2.
PAGE 258
CATC BTTRAINER 2.11 CHAPTER User’s Manual RFSendTest RFSendTest(Address, DLCI) Parameter Meaning Default Value Comments Address Bluetooth address of device 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.
PAGE 259
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning credit Number of credits to advance Default Value Comments Return value • • • “Success” “Failure” “Not Connected” Comments Advances a specified number of credits to a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1); DLCI = result[1]; if(result[0] == "Success") { status = RFAdvanceCredit(Device, DLCI, 2); Trace("RFAdvanceCredit returned: ", status, "\n\n"); } B.
PAGE 260
CATC BTTRAINER 2.
PAGE 261
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 262
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments This command can be called after a TCS channel is opened. It sends an INFORMATION TCS message with a called party number.
PAGE 263
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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"); } B.
PAGE 264
CATC BTTRAINER 2.11 CHAPTER User’s Manual BNEPClose() BNEPClose(BNEP_Address) Parameter Meaning BNEP_Address BNEP Address of the connection to be closed Default Value Comments Return value • • • • • "Success" "Failure" "Failed: Not found" "No BNEP connection" "Not connected" Comments Close BNEP connection with BNEP_Address.
PAGE 265
CATC BTTRAINER 2.11 CHAPTER User’s Manual BNEPOpen() BNEPOpen(Address) Parameter Meaning Address Address of the remote Bluetooth device Default Value Comments Return value Returns a list with the following values: status , BNEP_Address, ChannelID, ControlTimeout. Status (element 0) is one of the following: • • • • • "Success" "Failure" "Not connected" "Failed: Not found" "Timed out" Comments Open BNEP channel to a remote device.
PAGE 266
CATC BTTRAINER 2.
PAGE 267
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Packet_Type Possible types are: "compressed ethernet" "comp ethernet source only" "comp ethernet dest only" "general ethernet" "general with ext hdr Default Value Comments Return value • • • • • • • "Success" "Failure" "Invalid Parameter" "Timed out" "Failed: Not found" "No BNEP connection" "Not connected" Comments Send a predefined BNEP packet to the remote device.
PAGE 268
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning data_to_send byte stream which will be sent over this connection as a BNEP command Default Value Comments Return value • • • • • "Success" "Timeout" "Invalid Parameter" "Busy" "Failure" Comments This command provides means to send a sequence of bytes over a connection as a BNEP command.
PAGE 269
CATC BTTRAINER 2.
PAGE 270
CATC BTTRAINER 2.11 CHAPTER User’s Manual B.9 L2CAP Commands L2CAPConfigurationRequest L2CAPConfigurationRequest(FlushTimeout, ServiceType, TokenRate, TokenBucketSize, PeakBandwidth, Latency, DelayVariation) Parameter Meaning Default Value FlushTimeout Amount of time that the sender will attempt transmission before flushing the packet 0xFFFF ServiceType The required level of service 0x01 TokenRate The rate at which traffic credits are granted 0x00000000 0x00000000: no token rate is specified.
PAGE 271
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter DelayVariation Meaning Default Value Comments This value 0xFFFFFFFF The default value represents a Do Not Care. represents the The difference is in microseconds. difference between the maximum and minimum delay possible that a packet will experience Return value • • “Success” “Failure” Comments This command is used to request specified configuration for L2CAP channel. It should be executed before L2CAPConnectRequest().
PAGE 272
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example L2CAPConfigurationResponse("Reject-unknown options"); L2CAPConnectRequest L2CAPConnectRequest(Address, PSM, ReceiveMTU) Parameter Meaning Address Bluetooth address of the remote device Default Value Comments PSM ReceiveMTU 0x01C2 Return value Returns a list with three values: result, ACL Handle, and a list of all L2CAP CIDs.
PAGE 273
CATC BTTRAINER 2.11 CHAPTER User’s Manual L2CAPConnectResponse L2CAPConnectResponse(Response) Parameter Meaning Response Default Value “Accept” Comments 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.
PAGE 274
CATC BTTRAINER 2.
PAGE 275
CATC BTTRAINER 2.
PAGE 276
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value Returns a list with the following values: [status, GroupList] Status (element 0) is one of the following: • • • ·"Success" ·"Timed out" ·"Failed: Not found" GroupList has a format [Group1…GroupN] Group has a format [GroupCID, GroupPSM, GroupMember1…GroupMemberM] Comments Returns the list of all registered L2CAP groups for connectionless L2CAP connections.
PAGE 277
CATC BTTRAINER 2.11 CHAPTER User’s Manual L2CAPInfoRequest L2CAPInfoRequest(Address) Parameter Meaning Address Bluetooth address of the remote device Default Value Comments 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.
PAGE 278
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning ReceiveMTU Default Value Comments 0x1C2 Incoming MTU size for L2CAP connection with that PSM Return value • • • “Success” “Failure” “In use” Comments This command is used to register a PSM identifier with L2CAP.
PAGE 279
CATC BTTRAINER 2.11 CHAPTER User’s Manual L2CAPSendDataFromPipe L2CAPSendDataFromPipe(ChannelID, PipeName) Parameter Meaning ChannelID L2CAP ChannelID to send data to PipeName Name of the transmit data pipe to get data to send Default Value Comments 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.
PAGE 280
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 } B.
PAGE 281
CATC BTTRAINER 2.
PAGE 282
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Default Value PduID PDU ID that would be used for the request 1 Size Number of bytes to be used from ’data.’ data_to_send Byte values to be used for constructing the ASDP request. Comments 1 byte value Hex values Return value • • "Success" “Failure” Comments This command provides means to send an SDP request with a sequence of bytes provided by the user.
PAGE 283
CATC BTTRAINER 2.
PAGE 284
CATC BTTRAINER 2.11 CHAPTER User’s Manual Return value • • SDP Services "Failure " Comments Locate service records based on a search pattern. Example result = SDPRequestServiceSearch(Device[0], 2, 0x1000, 0x1001, 0); if (result != "Success") { Trace("SDPRequestServiceSearch() - Failed.
PAGE 285
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example result = SDPRequestServiceAttribute(Device, 0, 2, 0x0001, 0x0002, 0); if (result != "Success") { Trace("SDPRequestServiceAttribute() - Failed.
PAGE 286
CATC BTTRAINER 2.11 CHAPTER User’s Manual SDPRequestServiceSearchAttribute SDPRequestServiceSearchAttribute(Address, AttributesNum, Attribute) Parameter Meaning Address Bluetooth address of device to query AttributesNum Number of attributes Attribute1Attribute3 Attribute values to search Default Value 1 Comments 1-3 Return value • • SDP Attribute values “Failure” Comments Retrieve attribute values that match the service search pattern.
PAGE 287
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example SDPResetDatabase(); B.11 TCI Commands HCICatcAcceptConnectionExt HCICatcAcceptConnectionExt(TestScenario, PacketType, NumberOfPackets, Data, ErrorType, ErrorMask, Tx Jitter) Comments This command supports TCI functionality that requires BTTrainer to be connected as a slave device. The command will accept an incoming connection request from the master, and configure BTTrainer to perform the specified test.
PAGE 288
CATC BTTRAINER 2.11 CHAPTER User’s Manual Parameter Meaning Default Value Comments ErrorMask 0 - Random error distribution >0 - Error bit positions If ErrorType is not zero, this parameter is valid. It defines error distribution. For uncorrectable FEC 2/3, random error distribution, several erroneous bits will be inserted in every 15-bit packet. Valid for DM packet types For uncorrectable FEC 1/3 header, random error distribution, two error bit will be inserted in every 3-bit packet.
PAGE 289
CATC BTTRAINER 2.11 CHAPTER User’s Manual ErrorType 0x0000 No error 0x0001 Send NULL packets with NAK as the response to the incoming data packets 0x0002 Implicit NAK. No response to the incoming data packets. 0x0004 Uncorrectable FEC 1/3 header error injection 0x0008 Uncorrectable FEC 2/3 payload error injection 0x0010 FLOW control bit set to 0. NAK bit is set as well. 0x0020 FLOW control bit set to 0. NAK bit is set as well. Implicit GO.
PAGE 290
CATC BTTRAINER 2.
PAGE 291
CATC BTTRAINER 2.11 CHAPTER User’s Manual AllowRoleSwitch Values defined for HCI_CreateConnection command. Value will be 0x00 (not allow role switch) if ErrorType is not 0. NumberOfPackets 0x0001 -- 0xFFFF Number of packets to transmit. On completion, only NULL-POLL packets will be transmitted to maintain the connection TimeLength 0x0000 -- 0xFFFF (ms) Amount of time to send data packets. After TimeLength, only NULL-POLL packets will be transmitted to maintain the connection.
PAGE 292
CATC BTTRAINER 2.11 CHAPTER User’s Manual 3 L_CH = 11 - LMP Message ErrorType 0x0000 No error 0x0001 FEC 1/3 -- uncorrectable packet header 0x0002 FEC 2/3 -- uncorrectable payload. Special case is for DV payload 0x0004 Explicit NAK 0x0008 SEQN. See TP/PROT/ARQ/BV-18-C test case 0x0010 FLOW control 0x0020 Same SEQN value.
PAGE 293
CATC BTTRAINER 2.
PAGE 294
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCICatcSetBdAddr HCICatcSetBdAddr(Address) Parameter Meaning Default Value Comments Address Return value • • "Success" "Failure" Comments The command will set the value of the local Bluetooth device address.
PAGE 295
CATC BTTRAINER 2.
PAGE 296
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCICatcInquiryScan HCICatcInquiryScan(TestScenario,Ninquiry) Parameter TestScenario Meaning Default Value Comments 0x00 -Exit Inquiry Scan test mode 0x01- Disable responding to incoming inquiry ID packets. Perform according to TP/PHYS/INQ/BV-01-C or TP/PHYS/INQ/BV-02-C according to the current Country Code settings. 0x02-0xFF- Reserved Ninquiry Number of train repetitions.
PAGE 297
CATC BTTRAINER 2.11 CHAPTER User’s Manual HCICatcPage HCICatcPage(Address, TestScenario, NumberOfTimes) Parameter Values Device Address Description Bluetooth address of the paged device. TestScenario 0x00 Return to use the normal Page 0x01 The tester pages the IUT only in the first half of the Tx time slot. After receiving response, the tester does not send an FHS packet. The test continues according to TP/PHYS/PAG/BV-10-C or TP/PHYS/PAG/BV-11-C test case according to the current Country Code.
PAGE 298
CATC BTTRAINER 2.11 CHAPTER User’s Manual Used in Test Cases Test Case Description TP/PHYS/PAG/BV-10-C Page response 1/1 slot/79 channel. TP/PHYS/PAG/BV-12-C Page response 1/2 slot/79 channel TP/PHYS/PAG/BV-14-C Page scan interval R0. TP/PHYS/PAG/BV-16-C Page scan interval R1. TP/PHYS/PAG/BV-18-C Page scan interval R2.
PAGE 299
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments This command supports TCI functionality that requires BtTrainer to enter modified Page Scan mode, and respond to the IUT Page attempts as required by the Bluetooth Baseband test cases Used in Test Cases Test Case Description TP/PHYS/PAG/BV-01-C Page hop seq/79 channel. Tester does not respond to the Page ID packets as defined in this test case. TP/PHYS/PAG/BV-03-C Page response to 1st msg/79 channel.
PAGE 300
CATC BTTRAINER 2.11 CHAPTER User’s Manual Test 0x00 Pause Test Mode Values defined for LMP_TestControl command. Scenario This parameter defines the transmitted data type and the loopback mode.
PAGE 301
CATC BTTRAINER 2.11 CHAPTER User’s Manual PowerControl Mode 0 Fixed Tx output power 1 Adaptive power control Values defined for LMP_TestControl command 1 Byte PollPeriod** 1 Byte Example: 1 - POLL is sent every master-to-slave slot Values defined for LMP_TestControl command. Units: 1.
PAGE 302
CATC BTTRAINER 2.11 CHAPTER User’s Manual PacketLength 0x0000 - MaxPacketSize Cannot be longer than the maximum packet size of the selected min(PacketType, maxHCICommandLength). 2 Bytes Currently it’s set to 224 Bytes. In Closed Loopback mode, set to 0 (not applicable) Data If TestScenario does not require a predefined data pattern, this parameter will be used. Otherwise, it’ll be ignored. From 0 to Data length is defined by the PacketLength parameter. If it is 0, this parameter will be ignored.
PAGE 303
CATC BTTRAINER 2.11 CHAPTER User’s Manual ErrorMask 0 2 Bytes Random error distribution If ErrorType is not zero, this parameter is valid. It defines error distribution. For FEC 2/3, random error distribution, one error bit will be inserted in every 15-bit packet. Valid for DM packet types For FEC 1/3 header, random error distribution, one error bit will be inserted in every 3-bit packet.
PAGE 304
CATC BTTRAINER 2.
PAGE 305
CATC BTTRAINER 2.11 CHAPTER User’s Manual Used in Test Cases Test Case Description TP/PHYS/FRE/BV-01 -C 79 channel hopping sequence. Tester transmits POLL packets every master-to-slave slot. Clock is set to include wrap-around TP/PHYS/FRE/BV-03 -C 23 channel hopping sequence. Tester transmits POLL packets every master-to-slave slot. Clock is set to include wrap-around TP/PHYS/TRX/BV-02 -C Slave Tx timing.
PAGE 306
CATC BTTRAINER 2.
PAGE 307
CATC BTTRAINER 2.11 CHAPTER User’s Manual Example B.12BTTracer Commands BTTracerStartRecording BTTracerStartRecording() Parameter Meaning Default Value Comments N/A Return value • • “Success” “Failure” Comments This command is used to start a BTTracer recording. Example BTTracerStartRecording(); BTTracerStopRecording BTTracerStopRecording() Parameter Meaning Default Value Comments N/A Return value • “Success” Comments This command is used to stop a BTTracer recording.
PAGE 308
CATC BTTRAINER 2.
PAGE 309
CATC BTTRAINER 2.11 CHAPTER User’s Manual Appendix C: 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 BTTrainer 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.
PAGE 310
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 311
CATC BTTRAINER 2.11 CHAPTER User’s Manual Lists 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.
PAGE 312
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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.
PAGE 313
CATC BTTRAINER 2.11 CHAPTER User’s Manual This function will create a local variable Parameter and a local variable Local, which has an assigned value of 20. C.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.
PAGE 314
CATC BTTRAINER 2.11 CHAPTER User’s Manual x > 2 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).
PAGE 315
CATC BTTRAINER 2.11 CHAPTER User’s Manual }; If none of the first four expressions evaluates to true, then default will be evaluated, returning a value of null for the entire expression.
PAGE 316
CATC BTTRAINER 2.11 CHAPTER User’s Manual !1 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.
PAGE 317
CATC BTTRAINER 2.
PAGE 318
CATC BTTRAINER 2.11 CHAPTER User’s Manual Operator Operand Symbol Description 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.
PAGE 319
CATC BTTRAINER 2.11 CHAPTER User’s Manual Operator Operand Symbol Description Types Result Types Examples Equality Operators == != Equal Not equal Integer-integer Integer 2 == 2 String-string Integer "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.
PAGE 320
CATC BTTRAINER 2.
PAGE 321
CATC BTTRAINER 2.
PAGE 322
CATC BTTRAINER 2.11 CHAPTER User’s Manual C.7 Comments 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.
PAGE 323
CATC BTTRAINER 2.11 CHAPTER User’s Manual In addition to the operators, the following are keywords in CSL: Keyword Usage select select expression set define a global variable const define a constant return return statement while while statement for for statement if if statement else if-else statement default select expression null null value in input context out output context C.9 Statements Statements are the building blocks of a program.
PAGE 324
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 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.
PAGE 325
CATC BTTRAINER 2.11 CHAPTER User’s Manual 2, 3, 4, for Statements A for statement takes the form for (; ; ) 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.
PAGE 326
CATC BTTRAINER 2.11 CHAPTER User’s Manual return Statements 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 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.
PAGE 327
CATC BTTRAINER 2.11 CHAPTER User’s Manual ... 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.
PAGE 328
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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. C.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.
PAGE 329
CATC BTTRAINER 2.11 CHAPTER User’s Manual C.11 Functions 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.
PAGE 330
CATC BTTRAINER 2.11 CHAPTER User’s Manual add(1); 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.
PAGE 331
CATC BTTRAINER 2.11 CHAPTER User’s Manual Call() Call( , ) Parameter Meaning Default Value Comments function_name string arg_list list Used as the list of parameters in the function call. Return value 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.
PAGE 332
CATC BTTRAINER 2.11 CHAPTER User’s Manual 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 Integer Character d Integer Signed decimal integer.
PAGE 333
CATC BTTRAINER 2.11 CHAPTER User’s Manual • 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.
PAGE 334
CATC BTTRAINER 2.11 CHAPTER User’s Manual NextNBits() NextNBits () 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.
PAGE 335
CATC BTTRAINER 2.11 CHAPTER User’s Manual Comments 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( , , ... ) Parameter Meaning Default Value arg any Comments The number of arguments is variable. Return value None.
PAGE 336
CATC BTTRAINER 2.