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