Silicon Labs Bluetooth Smart Software API Reference Manual
Bluetooth Smart Software API Reference
Manual
This document contains the full API reference for the Silicon Labs Bluetooth Smart Software, version
2.6.1.
The Blue Gecko family of the Silicon Labs' Bluetooth Smart chipsets deliver a high performance, low
energy and easy-to-use Bluetooth Smart solution integrated into a small form factor package.
The ultra-low power operating modes and fast wake-up times of the Silicon Labs' energy friendly 32bit MCUs, combined with the low transmit and receive power consumption of the Bluetooth radio,
result in a solution optimized for battery powered applications.
silabs.com | Building a more connected world. Rev. 2.5
Table of Contents
1. Data types ................................
4
2. API Reference ...............................5
2.1 Cooexistence interface (coex) ........................6
2.1.1 coex commands ...........................6
2.1.2 coex enumerations ..........................7
2.2 Device Firmware Upgrade (dfu) ........................9
2.2.1 dfu commands ...........................9
2.2.2 dfu events .............................13
2.3 Endpoint (endpoint) ............................15
2.3.1 endpoint commands..........................15
2.4 Persistent Store (flash) ...........................17
2.4.1 flash commands ...........................17
2.4.2 flash events ............................21
2.5 Generic Attribute Profile (gatt) ........................23
2.5.1 gatt commands ...........................23
2.5.2 gatt events .............................47
2.5.3 gatt enumerations ..........................54
2.6 Generic Attribute Profile Server (gatt_server) ...................56
2.6.1 gatt_server commands .........................56
2.6.2 gatt_server events ..........................64
2.6.3 gatt_server enumerations ........................69
2.7 Hardware (hardware) ...........................70
2.7.1 hardware commands .........................70
2.7.2 hardware events ...........................75
2.8 Connection management for low energy (le_connection) ...............76
2.8.1 le_connection commands ........................76
2.8.2 le_connection events .........................82
2.8.3 le_connection enumerations .......................87
2.9 Generic Access Profile, Low Energy (le_gap) ...................88
2.9.1 le_gap commands ..........................88
2.9.2 le_gap events ...........................106
2.9.3 le_gap enumerations ........................109
2.10 Security Manager (sm) .........................112
2.10.1 sm commands ..........................112
2.10.2 sm events ............................127
2.10.3 sm enumerations .........................134
2.11 System (system) ...........................136
2.11.1 system commands .........................136
2.11.2 system events ..........................143
2.12 testing commands (test) .........................147
2.12.1 test commands ..........................147
2.12.2 test events ...........................150
silabs.com | Building a more connected world. Rev. 2.5 | 2
2.12.3 test enumerations .........................150
2.13 User messaging (user) .........................152
2.13.1 user commands ..........................152
2.13.2 user events ...........................152
2.14 Error codes .............................153
3. Document Revision History .........................160
silabs.com | Building a more connected world. Rev. 2.5 | 3
Bluetooth Smart Software API Reference Manual
Data types
1. Data types
Data types used in the documentation are shown in the table below. Unless otherwise noted, all multi-byte fields are in little endian
format.
Table 1.1. Data types
Name Length Description
errorcode 2 bytes Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
int16 2 bytes Signed 16-bit integer
bd_addr 6 bytes Bluetooth address
uint16 2 bytes Unsigned 16-bit integer
int32 4 bytes Signed 32-bit integer
uint32 4 bytes Unsigned 32-bit integer
link_id_t 2 bytes Link ID
int8 1 byte Signed 8-bit integer
uint8 1 byte Unsigned 8-bit integer
uint8array 1 - 256 bytes Variable length byte array. The first byte defines the length of the data that follows, 0 -
255 bytes.
ser_name 16 bytes Service name, 16-byte array
dbm 1 byte Signal strength
connection 1 byte Connection handle
service 4 bytes GATT service handle
This value is normally received from the gatt_service event.
characteristic 2 bytes GATT characteristic handle
This value is normally received from the gatt_characteristic event.
descriptor 2 bytes GATT characteristic descriptor handle
uuid 1 byte Universal Unique Identifier (UUID)
att_errorcode 1 byte Attribute protocol error code
• 0: No error
• Non-zero: See Bluetooth specification, Host volume, Attribute Protocol, Error Codes
table.
att_opcode 1 byte Attribute opcode which informs the procedure from which attribute the value was re-
ceived
uuid_128 16 bytes 128-bit UUID
aes_key_128 16 bytes 128-bit AES Key
silabs.com | Building a more connected world. Rev. 2.5 | 4
Bluetooth Smart Software API Reference Manual
API Reference
2. API Reference
This section describes all commands, enumerations, responses, events and errors. Commands with related enumerations, responses
and events are grouped according to command classes.
BGAPI Payload
The parameters of a BGAPI command, response or event are passed between the application and firmware in a payload. For example,
a parameter of uint32 type uses 4 bytes of the payload space. A byte array parameter uses one byte to describe the length of the array
and the actual data in array is copied into the remaining free payload space.
Maximum BGAPI Payload Size
The maximum BGAPI payload size is 256 bytes for both NCP and SoC modes. When an application calls a BGAPI command, BGAPI
checks the payload length and will return error code 0x018a (command_too_long) if the payload will cause an overflow.
Deprecation Notice
Note that some commands, enumerations and events are marked as deprecated. The usage of those commands is not recommended
anymore as they will be removed in the future releases.
silabs.com | Building a more connected world. Rev. 2.5 | 5
2.1 Cooexistence interface (coex)
Bluetooth Smart Software API Reference Manual
API Reference
Coexistence BGAPI
class. Coexistence interface is enabled and initialised with gecko_initCoexHAL() function. Interface is configured
with HAL configurator.
2.1.1 coex commands
2.1.1.1 cmd_coex_get_counters
This command is used to read coexistence statistic counters from the device. Response contains the list of uint32 type counter values.
Counters in the list are in following order: low priority requested, high priority requested, low priority denied, high priority denied, low
priority tx aborted, high priority tx aborted.
Table 2.1. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x20 class Message class: Cooexistence interface
3 0x01 method Message ID
4 uint8 reset Reset counter values
Table 2.2. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x03 lolen Minimum payload length
2 0x20 class Message class: Cooexistence interface
3 0x01 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the
6 uint8array counters Variable length byte array. The first byte defines the length of the
data that follows, 0 - 255 bytes.
BGLIB C API
/* Function */
struct gecko_msg_coex_get_counters_rsp_t *gecko_cmd_coex_get_counters(uint8 reset);
/* Response id */
gecko_rsp_coex_get_counters_id
/* Response structure */
struct gecko_msg_coex_get_counters_rsp_t
{
uint16 result;,
uint8array counters;
};
silabs.com | Building a more connected world. Rev. 2.5 | 6
2.1.1.2 cmd_coex_set_options
This command is used to configure coexistence options at runtime.
Table 2.3. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x08 lolen Minimum payload length
2 0x20 class Message class: Cooexistence interface
3 0x00 method Message ID
4-7 uint32 mask Mask defines which coexistence options are changed.
8-11 uint32 options Value of options to be changed. This parameter is used together
Table 2.4. Response
Byte Type Name Description
Bluetooth Smart Software API Reference Manual
API Reference
with mask parameter.
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x20 class Message class: Cooexistence interface
3 0x00 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the
BGLIB C API
/* Function */
struct gecko_msg_coex_set_options_rsp_t *gecko_cmd_coex_set_options(uint32 mask, uint32 options);
/* Response id */
gecko_rsp_coex_set_options_id
/* Response structure */
struct gecko_msg_coex_set_options_rsp_t
{
uint16 result;
};
2.1.2 coex enumerations
silabs.com | Building a more connected world. Rev. 2.5 | 7
Bluetooth Smart Software API Reference Manual
2.1.2.1 enum_coex_option
Coexistence configuration options
Table 2.5. Enumerations
Value Name Description
256 coex_option_enable Enable coexistence feature
1024 coex_option_tx_abort Abort transmission if grant is denied
2048 coex_option_high_priority Enable priority signal
API Reference
silabs.com | Building a more connected world. Rev. 2.5 | 8
2.2 Device Firmware Upgrade (dfu)
Bluetooth Smart Software API Reference Manual
API Reference
These commands
and events are related to controlling firmware update over the configured host interface and are available only when
the device has been booted into DFU mode. The DFU process:
1. Boot device to DFU mode with DFU reset command
2. Wait for DFU boot event
3. Send command Flash Set Address to start the firmware update
4. Upload the firmware with Flash Upload commands until all the data has been uploaded
5. Send when all the data has been uploaded
6. Finalize the DFU firmware update with Reset command.
DFU mode is using UART baudrate from hardware configuration of firmware. Default baudrate 115200 is used if firmware is missing or
firmware content does not match with CRC checksum.
2.2.1 dfu commands
silabs.com | Building a more connected world. Rev. 2.5 | 9
2.2.1.1 cmd_dfu_flash_set_address
Bluetooth Smart Software API Reference Manual
API Reference
After re-booting
the local device into DFU mode, this command can be used to define the starting address on the flash to where the
new firmware will be written in.
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x04 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x01 method Message ID
4-7 uint32 address The offset in the flash where the new firmware is uploaded to. Al-
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
Table 2.6. Command
ways use the value 0x00000000.
Table 2.7. Response
3 0x01 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_dfu_flash_set_address_rsp_t *gecko_cmd_dfu_flash_set_address(uint32 address);
/* Response id */
gecko_rsp_dfu_flash_set_address_id
/* Response structure */
struct gecko_msg_dfu_flash_set_address_rsp_t
{
uint16 result;
};
silabs.com | Building a more connected world. Rev. 2.5 | 10
2.2.1.2 cmd_dfu_flash_upload
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to upload the whole firmware image file into the Bluetooth device. The passed data length must be a multiple of 4 bytes. As the BGAPI command payload size is limited, multiple commands need to be issued one after the other until the
whole .bin firmware image file is uploaded to the device. The next address of the flash sector in memory to write to is automatically
updated by the bootloader after each individual command.
Table 2.8. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x02 method Message ID
4 uint8array data An array of data which will be written onto the flash.
Table 2.9. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x02 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_dfu_flash_upload_rsp_t *gecko_cmd_dfu_flash_upload(uint8 data_len, const uint8 *data_data);
/* Response id */
gecko_rsp_dfu_flash_upload_id
/* Response structure */
struct gecko_msg_dfu_flash_upload_rsp_t
{
uint16 result;
};
silabs.com | Building a more connected world. Rev. 2.5 | 11
Bluetooth Smart Software API Reference Manual
API Reference
2.2.1.3 cmd_dfu_flash_upload_finish
This command can be used to tell to the device that the DFU file has been fully uploaded. To return the device back to normal mode the
command DFU Reset must be issued next.
Table 2.10. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x00 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x03 method Message ID
Table 2.11. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x03 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_dfu_flash_upload_finish_rsp_t *gecko_cmd_dfu_flash_upload_finish();
/* Response id */
gecko_rsp_dfu_flash_upload_finish_id
/* Response structure */
struct gecko_msg_dfu_flash_upload_finish_rsp_t
{
uint16 result;
};
silabs.com | Building a more connected world. Rev. 2.5 | 12
2.2.1.4 cmd_dfu_reset
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to reset the system. This command does not have a response, but it triggers one of the boot events (normal reset or boot to DFU mode) after re-boot.
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x00 method Message ID
4 uint8 dfu Boot mode:
BGLIB C API
/* Function */
void *gecko_cmd_dfu_reset(uint8 dfu);
/* Command does not have a response */
Table 2.12. Command
• 0: Normal reset
• 1: Boot to UART DFU mode
• 2: Boot to OTA DFU mode
Table 2.13. Events Generated
Event Description
system_boot Sent after the device has booted into normal mode
dfu_boot Sent after the device has booted into UART DFU mode
2.2.2 dfu events
silabs.com | Building a more connected world. Rev. 2.5 | 13
2.2.2.1 evt_dfu_boot
Bluetooth Smart Software API Reference Manual
API Reference
This event
indicates that the device booted into DFU mode, and is now ready to receive commands related to device firmware upgade
(DFU).
Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x04 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x00 method Message ID
4-7 uint32 version The version of the bootloader
C Functions
/* Event id */
gecko_evt_dfu_boot_id
/* Event structure */
struct gecko_msg_dfu_boot_evt_t
{
uint32 version;
};
Table 2.14. Event
2.2.2.2 evt_dfu_boot_failure
This event indicates that there has been error in bootloader, which prevents the device from booting.
Table 2.15. Event
Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x02 lolen Minimum payload length
2 0x00 class Message class: Device Firmware Upgrade
3 0x01 method Message ID
4-5 uint16 reason The reason for boot failure, refer to the Error codes
C Functions
/* Event id */
gecko_evt_dfu_boot_failure_id
/* Event structure */
struct gecko_msg_dfu_boot_failure_evt_t
{
uint16 reason;
};
silabs.com | Building a more connected world. Rev. 2.5 | 14
2.3 Endpoint (endpoint)
This class provides a command for closing Bluetooth LE connections.
2.3.1 endpoint commands
Bluetooth Smart Software API Reference Manual
API Reference
silabs.com | Building a more connected world. Rev. 2.5 | 15
Bluetooth Smart Software API Reference Manual
API Reference
2.3.1.1 cmd_endpoint_close
Deprecated. Use new command le_connection_close to close Bluetooth LE connections.
command can be used to close a Bluetooth LE connection. The parameter is a connection handle which is reported in event
This
le_connection_opened.
Table 2.16. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x0b class Message class: Endpoint
3 0x02 method Message ID
4 uint8 endpoint The connection handle
Table 2.17. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x03 lolen Minimum payload length
2 0x0b class Message class: Endpoint
3 0x02 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6 uint8 endpoint The connection handle that was closed
BGLIB C API
/* Function */
struct gecko_msg_endpoint_close_rsp_t *gecko_cmd_endpoint_close(uint8 endpoint);
/* Response id */
gecko_rsp_endpoint_close_id
/* Response structure */
struct gecko_msg_endpoint_close_rsp_t
{
uint16 result;,
uint8 endpoint;
};
Table 2.18. Events Generated
Event Description
le_connection_closed This event indicates that a connection was closed.
silabs.com | Building a more connected world. Rev. 2.5 | 16
2.4 Persistent Store (flash)
Bluetooth Smart Software API Reference Manual
API Reference
Deprecated. Persistent
Store commands can be used to manage the user data in the flash memory of the Bluetooth device. User data
stored in PS keys within the flash memory is persistent across reset and power cycling of the device. The maximum user data size
associated to a PS key is 56 bytes.
2.4.1 flash commands
2.4.1.1 cmd_flash_ps_dump
Deprecated. This command can be used to retrieve all PS keys and their current values. For each existing PS key a flash_pskey event
will be generated which includes the corresponding PS key value.
Table 2.19. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x00 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x00 method Message ID
Table 2.20. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x00 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_flash_ps_dump_rsp_t *gecko_cmd_flash_ps_dump();
/* Response id */
gecko_rsp_flash_ps_dump_id
/* Response structure */
struct gecko_msg_flash_ps_dump_rsp_t
{
uint16 result;
};
Table 2.21. Events Generated
Event Description
flash_ps_key PS Key contents
silabs.com | Building a more connected world. Rev. 2.5 | 17
Bluetooth Smart Software API Reference Manual
2.4.1.2 cmd_flash_ps_erase
Deprecated. This command can be used to erase a single PS key and its value from the persistent store..
Table 2.22. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x04 method Message ID
4-5 uint16 key PS key to erase
Table 2.23. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
API Reference
1 0x02 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x04 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_flash_ps_erase_rsp_t *gecko_cmd_flash_ps_erase(uint16 key);
/* Response id */
gecko_rsp_flash_ps_erase_id
/* Response structure */
struct gecko_msg_flash_ps_erase_rsp_t
{
uint16 result;
};
silabs.com | Building a more connected world. Rev. 2.5 | 18
2.4.1.3 cmd_flash_ps_erase_all
Deprecated. This command can be used to erase all PS keys and their corresponding values.
Table 2.24. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x00 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x01 method Message ID
Table 2.25. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
Bluetooth Smart Software API Reference Manual
API Reference
2 0x0d class Message class: Persistent Store
3 0x01 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_flash_ps_erase_all_rsp_t *gecko_cmd_flash_ps_erase_all();
/* Response id */
gecko_rsp_flash_ps_erase_all_id
/* Response structure */
struct gecko_msg_flash_ps_erase_all_rsp_t
{
uint16 result;
};
silabs.com | Building a more connected world. Rev. 2.5 | 19
2.4.1.4 cmd_flash_ps_load
Deprecated. This command can be used for retrieving the value of the specified PS key.
Table 2.26. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x03 method Message ID
4-5 uint16 key PS key of the value to be retrieved
Table 2.27. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
Bluetooth Smart Software API Reference Manual
API Reference
1 0x03 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x03 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6 uint8array value The returned value of the specified PS key.
BGLIB C API
/* Function */
struct gecko_msg_flash_ps_load_rsp_t *gecko_cmd_flash_ps_load(uint16 key);
/* Response id */
gecko_rsp_flash_ps_load_id
/* Response structure */
struct gecko_msg_flash_ps_load_rsp_t
{
uint16 result;,
uint8array value;
};
silabs.com | Building a more connected world. Rev. 2.5 | 20
2.4.1.5 cmd_flash_ps_save
Bluetooth Smart Software API Reference Manual
API Reference
Deprecated. This
command can be used to store a value into the specified PS key. Allowed PS keys are in range from 0x4000 to
0x407F. At most 56 bytes user data can be stored in one PS key. Error code 0x018a (command_too_long) will be returned if more than
56 bytes data is passed in.
Table 2.28. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x03 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x02 method Message ID
4-5 uint16 key PS key
6 uint8array value Value to store into the specified PS key.
Table 2.29. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x02 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_flash_ps_save_rsp_t *gecko_cmd_flash_ps_save(uint16 key, uint8 value_len, const uint8 *value_d
ata);
/* Response id */
gecko_rsp_flash_ps_save_id
/* Response structure */
struct gecko_msg_flash_ps_save_rsp_t
{
uint16 result;
};
2.4.2 flash events
silabs.com | Building a more connected world. Rev. 2.5 | 21
2.4.2.1 evt_flash_ps_key
Bluetooth Smart Software API Reference Manual
API Reference
Deprecated. This
event indicates that the flash_ps_dump command was given. It returns a single PS key and its value. There can be
multiple events if multiple PS keys exist.
Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x03 lolen Minimum payload length
2 0x0d class Message class: Persistent Store
3 0x00 method Message ID
4-5 uint16 key PS key
6 uint8array value Current value of the PS key specified in this event.
C Functions
/* Event id */
gecko_evt_flash_ps_key_id
/* Event structure */
struct gecko_msg_flash_ps_key_evt_t
{
uint16 key;,
uint8array value;
};
Table 2.30. Event
silabs.com | Building a more connected world. Rev. 2.5 | 22
Bluetooth Smart Software API Reference Manual
2.5 Generic Attribute Profile (gatt)
The commands and events in this class can be used to browse and manage attributes in a remote GATT server.
2.5.1 gatt commands
API Reference
silabs.com | Building a more connected world. Rev. 2.5 | 23
2.5.1.1 cmd_gatt_discover_characteristics
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to discover all characteristics of the defined GATT service from a remote GATT database. This command
generates a unique gatt_characteristic event for every discovered characteristic. Received gatt_procedure_completed event indicates
that this GATT procedure has succesfully completed or failed with error.
Table 2.31. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x05 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x03 method Message ID
4 uint8 connection Connection handle
5-8 uint32 service GATT service handle
This value is normally received from the gatt_service event.
Table 2.32. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x03 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_gatt_discover_characteristics_rsp_t *gecko_cmd_gatt_discover_characteristics(uint8 connection
, uint32 service);
/* Response id */
gecko_rsp_gatt_discover_characteristics_id
/* Response structure */
struct gecko_msg_gatt_discover_characteristics_rsp_t
{
uint16 result;
};
Table 2.33. Events Generated
Event Description
gatt_characteristic Discovered characteristic from remote GATT database.
gatt_procedure_completed Procedure has been successfully completed or failed with error.
silabs.com | Building a more connected world. Rev. 2.5 | 24
2.5.1.2 cmd_gatt_discover_characteristics_by_uuid
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to discover all the characteristics of the specified GATT service in a remote GATT database having the
specified UUID. This command generates a unique gatt_characteristic event for every discovered characteristic having the specified
UUID. Received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with error.
Table 2.34. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x06 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x04 method Message ID
4 uint8 connection Connection handle
5-8 uint32 service GATT service handle
This value is normally received from the gatt_service event.
9 uint8array uuid Characteristic UUID
Table 2.35. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x04 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_gatt_discover_characteristics_by_uuid_rsp_t *gecko_cmd_gatt_discover_characteristics_by_uuid(u
int8 connection, uint32 service, uint8 uuid_len, const uint8 *uuid_data);
/* Response id */
gecko_rsp_gatt_discover_characteristics_by_uuid_id
/* Response structure */
struct gecko_msg_gatt_discover_characteristics_by_uuid_rsp_t
{
uint16 result;
};
Table 2.36. Events Generated
Event Description
gatt_characteristic Discovered characteristic from remote GATT database.
gatt_procedure_completed Procedure has been successfully completed or failed with error.
silabs.com | Building a more connected world. Rev. 2.5 | 25
2.5.1.3 cmd_gatt_discover_descriptors
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to discover all the descriptors of the specified remote GATT characteristics in a remote GATT database.
This command generates a unique gatt_descriptor event for every discovered descriptor. Received gatt_procedure_completed event
indicates that this GATT procedure has succesfully completed or failed with error.
Table 2.37. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x03 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x06 method Message ID
4 uint8 connection Connection handle
5-6 uint16 characteristic GATT characteristic handle
This value is normally received from the gatt_characteristic event.
Table 2.38. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x06 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_gatt_discover_descriptors_rsp_t *gecko_cmd_gatt_discover_descriptors(uint8 connection, uint16
characteristic);
/* Response id */
gecko_rsp_gatt_discover_descriptors_id
/* Response structure */
struct gecko_msg_gatt_discover_descriptors_rsp_t
{
uint16 result;
};
Table 2.39. Events Generated
Event Description
gatt_descriptor Discovered descriptor from remote GATT database.
gatt_procedure_completed Procedure has been successfully completed or failed with error.
silabs.com | Building a more connected world. Rev. 2.5 | 26
2.5.1.4 cmd_gatt_discover_primary_services
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to discover all the primary services of a remote GATT database. This command generates a unique
gatt_service event for every discovered primary service. Received gatt_procedure_completed event indicates that this GATT procedure
has successfully completed or failed with error.
Table 2.40. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x01 method Message ID
4 uint8 connection Connection handle
Table 2.41. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x01 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_gatt_discover_primary_services_rsp_t *gecko_cmd_gatt_discover_primary_services(uint8 connectio
n);
/* Response id */
gecko_rsp_gatt_discover_primary_services_id
/* Response structure */
struct gecko_msg_gatt_discover_primary_services_rsp_t
{
uint16 result;
};
Table 2.42. Events Generated
Event Description
gatt_service Discovered service from remote GATT database
gatt_procedure_completed Procedure has been successfully completed or failed with error.
silabs.com | Building a more connected world. Rev. 2.5 | 27
2.5.1.5 cmd_gatt_discover_primary_services_by_uuid
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to discover primary services with the specified UUID in a remote GATT database. This command generates unique gatt_service event for every discovered primary service. Received gatt_procedure_completed event indicates that this
GATT procedure has succesfully completed or failed with error.
Table 2.43. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x02 method Message ID
4 uint8 connection Connection handle
5 uint8array uuid Service UUID
Table 2.44. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x02 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_gatt_discover_primary_services_by_uuid_rsp_t *gecko_cmd_gatt_discover_primary_services_by_uui
d(uint8 connection, uint8 uuid_len, const uint8 *uuid_data);
/* Response id */
gecko_rsp_gatt_discover_primary_services_by_uuid_id
/* Response structure */
struct gecko_msg_gatt_discover_primary_services_by_uuid_rsp_t
{
uint16 result;
};
Table 2.45. Events Generated
Event Description
gatt_service Discovered service from remote GATT database.
gatt_procedure_completed Procedure has been successfully completed or failed with error.
silabs.com | Building a more connected world. Rev. 2.5 | 28
2.5.1.6 cmd_gatt_execute_characteristic_value_write
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to commit or cancel previously queued writes to a long characteristic of a remote GATT server. Writes are
sent to queue with prepare_characteristic_value_write command. Content, offset and length of queued values are validated by this procedure. A received gatt_procedure_completed event indicates that all data has been written successfully or that an error response has
been received.
Table 2.46. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x0c method Message ID
4 uint8 connection Connection handle
5 uint8 flags Unsigned 8-bit integer
Table 2.47. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x0c method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_gatt_execute_characteristic_value_write_rsp_t *gecko_cmd_gatt_execute_characteristic_value_wri
te(uint8 connection, uint8 flags);
/* Response id */
gecko_rsp_gatt_execute_characteristic_value_write_id
/* Response structure */
struct gecko_msg_gatt_execute_characteristic_value_write_rsp_t
{
uint16 result;
};
Table 2.48. Events Generated
Event Description
gatt_procedure_completed Procedure has been successfully completed or failed with error.
silabs.com | Building a more connected world. Rev. 2.5 | 29
2.5.1.7 cmd_gatt_find_included_services
Bluetooth Smart Software API Reference Manual
API Reference
This command
can be used to find out if a service of a remote GATT database includes one or more other services. This command
generates a unique gatt_service_completed event for each included service. This command generates a unique gatt_service event for
every discovered service. Received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or
failed with error.
Table 2.49. Command
Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x05 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x10 method Message ID
4 uint8 connection Connection handle
5-8 uint32 service GATT service handle
This value is normally received from the gatt_service event.
Table 2.50. Response
Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x09 class Message class: Generic Attribute Profile
3 0x10 method Message ID
4-5 uint16 result Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGLIB C API
/* Function */
struct gecko_msg_gatt_find_included_services_rsp_t *gecko_cmd_gatt_find_included_services(uint8 connection, uin
t32 service);
/* Response id */
gecko_rsp_gatt_find_included_services_id
/* Response structure */
struct gecko_msg_gatt_find_included_services_rsp_t
{
uint16 result;
};
Table 2.51. Events Generated
Event Description
gatt_service Discovered service from remote GATT database.
gatt_procedure_completed Procedure has been successfully completed or failed with error.
silabs.com | Building a more connected world. Rev. 2.5 | 30
Loading...