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