Silicon Labs iWRAP5 User Manual

iWRAP5

USER GUIDE

Tuesday, 21 April 2015
Version 1.29

VERSION HISTORY

Version

Comment

1.0

First draft

1.1

SET CONTROL AUTOPAIR and list of changes from iWRAP4 added

1.2

SET BT FILTER added

1.3

SET BT PAGEMODE new parameters added
SET CONTROL ECHO new parameters added
Updated SET to contain information about category specific listings

1.4

SET CONTROL MSC new parameters added
BLINK command added
DELAY command added

1.5

SET BT BDADDR new command added
SET CONTROL CD new parameters added

1.6

NO CARRIER ERROR codes added

1.7

SET BT IDENT modified parameter description

1.8

CONNAUTH event/command parameters modified
SSPAUTH event/command added

1.9

CONNAUTH example added

1.10

Error Codes updated
SET BT IDENT syntax updated

1.11

SET PROFILE HID parameters updated
HID GET command added
HID GET command added
SET BT SCO command added

1.12

SET CONTROL AUDIO new parameters added
HID event added
SET CONTROL VOLSCALE command added

1.13

Added aptX configuration instructions into SET CONTROL CODEC

1.14

Removed SET CONTROL PCM command.

1.15

Updated SET BT SCO packet types

1.16

Update PLAY command example

1.17

LICENSE command added
Migration from iWRAP4 to iWRAP5 added
SET CONTROL PIO command added
BYPASSUART command removed
ECHO command modified

1.18

Added DEFRAG command

1.19

SET BT SCO examples improved

1.20

Known issues list updated

1.21

Updated SET CONTROL CODEC
Updated SET CONTROL GAIN with CVC volume range.

1.22

Updated PIO and SET CONTROL PIO

1.23

Updated description of bit 12 of SET CONTROL CONFIG

1.24

Updated manual to reflect iWRAP5.0.2:
SET BT SNIFF
SET CONTROL AUDIO
SET CONTROL CONFIG

1.25

Fixed SET BT MTU list comment.

1.26

Fixed IDENT event parameter list

1.27

Updated manual to reflect latest iWRAP5.0.2 release

1.28

Updated contact details

1.29

Updated SDP error codes

21.4.2015

TABLE OF CONTENTS

1 Introduction .................................................................................................................. 10

2 Migrating from previous iWRAP versions ................................................................. 12

3 Changes from iWRAP 5.0.1 ......................................................................................... 13

3.1 New features ....................................................................................................................................... 13

3.2 Issues addressed ................................................................................................................................ 13

3.3 Newly discovered known issues ......................................................................................................... 14

4 Getting started ............................................................................................................. 15

4.1 First course to iWRAP ......................................................................................................................... 16

5 iWRAP modes .............................................................................................................. 18

5.1 The escape sequence ......................................................................................................................... 19

5.2 Command mode .................................................................................................................................. 20

5.3 Data mode ........................................................................................................................................... 20

5.4 Multiplexing mode ............................................................................................................................... 21

5.5 HFP and HSP modes .......................................................................................................................... 21

5.6 OBEX mode ........................................................................................................................................ 21

5.7 A2DP mode ......................................................................................................................................... 21

5.8 AVRCP mode ...................................................................................................................................... 21

5.9 PBAP mode ......................................................................................................................................... 21

6 Technical details .......................................................................................................... 22

7 iWRAP command reference ........................................................................................ 24

7.1 Command listings ................................................................................................................................ 25

7.2 List of changes from iWRAP 4 ............................................................................................................ 34

7.3 Typographical conventions ................................................................................................................. 38

7.4 @ ......................................................................................................................................................... 39

7.5 AIO ...................................................................................................................................................... 41

7.6 AT ........................................................................................................................................................ 42

7.7 AUTH ................................................................................................................................................... 43

7.8 AVRCP PDU ....................................................................................................................................... 44

7.9 BATTERY ............................................................................................................................................ 47

7.10 BCSP_ENABLE ............................................................................................................................... 48

7.11 BER ................................................................................................................................................. 49

7.12 BLINK .............................................................................................................................................. 50

7.13 BOOT ............................................................................................................................................... 51

7.14 CALL ................................................................................................................................................ 52

7.15 CLOCK ............................................................................................................................................ 57

7.16 CLOSE ............................................................................................................................................. 58

Silicon Labs

21.4.2015

7.17 CONNAUTH .................................................................................................................................... 59

7.18 CONNECT ....................................................................................................................................... 61

7.19 ECHO .............................................................................................................................................. 63

7.20 DEFRAG .......................................................................................................................................... 64

7.21 DELAY ............................................................................................................................................. 65

7.22 HID GET .......................................................................................................................................... 67

7.23 HID SET ........................................................................................................................................... 68

7.24 INQUIRY .......................................................................................................................................... 69

7.25 IC ..................................................................................................................................................... 72

7.26 IDENT .............................................................................................................................................. 74

7.27 INFO ................................................................................................................................................ 75

7.28 KILL ................................................................................................................................................. 78

7.29 L2CAP ............................................................................................................................................. 79

7.30 LICENSE ......................................................................................................................................... 80

7.31 LIST ................................................................................................................................................. 81

7.32 NAME .............................................................................................................................................. 84

7.33 PAIR ................................................................................................................................................ 86

7.34 PIO ................................................................................................................................................... 91

7.35 PLAY ................................................................................................................................................ 93

7.36 RFCOMM ......................................................................................................................................... 95

7.37 RESET ............................................................................................................................................. 96

7.38 RSSI ................................................................................................................................................ 97

7.39 SCO ENABLE .................................................................................................................................. 98

7.40 SCO OPEN ...................................................................................................................................... 99

7.41 SDP ............................................................................................................................................... 101

7.42 SDP ADD ....................................................................................................................................... 104

7.43 SELECT ......................................................................................................................................... 106

7.44 SET ................................................................................................................................................ 107

7.45 SET BT AUTH ............................................................................................................................... 109

7.46 SET BT BDADDR .......................................................................................................................... 110

7.47 SET BT CLASS ............................................................................................................................. 111

7.48 SET BT FILTER ............................................................................................................................. 112

7.49 SET BT IDENT .............................................................................................................................. 114

7.50 SET BT LAP .................................................................................................................................. 116

7.51 SET BT MTU ................................................................................................................................. 118

7.52 SET BT NAME ............................................................................................................................... 119

7.53 SET BT PAIRCOUNT .................................................................................................................... 120

7.54 SET BT PAGEMODE .................................................................................................................... 121

Silicon Labs

21.4.2015

7.55 SET BT PAIR ................................................................................................................................. 123

7.56 SET BT POWER ........................................................................................................................... 124

7.57 SET BT ROLE ............................................................................................................................... 126

7.58 SET BT SCO ................................................................................................................................. 128

7.59 SET BT SNIFF ............................................................................................................................... 130

7.60 SET BT SSP .................................................................................................................................. 132

7.61 SET CONTROL AUDIO ................................................................................................................. 135

7.62 SET CONTROL AUTOCALL ......................................................................................................... 137

7.63 SET CONTROL AUTOPAIR .......................................................................................................... 140

7.64 SET CONTROL BATTERY ........................................................................................................... 142

7.65 SET CONTROL BAUD .................................................................................................................. 144

7.66 SET CONTROL BIND ................................................................................................................... 146

7.67 SET CONTROL CD ....................................................................................................................... 148

7.68 SET CONTROL CODEC ............................................................................................................... 150

7.69 SET CONTROL CONFIG .............................................................................................................. 152

7.70 SET CONTROL ECHO .................................................................................................................. 157

7.71 SET CONTROL ESCAPE ............................................................................................................. 158

7.72 SET CONTROL GAIN ................................................................................................................... 160

7.73 SET CONTROL INIT ..................................................................................................................... 162

7.74 SET CONTROL MICBIAS ............................................................................................................. 163

7.75 SET CONTROL MUX .................................................................................................................... 165

7.76 SET CONTROL MSC .................................................................................................................... 169

7.77 SET CONTROL PIO ...................................................................................................................... 171

7.78 SET CONTROL PREAMP ............................................................................................................. 172

7.79 SET CONTROL RINGTONE ......................................................................................................... 173

7.80 SET CONTROL READY ................................................................................................................ 174

7.81 SET CONTROL VOLSCALE ......................................................................................................... 175

7.82 SET CONTROL VREGEN ............................................................................................................. 176

7.83 SET {link_id} ACTIVE .................................................................................................................... 178

7.84 SET {link_id} MASTER .................................................................................................................. 179

7.85 SET {link_id} MSC ......................................................................................................................... 180

7.86 SET {link_id} SLAVE ..................................................................................................................... 182

7.87 SET {link_id} SNIFF ....................................................................................................................... 183

7.88 SET {link_id} SUBRATE ................................................................................................................ 185

7.89 SET {link_id} SELECT ................................................................................................................... 186

7.90 SET PROFILE ............................................................................................................................... 187

7.91 SET RESET ................................................................................................................................... 191

7.92 SLEEP ........................................................................................................................................... 192

Silicon Labs

21.4.2015

7.93 SSPAUTH ...................................................................................................................................... 193

7.94 SSP CONFIRM .............................................................................................................................. 194

7.95 SSP PASSKEY .............................................................................................................................. 195

7.96 SSP GETOOB ............................................................................................................................... 196

7.97 SSP SETOOB................................................................................................................................ 197

7.98 TEMP ............................................................................................................................................. 198

7.99 TEST .............................................................................................................................................. 199

7.100 TESTMODE ................................................................................................................................... 203

7.101 TXPOWER ..................................................................................................................................... 204

7.102 PBAP ............................................................................................................................................. 205

7.103 VOLUME ........................................................................................................................................ 211

8 iWRAP Events ............................................................................................................ 212

8.1 AUTH ................................................................................................................................................. 213

8.2 BATTERY .......................................................................................................................................... 214

8.3 CONNECT ......................................................................................................................................... 215

8.4 CONNAUTH ...................................................................................................................................... 216

8.5 CLOCK .............................................................................................................................................. 217

8.6 HID .................................................................................................................................................... 218

8.7 IDENT ................................................................................................................................................ 219

8.8 IDENT ERROR .................................................................................................................................. 220

8.9 INQUIRY_PARTIAL .......................................................................................................................... 221

8.10 NO CARRIER ................................................................................................................................ 222

8.11 NAME ............................................................................................................................................ 223

8.12 NAME ERROR .............................................................................................................................. 224

8.13 OBEX AUTH .................................................................................................................................. 225

8.14 PAIR .............................................................................................................................................. 226

8.15 READY .......................................................................................................................................... 227

8.16 RING .............................................................................................................................................. 228

8.17 SSPAUTH ...................................................................................................................................... 229

8.18 SSP COMPLETE ........................................................................................................................... 230

8.19 SSP CONFIRM .............................................................................................................................. 231

8.20 SSP PASSKEY .............................................................................................................................. 232

9 iWRAP Error Messages ............................................................................................. 233

9.1 HCI Errors ......................................................................................................................................... 233

9.2 SDP Errors ........................................................................................................................................ 235

9.3 RFCOMM Errors ............................................................................................................................... 236

9.4 L2CAP Errors .................................................................................................................................... 237

10 Supported Bluetooth Profiles ................................................................................ 238

Silicon Labs

21.4.2015

10.1 RFCOMM with TS07.10 ................................................................................................................ 238

10.2 Service Discovery Protocol (SDP) ................................................................................................. 238

10.3 Serial Port Profile (SPP) ................................................................................................................ 238

10.4 Headset Profile (HSP) ................................................................................................................... 239

10.5 Hands-Free Profile (HFP) .............................................................................................................. 239

10.6 Dial-up Networking Profile (DUN) .................................................................................................. 240

10.7 OBEX Object Push Profile (OPP) .................................................................................................. 240

10.8 OBEX File Transfer Profile (FTP) .................................................................................................. 240

10.9 Advanced Audio Distribution Profile (A2DP) ................................................................................. 241

10.10 Audio Video Remote Control Profile (AVRCP) .............................................................................. 241

10.11 Human Interface Device Profile (HID) ........................................................................................... 241

10.12 Phone Book Access Profile (PBAP) .............................................................................................. 242

10.13 Health Device Profile (HDP) .......................................................................................................... 242

10.14 Device Identification Profile (DI) .................................................................................................... 242

10.15 Bluegiga Proprietary Profiles ......................................................................................................... 243

10.16 UUIDs of Bluetooth profiles ........................................................................................................... 244

11 Useful Information .................................................................................................. 248

11.1 PS-keys and how to change them ................................................................................................. 248

11.2 BlueTest radio test utility ............................................................................................................... 249

11.3 Switching between iWRAP and HCI firmware ............................................................................... 250

11.4 Firmware updates .......................................................................................................................... 251

11.5 UART hardware flow control .......................................................................................................... 252

11.6 RS232 connections diagram ......................................................................................................... 253

12 General Bluetooth Information .............................................................................. 254

12.1 Secure Simple Pairing (SSP) Overview ........................................................................................ 254

12.2 Sniff power saving mode ............................................................................................................... 257

13 Known Issues .......................................................................................................... 259

14 iWRAP Usage Examples ........................................................................................ 263

14.1 Serial Port Profile ........................................................................................................................... 263

14.2 Dial-up Networking ........................................................................................................................ 263

14.3 Hands-Free Audio Gateway Connection to a Headset Device ..................................................... 264

14.4 Hands-Free connection to a Mobile Phone ................................................................................... 264

14.5 Human Interface Device profile example ...................................................................................... 264

14.6 Wireless IO Replacement .............................................................................................................. 265

14.7 A2DP Sink ..................................................................................................................................... 267

14.8 A2DP Source ................................................................................................................................. 267

14.9 AVRCP Connection ....................................................................................................................... 267

14.10 Over-the-Air Configuration ............................................................................................................. 268

Silicon Labs

21.4.2015

15 Technical support ................................................................................................... 269

15.1 Sending email to technical support ............................................................................................... 269

16 Contact information ................................................................................................ 270

Silicon Labs

21.4.2015

Host Controller Interface

L2CAP / eL2CAP

RFCOMM

SDP Audio

iWRAP

Link Manager

Baseband

Radio

UART / USB

GPIO / AIO

PCM / I2S / SPDIF

Analogue

Host + application

iWRAP

Hardware

1 Introduction

iWRAP is an embedded firmware running entirely on the RISC processor of WT12, WT11, WT41 and WT32
modules. It implements the full Bluetooth protocol stack and many Bluetooth profiles as well. All software
layers, including application software, run on the internal RISC processor in a protected user software
execution environment known as a Virtual Machine (VM).

The host system can interface to iWRAP firmware through one or more physical interfaces, which are also
shown in the figure below. The most common interfacing is done through the UART interface by using the
ASCII commands that iWRAP firmware supports. With these ASCII commands, the host can access Bluetooth
functionality without paying any attention to the complexity, which lies in the Bluetooth protocol stack. GPIO
interface can be used for event monitoring and command execution. PCM, SPDIF, I2S or analog interfaces
are available for audio. The available interfaces depend on the used hardware.

The user can write application code to the host processor to control iWRAP firmware using ASCII commands
or GPIO events. In this way, it is easy to develop Bluetooth enabled applications.

On WT32 there is an extra DSP processor available for data/audio processing.

Figure 1: iWRAP Bluetooth stack

Silicon Labs

Page 10 of 270

21.4.2015

In the figure above, a Bluetooth module with iWRAP firmware could be connected to a host system for
example through the UART interface. The options are:

 If the host system has a processor, software can be used to control iWRAP by using ASCII based

commands or GPIO events.

 If there is no need to control iWRAP, or the host system does not need a processor, iWRAP can be

configured to be totally transparent and autonomous, in which case it only accepts connections or
automatically opens them.

 GPIO lines that Bluegiga’s Bluetooth modules offer can also be used together with iWRAP to achieve

additional functionality, such as Carrier Detect or DTR signaling.

 Audio interfaces can be used to transmit audio over a Bluetooth link.

Silicon Labs

Page 11 of 270

21.4.2015

WRAP THOR AI (5.0.2 build 992)
Copyright (c) 2003-2013 Bluegiga Technologies Inc.
Built-in self-test error 992.10 - please contact <www.bluegiga.com/support>
No license key found or license key is wrong!

LICENSE 00112233445566778899aabbccddeeff
RESET

WRAP THOR AI (5.0.2 build 992)
Copyright (c) 2003-2013 Bluegiga Technologies Inc.

2 Migrating from previous iWRAP versions

This section only applies when upgrading from a previous version; users of new iWRAP5 modules
can ignore this.

For users upgrading to iWRAP5 from previous versions, the first consideration is that iWRAP is no longer
locked to Bluegiga’s address range of 00:07:80:xx:xx:xx, but instead uses a per-module license key. The
module will boot without the license key, and function normally, but with the radio interface completely
disabled. The following error message will be displayed:

For new modules coming from the factory (including modules with iWRAP3 or iWRAP4), the license key will
be written at the factory, and will be preserved in the “factory settings” section of the Persistent Store.

To enter a license key obtained from www.bluegiga.com/support, you can either use PSTool to write the
license to the key “Module security code” (0x025c PSKEY_MODULE_SECURITY_CODE), or use the built-in
command LICENSE, followed by a RESET command.

For writing license files in batches while upgrading stocked modules to iWRAP5, please contact

www.bluegiga.com/support.

Silicon Labs

Page 12 of 270

21.4.2015

3 Changes from iWRAP 5.0.1

3.1 New features

 SSP user confirmation auto-accept can be enabled by setting SET CONTROL CONFIG block #3 bit

#1: SET CONTROL CONFIG 2 0 0 0.

 New SET PROFILE HID configuration bits #4 and #5, which allow for reception of raw HID output

reports and larger HID data channel MTU configuration.

 SET CONTROL AUDIO allows routing input and output to different audio interfaces
 New optional parameter for SET BT SNIFF allows automatic sniff / active mode management

3.2 Issues addressed

3.2.1 General issues

 The radio power table for WT41-A and WT41-E has been adjusted to reduce the difference between

power output levels. Since the change does not affect the maximum power output, only the steps
between the minimum and maximum power level, it does not affect any radio certifications.

 We have found and implemented a workaround for CSR’s S/PDIF issue with getting wrong sampling

rates. S/PDIF can be used for A2DP audio, but not for SCO audio. See IWRAP-577 in the list of
known issues

 Added missing leading zeroes to SSP CONFIRM events – now iWRAP will always print 6 digits, for

example “012345” instead of “12345”. The leading zeroes are still missing from SSP PASSKEY

notification events (known issue IWRAP-579)

 Command @{link_id} now works for link_ids above 9
 Fixed a bug which caused link_ids above a disconnected link_id to stop working with the @

command; for example, if iWRAP had connections 0, 1 and 2, and connection #1 was disconnected,
@2 would no longer work

 Fixed parts of INFO CONFIG output missing when using very low baud rates
 Fixed a bug that limited the maximum number of ACL connections (unique Bluetooth devices) to 6

instead of 7 on BlueCore4-based modules (WT11i, WT12, WT41). On WT32, 6 is still the limit

 Fixed PLAY command and SET CONTROL RINGTONE stopping working after a VOLUME command

was issued

 Fixed SET BT PAGEMODE alternate pagemode setting threshold to count active ACLs (unique

devices connected to), not active logical links

 Added missing leading zeroes to SSP CONFIRM events
 Fixed a connection issue when making an L2CAP call and an RFCOMM call to a service UUID

simultaneously, and the L2CAP connection failed, which caused iWRAP to lose track of the RFCOMM
connection state, which in turn caused further SDP connections to fail

 Fixed no sound issue when SPDIF or I2S is used as an audio input.

3.2.2 A2DP profile issues

 Fixed a memory leak in the stream endpoint discovery subroutines, which caused iWRAP to crash

after 15 outgoing A2DP calls

Silicon Labs

Page 13 of 270

21.4.2015

 Fixed a bug in SET CONTROL CODEC that would leave aptX enabled for incoming connections even

when it was disabled with SET CONTROL CODEC

 Fixed problem with A2DP streaming using AptX codec from some new mobile phones

3.2.3 HID profile issues

 Added missing Bluetooth HID Handshake response to SET_REPORT packets sent by the HID Host
 Fixed an issue with losing characters in ASCII keyboard mode when the same letter was sent over

and over again, but with different Shift key states, e.g. “AaAaAa”

 HID GET now prints the last byte of an odd-numbered HID descriptor correctly; previously it always

printed the last byte as zero, even though it was stored and sent over the air correctly

 Fixed HID failure in data mode when SET CONTROL ESCAPE was disabled

3.2.4 iAP profile issues

 Fixed a rare data duplication bug
 Fixed iAP not working with SET CONTROL CONFIG 0040 0000 (print “OK” after each command)
 Fixed a bug with iWRAP hanging in MUX mode when an iAP link was abnormally disconnected in the

middle of receiving a MUX frame from the UART that was intended for the iAP link

3.3 Newly discovered known issues

See issues IWRAP-159, IWRAP-533, IWRAP-535, IWRAP-550, IWRAP-574, IWRAP-577, IWRAP-578,
IWRAP-579, IWRAP-596, IWRAP-614, IWRAP-619, IWRAP-620, IWRAP-628, IWRAP-641, IWRAP-644,
IWRAP-646, IWRAP-663, IWRAP-691, IWRAP-706, IWRAP-765 in Chapter 13.

Silicon Labs

Page 14 of 270

21.4.2015

4 Getting started

To start using iWRAP firmware, you can use, for example, terminal software such as HyperTerminal. When
using the terminal software, make sure that the Bluetooth module is connected to your PC’s serial port. By
default, iWRAP uses the following UART settings:

 Baud rate: 115200bps
 Data bits: 8
 Stop bits: 1
 Parity bit: No parity
 HW Flow Control: Enabled

When you power up your Bluetooth module or evaluation kit, you can see the boot prompt appear on the
screen of the terminal software. After the “READY.” event iWRAP firmware is ready to be used.

Figure 2: iWRAP boot prompt

If no READY. event is received the possible reasons are:

 The Bluetooth module is not equipped with iWRAP firmware, but HCI firmware
 The UART logic levels are incorrect
 Boot prompt is disabled with “SET CONTROL ECHO 0” setting

Silicon Labs

Page 15 of 270

21.4.2015

AT

OK

SET

SET BT BDADDR 00:07:80:ff:ff:f1
SET BT NAME WT32-A
SET BT CLASS 001f00
SET BT IDENT BT:47 f000 4.0.0 Bluegiga iWRAP
SET BT LAP 9e8b33
SET BT PAGEMODE 4 2000 1
SET BT POWER 0 0 0
SET BT ROLE 0 f 7d00
SET BT SNIFF 0 20 1 8
SET BT MTU 667
SET CONTROL BAUD 115200,8n1
SET CONTROL CD 00 0
SET CONTROL ECHO 7
SET CONTROL ESCAPE 43 00 1
SET CONTROL GAIN 8 8
SET CONTROL MSC DTE 00 00 00 00 00 00
SET CONTROL READY 00
SET PROFILE SPP Bluetooth Serial Port
SET

4.1 First course to iWRAP

A few very basic iWRAP usage examples are presented below. Just a few very basic use cases are shown
and more detailed examples will be presented later in this user guide.

AT command can be sent to iWRAP to test that the firmware is operational. An OK response tells that iWRAP
is functional.

SET command displays the settings of the local Bluetooth device.

Silicon Labs

Page 16 of 270

21.4.2015

INQUIRY 5

INQUIRY_PARTIAL 00:21:86:35:c9:c8 02010c
INQUIRY_PARTIAL 00:07:80:93:d7:66 240408
INQUIRY_PARTIAL a8:7b:39:c3:ca:99 5a020c
INQUIRY 3
INQUIRY 00:21:86:35:c9:c8 02010c
INQUIRY 00:07:80:93:d7:66 240408
INQUIRY a8:7b:39:c3:ca:99 5a020c

SET BT AUTH * 0000

SET BT SSP 3 0

CALL 00:07:80:93:d7:66 1101 RFCOMM

CALL 0
CONNECT 0 RFCOMM 1

SET RESET

WRAP THOR AI (4.0.0 build 317)
Copyright (c) 2003-2010 Bluegiga Technologies Inc.
READY.

INQUIRY command can be used to discover other visible Bluetooth devices in the range. An
INQUIRY_PARTIAL event is generated as soon as a device is discovered and finally is summary is displayed.

SET commands can be used to modify the settings of the local Bluetooth device. In the example below

Bluetooth PIN code required for pairing is set to “0000” and also the Secure Simple Pairing (SSP) “just works”

mode is enabled. The settings are stored on a local non-volatile memory so they need to be configured only
once. With iWRAP5 SSP is always enabled to fulfil Bluetooth 2.1 and later specifications.

A Bluetooth connection is opened with a CALL command. A CALL event indicates that a connection
establishment is in progress and a CONNECT event indicates a successful connection.

A SET RESET command can be used to return the factory level settings. iWRAP is reset as indicated by the
boot prompt.

Silicon Labs

Page 17 of 270

21.4.2015

- CONNECT event

- RING event

- Escape sequence

- SELECT command

Command

Mode

Data Mode

- NO CARRIER event

- Escape sequence

- DTR switch

5 iWRAP modes

iWRAP has two basic operational modes, command mode and data mode. In command mode, ASCII
commands can be given to iWRAP firmware to perform various actions or to change configuration settings.
Command mode is the default mode when there are no Bluetooth connections. Data mode, on the other hand,
is used to transmit and receive data over a Bluetooth link. Data mode is only available if there is a Bluetooth
connection. It is possible to switch between modes at any time assuming the conditions for data mode are
fulfilled. The mode transitions are illustrated below.

Figure 3: Mode transitions

Silicon Labs

Page 18 of 270

21.4.2015

Initial mode

Target mode

Requirements for state transition

Command Mode
(no Bluetooth connections)

In this mode, ASCII commands
can be given to iWRAP.

Data Mode

A connection is successfully created by
using the CALL command and
CONNECT event indicating that a
successful connection is received.

A remote device opens a Bluetooth
connection to iWRAP. A RING event
indicating that a connection is received.

If iWRAP events are disabled the carrier
detect (CD) pin can also be used to
indicate data or command mode.

Data Mode
In this mode, all data is sent

transparently from UART
interface to Bluetooth connection.

Command Mode

The user switches mode by sending an
escape sequence to iWRAP firmware or
by toggling the DTR pin.

A link is terminated (closed by the remote
device or by link loss) and NO
CARRIER event is received.

Command Mode
(active connection)

In this mode, ASCII commands
can be given to iWRAP.

Data Mode

User switches the mode either by sending
an escape sequence to iWRAP firmware
or by using the SELECT command.

5.1 The escape sequence

The escape sequence causes the iWRAP firmware to toggle between command mode and data mode. The
escape sequence consists of three (3) escape characters that are defined by the SET CONTROL ESCAPE
command. By default, the escape character is ‘+’.

Do not enter any character before and/or after the escape sequence for a guard time, which is 1 second.
Furthermore, send the escape characters individually, not as a string.

With default settings, the escape sequence is:

< 1 second sleep> +++ < 1 second sleep>
When a successful state transition from data mode to command mode is made, iWRAP sends a “READY.”

event to indicate that it is ready to receive commands.
The same escape sequence or the SELECT command can be used to return to data mode.

Table 1: iWRAP mode transitions explained

Silicon Labs

Page 19 of 270

21.4.2015

5.2 Command mode

The command mode is the default mode when iWRAP is powered up. In command mode, ASCII commands
can be entered to iWRAP to perform various functions.

Notes:

 In command mode, if there are active Bluetooth connections, the data from remote devices is buffered

into iWRAP buffers.

 Because of the embedded nature of iWRAP, buffering capabilities are low and only small amounts of

data can be received to buffers. The amount of data which can be buffered depends on the firmware
version and the state of iWRAP. Usually, it is around 1000 bytes, but may vary radically.

 The LIST command shows active connections and the amount of buffered data.

5.3 Data mode

Data mode is the default mode when there are one or more Bluetooth connections. In data mode, all data is
sent transparently from UART interface to the Bluetooth link and vice versa.

Notes:

 When iWRAP enters command mode from data mode, a “READY” event occurs, unless events are

masked away by using the “SET CONTROL ECHO” command.

 The DTR pin can be used instead of the escape sequence to switch from data mode to command

mode. This allows much faster mode switching and no guard time is needed. The DTR pin can be
enabled by using the “SET CONTROL ESCAPE” command.

 When enabled, the DTR line can be configured also for closing the active connection or for a reset.
 The Carrier Detect (CD) pin can be used to indicate either a Bluetooth connection or data mode. The

CD pin can be enabled and configured by using the “SET CONTROL CD” command.

 The “SET CONTROL BIND” command can be used in conjunction with the “SET CONTROL

ESCAPE” command to allow data-command-data mode switches with the same GPIO line; consider

in fact the following commands together: “SET CONTROL ESCAPE - 20 1” and “SET CONTROL
BIND 0 20 F SELECT 0”

Silicon Labs

Page 20 of 270

21.4.2015

5.4 Multiplexing mode

In iWRAP version 2.1.0 and newer, there is a special mode called multiplexing mode. In this mode, iWRAP
does not have separate commands or data modes, but data, commands and events are all handled in one
single mode. There is, however, a special protocol to separate commands and events from the actual data.
This protocol must be used between the host system and iWRAP firmware.

The advantage of multiplexing mode is that several Bluetooth connections can be handled simultaneously and
there is no need to do time consuming data-command-data mode switching. However, the downside is that
the performance of iWRAP is reduced, since the firmware needs to handle the multiplexing protocol and it
causes overhead.

To learn more about multiplexing mode, see the description of the “SET CONTROL MUX” command.

5.5 HFP and HSP modes

iWRAP 2.2.0 and newer support Bluetooth Hands-Free (v.1.6) profile. This profile includes a lot of control
messaging and events, which are handled in command mode. In other words, when a HFP connection is
opened or received no state transition occurs, but iWRAP stays in command mode, where all HFP messaging
is done. Refer to HFP profile usage for more information.

5.6 OBEX mode

IWRAP4 and newer versions support Bluetooth Object Push Profile (OPP) or File Transfer Protocol (FTP)
modes. The operation in this mode is quite similar to HFP mode. For example, there are no separate
command and data modes, but iWRAP always stays in command mode. Refer to OPP and FTP profile usage
for more information.

5.7 A2DP mode

As of iWRAP3, Bluetooth Advanced Audio Distribution Profile (A2DP) is supported. This profile also includes
control messaging and events, which are handled in command mode. In other words, when an A2DP
connection is opened or received no state transition occurs, but iWRAP stays in command mode, where all
A2DP messaging is done.

5.8 AVRCP mode

As of IWRAP3, Bluetooth Audio/Video Remote Control Profile (AVRCP) is supported. This profile also
includes control messaging and events, which are handled in command mode. In other words, when an
AVRCP connection is opened or received no state transition occurs, but iWRAP stays in command mode,
where all AVRCP messaging is done.

5.9 PBAP mode

As of IWRAP4, Bluetooth Phone Book Access Profile (PBAP) is supported. This profile also includes control
messaging and events, which are handled in command mode. In other words, when a PBAP connection is
opened or received no state transition occurs, but iWRAP stays in command mode, where all PBAP
messaging is done.

Silicon Labs

Page 21 of 270

6 Technical details

Feature

Value

MAX simultaneous ACL connections

7 (6 with WT32)

MAX simultaneous SCO connections

1

MAX data rate

550 kbps (WTxx to BT2.0 USB dongle)
500 kbps (WTxx to WTxx)
450 kbps (WTxx to BT1.1-BT1.2 device)
N/A (MUX data rate)
50 kbps (OBEX transfer)

MAX UART baud rate

1800000 bps

Typical data transmission delay

10-15ms

Minimum data transmission delay

5-10ms

Typical SCO delay

30-40ms

Typical A2DP delay (*

150-200ms

A2DP coding/encoding methods

SBC, aptX**

PIN code length

Configurable from 0 to 16 characters.

Encryption length

From 0 to 128** bits

MAX simultaneous pairings

16

MAX Friendly name length

Configurable up to 248 characters

RFCOMM Packet size

Configurable from 21 to 1009

Supported Bluetooth profiles (iWRAP5)

GAP, SPP, HFP (v.1.6 with wideband speech), HSP (v.1.2)
A2DP, AVRCP (1.3 CT, 1.0 TG), HID, DUN, DI, OPP, FTP,
HDP, PBAP and MAP.

Supported power saving modes

Sniff and deep sleep

Bluetooth QD ID

iWRAP 5.0: B019486
iWRAP 4.0: B016540
iWRAP 3.0: B014328
iWRAP 2.2.0: B012647

21.4.2015

Silicon Labs

Page 22 of 270

21.4.2015

Secure Simple Pairing modes

Just works mode
Man-in-the-middle protection (MITM)
Out-of-Band (OOB) pairing

Echo canceling and noise reduction

Clear Voice Capture (cVc) algorithm. A licensable 3rd party
product.

Table 2: Technical details

*) Alternative coding methods (aptX, FastStream) exist to reduce the delay to 40-90ms or to improve audio
quality.

**) Custom firmware needs to be request from www.bluegiga.com/support

Silicon Labs

Page 23 of 270

21.4.2015

7 iWRAP command reference

iWRAP can be used and controlled from the host system by sending ASCII commands through the
UART interface to iWRAP.

This section explains the iWRAP commands and their syntax. Some simple usage examples and tips
are also given.

NOTES:

 The parser is not case sensitive!
 iWRAP commands must end with a line feed “\n” character.
 By default iWRAP does not print OK to indicate that the command has been executed, but this

feature can be separately enabled with SET CONTROL CONFIG command.

Silicon Labs

Page 24 of 270

21.4.2015

Command:

iWRAP version:

HW version:

Short description

AUTH

iWRAP 2.2.0

ALL

Authenticates Bluetooth pairing

BER

iWRAP 2.2.0

ALL

Reads Bit Error Rate

CALL

iWRAP 2.1.0

ALL

Opens Bluetooth connections

CLOCK

iWRAP 3.0

ALL

Reads Piconet clock

CLOSE

iWRAP 2.1.0

ALL

Closes Bluetooth connections

CONNAUTH

iWRAP 4.0.0.

ALL

Authenticate incoming connections

CONNECT

iWRAP 3.0

ALL

Connects Bluetooth links

ECHO

iWRAP 2.2.0

ALL

Echoes data to Bluetooth connection

IC

iWRAP 2.2.0

ALL

Inquiry cancel

IDENT

iWRAP 3.0

ALL

Identifies a Bluetooth device

INQUIRY

iWRAP 2.1.0

ALL

Searches other Bluetooth devices

KILL

iWRAP 3.0

ALL

Kills Bluetooth connections

L2CAP

iWRAP 3.0

ALL

Sets up L2CAP psm

LIST

iWRAP 2.1.0

ALL

Lists Bluetooth connections

NAME

iWRAP 2.2.0

ALL

Does friendly name discovery

PAIR

iWRAP 3.0

ALL

Pairs with a Bluetooth device

PING

iWRAP 2.2.0

ALL

Pings a Bluetooth connection

RFCOMM

iWRAP 3.0

ALL

Sets up RFCOMM channels

RSSI

iWRAP 2.2.0

ALL

Reads RSSI of a connection

7.1 Command listings

All the available iWRAP commands are listed and briefly described in the tables below. The detailed
description of each command can be found later.

Silicon Labs

Page 25 of 270

SCO ENABLE

iWRAP 2.2.0

ALL

Enables SCO connections

SCO OPEN

iWRAP 2.2.0

ALL

Opens SCO connection

SDP

iWRAP 2.2.0

ALL

Browse SDP records

SDP ADD

iWRAP 2.2.0

ALL

Create SDP entries

SELECT

iWRAP 2.1.0

ALL

Selects a Bluetooth connection

TEST

iWRAP 2.2.0

ALL

Enables self test modes

TESTMODE

iWRAP 2.2.0

ALL

Enables Bluetooth test mode

TXPOWER

iWRAP 2.2.0

ALL

Reads TX power level

Table 3: Commands related to Bluetooth actions

21.4.2015

Silicon Labs

Page 26 of 270

21.4.2015

Command:

iWRAP
version:

HW version:

Short description

@

iWRAP 4.0.0.

ALL

Shortcut for “SET {link_id} SELECT”

AIO

iWRAP 4.0.0

ALL

Read AIO values

A2DP

iWRAP3.0

WT32

A2DP streaming control

AT

iWRAP 2.1.0

ALL

Attention

BATTERY

iWRAP 3.0

WT32

Reads battery level

BCSP_ENABLE

iWRAP 3.0

ALL

Enables BCSP mode

BLINK

iWRAP 5.0.0

ALL

Configures LED blinking

BOOT

iWRAP 2.2.0

ALL

Boots module into different modes

BYPASSUART

iWRAP 3.0

ALL

Enables UART bypass

DEFRAG

iWRAP 3.0

ALL

Defrags PS key storage

DELAY

iWRAP 5.0.0

ALL

Delay before executing a command

HELP

iWRAP 2.2.0

ALL

Prints help

HID GET

iWRAP 5.0.0

ALL

HID descriptor reading

HID SET

iWRAP 5.0.0

ALL

HID descriptor writing

INFO

iWRAP 2.2.0

ALL

Prints firmware information

PIO

iWRAP 3.0

ALL

Reads & Writes PIO statuses

RESET

iWRAP 2.1.0

ALL

Does a software reset

SET

iWRAP 2.1.0

ALL

Lists iWRAP configuration

SET RESET

iWRAP 3.0.0

ALL

Restores factory settings

SLEEP

iWRAP 2.2.0

ALL

Enables deep sleep

TEMP

iWRAP 3.0

ALL

Reads internal temperature sensor

Silicon Labs

Page 27 of 270

VOLUME

iWRAP 3.0

ALL

Changes volume level

Table 4: Generic commands

21.4.2015

Silicon Labs

Page 28 of 270

21.4.2015

Command:

iWRAP version:

HW version:

Short description

SET BT OPP

iWRAP 2.2.0

ALL

Enable OPP profile

SET BT AUTH

iWRAP 2.1.0

ALL

Set PIN code

SET BT BDADDR

iWRAP 2.1.0

ALL

Read BD_ADDR

SET BT CLASS

iWRAP 2.1.0

ALL

Set Class-of-Device

SET BT FILTER

iWRAP 5.0.0

ALL

Inquiry result filter

SET BT IDENT

iWRAP 3.0

ALL

Set DI profile data

SET BT LAP

iWRAP 2.2.0

ALL

Set inquiry access code

SET BT MTU

iWRAP 4.0.0

ALL

Configure Bluetooth connection
MTU

SET BT NAME

iWRAP 2.1.0

ALL

Change friendly name

SET BT PAGEMODE

iWRAP 2.1.0

ALL

Set page mode and timeout

SET BT PAIR

iWRAP 2.1.0

ALL

Manage pairings

SET BT PAIRCOUNT

iWRAP 4.0.0

ALL

Limit the number of stored pairings

SET BT POWER

iWRAP 2.2.0

ALL

Set TX power levels

SET BT ROLE

iWRAP 2.1.0

ALL

Set role and supervision timeout

SET BT SCO

iWRAP 5.0.0

ALL

Configure SCO audio parameters

SET BT SNIFF

iWRAP 2.2.0

ALL

Manage automatic sniff mode

SET BT SSP

iWRAP 4.0.0

ALL

Configure SSP capabilities

Table 5: Bluetooth settings related SET commands

Silicon Labs

Page 29 of 270

21.4.2015

Command:

iWRAP
version:

HW
version:

Short description

SET CONTROL AUDIO

iWRAP 4.0.0

WT32

Configure hardware audio interfaces

SET CONTROL AUTOCALL

iWRAP 2.1.0

ALL

Manage automatic connection
control

SET CONTROL AUTOPAIR

iWRAP 5.0.0

ALL

Manage automatic pairing

SET CONTROL BATTERY

iWRAP 4.0.0.

WT32

Change battery configuration

SET CONTROL BAUD

iWRAP 2.1.0

ALL

Change UART baud rate

SET CONTROL BIND

iWRAP 2.2.0

ALL

Manage GPIO bindings

SET CONTROL CD

iWRAP 2.1.0

ALL

Manage Carrier Detect (CD) signal

SET CONTROL CODEC

iWRAP 4.0.0

WT32

Configures the internal audio codec

SET CONTROL CONFIG

iWRAP 2.1.0

ALL

Manage configuration bits

SET CONTROL ECHO

iWRAP 2.1.0

ALL

Manage echo mode

SET CONTROL GAIN

iWRAP 3.0

WT32

Manage ADC and DAC gains

SET CONTROL INIT

iWRAP 2.1.0

ALL

Manage start-up command

SET CONTROL MICBIAS

iWRAP 3,0

WT32

Control MIC bias settings

SET CONTROL MSC

iWRAP 2.2.0

ALL

Manage MSC functionality

SET CONTROL MUX

iWRAP 2.2.0

ALL

Manage MUX mode

SET CONTROL PCM

iWRAP 3.0-4.0

ALL

Manage PCM settings. Removed in
iWRAP5.

SET CONTROL PIO

iWRAP 5.0.0

ALL

Sets the initial direction of the PIOs

SET CONTROL PREAMP

iWRAP 4.0

WT32

Enable/disable 20dB preamplifier

SET CONTROL RINGTONE

iWRAP 4.0

All

Set HFP/HSP ringtone

SET CONTROL READY

iWRAP 4.0

All

Tells when iWRAP firmware is ready

SET CONTROL VOLSCALE

iWRAP 5.0.0

WT32

Scale the volume levels

Silicon Labs

Page 30 of 270