Silicon Labs BLE API User Manual
BLUEGIGA BLUETOOTH SMART SOFTWARE
V.1.6 API DOCUMENTATION
Thursday, 14 December 2017
Version 3.11
Table of Contents
1 Version History -- BLE API Doc ____________________________________________________________ 5
2 Introduction to Bluegiga Bluetooth Smart Software -- BLEAPI ____________________________________ 7
2.1 The Bluegiga Bluetooth Smart Stack ___________________________________________________ 7
2.2 The Bluegiga Bluetooth Smart SDK ____________________________________________________ 8
2.3 The BGAPI TM Protocol _____________________________________________________________ 9
2.4 The BGLIB TM Host Library _________________________________________________________ 10
2.5 The BGScript TM Scripting Language _________________________________________________ 11
2.6 The Profile Toolkit TM _____________________________________________________________ 12
3 Introduction to Bluetooth Smart Technology -- BLEAPI ________________________________________ 13
3.1 Physical layer ____________________________________________________________________ 13
3.2 Packet format ____________________________________________________________________ 14
3.2.1 Generic packet format _______________________________________________________ 14
3.2.2 Advertisement packet format __________________________________________________ 14
3.2.3 Data packet format _________________________________________________________ 14
3.3 Link layer state machine ____________________________________________________________ 16
3.4 Link layer operations ______________________________________________________________ 17
3.4.1 Passive scanning __________________________________________________________ 17
3.4.2 Active scanning ____________________________________________________________ 18
3.4.3 Connection establishment ____________________________________________________ 18
3.5 Topologies ______________________________________________________________________ 19
3.6 Connections and packet timings ______________________________________________________ 20
3.7 Encryption _______________________________________________________________________ 22
3.8 L2CAP _________________________________________________________________________ 23
3.9 Security Manager -- BLEAPI ________________________________________________________ 24
3.9.1 I/O capabilities and Man-in-the-Middle (MITM) protection ___________________________ 24
3.10 Attribute Protocol (ATT) ___________________________________________________________ 25
3.11 Generic Attribute Profile (GATT) ____________________________________________________ 28
3.12 Generic Access Profile (GAP) -- BLEAPI ______________________________________________ 31
4 API definition -- BLEAPIs ________________________________________________________________ 32
4.1 The BGAPI protocol definition -- BLEAPI _______________________________________________ 32
4.1.1 Message types ____________________________________________________________ 32
4.1.2 Command Class IDs ________________________________________________________ 34
4.1.3 Packet Exchange __________________________________________________________ 34
4.2 The BGLIB functions definition _______________________________________________________ 38
4.3 The BGScript API definition _________________________________________________________ 39
4.4 Data Types -- BLEAPI _____________________________________________________________ 40
5 API Reference ________________________________________________________________________ 41
5.1 Attribute Client ___________________________________________________________________ 42
5.1.1 Commands--attclient ________________________________________________________ 42
5.1.2 Enumerations--attclient ______________________________________________________ 65
5.1.3 Events--attclient ____________________________________________________________ 66
5.2 Attribute Database ________________________________________________________________ 72
5.2.1 Commands--attributes _______________________________________________________ 72
5.2.2 Enumerations--attributes _____________________________________________________ 80
5.2.3 Events--attributes __________________________________________________________ 82
5.3 Connection ______________________________________________________________________ 85
5.3.1 Commands--connection _____________________________________________________ 85
5.3.2 Enumerations--connection ___________________________________________________ 96
5.3.3 Events--connection _________________________________________________________ 97
5.4 Generic Access Profile ____________________________________________________________ 101
5.4.1 Commands--gap __________________________________________________________ 101
5.4.2 Enumerations--gap ________________________________________________________ 121
5.4.3 Events--gap ______________________________________________________________ 130
5.5 Hardware ______________________________________________________________________ 131
5.5.1 Commands--hardware ______________________________________________________ 131
5.5.2 Events--hardware _________________________________________________________ 160
5.6 Persistent Store _________________________________________________________________ 165
5.6.1 Commands--flash _________________________________________________________ 165
Silicon Labs Page of 3 233
5.6.2 Events--flash _____________________________________________________________ 174
5.7 Security Manager ________________________________________________________________ 175
5.7.1 Commands--sm ___________________________________________________________ 175
5.7.2 Enumerations--sm _________________________________________________________ 186
5.7.3 Events--sm ______________________________________________________________ 189
5.8 System ________________________________________________________________________ 193
5.8.1 Commands--system _______________________________________________________ 193
5.8.2 Enumerations--system _____________________________________________________ 208
5.8.3 Events--system ___________________________________________________________ 209
5.9 Testing ________________________________________________________________________ 215
5.9.1 Commands--test __________________________________________________________ 215
5.10 Device Firmware Upgrade ________________________________________________________ 221
5.10.1 Commands--dfu __________________________________________________________ 221
5.10.2 Events--dfu _____________________________________________________________ 226
5.11 Error Codes ___________________________________________________________________ 227
5.11.1 BGAPI Errors ____________________________________________________________ 227
5.11.2 Bluetooth Errors _________________________________________________________ 228
5.11.3 Security Manager Protocol Errors ____________________________________________ 230
5.11.4 Attribute Protocol Errors ___________________________________________________ 231
Silicon Labs Page of 4 233
1 Version History -- BLE API Doc
,
Version
1.3 API documentation for SW version v.1.0.3 (Build 43)
2.0 API documentation for v.1.1.0 beta (Build 46)
2.1 API documentation for v.1.1.0 beta (Build 55)
Note: API changes history is now included here (not separate)
Changed APIs:
* Attribute Database – User Read Response (function implemented for Beta 2)
* Connection – Connection Status Flags (fixed)
Doc improved for following APIs:
* Attribute Client – Attribute Value, Indicated, Procedure Completed, Group Found
* Attribute Database – User Read Request
* Generic Access Profile – Discover, Set Adv Parameters
* Hardware – I2c Read, I2c Write, Set Soft Timer, Set Txpower
* Security Manager – Delete Bonding, Get Bonds
* System – Whitelist Append
Other sections (outside API reference) has also been updated to improve the document
2.2 Added documentation how to use BGAPI protocol without UART flow control.
Section updated: BGAPI protocol definition
2.3 API documentation for v1.1.0 (Build 71+)
* Various typos and wording corrected.
3.0 Documentation updates for SW v1.2 compatibility
Changed APIs:
Channel quality testing commands added: Get Channel Map and Channel mode
Out of Bonds and Command Too Long error code added
Protocol error event added for indicating the invalid command or wrong length
GAP Discoverable Mode is updated to support the Enhanced Broadcasting.
Doc improved for following APIs/referenses:
Updated ADC internal reference to 1.24V (was 1.15V),
GAP - Set Scan Paremeters, Connect Selective, Connect Direct
3.1 Documentation updates for SW v1.2.2 compatibility
Added APIs:
Added API's for reading (Read Data), writing (Write Data), and erasing (Erase Page)
the user area data on the internal flash memory
Added API's for handling I/O port interrupts (Io Port Irq Enable) and setting the
directions (Io Port Irq Direction)
Added testing API's for sending and receiving data (Phy Tx, Phy Rx, Phy End)
Added API's for handling the comparator functionality under HW commands and
events.
Silicon Labs Page of 5 233
Version
3.2 Documentation updates for SW v1.3.0 compatibility
Added APIs:
Added Set RXGain API for controlling RX Gain for lowering the sensitivity (Hardware
commands)
Added Usb Enable API for controlling whether USB interface is on or off (Hardware
commands)
Added AES API’s for using AES engine for de-/encryptions (System commands)
3.3 Documentation updates for SW v1.3.1 compatibility
Added APIs:
Added Send Attributes (attributes_send) command for controlling sending of
notifications and indications (Attributes commands)
Added Whitelist Bonds (sm_whitelist_bonds) command for adding all the
bonded devices to the whitelist (Security Manager commands).
3.4 Editorial changes and improvements and enhancements to command, response and event
descriptions.
3.5 Editorial changes and improvements and enhancements to command, response and event
descriptions.
3.6 Updates for the software v.1.4.0
New API added : Set Initiating Con Parameters
New API added : Slave Latency Disable
iOS9.1 pairing pairing instructions: Encrypt Start
3.7 New API added: Set Pairing Distribution Keys
3.8 New API added: Sleep Enable
3.9 New API added: Set Nonresolvable Address
Updated API: Set Privacy Flags
3.10 Updates for the software v.1.5.0
Corrected AFH Description in section.Connections and packet timings
New API added: and commands description.Channel Map Set Channel Map Get
Corrected and descriptions.Attribute Write Write Command
Added note about packet mode responses in BGAPI protocol definition
Refined descriptionPhy Tx
3.11 Updates for the software v.1.6.0
Corrected type, added Bluetooth 4.0 specification reference in
lolen
Set Initiating Con
section.Parameters
Added Bluetooth 4.0 specification reference in section.Set Scan Parameters--gap
Silicon Labs Page of 6 233
2 Introduction to Bluegiga Bluetooth Smart Software -- BLEAPI
The Bluegiga Smart Software enables developers to quickly and easily develop Smart
Bluetooth Bluetooth
applications without in-depth knowledge of the Smart technology. The Smart Software
Bluetooth Bluetooth
consists of two main parts:
The Smart Stack
Bluetooth
The Smart Software Development Kit (SDK)
Bluetooth
2.1 The Bluegiga Bluetooth Smart Stack
The Smart stack is a fully 4.0 single mode compatible software stack implementing slave
Bluetooth Bluetooth
and master modes, all the protocol layers such as L2CAP, Attribute Protocol (ATT), Generic Attribute Profile
(GATT), Generic Access Profile (GAP) and security manager (SM). The Bluetooth Smart stack also implements
various other features such as interface APIs to SPI, UART, GPIO, ADC, flash etc. and other features like the
Device Firmware Update (DFU) API.
The Smart is meant for the Bluegiga Smart products such as BLE112, BLE113 BLE121LR
Bluetooth Bluetooth
and BLED112.
Figure: The Bluegiga Bluetooth Smart Stack
Silicon Labs Page of 7 233
2.2 The Bluegiga Bluetooth Smart SDK
The Bluegiga Smart SDK is a software development kit, which enables the device and software
Bluetooth
vendors to develop products on top of the Bluegiga’s Smart hardware and software.
Bluetooth
The Smart SDK supports multiple development models and the software developers can decide
Bluetooth
whether the device’s application software runs on a separate host (for example a MCU) or whether they want to
make fully standalone devices and execute their application on-board the Bluegiga Smart modules.
Bluetooth
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.
The SDK contains the following components:
Bluetooth Smart
The BGAPI protocol
TM
is a binary based commend and response protocol that allows the Bluetooth
Smart stack to be controller form an external host and an application over for example UART or USB
interface.
The BGScript scripting language TMis a simple BASIC like scripting language that allows the software
developers to embed applications on-board the Bluegiga Smart modules. The BGScript
Bluetooth
applications are executed in the BGScript Virtual Machine (VM) and the benefit of this is that no external
host MCU is required.
The BGLIB host library
TM
is a lightweight parser for the BGAPI host protocol and it implements C
functions and callback handlers for all the BGAPI commands, responses and events. The benefit of the
BGLIB library is that speeds up the application development for the external host processors.
The Profile ToolkitTM is a simple XML based description language that enables quick and easy
development of GATT Bluetooth Smart services and characteristics on a device.
Each of these components are described in more detail in the following chapters.
Silicon Labs Page of 8 233
2.3 The BGAPI TM Protocol
For applications where a separate host is used to implement the end user application, a transport protocol is
needed between the host and the Smart stack. The transport protocol is used to communicate with
Bluetooth
the stack as well to transmit and receive data packets. This protocol is called BGAPI and it's a
Bluetooth
lightweight binary based communication protocol designed specifically for ease of implementation within host
devices with limited resources.
The BGAPI protocol is a simple command, response and event based protocol and it can be used over UART
or USB physical interfaces.
Figure: BGAPI message exchange
The BGAPI provides access for example to the following layers in the Smart Stack:
Bluetooth
Generic Access Profile - GAP allows the management of discoverability and connetability modes and
open connections
Security manager - Provides access the low energy security functions
Bluetooth
Attribute database - An class to access the local attribute database
Attribute client - Provides an interface to discover, read and write remote attributes
Connection - Provides an interface to manage low energy connections
Bluetooth
Hardware - An interface to access the various hardware layers such as timers, ADC and other hardware
interfaces
Persistent Store - User to access the parameters of the radio hardware and read/write data to nonvolatile memory
System - Various system functions, such as querying the hardware status or reset it
Silicon Labs Page of 9 233
2.4 The BGLIB TM Host Library
For easy implementation of BGAPI protocol an ANSI C host library is available. The library is easily portable
ANSI C code delivered within the Smart SDK. The purpose is to simplify the application development
Bluetooth
to various host environments.
Figure: The BGLIB host library
Silicon Labs Page of 10 233
2.5 The BGScript TM Scripting Language
The Smart SDK Also allows the application developers to create fully standalone devices without a
Bluetooth
separate host MCU and run all the application code on the Bluegiga Smart modules. The
Bluetooth Bluetooth
Smart modules can run simple applications along the Smart stack and this provides a benefit when
Bluetooth
one needs to minimize the end product’s size, cost and current consumption. For developing standalone
Smart applications the SDK includes a BGScript VM, compiler and other BGScript development tools.
Bluetooth
BGScript provides access to the same software and hardware interfaces as the BGAPI protocol and the
BGScript code can be developed and compiled with free-of-charge tools provided by Bluegiga.
Typical BGScript applications are only few tens to hundreds lines of code, so they are really quick and easy to
develop and lots of readymade examples are provides with the SDK.
Figure: BGScript application model
Figure: BGScript code example
Silicon Labs Page of 11 233
2.6 The Profile Toolkit TM
The Smart profile toolkit is a simple set of tools, which can used to describe GATT based
Bluetooth 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 to binary format and generates API to access the characteristic values.
Figure: A profile toolkit example of GAP service
Silicon Labs Page of 12 233
3 Introduction to Bluetooth Smart Technology -- BLEAPI
This section gives a quick introduction to the Smart technology and its most important features. The
Bluetooth
chapter does not contain complete detailed technology walkthrough but gives developers more insight into the
technology and to help them develop Smart applications.
Bluetooth
3.1 Physical layer
The features of physical the layer in low energy are:
Bluetooth
Feature Value
Frequency band 2.4GHz (2402Mhz - 2480MHz
Modulation GFSK, 1 Mbps
Modulation index 0.5
Channel spacing 2 MHz
Advertising channels 3
Data channels 37
Frequency hopping Adaptive FHSS
The requirements for the low energy radio are:
Bluetooth
Feature Value
Minimum TX power 0.01mW (-20 dBm)
Maximum TX power 10 mW (10 dBm)
Minimum RX sensitivity -70 dBm (BER 0.1%)
The typical range for low energy radios is:
Bluetooth
TX power RX sensitivity Range
0 dBm -70 dBm ~30 meters
10 dBm -90 dBm 100+ meters
The figure below illustrates the link layer channels. There are 37 data channels and 3 advertisement channels.
Figure: Link layer channels
Silicon Labs Page of 13 233
3.2 Packet format
3.2.1 Generic packet format
Bluetooth
Smart technology uses one generic packet format used for both advertisement and data packets.
Figure: Generic packet format
Preamble: either 010101010 or 101010101
Access address: advertisement packets use a fixed access address of 0x8E89BED6. Data packets use
a random access address depending on the connection.
PDU: protocol data unit depends on the packet type.
CRC: a 24-bit CRC checksum is used to protect the PDU.
3.2.2 Advertisement packet format
The advertisement packets use the following structure and can contain 0 to 31 bytes of advertisement data.
Figure: Advertisement packet structure
3.2.3 Data packet format
The data packets on the other hand use the following structure. An unencrypted data packet can have 0 to 27
bytes of payload.
Figure: Unencrypted data packet
Silicon Labs Page of 14 233
An encrypted data packet can have 0 to 31 bytes of payload length, but MIC (Message Integrity Check) is part
of it.
Figure: Encrypted data packet
Silicon Labs Page of 15 233
3.3 Link layer state machine
The low energy link layer state machine and state transitions are illustrated in the figure below.
Bluetooth
Figure: Link layer state machine and state transitions
Silicon Labs Page of 16 233
3.4 Link layer operations
This section describes the low energy link layer operations.
Bluetooth
3.4.1 Passive scanning
In passive scanning mode the advertiser simply broadcasts advertisement packets on the advertising channels
and a scanner simply listens to incoming advertisements.
Typically in passive scanning scenario:
Advertiser sends three advertisement packet one on each advertisement channel separated by 150us.
Scanner only listens to one advertisement channel at a time, but keeps switching between the three
advertisement channels.
The advertisement events are separated by a time called advertisement interval, which can vary from 20ms to
10240ms. In addition a random delay is added to the advertisement interval to avoid interference with other
devices.
Figure: Passive scanning
The advertisement packets typically contains information like:
Discoverability and connectability modes
The address of advertiser
TX power level
Supported services
Application data
Silicon Labs Page of 17 233
3.4.2 Active scanning
In active scanning mode the scanner will request more information from the Advertiser after it has received an
advertisement packet. The scanner will send a scan request packet to the advertiser and, which the advertiser
can respond by sending back scan response packet and scan response data.
Figure: Active scanning The scan response packets typically contains information like:
Device friendly name
Supported services (profiles)
Application data
3.4.3 Connection establishment
The figure below illustrates how the connection establishment happens at the link layer level.
Figure: Bluetooth low energy connection establisment
Silicon Labs Page of 18 233
3.5 Topologies
Bluetooth
4.0 specification defines four device roles: advertiser, scanner, master and slave. The 4.0 version of
the specification supports point-to-point and start topologies. The figure below illustrates the device roles, and
topologies.
Advetiser : Broadcasts advertisement packets, but is not able to receive them
Scanner : Listens for advertisement packets sent out by advertisers. Can try to connect an advertiser.
Master : A device that is connected to one or several slaves
Slave : A deivce that is connected to a master. Can only be connected to one master at a time
Figure: Bluetooth low energy topologiesDevices can change roles and topologies as illustrated
below.
Figure: Topology and role change
Silicon Labs Page of 19 233
3.6 Connections and packet timings
Connections allow application data to be transmitted reliably and robustly. The data sent in a connection can be
acknowledged, integrity is protected by CRC and to protect privacy the data can also be encrypted. On addition
the Adaptive Frequency Hopping (AFH) guarantees reliable data transmission even in noisy environments.
Firmware only preforms channel hopping and user is responsible for disable noisy channels. There is set of API
functions: , and , which allow user to Channel Map Set Channel Map Get, Channel Mode Channel Quality Map
specify noisy channels and disable them if necessary.
In Smart technology the connection procedures are very simple and connections are always starts
Bluetooth
when master sends a connection request packet to the slave. The connection request packet can only be sent
right after a successful reception of an advertisement packet. The connection request packet contains the
following information:
Parameter Description
Conn_Interval_Min Minimum value for the connection event interval
Range: 7.5 ms to 4000ms
Conn_Interval_Max Maximum value for the connection event interval
Range: 7.5 ms to 4000ms
Shall be greater then Conn_Interval_Min
Conn_Latency Slave latency for the connection in number of connection events.
Slave latency allows the slave devices to skip a number of connection events in case
it does not have any data to send.
Range: 0 to 500
Supervision_Timeout Supervision timeout
Range: 100ms to 32 seconds
Shall be greater than Connection Interval
The connection parameters can be updated during the connection.
The connection timeline and events are illustrated below.
Figure: Bluetooth LE connectionThe connection event starts, when master sends a packet to the slave
at the defined connection interval. The slave can respond 150us after it has received a packet from the
master. However if the slave has no data to send it can skip a certain number of connection events
defined by the slave latency parameter. If no packets are received by the master or slave within the time
defined by the supervision timeout, the connection is terminated.
If the slave has more data to send than what can be fitted into a single packet, the connection event will
automatically extend and the slave can send as many packets as there is time until the beginning of next
connection interval. This however can only be used with attribute protocol operations, that do not require an
acknowledgement.
Silicon Labs Page of 20 233
Figure: Slave latency in function (latency=3)
Silicon Labs Page of 21 233
3.7 Encryption
Bluetooth
low energy uses AES-128 link layer encryption block with Counter Mode CBC MAC (defined in RFC
3610).
The data packets are encrypted as show below.
Figure: Encrypted data packet
The full AES encryption procedure is illustrated below.
Figure: AES encryption procedure
Limitations of link layer encryption
Maximum 2^39 packets per Long Term Key (LTK)
13.7 TB of data / connection
~12 years at maximum data rate
Silicon Labs Page of 22 233
3.8 L2CAP
L2CAP stands for Logical Link Control and Adaptation Protocol and it is acts as a protocol multiplexer and
handles segmentation and reassembly of packets. It also provides logical channels, which are multiplexed over
a or more logical links.
All application data is sent over L2CAP packets and the L2CAP structure is illustrated below.
Figure: L2CAP packet format
The following CIDs are defined:
CID Description Notes
0x0000 Null identifier Not used
0x0001 L2CAP Signaling Channel BR/EDR only
0x0002 Connectionless Channel BR/EDR only
0x0003 AMP Manager Protocol BR/EDR only
0x0004 Attribute Protocol LE only
0x0005 LE L2CAP Signaling Channel LE only
0x0006 Security Manager Protocol LE only
Silicon Labs Page of 23 233
3.9 Security Manager -- BLEAPI
The security manager protocol is responsible of:
Pairing
Key distribution
Generating hashes and short term keys
The security manager uses asymmetric model and more responsibility is given to the master device, so the
memory and processing requirements on the slaves can be kept to minimum.
The basic security manager concepts include:
Distributing key model
Slave generates and distributes key information to master
Master can use this key information when reconnecting
Pairing
Authentication of devices based on their capabilities and security requirements
Signing Data
Signing allows authentication of sender without encryption
Bonding
GAP concept – device save keys for bonded devices
Three pairing methods are supported:
Just works pairing, similar to 2.1 + EDR
Bluetooth
Man-in-the-Middle pairing using a passkey entry or comparison, similar to 2.1 + EDR
Bluetooth
Out-of-band pairing, where security keys are exchanged over an other medium like NFC
3.9.1 I/O capabilities and Man-in-the-Middle (MITM) protection
Same I/O capabilities and MITM features are supported as in 2.1 + EDR.
Bluetooth
Figure: I/O capabilities
Silicon Labs Page of 24 233
3.10 Attribute Protocol (ATT)
Bluetooth
low energy profiles expose a state of a device. The state is exposed as one or several values called
attributes and the protocol to access these attributes is called the Attribute protocol (ATT).
The attribute protocol uses a client server architecture and has two roles:
Server
Service is the device that exposes the information as one or several attributes
Client
Client device that collects the information for one or more servers
Figure: Device roles
Attribute types:
Attributes are values:
Arrays of octets
From 0 to 512 octets
Can be fixed or variable length
Example:
Value
0x0000
0x426c75656769676120546563686e6f6c6f67696573
Attribute have handles, which are used to address an individual attribute. The client accesses the server's
attributes using this handle.
Example:
Handle Value
0x0001 0x0000
0x0002 0x426c75656769676120546563686e6f6c6f6769657
Attributes also have a type, described by a UUID. UUID determines what the attribute value means.
Silicon Labs Page of 25 233
Two types of UUIDs are used:
Globally unique 16-bit UUID defined in the characteristics specifications ( )http://developer.bluetooth.org/
Manufacturer specific 128-bit UUIDs, which can for example be generated online. (http://www.
)uuidgenerator.com/
Example:
Handle UUID Value Description
0x0001 0x1804 0x0000 TX power as dBm
0x0002 0x2a00 0x426c75656769676120546563686e6f6c6f6769657 Device name, UTF-8
Attribute permissions:
Attributes also have permissions, which can be:
Readable / Not readable
Writable / Not writable
Readable and writable / Not readable and not writable
The attributes may also require:
Authentication to read or write
Authorization to read or write
Encryption and pairing to read or write
The attribute types and handles are public information, but the permissions are not. Therefore and read or write
request may result an error or
Read/Write Not Permitted Insufficient authentication.
Silicon Labs Page of 26 233
Attribute protocol methods:
The attribute protocol is a stateless sequential protocol, meaning that no state is stored in the protocol and only
one operation can be performed at a time.
The available Attribute Protocol methods are described in the table below:
Method Description Direction
Find Information (starting handle,
ending handle)
Used to discover attribute handles and their types
(UUIDs)
Client ->
Server
Find By Type Value (starting handle,
ending handle, type, value)
Returns the handles of all attributes matching the type
and value
Client ->
Server
Read By Group Type (starting handle,
ending handle, type)
Reads the value of each attribute of a given type in a
range
Client ->
Server
Read By Type (starting handle, ending
handle, type)
Reads the value of each attribute of a given type in a
range
Client ->
Server
Read (handle) Reads the value of given handle
Maximum payload : 22 bytes
Client ->
Server
Read Blob (handle, offset) Can be used to read long attributes larger than 22
bytes.
Maximum payload: 64 kBytes
Client ->
Server
Read Multiple ([Handle]*) Used to read multiple values at the same time Client ->
Server
Write (handle, value) Writes the value to the given handle, with no response
Maximum payload: 20 bytes
Client ->
Server
Prepare Write (handle, offset, value)
and
Execute (exec/cancel)
Prepares a write procedure, which is queued in server
until the write is executed.
Client ->
Server
Handle Value Notification (handle,
value)
Server notifies client of an attribute with a new value
Maximum payload: 20 bytes
Server ->
Client
Handle Value Indication (handle, value) Server indicates to client an attribute with a new value.
Client must confirm reception.
Maximum payload: 20 bytes
Server ->
Client
Error response Any request can cause an error and error response
contains information about the error
Server ->
Client
Silicon Labs Page of 27 233
3.11 Generic Attribute Profile (GATT)
The Generic ATTribute profile (GATT) has similar client server structure as Attribute Protocol. However the
GATT encapsulates data (attributes) into and the data is exposed as .
services characteristics
Figure: GATT architecture
GATT defines concepts of:
Service Group
Characteristic Group
Declarations
Descriptors
It's important also to understand that GATT does not does not define rules for their use.
Characteristics
Characteristic is a value, with a known type, and a known format. They characteristics are defined in
"Characteristic Specification" available at .http://developer.bluetooth.org
Characteristics consist of:
Characteristic Declaration
Describes the properties of (read, write, indicate etc.), handle
characteristic value characteristic value
and type (UUID)
characteristic value
Characteristic Value
Contains the value of the characteristic.
Characteristic Descriptor(s)
Provide additional information about the characteristic (characteristic user description, characteristic
client configuration, vendor specific information etc.)
Figure: Characteristic format
Silicon Labs Page of 28 233
Service
A service is:
defined in a service specification ( )http://developer.bluetooth.org
collection of characteristics
references to other services
There are two types of service:
Primary services
A primary service exposes primary functionality of a device. It can be included by an other service.
Secondary services
Secondary service is a subservient of another primary or a secondary service. It's only relevant in the
context of an other service.
Attributes alone are just flat:
Figure: List of attributes
Grouping attributes into services gives structure:
Figure: Attributes grouped into services
Silicon Labs Page of 29 233
GATT procedures
The available Attribute Protocol methods are described in the table below:
Procedure Sub-Procedures
Server Configuration Exchange MTU
Primary Service Discovery Discovery All Primary Service
Discover Primary Service by Service UUID.
Relationship Discovery Find Included Services
Characteristic Discovery Discover All Characteristics of a Service
Discover Characteristics by UUID
Characteristic Descriptor Discovery Discover All Characteristic Descriptors
Characteristic Value Read Characteristic Value Read Read Characteristic Value
Read Using Characteristic UUID
Read Long Characteristic Values
Read Multiple Characteristic Values
Characteristic Value Write Write Without Response
Write Without Response With Authentication
Write Characteristic Value
Write Long Characteristic Values
Reliable Writes
Characteristic Value Notifications Notifications
Characteristic Value Indications Indications
Characteristic Descriptors Read Characteristic Descriptors
Read Long Characteristic Descriptors
Write Characteristic Descriptors
Write Long Characteristic Descriptors
Silicon Labs Page of 30 233
3.12 Generic Access Profile (GAP) -- BLEAPI
GAP defines device roles:
Broadcaster : Sends advertising events, including characteristics, including service data (does not need
RX)
Observer : Receives advertising events, listens for characteristics, listens for service data (does not
need TX)
Peripheral : Has RX and TX, is always slave, is connectable and advertising
Central : Has RX and TX, is always master, never advertises
GAP also defines modes and procedures for
Discovery
Connections
Bonding
Privacy
Non-Resolvable and Resolvable Private Addresses
Silicon Labs Page of 31 233
Loading...