CATC MERLIN’S WAND 1.22 APPENDIX A User’s Manual Command Generator Command Descriptions ClientPut This command will initiate an OBEX Put operation in the remote device for the object defined in the FileName parameter. Command Parameters Examples Filename “C:\VCard.vcf” Comments Return Events ClientPut_Complete ClientPut_Error ClientSetPath This command will initiate an OBEX SetPath operation in the remote device. Flags indicate SetPath option such as Backup.
CATC MERLIN’S WAND 1.22 User’s Manual APPENDIX A Command Generator Command Descriptions ServerInit This command will initialize the OBEX server. Command Parameters Examples Comments N/A Return Events ServerInit_Complete ServerInit_Error ServerSetPath Sets the path where received OBEX files are stored. Command Parameters Examples Comments Path “C:\OBEX” Use the “...” button to select a path, or type one in.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples Appendix B: Command Generator Examples This chapter provides fourteen Command Generator examples. These examples consist of command sequences that are presented in order to illustrate useful scenarios. Please note that these examples do not cover all possible alternatives.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.1 Device Discovery and Remote Name Request Procedure In this scenario, Merlin’s Wand performs a General Inquiry and a Remote Name Request. Step 1 Select HCI tab. Step 2 Select Inquiry from the menu. You can use the default settings for the Inquiry_Length (8 seconds) and Num_Responses (10). Step 3 Click Execute. The Event Log should display an Inquiry_Result for each found device followed by an Inquiry_Complete event.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.2 Establish Baseband Connection Procedure In this scenario, Merlin’s Wand creates a Baseband (ACL) Connection. This procedure assumes that Device Discovery has already been performed. See “Device Discovery and Remote Name Request” on page 138. Step 1 From the HCI menu select Create_Connection. Step 2 Select the target device from the BD_ADDR drop-down menu or enter a new BD_ADDR. Step 3 Click Execute.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.3 Baseband Disconnection Procedure In this scenario, Merlin’s Wand terminates a Baseband connection. These steps continue the connection you established in the preceding scenario. This procedure assumes that an ACL connection exists. See “Establish Baseband Connection” on page 139. Step 1 From the HCI menu, select Disconnect. Step 2 From the HCI_Handle drop-down menu, select a handle. Step 3 Click Execute.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.4 Create Audio Connection Procedure In this scenario, Merlin’s Wand creates an SCO connection. This procedure assumes that you have established an ACL connection between Merlin’s Wand and the target device. See “Establish Baseband Connection” on page 139. Step 1 From the HCI menu, select Add_SCO_Connection from the menu.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.5 L2CAP Connection Procedure In this scenario, Merlin’s Wand establishes an L2CAP connection. This procedure assumes that an ACL connection has been established. See “Establish Baseband Connection” on page 139. Step 1 Click the L2CAP tab to display the L2CAP drop-down menu. Step 2 Select Register_PSM from the menu. Merlin’s Wand must register its PSM channel before it can form an L2CAP connection.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples Step 7 Select ConnectRequest from the L2CAP menu. Step 8 Select an HCI Handle from the HCI_Handle drop-down menu. To determine which HCI_Handle value is correct, open the Piconet window on the far left side of the Merlin’s Wand application. Step 9 Select or type a PSM from the PSM menu. Step 10 Select or type the Receive MTU from the Receive MTU menu (default value can be used). Step 11 Click Execute.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.6 L2CAP Channel Disconnect Procedure In this scenario, Merlin’s Wand terminates an L2CAP connection. This procedure assumes that an L2CAP connection has been established. See “L2CAP Connection” on page 142. Step 1 From the L2CAP menu, select DisconnectRequest. Step 2 Select the appropriate CID from the CID menu. Step 3 Click Execute.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.7 SDP Profile Service Search Procedure In this scenario, Merlin’s Wand conducts a Profile Service Search. This procedure assumes that an ACL connection has been established. “Establish Baseband Connection” on page 139. Step 1 Click the SDP tab to display the SDP menu. Step 2 Select ProfileServiceSearch from the menu. Step 3 Select an HCI Handle from the HCI_Handle drop-down list.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.8 SDP Reset Database and Add Profile Service Record Procedure In this scenario, Merlin’s Wand resets the SDP database and then adds an SDP Profile Service Record. This procedure assumes that an ACL connection has been established between Merlin’s Wand and the target device. “Establish Baseband Connection” on page 139. Note A connection is not necessary to perform a Reset_Database or AddProfileServiceRecord.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.9 RFCOMM Client Channel Establishment Procedure In this scenario, Merlin’s Wand opens an RFCOMM client channel. This procedure assumes that an ACL connection has been established and that the target device has assumed the role of an RFCOMM server. See “Establish Baseband Connection” on page 139. Step 1 Click the RFCOMM tab to open the RFCOMM drop-down menu. Step 2 Select OpenClientChannel from the menu.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.10 RFCOMM Client Channel Disconnection Procedure In this scenario, Merlin’s Wand closes an RFCOMM client channel. This procedure assumes that an RFCOMM channel has been established. See “RFCOMM Client Channel Establishment” on page 147. Step 1 From the RFCOMM menu select CloseClientChannel. Step 2 Select the HCI/DLCI combination from the (HCI/DLCI) menu. Step 3 Click Execute.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.11 RFCOMM Register Server Channel Procedure In this scenario, Merlin’s Wand registers a Server Channel. This procedure assumes that an ACL connection has been established. See “Establish Baseband Connection” on page 139. Note A connection is not necessary to call a RegisterServerChannel command. Step 1 From the RFCOMM menu select RegisterServerChannel. Step 2 Click Execute.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.12 Establish TCS Connection Procedure In this scenario, Merlin's Wand establishes a TCS connection. This procedure assumes that an ACL connection has been established. See “Establish Baseband Connection” on page 139. Step 1 Click the TCS tab to display the TCS drop-down menu. Step 2 Select Register_Intercom_Profile from the menu. Merlin 's Wand must register its Intercom profile before it can form a TCS connection.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Step 6 Command Generator Examples Click Execute. Event Log should display “Open_TCS_Channel_Complete.” Step 7 Select Start_TCS_Call from the menu. Step 8 Click Execute. Event Log should display “Start_TCS_Call_Complete.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.13 OBEX Server Init Procedure In this scenario, Merlin’s Wand initializes itself as an OBEX server. This scenario assumes that an ACL connection exists. See “Establish Baseband Connection” on page 139. Note A connection is not necessary to call an OBEX ServerInit function. Step 1 Click the OBEX tab to display the OBEX menu. Step 2 Select ServerInit from the menu. Step 3 Click Execute.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Command Generator Examples B.14 OBEX Client Connection and Client Get & Put Procedure In this scenario, Merlin’s Wand forms a client connection with the target device and then retrieves a text file from the target and sends one to it. This procedure assumes that an ACL connection has been established (see “Establish Baseband Connection” on page 139). It also assumes that the target device has been configured as an OBEX server.
CATC MERLIN’S WAND 1.22 APPENDIX B User’s Manual Step 4 Command Generator Examples Click Execute. The Event Log should indicate that a connection was established. Step 5 Select ClientGet from the command menu. Step 6 Type in the name of a file that is to be transferred from the Server into the Object parameter box. Step 7 Click Execute. The Event Log should indicate that the file was transferred. A Save As dialog box should open. Step 8 Enter a name for the file you are retrieving.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Appendix C: Merlin’s Wand Scripting Commands Merlin’s Wand 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. C.1 Bluetooth Addresses Bluetooth addresses are represented in scripts as binary strings in big-endian byte order.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands #include body of script here } Clock() Clock() Parameter Meaning Default Value Comments N/A Return value The number of milliseconds that have elapsed since the system was started. Comments This function returns the amount of time that the system has been running. It can be used to find out how long it takes to run a script or a series of commands within a script.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • • • Device name “Not connected” “Failure” Comments Queries the specified device for its name. An ACL connection must be established before calling GetRemoteDeviceName().
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • • “Success” “Failure” Comments Sets the device class of Merlin’s Wand 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 C.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • Merlin’s Wand Scripting Commands “Failure” “Pipe Not Found” “Invalid parameter” Comments Closes the specified data pipe.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Data (element 2) is the raw data received in the transaction. Valid only if result is “Success”. Comments Reads the specified amount of data from an open pipe. Example result = ReadPipe("Data1", "Receive", 1024); if(result[0] == "Success") { Trace("Read ", result[1], "bytes:\n"); Trace(result[2]); } WritePipe() WritePipe(PipeName, Data) Parameter Meaning PipeName Name of the data pipe to open Data Data to write to t
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands C.4 HCI Commands HCIAcceptConnectionRequest() HCIAcceptConnectionRequest() Parameter Meaning Default Value Comments N/A Return value • “Success” Comments Sets the accept connection request variable to True.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Parameter Meaning Gain New gain of the device Default Value Comments Values: 0 – 0xF Return value • • • • “Success” “Failure” “Not connected” “No SCO connection” Comments This command is used to change gain of connected speaker or microphone. In order to use this command, an SCO connection must exist. Example Main() { result = Connect('00803713BDF0'); Trace("Connection result : ", result, "\n"); if( result == "Su
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Sleep(2000); } status = HCIRemoveSCOConnection('00803713BDF0'); Trace("SCO disconnect result: ", status, "\n"); } status = Disconnect('00803713BDF0'); Trace("Disconnect result: ", status, "\n"); } } HCICatcEnterTestMode() HCICatcEnterTestMode(Address) Parameter Meaning Address Bluetooth address of remote device Default Value Comments Return value • • • • “Success” “Failure” “Not found” “Not connected” Comments T
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • • Merlin’s Wand Scripting Commands “Success” “Failure” “Not found” “No SCO connection” Gain (element 1) is the one-byte value of the headset gain. Range is 0 to 15. Comments This command is used to read current gain of connected speaker or microphone. In order to use this command, an SCO connection must exist. Example See the example for the HCICatcChangeHeadsetGain command.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCICatcSelfTest() HCICatcReadRevisionInformation() Parameter Meaning Default Value Comments N/A Return value • • “Success” “Failure” Comments This command is used to perform a self test on a local device. Example Trace("Merlin's Wand Self Test : ", HCICatcSelfTest(), "\n"); HCICatcTestControl() HCICatcTestControl(Address, TestScenario, HoppingMode, TxFrequency, RxFrequency, TestPacketType) Parameter Meaning Add
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • Merlin’s Wand Scripting Commands “Not connected” Comments This command is used to start a specific test for the slave device identified by Bluetooth address. See Bluetooth LMP specification, page 246 for description of the parameters. Example See the example for HCICatcBerTest command.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • Merlin’s Wand Scripting Commands “Failure” “Not found” “Not connected” Comments This command is used to force both devices associated with a connection to generate a new link key. Example result = HCIChangeConnectionLinkKey('00803713BDF0'); Trace("Change Connection Link Key: ", result, "\n"); HCIChangeConnectionPacketType() HCIChangeConnectionPacketType(Address, PacketType) Parameter Meaning Address Bluetooth address of device to connect with
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Parameter Meaning Default Value DeleteAll Boolean value that indicates whether to delete only the specified address's link key, or all link keys 0 Comments 0 or 1 Return value • • “Success” “Failure” Comments Attempts to delete the stored link key for the specified address or for all addresses, depending on the value of DeleteAll.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIExitParkMode() HCIExitParkMode(Address) Parameter Meaning Address Bluetooth address of device in question Default Value Comments Return value • • • • “Success” “Failure” “Failed: Device not found” “Not connected” Comments Switches the current role of the device in the piconet. Example Device = '010203040506'; result = HCIExitParkMode(Device); Trace("HCIExitParkMode result is: ", result, "\n"); HCIExitSniffMod
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands result = HCIExitSniffMode(Device); Trace("HCIExitSniffMode result is: ", result, "\n"); HCIHoldMode() HCIHoldMode(Address, MaxInterval, MinInterval) Parameter Meaning Default Value Comments Address Bluetooth address of device in question MaxInterval Maximum number of 0.625-msec intervals to wait in Hold mode. Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec). MinInterval Minimum number of 0.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIMasterLinkKey() HCIMasterLinkKey(KeyFlag) Parameter Meaning Default Value KeyFlag Comments 0x0 use semi-permanent link keys 0x1 use temporary link keys Return values Returns a list with three values: status, HCI handle, and key flag. Status (element 0) is one of the following: • • “Success” “Failure” HCI handle (element 1) is the handle for the ACL connection.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Parameter Meaning Default Value Comments 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.9 sec).
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Comments Specifies a device for which no PIN code will be supplied, thus causing a pair request to fail. Example result = HCIPINCodeRequestNegativeReply('6C421742129F9'); Trace("HCIPINCodeRequestNegativeReply returned: ", result, "\n"); HCIPINCodeRequestReply() HCIPINCodeRequestReply(Address, PINCode) Parameter Meaning Address Bluetooth address of device for which PIN code will be used.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Token rate (element 4) is the four-byte token rate value in bytes per second. Peak bandwidth (element 5) is the four-byte peak bandwidth value in bytes per second. Latency (element 6) is the four-byte latency value in microseconds. Delay variation (element 7) is the four-byte delay variation value in microseconds. Comments This command is used to specify Quality of Service parameters for the connection.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Comments This command will read the value for AuthenticationEnable parameter. Example result = HCIReadAuthenticationEnable(); if(result[0] == "Success") Trace("Merlin's Wand Authentication Enabled : ", result[1], "\n"); HCIReadBDADDR() HCIReadBDADDR() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and address.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Status (element 0) is one of the following: • • “Success” “Failure” ACL packet length (element 1) is the two-byte value of the maximum length (in bytes) of the data portion of each HCI ACL data packet that the Host Controller is able to accept. SCO packet length (element 2) is the one-byte value of the maximum length (in bytes) of the data portion of each HCI SCO data packet that the Host Controller is able to accept.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIReadClockOffset() HCIReadClockOffset(Address) Parameter Meaning Address Bluetooth address of device to connect with. Default Value Comments Return values Returns a list with two values: status and offset. Status (element 0) is one of the following: • • • • “Success” “Failure” “Failed: Device not found” “Not connected” Offset (element 1) is the two-byte value of the clock offset.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Timeout (element 1) is the two-byte value of the timeout, interpreted as multiples of 0.625-msec intervals. Comments Reads the current timeout interval for connection. The timeout value defines the time duration from when the Host Controller sends a Connection Request event until the Host Controller automatically rejects an incoming connection.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Trace("Country code is: 0x", result[1], "\n"); } HCIReadCurrentIACLAP() HCIReadCurrentIACLAP() Parameter Meaning Default Value Comments N/A Return value Returns a list with two values: status and Current IAC LAP. Status (element 0) is one of the following: • • “Success” “Failure” Current IAC LAP (element 1) is the 3-byte value of the LAPs (Lower Address Part) that make up the current IAC (Inquiry Access Code).
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIReadEncryptionMode() HCIReadEncryptionMode() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and encryption mode. Status (element 0) is one of the following: • • “Success” “Failure” Encryption mode (element 1) is the one-byte encryption mode value.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • Merlin’s Wand Scripting Commands “Failure” “Failed: Device not found” “Not connected” Link policy settings (element 1) is the two-byte value of the link policy settings. Comments Reads the value of the Link_Policy_Settings parameter for the device. Example Device = '010203040506'; result = HCIReadLinkPolicySettings(Device); Trace("HCIReadLinkPolicySettings returned: ", result[0], "\n"); if (result[0] == "Success") { Trace("Link Policy Settings :
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Example Device = '010203040506'; result = HCIReadLinkSupervisionTimeout(Device); Trace("HCIReadLinkSupervisionTimeout returned: ", result[0], "\n"); if (result[0] == "Success") { Trace("Link Supervision Timeout is: ", result[1] ,"\n"); } HCIReadLocalName() HCIReadLocalName() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and name.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return values Returns a list with two values: status and features. Status (element 0) is one of the following: • • “Success” “Failure” Features (element 1) is the eight-byte bit mask list of Link Manager Protocol features. Comments Reads the LMP supported features for the local device. Example result = HCIReadLocalSupportedFeatures(); Trace("HCIReadLocalSupportedFeatures returned: ", result[0], "\n"); if (result[0] ==
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Manufacturer name (element 4) is the two-byte manufacturer name of the Bluetooth hardware. LMP subversion (element 5) is the two-byte Link Manager Protocol subversion value. Comments Reads the version information for the local device. Example result = HCIReadLocalVersionInformation(); Trace("HCIReadLocalVersionInformation returned: result[0], "\n"); if (result[0] == "Success") { Trace("HCI version is: 0x", result[1], Trac
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands if (result[0] == "Success") { Trace("Loopback mode is: 0x", result[1], "\n"); } HCIReadNumberOfSupportedIAC() HCIReadNumberOfSupportedIAC() Parameter Meaning Default Value Comments N/A Return value Returns a list with two values: status and number of supported IAC.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIReadPINType() HCIReadPINType() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and PIN type. Status (element 0) is one of the following: • • “Success” “Failure” PIN type (element 1) is the one-byte PIN type. (0=Variable PIN; 1=Fixed PIN.) Comments Reads the PIN type, which determines whether the Host supports variable PIN codes or only a fixed PIN code.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • Merlin’s Wand Scripting Commands “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. Example Device = '010203040506'; result = HCIReadRemoteSupportedFeatures(Device); Trace("HCIReadRemoteSupportedFeatures returned: ", result[0], "\n"); if (result[0] == "Succ
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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. Example Address = '010203040506'; result = HCIReadRemoteVersionInformation(Address); Trace("HCIReadRemoteVersionInformation returned: ", result[0], "\n"); if (result[0] == "Success") { Trace("LMP version is: 0x", result[1], "\n");
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIReadSCOFlowControlEnable() HCIReadSCOFlowControlEnable() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and SCO flow control enable. Status (element 0) is one of the following: • • “Success” “Failure” SCO flow control enable (element 1) is the one-byte SCO flow control value. (0=SCO flow control disabled; 1=SCO flow control enabled.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIReadVoiceSetting() HCIReadVoiceSetting() Parameter Meaning Default Value Comments N/A Return values Returns a list with two values: status and voice setting. Status (element 0) is one of the following: • • “Success” “Failure” Voice setting (element 1) is the 10-bit voice setting value. Comments Reads the voice setting value. This value controls all settings for voice connections.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIRoleDiscovery() HCIRoleDiscovery(Address) Parameter Meaning Address Bluetooth address of device relative to which we want to know our role Default Value Comments A connection must exist with this address for Role Discovery to work. Return value • • • • • “Master” “Slave” “Failure” “Failed: Device not found” “Not connected” Comments Attempts to discover the role of our device relative to the specified device.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Parameter Meaning Condition Details of the filter to be set. Default Value Comments Must be entered as a series of bytes within brackets, e.g., [0x1, 0x12, 0x0F]. Byte values must be entered in hex notation separated by commas. Return value • • • “Success” “Failure” “Invalid parameter” Comments Instructs the Host Controller to send only certain types of events to the Host.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Parameter Meaning Default Value Comments MinInterval Minimum number of 0.625-msec intervals between sniff periods. Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec). Attempt Number of receive slots for sniff attempt. Range is 0x0001 to 0x7FFF (0.625 msec to 20.5 sec). Timeout Number of receive slots for sniff timeout. Range is 0x0001 to 0x7FFF (0.625 msec to 20.5 sec).
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • Merlin’s Wand Scripting Commands “Failed: Device not found” “Not connected” “Invalid parameter” Comments Switches the current role of the device in the piconet. Example Device = '010203040506'; result = HCISwitchRole(Device, "Slave"); Trace("HCISwitchRole result is: ", result, "\n\n"); HCIWriteAuthenticationEnable() HCIWriteAuthenticationEnable(AuthenticationEnable) Parameter Meaning Default Value AuthenticationEnable Authentication value: 0
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIWriteConnectionAcceptTimeout() HCIWriteConnectionAcceptTimeout(Interval) Parameter Meaning Interval Number of 0.625-msec intervals before the connection request times out. Default Value Comments 0x1FA0 (= 5 Range is 0x0001 to 0xB540 (0.625 msec to 29 sec) sec). Return value • • • “Success” “Failure” “Invalid parameter” Comments Sets a timeout interval for connection.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Comments Writes the number and values of the IAC LAPs to be used. One of the values has to be the General Inquiry Access Code, 0x9E8B33. Example result = HCIWriteCurrentIACLAP(2, 0x9E8B33, 0x9E8B34); Trace("Result of HCIWriteCurrentIACLAP: ", result, "\n\n"); HCIWriteEncryptionMode() HCIWriteEncryptionMode(EncryptionMode) Parameter Meaning Default Value Encryption Mode Encryption mode: 0 = Encryption disabled; 1 = En
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIWriteLinkPolicySettings() HCIWriteLinkPolicySettings(Address, LinkPolicySettings) Parameter Meaning Address Bluetooth address of device in question Default Value LinkPolicy Settings Comments Range is 0x0000-0x8000. Return value • • • • “Success” “Failure” “Failed: Device not found” “Not connected” Comments Writes the value for the Link_Policy_Settings parameter for the device.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • • • • “Success” “Failure” “Failed: Device not found” “Not connected” Comments Writes the value for the Link_Supervision_Timeout parameter for the device. Example Device = '010203040506'; result = HCIWriteLinkSupervisionTimeout(Device, 0x7D00); Trace("HCIWriteLinkSupervisionTimeout result is: ", result[0], "\n\n"); HCIWriteLoopbackMode() HCIWriteLoopbackMode(LoopbackMode) Parameter Meaning Default Valu
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands HCIWritePageTimeout() HCIWritePageTimeout(Interval) Parameter Meaning Default Value Comments Interval Number of 0.625-msec intervals before the connection attempt times out. 0x2000 (= 5.12 sec) Range is 0x0001 to 0xFFFF (0.625 msec to 40.9 sec).
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Example result = HCIWritePINType(0); HCIWriteScanEnable() HCIWriteScanEnable(AccessibleMode) Parameter Meaning Accessible Mode Default Value Comments Access mode “GENERAL_ Mode can be one of: to set Merlin's ACCESSI- “GENERAL_ACCESSIBLE”, Wand BLE” “NOT_ACCESSIBLE”, “CONNECTABLE_ONLY” Return value • • • “Success” “Timed out” “Failure” Comments Sets the accessible mode of Merlin’s Wand.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Comments Attempts to store the link key for the specified address. If a link key already exists for the specified address, it will be overwritten. Example result = HCIWriteStoredLinkKey('6E8110AC0108', "ABC123"); Trace("HCIWriteStoredLinkKey() returned: ", result, "\n\n"); HCIWriteVoiceSettings() HCIWriteVoiceSettings(Address, VoiceSetting) Parameter Meaning Address Bluetooth address of device whose voice settings to
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands C.5 OBEX Commands OBEXClientConnect() OBEXClientConnect(Address) Parameter Meaning Address Bluetooth address of device to connect with Default Value Comments Return value • • • • • “Success” “Failure” “Failed: Busy” “Failed: Not connected” “Failed: Packet too small” Comments Establishes an OBEX client connection with the specified device.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Example result = OBEXClientDeinit(); OBEXClientDisconnect() OBEXClientDisconnect() Parameter Meaning Default Value Comments N/A Return value • • • • • “Success” “Failure” “Failed: Busy” “Failed: Not connected” “Failed: Packet too small” Comments Breaks the current OBEX client connection.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • • • Merlin’s Wand Scripting Commands “Failure” “Failed: Busy” “Failed: Not connected” “Failed: Packet too small” “Failed: Invalid handle” Comments Retrieves object from a server and saves it to the client. If directory names are included in either path argument, be sure to use double-slashes to separate components (e.g., “temp1\\temp2\\filename.txt”). Using single slashes will cause errors.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.) Example result = OBEXClientInit(); OBEXClientPut() OBEXClientPut(LocalPath, RemotePath) Parameter Meaning LocalPath Full (not relative) path and name of file to be sent from client. RemotePath Path and name of object to be stored on server.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Examples In these examples, the server’s OBEX directory is assumed to be c:\obexdir. #store file to "file.txt" in server’s OBEX directory # (i.e., c:\obexdir\file.txt) OBEXClientPut("c:\\temp\\file.txt"); #store file to "newfile.txt" in server’s OBEX dir # (i.e., c:\obexdir\newfile.txt) OBEXClientPut("c:\\temp\\file.txt", "newfile.txt"); #store file to "newfile.txt" in temp dir under OBEX dir # (i.e., c:\obexdir\temp\newf
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Comments Temporarily changes a server's current working directory, accessed by clients during ClientGet and ClientPut operations. The device must be connected to an OBEX server before the command can be successfully executed. The change is lost when the connection is broken. Note that the server’s OBEX root directory cannot be changed with this command.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • Merlin’s Wand Scripting Commands “Failed: Busy” Comments Deinitializes an OBEX server. Example result = OBEXServerDeinit(); 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
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands C.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • • • Merlin’s Wand Scripting Commands “Success” “Failure” “Timed out” “Not connected” “Restricted” If the return value is “Success”, the second element in the list is the DLCI of the established connection. Comments An ACL connection must already be established with the device. Example result = RFOpenClientChannel(Devices[0], 1); if(result[0] == "Success") { Trace("Successfully connected with DLCI ", result[1], "\n"); # Send some data over RFCOMM
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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. Example #Get the data; stop when no data is received for 5 secs result = RFReceiveData(Device, DLCI, 5000); while(result[0] == "Success") { Trace("Number of data bytes received: ", result[1], "\n"); result = RFReceiveData(Device, DLCI, 5000); } RFWa
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands RFCOMM connection is already present when this function is called, it will immediately return “Success”. Example # Wait 3 seconds for RFCOMM connection Trace("RFWaitForConnection\n"); result = RFWaitForConnection(1, 3000); if( result[0] == "Success" ) { Trace("Incoming RFCOMM connection DLCI: ", result[1], "\n"); Trace("Connecting device address: ", result[2], "\n"); } RFAcceptChannel() RFAcceptChannel(bAccept) Parameter
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • “Success” Comments Example status = RFAcceptPortSettings(0); Trace("RFAcceptPortSettings returned: ", status, "\n\n"); RFCreditFlowEnabled() RFCreditFlowEnabled(Address, DLCI) Parameter Meaning Address Bluetooth address of device DLCI Data link connection identifier Default Value Comments Can use “CONNECTED_DEVICE” to check if credit flow is enabled on a master RFCOMM connection.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • • • • “Success” “Failure” “Not connected” “Timed Out” Comments Submits a request to change the port settings on a particular RFCOMM connection.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands • BaudRate (element 0) is a string containing the baud rate • DataFormat (element 1) is a string containing data bits, stop bits, and parity settings • FlowControl (element 2) is a string indicating port flow control options • Xon (element 3) is a string containing the XON character • Xoff (element 4) is a string containing the XOFF character Comments Requests the port settings on a particular RFCOMM connection.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual • • • Merlin’s Wand Scripting Commands “Failure” “Not Connected” “Timed Out” Comments Sets the line status on a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1); DLCI = result[1]; if(result[0] == "Success") { status = RFSetLineStatus("CONNECTED_DEVICE", DLCI, ["RF_LINE_ERROR", "RF_FRAMING"]); Trace("RFSetLineStatus returned: ", status, "\n\n"); } RFSetModemStatus() RFSetModemStatus(Address, DLCI, ModemSignals, BreakLength)
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Comments Sets the modem status on a particular RFCOMM connection. Example result = RFOpenClientChannel(Device, 1); DLCI = result[1]; if(result[0] == "Success") { status = RFSetModemStatus("CONNECTED_DEVICE", DLCI, ["RF_FLOW"], 3); Trace("RFSetModemStatus returned: ", status, "\n\n"); } RFSendTest() RFSendTest(Address, DLCI) Parameter Meaning Default Value Comments Address Bluetooth address of device Can use “CONNEC
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands RFAdvanceCredit() RFAdvanceCredit(Address, DLCI, credit) Parameter Meaning Address Bluetooth address of device DLCI Data link connection identifier credit Number of credits to advance Default Value Comments Can use “CONNECTED_DEVICE” to advance a credit to a master RFCOMM connection. Note that this will work only if exactly one device is connected via RFCOMM.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • • “Success” “Failure” Comments Register Intercom profile with the application. Example result = TCSRegisterProfile(); Trace("TCSRegisterProfile returned: ", result, "\n"); TCSOpenChannel() TCSOpenChannel(Address) Parameter Meaning Address Bluetooth address of device to connect with Default Value Comments Return value • • • • “Success” “Failure” “Not Found” “Timed Out” Comments This command ope
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • • “Success” “Failure” Comments 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. Example result = TCSStartCall(); Trace("TCSStartCall result : ", result, "\n"); if( r
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands TCSSendInfoMessage() TCSSendInfoMessage(Phone_Number) Parameter Meaning Phone_Number Up to 10-digit Phone Number Default Value Comments Return value • • • “Success” “Failure” “Invalid Parameter” Comments This command can be called after a TCS channel is opened. It sends an INFORMATION TCS message with a called party number.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Sleep(1000); result = TCSOpenChannel(Device[0]); Trace("TCSOpenChannel result : ", result, "\n"); if( result != "Success") return result; Sleep(1000); result = TCSStartCall(); Trace("TCSStartCall result : ", result, "\n"); if( result != "Success") return result; Sleep(1000); result = TCSSendInfoMessage("4088447081"); Trace("TCSSendInfoMessage result : ", result, "\n"); if( result != "Success") return result; Sleep(1000); r
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands C.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Parameter DelayVariation Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands 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.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Example result = L2CAPEchoRequest('838010AC0008', "Test"); Trace("L2CAPEchoRequest result : ", result[0], "\n"); if(result[0] == "Success") { Trace("Data : ", result[1], "\n"); } 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands L2CAPRegisterPsm() L2CAPRegisterPsm(PSM, ReceiveMTU) Parameter Meaning Default Value Comments 0x1C2 Incoming MTU size for L2CAP connection with that PSM PSM ReceiveMTU Return value • • • “Success” “Failure” “In use” Comments This command is used to register a PSM identifier with L2CAP. Example Trace("Register PSM\n"); result = L2CAPRegisterPsm(0x1001, 0x1C2); Trace(" Result : ", result, "\n"); L2CAPSendData() L
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Example result = L2CAPSendData(0x40, "test data"); Trace("Result : ", result, "\n"); 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.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Return value • • “Success” “Timed out” Comments Waits Timeout milliseconds for a device to establish an L2CAP connection with Merlin's Wand. This function will block the specified amount of time (or infinitely if 0 is specified) unless a connection is established. Example Trace("L2CAPWaitForConnection\n"); result = L2CAPWaitForConnection(); if( result == "Success") { #Do something else } C.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Comments Clears all records out of the Merlin’s Wand SDP profile database.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands C.10 Merlin Commands MerlinResetAllEncryptionOptions() MerlinResetAllEncryptionOptions() Parameter Meaning Default Value Comments N/A Return value • • “Success” “Failure” Comments This command is used to remove all previously associated link keys and PIN numbers.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Example MerlinSetEncryptionPIN('008037BB2100', "1234"); MerlinSetRecordingOptions() MerlinSetRecordingOptions(RecOptionsFile) Parameter Meaning RecOptionsFile Name and full path to the recording options file Default Value Comments Return value • “Success” Comments This command is used to set the recording options file to be used for the next recording. Example MerlinSetRecordingOptions("C:\\CATC\\Merlin \\defaul
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands Example result = MerlinStart("192.168.2.1"); Trace("Result : ", result, "\n"); MerlinStartRecording() MerlinStartRecording() Parameter Meaning Default Value Comments N/A Return value • • “Success” “Failure” Comments This command is used to start a Merlin recording.
CATC MERLIN’S WAND 1.22 APPENDIX C User’s Manual Merlin’s Wand Scripting Commands MerlinStopRecording() MerlinStopRecording() Parameter Meaning Default Value N/A Return value • “Success” Comments This command is used to stop a Merlin recording.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language Appendix D: CATC Scripting Language CATC Scripting Language (CSL) was developed to allow users to automate test processes and provide textual output to suit specific needs. CSL is used in Merlin’s Wand to write traffic-generating scripts, making it possible to automate some Bluetooth command sequences. Scripts are written, saved, and run using the Script Manager utility. Scripts’ output can be viewed in the Script Log.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language Hexadecimal numbers must be preceded by 0x: 0x2A, 0x54, 0xFFFFFF01 Octal numbers must begin with 0: 0775, 017, 0400 Decimal numbers are written as usual: 24, 1256, 2 Binary numbers are denoted with 0b: 0b01101100, 0b01, 0b100000 Strings String literals are used to represent text. A string consists of zero or more characters and can include numbers, letters, spaces, and punctuation.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language A variable is created when it is assigned a value. Variables can be of any value type, and can change type with re-assignment. Values are assigned using the assignment operator ( = ). The name of the variable goes on the left side of the operator, and the value goes on the right: x = [ 1, 2, 3 ] New_value = x name2 = "Smith" If a variable is referenced before it is assigned a value, it evaluates to null.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language This function will create a local variable Parameter and a local variable Local, which has an assigned value of 20. D.4 Constants A constant is similar to a variable, except that its value cannot be changed. Like variables, constant names must contain only alphanumeric characters and the underscore ( _ ) character, and they cannot begin with a number.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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).
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language }; If none of the first four expressions evaluates to true, then default will be evaluated, returning a value of null for the entire expression.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language !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.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language D.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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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 D.9 Statements Statements are the building blocks of a program.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language The variable expression statement is also called an assignment statement, because it assigns a value to a variable. if Statements An if statement follows the form if 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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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() ); ...
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language ... HiThere() { a = "Hi there"; b = "Goodbye"; if ( 3 != 3 ) return a; else return b; } will output Goodbye because the if statement evaluates to false. This causes the first return statement to be skipped. The function continues executing with the else statement, thereby returning the value of b to be used as an argument to Trace.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language y = 3; } x + 3; } Compound statements can be used anywhere that any other kind of statement can be used. if (3 && 3) { result = "True!"; Trace(result); } Compound statements are required for function declarations and are commonly used in if, if-else, while, and for statements. D.10 Preprocessing The preprocessing command %include can be used to insert the contents of a file into a script.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language D.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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language Format can only handle one value at a time, so Format("%d %d", 20, 30); would not work properly. Furthermore, types that do not match what is specified in the format string will yield unpredictable results. Format Conversion Characters These are the format conversion characters used in CSL: Code Type Output c Integer Character d Integer Signed decimal integer.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual • CATC Scripting Language Field width specification is a positive integer that defines the field width, in spaces, of the converted argument. If the number of characters in the argument is smaller than the field width, then the field is padded with spaces. If the argument has more characters than the field width has spaces, then the field will expand to accommodate the argument.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.22 APPENDIX D User’s Manual CATC Scripting Language 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.
CATC MERLIN’S WAND 1.
