Silicon Labs AN980 User Manual

AN980: BLUETOOTH LOW ENERGY SDK

Developing your 1st Bluetooth Low Energy Application

Wednesday, 02 December 2020
Version 2.2

Silicon Labs

VERSION HISTORY

Version

Comment

1.0

First version

1.1

Project and Hardware configuration added

1.2

BGScript and firmware update instructions added

1.3

Better screen captures and BLEGUI example added

1.4

Bluetooth LE description updated

1.6

Minor updates

1.7

Updated compile and installation instructions

1.8

Chapter 3 updated

1.9

Chapter 4 updated

2.0

Minor changes

2.1

Updated notes about sleep oscillator setting, which should be configured in
the hardware configuration file

2.2

Renamed "Bluetooth Smart" to "Bluetooth Low Energy" according to the
official Bluetooth SIG nomenclature

Silicon Labs

TABLE OF CONTENTS

1 Introduction ....................................................................................................................................................4

2 What is Bluetooth Low Energy Technology? ...........................................................................................5

3 Typical Bluetooth 4.0 Application Architecture .......................................................................................6

3.1 Overview ...............................................................................................................................................6

3.2 What is a Profile? ..................................................................................................................................7

3.3 What Is a Service? ................................................................................................................................8

3.4 What is a Characteristic? ......................................................................................................................9

3.5 Relationship Between Profiles, Services and Characteristics ........................................................... 10

4 Introduction to the Bluegiga Bluetooth Low Energy Software ............................................................ 11

4.1 The Bluetooth Low Energy Stack ...................................................................................................... 11

4.2 The Bluetooth Low Energy SDK ........................................................................................................ 11

4.3 The BGAPI Protocol .......................................................................................................................... 13

4.4 The BGLib Host Library ..................................................................................................................... 14

4.5 BGScriptTM Scripting Language ......................................................................................................... 15

4.6 The Profile Toolkit .............................................................................................................................. 16

5 Implementation of “BGDemo” Sensor ................................................................................................... 17

5.1 Installing the Tools ............................................................................................................................. 18

5.2 Creating a Project .............................................................................................................................. 19

5.3 Hardware Configuration ..................................................................................................................... 20

5.4 Building a GATT Database with Profile Toolkit .................................................................................. 21

5.4.1 Generic Access Profile Service ..................................................................................................... 21

5.4.2 Device ID ....................................................................................................................................... 23

5.4.3 A Manufacturer Specific Service.................................................................................................... 24

5.5 Writing BGScript Code ....................................................................................................................... 25

5.6 Compiling and Installing the Firmware .............................................................................................. 27

5.6.1 Using BLE Update tool .................................................................................................................. 27

5.6.2 Compiling Using bgbuild.exe ......................................................................................................... 29

5.6.3 Installing the firmware with TI’s Flash Tool .................................................................................... 30

6 Testing the BGDemo Sensor ................................................................................................................... 31

6.1 Using BLEGUI ................................................................................................................................... 31

6.1.1 Discovering the BGDemo Sensor .................................................................................................. 31

6.1.2 Establishing a Connection ............................................................................................................. 32

6.1.3 Making GATT Service Discovery ................................................................................................... 33

6.1.4 Reading the Serial Number String ................................................................................................. 34

6.2 Reading and Writing the Manufacturer Specific Service ................................................................... 36

Silicon Labs

Page 4 of 38

1 Introduction

This application note discusses how to start developing Bluetooth Low Energy applications using Bluegiga
Bluetooth Low Energy modules and BLED112 Bluetooth Low Energy USB dongle. The application note
contains a practical example of how to build Bluetooth Low Energy GATT based services with the profile
toolkit, how to make a standalone sensor device using BGScript programming language.

Silicon Labs

Page 5 of 38

2 What is Bluetooth Low Energy Technology?

Bluetooth Low Energy (Bluetooth 4.0) is a new, open standard developed by the Bluetooth SIG. It’s targeted

to address the needs of new modern wireless applications such as ultra-low power consumption, fast
connection times, reliability and security. Bluetooth Low Energy consumes 10-20 times less power and is able
to transmit data 50 times quicker than classical Bluetooth solutions.

Link: How Bluetooth low energy technology works?
Bluetooth Low Energy is designed for new emerging applications and markets, but it still embraces the very

same benefits we already know from the classical, well established Bluetooth technology:

• Robustness and reliability - The adaptive frequency hopping technology used by Bluetooth Low
Energy allows the device to quickly hop within a wide frequency band, not just to reduce interference
but also to identify crowded frequencies and avoid them. On addition to broadcasting Bluetooth Low
Energy also provides a reliable, connection oriented way of transmitting data.

• Security - Data privacy and integrity is always a concern is wireless, mission critical applications.
Therefore Bluetooth Low Energy technology is designed to incorporate high level of security including
authentication, authorization, encryption and man-in-the-middle protection.

• Interoperability - Bluetooth Low Energy technology is an open standard maintained and developed
by the Bluetooth SIG. Strong qualification and interoperability testing processes are included in the
development of technology so that wireless device manufacturers can enjoy the benefit of many
solution providers and consumers can feel confident that equipment will communicate with other
devices regardless of manufacturer.

• Global availability - Based on the open, license free 2.4GHz frequency band, Bluetooth Low Energy
technology can be used in world wide applications.

There are two types of Bluetooth 4.0 devices:

• Bluetooth 4.0 single-mode devices that only support Bluetooth Low Energy and are optimized for
low-power, low-cost and small size solutions.

• Bluetooth 4.0 dual-mode devices that support Bluetooth Low Energy and BR/EDR technologies and
are interoperable with all the previously Bluetooth specification versions.

Key features of Bluetooth Low Energy wireless technology include:

• Ultra-low peak, average and idle mode power consumption

• Ability to run for years on standard, coin-cell batteries

• Low cost

• Multi-vendor interoperability

• Enhanced range

Bluetooth Low Energy is also meant for markets and applications, such as:

• Automotive

• Consumer electronics

• Smart energy

• Entertainment

• Home automation

• Security & proximity

• Sports & fitness

Silicon Labs

Page 6 of 38

3 Typical Bluetooth 4.0 Application Architecture

3.1 Overview

Bluetooth Low Energy applications typically have the following architecture:

• Server
Service is the device that provides the information, so these are typically the sensor devices, like

thermometers or heart rate sensors. The server exposes implements services and the services
expose the data in characteristics.

• Client
Client is the device that collects the information for one or more sensors and typically either displays it

to the user or passes it forward. The client devices typically do not implement any service, but just
collect the information from the service provided by the server devices. Clients are typically devices
like mobile phones, tablets and PCs.

The figure below shows the relationship of these two roles.

Client Server

Service 1

Servic e 2

Service n

Figure 1: Bluetooth Low Energy device roles

Silicon Labs

Page 7 of 38

3.2 What is a Profile?

Profiles are used to describe devices and the data they expose and also how these devices behave. The data
is described by using services, which are explained later and a profile may implement single or multiple
services depending on the profile specification. For example a Heart Rate Service specification mandates that
the following services need to be implemented:

• Heart Rate Service

• Device Information Service

Profile specifications might also define other requirements such as security, advertisement intervals and
connection parameters.

The purpose of profile specifications is to allow device and software vendors to build standardized
interoperable devices and software. Standardized profiles have globally unique 16-bit UUID, so they can
easily identify.

Profiles are defined in profiles specifications, which are available at:

https://www.bluetooth.com/specifications/

Silicon Labs

Page 8 of 38

3.3 What Is a Service?

Services such as a Heart Rate service describes what kind of data a device exposes, how the data can be
accessed and what the security requirements for that data are. The data is described using characteristics
and a service may contain single or multiple characteristics and some characteristics might be optional where
as some are mandatory.

Two types of services exist:

• Primary Service

A primary service is a service that exposes primary usable functionality of this device. A primary service
can be included by another service.

• Secondary Service

A secondary service is a service that is subservient to another secondary service or primary service. A
secondary service is only relevant in the context of another service.

Just like the profiles also the services are defined in service specifications and the Bluetooth SIG standardized
services are available at:

https://www.bluetooth.com/specifications/gatt/services

Every service standardized by the Bluetooth SIG has a globally unique 16-bit UUID so just like the profiles
also the services can be easily identified.

However not every use case can be fulfilled by the standardized service and therefore the Bluetooth Low
Energy specification enables device vendors to make proprietary service. The proprietary services are
described just as the standardized services, but 128-bit UUIDs need to be used instead of use 16-bit UUIDs
reserved for the standard services.

Silicon Labs

Page 9 of 38

3.4 What is a Characteristic?

Characteristics are used to expose the actual data. Characteristic is a value, with a known type (UINT8,
UINT16, UTF-8 etc.), a known presentation format. Just like profiles and services also characteristics have
unique UUID so they can be easily identified and the standardized characteristics use 16-bit UUIDs and
vendor specific characteristics use 128-bit UUIDs.

Characteristics consist of:

• Characteristic Declaration describing the properties of characteristic value such as:

• characteristic (UUID)

• Access control (read, write, indicate etc.)

• Characteristic value handle (unique handle within a single device)

• Characteristic Value containing the value of a characteristic (for example temperature reading).

• Characteristic Descriptor(s) which provide additional information about the characteristic (characteristic

user description, characteristic client configuration, vendor specific information etc.).

Figure 2: Characteristic structure

Standardized characteristics are defined in Characteristic Specification and the standardized characteristics
are available at:

https://www.bluetooth.com/specifications/gatt/characteristics

Silicon Labs

Page 10 of 38

3.5 Relationship Between Profiles, Services and Characteristics

The illustration below shows the relationship between profiles, services and characteristics.

Health thermometer profile

GAP service

(UUID: 1800)

Health thermometer

service

(UUID: 1809)

Device information

service

(UUID:180A)

Health thermometer service

(UUID: 1809)

Temperature measurement

(UUID: 2A1C)

Mandatory

Temperature type

(UUID: 2A1D)

Optional

Intermediate temperature

(UUID: 2A1E)

Optional

Measurement interval

(UUID: 2A21)

Optional

Temperature measurement

Handle : 1

UUID: 2803 (declaration)

Data:

Data UUID: 2A1D

Data Handle: 2

Data Properties: Indicate

Handle : 2

UUID: 2A1C (attribute value)

Data:
Flags: <uint8>
Measurement value:<float>

Time stamp: <date_time>

Temperature type: <temperature_type>

Handle: 3

UUID: 2903

Client characteristics configuration

Properties: Read, write

Figure 3: Health thermometer profile

Silicon Labs

Page 11 of 38

4 Introduction to the Bluegiga Bluetooth Low Energy Software

The Bluegiga Bluetooth Low Energy Software enables developers to quickly and easily develop Bluetooth Low
Energy applications without in-depth knowledge of the Bluetooth Low Energy technology. The Bluetooth Low
Energy Software consist of two parts:

• The Bluetooth Low Energy Stack

• The Bluetooth Low Energy Software Development Kit (SDK)

4.1 The Bluetooth Low Energy Stack

The Bluetooth Low Energy stack is a fully Bluetooth 4.0 single mode compatible software stack implementing
slave and master modes, all the protocol layers such as L2CAP, Attribute Protocol (ATT), Generic Attribute
Profile (GATT), Generic Access Profile (GAP) and security and connection management.

The Bluetooth Low Energy is meant for the Bluegiga Bluetooth Low Energy products such as BLE112,
BLE113 and BLED112 and it runs on the embedded MCU used in these products, so no host is needed.

4.2 The Bluetooth Low Energy SDK

The Bluetooth Low Energy SDK is a software development kit, which enables the device and software
vendors to develop products on top of the Bluegiga’s Bluetooth Low Energy hardware and software.

The Bluetooth Low Energy SDK supports multiple development models and the software 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 Low
Energy modules. The SDK also contains documentation, tools for compiling the firmware, installing it into the
hardware and lot of example application speeding up the development process.

Fully standalone applications can be developed using a simple scripting language called BGScriptTM. Several
profiles and examples are also offered as a part of the Bluetooth Low Energy Software in order to easily
develop the Bluetooth Low Energy compatible end products.

Bluegiga’s Bluetooth Low Energy Software provides a complete development framework for Bluetooth Low
Energy application implementers.

Silicon Labs

Page 12 of 38

Figure 4: Bluetooth Low Energy Software

The Bluetooth Low Energy Software architecture is illustrated, and it consists of the following components

• The Bluetooth Low Energy stack implementing the Bluetooth Low Energy protocol

• BGAPI

TM

APIs that enable the software developers to interface to the Bluetooth Low Energy Stack

• BGScriptTM Virtual Machine (VM) and scripting language which enable application code to be
developed and executed directly on the Bluetooth Low Energy hardware

• BGLibTM lightweight host library which implements the BGAPI binary protocol and parser and is target
for applications where separate host processor is used to interface to the Bluetooth Low Energy
modules over UART or USB.

• Profile ToolkitTM is a GATT based profile development tool that enables software developers quickly
and easily to describe the Bluetooth Low Energy profiles, services and characteristics using simple
XML templates

Each of these components are described in more detail in the following chapters.