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
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_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_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
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
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
cmd_connection_read_remote_used_features 0x06 0x0d 1
cmd_connection_get_security_status 0x06 0x0e 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
evt_connection_remote_used_features 0x06 0x08 2
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 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
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
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
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 11
evt_l2cap_le_channel_open_response 0x43 0x02 11
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 4
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