Silicon Labs BLUETOOTH LOW ENERGY PROFILE TOOLKIT User Manual
BLUETOOTH LOW ENERGY PROFILE
TOOLKIT
GUIDE DEVELOPER
2020 December 2 Wednesday,
3.12 Version
Table of Contents
1 Version history _________________________________________________________________________ 4
2 Introduction ___________________________________________________________________________ 5
2.1 Understanding Profile, Services, Characteristics and the Attribute Protocol _____________________ 5
2.1.1 GATT-Based Bluetooth Profiles ________________________________________________ 5
2.1.2 Services ___________________________________________________________________ 5
2.1.3 Characteristics ______________________________________________________________ 5
2.1.4 The Attribute Protocol ________________________________________________________ 6
2.1.5 The Profile Toolkit ___________________________________________________________ 7
3 GATT Database file (gatt.xml) _____________________________________________________________ 8
3.1 Generic GATT Limitations ___________________________________________________________ 8
3.2 Defining Services __________________________________________________________________ 9
3.2.1 <service>: Service Definition element ____________________________________________ 9
3.2.2 <description>: Service Description element ______________________________________ 10
3.2.3 <include>: Service Include element ____________________________________________ 10
3.3 Defining Characteristics ____________________________________________________________ 11
3.3.1 <characteristic>: Characteristic Definition element ________________________________ 11
3.3.2 <properties>: Characteristic Properties element __________________________________ 12
3.3.3 <value>: Characteristic Value Definition element __________________________________ 14
3.3.4 <description>: Characteristic User Description element ____________________________ 16
3.3.5 <aggregate>: Characteristic Aggregated Format Definition element ___________________ 16
3.3.6 <descriptor>: Characteristic Descriptor Definition element __________________________ 16
3.3.7 Notes ____________________________________________________________________ 17
3.4 Examples _______________________________________________________________________ 18
Silicon Labs Page of 3 21
1 Version history
Version Comments
2.1 v1.2 SW compatibility changes; USB set inactive (false) by default, ...)
2.2 v.1.1 beta 2 updates added
2.3 Updated firmware compile and installation instructions
2.4 Improved hardware.xml and gatt.xml examples and documentation
2.5 UART packet mode documentation updated
2.6 Updated compilation and installation instructions
2.7 Config.xml documentation improved and example added
2.8 <port> description improved
2.9 Updated with the latest SW 1.1 release (build 71). BLE113 (project.xml) is also added
3.0
3.1 Improved examples
3.2 Improved examples
3.3 Improved the user characteristic property documentation and an example added
3.4 Characteristic default type description added
3.5 Minor edits, textual style aligned, terminology check, GATT database limitations added for BLExxx
and BT121 modules
3.6 encrypted_write and encrypted_read plus other minor clarifications added.
3.7 Attribute operation figures corrected
3.8 GATT limitations documentation corrected.
Chapter 3.3.7 added
3.9 Corrected description of attribute in <properties> section
write_no_response
3.10 Added note about parameter, added limitation note for ,
advertise encrypted_write encrypted_read
and parameters.
encrypted_notify
3.11 Added note about new capabilities of service parameter in BT121 modules.
id
3.12
Project.xml, Config.xml, Hardware.xml sections are moved to the Bluetooth Low Energy
Module Configuration Guide document.
Renamed "Bluetooth 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 Page of 4 21
2 Introduction
Bluetooth Low Energy services and characteristics are the basis of Bluetooth low-energy data exchange. They
are used to describe the structure, access type, and security properties of the data exposed by a device, such
as a heart-rate monitor. The BLE services and characteristics have a well-defined and structured format, and
they can be easily described using XML mark-up language.
The Profile Toolkit is an XML-based mark-up language for describing the Bluetooth Low Energy services and
characteristics, also known as the GATT database, in an easy human-readable and machine-readable format.
The Bluetooth Low Energy Profile Toolkit Developer Guide walks you through the XML syntax with the Profile
Toolkit and instructs you how to easily describe your own Bluetooth Low Energy services and characteristics,
configure the access and security properties, and include the GATT database as a part of the firmware.
This guide also contains practical examples of both standardized Bluetooth, as well vendor proprietary services,
which can serve as an example for your own development.
2.1 Understanding Profile, Services, Characteristics and the Attribute
Protocol
2.1.1 GATT-Based Bluetooth Profiles
The profile specifies the structure in which data is exchanged. The profile defines elements, such as services
and characteristics, used in a profile, but it may also contain definitions for security and connectionestablishment parameters. Typically a profile consists of one or more services which are needed to accomplish
a high-level use case, such as heart-rate or cadence monitoring. Standardized profiles allow device and
software vendors to build interoperable devices and applications.Bluetooth SIG standardized profiles are
defined in profiles specifications.
These are available at: https://developer.bluetooth.org/gatt/profiles/Pages/ProfilesHome.aspx
2.1.2 Services
Services are a collection of data composed of one or more characteristics used to accomplish a specific
function of a device, such as battery monitoring or temperature data, rather than a complete use case.
Standardized Bluetooth SIG are defined in service specifications, which are available at: https://developer.
bluetooth.org/gatt/services/Pages/ServicesHome.aspx
2.1.3 Characteristics
A characteristic is a value used in a service, either to (1) expose and/or exchange data and/or (2) control
information. Characteristics have a well-defined, known format. They also contain information about how the
value can be accessed, what security requirements must be fulfilled, and ,optionally, how the characteristic
value is displayed or interpreted. Characteristics may also contain descriptors that describe the value or permit
configuration of characteristic data indications or notifications.
Standardized characteristics are defined in the Characteristic Specification, which are available at:
https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicsHome.aspx
Silicon Labs Page of 5 21
2.1.4 The Attribute Protocol
The Attribute protocol enables the data exchange between the GATT server and the GATT client. The protocol
also provides a set of operations: how to query, write, indicate or notify the data and/or control information
between the two GATT parties.
Figure: Read operation
Figure: Write operation
Figure: Write without response operation
Figure: Attribute indication
Figure: Attribute notification
Silicon Labs Page of 6 21
2.1.5 The Profile Toolkit
The Low Energy Profile Toolkit is a simple set of tools, which can be used to describe GATT based
Bluetooth
Low Energy and . The Profile Toolkit consists of a simple XML based
Bluetooth services characteristics
description language and templates, which can be used to describe the devices GATT database. The Profile
Toolkit also contains a compiler, which converts the XML in to binary format and generates API to access the
characteristic values.
Figure: A profile toolkit example of GAP service
Silicon Labs Page of 7 21
Loading...