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.

Concurrency#

When the application runs in an RTOS, the Bluetooth RTOS adaptation component has a mechanism to synchronize the handling of individual BGAPI commands. Thus, individual BGAPI commands are safe to be called from multiple threads when the Bluetooth RTOS adaptation component is used.

BGAPI commands cannot be called from interrupt context. Calling a command from interrupt context may delay the radio activity. Furthermore, when commands are also called from the main event loop or an RTOS task simultaneously, concurrent BGAPI calls may cause memory issues in the stack.

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.

BGAPI message header summary
Message Name	Class ID	Message ID	Minimum Payload Length
Device Firmware Update
Commands
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_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_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_resource_exhausted	0x01	0x08	3
evt_system_external_signal	0x01	0x03	4
evt_system_awake	0x01	0x04	0
evt_system_soft_timer	0x01	0x07	1
Resource Report
Commands
cmd_resource_get_status	0x5f	0x00	0
cmd_resource_set_report_threshold	0x5f	0x01	8
cmd_resource_enable_connection_tx_report	0x5f	0x02	2
cmd_resource_get_connection_tx_status	0x5f	0x03	1
cmd_resource_disable_connection_tx_report	0x5f	0x04	0
Events
evt_resource_status	0x5f	0x00	4
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
cmd_gap_set_identity_address	0x02	0x04	7
Advertiser
Commands
cmd_advertiser_create_set	0x04	0x01	0
cmd_advertiser_configure	0x04	0x12	5
cmd_advertiser_set_timing	0x04	0x03	12
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_stop	0x04	0x0a	1
cmd_advertiser_delete_set	0x04	0x02	1
cmd_advertiser_set_phy	0x04	0x06	3
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_start_periodic_advertising	0x04	0x0c	9
cmd_advertiser_stop_periodic_advertising	0x04	0x0d	1
Events
evt_advertiser_timeout	0x04	0x01	1
evt_advertiser_scan_request	0x04	0x02	9
Legacy Advertiser
Commands
cmd_legacy_advertiser_set_data	0x56	0x00	3
cmd_legacy_advertiser_generate_data	0x56	0x01	2
cmd_legacy_advertiser_start	0x56	0x02	2
cmd_legacy_advertiser_start_directed	0x56	0x03	9
Extended Advertiser
Commands
cmd_extended_advertiser_set_phy	0x57	0x00	3
cmd_extended_advertiser_set_data	0x57	0x01	2
cmd_extended_advertiser_set_long_data	0x57	0x02	1
cmd_extended_advertiser_generate_data	0x57	0x03	2
cmd_extended_advertiser_start	0x57	0x04	6
cmd_extended_advertiser_start_directed	0x57	0x05	13
Periodic Advertiser
Commands
cmd_periodic_advertiser_set_data	0x58	0x00	2
cmd_periodic_advertiser_set_long_data	0x58	0x01	1
cmd_periodic_advertiser_start	0x58	0x02	9
cmd_periodic_advertiser_stop	0x58	0x03	1
Events
Scanner
Commands
cmd_scanner_set_parameters	0x05	0x06	5
cmd_scanner_set_parameters_and_filter	0x05	0x07	10
cmd_scanner_stop	0x05	0x05	0
cmd_scanner_set_timing	0x05	0x01	5
cmd_scanner_set_mode	0x05	0x02	2
cmd_scanner_start	0x05	0x03	2
Events
evt_scanner_legacy_advertisement_report	0x05	0x00	19
evt_scanner_extended_advertisement_report	0x05	0x02	27
evt_scanner_scan_report	0x05	0x01	18
Synchronization
Commands
cmd_sync_set_parameters	0x42	0x02	8
cmd_sync_open	0x42	0x00	8
cmd_sync_set_reporting_mode	0x42	0x03	3
cmd_sync_update_sync_parameters	0x42	0x04	6
cmd_sync_close	0x42	0x01	2
Events
evt_sync_opened	0x42	0x00	16
evt_sync_transfer_received	0x42	0x03	21
evt_sync_data	0x42	0x02	6
evt_sync_closed	0x42	0x01	4
Periodic Advertising Sync Scanner
Commands
cmd_sync_scanner_set_sync_parameters	0x50	0x00	5
cmd_sync_scanner_open	0x50	0x01	8
PAST Receiver
Commands
cmd_past_receiver_set_default_sync_receive_parameters	0x51	0x00	6
cmd_past_receiver_set_sync_receive_parameters	0x51	0x01	7
Advertiser PAST
Commands
cmd_advertiser_past_transfer	0x52	0x00	4
Sync PAST
Commands
cmd_sync_past_transfer	0x5b	0x00	5
Periodic Advertising without responses Synchronization
Commands
Events
evt_periodic_sync_opened	0x53	0x00	16
evt_periodic_sync_transfer_received	0x53	0x01	21
evt_periodic_sync_report	0x53	0x02	8
Periodic Advertising with responses Synchronization
Commands
cmd_pawr_sync_set_sync_subevents	0x54	0x02	3
cmd_pawr_sync_set_response_data	0x54	0x03	8
Events
evt_pawr_sync_opened	0x54	0x00	20
evt_pawr_sync_transfer_received	0x54	0x01	25
evt_pawr_sync_subevent_report	0x54	0x02	11
PAwR Advertiser
Commands
cmd_pawr_advertiser_start	0x55	0x00	14
cmd_pawr_advertiser_set_subevent_data	0x55	0x01	5
cmd_pawr_advertiser_create_connection	0x55	0x02	9
cmd_pawr_advertiser_stop	0x55	0x03	1
Events
evt_pawr_advertiser_subevent_data_request	0x55	0x00	3
evt_pawr_advertiser_subevent_tx_failed	0x55	0x02	2
evt_pawr_advertiser_response_report	0x55	0x01	9
Connection
Commands
cmd_connection_set_default_parameters	0x06	0x00	12
cmd_connection_set_default_preferred_phy	0x06	0x01	2
cmd_connection_set_default_data_length	0x06	0x10	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_set_tx_power	0x06	0x12	3
cmd_connection_read_remote_used_features	0x06	0x0d	1
cmd_connection_get_security_status	0x06	0x0e	1
cmd_connection_set_data_length	0x06	0x11	5
cmd_connection_close	0x06	0x05	1
cmd_connection_forcefully_close	0x06	0x0f	1
Events
evt_connection_opened	0x06	0x00	13
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_remote_used_features	0x06	0x08	2
evt_connection_data_length	0x06	0x09	9
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_discover_characteristic_descriptors	0x09	0x14	5
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 Database
Commands
cmd_gattdb_new_session	0x46	0x00	0
cmd_gattdb_add_service	0x46	0x01	5
cmd_gattdb_remove_service	0x46	0x02	4
cmd_gattdb_add_included_service	0x46	0x03	6
cmd_gattdb_remove_included_service	0x46	0x04	4
cmd_gattdb_add_uuid16_characteristic	0x46	0x05	16
cmd_gattdb_add_uuid128_characteristic	0x46	0x06	30
cmd_gattdb_remove_characteristic	0x46	0x07	4
cmd_gattdb_add_uuid16_descriptor	0x46	0x08	15
cmd_gattdb_add_uuid128_descriptor	0x46	0x09	29
cmd_gattdb_remove_descriptor	0x46	0x0a	4
cmd_gattdb_start_service	0x46	0x0b	4
cmd_gattdb_stop_service	0x46	0x0c	4
cmd_gattdb_start_characteristic	0x46	0x0d	4
cmd_gattdb_stop_characteristic	0x46	0x0e	4
cmd_gattdb_commit	0x46	0x0f	2
cmd_gattdb_abort	0x46	0x10	2
GATT Server
Commands
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_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
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_read_client_supported_features	0x0a	0x15	1
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	8
evt_gatt_server_execute_write_completed	0x0a	0x04	3
evt_gatt_server_indication_timeout	0x0a	0x05	1
evt_gatt_server_notification_tx_completed	0x0a	0x06	2
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_v4	0x0e	0x03	5
cmd_test_dtm_tx_cw	0x0e	0x04	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_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_delete_bonding	0x0f	0x06	1
cmd_sm_delete_bondings	0x0f	0x07	0
cmd_sm_get_bonding_handles	0x0f	0x15	4
cmd_sm_get_bonding_details	0x0f	0x16	4
cmd_sm_find_bonding_by_address	0x0f	0x17	6
cmd_sm_set_legacy_oob	0x0f	0x19	17
cmd_sm_set_oob	0x0f	0x1a	1
cmd_sm_set_remote_oob	0x0f	0x1b	33
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	3
evt_sm_bonding_failed	0x0f	0x04	3
evt_sm_confirm_bonding	0x0f	0x09	2
External Bonding Database
Commands
cmd_external_bondingdb_set_data	0x5c	0x00	3
Events
evt_external_bondingdb_data_request	0x5c	0x00	2
evt_external_bondingdb_data	0x5c	0x01	3
evt_external_bondingdb_data_ready	0x5c	0x02	1
Address Resolving List
Commands
cmd_resolving_list_add_device_by_bonding	0x5d	0x00	5
cmd_resolving_list_add_device_by_address	0x5d	0x01	24
cmd_resolving_list_remove_device_by_bonding	0x5d	0x02	4
cmd_resolving_list_remove_device_by_address	0x5d	0x03	7
cmd_resolving_list_remove_all_devices	0x5d	0x04	0
Filter Accept List
Commands
cmd_accept_list_add_device_by_bonding	0x5e	0x00	4
cmd_accept_list_add_device_by_address	0x5e	0x01	7
cmd_accept_list_remove_device_by_bonding	0x5e	0x02	4
cmd_accept_list_remove_device_by_address	0x5e	0x03	7
cmd_accept_list_remove_all_devices	0x5e	0x04	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_parameters	0x20	0x04	0
cmd_coex_get_counters	0x20	0x01	1
Accurate Bluetooth Ranging
Commands
cmd_cs_security_enable	0x59	0x00	1
cmd_cs_set_default_settings	0x59	0x01	5
cmd_cs_create_config	0x59	0x02	27
cmd_cs_remove_config	0x59	0x03	2
cmd_cs_set_channel_classification	0x59	0x04	10
cmd_cs_set_procedure_parameters	0x59	0x05	22
cmd_cs_procedure_enable	0x59	0x06	3
cmd_cs_set_antenna_configuration	0x59	0x07	1
Events
evt_cs_security_enable_complete	0x59	0x00	1
evt_cs_config_complete	0x59	0x01	29
evt_cs_procedure_enable_complete	0x59	0x02	20
evt_cs_result	0x59	0x03	15
Accurate Bluetooth Ranging Test
Commands
cmd_cs_test_start	0x5a	0x00	26
L2CAP Connection Oriented Channels
Commands
cmd_l2cap_open_le_channel	0x43	0x01	9
cmd_l2cap_send_le_channel_open_response	0x43	0x02	11
cmd_l2cap_channel_send_data	0x43	0x03	4
cmd_l2cap_channel_send_credit	0x43	0x04	5
cmd_l2cap_close_channel	0x43	0x05	3
Events
evt_l2cap_le_channel_open_request	0x43	0x01	13
evt_l2cap_le_channel_open_response	0x43	0x02	13
evt_l2cap_channel_data	0x43	0x03	4
evt_l2cap_channel_credit	0x43	0x04	5
evt_l2cap_channel_closed	0x43	0x05	5
evt_l2cap_command_rejected	0x43	0x06	6
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_set_default_sync_receive_parameters	0x45	0x0a	7
cmd_cte_receiver_set_sync_receive_parameters	0x45	0x0b	8
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
cmd_user_reset_to_dfu	0xff	0x02	0
Events
evt_user_message_to_host	0xff	0x00	1