Silicon Labs BLUETOOTH DUAL MODE SOFTWARE Installation Manual

BLUETOOTH DUAL MODE SOFTWARE

GUIDE STARTED GETTING

1.4 Revision: Document

2020 December 02 Wednesday,

Silicon Labs

VERSION HISTORY

Date Edited

Comment

1.0

First version

1.1

Minor changes

1.2

Updated to match software release 1.1.1 build 168

1.3

Bluetooth stack technical features added

1.4

Renamed "Blue tooth Smart Ready" to "Bluetooth Dual Mode", "Bluetooth
Smart" to "Bluetooth Low Energy" and "Classic" to "BR/EDR" according to
the official Bluetooth SIG nomenclature

Silicon Labs

TABLE OF CONTENTS

1 Introduction 5
2 The Bluegiga Bluetooth Dual Mode software 6

2.1 The Bluegiga Bluetooth Dual Mode stack 6

2.2 Bluetooth Stack Features 7

2.3 The Bluegiga Bluetooth Dual Mode SDK 8

2.4 The BGAPITM serial protocol API 9

2.5 The BGLIBTM host library API 10

2.6 BGScriptTM scripting language API 11

2.7 BGAPITM vs. BGScriptTM 12

2.8 Profile ToolkitTM 13

2.9 BGBuild compiler 14

2.10 DFU tools 14

2.11 BGTool test application 14

3 Factory default configurations 15

3.1 Bluetooth module factory configuration 15

3.2 Development kit factory configuration 15

4 Getting started with the Bluetooth Dual Mode Software 16

4.1 Installing the Bluetooth Dual Mode SDK 16

4.2 Folder structure 17

4.3 Included tools 17

4.4 Built-in demos in the SDK 18

5 Walkthrough of the BGDemo application 19

5.1 Project configuration 20

5.2 Hardware configuration 21

5.3 Bluetooth services configuration 22

5.4 BGScript code 29

5.5 Compiling BGDemo application 33

5.6 Installing the firmware 34

5.7 Testing BGDemo application 34

6 Contact information 35

Silicon Labs

5

1 Introduction

This document explains the architecture and the APIs of the Bluegiga Bluetooth Dual Mode Software as well
the tools and components included in the Bluetooth Dual Mode Software Development Kit.

This document also walks you through the factory demo application preinstalled in the DKBT Bluetooth Dual
Mode development kit which is also included as one of the demo applications in the SDK.

Silicon Labs

6

2 The Bluegiga Bluetooth Dual Mode software

This section contains a short description of the Bluegiga Bluetooth Dual Mode software, the components, APIs
and the tools it includes.

2.1 The Bluegiga Bluetooth Dual Mode stack

The main components of the Bluegiga Bluetooth Dual Mode and stack are shown in the figure below. The
figure shows the layers the Bluetooth Dual Mode stack as well also shows the APIs that can be used to
interface to the Bluegiga Bluetooth Low Energy Stack.

Figure 1: Bluegiga Bluetooth Dual Mode Stack and APIs

Silicon Labs

7

2.2 Bluetooth Stack Features

Feature

Value

Simultaneous SPP/HID connections

up to 6

Simultaneous SCO connections

0

Simultaneous LE connections

Up to 7

Simultanous master / slave

Supported for BR/EDR
Not supported for LE
BR/EDR and LE connections are independent from each other

Combined BR/EDR and LE connections

Any combination of connections up to 6

Max data rate

1000 kbps over SPP (transparent UART mode)
700 kbps over SPP (BGAPI mode)
200 kbps (iAP2)

Bluetooth security features

Just works for BR/EDR and LE
Man-in-the-Middle protection for BR/EDR and LE
Legacy Pin code paring for BR/EDR
Out-of-Band pairing for LE

Max bondings

12

Supported Bluetooth BR/EDR profiles

GAP, SPP, DI, GATT over BR, HID device

Supported Bluetooth GATT profiles

Any

Apple iAP support

iAP2

Bluetooth QDIDs

Controller: 58852
Host: 70031
HID over BR: 90001

Silicon Labs

8

2.3 The Bluegiga Bluetooth Dual Mode SDK

The Bluegiga Bluetooth Dual Mode SDK is a software development kit, which enables the device and software
vendors to develop applications on top of the Bluegiga’s Bluetooth Dual Mode hardware and stack software.

The Bluetooth Dual Mode SDK supports multiple development models and the application developers can
decide whether the application software runs on a separate host (a low power MCU) or whether they want to
make fully standalone devices and execute their code on the MCU embedded in the Bluegiga Bluetooth Dual
Mode modules.

The SDK also contains documentation, tools for compiling the firmware, installing it into the hardware and lot
of example applications speeding up the development process.

The Bluegiga Bluetooth Dual Mode SDK includes the following APIs, components and tools:

• The Bluetooth Dual Mode stack as described in the previous chapter.

• BGAPITM is a binary serial protocol API to the Bluegiga Bluetooth Dual Mode stack over UART or SPI

interfaces. BGAPI is target for users, who want to use both Bluetooth BR/EDR and LE functionality
and use all the features in the Bluetooth Dual Mode stack form an external host such as a low power
MCU.

• BGLIBTM is a host library for external MCUs and implements a reference parser for the BGAPI serial
protocol. BGLIB is delivered in C source code as part of the Bluetooth Dual Mode SDK and it can be
easily ported to various processor architectures.

• BGScriptTM interpreter and scripting language allow applications to be developed into the Bluetooth
Dual Mode modules built-in MCU. It allows simple end user applications or enhanced functionality to
be developed directly into the Bluetooth Dual Mode module which means no external host MCU is
necessarily needed. BGScript applications can be executed at the same time as the BGAPI is used,
allowing the possibility to implement some functionality on the Bluetooth module and some on the
host.

• Profile Toolkit

TM

is a simple XML based description language which can be used to easily and quickly

develop GATT based service and characteristic databases for the Bluetooth Low Energy module.

• BGBuild compiler is a free-of-charge compiler that compiles the Bluetooth Dual Mode Stack, the
BGScript application and the Bluetooth GATT services into the firmware binary that can be installed to
the Bluetooth Dual Mode modules.

• BGTool is a graphical user interface application and a developer tool, which allows the Bluetooth Low
Energy module to be controller over the host interface using the BGAPI serial protocol. BGTool is a
useful tool for testing the Bluetooth Low Energy module and evaluating it’s functionality and APIs.

• DFU Tools are also included as part of the SDK allowing the firmware to be updated over the UART
and SPI interfaces.

Silicon Labs

9

2.4 The BGAPITM serial protocol API

The BGAPI is a serial protocol allows external hosts to interface to the Bluetooth Dual Mode modules over
UART or SPI interfaces. The BGAPI serial protocol is a lightweight and well defined binary protocol which
allows command and data to be sent to the Bluetooth Dual Mode module and it also provides a way to receive
responses and events and data from the module.

Figure 2: Architecture when using BGAPI and BGLIB

The BGAPI serial protocol provides access for example to the following layers in the Bluetooth Dual Mode
stack:

• BT GAP – BT GAP provides access to basic Bluetooth BR/EDR features, like device discovery and
connection establishment.

• LE GAP - LE GAP provides access to basic Bluetooth LE features, like device advertisement,
discovery and connection establishment.

• Security manager – Security manager is used to configure the local devices security features and
establish secure connections

• RFCOMM – RFCOMM provides basic serial data transmission over Bluetooth RD/EDR.

• iAP – iAP provides basic serial data transmission to Apple iOS devices using Bluetooth BR/EDR. iAP

is only available to Apple MFI licenses and not included in the standard SDK.

• Hardware – Access to local hardware features and interfaces like SPI, I2C, GPIO and ADC

• Persistent Store - A data storage that allows data to be stored to and read from the internal flash

• System - Local device's status and management functions

Silicon Labs

10

2.5 The BGLIBTM host library API

BGLIBTM host library is a reference implementation of the BGAPI serial protocol parser and it’s provided in an
ANSI C source code in the Bluetooth Dual Mode SDK.

BGLIB host library abstracts the complexity of the BGAPI serial protocol and provides instead high level C
functions and call-back handlers to the application developer, which makes the application development
easier and faster.

BGLIB library can be ported to various host systems ranging from low cost MCUs to devices running Linux,
Windows or OSX.

Figure 3: BGLIB API example

Silicon Labs

11

2.6 BGScriptTM scripting language API

BGScript is a simple BASIC-style programming language that allows end-user applications to be embedded to
the Bluegiga Bluetooth Dual Mode modules. Although being a simple and easy-to-learn programming
language BGScript does provide features and functions to create fairly complex and powerful applications and
it provides access to all the same APIs as the BGAPI serial protocol.

BGScript is fully event based programming language and code execution is started when events such as
system start-up, Bluetooth connection, I/O interrupt etc. occur.

BGScript applications are developed with Bluegiga’s free-of-charge Bluetooth Dual Mode SDK and the
BGScript applications are executed in the BGScript Virtual Machine (VM) that is part of the Bluegiga Bluetooth
Dual Mode software. The Bluetooth Dual Mode SDK comes with all the necessary tools for code editing and
compilation and also the needed tools for installing the complied firmware binary to the Bluegiga Bluetooth
Dual Mode modules.

BGScript applications can also be used at the same time as BGAPI and they can be for example used to
automate some simple actions.

Figure 4: Bluegiga BGScript

Figure 5: A simple BGScript code example

Silicon Labs

12

2.7 BGAPITM vs. BGScriptTM

This section describes the differences between using BGAPI and BGScript. In brief the difference is:

• BGScript is our custom scripting language used for on-module applications. BGScript applications
only run on Bluegiga modules and dongles.

• BGAPI is a custom serial protocol used to externally control the modules over the host interface and
BGLIB is an ANSI C reference implementation of the BGAPI serial protocol and only runs outside of
our modules and dongles.

So the main difference between BGScript and BGLIB is that BGScript allows you to run an application right on
the Bluetooth module, whereas BGLIB uses the BGAPI serial protocol API to send commands and receive
events from an external device - typically a microcontroller. Note however that BGScript and BGLIB implement
the exact same functionality. Every BGScript command, response, and event has a counterpart in the BGAPI
serial protocol and BGLIB host library.

One other thing to keep in mind is that BGScript has some performance penalties compared to external API
control due to the fact that BGScript is an interpreted scripting language and requires extra overhead in order
to use. It makes the Bluetooth module do the work that could otherwise be done elsewhere. If you are trying to
achieve maximum performance or you have an application which is fairly complex (lots of fast timers,
interrupts, or communicating with many external sensors over I2C or SPI for example), it is often a good idea
to use a small external microcontroller and BGLIB/BGAPI instead.

Question

BGAPITM

BGScriptTM

An external host needed?

Yes

No

Host interface

UART

No separate host needed

Bluetooth API

BGAPI serial protocol

or BGLIB host API

BGScript API

Peripheral interface APIs and

support

Host dependent (*

APIs for UART, SPI, I2C, GPIO, ADC and PS

store

Custom peripheral interface

drivers

Can be developed to

the host

Peripheral drivers are part of the Bluegiga

Bluetooth Dual Mode stack

RAM available for application

Host dependent

TBD

Flash available for application

Host dependent (**

~12 kB

Execution speed

Host dependent

TBD

Application development SDK

Host dependent +

BGAPI and BGLIB

Bluegiga Bluetooth Dual Mode SDK

Bluetooth firmware / application

updates

DFU over UART

DFU over UART

Figure 6: BGAPI vs. BGScript

*) The Bluetooth Low Energy modules peripheral interfaces are still available via BGAPI commands and can
be used to extend the host MCUs I/Os.