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.