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
4 API definition -- BLEAPIs
This section of the document contains the generic Smart Stack API definition. The definition consist of
Bluetooth
three parts:
The BGAPI host protocol API definition
TM
The BGLIB host library API description
TM
The BGScript scripting language API description
TM
This section of the document only provides the generic definition and description of the API. The actual
commands, responses and events are described in detail in the section.API reference
4.1 The BGAPI protocol definition -- BLEAPI
The BGAPI protocol is a command, response and event protocol that can be used to communicate with the
Smart stack over one of the physical interfaces like UART or USB. The BGAPI protocol can be used
Bluetooth
to instruct the Smart stack to do something like advertise, discover and connect other
Bluetooth Bluetooth
devices or access the physical interfaces like SPI or I2C of the Smart module.
Bluetooth
The BGAPI commands, responses and events use a binary format and the generic protocol format is described
in this section.
BGAPI Packet format
The generic BGAPI protocol format is described in the table below. The BGAPI protocol uses a four (4) byte
header and data payload.
Packets in either direction use the following format.
Table: BGAPI packet format
Octet Octet bits Length Description Notes
Octet 0 7 1 bit
Message Type (MT) 0: Command/Response
Event1:
... 6:3 4 bits
Technology Type (TT) 0000: Smart
Bluetooth
: Wi-Fi0001
... 2:0 3 bits
Length High (LH)
Payload length (high bits)
Octet 1 7:0 8 bits
Length Low (LL)
Payload length (low bits)
Octet 2 7:0 8 bits
Class ID (CID)
Command class ID
Octet 3 7:0 8 bits
Command ID (CMD)
Command ID
Octet 4-n - 0 - 2048 Bytes
Payload (PL)
Up to 2048 bytes of payload
With the Bluegiga Smart products the maximum allowed BGAPI packet size is 64 bytes and
Bluetooth
longer packet sizes cannot be used. Four (4) bytes will be used for the BGAPI protocol header so the
maximum payload size is 60 bytes.
4.1.1 Message types
The following message types exist in the BGAPI protocol.
Table: BGAPI message types
Silicon Labs Page of 32 233
Message type Message Type (MT)
Value
Description
Command 0x00 Command from host to the stack
Response 0x00 Response from stack to the host
Event 0x80 Event from stack to the host
Silicon Labs Page of 33 233
4.1.2 Command Class IDs
The following command classes exist.
Table: BGAPI command classes
Class ID Description Explanation
0x00 System Provides access to system functions
0x01 Persistent Store Provides access the persistence store (parameters)
0x02 Attribute database Provides access to local GATT database
0x03 Connection Provides access to connection management functions
0x04 Attribute client Functions to access remote devices GATT database
0x05 Security Manager Bluetooth low energy security functions
0x06 Generic Access Profile GAP functions
0x07 Hardware Provides access to hardware such as timers and ADC
4.1.3 Packet Exchange
The BGAPI protocol is a simple command / response protocol and the BGAPI messages are exchanged as
show in the picture below.
The command messages are transmitted from the Application to the Stack and the Stack provides a response
to every successfully received command.
Some commands may generate events, which are transmitted from the Stack to the Application.
Silicon Labs Page of 34 233
The Application should always wait for the response to a command before issuing another command.
Silicon Labs Page of 35 233
Using BGAPI protocol without UART flow control (Packet mode)
By default the BGAPI protocol assumes that UART flow control (RTS/CTS) is used to ensure reliable data
transmission and to prevent lost data because of buffer overflows. It is however possible to use the BGAPI
protocol without UART flow control.
When using the BGAPI protocol without UART flow control over a simple 2-wire (TX and RX) UART interface
and additional needs to be added to the BGAPI packets, which tells the total length of the BGAPI
length byte
packet excluding the itself. This is used by the BGAPI protocol parser to identify the length of
length byte
incoming commands and data and make sure they are fully received.
In this case the BGAPI protocol uses the following format:
Table: BGAPI packet format
Octet Octet
bits
Length Description Notes
Octet 07:0 8 bits
BGAPI command
length
Tells the length of the BGAPI command excluding the
length byte itself
Range of this octet is 4 - 62
Octet 17 1 bit
Message Type
(MT)
0: Command/Response
Event1:
... 6:3 4 bits
Technology Type
(TT)
0000: Bluetooth Smart
Wi-Fi0001:
... 2:0 3 bits
Length High (LH)
Payload length (high bits)
Octet 27:0 8 bits
Length Low (LL)
Payload length (low bits)
Octet 37:0 8 bits
Class ID (CID)
Command class ID
Octet 47:0 8 bits
Command ID
(CMD)
Command ID
Octet
5-n
- 0 - 2048
Bytes
Payload (PL)
Up to 64 bytes of payload
This operational mode needs to be especially enabled in devices hardware configuration file (typically
) and is not used by default. The default operational mode assumes a UART with flow hardware.xml
control is used.
Below is a simple example which shows how a command (Raw: 0x00 0x00 0x00 0x08) is sent System Get Info
using the BGAPI packet format.
Silicon Labs Page of 36 233
Packet mode responses
The extra length byte required in Packet Mode is only used in the traffic from host to the stack. When
the Bluetooth stack produces responses or events to the host the length byte is not included in them.
Silicon Labs Page of 37 233
4.2 The BGLIB functions definition
Bluegiga provides a reference parser for the BGAPI protocol called the BGLIB. The BGLIB is an ANSI C
implementation of BGAPI packet parser and it's provided in source code format with the Bluegiga Bluetooth
Smart SDK. The purpose of the BGLIB is to simplify and speed up the development process and also to provide
higher level, easier to use C functions and callbacks so the developers do not need to fully learn the raw BGAPI
protocol.
In BGLIB all of the BGAPI commands are available as C functions and for the BGAPI responses and events
there are callback handlers.
The BGLIB functions and callbacks are documented as show below:
C Functions
/* Function */
void ble_cmd_gap_connect_direct(
bd_addr address ,
uint8 addr_type ,
uint16 conn_interval_min ,
uint16 conn_interval_max ,
uint16 timeout
);
/* Callback */
void ble_rsp_gap_connect_direct(
uint16 result ,
uint8 conn
);
The command parameters and return values are the same as used in the BGAPI protocol and they are not
documented separately in the API reference section.
Callback programming
Callback programming is a style of computer programming, which allows lower layer of software to call functions
defined on a higher layer. Callback is piece of code or a reference to a piece of code that is passed as an
argument. The figure below illustrates the callback architecture used with BGLIB.
Figure: Callback arhitectureIf you are not familiar with callback programming a basic tutorial can for
example be found from here:
http://www.codeguru.com/cpp/cpp/cpp_mfc/callbacks/article.php/c10557
Silicon Labs Page of 38 233
4.3 The BGScript API definition
The BGScript functions are also documented in the API reference section. The format of the commands varies
slightly from the BGLIB functions and instead of using callbacks the BGScript functions take the return values
as parameters.
BGScript commands are documented as follows:
BGScript Functions
CALL gap_connect_direct(address ,addr_type ,conn_interval_min ,conn_interval_max ,timeout )(result
,conn )
The BGScript command parameters and return values are the same as used in the BGAPI binary protocol and
they are not documented separately.
Silicon Labs Page of 39 233
4.4 Data Types -- BLEAPI
The following data types are used in this documentation.
Table: Used data types
Type Description Example: Human
readable
Example Packet data in
hex
int8
signed integer stored in 1 byte twos
complement form
-42 0xd6
uint8
unsigned integer stored in 1 byte 42 0x2a
uint16
unsigned integer stored in 2 bytes little
endian format
1701 0xa5 0x06
uint32
unsigned integer stored in 4 bytes little
endian format
1000000 0x40 0x42 0x0f 0x00
uint8array
byte array, first byte is array size "Hello" 0x05 0x68 0x65 0x6c
0x6c 0x6f
bd_addr
Bluetooth address in little endian format 00:07:80:c0:ff:ee 0xee 0xff 0xc0 0x80 0x07
0x00
Silicon Labs Page of 40 233
5 API Reference
This section of the document contains the actual API description, so the description of commands, responses,
events and enumerations and their possible parameters and values. The high level categorization is made
based on the command classes, which are:
Description Explanation
Attribute database Provides access to local GATT database and allows data to be written there for remote
devices to access it.
Attribute client Provides access to ATT protocol operationsa and allows a remote devices data to be
accessed.
Connection Provides access to connection and status management
Bluetooth
Generic Access
Profile
Provides access to GAP functions which allows one to control the local
Bluetooth
devices discoverability and connectability
Hardware Provides access to hardware interfaces such as SPI, I2C, timers and ADC
Persistent Store Provides access to the local persistence store, which allows data to be written and read
to the devices flash.
Security Manager
Provides
to security functions
Bluetooth
System Provides access to various system functions
Testing Functions needed for conformance testing
Bluetooth
Device Firmware
Upgrade
Provides access to functions required for field firmware upgrades
Final section of the API reference contains description of the error codes categorized as follows:
Description
BGAPI errors
Bluetooth errors
Security manager errors
Attribute protocols errors
Silicon Labs Page of 41 233
5.1 Attribute Client
The Attribute Client class implements the Smart Attribute Protocol (ATT) and provides access to the
Bluetooth
ATT protocol methods. The Attribute Client class can be used to discover services and characteristics from the
ATT server, read and write values and manage indications and notifications.
5.1.1 Commands--attclient
Attribute Client commands
Attribute Write--attclient
This command can be used to write an attributes value on a remote device. In order to write the value of an
attribute a connection must exists and you need to know the handle of the attribute you want to write.
Bluetooth
A successful attribute write will be acknowledged by the remote device and this will generate an event
. The acknowledgement should happen within a 30 second window or otherwise attclient_procedure_completed
the Bluetooth connection will be dropped.
This command should be used for writing data to characteristic with property write="true".
The data payload for the Attribute Write command can be up to 20 bytes.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x04 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x05 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 atthandle
Attribute handle to write to
7
uint8array data
Attribute value
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x05 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 result 0 : write was successful
Otherwise error occurred
Table: EVENTS
Silicon Labs Page of 42 233
Event Description
attclient
procedure_completed
This event is generated when the write operation has been acknowledged by
remote device.
C Functions
/* Function */
void ble_cmd_attclient_attribute_write(
uint8 connection,
uint16 atthandle,
uint8 data_len,
const uint8* data_data
);
/* Callback */
struct ble_msg_attclient_attribute_write_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_attribute_write(
const struct ble_msg_attclient_attribute_write_rsp_t * msg
)
BGScript Functions
call attclient_attribute_write(connection, atthandle, data_len, data_data)(connection, result)
Silicon Labs Page of 43 233
Execute Write--attclient
This command can be used to execute or cancel a previously queued command on a remote prepare_write
device.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x02 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x0A method Message ID
4
uint8 connection
Connection Handle
5
uint8 commit 1: commits queued writes
0: cancels queued writes
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x0A method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 result
Command result
Table: EVENTS
Event Description
attclient procedure_completed Write operation has been acknowledged by remote end
C Functions
/* Function */
void ble_cmd_attclient_execute_write(
uint8 connection,
uint8 commit
);
/* Callback */
struct ble_msg_attclient_execute_write_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_execute_write(
const struct ble_msg_attclient_execute_write_rsp_t * msg
)
BGScript Functions
call attclient_execute_write(connection, commit)(connection, result)
Silicon Labs Page of 44 233
Silicon Labs Page of 45 233
Find By Type Value--attclient
This command can be used to find specific attributes on a remote device based on their 16-bit UUID value and
value. The search can be limited by a starting and ending handle values.
The command returns the handles of all attributes matching the type (UUID) and value.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x08 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x00 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 start
First requested handle number
7 - 8
uint16 end
Last requested handle number
9 - 10
uint16 uuid
2 octet UUID to find
11
uint8array value
Attribute value to find
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x00 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 result 0 : the operation was successful
Otherwise error occurred
Table: EVENTS
Event Description
attclient group_found Attributes found
attclient
procedure_completed
Procedure has completed and new procedure can be started on GATT server
C Functions
/* Function */
void ble_cmd_attclient_find_by_type_value(
uint8 connection,
uint16 start,
uint16 end,
uint16 uuid,
uint8 value_len,
const uint8* value_data
Silicon Labs Page of 46 233
);
/* Callback */
struct ble_msg_attclient_find_by_type_value_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_find_by_type_value(
const struct ble_msg_attclient_find_by_type_value_rsp_t * msg
)
BGScript Functions
call attclient_find_by_type_value(connection, start, end, uuid, value_len, value_data)(connection,
result)
Silicon Labs Page of 47 233
Find Information--attclient
This command is used to discover attribute handles and their types (UUIDs) in a given handle range.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x05 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x03 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 start
First attribute handle
7 - 8
uint16 end
Last attribute handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x03 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 result 0: if the command was successful
Otherwise error occurred
Table: EVENTS
Event Description
attclient find_information_found Handle, type - mapping found
attclient procedure_completed Find information procedure has completed
C Functions
/* Function */
void ble_cmd_attclient_find_information(
uint8 connection,
uint16 start,
uint16 end
);
/* Callback */
struct ble_msg_attclient_find_information_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_find_information(
const struct ble_msg_attclient_find_information_rsp_t * msg
)
Silicon Labs Page of 48 233
BGScript Functions
call attclient_find_information(connection, start, end)(connection, result)
Silicon Labs Page of 49 233
Indicate Confirm--attclient
This command can be used to send a acknowledge a received indication from a remote device. This function
allows the application to manually confirm the indicated values instead of the smart stack
Bluetooth
automatically doing it. The benefit of this is extra reliability since the application can for example store the
received value on the flash memory before confirming the indication to the remote device.
In order to use this feature the manual indication acknowledgements must be enabled to the
application configuration file (config.xml).
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x07 method Message ID
4
uint8 connection
Connection Handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x02 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x07 method Message ID
4 - 5
uint16 result
Command result
C Functions
/* Function */
void ble_cmd_attclient_indicate_confirm(
uint8 connection
);
/* Callback */
struct ble_msg_attclient_indicate_confirm_rsp_t{
uint16 result
}
void ble_rsp_attclient_indicate_confirm(
const struct ble_msg_attclient_indicate_confirm_rsp_t * msg
)
BGScript Functions
call attclient_indicate_confirm(connection)(result)
Silicon Labs Page of 50 233
1.
2.
3.
4.
5.
6.
7.
8.
9.
Prepare Write--attclient
This command will send a prepare write request to a remote device for queued writes. Queued writes can for
example be used to write large attribute values by transmitting the data in chunks using prepare write
command.
Once the data has been transmitted with multiple prepare write commands the write must then be executed or
canceled with command, which if acknowledged by the remote device triggers a Execute Write Procedure
event.Completed
The example below shows how this approach can be used to write a 30-byte characteristic value:
attclient_prepare_write(...., partial data)
wait for rsp_attclient_prepare_write
wait for evt_attclient_procedure_completed
attclient_prepare_write(...., partial data)
wait for rsp_attclient_prepare_write
wait for evt_attclient_procedure_completed
attclient_execute_write(1)
wait for rsp_attclient_execute_write
wait for evt_attclient_procedure_completed
It is not mandatory for an ATT server to support this command. It is only recommended to use this
command to write long-attributes which do not fit in single ATT packet.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x06 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x09 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 atthandle
Attribute handle
7 - 8
uint16 offset
Offset to write to
9
uint8array data
Data to write
Maximum amount of data that can be sent in single command is 18 bytes.
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x09 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 result
Command result
Silicon Labs Page of 51 233
Table: EVENTS
Event Description
attclient procedure_completed Write operation has been acknowledged by remote end
C Functions
/* Function */
void ble_cmd_attclient_prepare_write(
uint8 connection,
uint16 atthandle,
uint16 offset,
uint8 data_len,
const uint8* data_data
);
/* Callback */
struct ble_msg_attclient_prepare_write_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_prepare_write(
const struct ble_msg_attclient_prepare_write_rsp_t * msg
)
BGScript Functions
call attclient_prepare_write(connection, atthandle, offset, data_len, data_data)(connection,
result)
Silicon Labs Page of 52 233
Read By Group Type--attclient
This command reads the value of each attribute of a given type and in a given handle range.
The command is typically used for primary (UUID: 0x2800) and secondary (UUID: 0x2801) service discovery.
Discovered services are reported by event.Group Found
Finally when the procedure is completed a event is generated.Procedure Completed
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x06 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x01 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 start
First requested handle number
7 - 8
uint16 end
Last requested handle number
9
uint8array uuid
Group UUID to find
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x01 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 result
Command result
Table: EVENTS
Event Description
attclient group_found Attributes found
attclient
procedure_completed
Procedure has completed and new procedure can be started on GATT server
C Functions
/* Function */
void ble_cmd_attclient_read_by_group_type(
uint8 connection,
uint16 start,
uint16 end,
uint8 uuid_len,
const uint8* uuid_data
);
/* Callback */
Silicon Labs Page of 53 233
struct ble_msg_attclient_read_by_group_type_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_read_by_group_type(
const struct ble_msg_attclient_read_by_group_type_rsp_t * msg
)
BGScript Functions
call attclient_read_by_group_type(connection, start, end, uuid_len, uuid_data)(connection, result)
Silicon Labs Page of 54 233
Read By Handle--attclient
This command reads a remote attribute's value with the given handle. Read by handle can be used to read
attributes up to 22 bytes long.
For longer attributes command must be used.Read Long
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x04 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 chrhandle
Attribute handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x04 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 result 0 : the command was successful
Otherwise an error occurred
Table: EVENTS
Event Description
attclient attribute_value Only this event is received if the attribute value is successfully received
attclient
procedure_completed
If the attribute value is not successfully received, then this event is received
instead
C Functions
/* Function */
void ble_cmd_attclient_read_by_handle(
uint8 connection,
uint16 chrhandle
);
/* Callback */
struct ble_msg_attclient_read_by_handle_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_read_by_handle(
const struct ble_msg_attclient_read_by_handle_rsp_t * msg
)
Silicon Labs Page of 55 233
BGScript Functions
call attclient_read_by_handle(connection, chrhandle)(connection, result)
Silicon Labs Page of 56 233
Read By Type--attclient
The command reads the value of each attribute of a given type (UUID) and in a given attribute handle range.
The command can for example be used to discover the characteristic declarations (UUID: 0x2803) within a
service.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x06 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x02 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 start
First attribute handle
7 - 8
uint16 end
Last attribute handle
9
uint8array uuid
Attribute type (UUID)
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x02 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 result 0: the command was successful
Otherwise an error occurred
Table: EVENTS
Event Description
attclient attribute_value Attribute value read from GATT server
attclient
procedure_completed
Procedure has completed and new procedure can be started on GATT server
C Functions
/* Function */
void ble_cmd_attclient_read_by_type(
uint8 connection,
uint16 start,
uint16 end,
uint8 uuid_len,
const uint8* uuid_data
);
/* Callback */
Silicon Labs Page of 57 233
struct ble_msg_attclient_read_by_type_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_read_by_type(
const struct ble_msg_attclient_read_by_type_rsp_t * msg
)
BGScript Functions
call attclient_read_by_type(connection, start, end, uuid_len, uuid_data)(connection, result)
Silicon Labs Page of 58 233
Read Long--attclient
This command can be used to read long attribute values, which are longer than 22 bytes and cannot be read
with a simple command.Read by Handle
The command starts a procedure, where the client first sends a normal read command to the server and if the
returned attribute value length is equal to MTU, the client will send further read long read requests until rest of
the attribute is read.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x08 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 chrhandle
Attribute handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x08 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 result 0: Command executed successfully
: An error occurredNon-zero
Table: EVENTS
Event Description
attclient attribute_value Data received from remote end
attclient procedure_completed Full attribute has read, or error occurred
C Functions
/* Function */
void ble_cmd_attclient_read_long(
uint8 connection,
uint16 chrhandle
);
/* Callback */
struct ble_msg_attclient_read_long_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_read_long(
const struct ble_msg_attclient_read_long_rsp_t * msg
Silicon Labs Page of 59 233
)
BGScript Functions
call attclient_read_long(connection, chrhandle)(connection, result)
Silicon Labs Page of 60 233
Read Multiple--attclient
This command can be used to read multiple attributes from a server.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x02 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x0B method Message ID
4
uint8 connection
Connection handle
5
uint8array handles
List of attribute handles to read from the remote device
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x0B method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 result 0: Command executed successfully
: An error occurredNon-zero
Table: EVENTS
Event Description
attclient read_multiple_response Attribute data if command was succesful
attclient procedure_completed Operation has failed
C Functions
/* Function */
void ble_cmd_attclient_read_multiple(
uint8 connection,
uint8 handles_len,
const uint8* handles_data
);
/* Callback */
struct ble_msg_attclient_read_multiple_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_read_multiple(
const struct ble_msg_attclient_read_multiple_rsp_t * msg
)
BGScript Functions
Silicon Labs Page of 61 233
call attclient_read_multiple(connection, handles_len, handles_data)(connection, result)
Silicon Labs Page of 62 233
Write Command--attclient
Writes the value of a remote devices attribute. The handle and the new value of the attribute are gives as
parameters.
Write command will not be acknowledged by the remote device unlike . This command Attribute Write
should be used for writing data to characteristic with property write_no_response="true".
The maximum data payload for Write Command is 20 bytes.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x04 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x06 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 atthandle
Attribute handle to write
7
uint8array data
Value for the attribute
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x06 method Message ID
4
uint8 connection
Connection Handle
5 - 6
uint16 result 0: Command executed successfully
: An error occurredNon-zero
C Functions
/* Function */
void ble_cmd_attclient_write_command(
uint8 connection,
uint16 atthandle,
uint8 data_len,
const uint8* data_data
);
/* Callback */
struct ble_msg_attclient_write_command_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_attclient_write_command(
Silicon Labs Page of 63 233
const struct ble_msg_attclient_write_command_rsp_t * msg
)
BGScript Functions
call attclient_write_command(connection, atthandle, data_len, data_data)(connection, result)
Silicon Labs Page of 64 233
5.1.2 Enumerations--attclient
Attribute Client enumerations
Attribute Value Types--attclient
These enumerations are in the Attribute Client class
Table: VALUES
Value Name Description
0 attclient_attribute_value_type_read Value was read
1 attclient_attribute_value_type_notify Value was notified
2 attclient_attribute_value_type_indicate Value was indicated
3 attclient_attribute_value_type_read_by_type Value was read
4 attclient_attribute_value_type_read_blob Value was part of a long attribute
5 attclient_attribute_value_type_indicate_rsp_req Value was indicated and the remote device is
waiting for a confirmation.
Indicate Confirm command can be used to send a
confirmation.
Silicon Labs Page of 65 233
5.1.3 Events--attclient
Attribute Client events
Attribute Value--attclient
This event is produced at the GATT client side when an attribute value is passed from the GATT server to the
GATT client. This event is for example produced after a successful operation or when an Read by Handle
attribute is indicated or notified by the remote device.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x05 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x05 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 atthandle
Attribute handle
7
uint8 type
Attribute type
8
uint8array value
Attribute value (data)
C Functions
/* Callback */
struct ble_msg_attclient_attribute_value_evt_t{
uint8 connection,
uint16 atthandle,
uint8 type,
uint8 value_len,
const uint8* value_data
}
void ble_evt_attclient_attribute_value(
const struct ble_msg_attclient_attribute_value_evt_t * msg
)
BGScript Functions
event attclient_attribute_value(connection, atthandle, type, value_len, value_data)
Silicon Labs Page of 66 233
Find Information Found--attclient
This event is generated when characteristics type mappings are found. This happens yypically after Find
command has been issued to discover all attributes of a service.Information
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x04 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x04 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 chrhandle
Characteristics handle
7
uint8array uuid
Characteristics type (UUID)
C Functions
/* Callback */
struct ble_msg_attclient_find_information_found_evt_t{
uint8 connection,
uint16 chrhandle,
uint8 uuid_len,
const uint8* uuid_data
}
void ble_evt_attclient_find_information_found(
const struct ble_msg_attclient_find_information_found_evt_t * msg
)
BGScript Functions
event attclient_find_information_found(connection, chrhandle, uuid_len, uuid_data)
Silicon Labs Page of 67 233
Group Found--attclient
This event is produced when an attribute group (a service) is found. Typically this event is produced after Read
command.by Group Type
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x06 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x02 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 start
Starting handle
7 - 8
uint16 end
Ending handle
Note: "end" is a reserved word and in BGScript so "end" cannot be used as
such.
9
uint8array uuid
UUID of a service
Length is 0 if no services are found.
C Functions
/* Callback */
struct ble_msg_attclient_group_found_evt_t{
uint8 connection,
uint16 start,
uint16 end,
uint8 uuid_len,
const uint8* uuid_data
}
void ble_evt_attclient_group_found(
const struct ble_msg_attclient_group_found_evt_t * msg
)
BGScript Functions
event attclient_group_found(connection, start, end, uuid_len, uuid_data)
Silicon Labs Page of 68 233
Indicated--attclient
This event is produced at the GATT server side when an attribute is successfully indicated to the GATT client.
This means the event is only produced at the GATT server if the indication is acknowledged by the GATT client
(the remote device).
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x03 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x00 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 attrhandle
Attribute handle
C Functions
/* Callback */
struct ble_msg_attclient_indicated_evt_t{
uint8 connection,
uint16 attrhandle
}
void ble_evt_attclient_indicated(
const struct ble_msg_attclient_indicated_evt_t * msg
)
BGScript Functions
event attclient_indicated(connection, attrhandle)
Silicon Labs Page of 69 233
Procedure Completed--attclient
This event is produced at the GATT client when an attribute protocol event is completed a and new operation
can be issued.
This event is for example produced after an command is successfully used to write a value to a Attribute Write
remote device.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x05 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x01 method Message ID
4
uint8 connection
Object Handle
5 - 6
uint16 result 0: The operation was successful
Otherwise: attribute protocol error code returned by remote device
7 - 8
uint16 chrhandle
Characteristic handle at which the event ended
C Functions
/* Callback */
struct ble_msg_attclient_procedure_completed_evt_t{
uint8 connection,
uint16 result,
uint16 chrhandle
}
void ble_evt_attclient_procedure_completed(
const struct ble_msg_attclient_procedure_completed_evt_t * msg
)
BGScript Functions
event attclient_procedure_completed(connection, result, chrhandle)
Silicon Labs Page of 70 233
Read Multiple Response--attclient
This event is a response to a request.Read Multiple
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x02 lolen Minimum payload length
2 0x04 class Message class: Attribute Client
3 0x06 method Message ID
4
uint8 connection
Connection handle
5
uint8array handles
This array contains the concatenated data from the multiple attributes that
have been read, up to 22 bytes.
C Functions
/* Callback */
struct ble_msg_attclient_read_multiple_response_evt_t{
uint8 connection,
uint8 handles_len,
const uint8* handles_data
}
void ble_evt_attclient_read_multiple_response(
const struct ble_msg_attclient_read_multiple_response_evt_t * msg
)
BGScript Functions
event attclient_read_multiple_response(connection, handles_len, handles_data)
Silicon Labs Page of 71 233
1.
2.
5.2 Attribute Database
The Attribute Database class provides methods to read and write attributes to the local devices attribute
database. This class is usually only needed on sensor devices (Attribute server) for example to update attribute
values to the local database based on the sensor readings. A remote device then can access the GATT
database and these values over a connection.
Bluetooth
5.2.1 Commands--attributes
Attribute database commands
Read--attributes
The command reads the given attribute's value from the local database. There is a 32-byte limit in the amount
of data that can be read at a time. In order to read larger values multiple read commands must be used with the
offset properly used.
For example to read a 64 bytes attribute:
Read first 32 bytes using offset 0
Read second 32 bytes using offset 32
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x04 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x01 method Message ID
4 - 5
uint16 handle
Handle of the attribute to read
6 - 7
uint16 offset
Offset to read from.
Maximum of 32 bytes can be read at a time.
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x07 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x01 method Message ID
4 - 5
uint16 handle
Handle of the attribute which was read
6 - 7
uint16 offset
Offset read from
8 - 9
uint16 result 0 : the read was successful
: An error occurredNon-zero
10
uint8array value
Value of the attribute
C Functions
Silicon Labs Page of 72 233
/* Function */
void ble_cmd_attributes_read(
uint16 handle,
uint16 offset
);
/* Callback */
struct ble_msg_attributes_read_rsp_t{
uint16 handle,
uint16 offset,
uint16 result,
uint8 value_len,
const uint8* value_data
}
void ble_rsp_attributes_read(
const struct ble_msg_attributes_read_rsp_t * msg
)
BGScript Functions
call attributes_read(handle, offset)(handle, offset, result, value_len, value_data)
Silicon Labs Page of 73 233
Read Type--attributes
This command reads the given attribute's type (UUID) from the local database.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x02 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x02 method Message ID
4 - 5
uint16 handle
Handle of the attribute to read
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x05 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x02 method Message ID
4 - 5
uint16 handle
Handle of the attribute which was read
6 - 7
uint16 result 0: if the read was successful
: An error occurredNon-zero
8
uint8array value
Value of the attribute type (UUID)
C Functions
/* Function */
void ble_cmd_attributes_read_type(
uint16 handle
);
/* Callback */
struct ble_msg_attributes_read_type_rsp_t{
uint16 handle,
uint16 result,
uint8 value_len,
const uint8* value_data
}
void ble_rsp_attributes_read_type(
const struct ble_msg_attributes_read_type_rsp_t * msg
)
BGScript Functions
call attributes_read_type(handle)(handle, result, value_len, value_data)
Silicon Labs Page of 74 233
Send--attributes
This command will send an attribute value, identified by handle, via a notification or an indication to a remote
device, but does not modify the current corresponding value in the local GATT database.
If this attribute, identified by handle, does not have notification or indication property, or no remote device has
registered for notifications or indications of this attribute, then an error will be returned.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x04 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x05 method Message ID
4
uint8 connection
Connection handle to send to.
Use 0xFF to send to all connected clients which have subscribed to
receive the notifications or indications.
An error is returned as soon as the first failed transmission occurs.
5 - 6
uint16 handle
Attribute handle to send.
7
uint8array value
Data to send.
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x02 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x05 method Message ID
4 - 5
uint16 result
Command result
0: notification or indication was successfully sent
Otherwise: An error occurred
C Functions
/* Function */
void ble_cmd_attributes_send(
uint8 connection,
uint16 handle,
uint8 value_len,
const uint8* value_data
);
/* Callback */
struct ble_msg_attributes_send_rsp_t{
uint16 result
}
void ble_rsp_attributes_send(
const struct ble_msg_attributes_send_rsp_t * msg
)
Silicon Labs Page of 75 233
BGScript Functions
call attributes_send(connection, handle, value_len, value_data)(result)
User Read Response--attributes
This command is used to respond to an attribute Read request by a remote device, but only for attributes which
have been configured with the user property. Attributes which have the user property enabled allow the attribute
value to be requested from the application instead of the Smart stack automatically responding with
Bluetooth
the data in it's local GATT database.
This command is normally used in response to a event, which is generated when a remote User Read Request
device tries to read an attribute with a user property enabled.
The response to events must happen within 30 seconds or otherwise a timeout will occur.User Read Request
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x03 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x03 method Message ID
4
uint8 connection
Connection handle to respond to
5
uint8 att_error 0: User Read Request is responded with data.
In case of an error an application specific error code can be sent.
6
uint8array value
Data to send
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x00 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x03 method Message ID
C Functions
/* Function */
void ble_cmd_attributes_user_read_response(
uint8 connection,
uint8 att_error,
uint8 value_len,
const uint8* value_data
);
/* Callback *
void ble_rsp_attributes_user_read_response(
const void *nul
)
BGScript Functions
Silicon Labs Page of 76 233
call attributes_user_read_response(connection, att_error, value_len, value_data)
Silicon Labs Page of 77 233
User Write Response--attributes
This command is used by the GATT server to acknowledge to the remote device that the attribute's value was
written. This feature again allows the user application to acknowledged the attribute write operations instead of
the Smart stack doing it automatically.
Bluetooth
The command should be used when a event is received where the reason why value has changed Value
corresponds to .attributes_attribute_change_reason_write_request_user
This response must be sent within 30 seconds or otherwise a timeout will occur.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x02 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x04 method Message ID
4
uint8 connection
Connection handle to respond to
5
uint8 att_error
Attribute error code to send if an error occurs.
0x0: Write was accepted
0x80-0x9F: Reserved for user defined error codes
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x00 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x04 method Message ID
C Functions
/* Function */
void ble_cmd_attributes_user_write_response(
uint8 connection,
uint8 att_error
);
/* Callback *
void ble_rsp_attributes_user_write_response(
const void *nul
)
BGScript Functions
call attributes_user_write_response(connection, att_error)
Silicon Labs Page of 78 233
Write--attributes
This command writes an attribute's value to the local database.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x04 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x00 method Message ID
4 - 5
uint16 handle
Handle of the attribute to write
6
uint8 offset
Attribute offset to write data
7
uint8array value
Value of the attribute to write
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x02 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x00 method Message ID
4 - 5
uint16 result 0: the write was successful
: An error occuredNon-zero
C Functions
/* Function */
void ble_cmd_attributes_write(
uint16 handle,
uint8 offset,
uint8 value_len,
const uint8* value_data
);
/* Callback */
struct ble_msg_attributes_write_rsp_t{
uint16 result
}
void ble_rsp_attributes_write(
const struct ble_msg_attributes_write_rsp_t * msg
)
BGScript Functions
call attributes_write(handle, offset, value_len, value_data)(result)
Silicon Labs Page of 79 233
5.2.2 Enumerations--attributes
Attribute Database enumerations
Attribute Change Reason--attributes
This enumeration contains the reason for an attribute value change.
Table: VALUES
Value Name Description
0 attributes_attribute_change_reason_write_request Value was written by remote device using
write request
1 attributes_attribute_change_reason_write_command Value was written by remote device using
write command
2 attributes_attribute_change_reason_write_request_user Local attribute value was written by the
remote device, but the Smart
Bluetooth
stack is waiting for the write to be
confirmed by the application.
User Write Response command should
be used to send the confirmation.
For this reason to appear the attribute in
the GATT database must have the user
property enabled.
See for
Profile Toolkit Developer Guide
more information how to enable the user
property for an attribute.
Silicon Labs Page of 80 233
Attribute Status Flags--attributes
Attribute status flags
Table: VALUES
Value Name Description
1 attributes_attribute_status_flag_notify Notifications are enabled
2 attributes_attribute_status_flag_indicate Indications are enabled
Silicon Labs Page of 81 233
5.2.3 Events--attributes
Attribute Database events
Status--attributes
This event indicates attribute status flags have changed. For example, this even is generated at the module
acting as the GATT Server whenever the remote GATT Client changes the Client Characteristic Configuration
to start or stop notification or indications from the Server.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x03 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x02 method Message ID
4 - 5
uint16 handle
Attribute handle
6
uint8 flags
Attribute status flags
See: Attribute Status Flags
C Functions
/* Callback */
struct ble_msg_attributes_status_evt_t{
uint16 handle,
uint8 flags
}
void ble_evt_attributes_status(
const struct ble_msg_attributes_status_evt_t * msg
)
BGScript Functions
event attributes_status(handle, flags)
Silicon Labs Page of 82 233
User Read Request--attributes
This event is generated when a remote device tries to read an attribute which has the user property enabled.
This event should be responded within 30 seconds with command either containing the User Read Response
data or an error code.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x06 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x01 method Message ID
4
uint8 connection
Connection ID which requested attribute
5 - 6
uint16 handle
Attribute handle requested
7 - 8
uint16 offset
Attribute offset to send data from
9
uint8 maxsize
Maximum data size to respond with
If more data is sent than indicated by this parameter, the extra bytes will be
ignored.
C Functions
/* Callback */
struct ble_msg_attributes_user_read_request_evt_t{
uint8 connection,
uint16 handle,
uint16 offset,
uint8 maxsize
}
void ble_evt_attributes_user_read_request(
const struct ble_msg_attributes_user_read_request_evt_t * msg
)
BGScript Functions
event attributes_user_read_request(connection, handle, offset, maxsize)
Silicon Labs Page of 83 233
Value--attributes
This event is produced at the GATT server when a local attribute value was written by a remote device.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x07 lolen Minimum payload length
2 0x02 class Message class: Attribute Database
3 0x00 method Message ID
4
uint8 connection
Connection handle
5
uint8 reason
Reason why value has changed see: enum Attribute Change Reason
6 - 7
uint16 handle
Attribute handle, which was changed
8 - 9
uint16 offset
Offset into attribute value where data starts
10
uint8array value
Attribute value
C Functions
/* Callback */
struct ble_msg_attributes_value_evt_t{
uint8 connection,
uint8 reason,
uint16 handle,
uint16 offset,
uint8 value_len,
const uint8* value_data
}
void ble_evt_attributes_value(
const struct ble_msg_attributes_value_evt_t * msg
)
BGScript Functions
event attributes_value(connection, reason, handle, offset, value_len, value_data)
Silicon Labs Page of 84 233
5.3 Connection
The Connection class provides methods to manage connections and query their statuses.
Bluetooth
5.3.1 Commands--connection
Connection class commands
Channel Map Get--connection
This command can be used to read the current Channel Map.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x04 method Message ID
4
uint8 connection
Connection handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x07 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x04 method Message ID
4
uint8 connection
Connection handle
5
uint8array map
Current Channel Map. Each bit corresponds to one channel. 0-bit
corresponds to 0 channel. Size of Channel Map is 5 bytes.
: 0-36Channel range
C Functions
/* Function */
void ble_cmd_connection_channel_map_get(
uint8 connection
);
/* Callback */
struct ble_msg_connection_channel_map_get_rsp_t{
uint8 connection,
uint8 map_len,
const uint8* map
}
void ble_rsp_connection_channel_map_get(
const struct ble_msg_connection_channel_map_get_rsp_t * msg
)
BGScript Functions
Silicon Labs Page of 85 233
call connection_channel_map_get(connection)(connection, map_len, map)
Silicon Labs Page of 86 233
Channel Map Set--connection
This command can be used to set the new Channel Map.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x07 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x05 method Message ID
4
uint8 connection
Connection handle
5
uint8array map
New Channel Map. Channel Map is 5 bytes array. Each bit corresponds to
one channel. 0-bit corresponds to 0 channel.
: 0-36Channel range
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x05 method Message ID
4
uint8 connection
Connection handle
5-6
uint8 result 0 : the update was successful
: An error occurred.Non-zero
C Functions
/* Function */
void ble_cmd_connection_channel_map_set(
uint8 connection,
uint8 map_len,
const uint8* map
);
/* Callback */
struct ble_msg_connection_channel_map_set_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_connection_channel_map_set(
const struct ble_msg_connection_channel_map_set_rsp_t * msg
)
BGScript Functions
call connection_channel_map_set(connection, map_len, map)(connection, result)
Silicon Labs Page of 87 233
Disconnect--connection
This command disconnects an active connection.
Bluetooth
When link is disconnected a event is produced.Disconnected
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x00 method Message ID
4
uint8 connection
Connection handle to close
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x00 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 result 0: disconnection procedure successfully started
: An error occurredNon-zero
Table: EVENTS
Event Description
connection disconnected Sent after connection has disconnected
C Functions
/* Function */
void ble_cmd_connection_disconnect(
uint8 connection
);
/* Callback */
struct ble_msg_connection_disconnect_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_connection_disconnect(
const struct ble_msg_connection_disconnect_rsp_t * msg
)
BGScript Functions
call connection_disconnect(connection)(connection, result)
Silicon Labs Page of 88 233
Get Rssi--connection
This command returns the Receiver Signal Strength Indication (RSSI) related to the connection referred to by
the connection handle parameter. If the connection is not open, then the RSSI value returned in the response
packet will be 0x00, while if the connection is active, then it will be some negative value (2's complement form
between 0x80 and 0xFF and never 0x00). Note that this command also returns an RSSI of 0x7F if you request
RSSI on an invalid/unsupported handle.
At -38 dBm the BLE112 receiver is saturated. The measurement value may depend on the used
hardware and design.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x01 method Message ID
4
uint8 connection
Connection handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x02 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x01 method Message ID
4
uint8 connection
Connection handle
5
int8 rssi
RSSI value of the connection in dBm.
: -103 to -38Range
C Functions
/* Function */
void ble_cmd_connection_get_rssi(
uint8 connection
);
/* Callback */
struct ble_msg_connection_get_rssi_rsp_t{
uint8 connection,
int8 rssi
}
void ble_rsp_connection_get_rssi(
const struct ble_msg_connection_get_rssi_rsp_t * msg
)
BGScript Functions
call connection_get_rssi(connection)(connection, rssi)
Silicon Labs Page of 89 233
Get Rssi--connection (Copy)
This command returns the Receiver Signal Strength Indication (RSSI) related to the connection referred to by
the connection handle parameter. If the connection is not open, then the RSSI value returned in the response
packet will be 0x00, while if the connection is active, then it will be some negative value (2's complement form
between 0x80 and 0xFF and never 0x00). Note that this command also returns an RSSI of 0x7F if you request
RSSI on an invalid/unsupported handle.
At -38 dBm the BLE112 receiver is saturated. The measurement value may depend on the used
hardware and design.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x01 method Message ID
4
uint8 connection
Connection handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x02 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x01 method Message ID
4
uint8 connection
Connection handle
5
int8 rssi
RSSI value of the connection in dBm.
: -103 to -38Range
C Functions
/* Function */
void ble_cmd_connection_get_rssi(
uint8 connection
);
/* Callback */
struct ble_msg_connection_get_rssi_rsp_t{
uint8 connection,
int8 rssi
}
void ble_rsp_connection_get_rssi(
const struct ble_msg_connection_get_rssi_rsp_t * msg
)
BGScript Functions
call connection_get_rssi(connection)(connection, rssi)
Silicon Labs Page of 90 233
Get Status--connection
This command returns the status of the given connection.
Status is returned in a event.Status
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x07 method Message ID
4
uint8 connection
Connection handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x07 method Message ID
4
uint8 connection
Connection handle
Table: EVENTS
Event Description
connection status Reports the status of a connection
C Functions
/* Function */
void ble_cmd_connection_get_status(
uint8 connection
);
/* Callback */
struct ble_msg_connection_get_status_rsp_t{
uint8 connection
}
void ble_rsp_connection_get_status(
const struct ble_msg_connection_get_status_rsp_t * msg
)
BGScript Functions
call connection_get_status(connection)(connection)
Silicon Labs Page of 91 233
Slave Latency Disable--connection
This command temporarily enables or disables slave latency.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x09 method Message ID
4
uint8 disable : 0 enables slave latency
1: disables slave latency
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x02 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x09 method Message ID
4 - 5
uint16 result 0 : the request was successful
: An error occurredNon-zero
C Functions
/* Function */
void ble_cmd_connection_slave_latency_disable(
uint8 disable
);
/* Callback */
struct ble_msg_connection_slave_latency_disable_rsp_t{
uint16 result
}
void ble_rsp_connection_slave_latency_disable(
const struct ble_msg_connection_slave_latency_disable_rsp_t * msg
)
BGScript Functions
call connection_slave_latency_disable(disable)(result)
Update--connection
This command updates the connection parameters of a given connection. The parameters have the same
meaning and follow the same rules as for the GAP class command: .Connect Direct
If this command is issued at a master device, it will send parameter update request to the link layer.
Bluetooth
On the other hand if this command is issued at a slave device, it will send L2CAP connection parameter update
request to the master, which may either accept or reject it.
Silicon Labs Page of 92 233
It will take an amount of time corresponding to at least six times the current connection interval before the new
connection parameters will become active.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x09 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x02 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 interval_min
Minimum connection interval (units of 1.25ms)
7 - 8
uint16 interval_max
Maximum connection interval (units of 1.25ms)
9 - 10
uint16 latency
Slave latency which defines how many connections intervals a slave may
skip.
11 - 12
uint16 timeout
Supervision timeout (units of 10ms)
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x02 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 result 0 : the update was successful
: An error occurred.Non-zero
C Functions
/* Function */
void ble_cmd_connection_update(
uint8 connection,
uint16 interval_min,
uint16 interval_max,
uint16 latency,
uint16 timeout
);
/* Callback */
struct ble_msg_connection_update_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_connection_update(
const struct ble_msg_connection_update_rsp_t * msg
)
BGScript Functions
call connection_update(connection, interval_min, interval_max, latency, timeout)(connection,
result)
Silicon Labs Page of 93 233
Silicon Labs Page of 94 233
Version Update--connection
This command requests a version exchange of a given connection.
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x01 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x03 method Message ID
4
uint8 connection
Connection handle
Table: RESPONSE
Byte Type Name Description
0 0x00 hilen Message type: response
1 0x03 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x03 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 result 0 : the request was successful
: An error occurredNon-zero
Table: EVENTS
Event Description
connection version_ind Sent after receiving version indication from other end
C Functions
/* Function */
void ble_cmd_connection_version_update(
uint8 connection
);
/* Callback */
struct ble_msg_connection_version_update_rsp_t{
uint8 connection,
uint16 result
}
void ble_rsp_connection_version_update(
const struct ble_msg_connection_version_update_rsp_t * msg
)
BGScript Functions
call connection_version_update(connection)(connection, result)
Silicon Labs Page of 95 233
5.3.2 Enumerations--connection
Connection class enumerations
Connection Status Flags--connection
The possible connection status flags are described in the table below. The flags field is a bit mask, so multiple
flags can be set at a time. If the bit is 1 the flag is active and if the bit is 0 the flag is inactive.
Table: VALUES
Value Name Description
bit 0 connection_connected This status flag tells the connection exists to a remote device.
bit 1 connection_encrypted This flag tells the connection is encrypted.
bit 2 connection_completed Connection completed flag, which is used to tell a new connection
has been created.
bit 3 connection_parameters_change This flag tells that connection parameters have changed and. It is
set when connection parameters have changed due to a link layer
operation.
Silicon Labs Page of 96 233
5.3.3 Events--connection
Connection class events
Disconnected--connection
This event is produced when a connection is disconnected.
Bluetooth
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x03 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x04 method Message ID
4
uint8 connection
Connection handle
5 - 6
uint16 reason
Disconnection reason code
: disconnected by local user0
C Functions
/* Callback */
struct ble_msg_connection_disconnected_evt_t{
uint8 connection,
uint16 reason
}
void ble_evt_connection_disconnected(
const struct ble_msg_connection_disconnected_evt_t * msg
)
BGScript Functions
event connection_disconnected(connection, reason)
Silicon Labs Page of 97 233
Feature Ind--connection
This event indicates the remote devices features.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x02 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x02 method Message ID
4
uint8 connection
Connection handle
5
uint8array features
CtrData field from LL_FEATURE_RSP - packet
C Functions
/* Callback */
struct ble_msg_connection_feature_ind_evt_t{
uint8 connection,
uint8 features_len,
const uint8* features_data
}
void ble_evt_connection_feature_ind(
const struct ble_msg_connection_feature_ind_evt_t * msg
)
BGScript Functions
event connection_feature_ind(connection, features_len, features_data)
Silicon Labs Page of 98 233
Status--connection
This event indicates the connection status and parameters.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x10 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x00 method Message ID
4
uint8 connection
Connection handle
5
uint8 flags
Connection status flags use -enumeratorconnstatus
6 - 11
bd_addr address
Remote devices Bluetooth address
12
uint8 address_type
Remote address type see: Bluetooth Address Types--gap
13 - 14
uint16 conn_interval
Current connection interval (units of 1.25ms)
15 - 16
uint16 timeout
Current supervision timeout (units of 10ms)
17 - 18
uint16 latency
Slave latency which tells how many connection intervals the slave may
skip.
19
uint8 bonding
Bonding handle if the device has been bonded with.
Otherwise: 0xFF
C Functions
/* Callback */
struct ble_msg_connection_status_evt_t{
uint8 connection,
uint8 flags,
bd_addr address,
uint8 address_type,
uint16 conn_interval,
uint16 timeout,
uint16 latency,
uint8 bonding
}
void ble_evt_connection_status(
const struct ble_msg_connection_status_evt_t * msg
)
BGScript Functions
event connection_status(connection, flags, address, address_type, conn_interval, timeout, latency,
bonding)
Silicon Labs Page of 99 233
Version Ind--connection
This event indicates the remote devices version.
Table: EVENT
Byte Type Name Description
0 0x80 hilen Message type: event
1 0x06 lolen Minimum payload length
2 0x03 class Message class: Connection
3 0x01 method Message ID
4
uint8 connection
Connection handle
5
uint8 vers_nr
Bluetooth
controller specification version
6 - 7
uint16 comp_id
Manufacturer of the controller
Bluetooth
8 - 9
uint16 sub_vers_nr
Bluetooth
controller version
C Functions
/* Callback */
struct ble_msg_connection_version_ind_evt_t{
uint8 connection,
uint8 vers_nr,
uint16 comp_id,
uint16 sub_vers_nr
}
void ble_evt_connection_version_ind(
const struct ble_msg_connection_version_ind_evt_t * msg
)
BGScript Functions
event connection_version_ind(connection, vers_nr, comp_id, sub_vers_nr)
Silicon Labs Page of 100 233
5.4 Generic Access Profile
The Generic Access Profile (GAP) class provides methods to control the GAP level functionality of
Bluetooth
the local device. The GAP call for example allows remote device discovery, connection establishment and local
devices connection and discovery modes. The GAP class also allows the control of local devices privacy
modes.
5.4.1 Commands--gap
Generic Access Profile class commands
Connect Direct--gap
This command will start the GAP direct connection establishment procedure to a dedicated Smart
Bluetooth
device.
The module will enter a state where it continuously scans for the connectable advertisement packets
Bluetooth
from the remote device which matches the Bluetooth address gives as a parameter. Upon receiving the
advertisement packet, the module will send a connection request packet to the target device to imitate a
connection. A successful connection will bi indicated by a event.
Bluetooth
Status
If the device is configured to support more than one connection, the smallest connection interval which is
divisible by will be selected. Thus, it is important to provide minimum and maximum_connections * 2.5ms
maximum connection intervals so that such a connection interval is available within the range.
The connection establishment procedure can be cancelled with command.End Procedure
Table: COMMAND
Byte Type Name Description
0 0x00 hilen Message type: command
1 0x0F lolen Minimum payload length
2 0x06 class Message class: Generic Access Profile
3 0x03 method Message ID
4 - 9
bd_addr address
Bluetooth address of the target device
10
uint8 addr_type
see: Bluetooth Address Types
11 12
uint16 conn_interval_min
Minimum Connection Interval (in units of 1.25ms).
Range: 6 - 3200
The lowest possible Connection Interval is 7.50ms and the largest is
4000ms.
13 14
uint16 conn_interval_max
Maximum Connection Interval (in units of 1.25ms).
Range: 6 - 3200
Must be equal or bigger than minimum Connection Interval.
15 16
uint16
timeout
Supervision Timeout (in units of 10ms). The Supervision Timeout
defines how long the devices can be out of range before the
connection is closed.
Range: 10 - 3200
Minimum time for the Supervision Timeout is 100ms and maximum
value is 32000ms.
Silicon Labs Page of 101 233
Loading...