Silicon Labs BLUEGIGA BLUETOOTH LOW ENERGY SOFTWARE V.1.10 API DOCUMENTATION

BLUEGIGA BLUETOOTH LOW ENERGY SOFTWARE

V.1.10 API DOCUMENTATION Wednesday, Version 4.1

2 December 2020

Table of Contents

1 Version History ________________________________________________________________________ 4 2 Introduction to Bluegiga Bluetooth Low Energy Software ________ ________________________________ 7

2.1 The Bluegiga Bluetooth Low Energy Stack ______________________________________________ 7

2.2 The Bluegiga Bluetooth Low Energy 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 API definition _________________________________________________________________________ 13

3.1 The BGAPI protocol definition ________________________________________________________ 13

3.1.1 Message types ____________________________________________________________ 13

3.1.2 Command Class IDs ________________________________________________________ 15

3.1.3 Packet Exchange __________________________________________________________ 15

3.2 The BGLIB functions definition _______________________________________________________ 19

3.3 The BGScript API definition _________________________________________________________ 20

3.4 Data Types ______________________________________________________________________ 21

4 API Reference ________________________________________________________________________ 22

4.1 Attribute Client ___________________________________________________________________ 23

4.1.1 Commands _______________________________________________________________ 23

4.1.2 Enumerations ______________________________________________________________ 46

4.1.3 Events ___________________________________________________________________ 47

4.2 Attribute Database ________________________________________________________________ 53

4.2.1 Commands ________________________________________________________________ 53

4.2.2 Enumerations ______________________________________________________________ 61

4.2.3 Events ___________________________________________________________________ 63

4.3 Connection ______________________________________________________________________ 66

4.3.1 Commands ________________________________________________________________ 66

4.3.2 Enumerations ______________________________________________________________ 76

4.3.3 Events ____________________________________________________________________ 77

4.4 Generic Access Profile _____________________________________________________________ 81

4.4.1 Commands ________________________________________________________________ 81

4.4.2 Enumerations _____________________________________________________________ 101

4.4.3 Events __________________________________________________________________ 110

4.5 Hardware ______________________________________________________________________ 111

4.5.1 Commands _______________________________________________________________ 111

4.5.2 Events ___________________________________________________________________ 142

4.6 Persistent Store _________________________________________________________________ 148

4.6.1 Commands ______________________________________________________________ 148

4.6.2 Events __________________________________________________________________ 157

4.7 Security Manager ________________________________________________________________ 158

4.7.1 Commands ______________________________________________________________ 158

4.7.2 Enumerations

4.7.3 Events

4.8 System ________________________________________________________________________ 176

4.8.1 Commands

4.8.2 Enumerations

4.8.3 Events

4.9 Testing ________________________________________________________________________ 202

4.9.1 Commands

4.10 Device Firmware Upgrade ________________________________________________________ 208

4.10.1 Commands _____________________________________________________________ 208

4.10.2 Events

4.11 Error Codes ___________________________________________________________________ 214

4.11.1 BGAPI Errors ____________________________________________________________ 214

4.11.2 Bluetooth Errors _________________________________________________________ 215

4.11.3 Security Manager Protocol Errors ____________________________________________ 217

4.11.4 Attribute Protocol Errors ___________________________________________________ 218

____________________________________________________________ 169

__________________________________________________________________ 172

_______________________________________________________________ 176

_____________________________________________________________ 194

__________________________________________________________________ 195

______________________________________________________________ 202

_________________________________________________________________ 213

Silicon Labs Page of 3 220

Version History

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 4 220

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 5 220

Version

3.12 Removed "Introduction to Bluetooth Smart Technology" paragraph Updates for the software v.1.7.0

New BGAPI error code for BGScript stack overflow I2C commands timeout documentation New API added: Get Bootloader Crc New API added: Delay Reset New API added: Get Timestamp New API added: USB Enumeration Status Get New API event added: USB Enumerated

4.0 Updates for the software v.1.8.0

New API event added: Radio Error

4.1 Renamed "Bluetooth Smart" to "Bluetooth Low Energy" according to the official Bluetooth SIG nomenclature.

Silicon Labs Page of 6 220

The Bluegiga Low Energy Software enables developers to quickly and easily develop Low

Bluetooth Bluetooth

Energy applications without in-depth knowledge of the Low Energy technology. The Low

Bluetooth Bluetooth

Energy Software consists of two main parts:

The Low Energy Stack

Bluetooth

The Low Energy Software Development Kit (SDK)

Bluetooth

2.1

The Low Energy is meant for the Bluegiga Low Energy products such as BLE112, BLE113

Bluetooth Bluetooth

BLE121LR and BLED112.

Figure: The Bluegiga Bluetooth Low Energy Stack

Introduction to Bluegiga Bluetooth Low Energy Software

The Bluegiga Bluetooth Low Energy Stack

The

Bluetooth Bluetooth

slave 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 Low Energy 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.

Low Energy stack is a fully

4.0 single mode compatible software stack implementing

Silicon Labs Page of 7 220

2.2 The Bluegiga Bluetooth Low Energy SDK

The Bluegiga Low Energy SDK is a software development kit, which enables the device and software

Bluetooth

vendors to develop products on top of the Bluegiga’s Low Energy hardware and software.

Bluetooth

The Low Energy 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 Low Energy

Bluetooth

modules. 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 Low Energy

The BGAPI protocol

is a binary based commend and response protocol that allows the Bluetooth Low Energy 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 Low Energy 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

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 Low Energy services and characteristics on a device.

Each of these components are described in more detail in the following chapters.

Silicon Labs Page of 8 220

2.3

needed between the host and the Low Energy stack. The transport protocol is used to communicate

Bluetooth

with 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 Low Energy Stack:

Bluetooth

The BGAPI TM Protocol

For applications where a separate host is used to implement the end user application, a transport protocol is

Generic

open connections

Security Attribute Database - An class to access the local Attribute Database Attribute Connection - Provides an interface to manage 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 non-

volatile memory

System

Access Profile

Manager -

Client - Provides

- Various system functions, such as querying the hardware status or reset it

- GAP allows the management of discoverability and connetability modes and

Provides access the

an interface

Bluetooth

discover, read

low energy security functions

write remote attributes

and

Bluetooth

low energy connections

Silicon Labs Page of 9 220

2.4

Figure: The BGLIB host library

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 Low Energy SDK. The purpose is to simplify the application development to various host environments.

Bluetooth

Silicon Labs Page of 10 220

2.5

The BGScript TM Scripting Language

without a separate host MCU and run all the application code on the Bluegiga Low Energy modules.

Bluetooth

The Low Energy modules can run simple applications along the Low Energy stack and this

Bluetooth Bluetooth

provides a benefit when one needs to minimize the end product’s size, cost and current consumption. For developing standalone Low Energy applications the SDK includes a BGScript VM, compiler and other

Bluetooth

BGScript development tools. 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

The

Bluetooth

Low Energy SDK Also allows the application developers to create fully standalone devices

Silicon Labs Page of 11 220

2.6

The Profile Toolkit TM

Figure: A profile toolkit example of GAP service

The

Bluetooth

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.

Low Energy profile toolkit is a simple set of tools, which can used to describe GATT based

Low Energy services and characteristics. The profile toolkit consists of a simple XML based

Silicon Labs Page of 12 220

3 API definition

The BGAPI host protocol API definition

The BGLIB host library API description

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:

... 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

Bluetooth

3.1.1 Message types

The following message types exist in the BGAPI protocol.

Table: BGAPI message types

This section of the document contains the generic Bluetooth Low Energy Stack API definition. The definition consist of three parts:

The BGScript scripting language API description

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

3.1 The BGAPI protocol definition

The BGAPI protocol is a command, response and event protocol that can be used to communicate with the

Bluetooth

used to instruct the

Bluetooth Bluetooth

The BGAPI commands, responses and events use a binary format and the generic protocol format is described in this section.

BGAPI Packet format

Low Energy stack over one of the physical interfaces like UART or USB. The BGAPI protocol can be

Bluetooth

devices or access the physical interfaces like SPI or I2C of the

Low Energy stack to do something like advertise, discover and connect other

Low Energy module.

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

bytes and header so the maximum payload size is 60 bytes.

longer packet sizes cannot be used. Four (4) bytes will be used for the BGAPI protocol

Low Energy

products the maximum allowed BGAPI packet size is 64

Low EnergyBluetooth

: Wi-Fi0001

Silicon Labs Page of 13 220

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 14 220

3.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

Provides access to local GATT database 0x03 Connection Provides access to connection management functions 0x04

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

3.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.

Attribute Database

Attribute Client

Silicon Labs Page of 15 220

The Application should always wait for the response to a command before issuing another command.

Silicon Labs Page of 16 220

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 Low Energy

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 17 220

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 18 220

3.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 Low Energy 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

are not familiar with callback programming a basic tutorial can for example be found

If you

architecture

from

http://www.codeguru.com/cpp/cpp/cpp_mfc/callbacks/article.php/c10557

here:

Silicon Labs Page of 19 220

3.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 20 220

3.4

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

The following data types are used in this documentation.

Table: Used data types

Silicon Labs Page of 21 220

4 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

Provides access to local GATT database and allows data to be written there for remote devices to access it.

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

Attribute protocols errors

Attribute Database

Attribute Client

Security Manager errors

Silicon Labs Page of 22 220

4.1

Attribute Client

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

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

The Attribute Client class implements the to the 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.

Bluetooth

Low Energy Attribute Protocol (ATT) and provides access

4.1.1 Commands

Attribute Client commands

Attribute Write

This command can be used to write an attributes value on a remote device. In order to write the value of an attribute a A successful attribute write will be acknowledged by the remote device and this will generate an event

the Bluetooth connection will be dropped.

Bluetooth

connection must exists and you need to know the handle of the attribute you want to write.

. The acknowledgement should happen within a 30 second window or otherwise attclient_procedure_completed

Silicon Labs Page of 23 220

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 24 220

Execute Write

command on a remote prepare_write

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

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)

This command can be used to execute or cancel a previously queued device.

Table: COMMAND

Silicon Labs Page of 25 220

Silicon Labs Page of 26 220

Find By Type Value

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

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

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

Silicon Labs Page of 27 220

);

/* 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 28 220

Find Information

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 )

This command is used to discover attribute handles and their types (UUIDs) in a given handle range.

Table: COMMAND

Silicon Labs Page of 29 220

BGScript Functions

call attclient_find_information(connection, start, end)(connection, result)

Silicon Labs Page of 30 220

Indicate Confirm

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)

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 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.

Bluetooth

Low Energy

stack

Silicon Labs Page of 31 220

Prepare Write

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

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

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

event.Completed

The example below shows how this approach can be used to write a 30-byte characteristic value:

command, which if acknowledged by the remote device triggers a Execute Write Procedure

Silicon Labs Page of 32 220

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 33 220

Read By Group Type

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

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 */

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

Table: COMMAND

event is generated.Procedure Completed

Silicon Labs Page of 34 220

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 35 220

Read By Handle

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 )

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.

Silicon Labs Page of 36 220

BGScript Functions

call attclient_read_by_handle(connection, chrhandle)(connection, result)

Silicon Labs Page of 37 220

Read By Type

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

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 */

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

Silicon Labs Page of 38 220

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 39 220

Read Long

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

This command can be used to read long attribute values, which are longer than 22 bytes and cannot be read with a simple

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

command.Read by Handle

Silicon Labs Page of 40 220

)

BGScript Functions

call attclient_read_long(connection, chrhandle)(connection, result)

Silicon Labs Page of 41 220

Read Multiple

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

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

This command can be used to read multiple attributes from a server.

Table: COMMAND

Silicon Labs Page of 42 220

call attclient_read_multiple(connection, handles_len, handles_data)(connection, result)

Silicon Labs Page of 43 220

Write Command

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

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(

Writes the value of a remote devices attribute. The handle and the new value of the attribute are gives as parameters.

Silicon Labs Page of 44 220

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 45 220

4.1.2

Enumerations

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.

Attribute Client enumerations

Attribute Value Types

These enumerations are in the Attribute Client class

Table: VALUES

Silicon Labs Page of 46 220

4.1.3

Events

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

uint8 type

Attribute type

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)

Attribute Client events

Attribute Value

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 attribute is indicated or notified by the remote device.

Table: EVENT

operation or when an Read by Handle

Silicon Labs Page of 47 220

Find Information Found

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

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)

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

Silicon Labs Page of 48 220

Group Found

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.

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)

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

Silicon Labs Page of 49 220

Indicated

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)

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

Silicon Labs Page of 50 220

Procedure Completed

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)

This event is produced at the GATT client when an attribute protocol event is completed a and new operation can be issued.

Silicon Labs Page of 51 220

Read Multiple Response

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

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 52 220

4.2

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

uint8array value

Value of the attribute

C Functions

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

4.2.1 Commands

Attribute Database commands

Read

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:

Bluetooth

connection.

Silicon Labs Page of 53 220

/* 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 54 220

Read Type

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

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)

This command reads the given attribute's type (UUID) from the local database.

Table: COMMAND

Silicon Labs Page of 55 220

Send

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.

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 )

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

Silicon Labs Page of 56 220

BGScript Functions

call attributes_send(connection, handle, value_len, value_data)(result)

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

uint8 att_error 0: User Read Request is responded with data.

In case of an error an application specific error code can be sent.

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

User Read Response

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 with

the data in it's local GATT database.

Bluetooth

Low Energy

stack automatically responding

This command is normally used in response to a device tries to read an attribute with a user property enabled.

event, which is generated when a remote User Read Request

Silicon Labs Page of 57 220

call attributes_user_read_response(connection, att_error, value_len, value_data)

Silicon Labs Page of 58 220

User Write Response

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

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)

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

Bluetooth

Low Energy

stack doing it automatically.

Silicon Labs Page of 59 220

Write

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

uint8 offset

Attribute offset to write data

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)

This command writes an attribute's value to the local database.

Table: COMMAND

Silicon Labs Page of 60 220

4.2.2

Enumerations

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

Attribute Database enumerations

Attribute Change Reason

This enumeration contains the reason for an attribute value change.

Table: VALUES

remote device, but the Energy 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.

stack is waiting for the write to

Bluetooth

Low

See

Profile Toolkit Developer Guide

more information how to enable the user property for an attribute.

for

Silicon Labs Page of 61 220

Attribute Status Flags

Value Name Description

1 attributes_attribute_status_flag_notify Notifications are enabled 2 attributes_attribute_status_flag_indicate Indications are enabled

Attribute status flags

Table: VALUES

Silicon Labs Page of 62 220

4.2.3

Events

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

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)

Attribute Database events

Status

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

Silicon Labs Page of 63 220

User Read Request

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

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)

This event is generated when a remote device tries to read an attribute which has the user property enabled.

Silicon Labs Page of 64 220

Value

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

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

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)

This event is produced at the GATT server when a local attribute value was written by a remote device.

Table: EVENT

Silicon Labs Page of 65 220

4.3

Connection

connections and query their statuses.

Bluetooth

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

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

The Connection class provides methods to manage

4.3.1 Commands

Connection class commands

Channel Map Get

Silicon Labs Page of 66 220

call connection_channel_map_get(connection)(connection, map_len, map)

Silicon Labs Page of 67 220

Channel Map Set

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

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)

This command can be used to set the new Channel Map.

Table: COMMAND

Silicon Labs Page of 68 220

Disconnect

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)

This command disconnects an active

Silicon Labs Page of 69 220

Get Rssi

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

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)

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.

Silicon Labs Page of 70 220

Get Status

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)

This command returns the status of the given connection. Status is returned in a

event.Status

Table: COMMAND

Silicon Labs Page of 71 220

Slave Latency Disable

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)

This command temporarily enables or disables slave latency.

Table: COMMAND

Update

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 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 72 220

Bluetooth

link layer.

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 73 220

Silicon Labs Page of 74 220

Version Update

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)

This command requests a version exchange of a given connection.

Table: COMMAND

Silicon Labs Page of 75 220

4.3.2

Enumerations

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.

Connection class enumerations

Connection Status Flags

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

Silicon Labs Page of 76 220

4.3.3

Events

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)

Connection class events

Disconnected

Silicon Labs Page of 77 220

Feature Ind

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

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)

This event indicates the remote devices features.

Table: EVENT

Silicon Labs Page of 78 220

Status

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

uint8 flags

Connection status flags use -enumeratorconnstatus

6 - 11

bd_addr address

Remote devices Bluetooth address

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.

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)

This event indicates the connection status and parameters.

Table: EVENT

Silicon Labs Page of 79 220

Version Ind

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

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)

This event indicates the remote devices version.

Table: EVENT

Silicon Labs Page of 80 220

4.4

Generic Access Profile

Bluetooth

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

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.

The Generic Access Profile (GAP) class provides methods to control the 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.

Bluetooth

GAP level functionality of

4.4.1 Commands

Generic Access Profile class commands

Connect Direct

This command will start the GAP direct connection establishment procedure to a dedicated

Energy device.

Low

Silicon Labs Page of 81 220

Byte Type Name Description

According to the specification, the Supervision Timeout in milliseconds shall be larger than (1 + latency) * conn_interval_max

, where conn_interval_max is given in milliseconds.* 2

17 18

uint16 latency

This parameter configures the slave latency. Slave latency defines how many connection intervals a slave device can skip. Increasing slave latency will decrease the energy consumption of the slave in scenarios where slave does not have data to send at every connection interval.

Range: 0 - 500 0 : Slave latency is disabled.

Example:

Connection interval is 10ms and slave latency is 9: this means that the slave is allowed to communicate every 100ms, but it can communicate every 10ms if needed.

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: response 1 0x03 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x03 method Message ID 4 - 5

uint16 result 0 : procedure was successfully started

: An error occurredNon-zero

uint8 connection_handle

Connection handle that is reserved for new connection

Table: EVENTS

Event Description

connection status Sent after connection is established

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, uint16 latency );

/* Callback */

struct ble_msg_gap_connect_direct_rsp_t{ uint16 result, uint8 connection_handle }

void ble_rsp_gap_connect_direct(

const struct ble_msg_gap_connect_direct_rsp_t * msg )

Silicon Labs Page of 82 220

BGScript Functions

call gap_connect_direct(address, addr_type, conn_interval_min, conn_interval_max, timeout, latency) (result, connection_handle)

Silicon Labs Page of 83 220

Connect Selective

device, and a successful connection will produce a event.connection status The connect selective command can be cancelled with command.End Procedure When in there are no events

Initiating State

scan response

Table: COMMAND

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x08 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x05 method Message ID 4 - 5

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. When more then one connection is supported the connection interval values (minimum and maximum) used in connection commands all must be divisible by *

connection count 2.5ms

6 - 7

uint16 conn_interval_max

Maximum connection interval (in units of 1.25ms).

Range: 6 - 3200

Must be equal or bigger than minimum connection interval.

8 - 9

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: 32000ms. Supervision timeout must also be equal or grater than maximum connection interval.

10 11

uint16

latency

Range: 0 - 500 0 : Slave latency is disabled.

Example:

Connection interval is 10ms and slave latency is 9: this means that the slave is allowed to communicate every 100ms, but it can communicate

This command will start the GAP direct connection establishment procedure to a set of dedicated Bluetooth Low Energy devices.

When this command is issued the the advertisement packets from the remote devices which are registered in the local white list. Upon receiving an advertisement packet from one of the registered devices, the module will send a connection request to this

Bluetooth

module will enter a state where it scans connectable

Silicon Labs Page of 84 220

Byte Type Name Description

every 10ms if needed.

Note:

x can NOT be higher than

Slave Latency Connection interval

supervision timeout.

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x03 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x05 method Message ID 4 - 5

uint16 result 0: Command was executed successfully

: An error occurredNon-zero

uint8 connection_handle

Connection handle reserved for connection

Table: EVENTS

Event Description

connection status Sent after connected to any whitelisted device

C Functions

/* Function */

void ble_cmd_gap_connect_selective(

uint16 conn_interval_min, uint16 conn_interval_max, uint16 timeout, uint16 latency );

/* Callback */

struct ble_msg_gap_connect_selective_rsp_t{ uint16 result, uint8 connection_handle }

void ble_rsp_gap_connect_selective(

const struct ble_msg_gap_connect_selective_rsp_t * msg )

BGScript Functions

call gap_connect_selective(conn_interval_min, conn_interval_max, timeout, latency)(result, connection_handle)

Silicon Labs Page of 85 220

Discover

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x01 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x02 method Message ID 4

uint8 mode

see:GAP Discover Mode

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: response 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x02 method Message ID 4 - 5

uint16 result 0: Scan procedure was successfully started

: An error occurredNon-zero

Table: EVENTS

Event Description

gap scan_response Discovered device scan response

C Functions

/* Function */

void ble_cmd_gap_discover(

uint8 mode );

/* Callback */

struct ble_msg_gap_discover_rsp_t{ uint16 result }

void ble_rsp_gap_discover(

const struct ble_msg_gap_discover_rsp_t * msg )

BGScript Functions

call gap_discover(mode)(result)

This command starts the GAP discovery procedure to scan for advertising devices i.e. to perform a device discovery. Scanning parameters can be configured with the Set Scan Parameters To cancel on an ongoing discovery process use the End Procedure

Table: COMMAND

Silicon Labs Page of 86 220

End Procedure

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x00 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x04 method Message ID

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: response 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x04 method Message ID 4 - 5

uint16 result 0: the command was successful

: An error occurredNon-zero

C Functions

/* Function */

void ble_cmd_gap_end_procedure(

void );

/* Callback */

struct ble_msg_gap_end_procedure_rsp_t{ uint16 result }

void ble_rsp_gap_end_procedure(

const struct ble_msg_gap_end_procedure_rsp_t * msg )

BGScript Functions

call gap_end_procedure()(result)

This command ends the current GAP discovery procedure and stop the scanning of advertising devices.

Table: COMMAND

Silicon Labs Page of 87 220

Set Adv Data

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x09 method Message ID 4

uint8 set_scanrsp

Advertisement data type

0 : sets advertisement data

1 : sets scan response data

uint8array adv_data

Advertisement data to send

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x09 method Message ID 4 - 5

uint16 result

Command result

C Functions

/* Function */

void ble_cmd_gap_set_adv_data(

uint8 set_scanrsp, uint8 adv_data_len, const uint8* adv_data_data );

/* Callback */

struct ble_msg_gap_set_adv_data_rsp_t{ uint16 result }

void ble_rsp_gap_set_adv_data(

const struct ble_msg_gap_set_adv_data_rsp_t * msg )

BGScript Functions

call gap_set_adv_data(set_scanrsp, adv_data_len, adv_data_data)(result)

This commands set advertisement or scan response data used in the advertisement and scan response packets. The command allows application specific data to be broadcasts either in advertisement or scan response packets.

The data set with this command is only used when the Notice that advertisement or scan response data must be formatted in accordance to the Bluetooth Core

Specification. See BLUETOOTH SPECIFICATION Version 4.0 [Vol 3 - Part C - Chapter 11].

Table: COMMAND

mode is set to gap_user_data.GAP discoverable

Silicon Labs Page of 88 220

Set Adv Parameters

If you are currently advertising, then any changes set using this command will not take effect until you stop and re-start advertising.

Table: COMMAND

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x05 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x08 method Message ID 4 - 5

uint16 adv_interval_min

Minimum advertisement interval in units of 625us

Range: 0x20 to 0x4000

(320ms)Default: 0x200

Explanation:

0x200 = 512 512 * 625us = 320000us = 320ms

6 - 7

uint16 adv_interval_max

Maximum advertisement interval in units of 625us.

Range: 0x20 to 0x4000

(320ms)Default: 0x200

uint8 adv_channels

A bit mask to identify which of the three advertisement channels are used.

Examples:

All three channels are used0x07:

: Advertisement channels 37 and 38 are used.0x03

Only advertisement channel 39 is used0x04:

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x08 method Message ID 4 - 5

uint16 result 0: Command was successfully executed

: An error occurredNon-zero

This command is used to set the advertising parameters. Example: If the minimum advertisement interval is 40ms and the maximum advertisement interval is 100ms

then the real advertisement interval will be mostly the middle value (70ms) plus a randomly added 20ms delay, which needs to be added according to the Bluetooth specification.

Silicon Labs Page of 89 220

C Functions

/* Function */

void ble_cmd_gap_set_adv_parameters(

uint16 adv_interval_min, uint16 adv_interval_max, uint8 adv_channels );

/* Callback */

struct ble_msg_gap_set_adv_parameters_rsp_t{ uint16 result }

void ble_rsp_gap_set_adv_parameters(

const struct ble_msg_gap_set_adv_parameters_rsp_t * msg )

BGScript Functions

call gap_set_adv_parameters(adv_interval_min, adv_interval_max, adv_channels)(result)

Silicon Labs Page of 90 220

Set Directed Connectable Mode

the parameters defined by this characteristic will be used for the connection.characteristic in its GAP service

Table: COMMAND

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x07 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x0A method Message ID 4 - 9

bd_addr address

Bluetooth address to connect to

uint8 addr_type

Address type to connect see:enum gap_address_type

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x0A method Message ID 4 - 5

uint16 result

Command result

Table: EVENTS

Event Description

connection status Sent after connection is established

C Functions

/* Function */

void ble_cmd_gap_set_directed_connectable_mode(

bd_addr address, uint8 addr_type );

/* Callback */

struct ble_msg_gap_set_directed_connectable_mode_rsp_t{ uint16 result }

void ble_rsp_gap_set_directed_connectable_mode(

const struct ble_msg_gap_set_directed_connectable_mode_rsp_t * msg )

BGScript Functions

call gap_set_directed_connectable_mode(address, addr_type)(result)

This command sets device to Directed Connectable mode. In this mode the device uses fast advertisement procedure for the first 1.28 seconds, after which the device

enters a non-connectable mode. If the device implements the Peripheral Preferred Connection Parameters

Silicon Labs Page of 91 220

Set Filtering

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x03 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x06 method Message ID 4

uint8 scan_policy

see: enum gap_scan_policy

uint8 adv_policy

see: enum gap_advertising_policy

uint8 scan_duplicate_filtering 0: Do not filter duplicate advertisers

Filter duplicates1:

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x06 method Message ID 4 - 5

uint16 result 0: The command was successfully executed

: An error occurredNon-zero

C Functions

/* Function */

void ble_cmd_gap_set_filtering(

uint8 scan_policy, uint8 adv_policy, uint8 scan_duplicate_filtering );

/* Callback */

struct ble_msg_gap_set_filtering_rsp_t{ uint16 result }

void ble_rsp_gap_set_filtering(

const struct ble_msg_gap_set_filtering_rsp_t * msg )

BGScript Functions

call gap_set_filtering(scan_policy, adv_policy, scan_duplicate_filtering)(result)

This command can be used to set scan, connection, and advertising filtering parameters based on the local devices white list. See also

Table: COMMAND

command.Whitelist Append

Silicon Labs Page of 92 220

Set Initiating Con Parameters

This command sets the scan parameters for Initiating State which affect for establishing BLE connection. See BLUETOOTH SPECIFICATION Version 4.0 [Vol 6 - Part B - Chapter 4.4.4].

Table: COMMAND

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x04 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x0B method Message ID 4 - 5

uint16 scan_interval

Scan interval defines the interval when scanning is re-started in units of 625us

Range: 0x4 - 0x4000 Default: (31,25ms)0x32

After every scan interval the scanner will change the frequency it operates at at it will cycle through all the three advertisements channels in a round robin fashion. According to the specification all three channels must be

Bluetooth

used by a scanner.

6 - 7

uint16 scan_window

Scan Window defines how long time the scanner will listen on a certain frequency and try to pick up advertisement packets. Scan window is defined as units of 625us

Range: 0x4 - 0x4000 Default: 0x32 (31,25ms)

Scan windows must be equal or smaller than scan interval If scan window is equal to the scan interval value, then the module

Bluetooth

will be scanning at a 100% duty cycle. If scan window is half of the scan interval value, then the module

Bluetooth

will be scanning at a 50% duty cycle.

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x0B method Message ID 4 - 5

uint16 result 0: The command was executed successfully

: An error occurredNon-zero

C Functions

/* Function */

void ble_cmd_gap_set_initiating_con_parameters(

uint16 scan_interval, uint16 scan_window

Silicon Labs Page of 93 220

);

/* Callback */

struct ble_msg_gap_set_initiating_con_parameters_rsp_t{ uint16 result }

void ble_rsp_gap_set_initiating_con_parameters(

const struct ble_msg_gap_set_initiating_con_parameters_rsp_t * msg )

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x01 method Message ID 4

uint8 discover

see:GAP Discoverable Mode

uint8 connect

see:GAP Connectable Mode

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: response 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x01 method Message ID 4 - 5

uint16 result 0: the command was executed successfully

: An error occurredNon-zero

Table: EVENTS

Event Description

connection status Sent if device was connectable and master connected to device

C Functions

/* Function */

void ble_cmd_gap_set_mode(

uint8 discover, uint8 connect );

/* Callback */

struct ble_msg_gap_set_mode_rsp_t{ uint16 result }

void ble_rsp_gap_set_mode(

Set Mode

This command configures the current GAP discoverability and connectability modes. It can be used to enable advertisements and/or allow connection. The command is also meant to fully stop advertising, when using gap_non_discoverable and gap_non_connectable.

Table: COMMAND

Silicon Labs Page of 94 220

const struct ble_msg_gap_set_mode_rsp_t * msg )

BGScript Functions

call gap_set_mode(discover, connect)(result)

Silicon Labs Page of 95 220

Set Nonresolvable Address

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x06 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x0C method Message ID 4 - 9

bd_addr address

Bluetooth non-resolvable address of the local device

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: response 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x0C method Message ID 4 - 5

uint16 result 0: Command was successfully executed

: An error occurredNon-zero

C Functions

/* Function */

void ble_cmd_gap_set_nonresolvable_address(

bd_addr address );

/* Callback */

struct ble_msg_gap_set_nonresolvable_address_rsp_t{ uint16 result }

void ble_rsp_gap_set_nonresolvable_address(

const struct ble_msg_gap_set_nonresolvable_address_rsp_t * msg )

BGScript Functions

call gap_set_nonresolvable_address(address)(result)

This command set the local device's random Non-Resolvable Bluetooth address. Default local device's random Non-Resolvable Bluetooth address is 00:00:00:00:00:01.

Table: COMMAND

Silicon Labs Page of 96 220

Set Privacy Flags

demand. If peripherial_privacy is set to 2 additionally is called with the current Discoverable and Set Mode Connectable parameters. Setting up new mode by command does not change generated address.Set Mode

By setting privacy mode to 3, the stack will use a non-resolvable random private address (set by

Bluetooth

Set

command). For example if peripheral_privacy is set to 3, the stack will get a Nonresolvable Address

Bluetooth

non-resolvable random private address for the advertising packets every time the command is used Set Mode to enter advertising mode.

It is not recommended to adjust peripheral privacy unless mandatory by the application, because not all implementations can decode resolvable private addresses.

Bluetooth

Table: COMMAND

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x00 method Message ID 4

uint8 peripheral_privacy 3: enable peripheral privacy with non-resolvable address

2: change peripheral private address on demand 1: enable peripheral privacy 0: disable peripheral privacy

Any other value will have no effect on flag

uint8 central_privacy :3 enable central privacy with non-resolvable address

2: change central private address on demand 1: enable central privacy 0: disable central privacy

Any other value will have no effect on flag

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x00 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile

This command sets GAP central/peripheral privacy flags. By setting for example peripheral_privacy to 1, the

random private address for the advertising packets every time the advertising mode.

By setting privacy mode to 2, the

Bluetooth

stack will generate a resolvable random private address on

Bluetooth

stack will automatically generate a resolvable

command is used to enter Set Mode

Silicon Labs Page of 97 220

Byte Type Name Description

3 0x00 method Message ID

C Functions

/* Function */

void ble_cmd_gap_set_privacy_flags(

uint8 peripheral_privacy, uint8 central_privacy );

/* Callback *

void ble_rsp_gap_set_privacy_flags(

const void *nul )

BGScript Functions

call gap_set_privacy_flags(peripheral_privacy, central_privacy)

Silicon Labs Page of 98 220

Set Scan Parameters

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x05 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile 3 0x07 method Message ID 4 - 5

uint16 scan_interval

Scan interval defines the interval when scanning is re-started in units of 625us

Range: 0x4 - 0x4000 Default: (46,875ms)0x4B

Bluetooth

used by a scanner.

6 - 7

uint16 scan_window

Scan Window defines how long time the scanner will listen on a certain frequency and try to pick up advertisement packets. Scan window is defined as units of 625us

Range: 0x4 - 0x4000 Default: 0x32 (31,25 ms)

Scan windows must be equal or smaller than scan interval If scan window is equal to the scan interval value, then the module

Bluetooth

will be scanning at a 100% duty cycle. If scan window is half of the scan interval value, then the module

Bluetooth

will be scanning at a 50% duty cycle.

uint8 active 1: Active scanning is used. When an advertisement packet is received the

stack will send a scan request packet to the advertiser to try and

Bluetooth

read the scan response data. 0: Passive scanning is used. No scan request is made.

Keep in mind that when scan window value is equal to scan interval value, CPU may not have enough time to switch between speed of the system clock when using slow clock option and as a result the current consumption may not decrease.

Table: RESPONSE

Byte Type Name Description

0 0x00 hilen Message type: command 1 0x02 lolen Minimum payload length 2 0x06 class Message class: Generic Access Profile

This command sets the scan parameters which affect how other discovered. See

Table: COMMAND

BLUETOOTH SPECIFICATION Version 4.0 [Vol 6 - Part B - Chapter 4.4.3].

Bluetooth

Low Energy

devices are

Silicon Labs Page of 99 220

Byte Type Name Description

3 0x07 method Message ID 4 - 5

uint16 result 0: The command was executed successfully

: An error occurredNon-zero

C Functions

/* Function */

void ble_cmd_gap_set_scan_parameters(

uint16 scan_interval, uint16 scan_window, uint8 active );

/* Callback */

struct ble_msg_gap_set_scan_parameters_rsp_t{ uint16 result }

void ble_rsp_gap_set_scan_parameters(

const struct ble_msg_gap_set_scan_parameters_rsp_t * msg )

BGScript Functions

call gap_set_scan_parameters(scan_interval, scan_window, active)(result)

Silicon Labs Page of 100 220

4.4.2

Enumerations

Value Name Description

0x01 GAP_AD_FLAG_LIMITED_DISCOVERABLE Limited discoverability 0x02 GAP_AD_FLAG_GENERAL_DISCOVERABLE General discoverability 0x04 GAP_AD_FLAG_BREDR_NOT_SUPPORTED BR/EDR not supported 0x10 GAP_AD_FLAG_SIMULTANEOUS_LEBREDR_CTRL BR/EDR controller 0x20 GAP_AD_FLAG_SIMULTANEOUS_LEBREDR_HOST BE/EDR host 0x1f GAP_AD_FLAG_MASK -

Generic Access Profile class enumerations

AD_FLAGS

Scan header flags

Table: VALUES

Silicon Labs Page of 101 220

Silicon Labs BLUEGIGA BLUETOOTH LOW ENERGY SOFTWARE V.1.10 API DOCUMENTATION

Specifications and Main Features

Frequently Asked Questions

User Manual

Version History

Introduction to Bluegiga Bluetooth Low Energy Software

The Bluegiga Bluetooth Low Energy Stack

The BGAPI TM Protocol

The BGLIB TM Host Library

The BGScript TM Scripting Language

The Profile Toolkit TM

Data Types

Attribute Client

Attribute Database

Connection

Generic Access Profile

Set Initiating Con Parameters