UG212: Bluetooth® Smart Ready Configuration Guide

BLUETOOTH SMART READY
CONFIGURATION GUIDE
Wednesday, 23 September 2015
Version 1.4
Copyright © Silicon Labs
All rights reserved.
Silicon Labs assumes no liability or responsibility for any errors, mistakes or inaccuracies in content. Silicon
Labs reserves the right to change products or specifications without notice, and does not make any commitment
to update the information herein.
Silicon Labs’ products are not authorized for use as critical components in life support devices or systems.
The Bluetooth® word mark and logos are registered trademarks owned by the Bluetooth® SIG, Inc. USA.
All other trademarks and trade names listed herein belong to their respective owners.
Information is subject to change without notice.
Bluegiga – A Silicon Labs Company
Page 2 of 23
Table of Contents
1 Version History ________________________________________________________________________ 4
2 Introduction ___________________________________________________________________________ 5
2.1 Project structure ___________________________________________________________________ 5
2.1.1
Project file _________________________________________________________________ 5
2.1.2
Hardware configuration _______________________________________________________ 5
2.1.3
Bluetooth Smart service database ______________________________________________ 5
2.1.4
Bluetooth classic profile SDP entries ____________________________________________ 5
2.1.5
BGScript application code _____________________________________________________ 5
2.1.6
Host application code ________________________________________________________ 6
3 Project File Syntax ______________________________________________________________________ 7
3.1 <project> _________________________________________________________________________ 7
3.2 <hardware> ______________________________________________________________________ 7
3.3 <gatt> ___________________________________________________________________________ 8
3.4 <script> __________________________________________________________________________ 8
3.5 <image> _________________________________________________________________________ 8
3.6 <entry> __________________________________________________________________________ 9
3.7 Examples ________________________________________________________________________ 9
4 Hardware Configuration File _____________________________________________________________ 11
4.1 <adc> __________________________________________________________________________ 11
4.2 <sleep> _________________________________________________________________________ 11
4.3 <wakeup_pin> ___________________________________________________________________ 12
4.4 <port> __________________________________________________________________________ 14
4.5 <uart> __________________________________________________________________________ 16
4.6 <spi> ___________________________________________________________________________ 17
4.7 <i2c> ___________________________________________________________________________ 19
5 SPP Configuration file __________________________________________________________________ 21
6 DID Configuration file __________________________________________________________________ 22
Bluegiga – A Silicon Labs Company
Page 3 of 23
1 Version History
Version
Comments
1.0
First version
1.1
Improved hardware.xml syntax documentation
1.2
ADC / Sleep pin / I2C parts edited and general edits
1.3
SPP and DID sections added
1.4
Minor changes
Bluegiga – A Silicon Labs Company
Page 4 of 23
2 Introduction
This document walks you through how to start a software project for your Bluetooth Smart Ready modules, how
to include the necessary resources in the project and also how to do configure the hardware interface settings
for the Bluetooth modules.
2.1 Project structure
The figure below illustrates the Bluetooth software project structure and the mandatory and optional resources
the structure is relatively simple and consists of the following components:
1.
2.
3.
4.
5.
6.
Project file
Hardware configuration file
Bluetooth Smart service and characteristics database (GATT database)
Bluetooth classic profile SDP entries
BGScript application source code (optional)
Host application source code (optional and exclusive to BGScript code)
2.1.1 Project file
Project file simply defines the resources included in the project and their physical locations.
2.1.2 Hardware configuration
The hardware configuration file defines the host and peripheral interfaces like UART, SPI, I2C and GPIO used
by the application and their physical locations (pins) and the settings.
2.1.3 Bluetooth Smart service database
The service database (GATT database) defines the contents and structure of the Bluetooth GATT services and
characteristics implemented by the application. The GATT database is defined with the Profile Toolkit TM tool
included in the Bluetooth SDK, which is XML based description language for GATT services and characteristics.
2.1.4 Bluetooth classic profile SDP entries
The SDP entries defines the contents of the Service Discovery Profile database for Bluetooth classic profiles
like Serial Port Profile.
2.1.5 BGScript application code
BGScript is a basic-style application programming language, which allows simple applications to be embedded
into the Bluetooth modules. In case BGScript is used to implement the application logic, the source files need to
be included in the Bluetooth project file.
Bluegiga – A Silicon Labs Company
Page 5 of 23
2.1.6 Host application code
An alternative way to implement the application is to use an additional host (typically a MCU) and use the
Bluetooth module as a modem. In this case the application code runs outside the module and source code files
do not need to be included in the Bluetooth project, but the architecture selection needs to defined in the project
file.
Bluegiga – A Silicon Labs Company
Page 6 of 23
3 Project File Syntax
The project file (typically project.xml or project.bgproj) is the file that describes all the components included in
your Bluetooth Smart Ready project. Typically these files are named as follows:
hardware.xml - Hardware configuration file for interfaces like UART and SPI
GATT.xml - GATT database file for Bluetooth Smart services and characteristics
DID.xml and SPP.xml - SDP entry file(s) for supported Bluetooth profiles
script.bgs - Optional BGScript application source code
The project file also defines other features of the project like the hardware version, firmware output files and
selected boot loader.
The project file itself is a simple XML file with only few elements on it, which are described below.
3.1 <project>
This attribute starts the definition of project file and also includes the hardware device type the project is meant
for. All the other definitions need to be inside the project attribute.
Attribute
Description
device
This attribute defines the hardware type this project is used for.
Options:
bt121
Example: Defining the hardware configuration file
<project device="bt121">
...
</project>
3.2 <hardware>
The XML element <hardware> and its attribute in are used to define the hardware configuration file for the
device.
Attribute
Description
in
This attribute points to the XML file which contains the hardware configuration definition for your
Bluegiga Bluetooth Smart Ready device.
Example: Defining the hardware configuration file
<hardware in="hardware.xml" />
Bluegiga – A Silicon Labs Company
Page 7 of 23
3.3 <gatt>
The XML element <gatt> and its attribute in are used to define the GATT database file.
NOTE! The GATT definition can also be placed inside the Project XML file.
Attribute
Description
in
This attribute points to the XML file that contains the GATT database defining the Bluetooth
Smart services and characteristics.
Example: Defining the GATT database file
<gatt in="GATT.xml" />
3.4 <script>
The optional XML element <script> and its attribute in are used to define the BGScript source code file.
Attribute
Description
in
This attribute points to the BGScript file that contains the BGScript source code for your
standalone Bluetooth Smart Ready application.
If you use the BGAPI protocol and a separate host (which cannot be used simultaneously with
BGScript code), this tag should not be used.
Example: Defining the BGScript file
<scripting>
<script in="bgdemo.bgs" />
</scripting>
3.5 <image>
The XML element <image> and its attribute out are used to define the firmware binary output files.
Attribute
Description
out
This attribute defines the name of the binary firmware output file which the compiler will generate.
This attribute will generate a .bin file which can be uploaded to the Bluetooth Smart Ready
Module using the DFU firmware update protocol.
Example: Defining the binary and HEX output files for the compiler
<image out="BT121_BGDemo.bin" />
Bluegiga – A Silicon Labs Company
Page 8 of 23
3.6 <entry>
The XML element <entry> and its attributes are used to define actual XML files for each Bluetooth classic
profile's SDP entry.
These XML elements are grouped within an XML element <sdp> </sdp> which is used to define the Bluetooth
BR/EDR Service Discover Profile (SDP) entries or Bluetooth profiles used by the project.
Attribute
Description
file
This element defines the name of the XML file containing a single SDP entry
autoload
This element defines whether the SDP entry should be loaded automatically when the Bluetooth
stack starts.
Values:
true: SDP entry is automatically loaded to the SDP database
false: SDP entry is NOT automatically loaded to the SDP database
id
This element defines a unique ID for the SDP entry that can then later be used by the application
to manually load the SDP entry
If autoload is used then id is not allowed.
Example: Defining an SDP entry for the project, which is autoloaded and another SDP entry with a
unique ID = 2
<sdp>
<entry file="DID.xml" autoload="true"/>
<entry file="SPP.xml" id="2"/>
</sdp>
3.7 Examples
Below is an example of a project file for BT121 Bluetooth Smart Ready Module.
BT121 Project
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Project configuration including BT121 device type -->
<project device="bt121">
<!-- XML file containing GATT service and characteristic
definitions both for BLE and GATT over BR -->
<gatt in="gatt.xml" out="gatt_db.c" />
<!-- Local hardware interfaces configuration file -->
<hardware in="hardware.xml" />
<!-- Local SDP entries for Bluetooth BR/EDR -->
<sdp>
<entry file="DID.xml" autoload="true"/>
<entry file="SPP.xml" id="2"/>
</sdp>
<!-- Firmware output files -->
<image out="BT121_BGDemo.bin" />
</project>
Below is an example of a project file for BT121 Bluetooth Smart Module including a BGScript application
Bluegiga – A Silicon Labs Company
Page 9 of 23
BT121 Project
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Project configuration including BT121 device type -->
<project device="bt121">
<!-- XML file containing GATT service and characteristic
definitions both for BLE and GATT over BR -->
<gatt in="gatt.xml" />
<!-- Local hardware interfaces configuration file -->
<hardware in="hardware.xml" />
<!-- Local SDP entries for Bluetooth BR/EDR -->
<sdp>
<entry file="DID.xml" autoload="true"/>
<entry file="SPP.xml" id="2"/>
</sdp>
<!-- BGScript source code file -->
<scripting>
<script in="bgdemo.bgs" />
</scripting>
<!-- Firmware output files -->
<image out="BT121_BGDemo.bin" />
</project>
Bluegiga – A Silicon Labs Company
Page 10 of 23
4 Hardware Configuration File
The hardware configuration file is used to configure the hardware features such as TX power, UART, SPI,
hardware timers, and GPIO settings of your Bluegiga Bluetooth Ready Smart device.
4.1 <adc>
This XML element <adc> is used to configure the module's ADC (Analog Digital Converter) settings:
Attribute
Description
inputs
This bitmask defines which ADC-channels are in use.
Values:
Bit 4: AIN4
Bit 5: AIN5
Bit 6: AIN6
Bit 7: AIN7
Example to enable all ADCs:
<adc inputs="0xf0" />
4.2 <sleep>
This XML element <sleep> can be used to allow or prevent the use of sleep modes.
Attribute
Description
enabled
Options:
true: All power modes can be enabled. Selection of power modes is done automatically by the
firmware. Firmware will select the best power saving mode automatically to achieve lowest
possible power consumption. Currently the lowest mode is Power Mode 2.
false: Use this to prevent the firmware from entering any of the sleep modes.
Default:
false
Example : Allow power saving
<sleep enabled="true" />
Bluegiga – A Silicon Labs Company
Page 11 of 23
4.3 <wakeup_pin>
This XML element <wakeup_pin> can be used to prevent to Bluetooth module from entering a sleep mode or
alternatively can be used to wake it up from a sleep mode. If you have enabled the use of sleep modes in the
hardware configuration file and use UART to communicate with the module, then this feature must be enabled
and you must assert the wake-up pin before sending any data or BGAPI commands to the module, and also
keep it asserted until the last byte has been clocked into the module over the UART RX pin.
The wake-up pin functionality can only be assigned to a single GPIO, but you can still assign normal GPIO
interrupts to other pins. The difference between the wake-up pin and normal GPIO interrupts is that the wake-up
pin will not only generate the interrupt which wakes the module, but will also keep the module awake as long as
it is held in the asserted state. Normal GPIO interrupts can wake the module from any state but after the
interrupt event handler completes the module will return to sleep.
There is always a delay before the module wakes up. It is possible to measure the wake-up time by
measuring when flow control starts to work. Data should not be sent before the module has waken up
to prevent data loss. Monitor the RTS/CTS signal to detect when the module has waken up. There is
no special command separately to wake up the module.
How to use the wake-up pin:
1.
2.
3.
4.
Assert the wake-up pin from an external host
Process the "dumo_evt_hardware_interrupt" event (See the API Reference)
Send the desired BGAPI command to the module
Wait until you receive the BGAPI response packet before de-asserting the wake-up pin
wake-up pin
Steps 2 and 4 are critical and must be implemented correctly or otherwise data might be lost.
Attribute
Description
port
Defines the port to which the wake-up pin is to be assigned to.
Options:
0: Port A
1: Port B
pin
Defines the pin of the defined port to which the wake-up pin is to be assigned to.
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
Bluegiga – A Silicon Labs Company
Page 12 of 23
Attribute
Description
state
Logic state for the assigned wake-up pin.
Options:
up
down
Default:
up
Example: Enabling wake-up pin on PB12 (BTN4 on DKBT Development kit) and defining the state to
"up".
<wakeup_pin port="1" pin="12" state="up" />
When this pin is pulled, the Bluetooth Smart Ready module does not enter any sleep modes which
increases power consumption.
Bluegiga – A Silicon Labs Company
Page 13 of 23
4.4 <port>
This XML element <port> can be used to define I/O port A and B configuration settings.
The attributes are explained in the table below.
Attribute
Description
index
Port index to configure
Range:
0: Port A
1: Port B
output
Output configuration (bit mask) for port.
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
input
Input configuration (bit mask) for port.
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
value
Default value configuration (bit mask) of pins after bootup.
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
pullup
Pull-up configuration (bit mask) for port.
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
pulldown
Pull-down configuration (bit mask) for port.
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
interrupts_rising
Rising interrupt configuration (bit mask) for this port
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
Bluegiga – A Silicon Labs Company
Page 14 of 23
Attribute
Description
interrupts_falling
Falling interrupt configuration (bit mask) for this port
Range:
Port A: pins 4-7 and 9-14
Port B: pins 4-10 and 12-15
Example : Set PB8 and PB9 as outputs and enable interrupts on PB10 and PB13
<port index="1" output="0x300" />
<port index="1" input="0x2400"/>
<port index="1" interrupts_rising="0x2400"/>
Bluegiga – A Silicon Labs Company
Page 15 of 23
4.5 <uart>
This XML element <uart> can be used to define settings of the UART interface on the module.
The attributes are explained in the table below.
attribute
description
baud
UART baudrate
Range:
1200 - 4000000
Default:
115200
stopbits
Number of stop bits
Options:
1
1.5
2
Default:
1
parity
Parity bit settings
Values:
odd: use odd parity bit
even: use even parity bit
none: no parity bit
Default:
none
Example:
parity="odd"
flowcontrol UART flow control setting
Options:
true: Hardware flow control (RTS and CTS) enabled
false: Hardware flow control (RTS and CTS) disabled
Default:
false
Bluegiga – A Silicon Labs Company
Page 16 of 23
attribute
description
bgapi
UART is used for BGAPI protocol
Values:
true: UART is used for BGAPI protocol
false: UART is used for application data
Default:
false
Example:
bgapi="true"
Note:
When true, there should be an application receiving the BGAPI responses and events at the
host uC, otherwise the module might get stuck.
timeout
This parameter configures the timeout in milliseconds that the module waits between two
consecutive bytes received over UART.
If UART is in transparent mode (bgapi="false") and this timeout is reached, then the bytes are
sent forward.
if UART is in BGAPI mode (bgapi="true") and this timeout is reached while sending the bytes
belonging to a BGAPI command, then a syntax error event is sent back to the host and the
UART buffer is cleared.
Range:
1 - 4000
Default:
1 (bgapi=false)
1000 (bgapi=true)
Example : Enabling BGAPI over UART on BT121 @ 115200bps and RTS/CTS flow control
<uart baud="115200" flowcontrol="true" bgapi="true" />
Example : Enabling BGAPI over UART on BT121 @ 115200bps for BGScript usage
<uart baud="115200" flowcontrol="true" bgapi="false" />
4.6 <spi>
The XML element <spi> can be used to define the module's SPI configuration settings.
The attributes are explained in the table below.
Attribute
Description
Bluegiga – A Silicon Labs Company
Page 17 of 23
Attribute
Description
channel
Defines the SPI channel to configure
Values:
1: SPI channel 1
2: SPI channel 2
Example:
channel="2"
alternate
Defines the alternate pin configuration option for SPI
Values:
1: Alternative configuration 1 (Alt 1) (see module Data sheet for details)
2: Alternative configuration 2 (Alt 2) (see module Data sheet for details)
Default:
1
divisor
Defines the SPI divisor used for the clock in master mode.
Bitrate is 48MHz / (divisor )
Values:
2,4,8,16,32,64,128,256
Default:
2
Example:
divisor="16"
mode
Defines the SPI mode as master or slave
Values:
master: Use SPI as master
slave: Use SPI as slave
Default:
master
Example:
mode="master"
Bluegiga – A Silicon Labs Company
Page 18 of 23
Attribute
Description
slave_select
Defines whether to use SPI slave select (SS) pin or not
Values:
true: Use SPI slave select (SS) pin
false: Do not use SPI slave select (SS) pin
Default:
false
Example:
slave_select="true"
clock_idle_polarity Defines the logic level used when SPI clock is in idle state
Values:
low: Idle state for clock is a low level; active state is a high level.
high: Idle state for clock is a high level; active state is a low level.
Default:
low
Example:
clock_idle_polarity="low"
clock_edge
Defines the SPI clock edge
Values:
0: Serial output data changes on transition from idle clock state to active clock state.
1: Serial output data changes on transition from active clock state to idle clock state.
Default:
0
Example:
clock_edge="0"
endianness
Defines the SPI bit order
Options:
msb: most signigicant bit
lsb: least significant bit
Example: Configure SPI interface settings for the display on the DKBT Development kit:
<spi channel="1" alternate="2" clock_idle_polarity="high" clock_edge="1" endianness="msb" divisor="256" />
4.7 <i2c>
This XML element <i2c> can be used to define the module's I2C (Inter-Integrated Circuit) interface
configuration.
Bluegiga – A Silicon Labs Company
Page 19 of 23
Bitrate is calculated as 48MHz/prescaler/divider = bitrate
If you select I2C channel 2 you may only use Alt 2 setting, Alt 1 setting is not allowed. For details see
module data sheet.
Attribute
Value - Description
channel
Defines the I2C channel to configure
Values:
1: I2C channel 1
2: I2C channel 2
alternate
Defines the alternate configuration option for I2C.
Options:
1 : Alternative configuration 1 (Alt 1) (see Data sheet for details)
2 : Alternative configuration 2 (Alt 2) (see Data sheet for details)
prescaler
Defines the prescaler for baudrate generator
Range:
1-16
Default:
1
divider
Defines the divider for baudrate generator
Range:
1-256
Default:
64
Example: Enabling I2C
<i2c channel="1" alternate="1" prescaler="1" divider="64" />
Bluegiga – A Silicon Labs Company
Page 20 of 23
5 SPP Configuration file
For Bluetooth BR/EDR the SDP entries also need to be configured. The included SDP entries are defined in the
project configuration file. In addition the actual XML file needs to exist and in the examples provided these are
named SPP.xml in the project configuration file.
Contents
Description
<ServiceClassIDList>
This defines the UUID of the Bluetooth profile. For Bluetooth Serial Port Profile the
UUID must be 1101 and should not be changed.
<ServiceClass uuid128="
1101"/>
</ServiceClassIDList>
<BrowseGroupList>
<UUID16 value="1002"
/>
This section defines if this SDP entry is visible in the SDP browse group. Typically
you should not change this, but for some special applications you might want to
disable the browse group visibility.
</BrowseGroupList>
<ProtocolDescriptorList>
value="0100" means this profile is based on top of RFCOMM.
<Protocol>
value="03" means the next parameter defines the assigned RFCOMM channel
<UUID16 value="0100"
/>
value="05" defines the RFCOMM channel assigned for the profile
</Protocol>
Note:
<Protocol>
You can only change the RFCOMM channel number, but you must take care
that when in your application code you load the RFCOMM server you use
exactly the value defined in this XML file.
<UUID16 value="03"/>
<UINT8 value="05"/>
</Protocol>
<
/ProtocolDescriptorList>
<ServiceName>
This defines the service name for the given UUID. If you want to rename the
service you can modify the Bluetooth Serial Port to contain something else.
text="Bluetooth Serial
Port"
language_id="0100"
</ServiceName>
Bluegiga – A Silicon Labs Company
Page 21 of 23
6 DID Configuration file
This mandatory SDP entry defines the so called Device Information Profile, the attributes of which describe
certain characteristics of the module such as Vendor ID, Product ID, Version etc. For the Device Information
Profile there is a corresponding XML file, named DID.xml in the project configuration file.
The DID configuration file itself is a simple XML file consisting of nested structured elements, their attributes and
attribute values.
Contents
Description
<UINT16
value="
0200"/>
This MUST not be changed.
<UINT16
value="
0103"/>
<UINT16
value="
0201"/>
<UINT16
value="
0047"/>
0201 refers to vendor ID parameter and you can change the 0047 to your own vendor ID if you
have one assigned from USB Implementers Forum or Bluetooth SIG.
<UINT16
value="
0202"/>
<UINT16
value="
1234"/>
0202 refers to product ID parameter and if you have decided to use your own vendor ID you
can also use your own product ID as well and change 1234 to something else.
If case you are using the default vendor ID, this value must not be changed.
<UINT16
value="
0203"/>
<UINT16
value="
0000"/>
0202 refers to product version and you can replace the value 0000 with your own version
number.
<UINT16
value="
0204"/>
<UINT16
value="1"/>
This MUST not be changed.
<UINT16
value="
0205"/>
<UINT16
value="
0001"/>
0205 refers to the source of the vendor ID and it must tell if your own vendor ID is from
Bluetooth SIG or USB Implementers Forum
If you do not have your own vendor ID you can keep using 0047 unless you are making MFI
compliant devices in which can you must have your own ID.
0000: Source of vendor ID is USB Implementers Forum0001: Source of vendor ID is Bluetooth
SIG
Bluegiga – A Silicon Labs Company
Page 22 of 23
Contact information
Sales:
www.bluegiga.com
Technical support:
http://www.bluegiga.com/support/
Orders:
[email protected]
WWW:
http://www.bluegiga.com
SILICON LABS
Phone: +1 877.444.3032
400 West Cesar Chavez
Austin, TX 78701 USA
FINLAND OFFICE
Phone: +358 9 435 5060
Fax: +358 9 435 50660
Sinikalliontie 5A, 5th floor
02630 Espoo, Finland
Bluegiga – A Silicon Labs Company
Page 23 of 23