Read More

Bluetooth Smart Software API Reference
Manual
This document contains the full API reference for the Silicon Labs Bluetooth Smart Software, version
1.0.0.
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 | Smart. Connected. Energy-friendly.
Rev. 1.3
Bluetooth Smart Software API Reference Manual
Table of Contents
1. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2. API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1 Device Firmware Upgrade (dfu) .
2.1.1 dfu commands . . . . . .
2.1.1.1 cmd_dfu_flash_set_address .
2.1.1.2 cmd_dfu_flash_upload . .
2.1.1.3 cmd_dfu_flash_upload_finish
2.1.1.4 cmd_dfu_reset . . . . .
2.1.2 dfu events . . . . . . .
2.1.2.1 evt_dfu_boot . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2.2 Endpoint (endpoint) . . . . . . . . .
2.2.1 endpoint commands . . . . . . . .
2.2.1.1 cmd_endpoint_close . . . . . . .
2.2.1.2 cmd_endpoint_read_counters . . . .
2.2.1.3 cmd_endpoint_send . . . . . . .
2.2.1.4 cmd_endpoint_set_streaming_destination
2.2.2 endpoint events . . . . . . . . .
2.2.2.1 evt_endpoint_closing . . . . . . .
2.2.2.2 evt_endpoint_data . . . . . . . .
2.2.2.3 evt_endpoint_status . . . . . . .
2.2.2.4 evt_endpoint_syntax_error . . . . .
2.2.3 endpoint enumerations . . . . . . .
2.2.3.1 enum_endpoint_types . . . . . . .
2.2.4 endpoint defines . . . . . . . . .
2.2.4.1 define_endpoint_endpoint_flags . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 9
. 9
.10
.11
.12
.13
.14
.14
.15
.16
.17
.17
.18
.18
.18
2.3 Persistent Store (flash) . .
2.3.1 flash commands . . .
2.3.1.1 cmd_flash_ps_dump .
2.3.1.2 cmd_flash_ps_erase .
2.3.1.3 cmd_flash_ps_erase_all
2.3.1.4 cmd_flash_ps_load . .
2.3.1.5 cmd_flash_ps_save .
2.3.2 flash events . . . . .
2.3.2.1 evt_flash_ps_key . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.19
.19
.20
.21
.22
.23
.24
.24
.25
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.26
.26
.27
.29
.31
.33
.34
.36
.37
.39
.41
.43
.45
.47
.48
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2.4 Generic Attribute Profile (gatt) . . . . . . .
2.4.1 gatt commands . . . . . . . . . . . .
2.4.1.1 cmd_gatt_discover_characteristics . . . .
2.4.1.2 cmd_gatt_discover_characteristics_by_uuid .
2.4.1.3 cmd_gatt_discover_descriptors. . . . . .
2.4.1.4 cmd_gatt_discover_primary_services . . .
2.4.1.5 cmd_gatt_discover_primary_services_by_uuid
2.4.1.6 cmd_gatt_execute_characteristic_value_write .
2.4.1.7 cmd_gatt_find_included_services . . . . .
2.4.1.8 cmd_gatt_prepare_characteristic_value_write .
2.4.1.9 cmd_gatt_read_characteristic_value . . . .
2.4.1.10 cmd_gatt_read_characteristic_value_by_uuid
2.4.1.11 cmd_gatt_read_descriptor_value. . . . .
2.4.1.12 cmd_gatt_read_multiple_characteristic_values
2.4.1.13 cmd_gatt_send_characteristic_confirmation .
Table of Contents
3
3
4
5
6
7
7
8
ii
Bluetooth Smart Software API Reference Manual
2.4.1.14 cmd_gatt_set_characteristic_notification . . . . .
2.4.1.15 cmd_gatt_write_characteristic_value . . . . . .
2.4.1.16 cmd_gatt_write_characteristic_value_without_response
2.4.1.17 cmd_gatt_write_descriptor_value . . . . . . .
2.4.2 gatt events . . . . . . . . . . . . . . . .
2.4.2.1 evt_gatt_characteristic. . . . . . . . . . . .
2.4.2.2 evt_gatt_characteristic_value . . . . . . . . .
2.4.2.3 evt_gatt_descriptor . . . . . . . . . . . . .
2.4.2.4 evt_gatt_descriptor_value . . . . . . . . . .
2.4.2.5 evt_gatt_procedure_completed . . . . . . . . .
2.4.2.6 evt_gatt_service . . . . . . . . . . . . . .
2.4.3 gatt enumerations . . . . . . . . . . . . . .
2.4.3.1 enum_gatt_att_opcode . . . . . . . . . . .
2.4.3.2 enum_gatt_client_config_flag . . . . . . . . .
2.4.3.3 enum_gatt_execute_write_flag . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.49
.51
.53
.54
.55
.55
.56
.57
.58
.59
.60
.60
.61
.61
.61
2.5 Generic Attribute Profile Server (gatt_server) . . .
2.5.1 gatt_server commands . . . . . . . . . .
2.5.1.1 cmd_gatt_server_find_attribute . . . . . . .
2.5.1.2 cmd_gatt_server_read_attribute_type . . . .
2.5.1.3 cmd_gatt_server_read_attribute_value . . . .
2.5.1.4 cmd_gatt_server_send_characteristic_notification
2.5.1.5 cmd_gatt_server_send_user_read_response . .
2.5.1.6 cmd_gatt_server_send_user_write_response . .
2.5.1.7 cmd_gatt_server_write_attribute_value . . . .
2.5.2 gatt_server events. . . . . . . . . . . .
2.5.2.1 evt_gatt_server_attribute_value . . . . . .
2.5.2.2 evt_gatt_server_characteristic_status . . . .
2.5.2.3 evt_gatt_server_execute_write_completed . . .
2.5.2.4 evt_gatt_server_user_read_request . . . . .
2.5.2.5 evt_gatt_server_user_write_request . . . . .
2.5.3 gatt_server enumerations . . . . . . . . .
2.5.3.1 enum_gatt_server_characteristic_status_flag . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.62
.62
.63
.64
.65
.66
.67
.69
.70
.70
.71
.72
.73
.74
.75
.75
.76
2.6 Hardware (hardware) . . . . . . .
2.6.1 hardware commands . . . . . . .
2.6.1.1 cmd_hardware_configure_gpio . . .
2.6.1.2 cmd_hardware_config_adc_reference
2.6.1.3 cmd_hardware_read_adc . . . .
2.6.1.4 cmd_hardware_read_gpio . . . .
2.6.1.5 cmd_hardware_read_i2c . . . . .
2.6.1.6 cmd_hardware_set_soft_timer . . .
2.6.1.7 cmd_hardware_stop_i2c . . . . .
2.6.1.8 cmd_hardware_write_gpio . . . .
2.6.1.9 cmd_hardware_write_i2c . . . . .
2.6.2 hardware events . . . . . . . .
2.6.2.1 evt_hardware_interrupt . . . . .
2.6.2.2 evt_hardware_soft_timer . . . . .
2.6.3 hardware enumerations . . . . . .
2.6.3.1 enum_hardware_adc_reference . .
2.6.3.2 enum_hardware_gpio_mode . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.77
.77
.78
.79
.80
.81
.82
.83
.84
.85
.86
.86
.87
.88
.88
.88
.89
2.7 Connection management for low energy (le_connection)
2.7.1 le_connection commands . . . . . . . . . .
2.7.1.1 cmd_le_connection_disable_slave_latency . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.90
.90
.90
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Table of Contents
iii
Bluetooth Smart Software API Reference Manual
2.7.1.2 cmd_le_connection_get_rssi . .
2.7.1.3 cmd_le_connection_set_parameters
2.7.2 le_connection events . . . . . .
2.7.2.1 evt_le_connection_closed . . .
2.7.2.2 evt_le_connection_opened . . .
2.7.2.3 evt_le_connection_parameters . .
2.7.2.4 evt_le_connection_rssi . . . .
2.7.3 le_connection enumerations . . .
2.7.3.1 enum_le_connection_security . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.91
.92
.93
.94
.95
.96
.97
.97
.97
2.8 Generic Access Profile, Low Energy (le_gap) . . . . . . . . . . . . . . . . . . .98
2.8.1 le_gap commands . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
2.8.1.1 cmd_le_gap_discover . . . . . . . . . . . . . . . . . . . . . . . . . .99
2.8.1.2 cmd_le_gap_end_procedure
. . . . . . . . . . . . . . . . . . . . . 100
.
2.8.1.3 cmd_le_gap_open . . . . . . . . . . . . . . . . . . . . . . . . . . 101
2.8.1.4 cmd_le_gap_set_adv_data . . . . . . . . . . . . . . . . . . . . . . . 103
2.8.1.5 cmd_le_gap_set_adv_parameters . . . . . . . . . . . . . . . . . . . . . 104
2.8.1.6 cmd_le_gap_set_conn_parameters
. . . . . . . . . . . . . . . . . . . .106
2.8.1.7 cmd_le_gap_set_mode
. . . . . . . . . . . . . . . . . . . . . . . .108
2.8.1.8 cmd_le_gap_set_scan_parameters
. . . . . . . . . . . . . . . . . . . .109
2.8.2 le_gap events
. . . . . . . . . . . . . . . . . . . . . . . . . . . .110
2.8.2.1 evt_le_gap_scan_response . . . . . . . . . . . . . . . . . . . . . . . 111
2.8.3 le_gap enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . 111
2.8.3.1 enum_le_gap_address_type. . . . . . . . . . . . . . . . . . . . . . . 112
2.8.3.2 enum_le_gap_connectable_mode . . . . . . . . . . . . . . . . . . . . . 112
2.8.3.3 enum_le_gap_discoverable_mode
. . . . . . . . . . . . . . . . . . . 112
.
2.8.3.4 enum_le_gap_discover_mode . . . . . . . . . . . . . . . . . . . . . . 113
2.9 Security Manager (sm) . . . . . . . . . . . . . . . . . . . . . . . . . . 114
2.9.1 sm commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
2.9.1.1 cmd_sm_configure . . . . . . . . . . . . . . . . . . . . . . . . . . 115
2.9.1.2 cmd_sm_delete_bonding . . . . . . . . . . . . . . . . . . . . . . . . 116
2.9.1.3 cmd_sm_delete_bondings
. . . . . . . . . . . . . . . . . . . . . . .117
2.9.1.4 cmd_sm_enter_passkey . . . . . . . . . . . . . . . . . . . . . . . . 118
2.9.1.5 cmd_sm_increase_security . . . . . . . . . . . . . . . . . . . . . . . 119
2.9.1.6 cmd_sm_list_all_bondings
. . . . . . . . . . . . . . . . . . . . . . .120
2.9.1.7 cmd_sm_passkey_confirm
. . . . . . . . . . . . . . . . . . . . . . .121
2.9.1.8 cmd_sm_set_bondable_mode . . . . . . . . . . . . . . . . . . . . . . 122
2.9.1.9 cmd_sm_set_oob_data
. . . . . . . . . . . . . . . . . . . . . . . .123
2.9.1.10 cmd_sm_store_bonding_configuration . . . . . . . . . . . . . . . . . . . 124
2.9.2 sm events
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
.
2.9.2.1 evt_sm_bonded . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.9.2.2 evt_sm_bonding_failed
. . . . . . . . . . . . . . . . . . . . . . . 1
. 26
2.9.2.3 evt_sm_confirm_passkey . . . . . . . . . . . . . . . . . . . . . . . . 127
2.9.2.4 evt_sm_list_all_bondings_complete . . . . . . . . . . . . . . . . . . . .128
2.9.2.5 evt_sm_list_bonding_entry . . . . . . . . . . . . . . . . . . . . . . .129
2.9.2.6 evt_sm_passkey_display . . . . . . . . . . . . . . . . . . . . . . . . 130
2.9.2.7 evt_sm_passkey_request
. . . . . . . . . . . . . . . . . . . . . . 131
.
2.9.3 sm enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
2.9.3.1 enum_sm_bonding_key . . . . . . . . . . . . . . . . . . . . . . . .131
2.9.3.2 enum_sm_io_capability
. . . . . . . . . . . . . . . . . . . . . . . .132
2.10 System (system)
. . . . . . . . . . . . . . . . . . . . . . . . . . 133
.
2.10.1 system commands . . . . . . . . . . . . . . . . . . . . . . . . . .133
2.10.1.1 cmd_system_get_bt_address . . . . . . . . . . . . . . . . . . . . . . 133
Table of Contents
iv
Bluetooth Smart Software API Reference Manual
2.10.1.2 cmd_system_hello
. . . . . . . . . . . . . . . . . . . . . . . . 134
.
2.10.1.3 cmd_system_reset
. . . . . . . . . . . . . . . . . . . . . . . . 1. 35
2.10.1.4 cmd_system_set_tx_power
. . . . . . . . . . . . . . . . . . . . . 136
.
2.10.2 system events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
2.10.2.1 evt_system_awake
. . . . . . . . . . . . . . . . . . . . . . . . .137
2.10.2.2 evt_system_boot . . . . . . . . . . . . . . . . . . . . . . . . . . 138
2.10.2.3 evt_system_external_signal
. . . . . . . . . . . . . . . . . . . . . .139
2.10.2.4 evt_system_hardware_error
. . . . . . . . . . . . . . . . . . . . . .140
2.11 testing commands (test) . . . . . . . . . . . . . . . . . . . . . . . . . 141
2.11.1 test commands
. . . . . . . . . . . . . . . . . . . . . . . . . . .141
2.11.1.1 cmd_test_dtm_end
. . . . . . . . . . . . . . . . . . . . . . . . .141
2.11.1.2 cmd_test_dtm_rx . . . . . . . . . . . . . . . . . . . . . . . . . . 142
2.11.1.3 cmd_test_dtm_tx . . . . . . . . . . . . . . . . . . . . . . . . . . 143
2.11.2 test events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
2.11.2.1 evt_test_dtm_completed
. . . . . . . . . . . . . . . . . . . . . . 144
.
2.11.3 test enumerations
. . . . . . . . . . . . . . . . . . . . . . . . . 1
. 44
2.11.3.1 enum_test_packet_type . . . . . . . . . . . . . . . . . . . . . . . . 145
2.12 Utilities for BGScript (util)
. . . . . . . . . . . . . . . . . . . . . . . 146
.
2.12.1 util commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
2.12.1.1 cmd_util_atoi
. . . . . . . . . . . . . . . . . . . . . . . . . . .146
2.12.1.2 cmd_util_itoa
. . . . . . . . . . . . . . . . . . . . . . . . . . .147
2.13 Error codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.147
3. Document Revision History . . . . . . . . . . . . . . . . . . . . . . . . . 154
Table of Contents
v
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
BGScript equivalent
Description
errorcode
2 bytes
Number
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
int16
2 bytes
Number
Signed 16-bit integer
bd_addr
6 bytes
Array of 6 bytes
Bluetooth address
uint16
2 bytes
Number
Unsigned 16-bit integer
int32
4 bytes
Number
Signed 32-bit integer
uint32
4 bytes
Number*
Unsigned 32-bit integer
link_id_t
2 bytes
Number
Link ID
int8
1 byte
Number
Signed 8-bit integer
uint8
1 byte
Number
Unsigned 8-bit integer
uint8array
1 - 256 bytes
Array
Variable length byte array. The first byte defines the length of the data that
follows, 0 - 255 bytes.
ser_name
16 bytes
Array of 16 bytes
Service name, 16-byte array
dbm
1 byte
Number
Signal strength
connection
1 byte
Number
Connection handle
service
1 byte
Number
GATT service handle
This value is normally received from the gatt_service event.
characteristic
1 byte
Number
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
descriptor
1 byte
Number
GATT characteristic descriptor handle
uuid
1 byte
Number
Characteristic UUID
att_errorcode
1 byte
Number
Attribute protocol error code
• 0: No error
• Non-zero: see link
att_opcode
1 byte
Number
Attribute opcode which informs the procedure from which attribute the value
was received
(*) The script's internal number type is a signed 32-bit integer. This means large unsigned 32-bit integers in the BGAPI will be represented with negative numbers in the script. This is a known limitation.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 1
Bluetooth Smart Software API Reference Manual
API Reference
2. API Reference
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 2
Bluetooth Smart Software API Reference Manual
API Reference
2.1 Device Firmware Upgrade (dfu)
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.1.1 dfu commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 3
Bluetooth Smart Software API Reference Manual
API Reference
2.1.1.1 cmd_dfu_flash_set_address
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.
Table 2.1. Command
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. Always use the value 0x00000000.
Table 2.2. 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
0x01
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call dfu_flash_set_address(address)(result)
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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 4
Bluetooth Smart Software API Reference Manual
API Reference
2.1.1.2 cmd_dfu_flash_upload
This command can be used to upload the whole firmware image file in to the Bluetooth device. The recommended payload size of the
command is 128 bytes, so 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.3. 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
4
uint8array
data
Message ID
An array of data which will be written onto the flash.
Table 2.4. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call dfu_flash_upload(data_len, data_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_dfu_flash_upload_rsp_t *gecko_cmd_dfu_flash_upload(uint8array data);
/* Response id */
gecko_rsp_dfu_flash_upload_id
/* Response structure */
struct gecko_msg_dfu_flash_upload_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 5
Bluetooth Smart Software API Reference Manual
API Reference
2.1.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.5. 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.6. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call dfu_flash_upload_finish()(result)
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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 6
Bluetooth Smart Software API Reference Manual
API Reference
2.1.1.4 cmd_dfu_reset
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.
Table 2.7. 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
0x00
method
4
uint8
dfu
Message ID
Boot mode:
• 0: Normal reset
• 1: Boot to DFU mode
BGScript command
call dfu_reset(dfu)
BGLIB C API
/* Function */
void *gecko_cmd_dfu_reset(uint8 dfu);
/* Command does not have a response */
Table 2.8. Events Generated
Event
Description
system_boot
Sent after the device has booted into normal mode
dfu_boot
Sent after the device has booted into DFU mode
2.1.2 dfu events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 7
Bluetooth Smart Software API Reference Manual
API Reference
2.1.2.1 evt_dfu_boot
This event indicates that the device booted into DFU mode, and is now ready to receive commands related to device firmware upgade
(DFU).
Table 2.9. Event
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
BGScript event
event dfu_boot(version)
C Functions
/* Event id */
gecko_evt_dfu_boot_id
/* Event structure */
struct gecko_msg_dfu_boot_evt_t
{
uint32 version
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 8
Bluetooth Smart Software API Reference Manual
API Reference
2.2 Endpoint (endpoint)
These commands and events are related to the control of endpoints. They allow the creation and deletion of endpoints as well as configuration of data routing. Predefined endpoint ID's in the device are:
• 2:UART1
• 5:UART0
• 31:DROP
Note the difference between these endpoint ID's and the following endpoint types - they describe different categories. Each endpoint
has an endpoint type which describes what kind of endpoint it is. There may be multiple endpoints which have the same type. Each
endpoint has exactly one ID, and each ID points to exactly one endpoint.
2.2.1 endpoint commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 9
Bluetooth Smart Software API Reference Manual
API Reference
2.2.1.1 cmd_endpoint_close
This command can be used to close an endpoint. This command must always be used to close an endpoint with WAIT_CLOSE status.
This is to free the endpoint for future reuse in the case when the remote side closes the connection.
Table 2.10. 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 handle of the BLE connection to be closed. The connection
handle is reported in the event le_connection_opened.
Table 2.11. 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
4-5
uint16
result
6
uint8
endpoint
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
The endpoint that was closed
BGScript command
call endpoint_close(endpoint)(result,endpoint)
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.12. Events Generated
Event
Description
endpoint_status
Sent when endpoint status changes
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 10
Bluetooth Smart Software API Reference Manual
API Reference
2.2.1.2 cmd_endpoint_read_counters
This command can be used to read the data performance counters (data sent counter and data received counter) of an endpoint.
Table 2.13. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x05
method
Message ID
4
uint8
endpoint
The endpoint's handle
Table 2.14. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x0b
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x05
method
4-5
uint16
result
6
uint8
endpoint
7-10
uint32
tx
Amount of data sent to this endpoint
11-14
uint32
rx
Amount of data received from this endpoint
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call endpoint_read_counters(endpoint)(result,endpoint,tx,rx)
BGLIB C API
/* Function */
struct gecko_msg_endpoint_read_counters_rsp_t *gecko_cmd_endpoint_read_counters(uint8 endpoint);
/* Response id */
gecko_rsp_endpoint_read_counters_id
/* Response structure */
struct gecko_msg_endpoint_read_counters_rsp_t
{
uint16 result,
uint8 endpoint,
uint32 tx,
uint32 rx
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 11
Bluetooth Smart Software API Reference Manual
API Reference
2.2.1.3 cmd_endpoint_send
This command can be used to send data to the defined endpoint.
Table 2.15. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x00
method
Message ID
4
uint8
endpoint
The index of the endpoint to which the data will be sent.
5
uint8array
data
The RAW data which will be written or sent
Table 2.16. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x03
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x00
method
4-5
uint16
result
6
uint8
endpoint
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
The endpoint to which the data was written
BGScript command
call endpoint_send(endpoint,data_len, data_data)(result,endpoint)
BGLIB C API
/* Function */
struct gecko_msg_endpoint_send_rsp_t *gecko_cmd_endpoint_send(uint8 endpoint, uint8array data);
/* Response id */
gecko_rsp_endpoint_send_id
/* Response structure */
struct gecko_msg_endpoint_send_rsp_t
{
uint16 result,
uint8 endpoint
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 12
Bluetooth Smart Software API Reference Manual
API Reference
2.2.1.4 cmd_endpoint_set_streaming_destination
This command can be used to set the destination into which data from an endpoint will be routed to.
Table 2.17. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x01
method
Message ID
4
uint8
endpoint
The endpoint which to control
5
uint8
destination_endpoint The destination for the data
Table 2.18. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x03
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x01
method
4-5
uint16
result
6
uint8
endpoint
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
Endpoint of the connection
BGScript command
call endpoint_set_streaming_destination(endpoint,destination_endpoint)(result,endpoint)
BGLIB C API
/* Function */
struct gecko_msg_endpoint_set_streaming_destination_rsp_t *gecko_cmd_endpoint_set_streaming_destination(uint8 e
ndpoint, uint8 destination_endpoint);
/* Response id */
gecko_rsp_endpoint_set_streaming_destination_id
/* Response structure */
struct gecko_msg_endpoint_set_streaming_destination_rsp_t
{
uint16 result,
uint8 endpoint
}
Table 2.19. Events Generated
Event
Description
endpoint_status
Sent when endpoint status changes
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 13
Bluetooth Smart Software API Reference Manual
API Reference
2.2.2 endpoint events
2.2.2.1 evt_endpoint_closing
This event indicates that an endpoint is closing or that the remote end has terminated the connection. This event should be acknowledged by calling the endpoint_close command or otherwise the firmware will not re-use the endpoint index.
Table 2.20. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x03
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x03
method
Message ID
4-5
uint16
reason
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6
uint8
endpoint
Endpoint handle. Values:
• 0xff: connection failed without associated endpoint
• Others: Handle for closed endpoint
BGScript event
event endpoint_closing(reason,endpoint)
C Functions
/* Event id */
gecko_evt_endpoint_closing_id
/* Event structure */
struct gecko_msg_endpoint_closing_evt_t
{
uint16 reason,
uint8 endpoint
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 14
Bluetooth Smart Software API Reference Manual
API Reference
2.2.2.2 evt_endpoint_data
This event indicates incoming data from an endpoint.
Table 2.21. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x02
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x01
method
Message ID
4
uint8
endpoint
The endpoint which received this data, i.e. to which it was sent.
5
uint8array
data
The raw data
BGScript event
event endpoint_data(endpoint,data_len, data_data)
C Functions
/* Event id */
gecko_evt_endpoint_data_id
/* Event structure */
struct gecko_msg_endpoint_data_evt_t
{
uint8 endpoint,
uint8array data
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 15
Bluetooth Smart Software API Reference Manual
API Reference
2.2.2.3 evt_endpoint_status
This event indicates an endpoint's status.
Table 2.22. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x07
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x02
method
Message ID
4
uint8
endpoint
The index of the endpoint whose status this event describes
5-8
uint32
type
9
int8
10
uint8
Unsigned 32-bit integer
destination_endpoint The index of the endpoint to which the incoming data goes.
flags
Flags which indicate the mode of endpoint
BGScript event
event endpoint_status(endpoint,type,destination_endpoint,flags)
C Functions
/* Event id */
gecko_evt_endpoint_status_id
/* Event structure */
struct gecko_msg_endpoint_status_evt_t
{
uint8 endpoint,
uint32 type,
int8 destination_endpoint,
uint8 flags
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 16
Bluetooth Smart Software API Reference Manual
API Reference
2.2.2.4 evt_endpoint_syntax_error
This event indicates that a protocol error was detected in BGAPI command parser. This event is triggered if a BGAPI command from
the host contains syntax error(s), or if a command is only partially sent, in which case the BGAPI parser has a 1 second command
timeout. If a valid command is not transmitted within this timeout an error event is generated and the partial or wrong command will be
ignored.
Table 2.23. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x03
lolen
Minimum payload length
2
0x0b
class
Message class: Endpoint
3
0x00
method
4-5
uint16
result
6
uint8
endpoint
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
Endpoint of the connection
BGScript event
event endpoint_syntax_error(result,endpoint)
C Functions
/* Event id */
gecko_evt_endpoint_syntax_error_id
/* Event structure */
struct gecko_msg_endpoint_syntax_error_evt_t
{
uint16 result,
uint8 endpoint
}
2.2.3 endpoint enumerations
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 17
Bluetooth Smart Software API Reference Manual
API Reference
2.2.3.1 enum_endpoint_types
These values define the endpoint types.
Table 2.24. Enumerations
Value
Name
Description
0
endpoint_free
Endpoint is not in use
1
endpoint_uart
UART
2
endpoint_script
Scripting
4
endpoint_reserved
Reserved for future use
16
endpoint_drop
Drop all data sent to this endpoint
32
endpoint_rfcomm
RFCOMM channel
64
endpoint_spi
SPI
128
endpoint_connection
Connection
256
endpoint_native
Endpoint used for native interface
2.2.4 endpoint defines
2.2.4.1 define_endpoint_endpoint_flags
Table 2.25. Defines
Value
Name
Description
1
ENDPOINT_FLAG_UPDATED
Endpoint status has been changed since last indication
2
ENDPOINT_FLAG_ACTIVE
Endpoint is active and can send and receive data
4
ENDPOINT_FLAG_STREAMING
Endpoint is in streaming mode. Data is sent and received from endpoint without framing
8
ENDPOINT_FLAG_BGAPI
Endpoint is configured for BGAPI. Data received is
parsed as BGAPI commands. Also all BGAPI events
and responses are sent to this endpoint
16
ENDPOINT_FLAG_WAIT_CLOSE
Endpoint is closed from the device side. Host needs to
acknowledge by sending endpoint_close command to
device with this endpoint as parameter
32
ENDPOINT_FLAG_CLOSING
Endpoint is closed from the host side and is waiting for
the device to acknowledge closing of the endpoint
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 18
Bluetooth Smart Software API Reference Manual
API Reference
2.3 Persistent Store (flash)
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.
2.3.1 flash commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 19
Bluetooth Smart Software API Reference Manual
API Reference
2.3.1.1 cmd_flash_ps_dump
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.26. 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.27. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call flash_ps_dump()(result)
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.28. Events Generated
Event
Description
flash_ps_key
PS Key contents
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 20
Bluetooth Smart Software API Reference Manual
API Reference
2.3.1.2 cmd_flash_ps_erase
This command can be used to erase a single PS key and its value from the persistent store..
Table 2.29. 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
4-5
uint16
key
Message ID
PS key to erase
Table 2.30. 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
0x04
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call flash_ps_erase(key)(result)
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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 21
Bluetooth Smart Software API Reference Manual
API Reference
2.3.1.3 cmd_flash_ps_erase_all
This command can be used to erase all PS keys and their corresponding values.
Table 2.31. 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.32. 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
0x01
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call flash_ps_erase_all()(result)
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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 22
Bluetooth Smart Software API Reference Manual
API Reference
2.3.1.4 cmd_flash_ps_load
This command can be used for retrieving the value of the specified PS key.
Table 2.33. 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
4-5
uint16
key
Message ID
PS key of the value to be retrieved
Table 2.34. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x03
lolen
Minimum payload length
2
0x0d
class
Message class: Persistent Store
3
0x03
method
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.
Message ID
BGScript command
call flash_ps_load(key)(result,value_len, value_data)
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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 23
Bluetooth Smart Software API Reference Manual
API Reference
2.3.1.5 cmd_flash_ps_save
This command can be used to store a value into the specified PS key. Allowed PS keys are in range from 0x4000 to 0x407F
Table 2.35. 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
4-5
uint16
key
6
uint8array
value
Message ID
PS key
Value to store into the specified PS key.
Table 2.36. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call flash_ps_save(key,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_flash_ps_save_rsp_t *gecko_cmd_flash_ps_save(uint16 key, uint8array value);
/* Response id */
gecko_rsp_flash_ps_save_id
/* Response structure */
struct gecko_msg_flash_ps_save_rsp_t
{
uint16 result
}
2.3.2 flash events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 24
Bluetooth Smart Software API Reference Manual
API Reference
2.3.2.1 evt_flash_ps_key
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.
Table 2.37. Event
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
4-5
uint16
key
6
uint8array
value
Message ID
PS key
Current value of the PS key specified in this event.
BGScript event
event flash_ps_key(key,value_len, value_data)
C Functions
/* Event id */
gecko_evt_flash_ps_key_id
/* Event structure */
struct gecko_msg_flash_ps_key_evt_t
{
uint16 key,
uint8array value
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 25
Bluetooth Smart Software API Reference Manual
API Reference
2.4 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.4.1 gatt commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 26
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.1 cmd_gatt_discover_characteristics
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.38. 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
4
uint8
connection
5-8
uint32
service
Message ID
Connection handle
GATT service handle
This value is normally received from the gatt_service event.
Table 2.39. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_discover_characteristics(connection,service)(result)
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
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 27
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.40. 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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 28
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.2 cmd_gatt_discover_characteristics_by_uuid
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.41. 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
4
uint8
connection
5-8
uint32
service
Message ID
Connection handle
GATT service handle
This value is normally received from the gatt_service event.
9
uint8array
uuid
Characteristic UUID
Table 2.42. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_discover_characteristics_by_uuid(connection,service,uuid_len, uuid_data)(result)
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, uint8array uuid);
/* Response id */
gecko_rsp_gatt_discover_characteristics_by_uuid_id
/* Response structure */
struct gecko_msg_gatt_discover_characteristics_by_uuid_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 29
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.43. 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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 30
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.3 cmd_gatt_discover_descriptors
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.44. 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
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
Table 2.45. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_discover_descriptors(connection,characteristic)(result)
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
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 31
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.46. 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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 32
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.4 cmd_gatt_discover_primary_services
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.47. 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
4
uint8
connection
Message ID
Connection handle
Table 2.48. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_discover_primary_services(connection)(result)
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.49. 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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 33
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.5 cmd_gatt_discover_primary_services_by_uuid
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.50. 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
4
uint8
connection
Connection handle
5
uint8array
uuid
Characteristic UUID
Message ID
Table 2.51. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_discover_primary_services_by_uuid(connection,uuid_len, uuid_data)(result)
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, uint8array uuid);
/* 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.52. Events Generated
Event
Description
gatt_service
Discovered service from remote GATT database.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 34
Bluetooth Smart Software API Reference Manual
API Reference
Event
Description
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 35
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.6 cmd_gatt_execute_characteristic_value_write
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.53. 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
4
uint8
connection
5
uint8
flags
Message ID
Connection handle
Unsigned 8-bit integer
Table 2.54. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_execute_characteristic_value_write(connection,flags)(result)
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.55. Events Generated
Event
Description
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 36
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.7 cmd_gatt_find_included_services
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.56. 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
4
uint8
connection
5-8
uint32
service
Message ID
Connection handle
GATT service handle
This value is normally received from the gatt_service event.
Table 2.57. 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
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_find_included_services(connection,service)(result)
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
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 37
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.58. 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 | Smart. Connected. Energy-friendly.
Rev. 1.3 | 38
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.8 cmd_gatt_prepare_characteristic_value_write
This command can be used to add a characteristic value to the write queue of a remote GATT server. This command can be used in
cases where very long attributes need to be written, or a set of values needs to be written atomically. In all cases where the amount of
data to transfer fits into the BGAPI payload the command gatt_write_characteristic_value is recommended for writing long values since
it transparently performs the prepare_write and execute_write commands. A received evt_gatt_characteristic_value event can be used
to verify that the data has been transmitted. Writes are executed or cancelled with the execute_characteristic_value_write command.
Whether the writes succeeded or not are indicated in the response of the execute_characteristic_value_write command.
Table 2.59. 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
0x0b
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7-8
uint16
offset
Offset of the characteristic value
9
uint8array
value
Value to write into the specified characteristic of the remote GATT
database
Table 2.60. 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
0x0b
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_prepare_characteristic_value_write(connection,characteristic,offset,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_prepare_characteristic_value_write_rsp_t *gecko_cmd_gatt_prepare_characteristic_value_wri
te(uint8 connection, uint16 characteristic, uint16 offset, uint8array value);
/* Response id */
gecko_rsp_gatt_prepare_characteristic_value_write_id
/* Response structure */
struct gecko_msg_gatt_prepare_characteristic_value_write_rsp_t
{
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 39
Bluetooth Smart Software API Reference Manual
API Reference
uint16 result
}
Table 2.61. Events Generated
Event
Description
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 40
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.9 cmd_gatt_read_characteristic_value
This command can be used to read the value of a characteristic from a remote GATT database. A single gatt_characteristic_value
event is generated if the length of the characteristic value returned by the remote GATT server is less than or equal to the size of the
GATT MTU. If the length of the value exceeds the size of the GATT MTU more than one gatt_characteristic_value event is generated
because the firmware will automatically use the "read long" GATT procedure. A received gatt_procedure_completed event indicates
that all data has been read successfully or that an error response has been received.
Table 2.62. 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
0x07
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
Table 2.63. 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
0x07
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_read_characteristic_value(connection,characteristic)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_read_characteristic_value_rsp_t *gecko_cmd_gatt_read_characteristic_value(uint8 connectio
n, uint16 characteristic);
/* Response id */
gecko_rsp_gatt_read_characteristic_value_id
/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 41
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.64. Events Generated
Event
Description
gatt_characteristic_value
This event contains the data belonging to a characteristic sent by the GATT Server.
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 42
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.10 cmd_gatt_read_characteristic_value_by_uuid
This command can be used to read the characteristic value of a service from a remote GATT database by giving the UUID of the characteristic and the handle of the service containing this characteristic. A single gatt_characteristic_value event is generated if the length
of the characteristic value returned by the remote GATT server is less than or equal to the size of the GATT MTU. If the length of the
value exceeds the size of the GATT MTU more than one gatt_characteristic_value event is generated because the firmware will automatically use the "read long" GATT procedure. A received gatt_procedure_completed event indicates that all data has been read successfully or that an error response has been received.
Table 2.65. 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
0x08
method
4
uint8
connection
5-8
uint32
service
Message ID
Connection handle
GATT service handle
This value is normally received from the gatt_service event.
9
uint8array
uuid
Characteristic UUID
Table 2.66. 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
0x08
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_read_characteristic_value_by_uuid(connection,service,uuid_len, uuid_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_read_characteristic_value_by_uuid_rsp_t *gecko_cmd_gatt_read_characteristic_value_by_uui
d(uint8 connection, uint32 service, uint8array uuid);
/* Response id */
gecko_rsp_gatt_read_characteristic_value_by_uuid_id
/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_by_uuid_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 43
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.67. Events Generated
Event
Description
gatt_characteristic_value
This event contains the data belonging to a characteristic sent by the GATT Server.
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 44
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.11 cmd_gatt_read_descriptor_value
This command can be used to read the descriptor value of a characteristic in a remote GATT database. A single gatt_descriptor_value
event is generated if the length of the descriptor value returned by the remote GATT server is less than or equal to the size of the GATT
MTU. If the length of the value exceeds the size of the GATT MTU more than one gatt_descriptor_value event is generated because
the firmware will automatically use the "read long" GATT procedure. A received gatt_procedure_completed event indicates that all data
has been read successfully or that an error response has been received.
Table 2.68. 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
0x0e
method
4
uint8
connection
Connection handle
5-6
uint16
descriptor
GATT characteristic descriptor handle
Message ID
Table 2.69. 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
0x0e
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_read_descriptor_value(connection,descriptor)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_read_descriptor_value_rsp_t *gecko_cmd_gatt_read_descriptor_value(uint8 connection, uint1
6 descriptor);
/* Response id */
gecko_rsp_gatt_read_descriptor_value_id
/* Response structure */
struct gecko_msg_gatt_read_descriptor_value_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 45
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.70. Events Generated
Event
Description
gatt_descriptor_value
Descriptor value received from the remote GATT server.
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 46
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.12 cmd_gatt_read_multiple_characteristic_values
This command can be used to read the values of multiple characteristics from a remote GATT database at once. gatt_characteristic_value events are generated as the values are returned by the remote GATT server. A received gatt_procedure_completed event
indicates that either all data has been read successfully or that an error response has been received.
Table 2.71. 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
0x11
method
4
uint8
connection
5
uint8array
characteristic_list
Message ID
Connection handle
Little endian encoded uint16 list of characteristics to be read.
Table 2.72. 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
0x11
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_read_multiple_characteristic_values(connection,characteristic_list_len, characteristic_list_data)(res
ult)
BGLIB C API
/* Function */
struct gecko_msg_gatt_read_multiple_characteristic_values_rsp_t *gecko_cmd_gatt_read_multiple_characteristic_va
lues(uint8 connection, uint8array characteristic_list);
/* Response id */
gecko_rsp_gatt_read_multiple_characteristic_values_id
/* Response structure */
struct gecko_msg_gatt_read_multiple_characteristic_values_rsp_t
{
uint16 result
}
Table 2.73. Events Generated
Event
Description
gatt_characteristic_value
This event contains the data belonging to a characteristic sent by the GATT Server.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 47
Bluetooth Smart Software API Reference Manual
API Reference
Event
Description
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
2.4.1.13 cmd_gatt_send_characteristic_confirmation
This command must be used to send a characteristic confirmation to a remote GATT server after receiving an indication. The gatt_characteristic_value_event carries the att_opcode containing handle_value_indication (0x1e) which reveals that an indication has been received and this must be confirmed with this command. Confirmation needs to be sent within 30 seconds, otherwise the GATT transactions between the client and the server are discontinued.
Table 2.74. 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
0x0d
method
4
uint8
connection
Message ID
Connection handle
Table 2.75. 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
0x0d
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_send_characteristic_confirmation(connection)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_send_characteristic_confirmation_rsp_t *gecko_cmd_gatt_send_characteristic_confirmation(u
int8 connection);
/* Response id */
gecko_rsp_gatt_send_characteristic_confirmation_id
/* Response structure */
struct gecko_msg_gatt_send_characteristic_confirmation_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 48
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.14 cmd_gatt_set_characteristic_notification
This command can be used to enable or disable the notifications and indications being sent from a remote GATT server. This procedure discovers a characteristic client configuration descriptor and writes the related configuration flags to a remote GATT database. A
received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or that is has failed with an
error.
Table 2.76. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x05
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8
flags
Characteristic client configuration flags
Table 2.77. 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
0x05
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_set_characteristic_notification(connection,characteristic,flags)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_set_characteristic_notification_rsp_t *gecko_cmd_gatt_set_characteristic_notification(uin
t8 connection, uint16 characteristic, uint8 flags);
/* Response id */
gecko_rsp_gatt_set_characteristic_notification_id
/* Response structure */
struct gecko_msg_gatt_set_characteristic_notification_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 49
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.78. Events Generated
Event
Description
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
gatt_characteristic_value
If an indication or notification has been enabled for a characteristic, this event is triggered whenever an indication or notification is sent by the remote GATT server. The triggering conditions on the GATT server side are defined by an upper level, for example by
a profile; so it is possible that no values are ever received, or that it may take time,
depending on how the server is configured.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 50
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.15 cmd_gatt_write_characteristic_value
This command can be used to write the value of a characteristic in a remote GATT database. If the length of the given value is greater
than the exchanged GATT MTU (Message Transfer Unit), "write long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been written successfully or that an error response has been received.
Table 2.79. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x09
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8array
value
Characteristic value
Table 2.80. 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
0x09
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_write_characteristic_value(connection,characteristic,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_write_characteristic_value_rsp_t *gecko_cmd_gatt_write_characteristic_value(uint8 connect
ion, uint16 characteristic, uint8array value);
/* Response id */
gecko_rsp_gatt_write_characteristic_value_id
/* Response structure */
struct gecko_msg_gatt_write_characteristic_value_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 51
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.81. Events Generated
Event
Description
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 52
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.16 cmd_gatt_write_characteristic_value_without_response
This command can be used to write the value of a characteristic in a remote GATT database. This command does not generate any
event. All failures on the server are ignored silently. For example, if an error is generated in the remote GATT server and the given
value is not written into database no error message will be reported to the local GATT client. Note that this command cannot be used to
write long values.
Table 2.82. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x0a
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8array
value
Characteristic value
Table 2.83. 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
0x0a
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_write_characteristic_value_without_response(connection,characteristic,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_write_characteristic_value_without_response_rsp_t *gecko_cmd_gatt_write_characteristic_va
lue_without_response(uint8 connection, uint16 characteristic, uint8array value);
/* Response id */
gecko_rsp_gatt_write_characteristic_value_without_response_id
/* Response structure */
struct gecko_msg_gatt_write_characteristic_value_without_response_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 53
Bluetooth Smart Software API Reference Manual
API Reference
2.4.1.17 cmd_gatt_write_descriptor_value
This command can be used to write the value of a characteristic descriptor in a remote GATT database. If the length of the given value
is greater than the exchanged GATT MTU size, "write long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been written succesfully or that an error response has been received.
Table 2.84. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x0f
method
4
uint8
connection
Connection handle
5-6
uint16
descriptor
GATT characteristic descriptor handle
7
uint8array
value
Message ID
Descriptor value
Table 2.85. 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
0x0f
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_write_descriptor_value(connection,descriptor,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_write_descriptor_value_rsp_t *gecko_cmd_gatt_write_descriptor_value(uint8 connection, uin
t16 descriptor, uint8array value);
/* Response id */
gecko_rsp_gatt_write_descriptor_value_id
/* Response structure */
struct gecko_msg_gatt_write_descriptor_value_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 54
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.86. Events Generated
Event
Description
gatt_procedure_completed
Procedure has been successfully completed or failed with error.
2.4.2 gatt events
2.4.2.1 evt_gatt_characteristic
This event indicates that a GATT characteristic in the remote GATT database was discovered. This event is generated after issuing
either the gatt_discover_characteristics or command.
Table 2.87. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x05
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x02
method
4
uint8
connection
5-6
uint16
characteristic
7
uint8
properties
8
uint8array
uuid
Message ID
Connection handle
GATT characteristic handle
Characteristic properties
Characteristic UUID
BGScript event
event gatt_characteristic(connection,characteristic,properties,uuid_len, uuid_data)
C Functions
/* Event id */
gecko_evt_gatt_characteristic_id
/* Event structure */
struct gecko_msg_gatt_characteristic_evt_t
{
uint8 connection,
uint16 characteristic,
uint8 properties,
uint8array uuid
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 55
Bluetooth Smart Software API Reference Manual
API Reference
2.4.2.2 evt_gatt_characteristic_value
This event indicates that the value of a characteristic in the remote GATT server was received. This event is triggered as a result of
several commands: gatt_read_characteristic_value, , gatt_read_multiple_characteristic_values, gatt_prepare_characteristic_value_write; and when the remote GATT server sends indications or notifications after enabling notifications with gatt_set_characteristic_notification. The parameter att_opcode reveals which type of GATT transaction triggered this event. In particular, if the att_opcode
type is handle_value_indication (0x1d), the application needs to confirm the indication with gatt_send_characteristic_confirmation.
Table 2.88. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x07
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x04
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8
att_opcode
Attribute opcode which informs the GATT transaction used
8-9
uint16
offset
Value offset
10
uint8array
value
Characteristic value
BGScript event
event gatt_characteristic_value(connection,characteristic,att_opcode,offset,value_len, value_data)
C Functions
/* Event id */
gecko_evt_gatt_characteristic_value_id
/* Event structure */
struct gecko_msg_gatt_characteristic_value_evt_t
{
uint8 connection,
uint16 characteristic,
uint8 att_opcode,
uint16 offset,
uint8array value
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 56
Bluetooth Smart Software API Reference Manual
API Reference
2.4.2.3 evt_gatt_descriptor
This event indicates that a GATT characteristic descriptor in the remote GATT database was discovered. This event is generated after
issuing the gatt_discover_descriptors command.
Table 2.89. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x04
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x03
method
4
uint8
connection
Connection handle
5-6
uint16
descriptor
GATT characteristic descriptor handle
7
uint8array
uuid
Message ID
Characteristic UUID
BGScript event
event gatt_descriptor(connection,descriptor,uuid_len, uuid_data)
C Functions
/* Event id */
gecko_evt_gatt_descriptor_id
/* Event structure */
struct gecko_msg_gatt_descriptor_evt_t
{
uint8 connection,
uint16 descriptor,
uint8array uuid
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 57
Bluetooth Smart Software API Reference Manual
API Reference
2.4.2.4 evt_gatt_descriptor_value
This event indicates that the value of a descriptor in the remote GATT server was received. This event is generated by the
gatt_read_descriptor_value command.
Table 2.90. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x06
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x05
method
4
uint8
connection
Connection handle
5-6
uint16
descriptor
GATT characteristic descriptor handle
7-8
uint16
offset
Value offset
9
uint8array
value
Descriptor value
Message ID
BGScript event
event gatt_descriptor_value(connection,descriptor,offset,value_len, value_data)
C Functions
/* Event id */
gecko_evt_gatt_descriptor_value_id
/* Event structure */
struct gecko_msg_gatt_descriptor_value_evt_t
{
uint8 connection,
uint16 descriptor,
uint16 offset,
uint8array value
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 58
Bluetooth Smart Software API Reference Manual
API Reference
2.4.2.5 evt_gatt_procedure_completed
This event indicates that the current GATT procedure has been completed successfully or that is has failed with an error. All GATT
commands excluding gatt_write_characteristic_value_without_response and gatt_send_characteristic_confirmation will trigger this
event, so the application must wait for this event before issuing another GATT command (excluding the two aforementioned exceptions).
Table 2.91. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x03
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x06
method
4
uint8
connection
5-6
uint16
result
Message ID
Connection handle
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript event
event gatt_procedure_completed(connection,result)
C Functions
/* Event id */
gecko_evt_gatt_procedure_completed_id
/* Event structure */
struct gecko_msg_gatt_procedure_completed_evt_t
{
uint8 connection,
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 59
Bluetooth Smart Software API Reference Manual
API Reference
2.4.2.6 evt_gatt_service
This event indicates that a GATT service in the remote GATT database was discovered. This event is generated after issuing either the
gatt_discover_primary_services or command.
Table 2.92. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x06
lolen
Minimum payload length
2
0x09
class
Message class: Generic Attribute Profile
3
0x01
method
4
uint8
connection
5-8
uint32
service
GATT service handle
9
uint8array
uuid
Characteristic UUID
Message ID
Connection handle
BGScript event
event gatt_service(connection,service,uuid_len, uuid_data)
C Functions
/* Event id */
gecko_evt_gatt_service_id
/* Event structure */
struct gecko_msg_gatt_service_evt_t
{
uint8 connection,
uint32 service,
uint8array uuid
}
2.4.3 gatt enumerations
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 60
Bluetooth Smart Software API Reference Manual
API Reference
2.4.3.1 enum_gatt_att_opcode
These values indicate which attribute request or response has caused the event.
Table 2.93. Enumerations
Value
Name
Description
8
gatt_read_by_type_request
Read by type request
9
gatt_read_by_type_response
Read by type response
10
gatt_read_request
Read request
11
gatt_read_response
Read response
12
gatt_read_blob_request
Read blob request
13
gatt_read_blob_response
Read blob response
14
gatt_read_multiple_request
Read multiple request
15
gatt_read_multiple_response
Read multiple response
18
gatt_write_request
Write request
19
gatt_write_response
Write response
82
gatt_write_command
Write command
22
gatt_prepare_write_request
Prepare write request
23
gatt_prepare_write_response
Prepare write response
24
gatt_execute_write_request
Execute write request
25
gatt_execute_write_response
Execute write response
27
gatt_handle_value_notification
Notification
29
gatt_handle_value_indication
Indication
2.4.3.2 enum_gatt_client_config_flag
These values define whether the client is to receive notifications or indications from a remote GATT server.
Table 2.94. Enumerations
Value
Name
Description
0
gatt_disable
Disable notifications and indications
1
gatt_notification
Notification
2
gatt_indication
Indication
2.4.3.3 enum_gatt_execute_write_flag
These values define whether the GATT server is to cancel all queued writes or commit all queued writes to a remote database.
Table 2.95. Enumerations
Value
Name
Description
0
gatt_cancel
Cancel all queued writes
1
gatt_commit
Commit all queued writes
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 61
Bluetooth Smart Software API Reference Manual
API Reference
2.5 Generic Attribute Profile Server (gatt_server)
These commands and events are used by the local GATT server to manage the local GATT database.
2.5.1 gatt_server commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 62
Bluetooth Smart Software API Reference Manual
API Reference
2.5.1.1 cmd_gatt_server_find_attribute
This command can be used to find attributes of certain type from a local GATT database. Type is usually given as 16-bit or 128-bit
UUID.
Table 2.96. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x03
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x06
method
4-5
uint16
start
Search start index
6
uint8array
type
Variable length byte array. The first byte defines the length of the
data that follows, 0 - 255 bytes.
Message ID
Table 2.97. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x04
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x06
method
4-5
uint16
result
6-7
uint16
attribute
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
Attribute handle
BGScript command
call gatt_server_find_attribute(start,type_len, type_data)(result,attribute)
BGLIB C API
/* Function */
struct gecko_msg_gatt_server_find_attribute_rsp_t *gecko_cmd_gatt_server_find_attribute(uint16 start, uint8arra
y type);
/* Response id */
gecko_rsp_gatt_server_find_attribute_id
/* Response structure */
struct gecko_msg_gatt_server_find_attribute_rsp_t
{
uint16 result,
uint16 attribute
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 63
Bluetooth Smart Software API Reference Manual
API Reference
2.5.1.2 cmd_gatt_server_read_attribute_type
This command can be used to read the type of an attribute from a local GATT database. The type is a UUID, usually 16 or 128 bits
long.
Table 2.98. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x01
method
Message ID
4-5
uint16
attribute
Attribute handle
Table 2.99. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x03
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x01
method
4-5
uint16
result
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6
uint8array
type
Variable length byte array. The first byte defines the length of the
data that follows, 0 - 255 bytes.
Message ID
BGScript command
call gatt_server_read_attribute_type(attribute)(result,type_len, type_data)
BGLIB C API
/* Function */
struct gecko_msg_gatt_server_read_attribute_type_rsp_t *gecko_cmd_gatt_server_read_attribute_type(uint16 attrib
ute);
/* Response id */
gecko_rsp_gatt_server_read_attribute_type_id
/* Response structure */
struct gecko_msg_gatt_server_read_attribute_type_rsp_t
{
uint16 result,
uint8array type
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 64
Bluetooth Smart Software API Reference Manual
API Reference
2.5.1.3 cmd_gatt_server_read_attribute_value
This command can be used to read the value of an attribute from a local GATT database.
Table 2.100. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x00
method
Message ID
4-5
uint16
attribute
Attribute handle
6-7
uint16
offset
Value offset
Table 2.101. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x03
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x00
method
4-5
uint16
result
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6
uint8array
value
Variable length byte array. The first byte defines the length of the
data that follows, 0 - 255 bytes.
Message ID
BGScript command
call gatt_server_read_attribute_value(attribute,offset)(result,value_len, value_data)
BGLIB C API
/* Function */
struct gecko_msg_gatt_server_read_attribute_value_rsp_t *gecko_cmd_gatt_server_read_attribute_value(uint16 attr
ibute, uint16 offset);
/* Response id */
gecko_rsp_gatt_server_read_attribute_value_id
/* Response structure */
struct gecko_msg_gatt_server_read_attribute_value_rsp_t
{
uint16 result,
uint8array value
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 65
Bluetooth Smart Software API Reference Manual
API Reference
2.5.1.4 cmd_gatt_server_send_characteristic_notification
This command can be used to send notifications or indications to a remote GATT client. Notification or indication is sent only if the client
has enabled them by setting the corresponding flag to the Client Characteristic Configuration descriptor. A new notification or indication
cannot be sent before a confirmation from the GATT client is first received. The confirmation is indicated by
gatt_server_characteristic_status event.
Table 2.102. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x05
method
4
uint8
connection
5-6
uint16
characteristic
7
uint8array
value
Message ID
Handle of the connection over which the notification or indication
is sent. Values:
• 0xff: Sends notification or indication to all connected devices.
• Other: Connection handle
Characteristic handle
Value to be notified or indicated
Table 2.103. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x05
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_server_send_characteristic_notification(connection,characteristic,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_server_send_characteristic_notification_rsp_t *gecko_cmd_gatt_server_send_characteristic_
notification(uint8 connection, uint16 characteristic, uint8array value);
/* Response id */
gecko_rsp_gatt_server_send_characteristic_notification_id
/* Response structure */
struct gecko_msg_gatt_server_send_characteristic_notification_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 66
Bluetooth Smart Software API Reference Manual
API Reference
2.5.1.5 cmd_gatt_server_send_user_read_response
This command must be used to send a response to a user_read_request event. The response needs to be sent within 30 second, otherwise no more GATT transactions are allowed by the remote side. If attr_errorcode is set to 0 the characteristic value is sent to the
remote GATT client in the normal way. Other attr_errorcode values will cause the local GATT server to send an attribute protocol error
response instead of the actual data.
Table 2.104. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x05
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x03
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8
att_errorcode
8
uint8array
value
Attribute protocol error code
• 0: No error
• Non-zero: see link
Characteristic value to send to the GATT client. Ignored if att_errorcode is not 0.
Table 2.105. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x03
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_server_send_user_read_response(connection,characteristic,att_errorcode,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_server_send_user_read_response_rsp_t *gecko_cmd_gatt_server_send_user_read_response(uint
8 connection, uint16 characteristic, uint8 att_errorcode, uint8array value);
/* Response id */
gecko_rsp_gatt_server_send_user_read_response_id
/* Response structure */
struct gecko_msg_gatt_server_send_user_read_response_rsp_t
{
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 67
Bluetooth Smart Software API Reference Manual
API Reference
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 68
Bluetooth Smart Software API Reference Manual
API Reference
2.5.1.6 cmd_gatt_server_send_user_write_response
This command must be used to send a response to a gatt_server_user_write_request event. The response needs to be sent within 30
seconds, otherwise no more GATT transactions are allowed by the remote side. If attr_errorcode is set to 0 the ATT protocol's write
response is sent to indicate to the remote GATT client that the write operation was processed successfully. Other values will cause the
local GATT server to send an ATT protocol error response.
Table 2.106. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x04
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8
att_errorcode
Attribute protocol error code
• 0: No error
• Non-zero: see link
Table 2.107. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x04
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_server_send_user_write_response(connection,characteristic,att_errorcode)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_server_send_user_write_response_rsp_t *gecko_cmd_gatt_server_send_user_write_response(uin
t8 connection, uint16 characteristic, uint8 att_errorcode);
/* Response id */
gecko_rsp_gatt_server_send_user_write_response_id
/* Response structure */
struct gecko_msg_gatt_server_send_user_write_response_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 69
Bluetooth Smart Software API Reference Manual
API Reference
2.5.1.7 cmd_gatt_server_write_attribute_value
This command can be used to write the value of an attribute in the local GATT database. Writing the value of a characteristic of the
local GATT database will not trigger notifications or indications to the remote GATT client in case such characteristic has property of
indicate or notify and the client has enabled notification or indication. Notifications and indications are sent to the remote GATT client
using gatt_server_send_characteristic_notification command.
Table 2.108. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x05
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x02
method
Message ID
4-5
uint16
attribute
Attribute handle
6-7
uint16
offset
Value offset
8
uint8array
value
Value
Table 2.109. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x02
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call gatt_server_write_attribute_value(attribute,offset,value_len, value_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_gatt_server_write_attribute_value_rsp_t *gecko_cmd_gatt_server_write_attribute_value(uint16 at
tribute, uint16 offset, uint8array value);
/* Response id */
gecko_rsp_gatt_server_write_attribute_value_id
/* Response structure */
struct gecko_msg_gatt_server_write_attribute_value_rsp_t
{
uint16 result
}
2.5.2 gatt_server events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 70
Bluetooth Smart Software API Reference Manual
API Reference
2.5.2.1 evt_gatt_server_attribute_value
This event indicates that the value of an attribute in the local GATT database has been changed by a remote GATT client. Parameter
att_opcode describes which GATT procedure was used to change the value.
Table 2.110. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x07
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x00
method
4
uint8
connection
5-6
uint16
attribute
7
uint8
att_opcode
8-9
uint16
offset
Value offset
10
uint8array
value
Value
Message ID
Connection handle
Attribute Handle
Attribute opcode which informs the procedure from which attribute
the value was received
BGScript event
event gatt_server_attribute_value(connection,attribute,att_opcode,offset,value_len, value_data)
C Functions
/* Event id */
gecko_evt_gatt_server_attribute_value_id
/* Event structure */
struct gecko_msg_gatt_server_attribute_value_evt_t
{
uint8 connection,
uint16 attribute,
uint8 att_opcode,
uint16 offset,
uint8array value
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 71
Bluetooth Smart Software API Reference Manual
API Reference
2.5.2.2 evt_gatt_server_characteristic_status
This event indicates either that a local Client Characteristic Configuration descriptor has been changed by the remote GATT client, or
that a confirmation from the remote GATT client was received upon a successful reception of the indication. Confirmation by the remote
GATT client should be received within 30 seconds after an indication has been sent with the gatt_server_send_characteristic_notification command, otherwise further GATT transactions over this connection are disabled by the stack.
Table 2.111. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x06
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x03
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8
status_flags
8-9
uint16
client_config_flags
Describes whether Client Characteristic Configuration was
changed or if confirmation was received.
This field carries the new value of the Client Characteristic Configuration. If the status_flags is 0x2 (confirmation received), the value of this field can be ignored.
BGScript event
event gatt_server_characteristic_status(connection,characteristic,status_flags,client_config_flags)
C Functions
/* Event id */
gecko_evt_gatt_server_characteristic_status_id
/* Event structure */
struct gecko_msg_gatt_server_characteristic_status_evt_t
{
uint8 connection,
uint16 characteristic,
uint8 status_flags,
uint16 client_config_flags
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 72
Bluetooth Smart Software API Reference Manual
API Reference
2.5.2.3 evt_gatt_server_execute_write_completed
Execute write completed event indicates that the execute write command from a remote GATT client has completed with the given result.
Table 2.112. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x03
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x04
method
4
uint8
connection
Connection handle
5-6
uint16
result
Execute write result
Message ID
BGScript event
event gatt_server_execute_write_completed(connection,result)
C Functions
/* Event id */
gecko_evt_gatt_server_execute_write_completed_id
/* Event structure */
struct gecko_msg_gatt_server_execute_write_completed_evt_t
{
uint8 connection,
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 73
Bluetooth Smart Software API Reference Manual
API Reference
2.5.2.4 evt_gatt_server_user_read_request
This event indicates that a remote GATT client is attempting to read a value of an attribute from the local GATT database, where the
attribute was defined in the GATT XML firmware configuration file to have type="user". Parameter att_opcode informs which GATT procedure was used to read the value. The application needs to respond to this request by using the gatt_server_send_user_read_response command within 30 seconds, otherwise this GATT connection is dropped by remote side.
Table 2.113. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x06
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x01
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8
att_opcode
8-9
uint16
offset
Attribute opcode which informs the procedure from which attribute
the value was received
Value offset
BGScript event
event gatt_server_user_read_request(connection,characteristic,att_opcode,offset)
C Functions
/* Event id */
gecko_evt_gatt_server_user_read_request_id
/* Event structure */
struct gecko_msg_gatt_server_user_read_request_evt_t
{
uint8 connection,
uint16 characteristic,
uint8 att_opcode,
uint16 offset
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 74
Bluetooth Smart Software API Reference Manual
API Reference
2.5.2.5 evt_gatt_server_user_write_request
This event indicates that a remote GATT client is attempting to write a value of an attribute in to the local GATT database, where the
attribute was defined in the GATT XML firmware configuration file to have type="user". Parameter att_opcode informs which attribute
procedure was used to write the value. The application needs to respond to this request by using the gatt_server_send_user_write_response command within 30 seconds, otherwise this GATT connection is dropped by the remote side. If the value of att_opcode is Execute Write Request, it indicates that this is a queued prepare write request received earlier and now the GATT server is processing the
execute write. The event gatt_server_execute_write_completed will be emitted after all queued requests have been processed.
Table 2.114. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x07
lolen
Minimum payload length
2
0x0a
class
Message class: Generic Attribute Profile Server
3
0x02
method
4
uint8
connection
5-6
uint16
characteristic
Message ID
Connection handle
GATT characteristic handle
This value is normally received from the gatt_characteristic event.
7
uint8
att_opcode
Attribute opcode which informs the procedure from which attribute
the value was received
8-9
uint16
offset
Value offset
10
uint8array
value
Value
BGScript event
event gatt_server_user_write_request(connection,characteristic,att_opcode,offset,value_len, value_data)
C Functions
/* Event id */
gecko_evt_gatt_server_user_write_request_id
/* Event structure */
struct gecko_msg_gatt_server_user_write_request_evt_t
{
uint8 connection,
uint16 characteristic,
uint8 att_opcode,
uint16 offset,
uint8array value
}
2.5.3 gatt_server enumerations
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 75
Bluetooth Smart Software API Reference Manual
API Reference
2.5.3.1 enum_gatt_server_characteristic_status_flag
These values describe whether characteristic client configuration was changed or whether a characteristic confirmation was received.
Table 2.115. Enumerations
Value
Name
Description
1
gatt_server_client_config
Characteristic client configuration has been changed.
2
gatt_server_confirmation
Characteristic confirmation has been received.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 76
Bluetooth Smart Software API Reference Manual
API Reference
2.6 Hardware (hardware)
The commands and events in this class can be used to access and configure the system hardware and peripherals.
2.6.1 hardware commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 77
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.1 cmd_hardware_configure_gpio
This command can be used to configure the mode of an I/O port. After a boot, the device uses the default settings defined in hardware.xml, and this command can used to override the default settings. Note that GPIO configurations set with this command do not
persist over a reset.
Table 2.116. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x01
method
4
uint8
port
Port index, where A=0, B=1.
5
uint8
gpio
Index of the GPIO pin on the port which this command affects.
6
uint8
mode
Pin mode
7
uint8
output
Pin DOUT state
Message ID
Table 2.117. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x01
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call hardware_configure_gpio(port,gpio,mode,output)(result)
BGLIB C API
/* Function */
struct gecko_msg_hardware_configure_gpio_rsp_t *gecko_cmd_hardware_configure_gpio(uint8 port, uint8 gpio, uint
8 mode, uint8 output);
/* Response id */
gecko_rsp_hardware_configure_gpio_id
/* Response structure */
struct gecko_msg_hardware_configure_gpio_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 78
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.2 cmd_hardware_config_adc_reference
This command can be used to configure the ADC reference. Default reference is VDD.
Table 2.118. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x05
method
4
uint8
reference
Message ID
ADC reference setting.
Table 2.119. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x05
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call hardware_config_adc_reference(reference)(result)
BGLIB C API
/* Function */
struct gecko_msg_hardware_config_adc_reference_rsp_t *gecko_cmd_hardware_config_adc_reference(uint8 reference);
/* Response id */
gecko_rsp_hardware_config_adc_reference_id
/* Response structure */
struct gecko_msg_hardware_config_adc_reference_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 79
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.3 cmd_hardware_read_adc
This command can be used to read the specified GPIO pin analog value.
Table 2.120. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x04
method
Message ID
4
uint8
port
GPIO Port.
5
uint8
pin
GPIO Pin.
Table 2.121. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x04
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x04
method
4-5
uint16
result
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6-7
uint16
value
ADC value
Message ID
BGScript command
call hardware_read_adc(port,pin)(result,value)
BGLIB C API
/* Function */
struct gecko_msg_hardware_read_adc_rsp_t *gecko_cmd_hardware_read_adc(uint8 port, uint8 pin);
/* Response id */
gecko_rsp_hardware_read_adc_id
/* Response structure */
struct gecko_msg_hardware_read_adc_rsp_t
{
uint16 result,
uint16 value
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 80
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.4 cmd_hardware_read_gpio
This command can be used to read the pins of the specified I/O-port of the device.
Table 2.122. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x03
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x03
method
4
uint8
port
5-6
uint16
mask
Message ID
Port index to read from, A=0, B=1.
Bitmask of which pins on the port should be read
Table 2.123. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x04
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x03
method
4-5
uint16
result
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6-7
uint16
data
Port data
Message ID
BGScript command
call hardware_read_gpio(port,mask)(result,data)
BGLIB C API
/* Function */
struct gecko_msg_hardware_read_gpio_rsp_t *gecko_cmd_hardware_read_gpio(uint8 port, uint16 mask);
/* Response id */
gecko_rsp_hardware_read_gpio_id
/* Response structure */
struct gecko_msg_hardware_read_gpio_rsp_t
{
uint16 result,
uint16 data
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 81
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.5 cmd_hardware_read_i2c
This command can be used to read from the specified I2C interface. The I2C interfaces must be configured in the hardware.xml file, as
described in the device Configuration Guide.
Table 2.124. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x06
method
Message ID
4
uint8
channel
I2C channel to use.
5-6
uint16
slave_address
7
uint8
length
Slave address to use
Amount of data to read
Table 2.125. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x03
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x06
method
4-5
uint16
result
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6
uint8array
data
Data that was read if command was successful
Message ID
BGScript command
call hardware_read_i2c(channel,slave_address,length)(result,data_len, data_data)
BGLIB C API
/* Function */
struct gecko_msg_hardware_read_i2c_rsp_t *gecko_cmd_hardware_read_i2c(uint8 channel, uint16 slave_address, uint
8 length);
/* Response id */
gecko_rsp_hardware_read_i2c_id
/* Response structure */
struct gecko_msg_hardware_read_i2c_rsp_t
{
uint16 result,
uint8array data
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 82
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.6 cmd_hardware_set_soft_timer
This command can be used to start a software timer. Multiple concurrent timers can be running simultaneously. There are 256 unique
timer ID's available, but in practice the amount of concurrent timers is limited by the amount of free memory.
Table 2.126. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x06
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x00
method
4-7
uint32
time
8
uint8
handle
9
uint8
single_shot
Message ID
Interval between how often to send events, in milliseconds. If time
is 0, removes the scheduled timer. The maximum value is
4294967295, which corresponds to about 49.7 days.
Timer handle to use, is returned in timeout event
Timer mode. Values:
• 0: false (timer is repeating)
• 1: true (timer runs only once)
Table 2.127. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x00
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call hardware_set_soft_timer(time,handle,single_shot)(result)
BGLIB C API
/* Function */
struct gecko_msg_hardware_set_soft_timer_rsp_t *gecko_cmd_hardware_set_soft_timer(uint32 time, uint8 handle, ui
nt8 single_shot);
/* Response id */
gecko_rsp_hardware_set_soft_timer_id
/* Response structure */
struct gecko_msg_hardware_set_soft_timer_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 83
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.128. Events Generated
Event
Description
hardware_soft_timer
Sent after specified interval
2.6.1.7 cmd_hardware_stop_i2c
This command can be used to stop I2C transmission.
Table 2.129. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x08
method
Message ID
4
uint8
channel
I2C channel to use.
Table 2.130. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x08
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call hardware_stop_i2c(channel)(result)
BGLIB C API
/* Function */
struct gecko_msg_hardware_stop_i2c_rsp_t *gecko_cmd_hardware_stop_i2c(uint8 channel);
/* Response id */
gecko_rsp_hardware_stop_i2c_id
/* Response structure */
struct gecko_msg_hardware_stop_i2c_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 84
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.8 cmd_hardware_write_gpio
This command can be used to set the logic states of pins of the specified I/O-port using a bitmask.
Table 2.131. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x05
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x02
method
4
uint8
port
5-6
uint16
mask
Bitmask which determines the pins this command is used to set
7-8
uint16
data
Bitmask of which pins to set high and which pins to set low (1 is
high, 0 is low)
Message ID
Port index, where A=0, B=1.
Table 2.132. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x02
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call hardware_write_gpio(port,mask,data)(result)
BGLIB C API
/* Function */
struct gecko_msg_hardware_write_gpio_rsp_t *gecko_cmd_hardware_write_gpio(uint8 port, uint16 mask, uint16 data)
;
/* Response id */
gecko_rsp_hardware_write_gpio_id
/* Response structure */
struct gecko_msg_hardware_write_gpio_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 85
Bluetooth Smart Software API Reference Manual
API Reference
2.6.1.9 cmd_hardware_write_i2c
This command can be used to write data into I2C interface. The I2C interfaces must be configured in the hardware.xml file, as described in the device Configuration Guide.
Table 2.133. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x07
method
Message ID
4
uint8
channel
I2C channel to use.
5-6
uint16
slave_address
7
uint8array
data
Slave address to use
Data to write
Table 2.134. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x07
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call hardware_write_i2c(channel,slave_address,data_len, data_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_hardware_write_i2c_rsp_t *gecko_cmd_hardware_write_i2c(uint8 channel, uint16 slave_address, ui
nt8array data);
/* Response id */
gecko_rsp_hardware_write_i2c_id
/* Response structure */
struct gecko_msg_hardware_write_i2c_rsp_t
{
uint16 result
}
2.6.2 hardware events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 86
Bluetooth Smart Software API Reference Manual
API Reference
2.6.2.1 evt_hardware_interrupt
This event indicates that an external interrupt has occurred and provides a timestamp and a mask which indicates all triggered interrupt
channels.
Table 2.135. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x08
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x01
method
4-7
uint32
interrupts
Mask of interrupt channels
8-11
uint32
timestamp
Timestamp
Message ID
BGScript event
event hardware_interrupt(interrupts,timestamp)
C Functions
/* Event id */
gecko_evt_hardware_interrupt_id
/* Event structure */
struct gecko_msg_hardware_interrupt_evt_t
{
uint32 interrupts,
uint32 timestamp
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 87
Bluetooth Smart Software API Reference Manual
API Reference
2.6.2.2 evt_hardware_soft_timer
This event indicates that the soft timer has lapsed.
Table 2.136. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x01
lolen
Minimum payload length
2
0x0c
class
Message class: Hardware
3
0x00
method
Message ID
4
uint8
handle
Timer Handle
BGScript event
event hardware_soft_timer(handle)
C Functions
/* Event id */
gecko_evt_hardware_soft_timer_id
/* Event structure */
struct gecko_msg_hardware_soft_timer_evt_t
{
uint8 handle
}
2.6.3 hardware enumerations
2.6.3.1 enum_hardware_adc_reference
ADC reference configuration options
Table 2.137. Enumerations
Value
Name
Description
0
hardware_adc_reference_1v25
Internal 1.25 V reference
1
hardware_adc_reference_2v5
Internal 2.5 V reference
2
hardware_adc_reference_vdd
Buffered VDD
3
hardware_adc_reference_5vdiff
Internal differential 5 V reference
4
hardware_adc_reference_extsingle
Single ended external reference from pin 6
5
hardware_adc_reference_2xextdiff
Differential external reference, 2x(pin 6 - pin 7)
6
hardware_adc_reference_2xvdd
Unbuffered 2xVDD
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 88
Bluetooth Smart Software API Reference Manual
API Reference
2.6.3.2 enum_hardware_gpio_mode
GPIO mode configuration
Table 2.138. Enumerations
Value
Name
Description
0
hardware_gpio_mode_disabled
Input disabled. Pullup if DOUT is set.
1
hardware_gpio_mode_input
Input enabled. Filter if DOUT is set
2
hardware_gpio_mode_input_pull
Input enabled. DOUT determines pull direction
3
hardware_gpio_mode_input_pull_filter
Input enabled with filter. DOUT determines pull direction
4
hardware_gpio_mode_push_pull
Push-pull output
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 89
Bluetooth Smart Software API Reference Manual
API Reference
2.7 Connection management for low energy (le_connection)
The commands and events in this class are related to managing connection establishment, parameter setting, and disconnection procedures.
2.7.1 le_connection commands
2.7.1.1 cmd_le_connection_disable_slave_latency
This command temporarily enables or disables slave latency. Used only when Bluetooth device is in slave role.
Table 2.139. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x02
method
4
uint8
connection
5
uint8
disable
Message ID
Connection Handle
0 enable, 1 disable slave latency
Table 2.140. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x02
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_connection_disable_slave_latency(connection,disable)(result)
BGLIB C API
/* Function */
struct gecko_msg_le_connection_disable_slave_latency_rsp_t *gecko_cmd_le_connection_disable_slave_latency(uint
8 connection, uint8 disable);
/* Response id */
gecko_rsp_le_connection_disable_slave_latency_id
/* Response structure */
struct gecko_msg_le_connection_disable_slave_latency_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 90
Bluetooth Smart Software API Reference Manual
API Reference
2.7.1.2 cmd_le_connection_get_rssi
This command can be used to get the latest RSSI value of a BLE connection.
Table 2.141. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x01
method
4
uint8
connection
Message ID
Connection handle
Table 2.142. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x01
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_connection_get_rssi(connection)(result)
BGLIB C API
/* Function */
struct gecko_msg_le_connection_get_rssi_rsp_t *gecko_cmd_le_connection_get_rssi(uint8 connection);
/* Response id */
gecko_rsp_le_connection_get_rssi_id
/* Response structure */
struct gecko_msg_le_connection_get_rssi_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 91
Bluetooth Smart Software API Reference Manual
API Reference
2.7.1.3 cmd_le_connection_set_parameters
This command can be used to request a change in the connection parameters of a Bluetooth LE connection.
Table 2.143. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x09
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x00
method
4
uint8
connection
Connection Handle
5-6
uint16
min_interval
Minimum value for the connection event interval. This must be set
be less than or equal to max_interval.
• Time = Value x 1.25 ms
• Range: 0x0006 to 0x0c80
• Time Range: 7.5 ms to 4 s
7-8
uint16
max_interval
Maximum value for the connection event interval. This must be
set greater than or equal to min_interval.
• Time = Value x 1.25 ms
• Range: 0x0006 to 0x0c80
• Time Range: 7.5 ms to 4 s
9-10
uint16
latency
Slave latency. This parameter defines how many connection intervals the slave can skip if it has no data to send
• Range: 0x0000 to 0x01f4
Use 0x0000 for default value
11-12
uint16
timeout
Supervision timeout. The supervision timeout defines for how long
the connection is maintained despite the devices being unable to
communicate at the currently configured connection intervals.
• Range: 0x000a to 0x0c80
• Time = Value x 10 ms
• Time Range: 100 ms to 32 s
• The minimum value must be at least maximum interval * (latency + 1)
It is recommended that the supervision timeout is set at a value
which allows communication attempts over at least a few connection intervals.
Message ID
Table 2.144. Response
Byte
Type
Name
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x00
method
4-5
uint16
result
silabs.com | Smart. Connected. Energy-friendly.
Description
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
Rev. 1.3 | 92
Bluetooth Smart Software API Reference Manual
API Reference
BGScript command
call le_connection_set_parameters(connection,min_interval,max_interval,latency,timeout)(result)
BGLIB C API
/* Function */
struct gecko_msg_le_connection_set_parameters_rsp_t *gecko_cmd_le_connection_set_parameters(uint8 connection, u
int16 min_interval, uint16 max_interval, uint16 latency, uint16 timeout);
/* Response id */
gecko_rsp_le_connection_set_parameters_id
/* Response structure */
struct gecko_msg_le_connection_set_parameters_rsp_t
{
uint16 result
}
Table 2.145. Events Generated
Event
Description
le_connection_parameters
This event is triggered after new connection parameters has been applied on the connection.
2.7.2 le_connection events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 93
Bluetooth Smart Software API Reference Manual
API Reference
2.7.2.1 evt_le_connection_closed
This event indicates that a connection was closed.
Table 2.146. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x03
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x01
method
Message ID
4-5
uint16
reason
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
6
uint8
connection
Handle of the closed connection
BGScript event
event le_connection_closed(reason,connection)
C Functions
/* Event id */
gecko_evt_le_connection_closed_id
/* Event structure */
struct gecko_msg_le_connection_closed_evt_t
{
uint16 reason,
uint8 connection
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 94
Bluetooth Smart Software API Reference Manual
API Reference
2.7.2.2 evt_le_connection_opened
This event indicates that a new connection was opened, whether the devices are already bonded, and what is the role of the Bluetooth
device (Slave or Master). An open connection can be closed with the command endpoint_close by giving the connection handle ID
obtained from this event.
Table 2.147. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x0a
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x00
method
Message ID
4-9
bd_addr
address
Remote device address
10
uint8
address_type
11
uint8
master
12
uint8
connection
Handle for new connection
13
uint8
bonding
Bonding handle. Values:
• 0xff: No bonding
• Other: Bonding handle
Remote device address type
Device role in connection. Values:
• 0: Slave
• 1: Master
BGScript event
event le_connection_opened(address,address_type,master,connection,bonding)
C Functions
/* Event id */
gecko_evt_le_connection_opened_id
/* Event structure */
struct gecko_msg_le_connection_opened_evt_t
{
bd_addr address,
uint8 address_type,
uint8 master,
uint8 connection,
uint8 bonding
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 95
Bluetooth Smart Software API Reference Manual
API Reference
2.7.2.3 evt_le_connection_parameters
This event is triggered whenever the connection parameters are changed and at any time a connection is established.
Table 2.148. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x08
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x02
method
4
uint8
connection
Connection handle
5-6
uint16
interval
Connection interval
7-8
uint16
latency
Slave latency
9-10
uint16
timeout
Supervision timeout
11
uint8
security_mode
Message ID
Connection security mode
BGScript event
event le_connection_parameters(connection,interval,latency,timeout,security_mode)
C Functions
/* Event id */
gecko_evt_le_connection_parameters_id
/* Event structure */
struct gecko_msg_le_connection_parameters_evt_t
{
uint8 connection,
uint16 interval,
uint16 latency,
uint16 timeout,
uint8 security_mode
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 96
Bluetooth Smart Software API Reference Manual
API Reference
2.7.2.4 evt_le_connection_rssi
This event is triggered when an le_connection_get_rssi command has completed.
Table 2.149. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x03
lolen
Minimum payload length
2
0x08
class
Message class: Connection management for low energy
3
0x03
method
4
uint8
connection
5
uint8
status
Command complete status
6
int8
rssi
RSSI of the BLE connection
Message ID
Connection handle
Range: -127 to +20. Units: dBm.
BGScript event
event le_connection_rssi(connection,status,rssi)
C Functions
/* Event id */
gecko_evt_le_connection_rssi_id
/* Event structure */
struct gecko_msg_le_connection_rssi_evt_t
{
uint8 connection,
uint8 status,
int8 rssi
}
2.7.3 le_connection enumerations
2.7.3.1 enum_le_connection_security
These values indicate the Bluetooth LE Security Mode.
Table 2.150. Enumerations
Value
Name
Description
0
le_connection_mode1_level1
No security
1
le_connection_mode1_level2
Unauthenticated pairing with encryption
2
le_connection_mode1_level3
Authenticated pairing with encryption
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 97
Bluetooth Smart Software API Reference Manual
API Reference
2.8 Generic Access Profile, Low Energy (le_gap)
The commands and events in this class are related to Generic Access Profile (GAP) in Bluetooth Low Energy (LE).
2.8.1 le_gap commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 98
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.1 cmd_le_gap_discover
This command can be used to start the GAP discovery procedure to scan for advertising devices, that is to perform a device discovery.
Scanning parameters can be configured with the le_gap_set_scan_parameters command before issuing this command. To cancel an
ongoing discovery process use the le_gap_end_procedure command.
Table 2.151. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x02
method
4
uint8
mode
Message ID
Bluetooth LE Discovery Mode. For values see link
Table 2.152. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x02
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_gap_discover(mode)(result)
BGLIB C API
/* Function */
struct gecko_msg_le_gap_discover_rsp_t *gecko_cmd_le_gap_discover(uint8 mode);
/* Response id */
gecko_rsp_le_gap_discover_id
/* Response structure */
struct gecko_msg_le_gap_discover_rsp_t
{
uint16 result
}
Table 2.153. Events Generated
Event
Description
le_gap_scan_response
Every time an advertisement packet is received, this event is triggered. The packets are
not filtered in any way, so multiple events will be received for every advertising device in
range.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 99
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.2 cmd_le_gap_end_procedure
This command can be used to end a current GAP procedure.
Table 2.154. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x00
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x03
method
Message ID
Table 2.155. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x03
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_gap_end_procedure()(result)
BGLIB C API
/* Function */
struct gecko_msg_le_gap_end_procedure_rsp_t *gecko_cmd_le_gap_end_procedure();
/* Response id */
gecko_rsp_le_gap_end_procedure_id
/* Response structure */
struct gecko_msg_le_gap_end_procedure_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 100
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.3 cmd_le_gap_open
This command can be used to connect an advertising device. Scanning parameters can be configured with the le_gap_set_scan_parameters command before issuing this command. To cancel on an ongoing connection process use the le_gap_end_procedure command.
A connection is opened in no-security mode. If the GATT client needs to read or write the attributes on GATT server requiring encryption or authentication, it must first encrypt the connection using an appropriate authentication method.
Table 2.156. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x07
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x00
method
Message ID
4-9
bd_addr
address
Address of the device to connect to
10
uint8
address_type
Address type of the device to connect to
Table 2.157. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x03
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x00
method
4-5
uint16
result
6
uint8
connection
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
Handle that will be assigned to the connection once the connection will be established. This handle is valid only if the result code
of this response is 0 (zero).
BGScript command
call le_gap_open(address,address_type)(result,connection)
BGLIB C API
/* Function */
struct gecko_msg_le_gap_open_rsp_t *gecko_cmd_le_gap_open(bd_addr address, uint8 address_type);
/* Response id */
gecko_rsp_le_gap_open_id
/* Response structure */
struct gecko_msg_le_gap_open_rsp_t
{
uint16 result,
uint8 connection
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 101
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.158. Events Generated
Event
Description
le_connection_opened
This event is triggered after the connection has been opened, and indicates whether the
devices are already bonded and what is the role of the Bluetooth device (Slave or Master).
le_connection_parameters
This event indicates the connection parameters and security mode of the connection.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 102
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.4 cmd_le_gap_set_adv_data
This command can be used together with le_gap_set_mode to advertise user defined data. First use this command to set the data in
advertisement packets and/or in the scan response packets, and then use command le_gap_set_mode to configure this device to be
discoverable in user_data mode.
Note that the user defined data may be overwritten by the system when this device is later configured to other discoverable mode than
user_data. It is recommended to set both the advertisement data and scan response data at the same time.
Table 2.159. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x07
method
4
uint8
scan_rsp
This value selects if the data is intended for advertisement packets or scan response packets. Values:
• 0: Advertisement packets
• 1: Scan response packets
5
uint8array
adv_data
Data to be set. Maximum length is 30 bytes
Message ID
Table 2.160. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x07
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_gap_set_adv_data(scan_rsp,adv_data_len, adv_data_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_le_gap_set_adv_data_rsp_t *gecko_cmd_le_gap_set_adv_data(uint8 scan_rsp, uint8array adv_data);
/* Response id */
gecko_rsp_le_gap_set_adv_data_id
/* Response structure */
struct gecko_msg_le_gap_set_adv_data_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 103
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.5 cmd_le_gap_set_adv_parameters
This command can be used to set Bluetooth LE advertisement parameters.
Table 2.161. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x05
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x04
method
4-5
uint16
interval_min
Minimum connection interval. Value in units of 0.625 ms
• Range: 0x0020 to 0x4000 (connectable advertising)
• Time range: 20 ms to 10.24 s (connectable advertising)
• Range: 0x00a0 to 0x4000 (non-connectable advertising)
• Time range: 100 ms to 10.24 s (non-connectable advertising)
6-7
uint16
interval_max
Maximum connection interval. Value in units of 0.625 ms
• Range: 0x0020 to 0x4000
• Time range: 20 ms to 10.24 s
• Note: interval_max must be at least equal to or bigger than interval_min
8
uint8
channel_map
Advertisement channel map which determines which of the three
channels will be used for advertising. This value is given as a bitmask. Values:
• 1: Advertise on CH37
• 2: Advertise on CH38
• 3: Advertise on CH37 and CH38
• 4: Advertise on CH39
• 5: Advertise on CH37 and CH39
• 6: Advertise on CH38 and CH39
• 7: Advertise on all channels
• Recommended value: 7
Message ID
Table 2.162. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x04
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_gap_set_adv_parameters(interval_min,interval_max,channel_map)(result)
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 104
Bluetooth Smart Software API Reference Manual
API Reference
BGLIB C API
/* Function */
struct gecko_msg_le_gap_set_adv_parameters_rsp_t *gecko_cmd_le_gap_set_adv_parameters(uint16 interval_min, uint
16 interval_max, uint8 channel_map);
/* Response id */
gecko_rsp_le_gap_set_adv_parameters_id
/* Response structure */
struct gecko_msg_le_gap_set_adv_parameters_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 105
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.6 cmd_le_gap_set_conn_parameters
This command can be used to set the default Bluetooth LE connection parameters. The configured values are valid for all subsequent
connections that will be established. For changing the parameters of an already established connection use the command le_connection_set_parameters.
Table 2.163. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x08
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x05
method
4-5
uint16
min_interval
Minimum value for the connection event interval. This must be set
be less than or equal to max_interval.
• Time = Value x 1.25 ms
• Range: 0x0006 to 0x0c80
• Time Range: 7.5 ms to 4 s
6-7
uint16
max_interval
Maximum value for the connection event interval. This must be
set greater than or equal to min_interval.
• Time = Value x 1.25 ms
• Range: 0x0006 to 0x0c80
• Time Range: 7.5 ms to 4 s
8-9
uint16
latency
Slave latency. This parameter defines how many connection intervals the slave can skip if it has no data to send
• Range: 0x0000 to 0x01f4
Use 0x0000 for default value
10-11
uint16
timeout
Supervision timeout. The supervision timeout defines for how long
the connection is maintained despite the devices being unable to
communicate at the currently configured connection intervals.
• Range: 0x000a to 0x0c80
• Time = Value x 10 ms
• Time Range: 100 ms to 32 s
• The minimum value must be at least maximum interval * (latency + 1)
It is recommended that the supervision timeout is set at a value
which allows communication attempts over at least a few connection intervals.
Message ID
Table 2.164. Response
Byte
Type
Name
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x05
method
4-5
uint16
result
silabs.com | Smart. Connected. Energy-friendly.
Description
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
Rev. 1.3 | 106
Bluetooth Smart Software API Reference Manual
API Reference
BGScript command
call le_gap_set_conn_parameters(min_interval,max_interval,latency,timeout)(result)
BGLIB C API
/* Function */
struct gecko_msg_le_gap_set_conn_parameters_rsp_t *gecko_cmd_le_gap_set_conn_parameters(uint16 min_interval, ui
nt16 max_interval, uint16 latency, uint16 timeout);
/* Response id */
gecko_rsp_le_gap_set_conn_parameters_id
/* Response structure */
struct gecko_msg_le_gap_set_conn_parameters_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 107
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.7 cmd_le_gap_set_mode
This command can be used to configure the current Bluetooth LE GAP Connectable and Discoverable modes. It can be used to enable
advertisements and/or allow incoming connections. To exit from this mode (to stop advertising and/or disallow incoming connections),
issue this command with the Not Discoverable / Not Connectable parameter values.
Table 2.165. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x01
method
Message ID
4
uint8
discover
Discoverable mode
5
uint8
connect
Connectable mode
Table 2.166. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x01
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_gap_set_mode(discover,connect)(result)
BGLIB C API
/* Function */
struct gecko_msg_le_gap_set_mode_rsp_t *gecko_cmd_le_gap_set_mode(uint8 discover, uint8 connect);
/* Response id */
gecko_rsp_le_gap_set_mode_id
/* Response structure */
struct gecko_msg_le_gap_set_mode_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 108
Bluetooth Smart Software API Reference Manual
API Reference
2.8.1.8 cmd_le_gap_set_scan_parameters
This command can be used to set Bluetooth LE scan parameters.
Table 2.167. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x05
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x06
method
4-5
uint16
scan_interval
Scanner interval. This is defined as the time interval from when
the device started its last LE scan until it begins the subsequent
LE scan, that is how often to scan
• Time = Value x 0.625 ms
• Range: 0x0004 to 0x4000
• Time Range: 2.5 ms to 10.24 s
• Default: 0x0010 (10 ms)
6-7
uint16
scan_window
Scan window. The duration of the LE scan. scan_window shall be
less than or equal to scan_interval
• Time = Value x 0.625 ms
• Range: 0x0004 to 0x4000
• Time Range: 2.5 ms to 10.24 s
• Default: 0x0010 (10 ms)
8
uint8
active
Scan type indicated by a flag. Values:
• 0: Passive scanning
• 1: Active scanning
• Default value: 0
• In passive scanning mode the device only listens to advertising
packets and will not transmit any packet
• In active scanning mode the device will send out a scan request packet upon receiving advertising packet from a remote
device and then it will listen to the scan response packet from
remote device
Message ID
Table 2.168. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x06
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call le_gap_set_scan_parameters(scan_interval,scan_window,active)(result)
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 109
Bluetooth Smart Software API Reference Manual
API Reference
BGLIB C API
/* Function */
struct gecko_msg_le_gap_set_scan_parameters_rsp_t *gecko_cmd_le_gap_set_scan_parameters(uint16 scan_interval, u
int16 scan_window, uint8 active);
/* Response id */
gecko_rsp_le_gap_set_scan_parameters_id
/* Response structure */
struct gecko_msg_le_gap_set_scan_parameters_rsp_t
{
uint16 result
}
2.8.2 le_gap events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 110
Bluetooth Smart Software API Reference Manual
API Reference
2.8.2.1 evt_le_gap_scan_response
This event reports any advertisement or scan response packet that is received by the device's radio while in scanning mode.
Table 2.169. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x0b
lolen
Minimum payload length
2
0x03
class
Message class: Generic Access Profile, Low Energy
3
0x00
method
4
int8
rssi
5
uint8
packet_type
6-11
bd_addr
address
12
uint8
address_type
13
uint8
bonding
14
uint8array
data
Message ID
Received signal strength indicator (RSSI)
• Range: -127 to +20
• Units: dBm
Advertisement packet type
• 0x00: Connectable undirected advertising
• 0x02: Scannable undirected advertising
• 0x03: Non connectable undirected advertising
• 0x04: Scan Response
Note: Scan response (0x04) is only received if the device is in active scan mode.
Bluetooth address of the remote device
Advertiser address type. Values:
• 0: Public address
• 1: Random address
Bonding handle if the remote advertising device has previously
bonded with the local device. Values:
• 0xff: No bonding
• Other: Bonding handle
Advertisement or scan response data
BGScript event
event le_gap_scan_response(rssi,packet_type,address,address_type,bonding,data_len, data_data)
C Functions
/* Event id */
gecko_evt_le_gap_scan_response_id
/* Event structure */
struct gecko_msg_le_gap_scan_response_evt_t
{
int8 rssi,
uint8 packet_type,
bd_addr address,
uint8 address_type,
uint8 bonding,
uint8array data
}
2.8.3 le_gap enumerations
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 111
Bluetooth Smart Software API Reference Manual
API Reference
2.8.3.1 enum_le_gap_address_type
These values define the Bluetooth Address types used by the stack.
Table 2.170. Enumerations
Value
Name
Description
0
le_gap_address_type_public
LE public address
1
le_gap_address_type_random
LE random address
2
le_gap_address_type_public_identity
LE public identity address resolved by stack
3
le_gap_address_type_random_identity
LE random identity address resolved by stack
16
le_gap_address_type_bredr
Classic Bluetooth address
2.8.3.2 enum_le_gap_connectable_mode
These values define the available Connectable Modes.
Table 2.171. Enumerations
Value
Name
Description
0
le_gap_non_connectable
Not connectable
1
le_gap_directed_connectable
Directed Connectable (RESERVED, DO NOT USE)
2
le_gap_undirected_connectable
Undirected connectable
3
le_gap_scannable_non_connectable
Not connectable but responds to scan_req-packets
2.8.3.3 enum_le_gap_discoverable_mode
These values define the available Discoverable Modes, which dictate how the device is visible to other devices.
Table 2.172. Enumerations
Value
Name
Description
0
le_gap_non_discoverable
Not discoverable
1
le_gap_limited_discoverable
Discoverable using both limited discoverable mode
2
le_gap_general_discoverable
Discoverable using general discoverable mode
3
le_gap_broadcast
Device is not discoverable in either limited or generic
discoverable procedure, but may be discovered by using
the Observation procedure
4
le_gap_user_data
Send advertisement and/or scan response data defined
by the user using le_gap_set_adv_data command. The
limited/general discoverable flags are defined by the
user.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 112
Bluetooth Smart Software API Reference Manual
API Reference
2.8.3.4 enum_le_gap_discover_mode
These values indicate which Bluetooth LE discover mode to use when scanning for advertising slaves.
Table 2.173. Enumerations
Value
Name
Description
0
le_gap_discover_limited
Discover only limited discoverable devices
1
le_gap_discover_generic
Discover limited and generic discoverable devices
2
le_gap_discover_observation
Discover all devices
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 113
Bluetooth Smart Software API Reference Manual
API Reference
2.9 Security Manager (sm)
The commands in this section are used to manage Bluetooth security, including commands for starting and stopping encryption and
commands for management of all bonding operations.
The following procedure can be used to bond with a remote device:
• Use command sm_configure to configure the authentication method and I/O capabilities of this device.
• Use command sm_set_bondable_mode to set this device into bondable mode.
• Use command le_gap_open to open a connection to the remote device.
• After the connection is open, use command sm_increase_security to encrypt the connection. This will also start the bonding process.
If MITM is required, the application needs to display or ask user to enter a passkey during the process. See events sm_passkey_display and sm_passkey_request for more information. The following procedure can be used to respond the bonding initiated by a remote
device:
• Use command sm_configure to configure the authentication method and I/O capabilities of this device.
• Use command sm_set_bondable_mode to set this device into bondable mode.
• Use le_gap_set_mode to set this device into advertising and connectable mode.
• Open a connection to this device from the remote device.
• After the connection is open, start the bonding process on the remote device.
If MITM is required, the application needs to display or ask user to enter a passkey during the process. See events sm_passkey_display and sm_passkey_request for more information.
2.9.1 sm commands
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 114
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.1 cmd_sm_configure
This command can be used to configure authentication methods and I/O capabilities of the system.
Table 2.174. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x01
method
4
uint8
mitm_required
Require MITM flag. Values:
• 0: Allow bonding without MITM protection
• 1: Require MITM protection
5
uint8
io_capabilities
I/O Capabilities. See link
Message ID
Table 2.175. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x00
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x01
method
Message ID
BGScript command
call sm_configure(mitm_required,io_capabilities)()
BGLIB C API
/* Function */
struct gecko_msg_sm_configure_rsp_t *gecko_cmd_sm_configure(uint8 mitm_required, uint8 io_capabilities);
/* Response id */
gecko_rsp_sm_configure_id
/* Response structure */
struct gecko_msg_sm_configure_rsp_t
{
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 115
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.2 cmd_sm_delete_bonding
This command can be used to delete specified bonding information from Persistent Store.
Table 2.176. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x06
method
Message ID
4
uint8
bonding
Bonding handle
Table 2.177. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x06
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_delete_bonding(bonding)(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_delete_bonding_rsp_t *gecko_cmd_sm_delete_bonding(uint8 bonding);
/* Response id */
gecko_rsp_sm_delete_bonding_id
/* Response structure */
struct gecko_msg_sm_delete_bonding_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 116
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.3 cmd_sm_delete_bondings
This command can be used to delete all bonding information from Persistent Store.
Table 2.178. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x00
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x07
method
Message ID
Table 2.179. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x07
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_delete_bondings()(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_delete_bondings_rsp_t *gecko_cmd_sm_delete_bondings();
/* Response id */
gecko_rsp_sm_delete_bondings_id
/* Response structure */
struct gecko_msg_sm_delete_bondings_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 117
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.4 cmd_sm_enter_passkey
This command can be used to enter a passkey after receiving a passkey request event.
Table 2.180. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x05
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x08
method
4
uint8
connection
5-8
uint32
passkey
Message ID
Connection handle
Passkey. Valid range: 0-999999
Table 2.181. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x08
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_enter_passkey(connection,passkey)(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_enter_passkey_rsp_t *gecko_cmd_sm_enter_passkey(uint8 connection, uint32 passkey);
/* Response id */
gecko_rsp_sm_enter_passkey_id
/* Response structure */
struct gecko_msg_sm_enter_passkey_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 118
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.5 cmd_sm_increase_security
This command can be used to enhance the security of a connection to current security requirements. More specifically, the Start Encryption procedure will be performed on a connection if it is currently unencrypted. The connection becomes encrypted if the procedure
was completed sucessfully. Calling this command on an encrypted connection will result in performing the Restart Encryption procedure.
Table 2.182. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x04
method
4
uint8
connection
Message ID
Connection handle
Table 2.183. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x04
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_increase_security(connection)(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_increase_security_rsp_t *gecko_cmd_sm_increase_security(uint8 connection);
/* Response id */
gecko_rsp_sm_increase_security_id
/* Response structure */
struct gecko_msg_sm_increase_security_rsp_t
{
uint16 result
}
Table 2.184. Events Generated
Event
Description
le_connection_parameters
This event is triggered after increasing security has been completed successfully, and indicates the latest security mode of the connection.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 119
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.6 cmd_sm_list_all_bondings
This command can be used to list all bondings stored in the bonding database. Bondings are reported by using the sm_list_bonding_entry event for each bonding and the report is ended with sm_list_all_bondings_complete event. Recommended to be used only for
debugging purposes, because reading from the Persistent Store is relatively slow.
Table 2.185. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x00
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x0b
method
Message ID
Table 2.186. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x0b
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_list_all_bondings()(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_list_all_bondings_rsp_t *gecko_cmd_sm_list_all_bondings();
/* Response id */
gecko_rsp_sm_list_all_bondings_id
/* Response structure */
struct gecko_msg_sm_list_all_bondings_rsp_t
{
uint16 result
}
Table 2.187. Events Generated
Event
Description
sm_list_bonding_entry
This event is triggered by the command sm_list_all_bondings if bondings exist in the local database.
sm_list_all_bondings_complete
This event is triggered by the sm_list_all_bondings and follows sm_list_bonding_entry
events.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 120
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.7 cmd_sm_passkey_confirm
This command can be used for accepting or rejecting reported confirm value.
Table 2.188. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x09
method
4
uint8
connection
5
uint8
confirm
Message ID
Connection handle
Accept confirm value. Values:
• 0: Reject
• 1: Accept confirm value
Table 2.189. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x09
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_passkey_confirm(connection,confirm)(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_passkey_confirm_rsp_t *gecko_cmd_sm_passkey_confirm(uint8 connection, uint8 confirm);
/* Response id */
gecko_rsp_sm_passkey_confirm_id
/* Response structure */
struct gecko_msg_sm_passkey_confirm_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 121
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.8 cmd_sm_set_bondable_mode
This command can be used to set whether the device accepts new bondings or not.
Table 2.190. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x00
method
4
uint8
bondable
Message ID
Bondable mode. Values:
• 0: New bondings not accepted
• 1: Bondings allowed
Table 2.191. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x00
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_set_bondable_mode(bondable)(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_set_bondable_mode_rsp_t *gecko_cmd_sm_set_bondable_mode(uint8 bondable);
/* Response id */
gecko_rsp_sm_set_bondable_mode_id
/* Response structure */
struct gecko_msg_sm_set_bondable_mode_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 122
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.9 cmd_sm_set_oob_data
This command can be used to set the OOB data (out-of-band encryption data) for a device. The OOB data may be, for example, a PIN
code exchanged over an alternate path like NFC. The device will not allow any other kind of bonding if OOB data is set.
Table 2.192. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x0a
method
4
uint8array
oob_data
Message ID
OOB data. To set OOB data, send a 16-byte array. To clear OOB
data, send a zero-length array.
Table 2.193. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x0a
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_set_oob_data(oob_data_len, oob_data_data)(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_set_oob_data_rsp_t *gecko_cmd_sm_set_oob_data(uint8array oob_data);
/* Response id */
gecko_rsp_sm_set_oob_data_id
/* Response structure */
struct gecko_msg_sm_set_oob_data_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 123
Bluetooth Smart Software API Reference Manual
API Reference
2.9.1.10 cmd_sm_store_bonding_configuration
This command can be used to set maximum allowed bonding count and bonding policy.
Table 2.194. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x02
method
4
uint8
5
uint8
Message ID
max_bonding_count Maximum allowed bonding count. Range: 1 to 32
policy_flags
Bonding policy. Values:
• 0: If database is full, new bonding attempts will fail
• 1: New bonding will overwrite the oldest existing bonding
Table 2.195. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x02
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call sm_store_bonding_configuration(max_bonding_count,policy_flags)(result)
BGLIB C API
/* Function */
struct gecko_msg_sm_store_bonding_configuration_rsp_t *gecko_cmd_sm_store_bonding_configuration(uint8 max_bondi
ng_count, uint8 policy_flags);
/* Response id */
gecko_rsp_sm_store_bonding_configuration_id
/* Response structure */
struct gecko_msg_sm_store_bonding_configuration_rsp_t
{
uint16 result
}
2.9.2 sm events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 124
Bluetooth Smart Software API Reference Manual
API Reference
2.9.2.1 evt_sm_bonded
This event is triggered after the pairing or bonding procedure has been successfully completed.
Table 2.196. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x02
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x03
method
4
uint8
connection
5
uint8
bonding
Message ID
Connection handle
Bonding handle. Values:
• 0xff: Pairing completed without bonding - the pairing key will
be discarded after disconnection.
• Other: Procedure completed, pairing key stored with given
bonding handle
BGScript event
event sm_bonded(connection,bonding)
C Functions
/* Event id */
gecko_evt_sm_bonded_id
/* Event structure */
struct gecko_msg_sm_bonded_evt_t
{
uint8 connection,
uint8 bonding
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 125
Bluetooth Smart Software API Reference Manual
API Reference
2.9.2.2 evt_sm_bonding_failed
This event is triggered if the pairing or bonding procedure has failed.
Table 2.197. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x03
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x04
method
4
uint8
connection
5-6
uint16
reason
Message ID
Connection handle
Describes error that occurred
BGScript event
event sm_bonding_failed(connection,reason)
C Functions
/* Event id */
gecko_evt_sm_bonding_failed_id
/* Event structure */
struct gecko_msg_sm_bonding_failed_evt_t
{
uint8 connection,
uint16 reason
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 126
Bluetooth Smart Software API Reference Manual
API Reference
2.9.2.3 evt_sm_confirm_passkey
This event indicates a request to display the passkey to the user and for the user to confirm the displayed passkey. Use the command
sm_passkey_confirm to accept or reject the displayed passkey.
Table 2.198. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x05
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x02
method
4
uint8
connection
5-8
uint32
passkey
Message ID
Connection handle
Passkey. Range: 0 to 999999.
• NOTE! When displaying the passkey to the user, prefix the
number with zeros in order to obtain a 6 digit number
• Example: Passkey value is 42
• Number to display to user is 000042
BGScript event
event sm_confirm_passkey(connection,passkey)
C Functions
/* Event id */
gecko_evt_sm_confirm_passkey_id
/* Event structure */
struct gecko_msg_sm_confirm_passkey_evt_t
{
uint8 connection,
uint32 passkey
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 127
Bluetooth Smart Software API Reference Manual
API Reference
2.9.2.4 evt_sm_list_all_bondings_complete
This event is triggered by the sm_list_all_bondings and follows sm_list_bonding_entry events.
Table 2.199. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x00
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x06
method
Message ID
BGScript event
event sm_list_all_bondings_complete()
C Functions
/* Event id */
gecko_evt_sm_list_all_bondings_complete_id
/* Event structure */
struct gecko_msg_sm_list_all_bondings_complete_evt_t
{
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 128
Bluetooth Smart Software API Reference Manual
API Reference
2.9.2.5 evt_sm_list_bonding_entry
This event is triggered by the command sm_list_all_bondings if bondings exist in the local database.
Table 2.200. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x08
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x05
method
Message ID
4
uint8
bonding
Bonding index of bonding data
5-10
bd_addr
address
Bluetooth address of the remote device
11
uint8
address_type
Address type
BGScript event
event sm_list_bonding_entry(bonding,address,address_type)
C Functions
/* Event id */
gecko_evt_sm_list_bonding_entry_id
/* Event structure */
struct gecko_msg_sm_list_bonding_entry_evt_t
{
uint8 bonding,
bd_addr address,
uint8 address_type
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 129
Bluetooth Smart Software API Reference Manual
API Reference
2.9.2.6 evt_sm_passkey_display
This event indicates a request to display the passkey to the user.
Table 2.201. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x05
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x00
method
4
uint8
connection
5-8
uint32
passkey
Message ID
Connection handle
Passkey. Range: 0 to 999999.
• NOTE! When displaying the passkey to the user, prefix the
number with zeros in order to obtain a 6 digit number
• Example: Passkey value is 42
• Number to display to user is 000042
BGScript event
event sm_passkey_display(connection,passkey)
C Functions
/* Event id */
gecko_evt_sm_passkey_display_id
/* Event structure */
struct gecko_msg_sm_passkey_display_evt_t
{
uint8 connection,
uint32 passkey
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 130
Bluetooth Smart Software API Reference Manual
API Reference
2.9.2.7 evt_sm_passkey_request
This event indicates a request for the user to enter the passkey displayed on the remote device. Use the command sm_enter_passkey
to input the passkey value.
Table 2.202. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x01
lolen
Minimum payload length
2
0x0f
class
Message class: Security Manager
3
0x01
method
4
uint8
connection
Message ID
Connection handle
BGScript event
event sm_passkey_request(connection)
C Functions
/* Event id */
gecko_evt_sm_passkey_request_id
/* Event structure */
struct gecko_msg_sm_passkey_request_evt_t
{
uint8 connection
}
2.9.3 sm enumerations
2.9.3.1 enum_sm_bonding_key
These values define the bonding information of the bonded device stored in persistent store.
Table 2.203. Enumerations
Value
Name
Description
1
sm_bonding_key_ltk
LTK saved in master
2
sm_bonding_key_addr_public
Public Address
4
sm_bonding_key_addr_static
Static Address
8
sm_bonding_key_irk
Identity resolving key for resolvable private addresses
16
sm_bonding_key_edivrand
EDIV+RAND received from slave
32
sm_bonding_key_csrk
Connection signature resolving key
64
sm_bonding_key_masterid
EDIV+RAND sent to master
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 131
Bluetooth Smart Software API Reference Manual
API Reference
2.9.3.2 enum_sm_io_capability
These values define the security management related I/O capabilities supported by the device
Table 2.204. Enumerations
Value
Name
Description
0
sm_io_capability_displayonly
Display Only
1
sm_io_capability_displayyesno
Display with Yes/No-buttons
2
sm_io_capability_keyboardonly
Keyboard Only
3
sm_io_capability_noinputnooutput
No Input and No Output
4
sm_io_capability_keyboarddisplay
Display with Keyboard
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 132
Bluetooth Smart Software API Reference Manual
API Reference
2.10 System (system)
The commands and events in this class can be used to access and query the local device.
2.10.1 system commands
2.10.1.1 cmd_system_get_bt_address
This command can be used to read the LE public address used by the device.
Table 2.205. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x00
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x03
method
Message ID
Table 2.206. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x06
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x03
method
Message ID
4-9
bd_addr
address
LE public address in little endian format
BGScript command
call system_get_bt_address()(address)
BGLIB C API
/* Function */
struct gecko_msg_system_get_bt_address_rsp_t *gecko_cmd_system_get_bt_address();
/* Response id */
gecko_rsp_system_get_bt_address_id
/* Response structure */
struct gecko_msg_system_get_bt_address_rsp_t
{
bd_addr address
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 133
Bluetooth Smart Software API Reference Manual
API Reference
2.10.1.2 cmd_system_hello
This command does not trigger any event but the response to the command is used to verify that communication between the host and
the device is working.
Table 2.207. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x00
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x00
method
Message ID
Table 2.208. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x00
method
4-5
uint16
result
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript command
call system_hello()(result)
BGLIB C API
/* Function */
struct gecko_msg_system_hello_rsp_t *gecko_cmd_system_hello();
/* Response id */
gecko_rsp_system_hello_id
/* Response structure */
struct gecko_msg_system_hello_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 134
Bluetooth Smart Software API Reference Manual
API Reference
2.10.1.3 cmd_system_reset
This command can be used to reset the system. It does not have a response, but it triggers one of the boot events (normal reset or boot
to DFU mode) depending on the selected boot mode.
Table 2.209. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x01
method
4
uint8
dfu
Message ID
Boot mode:
• 0: Normal reset
• 1: Boot to DFU mode
BGScript command
call system_reset(dfu)
BGLIB C API
/* Function */
void *gecko_cmd_system_reset(uint8 dfu);
/* Command does not have a response */
Table 2.210. Events Generated
Event
Description
system_boot
Sent after the device has booted into normal mode
dfu_boot
Sent after the device has booted into DFU mode
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 135
Bluetooth Smart Software API Reference Manual
API Reference
2.10.1.4 cmd_system_set_tx_power
This command can be used to set the TX power. It returns the power that was set.
NOTE: This command should not be used while advertising, scanning or during connection.
Table 2.211. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x02
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x0a
method
4-5
int16
power
Message ID
TX power in 0.1dBm steps, for example the value of 10 is 1dBm
and 55 is 5.5dBm
Table 2.212. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x0a
method
4-5
int16
set_power
Message ID
Returns the power value currently in use after setting
BGScript command
call system_set_tx_power(power)(set_power)
BGLIB C API
/* Function */
struct gecko_msg_system_set_tx_power_rsp_t *gecko_cmd_system_set_tx_power(int16 power);
/* Response id */
gecko_rsp_system_set_tx_power_id
/* Response structure */
struct gecko_msg_system_set_tx_power_rsp_t
{
int16 set_power
}
2.10.2 system events
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 136
Bluetooth Smart Software API Reference Manual
API Reference
2.10.2.1 evt_system_awake
This event indicates that the device has woken up from sleep mode. This event is triggered after the wakeup pin is activated.
Table 2.213. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x00
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x04
method
Message ID
BGScript event
event system_awake()
C Functions
/* Event id */
gecko_evt_system_awake_id
/* Event structure */
struct gecko_msg_system_awake_evt_t
{
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 137
Bluetooth Smart Software API Reference Manual
API Reference
2.10.2.2 evt_system_boot
This event indicates the device has started and the radio is ready. This even carries the firmware build number and other SW and HW
identification codes.
Table 2.214. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x0c
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x00
method
4-5
uint16
major
Major release version
6-7
uint16
minor
Minor release version
8-9
uint16
patch
Patch release number
10-11
uint16
build
Build number
12-13
uint16
bootloader
14-15
uint16
hw
Message ID
Bootloader version
Hardware type
BGScript event
event system_boot(major,minor,patch,build,bootloader,hw)
C Functions
/* Event id */
gecko_evt_system_boot_id
/* Event structure */
struct gecko_msg_system_boot_evt_t
{
uint16 major,
uint16 minor,
uint16 patch,
uint16 build,
uint16 bootloader,
uint16 hw
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 138
Bluetooth Smart Software API Reference Manual
API Reference
2.10.2.3 evt_system_external_signal
This event indicates external signals have been received. External signals are generated from native application.
Table 2.215. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x04
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x03
method
4-7
uint32
extsignals
Message ID
Bitmask of external signals received since last event.
BGScript event
event system_external_signal(extsignals)
C Functions
/* Event id */
gecko_evt_system_external_signal_id
/* Event structure */
struct gecko_msg_system_external_signal_evt_t
{
uint32 extsignals
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 139
Bluetooth Smart Software API Reference Manual
API Reference
2.10.2.4 evt_system_hardware_error
This event indicates that hardware related errors occurred.
Table 2.216. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x02
lolen
Minimum payload length
2
0x01
class
Message class: System
3
0x05
method
4-5
uint16
status
Message ID
Result code
• 0: success
• Non-zero: an error occurred
For other values refer to the Error codes
BGScript event
event system_hardware_error(status)
C Functions
/* Event id */
gecko_evt_system_hardware_error_id
/* Event structure */
struct gecko_msg_system_hardware_error_evt_t
{
uint16 status
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 140
Bluetooth Smart Software API Reference Manual
API Reference
2.11 testing commands (test)
2.11.1 test commands
2.11.1.1 cmd_test_dtm_end
This command can be used to end a transmitter or a receiver test. When the command is processed by the radio and the test has
ended, a test_dtm_completed event is triggered.
Table 2.217. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x00
lolen
Minimum payload length
2
0x0e
class
Message class: testing commands
3
0x02
method
Message ID
Table 2.218. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0e
class
Message class: testing commands
3
0x02
method
4-5
uint16
result
Message ID
Command result
BGScript command
call test_dtm_end()(result)
BGLIB C API
/* Function */
struct gecko_msg_test_dtm_end_rsp_t *gecko_cmd_test_dtm_end();
/* Response id */
gecko_rsp_test_dtm_end_id
/* Response structure */
struct gecko_msg_test_dtm_end_rsp_t
{
uint16 result
}
Table 2.219. Events Generated
Event
Description
test_dtm_completed
This event is received when the command is processed.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 141
Bluetooth Smart Software API Reference Manual
API Reference
2.11.1.2 cmd_test_dtm_rx
This command can be used to start a receiver test. The test is meant to be used against a separate Bluetooth tester device. When the
command is processed by the radio, a test_dtm_completed event is triggered. This event indicates if the test started successfully.
The test may be stopped using the test_dtm_end command. This will trigger another test_dtm_completed event, which carries the number of packets received during the test.
Table 2.220. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x0e
class
Message class: testing commands
3
0x01
method
Message ID
4
uint8
channel
Bluetooth channel
Range: 0-39
Channel is (F - 2402) / 2,
where F is frequency in MHz
Table 2.221. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0e
class
Message class: testing commands
3
0x01
method
4-5
uint16
result
Message ID
Command result
BGScript command
call test_dtm_rx(channel)(result)
BGLIB C API
/* Function */
struct gecko_msg_test_dtm_rx_rsp_t *gecko_cmd_test_dtm_rx(uint8 channel);
/* Response id */
gecko_rsp_test_dtm_rx_id
/* Response structure */
struct gecko_msg_test_dtm_rx_rsp_t
{
uint16 result
}
Table 2.222. Events Generated
Event
Description
test_dtm_completed
This event is received when the command is processed.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 142
Bluetooth Smart Software API Reference Manual
API Reference
2.11.1.3 cmd_test_dtm_tx
This command can be used to start a transmitter test. The test is meant to be used against a separate Bluetooth tester device. When
the command is processed by the radio, a test_dtm_completed event is triggered. This event indicates if the test started successfully.
In the transmitter test, the device sends packets continuously with a fixed interval. The type and length of each packet is set by packet_type and length parameters. There is also a special packet type, test_pkt_carrier, which can be used to transmit continuous unmodulated carrier. The length field is ignored in this mode.
The test may be stopped using the test_dtm_end command.
Table 2.223. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x03
lolen
Minimum payload length
2
0x0e
class
Message class: testing commands
3
0x00
method
4
uint8
packet_type
Packet type to transmit
5
uint8
length
Packet length in bytes
Message ID
Range: 0-37
6
uint8
channel
Bluetooth channel
Range: 0-39
Channel is (F - 2402) / 2,
where F is frequency in MHz
Table 2.224. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x02
lolen
Minimum payload length
2
0x0e
class
Message class: testing commands
3
0x00
method
4-5
uint16
result
Message ID
Command result
BGScript command
call test_dtm_tx(packet_type,length,channel)(result)
BGLIB C API
/* Function */
struct gecko_msg_test_dtm_tx_rsp_t *gecko_cmd_test_dtm_tx(uint8 packet_type, uint8 length, uint8 channel);
/* Response id */
gecko_rsp_test_dtm_tx_id
/* Response structure */
struct gecko_msg_test_dtm_tx_rsp_t
{
uint16 result
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 143
Bluetooth Smart Software API Reference Manual
API Reference
Table 2.225. Events Generated
Event
Description
test_dtm_completed
This event is received when the command is processed.
2.11.2 test events
2.11.2.1 evt_test_dtm_completed
This event indicates that the radio has processed a test start or end command. The result parameter indicates the success of the command.
After the receiver test is stopped, the number_of_packets parameter in this event indicates the number of received packets.
Table 2.226. Event
Byte
Type
Name
Description
0
0xa0
hilen
Message type: Event
1
0x04
lolen
Minimum payload length
2
0x0e
class
Message class: testing commands
3
0x00
method
4-5
uint16
result
6-7
uint16
Message ID
Command result
number_of_packets Number of received packets
Only valid for test_dtm_end command.
BGScript event
event test_dtm_completed(result,number_of_packets)
C Functions
/* Event id */
gecko_evt_test_dtm_completed_id
/* Event structure */
struct gecko_msg_test_dtm_completed_evt_t
{
uint16 result,
uint16 number_of_packets
}
2.11.3 test enumerations
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 144
Bluetooth Smart Software API Reference Manual
API Reference
2.11.3.1 enum_test_packet_type
Test packet types
Table 2.227. Enumerations
Value
Name
Description
0
test_pkt_prbs9
PRBS9 packet payload
1
test_pkt_11110000
11110000 packet payload
2
test_pkt_10101010
10101010 packet payload
3
test_pkt_carrier
Unmodulated carrier
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 145
Bluetooth Smart Software API Reference Manual
API Reference
2.12 Utilities for BGScript (util)
The commands and events in this class can be used to simplify BGScript based application development and are typically not used in
any other applications.
2.12.1 util commands
2.12.1.1 cmd_util_atoi
Converts decimal value in ASCII string to 32-bit signed integer.
Table 2.228. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x01
lolen
Minimum payload length
2
0x11
class
Message class: Utilities for BGScript
3
0x00
method
4
uint8array
string
Message ID
String to convert
Table 2.229. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x04
lolen
Minimum payload length
2
0x11
class
Message class: Utilities for BGScript
3
0x00
method
4-7
int32
value
Message ID
Conversion result presenting the decimal value input as a string
as a 32-bit signed integer value
BGScript command
call util_atoi(string_len, string_data)(value)
BGLIB C API
/* Function */
struct gecko_msg_util_atoi_rsp_t *gecko_cmd_util_atoi(uint8array string);
/* Response id */
gecko_rsp_util_atoi_id
/* Response structure */
struct gecko_msg_util_atoi_rsp_t
{
int32 value
}
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 146
Bluetooth Smart Software API Reference Manual
API Reference
2.12.1.2 cmd_util_itoa
This command can be used to convert a 32-bit signed integer value into a decimal value represented as a string.
Table 2.230. Command
Byte
Type
Name
Description
0
0x20
hilen
Message type: Command
1
0x04
lolen
Minimum payload length
2
0x11
class
Message class: Utilities for BGScript
3
0x01
method
4-7
int32
value
Message ID
32-bit number to convert
Table 2.231. Response
Byte
Type
Name
Description
0
0x20
hilen
Message type: Response
1
0x01
lolen
Minimum payload length
2
0x11
class
Message class: Utilities for BGScript
3
0x01
method
4
uint8array
string
Message ID
Conversion result presenting the 32-bit signed integer value input
as a decimal value presented by a string
BGScript command
call util_itoa(value)(string_len, string_data)
BGLIB C API
/* Function */
struct gecko_msg_util_itoa_rsp_t *gecko_cmd_util_itoa(int32 value);
/* Response id */
gecko_rsp_util_itoa_id
/* Response structure */
struct gecko_msg_util_itoa_rsp_t
{
uint8array string
}
2.13 Error codes
This chapter describes all BGAPI error codes.
■
Errors related to hardware
Code
Name
Description
0x0501
ps_store_full
Flash reserved for PS store is full
0x0502
ps_key_not_found
PS key not found
0x0503
i2c_ack_missing
Acknowledge for i2c was not received.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 147
Bluetooth Smart Software API Reference Manual
API Reference
Code
Name
Description
0x0504
i2c_timeout
I2C read or write timed out.
0x0505
not_configured
Hardware is not configured for that function.
0x0506
ble_not_supported
Hardware does not support Blootooth Smart.
■
Errors related to BGAPI protocol
Code
Name
Description
0x0101
invalid_conn_handle
Invalid GATT connection handle.
0x0102
waiting_response
Waiting response from GATT server to previous procedure.
0x0103
gatt_connection_timeout
GATT connection is closed due procedure timeout.
0x0180
invalid_param
Command contained invalid parameter
0x0181
wrong_state
Device is in wrong state to receive command
0x0182
out_of_memory
Device has run out of memory
0x0183
not_implemented
Feature is not implemented
0x0184
invalid_command
Command was not recognized
0x0185
timeout
Command or Procedure failed due to timeout
0x0186
not_connected
Connection handle passed is to command is not a valid
handle
0x0187
flow
Command would cause either underflow or overflow error
0x0188
user_attribute
User attribute was accessed through API which is not
supported
0x0189
invalid_license_key
No valid license key found
0x018a
command_too_long
Command maximum length exceeded
0x018b
out_of_bonds
Bonding procedure can't be started because device has
no space left for bond.
0x018c
unspecified
Unspecified error
0x018d
hardware
Hardware failure
0x018e
buffers_full
Command not accepted, because internal buffers are
full
0x018f
disconnected
Command or Procedure failed due to disconnection
0x0190
too_many_requests
Too many Simultaneous Requests
0x0191
not_supported
Feature is not supported in this firmware build
Code
Name
Description
0x0601
record_not_found
Service Record not found
0x0602
record_already_exist
Service Record with this handle already exist.
■
SDP errors
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 148
Bluetooth Smart Software API Reference Manual
API Reference
■
Errors from Security Manager Protocol
Code
Name
Description
0x0301
passkey_entry_failed
The user input of passkey failed, for example, the user
cancelled the operation
0x0302
oob_not_available
Out of Band data is not available for authentication
0x0303
authentication_requirements
The pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities
of one or both devices
0x0304
confirm_value_failed
The confirm value does not match the calculated compare value
0x0305
pairing_not_supported
Pairing is not supported by the device
0x0306
encryption_key_size
The resultant encryption key size is insufficient for the
security requirements of this device
0x0307
command_not_supported
The SMP command received is not supported on this
device
0x0308
unspecified_reason
Pairing failed due to an unspecified reason
0x0309
repeated_attempts
Pairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request
0x030a
invalid_parameters
The Invalid Parameters error code indicates: the command length is invalid or a parameter is outside of the
specified range.
0x030b
no_bonding
The bonding does not exist.
■
Bluetooth errors
Code
Name
Description
0x0202
unknown_connection_identifier
A command was sent from the Host that should identify
a connection, but that connection does not exist.
0x0204
page_timeout
The Page Timeout error code indicates that a page
timed out because of the Page Timeout configuration
parameter.
0x0205
authentication_failure
Pairing or authentication failed due to incorrect results in
the pairing or authentication procedure. This could be
due to an incorrect PIN or Link Key
0x0206
pin_or_key_missing
Pairing failed because of missing PIN, or authentication
failed because of missing Key
0x0207
memory_capacity_exceeded
Controller is out of memory.
0x0208
connection_timeout
Link supervision timeout has expired.
0x0209
connection_limit_exceeded
Controller is at limit of connections it can support.
0x020a
synchronous_connectiontion_limit_exceeded
The Synchronous Connection Limit to a Device Exceeded error code indicates that the Controller has reached
the limit to the number of synchronous connections that
can be achieved to a device.
0x020b
acl_connection_already_exists
The ACL Connection Already Exists error code indicates
that an attempt to create a new ACL Connection to a device when there is already a connection to this device.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 149
Bluetooth Smart Software API Reference Manual
API Reference
Code
Name
Description
0x020c
command_disallowed
Command requested cannot be executed because the
Controller is in a state where it cannot process this command at this time.
0x020d
connection_rejected_due_to_limited_resources
The Connection Rejected Due To Limited Resources error code indicates that an incoming connection was rejected due to limited resources.
0x020e
connection_rejected_due_to_security_reasons
The Connection Rejected Due To Security Reasons error code indicates that a connection was rejected due to
security requirements not being fulfilled, like authentication or pairing.
0x020f
connection_rejected_due_to_unacceptable_bd_addr
The Connection was rejected because this device does
not accept the BD_ADDR. This may be because the device will only accept connections from specific
BD_ADDRs.
0x0210
connection_accept_timeout_exceeded
The Connection Accept Timeout has been exceeded for
this connection attempt.
0x0211
unsupported_feature_or_parameter_value
A feature or parameter value in the HCI command is not
supported.
0x0212
invalid_command_parameters
Command contained invalid parameters.
0x0213
remote_user_terminated
User on the remote device terminated the connection.
0x0214
remote_device_terminated_connection_due_to_low_resources
The remote device terminated the connection because
of low resources
0x0215
remote_powering_off
Remote Device Terminated Connection due to Power
Off
0x0216
connection_terminated_by_local_host
Local device terminated the connection.
0x0217
repeated_attempts
The Controller is disallowing an authentication or pairing
procedure because too little time has elapsed since the
last authentication or pairing attempt failed.
0x0218
pairing_not_allowed
The device does not allow pairing. This can be for example, when a device only allows pairing during a certain time window after some user input allows pairing
0x0219
unknown_lmp_pdu
The Controller has received an unknown LMP OpCode.
0x021a
unsupported_remote_feature
The remote device does not support the feature associated with the issued command or LMP PDU.
0x021b
sco_offset_rejected
The offset requested in the LMP_SCO_link_req PDU
has been rejected.
0x021c
sco_interval_rejected
The interval requested in the LMP_SCO_link_req PDU
has been rejected.
0x021d
sco_air_mode_rejected
The air mode requested in the LMP_SCO_link_req PDU
has been rejected.
0x021e
invalid_lmp_parameters
Some LMP PDU / LL Control PDU parameters were invalid.
0x021f
unspecified_error
No other error code specified is appropriate to use.
0x0220
unsupported_lmp_parameter_value
An LMP PDU or an LL Control PDU contains at least
one parameter value that is not supported by the Controller at this time.
0x0221
role_change_not_allowed
Controller will not allow a role change at this time.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 150
Bluetooth Smart Software API Reference Manual
API Reference
Code
Name
Description
0x0222
ll_response_timeout
Connection terminated due to link-layer procedure timeout.
0x0223
lmp_error_transaction_collision
LMP transaction has collided with the same transaction
that is already in progress.
0x0224
lmp_pdu_not_allowed
Controller sent an LMP PDU with an OpCode that was
not allowed.
0x0225
encryption_mode_not_acceptable
The requested encryption mode is not acceptable at this
time.
0x0226
link_key_cannot_be_changed
Link key cannot be changed because a fixed unit key is
being used.
0x0227
requested_qos_not_supported
The requested Quality of Service is not supported.
0x0228
instant_passed
LMP PDU or LL PDU that includes an instant cannot be
performed because the instant when this would have occurred has passed.
0x0229
pairing_with_unit_key_not_supported
It was not possible to pair as a unit key was requested
and it is not supported.
0x022a
different_transaction_collision
LMP transaction was started that collides with an ongoing transaction.
0x022c
qos_unacceptable_parameter
The specified quality of service parameters could not be
accepted at this time, but other parameters may be acceptable.
0x022d
qos_rejected
The specified quality of service parameters cannot be
accepted and QoS negotiation should be terminated.
0x022e
channel_assesment_not_supported
The Controller cannot perform channel assessment because it is not supported.
0x022f
insufficient_security
The HCI command or LMP PDU sent is only possible on
an encrypted link.
0x0230
parameter_out_of_mandatory_range
A parameter value requested is outside the mandatory
range of parameters for the given HCI command or LMP
PDU.
0x0232
role_switch_pending
Role Switch is pending. This can be used when an HCI
command or LMP PDU cannot be accepted because of
a pending role switch. This can also be used to notify a
peer device about a pending role switch.
0x0234
reserved_slot_violation
The current Synchronous negotiation was terminated
with the negotiation state set to Reserved Slot Violation.
0x0235
role_switch_failed
role switch was attempted but it failed and the original
piconet structure is restored. The switch may have failed
because the TDD switch or piconet switch failed.
0x0236
extended_inquiry_response_too_large
The extended inquiry response, with the requested requirements for FEC, is too large to fit in any of the packet types supported by the Controller.
0x0237
simple_pairing_not_supported_by_host
The IO capabilities request or response was rejected
because the sending Host does not support Secure
Simple Pairing even though the receiving Link Manager
does.
0x0238
host_busy_pairing
The Host is busy with another pairing operation and unable to support the requested pairing. The receiving device should retry pairing again later.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 151
Bluetooth Smart Software API Reference Manual
API Reference
Code
Name
Description
0x0239
connection_rejected_due_to_no_suitable_channel_found
The Controller could not calculate an appropriate value
for the Channel selection operation.
0x023a
controller_busy
Operation was rejected because the controller is busy
and unable to process the request.
0x023b
unacceptable_connection_interval
Remote evice terminated the connection because of an
unacceptable connection interval.
0x023c
directed_advertising_timeout
Directed advertising completed without a connection being created.
0x023d
connection_terminated_due_to_mic_failure
Connection was terminated because the Message Integrity Check (MIC) failed on a received packet.
0x023e
connection_failed_to_be_established
LL initiated a connection but the connection has failed to
be established. Controller did not receive any packets
from remote end.
0x023f
mac_connection_failed
The MAC of the 802.11 AMP was requested to connect
to a peer, but the connection failed.
0x0240
coarse_clock_adjustment_rejected_but_will_try_to_adjust_using_clock_dragging
The master, at this time, is unable to make a coarse adjustment to the piconet clock, using the supplied parameters. Instead the master will attempt to move the clock
using clock dragging.
■
Application errors
Code
Name
Description
0x0a01
file_open_failed
File open failed.
0x0a02
xml_parse_failed
XML parsing failed.
0x0a03
device_connection_failed
Device connection failed.
0x0a04
device_comunication_failed
Device communication failed.
■
Errors from Attribute Protocol
Code
Name
Description
0x0401
invalid_handle
The attribute handle given was not valid on this server
0x0402
read_not_permitted
The attribute cannot be read
0x0403
write_not_permitted
The attribute cannot be written
0x0404
invalid_pdu
The attribute PDU was invalid
0x0405
insufficient_authentication
The attribute requires authentication before it can be
read or written.
0x0406
request_not_supported
Attribute Server does not support the request received
from the client.
0x0407
invalid_offset
Offset specified was past the end of the attribute
0x0408
insufficient_authorization
The attribute requires authorization before it can be read
or written.
0x0409
prepare_queue_full
Too many prepare writes have been queueud
0x040a
att_not_found
No attribute found within the given attribute handle
range.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 152
Bluetooth Smart Software API Reference Manual
API Reference
Code
Name
Description
0x040b
att_not_long
The attribute cannot be read or written using the Read
Blob Request
0x040c
insufficient_enc_key_size
The Encryption Key Size used for encrypting this link is
insufficient.
0x040d
invalid_att_length
The attribute value length is invalid for the operation
0x040e
unlikely_error
The attribute request that was requested has encountered an error that was unlikely, and therefore could not
be completed as requested.
0x040f
insufficient_encryption
The attribute requires encryption before it can be read or
written.
0x0410
unsupported_group_type
The attribute type is not a supported grouping attribute
as defined by a higher layer specification.
0x0411
insufficient_resources
Insufficient Resources to complete the request
0x0480
application
Application error code defined by a higher layer specification.
■
Filesystem errors
Code
Name
Description
0x0901
file_not_found
File not found
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 153
Bluetooth Smart Software API Reference Manual
Document Revision History
3. Document Revision History
Table 3.1. Document Revision History
Revision Number
Effective Date
Change Description
1.0
April 1st 2015
Initial version.
1.1
December 23rd
2015
Updated for firmware version 0.9.2.
1.2
January 15th 2016
Corrected typography and formatting issues.
1.3
February 12th 2016
Updated for firmware version 1.0.0.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 1.3 | 154
Smart.
Connected.
Energy-Friendly
Products
Quality
www.silabs.com/products
www.silabs.com/quality
Support and Community
community.silabs.com
Disclaimer
Silicon Laboratories intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software implementers using
or intending to use the Silicon Laboratories products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and
"Typical" parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Laboratories reserves the right to
make changes without further notice and limitation to product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the
included information. Silicon Laboratories shall have no liability for the consequences of use of the information supplied herein. This document does not imply or express copyright licenses
granted hereunder to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any Life Support System without the specific written consent
of Silicon Laboratories. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant
personal injury or death. Silicon Laboratories products are not designed or authorized for military applications. Silicon Laboratories products shall under no circumstances be used in
weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons.
Trademark Information
Silicon Laboratories Inc.® , Silicon Laboratories®, Silicon Labs®, SiLabs® and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, Clockbuilder®, CMEMS®, DSPLL®, EFM®, EFM32®,
EFR, Ember®, Energy Micro, Energy Micro logo and combinations thereof, "the world’s most energy friendly microcontrollers", Ember®, EZLink®, EZRadio®, EZRadioPRO®, Gecko®,
ISOmodem®, Precision32®, ProSLIC®, Simplicity Studio®, SiPHY®, Telegesis, the Telegesis Logo®, USBXpress® and others are trademarks or registered trademarks of Silicon Laboratories Inc. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. All other products or brand
names mentioned herein are trademarks of their respective holders.
Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
USA
http://www.silabs.com