UG118: Blue Gecko Bluetooth® Smart
Profile Toolkit Developer's Guide
Bluetooth Smart services and characteristics are the basis of Bluetooth Smart 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. Bluetooth Smart 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
Smart services and characteristics, also known as the GATT database, in both easy human-readable and machine-readable formats. This guide walks you through the XML
syntax used in the Profile Toolkit and instructs you how to easily describe your own Bluetooth Smart services and characteristics, configure the access and security properties,
and how to include the GATT database as a part of the firmware.
KEY POINTS
• Understanding Bluetooth Smart profiles,
services, characteristics, attribute protocol
• Building the GATT database with the
Profile Toolkit
This guide also contains practical examples showing the use of both standardized Bluetooth and vendor-specific proprietary services. These examples provide a good starting
point for your own development work.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Understanding Profiles, Services, Characteristics and the Attribute Protocol
1. Understanding Profiles, Services, Characteristics and the Attribute Protocol
This section gives a basic explanation of Bluetooth profiles, services and characteristics and also explains how the Attribute protocol is
used in the data exchange between the GATT server and client. Links to further information regarding these subjects are also provided.
1.1 GATT Based Bluetooth Profiles
A Bluetooth 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 connection-establishment 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 inter-operable devices and applications.
Bluetooth SIG standardized profiles are available at:
https://developer.bluetooth.org/gatt/profiles/Pages/ProfilesHome.aspx.
1.2 Services
Services are collections 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.
Bluetooth SIG standardized service specifications are available at:
https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx.
1.3 Characteristics
A characteristic is a value used in a service, either to expose and/or exchange data and/or to 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.
Bluetooth SIG standardized characteristics are available at:
https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicsHome.aspx.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 1
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Understanding Profiles, Services, Characteristics and the Attribute Protocol
1.4 The Attribute Protocol
The Attribute protocol enables data exchange between the GATT server and the GATT client. The protocol also provides a set of operations, namely how to query, write, indicate or notify the data and/or control information between the two GATT parties.
GATT client
Attribute protocol
Operations:
Read
Write
Notify
Indicate
GATT server
(Heart Rate profile)
GAP service
UUID: 0x1800
HR measurement
Characteristic
UUID: 0x2A37
Device Information
service
UUID: 0x180A
Body Sensor
Location
Characteristic
UUID: 0x2A38
Heart Rate Service
UUID: 0x180D
Declaration
(notify property, no
security
requirements)
Characteristic
(2-6B of data
exposing HR
reading)
Descriptors
(enable/disable
notifications)
Figure 1.1. Profile, Service, and Characteristic Relationships
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 2
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Understanding Profiles, Services, Characteristics and the Attribute Protocol
Figure 1.2. Attribute Read Operation
Figure 1.3. Attribute Write Operation
Figure 1.4. Attribute Write without Response Operation
Figure 1.5. Attribute Indicate Operation
Figure 1.6. Attribute Notify Operation
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 3
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
2. Building the GATT Database with Profile Toolkit
This section of the document describes the XML syntax used in the Blue Gecko Bluetooth Smart Profile Toolkit and walks you through
the different options you can use when building Bluetooth Smart services and characteristics.
A few practical GATT database examples are also shown.
2.1 General Limitations
The table below shows the limitations of the GATT database supported by the Blue Gecko devices.
Item
Maximum number of characteristics
Maximum length of a type="user" characteristic
Limitation
Notes
64
All characteristics which do NOT have the
property const="true" are included in this
count.
512 bytes
These characteristics are handled by the
application which means that the amount of
RAM available for the application will limit
this.
If type="user is not used, then the maximum length of a characteristic is 255 B.
Note: Limited by Bluetooth specification
Maximum length of a const="true" characteristic
255 bytes
The amount of free flash available on the
device used defines this.
Maximum length of a const="false" characteristic
255 bytes
For every characteristic with the property
const="false" RAM will be allocated from
the Bluetooth Smart device for storing the
characteristic value.
Maximum number of attributes in a single
GATT database
254
A single characteristic typically uses 3-5 attributes.
2.2 <gatt>
The GATT database along with the services and characteristics must be described inside the XML attribute <gatt>.
Parameter
Description
─
─
Example: A GATT database definition
<?xml version="1.0" encoding="UTF-8" ?>
<gatt>
…
</gatt>
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 4
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
2.3 <service>
The GATT service definition is done with the XML attribute <service> and its parameters.
The table below describes the parameters which can be used for defining the related values.
Parameter
Description
uuid
Universally Unique Identifier. The UUID uniquely identifies a service. 16-bit values are used for the
services defined by the Bluetooth SIG and 128-bit UUIDs can be used for vendor specific implementations.
Range:
0x0000 – 0xFFFF: Reserved for Bluetooth SIG standardized services
0x00000000-0000-0000-0000-000000000000 - 0xFFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF: Reserved for vendor specific services.
id
The ID is used to identify a service within the service database and can be used as a reference from
other services (include statement). Typically this does not need to be used.
Value:
Any UTF-8 string
type
The type field defines whether the service is a primary or a secondary service. Typically this does not
need to be used.
Values:
primary: a primary service
secondary: a secondary service
Default: primary
advertise
This field defines if the service UUID is included in the advertisement data.
The advertisement data can contain up to 13 16-bity UUIDs or one (1) 128-but UUID.
Values:
true: UUID included in advertisement data
false: UUID not included in advertisement data
Default: false
Note: You can override the advertisement data with the GAP API in which case this is not valid.
Example: A Generic Access Profile (GAP) service definition

<service uuid="1800">
…
</service>
Example: A vendor specific service definition

<service uuid="25be6a60-2040-11e5-bd86-0002a5d5c51b">
…
</service>
Example: A Heart Rate service definition with UUID included in the advertisement data and ID “hrs”

<service uuid="180D" id="hrs" advertise=”true”>
…
</service>
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 5
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
Note: You can generate your own 128-bit UUIDs at: http://www.itu.int/en/ITU-T/asn1/Pages/UUID/uuids.aspx
2.3.1 <include>
A service can be included within another service by using the XML attribute <include>.
Parameter
Description
id
ID of the included service
Value:
ID of another service
Example: Including Hear Rate service within the GAP service

<service uuid="1800">

<include id="hrs” />
…
</service>
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 6
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
2.4 <characteristic>
All the characteristics exposed by a service are defined with the XML attribute <characteristic> and its parameters, which must be
used inside the <service> XML attribute tags.
The table below describes the parameters which can be used for defining the related values.
Parameter
Description
uuid
Universally Unique Identifier. The UUID uniquely identifies a characteristic.
16-bit values are used for the services defined by the Bluetooth SIG and 128-bit UUIDs can be used
for vendor specific implementations.
Range:
0x0000 – 0xFFFF: Reserved for Bluetooth SIG standardized characteristics.
0x00000000-0000-0000-0000-000000000000 to 0xFFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF :
Reserved for vendor specific characteristics.
id
The ID is used to identify a characteristic. The ID is used within a BGScript application to read and
write characteristic values or to detect if notifications or indications are enabled or disabled for a
specific characteristic.
When the project is compiled with the BGBuild compiler a text file called attributes.txt is generated.
This files contains the characteristic IDs and corresponding handle values.
Value:
Any UTF-8 string
Example: Adding Device name characteristic into GAP service

<service uuid="1800">

<characteristic uuid="2a00">
…
</characteristic>
…
</service>
Example: Adding a vendor specific characteristic into a vendor specific service with ID

<service uuid="25be6a60-2040-11e5-bd86-0002a5d5c51b">

<characteristic uuid="59cd69c0-2043-11e5-a717-0002a5d5c51b" id="mydata”>
…
</characteristic>
…
</service>
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 7
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
2.4.1 <properties>
The characteristics access and security properties are defined by the XML attribute <properties> and its parameters, which must be
used inside the <characteristic> XML attribute tags. A characteristic can have multiple properties at the same time.
The table below describes the parameters which can be used for defining the related values.
Parameter
Description
read
Characteristic can be read by a remote device.
Values:
true: Characteristic can be read
false: Characteristic cannot be read
Default: false
const
Characteristic has a constant value, which cannot be modified after programming.
The benefit of constant values is that no RAM is allocated for them leaving more RAM to the application.
Value:
true: Characteristic value is constant
false: Characteristic value is not constant
Default: false
write
Characteristic can be written by a remote device
Values:
true: Characteristic can be written
false: Characteristic cannot be written
Default: false
write_no_response
Characteristic can be written by a remote device. Write without response is not acknowledged over
the Attribute Protocol.
Values:
true: Characteristic can be written
false: Characteristic cannot be written
Default: false
notify
Characteristic has the notify property and characteristic value changes are notified over the Attribute
Protocol. Notifications are not acknowledged over the Attribute Protocol.
Values:
true: Characteristic has notify property.
false: Characteristic does not have notify property.
Default: false
indicate
Characteristic has the indicate property and characteristic value changes are indicated over the Attribute Protocol. Indications are acknowledged over the Attribute Protocol.
Values:
true: Characteristic has indicate property.
false: Characteristic does not have indicate property.
Default: false
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 8
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
Parameter
Description
authenticated_read
Reading the characteristic value requires an authentication. In order to read the characteristic with
this property the remote device has to be bonded using MITM protection and the connection must
be also encrypted.
Values:
true: Authentication is required
false: Authentication is not required
Default: false
encrypted_read
Reading the characteristic value requires an encrypted link. With iOS 9.1 and newer devices must
also be bonded at least with Just Works pairing.
Values:
true: Encryption is required
false: Encryption is not required
Default: false
bonded_read
Reading the characteristic value requires an encrypted link. Devices must also be bonded at least
with Just Works pairing.
Values:
true: Bonding and encryption are required
false: Bonding is not required
Default: false
authenticated_write
Writing the characteristic value requires an authentication. In order to write the characteristic with
this property the remote device has to be bonded using MITM protection and the connection must
be also encrypted.
Values:
true: Authentication is required
false: Authentication is not required
Default: false
encrypted_write
Writing the characteristic value requires an encrypted link. With iOS 9.1 and newer devices must also be bonded at least with Just Works pairing.
Values:
true: Encryption is required
false: Encryption is not required
Default: false
bonded_write
Writing the characteristic value requires an encrypted link. Devices must also be bonded at least
with Just Works pairing.
Values:
true: Bonding and encryption are required
false: Bonding is not required
Default: false
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 9
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
Parameter
Description
reliable_write
Allows using reliable write procedure to modify attribute, this is just a hint to GATT client. The Bluetooth stack always allows using reliable writes to be used to modify attributes.
Values:
true: Reliable write enabled
false: Reliable write disabled
Default: false
Example: Device name characteristic with const and read properties

<characteristic uuid="2a00">
<properties read="true" const="true" />
…
</characteristic>
Example: Device name characteristic with and read and write properties to allow the value to be modified by the remote device

<characteristic uuid="2a00">
<properties read="true" write="true" />
…
</characteristic>
Example: Heart Rate Measurement characteristic with notify property

<characteristic uuid="180D">
<properties notify="true" />
…
</characteristic>
Example: Characteristic with encrypted read propetry

<characteristic uuid="1234">
<properties read="true" encrypted_read="true" />
…
</characteristic>
Example: Characteristic with authenticated write property

<characteristic uuid="1234">
<properties write="true" authenticated_write="true" />
…
</characteristic>
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 10
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
2.4.2 <value>
The data type and length for a characteristic is defined with the XML attribute <value> and its parameters, which must be used inside
the <characteristic> XML attribute tags.
The table below describes the parameters which can be used for defining the related values.
Parameter
Description
length
Defines a fixed length for the variable or the maximum length if variable_length attribute is also
used.
Range:
0 – 255: Length in bytes
Default: 0
variable_length
Defines that the value is of variable length. The maximum length must also be defined with length
attribute.
Values:
true: Value is of variable length
false: Value has a fixed length
Default: false
type
Defines the data type
Values:
hex: Value type is hex
utf-8: Value is a string
user: When the characteristic type is marked as type="user" the application is responsible of initalizing the characteristic value and also providing it for example when read operation occurs. The Bluetooth stack does not initialize the value, bor automatically provide the value when it's being read.
When this is set the Bluetooth stack generates gatt_server_user_read_request or gatt_server_user_write_request which must be handled by the application.
Default: utf-8
Example: Heart Rate Measurement characteristic with notify property and fixed length of two (2) bytes.

<characteristic uuid="180D">
<properties notify="true" />
<value length="2" type="hex" />
…
</characteristic>
Example: A variable length vendor specific characteristic with maximum length of 20 bytes.

<characteristic uuid="59cd69c0-2043-11e5-a717-0002a5d5c51b" id="mydata”>
<properties notify="true" />
<value variable_length="true" length="20" type="hex" />
…
</characteristic>
Example: The value and length of a characteristic can also be defined by typing the actual value inside the <value> tags.
In the example below the value is “Blue Gecko BGM111” and the length is 17 bytes.

<characteristic uuid="2a00">
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 11
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
<properties read="true" const="true" />
<value>Blue Gecko BGM111</value>
</characteristic>
2.4.3 <description>
Characteristic user description values are defined with the XML attribute <description>, which must be used inside the <characteristic>
XML attribute tags.
Characteristic user description is an optional value, which is exposed to the remote device and can e.g. be used to provide a userfriendly description of the characteristic shown in the application's user interface.
The table below describes the parameters which can be used for defining the related values.
Parameter
Description
─
─
Example: Heart Rate Measurement characteristic with notify property and fixed length of two (2) bytes.

<characteristic uuid="180D">
<properties notify="true" />
<value length="2" type="hex" />
<description>Heart Rate Measurement</description>
</characteristic>
2.5 GATT Examples
Example: A full GAP service with device name and appearance characteristics as constant values with read property.
<?xml version="1.0" encoding="UTF-8" ?>
<gatt>

<service uuid="1800">

<characteristic uuid="2a00">
<properties read="true" const="true" />
<value>Blue Gecko</value>
</characteristic>

<characteristic uuid="2a01">
<properties read="true" const="true" />
<value type="hex">0768</value>
</characteristic>
</service>
</gatt>
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 12
UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide
Building the GATT Database with Profile Toolkit
Example: Full Device Information, Immediate Alert, and Link Loss services.
<?xml version="1.0" encoding="UTF-8" ?>
<gatt>

<service uuid="180A">

<characteristic uuid="2A29">
<properties read="true" const="true" />
<value>Silicon Labs</value>
</characteristic>

<characteristic uuid="2A24">
<properties read="true" const="true" />
<value>BGM111</value>
</characteristic>

<characteristic uuid="2A23">
<properties read="true" const="true" />
<value type="hex">000780000047</value>
</characteristic>
</service>

<service uuid="1803" advertise="true" >

<characteristic uuid="2a06" id="xgatt_lloss">
<properties read="true" write="true" />
<value length="1" />
</characteristic>
</service>

<service uuid="1802" advertise="true" >

<characteristic uuid="2a06" id="xgatt_alert">
<properties write_no_response="true" />
<value length="1" />
</characteristic>
</service>
</gatt>
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.4 | 13
Smart.
Connected.
Energy-Friendly.
Products
Quality
www.silabs.com/products
www.silabs.com/quality
Support and Community
community.silabs.com
Disclaimer
Silicon Laboratories intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software implementers using
or intending to use the Silicon Laboratories products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and
"Typical" parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Laboratories reserves the right to
make changes without further notice and limitation to product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the
included information. Silicon Laboratories shall have no liability for the consequences of use of the information supplied herein. This document does not imply or express copyright licenses
granted hereunder to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any Life Support System without the specific written consent
of Silicon Laboratories. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant
personal injury or death. Silicon Laboratories products are not designed or authorized for military applications. Silicon Laboratories products shall under no circumstances be used in
weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons.
Trademark Information
Silicon Laboratories Inc.® , Silicon Laboratories®, Silicon Labs®, SiLabs® and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, Clockbuilder®, CMEMS®, DSPLL®, EFM®, EFM32®,
EFR, Ember®, Energy Micro, Energy Micro logo and combinations thereof, "the world’s most energy friendly microcontrollers", Ember®, EZLink®, EZRadio®, EZRadioPRO®, Gecko®,
ISOmodem®, Precision32®, ProSLIC®, Simplicity Studio®, SiPHY®, Telegesis, the Telegesis Logo®, USBXpress® and others are trademarks or registered trademarks of Silicon Laboratories Inc. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. All other products or brand
names mentioned herein are trademarks of their respective holders.
Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
USA
http://www.silabs.com

Open as PDF

Similar pages: ETC IMAGELINK-50; ETC AMC3202

Read More