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_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

cmd_connection_read_remote_used_features

0x06

0x0d

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_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

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

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

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

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