Silicon Labs UG365 User guide

Brand: Silicon Labs

Model: UG365

Type: User guide

silabs.com | Building a more connected world. Rev. 0.1

KEY POINTS

• GATT Configuration user interface re-

view.

• Using the GATT Configurator to creat

and configure the GATT database.

• Typical GATT Configurator Use Cases

UG365: GATT Configurator User’s Guide

This guide provides the information needed to effectively use the

Bluetooth GATT Configurator provided as a part of Simplicity

Studio. The GATT Configurator is an intuitive interface providing

access to all the Profiles, Services, Characteristics, and

Descriptors as defined in the Bluetooth specification. It also

supports creating, importing, or exporting custom GATT profiles

for Bluetooth applications. This guide reviews the user interface

and covers some most common uses of the Configurator.

UG365: GATT Configurator User's Guide

GATT Configurator Overview

silabs.com | Building a more connected world. Rev. 0.1 | 1

1 GATT Configurator Overview

The GATT Configurator is composed of four different sections that allow you to work with the various components and aspects of the

interface. The Source section, Custom GATT section, Settings section, and Tools section are shown in the following figure. This chap-

ter reviews each section.

Figure 1-1. GATT Configurator Interface

Source

Custom GATT

Settings

Tools

UG365: GATT Configurator User's Guide

GATT Configurator Overview

silabs.com | Building a more connected world. Rev. 0.1 | 2

1.1 Source Section

The Source section displays a list of predefined Profiles, Services, Characteristics, and Descriptors. These items can be filtered based

on their source using the checkboxes. Tabs allow you to switch between different lists. As shown in the following figure, the pane below

the list displays textual information about the latest selection.

Note: This pane is shared by the Source and the Custom GATT sections. It can be used to find more information about a selected item

in the Source section or in the Custom GATT section.

The top of the Source section shows the name of the configurator file and the Bluetooth SDK version. An * in the configurator file name

indicates there are unsaved changes. Clicking the icon gives you more information about the current framework.

Figure 1-2. Source Section

UG365: GATT Configurator User's Guide

GATT Configurator Overview

silabs.com | Building a more connected world. Rev. 0.1 | 3

1.2 Custom GATT Section

The Custom GATT section displays the items present in the current configuration file. This includes a Custom GATT Profile, Services,

Characteristics, and Descriptors displayed as a hierarchical list. The order of items shown here reflect the order in which they exist in

the GATT database. You can select an item here to see its properties and configuration.

Figure 1-3. Custom GATT Section

Note: Unsaved changes will be shown in this section, so this view does not necessarily reflect the true state of the GATT database.

UG365: GATT Configurator User's Guide

GATT Configurator Overview

silabs.com | Building a more connected world. Rev. 0.1 | 4

1.3 Settings Section

The Settings section allows you to configure the properties of items such as Profiles, Services, Characteristics and Descriptors that are

present in the Custom GATT section. Selecting an item populates the relevant configuration options such as the name, ID, properties

and capabilities. Any changes made in this section reflect immediately for the selected item.

Figure 1-4. Settings Section

Note: Unsaved changes will be shown in this view, so changes made in this view does not necessarily reflect the true state of the

GATT database.

1.4 Tools Section

Tools allow you to create new items, duplicate, remove or reorder items, or import a new GATT database. Controls in this menu get

activated when you select a relevant item in the Custom GATT view section. For example, you can only create a new Descriptor when

a Characteristic is selected in the Custom GATT view. Similarly, reordering options will not work if there is only one item at that level.

The purpose of the control appears when the cursor is hovered over it.

Figure 1-5. Tools Section

UG365: GATT Configurator User's Guide

GATT Configurator Overview

silabs.com | Building a more connected world. Rev. 0.1 | 5

Generate is used to generate GATT database xml file (gatt.xml) as well as the associated source files (gatt_db.c/.h).

The Import control ( ) imports an existing GATT database using an .xml file or a .bgproj file.

Note: Importing a gatt.xml file using the Import function will overwrite the current custom GATT data. This message also appears as

a prompt when you click the Import control. The gatt.xml structure and notation is described in UG118: Blue Gecko Blue-

tooth® Profile Toolkit Developer's Guide.

1.4.1 Difference between Generate and Save

Save: This saves any changes made in the GATT Configurator to the “.isc” file of the project. Unsaved changes are indicated by an

asterisk ( * ) next to the name of the .isc file. Changes can be saved by pressing “Ctrl + S” or clicking Save under the File menu. Use

the Save function to save changes that you intend to keep but do not need to reflect yet in the GATT database or GATT source files.

Generate: When you click Generate, changes are made to the GATT database (gatt.xml) and source file (gatt_db.c/.h). Further gener-

ations will overwrite the changes to these files. Additionally, it can also create files and overwrite them if they have been modified (for

example. init_mcu*.c). If you have made modifications to such files, make sure to uncheck the files so that they do not get overwritten.

A prompt is displayed as shown below giving you the option of selecting specific files that need to be overwritten. Generating does not

save the changes to the “.isc” file.

Figure 2-6. Overwrite prompt after Generation

As a best practice, always first save the changes and then generate.

UG365: GATT Configurator User's Guide

Use Cases

silabs.com | Building a more connected world. Rev. 0.1 | 6

2 Use Cases

This chapter describes common tasks performed with the GATT Configurator.

2.1 Drag and Drop

To include predefined items from the source list in your application, drag and drop the item from the Source Section to the Custom

GATT section. When you drag and drop a profile or a service, all the Characteristics and Descriptors in the levels underneath get in-

cluded automatically. Maintaining the hierarchical structure, Descriptors can only be included under Characteristics, which go under

Services.

Figure 2-1. Drag and Drop a Profile to Include all the Items

Within the Custom GATT section, drag and drop can be used to reorder items. This saves the trouble of including and configuring the

item again. Similarly, an item can be duplicated and moved around in the section.

2.2 Create New Item

New items can be created from the tools menu. New Services get created at the bottom whereas Characteristics and Descriptors are

created under the selected item. Descriptors can only be created when you have selected a Characteristic. When you select the Profile

and create a new Characteristic, it gets created under the first Service.

Figure 2-2. Create New Item

UG365: GATT Configurator User's Guide

Use Cases

silabs.com | Building a more connected world. Rev. 0.1 | 7

When a new item is selected, the Settings section displays the default properties of the item. Here the item can be configured as per

the requirements.

Figure 2-3. Default Values for a Newly Created Characteristic

The application gets local access to the GATT database using the characteristic ID. You can enter this by selecting the checkbox and

entering a unique ID. Upon generation, this ID gets a macro in the gatt_db.h file as shown below.

extern const struct bg_gattdb_def bg_gattdb_data;

#define gattdb_service_changed_char 3

#define gattdb_device_name 7

#define gattdb_ota_control 21

#define gattdb_new_characteristic 24

UUID or Universally Unique identifier are numbers used to identify Services, Characteristics, and Descriptors uniquely. There are two

types of UUID:

1. 16 bit: These 16 bit UUIDs are predefined by the Bluetooth SIG. Being short they are energy and memory efficient. For example,

the Blood Pressure Service has a UUID of 0x1810 whereas the Battery level Characteristic has a UUID of 0x2A19.

2. 128 bit: This overcomes the limitation of running out of 16 bit UUIDs and gives the power to declare your own UUIDs for Custom

Services and Characteristics. These randomly generated UUIDs in the GATT Configurator are of version 4 (random) variant 1. You

can use any UUID for a custom Service or Characteristic if it does not overlap with Bluetooth base UUID: xxxxxxxx-0000-1000-

8000-00805F9B34FB.

While there is no central authority ensuring other devices don’t use the same UUID, there is very little chance (1 in 340 undecillion) that

two devices end up with the same UUID.

UG365: GATT Configurator User's Guide

Use Cases

silabs.com | Building a more connected world. Rev. 0.1 | 8

2.3 Adding Properties

Properties define what actions can be performed for a given Characteristic or Descriptor. For example, in the Blood Pressure Profile,

the Blood Pressure Feature has a Mandatory Read property. The green + control on the right can be used to add properties to an item.

Similarly, the red x control can be used to delete the selected item. Clicking on the fields in the table allows you to select the available

options for the requirements and the state fields for a given property.

Figure 2-4. Setting properties for a Characteristic or Descriptor

2.4 Adding Capabilities

Bluetooth SDK 2.4 introduced a new feature called Polymorphic GATT that can be used to dynamically show or hide GATT Services

and Characteristics. The GATT Configurator implements this feature using GATT capabilities. This section describes how to do it.

To summarize how capabilities work, each Service/Characteristic can declare several capabilities and the state of the capabilities (ena-

ble/disable) determines the visibility of those Services/Characteristics as a bit-wise OR operation. For example, the Ser-

vice/Characteristic is visible when at least one of its capabilities is enabled and it is not visible when all its capabilities are disabled.

Always start by declaring the GATT-level capabilities and defining their default value. That is done by selecting "Custom BLE GATT"

and adding the capabilities in "Capability declaration". To add a capability just click the + control on the right-hand side and then change

the capability name and default value. For example, Appearance, Temperature_measure and Tx_power are added to the profile as

shown in the following figure.

Figure 2-5. Declaring GATT-level Capabilities

UG365: GATT Configurator User's Guide

Use Cases

silabs.com | Building a more connected world. Rev. 0.1 | 9

Once those capabilities are added they become available on each of the services and characteristics. They can be added through the +

control but this time from the list of capabilities includes all those declared at the GATT level, as shown in the following figure.

Figure 2-6. Including GATT-level Capabilities in a Characteristic

Note: The capabilities state should not be changed during a connection, as that can cause misbehavior. The safest way is to change

the capabilities when no devices are connected.

2.5 Including Services

In a Service definition, you can add one or more references to other services, using the Service includes feature. Include definitions

consist of a single attribute (the include declaration) that contains all the details required for the client to reference the included service.

Included services can help avoid duplicating data in a GATT server. If a service will be referenced by other services, you can use this

mechanism to save memory and simplify the layout of the GATT server.

UG365: GATT Configurator User's Guide

Use Cases

silabs.com | Building a more connected world. Rev. 0.1 | 10

Start by declaring an ID for each service that needs to be included. Services without an ID cannot be referenced. This is done by select-

ing the ID checkbox and providing an identifier text for the Service. Next, select the Service to be referenced. In the Settings -> Service

includes section, click the + control on the right-hand side and click on the Service.

Figure 2-7. Referencing a Service using Service Includes

2.6 Import and Export a GATT Database

Import ( ): The Import control in the Tools section allows you to import an existing GATT database using an .xml file or a .bgproj

file. Note that this will overwrite the existing GATT data.

Export: The GATT database (usually named gatt.xml) gets updated whenever you generate. A validation prompt asks for permission to

overwrite files, as shown in the image below. Here you can uncheck files that do not need to be overwritten. All the generated or modi-

fied files are in the project folder. The gatt.xml file generated here can be used for exporting the GATT database (File menu).

Figure 2-8. GATT Database Generation for Export

Generation also has a feature of making backup files before overwriting existing files. Backup files are saved in

file-

name.extension.bak

format for each file. These files are also located in the same folder as the overwritten files.

http://www.silabs.com

Silicon Laboratories Inc.

400 West Cesar Chavez

Austin, TX 78701

USA

Simplicity Studio

One-click access to MCU and

wireless tools, documentation,

software, source code libraries &

more. Available for Windows,

Mac and Linux!

IoT Portfolio

www.silabs.com/IoT

SW/HW

www.silabs.com/simplicity

Quality

www.silabs.com/quality

Support and Community

community.silabs.com

Disclaimer

Silicon Labs 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 Labs 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 Labs 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 Labs 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 Labs. 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 Labs products are not designed or authorized for military applications. Silicon Labs 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®, Micrium, Precision32®, ProSLIC®, Simplicity Studio®, SiPHY®, Telegesis, the Telegesis Logo®, USBXpress®, Zentri, Z-Wave, and others are trademarks or

registered trademarks of Silicon Labs. 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.