BGAPI#
BGAPI message header format#
The BGAPI message header is the first 4 bytes of a BGAPI message. It consists of device and message types, IDs, and data payload length.
Byte 1#
Bits 0 - 2: Highest 3 bits of the data payload length field
Bits 3 - 5: Device type
Bit value 100: Bluetooth LE
Bit value 101: Bluetooth Mesh
Bit 6: Reserved
Bit 7: Message type
Bit value 0: The message is a command or a response to command.
Bit value 1: The message is an event.
Byte 2#
This byte is the lowest 8 bits of the data payload length field.
Byte 3#
This byte is the BGAPI class ID.
Byte 4#
This byte is the message ID of a command, response or event.
A device type, class ID, message type and message ID together construct a unique identifer of a message within the BGAPI protocol.
Endianness#
BGAPI protocol stores data in little endian.
Payload Length Calculation#
Use SL_BGAPI_MSG_LEN to calculate the payload length of a BGAPI message.
Decode a BGAPI Message#
On an NCP host, a received API message is either a response or an event. As the message is in binary format, users may need to decode the binary to its corresponding named message definition. Following method can be used to decode a message binary received on NCP host:
Find out the device type from Byte 1 of the message header. Go to the BGAPI message summary table according to the device type. The table may be the BGAPI message summary in this document, or a table in another API reference manual. Bluetooth LE and Bluetooth Mesh APIs have separate API reference manuals.
Find out the message type of the message from bit 7 of the Byte 1 in the message header.
Find out the class ID which is the Byte 3 of the message header. Together with the message type, locate either the command or event message group for this class.
Locate the row in the message group according to the message ID which is the Byte 4 of the message header.
If the row is a command, the decoded message is a response to this command. Go to the command documentation. The 5th and 6th bytes of the binary are the error code returned for the command. Rest data of the binary maps to the [out] parameters of the command in declaration order.
If the row is an event, go to the event documentation. Data starting from the 5th byte maps to the event data structure fields in declaration order.
BGAPI message summary#
The following table summarizes the class and message IDs of commands and events in the BGAPI protocol. A response message has the same class and message ID as the command it responds to.
The table also shows the minimum payload length for each message. Messages that have an array parameter can have longer payload length depending on the length of the array.
Message Name | Class ID | Message ID | Minimum Payload Length |
|---|---|---|---|
Device Firmware Update | |||
Commands | |||
cmd_dfu_reset | 0x00 | 0x00 | 1 |
cmd_dfu_flash_set_address | 0x00 | 0x01 | 4 |
cmd_dfu_flash_upload | 0x00 | 0x02 | 1 |
cmd_dfu_flash_upload_finish | 0x00 | 0x03 | 0 |
Events | |||
evt_dfu_boot | 0x00 | 0x00 | 4 |
evt_dfu_boot_failure | 0x00 | 0x01 | 2 |
System | |||
Commands | |||
cmd_system_hello | 0x01 | 0x00 | 0 |
cmd_system_start_bluetooth | 0x01 | 0x1c | 0 |
cmd_system_stop_bluetooth | 0x01 | 0x1d | 0 |
cmd_system_get_version | 0x01 | 0x1b | 0 |
cmd_system_reset | 0x01 | 0x01 | 1 |
cmd_system_halt | 0x01 | 0x0c | 1 |
cmd_system_linklayer_configure | 0x01 | 0x0e | 2 |
cmd_system_set_max_tx_power | 0x01 | 0x16 | 2 |
cmd_system_set_tx_power | 0x01 | 0x17 | 4 |
cmd_system_get_tx_power_setting | 0x01 | 0x18 | 0 |
cmd_system_set_identity_address | 0x01 | 0x13 | 7 |
cmd_system_get_identity_address | 0x01 | 0x15 | 0 |
cmd_system_get_random_data | 0x01 | 0x0b | 1 |
cmd_system_data_buffer_write | 0x01 | 0x12 | 1 |
cmd_system_data_buffer_clear | 0x01 | 0x14 | 0 |
cmd_system_get_counters | 0x01 | 0x0f | 1 |
cmd_system_set_soft_timer | 0x01 | 0x19 | 6 |
cmd_system_set_lazy_soft_timer | 0x01 | 0x1a | 10 |
Events | |||
evt_system_boot | 0x01 | 0x00 | 18 |
evt_system_error | 0x01 | 0x06 | 3 |
evt_system_hardware_error | 0x01 | 0x05 | 2 |
evt_system_external_signal | 0x01 | 0x03 | 4 |
evt_system_awake | 0x01 | 0x04 | 0 |
evt_system_soft_timer | 0x01 | 0x07 | 1 |
GAP | |||
Commands | |||
cmd_gap_set_privacy_mode | 0x02 | 0x01 | 2 |
cmd_gap_set_data_channel_classification | 0x02 | 0x02 | 1 |
cmd_gap_enable_whitelisting | 0x02 | 0x03 | 1 |
Advertiser | |||
Commands | |||
cmd_advertiser_create_set | 0x04 | 0x01 | 0 |
cmd_advertiser_set_timing | 0x04 | 0x03 | 12 |
cmd_advertiser_set_phy | 0x04 | 0x06 | 3 |
cmd_advertiser_set_channel_map | 0x04 | 0x04 | 2 |
cmd_advertiser_set_tx_power | 0x04 | 0x0b | 3 |
cmd_advertiser_set_report_scan_request | 0x04 | 0x05 | 2 |
cmd_advertiser_set_random_address | 0x04 | 0x10 | 8 |
cmd_advertiser_clear_random_address | 0x04 | 0x11 | 1 |
cmd_advertiser_set_configuration | 0x04 | 0x07 | 5 |
cmd_advertiser_clear_configuration | 0x04 | 0x08 | 5 |
cmd_advertiser_set_data | 0x04 | 0x0f | 3 |
cmd_advertiser_set_long_data | 0x04 | 0x0e | 2 |
cmd_advertiser_start | 0x04 | 0x09 | 3 |
cmd_advertiser_stop | 0x04 | 0x0a | 1 |
cmd_advertiser_start_periodic_advertising | 0x04 | 0x0c | 9 |
cmd_advertiser_stop_periodic_advertising | 0x04 | 0x0d | 1 |
cmd_advertiser_delete_set | 0x04 | 0x02 | 1 |
Events | |||
evt_advertiser_timeout | 0x04 | 0x01 | 1 |
evt_advertiser_scan_request | 0x04 | 0x02 | 9 |
Scanner | |||
Commands | |||
cmd_scanner_set_timing | 0x05 | 0x01 | 5 |
cmd_scanner_set_mode | 0x05 | 0x02 | 2 |
cmd_scanner_start | 0x05 | 0x03 | 2 |
cmd_scanner_stop | 0x05 | 0x05 | 0 |
Events | |||
evt_scanner_scan_report | 0x05 | 0x01 | 18 |
Synchronization | |||
Commands | |||
cmd_sync_set_parameters | 0x42 | 0x02 | 8 |
cmd_sync_open | 0x42 | 0x00 | 8 |
cmd_sync_close | 0x42 | 0x01 | 2 |
Events | |||
evt_sync_opened | 0x42 | 0x00 | 16 |
evt_sync_data | 0x42 | 0x02 | 6 |
evt_sync_closed | 0x42 | 0x01 | 4 |
Connection | |||
Commands | |||
cmd_connection_set_default_parameters | 0x06 | 0x00 | 12 |
cmd_connection_set_default_preferred_phy | 0x06 | 0x01 | 2 |
cmd_connection_open | 0x06 | 0x04 | 8 |
cmd_connection_set_parameters | 0x06 | 0x06 | 13 |
cmd_connection_set_preferred_phy | 0x06 | 0x08 | 3 |
cmd_connection_disable_slave_latency | 0x06 | 0x03 | 2 |
cmd_connection_get_rssi | 0x06 | 0x02 | 1 |
cmd_connection_read_channel_map | 0x06 | 0x07 | 1 |
cmd_connection_set_power_reporting | 0x06 | 0x09 | 2 |
cmd_connection_set_remote_power_reporting | 0x06 | 0x0a | 2 |
cmd_connection_get_tx_power | 0x06 | 0x0b | 2 |
cmd_connection_get_remote_tx_power | 0x06 | 0x0c | 2 |
cmd_connection_close | 0x06 | 0x05 | 1 |
Events | |||
evt_connection_opened | 0x06 | 0x00 | 11 |
evt_connection_parameters | 0x06 | 0x02 | 10 |
evt_connection_phy_status | 0x06 | 0x04 | 2 |
evt_connection_rssi | 0x06 | 0x03 | 3 |
evt_connection_get_remote_tx_power_completed | 0x06 | 0x05 | 7 |
evt_connection_tx_power | 0x06 | 0x06 | 5 |
evt_connection_remote_tx_power | 0x06 | 0x07 | 5 |
evt_connection_closed | 0x06 | 0x01 | 3 |
GATT Client | |||
Commands | |||
cmd_gatt_set_max_mtu | 0x09 | 0x00 | 2 |
cmd_gatt_discover_primary_services | 0x09 | 0x01 | 1 |
cmd_gatt_discover_primary_services_by_uuid | 0x09 | 0x02 | 2 |
cmd_gatt_find_included_services | 0x09 | 0x10 | 5 |
cmd_gatt_discover_characteristics | 0x09 | 0x03 | 5 |
cmd_gatt_discover_characteristics_by_uuid | 0x09 | 0x04 | 6 |
cmd_gatt_discover_descriptors | 0x09 | 0x06 | 3 |
cmd_gatt_set_characteristic_notification | 0x09 | 0x05 | 4 |
cmd_gatt_send_characteristic_confirmation | 0x09 | 0x0d | 1 |
cmd_gatt_read_characteristic_value | 0x09 | 0x07 | 3 |
cmd_gatt_read_characteristic_value_from_offset | 0x09 | 0x12 | 7 |
cmd_gatt_read_multiple_characteristic_values | 0x09 | 0x11 | 2 |
cmd_gatt_read_characteristic_value_by_uuid | 0x09 | 0x08 | 6 |
cmd_gatt_write_characteristic_value | 0x09 | 0x09 | 4 |
cmd_gatt_write_characteristic_value_without_response | 0x09 | 0x0a | 4 |
cmd_gatt_prepare_characteristic_value_write | 0x09 | 0x0b | 6 |
cmd_gatt_prepare_characteristic_value_reliable_write | 0x09 | 0x13 | 6 |
cmd_gatt_execute_characteristic_value_write | 0x09 | 0x0c | 2 |
cmd_gatt_read_descriptor_value | 0x09 | 0x0e | 3 |
cmd_gatt_write_descriptor_value | 0x09 | 0x0f | 4 |
Events | |||
evt_gatt_mtu_exchanged | 0x09 | 0x00 | 3 |
evt_gatt_service | 0x09 | 0x01 | 6 |
evt_gatt_characteristic | 0x09 | 0x02 | 5 |
evt_gatt_descriptor | 0x09 | 0x03 | 4 |
evt_gatt_characteristic_value | 0x09 | 0x04 | 7 |
evt_gatt_descriptor_value | 0x09 | 0x05 | 6 |
evt_gatt_procedure_completed | 0x09 | 0x06 | 3 |
GATT Server | |||
Commands | |||
cmd_gatt_server_set_capabilities | 0x0a | 0x08 | 8 |
cmd_gatt_server_enable_capabilities | 0x0a | 0x0c | 4 |
cmd_gatt_server_disable_capabilities | 0x0a | 0x0d | 4 |
cmd_gatt_server_get_enabled_capabilities | 0x0a | 0x0e | 0 |
cmd_gatt_server_set_max_mtu | 0x0a | 0x0a | 2 |
cmd_gatt_server_get_mtu | 0x0a | 0x0b | 1 |
cmd_gatt_server_find_attribute | 0x0a | 0x06 | 3 |
cmd_gatt_server_read_attribute_value | 0x0a | 0x00 | 4 |
cmd_gatt_server_read_attribute_type | 0x0a | 0x01 | 2 |
cmd_gatt_server_write_attribute_value | 0x0a | 0x02 | 5 |
cmd_gatt_server_send_user_read_response | 0x0a | 0x03 | 5 |
cmd_gatt_server_send_user_write_response | 0x0a | 0x04 | 4 |
cmd_gatt_server_send_characteristic_notification | 0x0a | 0x05 | 4 |
cmd_gatt_server_send_notification | 0x0a | 0x0f | 4 |
cmd_gatt_server_send_indication | 0x0a | 0x10 | 4 |
cmd_gatt_server_notify_all | 0x0a | 0x11 | 3 |
cmd_gatt_server_read_client_configuration | 0x0a | 0x12 | 3 |
cmd_gatt_server_send_user_prepare_write_response | 0x0a | 0x14 | 7 |
Events | |||
evt_gatt_server_attribute_value | 0x0a | 0x00 | 7 |
evt_gatt_server_user_read_request | 0x0a | 0x01 | 6 |
evt_gatt_server_user_write_request | 0x0a | 0x02 | 7 |
evt_gatt_server_characteristic_status | 0x0a | 0x03 | 6 |
evt_gatt_server_execute_write_completed | 0x0a | 0x04 | 3 |
evt_gatt_server_indication_timeout | 0x0a | 0x05 | 1 |
NVM | |||
Commands | |||
cmd_nvm_save | 0x0d | 0x02 | 3 |
cmd_nvm_load | 0x0d | 0x03 | 2 |
cmd_nvm_erase | 0x0d | 0x04 | 2 |
cmd_nvm_erase_all | 0x0d | 0x01 | 0 |
Testing Commands | |||
Commands | |||
cmd_test_dtm_tx | 0x0e | 0x00 | 4 |
cmd_test_dtm_tx_v4 | 0x0e | 0x03 | 5 |
cmd_test_dtm_rx | 0x0e | 0x01 | 2 |
cmd_test_dtm_end | 0x0e | 0x02 | 0 |
Events | |||
evt_test_dtm_completed | 0x0e | 0x00 | 4 |
Security Manager | |||
Commands | |||
cmd_sm_configure | 0x0f | 0x01 | 2 |
cmd_sm_set_minimum_key_size | 0x0f | 0x14 | 1 |
cmd_sm_set_debug_mode | 0x0f | 0x0f | 0 |
cmd_sm_add_to_whitelist | 0x0f | 0x13 | 7 |
cmd_sm_store_bonding_configuration | 0x0f | 0x02 | 2 |
cmd_sm_set_bondable_mode | 0x0f | 0x00 | 1 |
cmd_sm_set_passkey | 0x0f | 0x10 | 4 |
cmd_sm_set_oob_data | 0x0f | 0x0a | 1 |
cmd_sm_use_sc_oob | 0x0f | 0x11 | 1 |
cmd_sm_set_sc_remote_oob_data | 0x0f | 0x12 | 1 |
cmd_sm_increase_security | 0x0f | 0x04 | 1 |
cmd_sm_enter_passkey | 0x0f | 0x08 | 5 |
cmd_sm_passkey_confirm | 0x0f | 0x09 | 2 |
cmd_sm_bonding_confirm | 0x0f | 0x0e | 2 |
cmd_sm_list_all_bondings | 0x0f | 0x0b | 0 |
cmd_sm_delete_bonding | 0x0f | 0x06 | 1 |
cmd_sm_delete_bondings | 0x0f | 0x07 | 0 |
Events | |||
evt_sm_passkey_display | 0x0f | 0x00 | 5 |
evt_sm_passkey_request | 0x0f | 0x01 | 1 |
evt_sm_confirm_passkey | 0x0f | 0x02 | 5 |
evt_sm_bonded | 0x0f | 0x03 | 2 |
evt_sm_bonding_failed | 0x0f | 0x04 | 3 |
evt_sm_confirm_bonding | 0x0f | 0x09 | 2 |
evt_sm_list_bonding_entry | 0x0f | 0x05 | 8 |
evt_sm_list_all_bondings_complete | 0x0f | 0x06 | 0 |
OTA | |||
Commands | |||
cmd_ota_set_device_name | 0x10 | 0x01 | 1 |
cmd_ota_set_advertising_data | 0x10 | 0x02 | 2 |
cmd_ota_set_configuration | 0x10 | 0x03 | 4 |
cmd_ota_set_rf_path | 0x10 | 0x04 | 2 |
Coexistence | |||
Commands | |||
cmd_coex_set_options | 0x20 | 0x00 | 8 |
cmd_coex_set_parameters | 0x20 | 0x02 | 4 |
cmd_coex_set_directional_priority_pulse | 0x20 | 0x03 | 1 |
cmd_coex_get_counters | 0x20 | 0x01 | 1 |
CTE Transmitter | |||
Commands | |||
cmd_cte_transmitter_set_dtm_parameters | 0x44 | 0x04 | 3 |
cmd_cte_transmitter_clear_dtm_parameters | 0x44 | 0x05 | 0 |
cmd_cte_transmitter_enable_connection_cte | 0x44 | 0x00 | 3 |
cmd_cte_transmitter_disable_connection_cte | 0x44 | 0x01 | 1 |
cmd_cte_transmitter_enable_connectionless_cte | 0x44 | 0x02 | 5 |
cmd_cte_transmitter_disable_connectionless_cte | 0x44 | 0x03 | 1 |
cmd_cte_transmitter_enable_silabs_cte | 0x44 | 0x06 | 5 |
cmd_cte_transmitter_disable_silabs_cte | 0x44 | 0x07 | 1 |
CTE Receiver | |||
Commands | |||
cmd_cte_receiver_set_dtm_parameters | 0x45 | 0x05 | 4 |
cmd_cte_receiver_clear_dtm_parameters | 0x45 | 0x06 | 0 |
cmd_cte_receiver_set_sync_cte_type | 0x45 | 0x09 | 1 |
cmd_cte_receiver_enable_connection_cte | 0x45 | 0x01 | 7 |
cmd_cte_receiver_disable_connection_cte | 0x45 | 0x02 | 1 |
cmd_cte_receiver_enable_connectionless_cte | 0x45 | 0x03 | 5 |
cmd_cte_receiver_disable_connectionless_cte | 0x45 | 0x04 | 2 |
cmd_cte_receiver_enable_silabs_cte | 0x45 | 0x07 | 3 |
cmd_cte_receiver_disable_silabs_cte | 0x45 | 0x08 | 0 |
Events | |||
evt_cte_receiver_dtm_iq_report | 0x45 | 0x02 | 10 |
evt_cte_receiver_connection_iq_report | 0x45 | 0x00 | 12 |
evt_cte_receiver_connectionless_iq_report | 0x45 | 0x01 | 12 |
evt_cte_receiver_silabs_iq_report | 0x45 | 0x03 | 18 |
User Messaging | |||
Commands | |||
cmd_user_message_to_target | 0xff | 0x00 | 1 |
cmd_user_manage_event_filter | 0xff | 0x01 | 1 |
Events | |||
evt_user_message_to_host | 0xff | 0x00 | 1 |