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