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.

BGAPI message header summary
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_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
evt_advertiser_periodic_advertising_status 0x04 0x03 5
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
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
L2CAP
Commands
cmd_l2cap_coc_send_connection_request 0x43 0x01 9
cmd_l2cap_coc_send_connection_response 0x43 0x02 11
cmd_l2cap_coc_send_le_flow_control_credit 0x43 0x03 5
cmd_l2cap_coc_send_disconnection_request 0x43 0x04 3
cmd_l2cap_coc_send_data 0x43 0x05 4
Events
evt_l2cap_coc_connection_request 0x43 0x01 13
evt_l2cap_coc_connection_response 0x43 0x02 11
evt_l2cap_coc_le_flow_control_credit 0x43 0x03 5
evt_l2cap_coc_channel_disconnected 0x43 0x04 5
evt_l2cap_coc_data 0x43 0x05 4
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_configure 0x45 0x00 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
Memory Profiler
Commands
cmd_memory_profiler_get_status 0xfd 0x00 0
cmd_memory_profiler_reset 0xfd 0x01 4
cmd_memory_profiler_list_ram_usage 0xfd 0x02 0
Events
evt_memory_profiler_ram_usage_entry 0xfd 0x00 25
evt_memory_profiler_list_ram_usage_complete 0xfd 0x01 0
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