BLUETOOTH SMART PROFILE TOOLKIT DEVELOPER GUIDE Tuesday, 28 August 2018 Version 3.
Copyright © Silicon Labs All rights reserved. Silicon Labs assumes no liability or responsibility for any errors, mistakes or inaccuracies in content. Silicon Labs reserves the right to change products or specifications without notice, and does not make any commitment to update the information herein. Silicon Labs’ products are not authorized for use as critical components in life support devices or systems. The Bluetooth® word mark and logos are registered trademarks owned by the Bluetooth® SIG, Inc. USA.
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.
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 description improved 2.9 Updated with the latest SW 1.
2 Introduction Bluetooth Smart 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.
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.
2.1.5 The Profile Toolkit The Bluetooth Smart Profile Toolkit is a simple set of tools, which can be used to describe GATT based Bluetooth Smart services and characteristics. The Profile Toolkit consists of a simple XML based 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.
3 GATT Database file (gatt.xml) This section of the document describes the XML syntax used in the 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. 3.1 Generic GATT Limitations The following table lists limitations regarding GATT database.
3.2 Defining Services 3.2.1 : Service Definition element The XML element is used to define a service. The attributes are described in more detail in the table below. Attribute 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 are used for manufacturer specific implementations.
Attribute Description sdp This option can be used to exclude the service from classic BT SDP database. Options: true : UUID is included in SDP database (default) false : UUID is not included in SDP database Example: A 128-bit vendor specific service the UUID which will be included in the advertisement data: You can generate your own 128-bit UUIDs at http://www.itu.int/en/ITU-T/asn1/Pages/UUID/uuids.
3.3 Defining Characteristics 3.3.1 : Characteristic Definition element The XML element is used to define define a characteristic, it's UUID and internal ID used in applications. The attributes are described in more detail in the table below. Attribute Description uuid Universally Unique IDentifier. The UUID uniquely identifies a characteristic.
3.3.2 : Characteristic Properties element The XML element is used to define the properties of a characteristic. A characteristic may have one or more properties. The attributes are described in more detail in the table below. Possible values for all attributes are true or false and in all cases default value is false. Attribute Description read This attribute defines that a characteristic value can be read over a Bluetooth connection using the Attribute Read procedure.
Attribute Description encrypted_write This attribute defines that writing the characteristic value over a Bluetooth connection requires that the connection is encrypted. With iOS 9.1 and newer, devices must also be bonded at least with Just Works pairing. This attribute is only valid with the Bluetooth stack in the BT121. NOTE! Attribute write or write_no_response must also be set to "true".
3.3.3 : Characteristic Value Definition element The XML element is used to define a characteristic value description. The attributes are described in more detail in the table below. Attribute Description length This atttribute defines the fixed length of an attribute or the maximum length of an attribute if the attribute variable_length (see below) is used. Range: 0 - 255 (Bytes) variable_length This attribute defines that the length of an attribute is variable.
There are two ways to specify the length (in bytes) of a characteristic. One way is to use the length="..." attribute inside the element. Alternatively you can simply include the data inside the element, which for example must be done with constant data. Using this will override the length defined with length="".
3.3.4 : Characteristic User Description element The XML element is used to define a user description of the characteristic. This can be used to name a characteristic in a user friendly way. This information is exposed in the GATT database can be used to populate user interfaces with user friendly strings.
Descriptor properties are defined by the element and only read and/or write access is allowed. Value is defined by element the same way as for characteristic value. Below an example on how to add a characteristic descriptor with type UUID 2908.
3.4 Examples The example below shows how to implement the Generic Access (GAP) service which needs to be included in every Bluetooth Smart device. GAP Service
The second example below shows how to implement the Heart Rate (HRS) service. GAP Service HR service has 16-bit UUID 180d.
The third example below shows how to implement a vendor specific service and characteristic: GAP Service
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.
