STM32WBA Bluetooth LE NCP RCP framework

This wiki page presents the STM32WBA devices series Bluetooth^® LE network and radio coprocessor framework architecture and the related hardware and software configurations. It also describes the Bluetooth^® LE commands and event data format, as well as the SPI protocol specification used for the SPI interface.

1. Introduction

A typical Bluetooth^® LE system contains a controller and a host:

• The LE controller consists of a physical layer (PHY) including the radio, a link layer (LL), and a standard host-controller interface (HCI).
• The host consists of an HCI and other higher protocol layers, such as L2CAP, SM, ATT/GATT, or GAP.

The following network and radio coprocessor options are available for STM32WBA series devices:

• Network coprocessor controller only (also called radio coprocessor (RCP))
• Network coprocessor host and controller (NCP)

In a radio coprocessor (RCP) approach, the host and LE controller reside in two separate microcontrollers. Communication between the two microcontrollers occurs through a standard serial interface, such as UART or SPI. The host can send HCI commands to communicate with the LE controller. The HCI interface and the HCI commands are standardized by the Bluetooth^® core specification. The Zephyr framework specifically tailors the radio coprocessor approach.

Bluetooth LE radio coprocessor (controller only)

In the network coprocessor host-and-controller (NCP) approach, the LE controller and the host reside in a single microcontroller. The user application is implemented in an external microcontroller and communication between the two microcontrollers occurs through a standard serial interface, such as UART or SPI. A specific application command interface (ACI) is provided for accessing the Bluetooth^® LE host and controller. The user application can send ACI commands to control the STM32WBA Bluetooth^® LE network coprocessor and receive events from it.

Bluetooth LE network coprocessor (host and controller)

STM32WBA devices series can be configured as a Bluetooth^® LE NCP or RCP.

STM32WBA Bluetooth® LE network coprocessor options (NCP/RCP)

1.1. External microcontroller interface (UART or SPI)

An STM32WBA device series configured as a network or radio coprocessor provides a hardware interface to an external microcontroller using two very common protocols:

• SPI protocol with interrupt signal (with low-power mode enabled)
• UART protocol (no low-power mode)

The physical layer (SPI or UART) transfers commands and events between the external microcontroller and the STM32WBA series device.

1.1.1. UART interface

The UART interface has the following characteristics:

• Baud rate: 115200
• Data bits: 8
• Parity: N
• Stop bits: 1
• Full duplex

The UART interface does not allow the device to enter the sleep state and requires two pins:

• UART Tx
• UART Rx

1.1.2. SPI interface

The characteristics of the SPI interface are the following:

• SPI clock: refer to the STM32WBA devices series datasheets for supported speed.
• Data bits: 8
• Polarity: 1 (clock to 1 when idle)
• Phase: second edge
• Full duplex
• Controller mode

The SPI port requires five pins:

• SPI CLK
• SPI MOSI
• SPI MISO
• SPI CS
• SPI IRQ

A dedicated IRQ pin informs the external microcontroller that an event has occurred and the device needs attention. The SPI interface allows the device to go into sleep state, achieving optimal power consumption.

The following table describes the USART1 lines used on STM32WBA series devices.

USART1 lines
STM32WBA25 STM32WBA55 STM32WBA65 USART1 RX PA12 PA8 PA8 USART1 TX PA6 PB12 PB12

The following table describes the SPI lines used on STM32WBA series devices.

SPI lines
STM32WBA25 STM32WBA55 STM32WBA65 SPI MOSI PA9 (SPI3) PA15 (SPI1) PC3 (SPI2) SPI MISO PA10 (SPI3) PB3 (SPI1) PA9 (SPI2) SPI Clock PA8 (SPI3) PB4 (SPI1) PB10 (SPI2) SPI CS PA5 PA12 PB9 SPI IRQ PH3 PH3 PH3

Information

STM32WBA25 device uses the SPI3 interface; STM32WB55 device uses the SPI1 interface; STM32WB65 device uses the SPI2 interface.

1.2. External microcontroller interface (UART or SPI) example: STM32U3

The X-CUBE-WBA software expansion package for STM32Cube provides an example of UART and SPI protocol implementation on the STM32U3 microcontroller.

It provides a reference software framework for the STM32U3 external microcontroller connected to an X-NUCLEO-WBA25CE1 board, which includes an STM32WBA25CE device.

No dedicated Nucleo expansion boards are available with the STM32WBA55xx and STM32WBA65xx device variants.

The UART and SPI protocol implementation provided with the X-CUBE-WBA software package is designed to work with STM32WBA series device configured as a network or radio coprocessor (STM32WBA25CE, STM32WBA55CG, STM32WBA65RI)

Refer to the wiki page for more information about how to build a Bluetooth^® LE application within the Bluetooth^® LE network/radio coprocessor framework available on this SW package.

1.2.1. BLE_TransparentMode application configuration

On STM32WBA series devices, users can configure the device as a network coprocessor (NCP) by using the BLE_TransparentMode application, available in the STM32CubeWBA MCU Package.

The BLE_TransparentMode (UART mode) and BLE_TransparentMode_SPI (SPI mode) applications for network coprocessor configuration are built on top of the STMicroelectronics Bluetooth^® LE stack binary images (stm32wba_ble_stack_full.a + WBA2_LinkLayer_BLE_Full_lib.a/WBA5_LinkLayer_BLE_Full_lib.a/WBA6_LinkLayer_BLE_Full_lib.a ), provided with the STM32CubeWBA MCU Package.

These applications are built with the BLE_OPTIONS_EXTENDED_ADV option in order to use the extended set of advertising/scanning commands and events.

The BLE_TransparentMode_C_O (UART mode) and BLE_TransparentMode_SPI_C_O (SPI mode) applications for radio coprocessor (RCP) configuration are built on top of the STMicroelectronics Bluetooth^® LE controller-only binary image files (stm32wba_ble_stack_llo.a + WBA2_LinkLayer_BLE_Full_lib.a/WBA5_LinkLayer_BLE_Full_lib.a/WBA6_LinkLayer_BLE_Full_lib.a), provided with the STM32CubeWBA MCU Package.

Notes:

The references BLE_TransparentMode (UART mode) and BLE_TransparentMode_SPI (SPI mode) projects to be used for network coprocessor configuration are available in the STM32CubeWBA MCU Package (Projects\{NUCLEO-WBA25CE|NUCLEO-WBA55CG|NUCLEO-WBA65RI}\Applications\BLE folders).

The references BLE_TransparentMode_C_O (UART mode) and BLE_TransparentMode_SPI_C_O (SPI mode) projects to be used for radio coprocessor configuration can be built, respectively, from BLE_TransparentMode (UART mode) and BLE_TransparentMode_SPI (SPI mode) projects available in the STM32CubeWBA MCU Package (Projects\{NUCLEO-WBA25CE|NUCLEO-WBA55CG|NUCLEO-WBA65RI}\Applications\BLE folders), by following these steps:

• Open the related ioc file through STM32CubeMX tool
• On STM32_WPAN, Configuration, BLE_OPTIONS_LL_ONLY: select Link Layer only
• Follow STM32CubeMX indication in order to address required configurations raised as warnings from the tool
• Generate and save the project as BLE_TransparentMode_C_O (UART mode) or BLE_TransparentMode_SPI_C_O (SPI mode) on the specific destination Project folder: {NUCLEO-WBA25CE|NUCLEO-WBA55CG|NUCLEO-WBA65RI}\Applications\BLE.

Refer to the Guidelines for Bluetooth^® LE stack programming on STM32WB/STM32WBA MCUs (PM0271) for more information about the STM32WBA devices Bluetooth LE stack.

2. SPI protocol

The SPI protocol for the STM32WBA Bluetooth^® LE network and radio coprocessor framework targets the following:

• Power efficiency
• Code efficiency
• Fast data transfer

For detailed description about the SPI protocol specification refer to the Getting started with X-CUBE-WBA Bluetooth LE software expansion for STM32Cube (UM3529), Section 4.4 SPI protocol.

3. STM32WBA series Bluetooth^® LE stack ACI

A specific application command interface (ACI) is provided to access the STM32WBA series device Bluetooth^® LE host and controller components. User applications, running on an external microcontroller, can send ACI commands to control the STM32WBA device.

3.1. ACI commands data format

The Bluetooth^® LE stack ACI commands use the standard HCI data format. The supported HCI packets are as follows:

• HCI command packet (packet type: 0x01)
• HCI ACL data packet (packet type: 0x02)
• HCI synchronous data packet (packet type: 0x03)
• HCI event packet (packet type: 0x04)

The STM32WBA Bluetooth^® LE stack does not support the HCI synchronous data packet.

3.2. HCI command packet format

When an external device sends a command to the STM32WBA Bluetooth^® LE stack, the command must be formatted in an HCI command packet.

HCI command packet

Each HCI command uses a two-byte OpCode as a unique identifier for different types of commands.

The OpCode is divided into two fields: the OpCode group field (OGF) and the OpCode command field (OCF). The OGF consists of the six upper bits, while the remaining 10 lower bits are used by the OCF.

All HCI commands are grouped into logical categories by the Bluetooth^® specification, and each group is assigned a unique OGF value.

OGF values
Group name OGF value Link control commands 0x01 Link policy commands 0x02 Controller and baseband commands 0x03 Information parameters 0x04 Status parameters 0x05 Testing commands 0x06 LE controller commands 0x08 Vendor specific commands 0x3F

Depending on the OGF, the commands can be categorized into three sets:

• Standard HCI commands: these commands have an OGF value other than 0x3F. These commands are designed for the controller. All standard HCI command are clearly defined in the Bluetooth^® specification.
• Vendor-specific HCI commands: the commands with an OGF value 0x3F and are designed for the controller. Each vendor can define their own commands based on the hardware implementation.
• Vendor-specific ACI commands: these commands also have an OGF value 0x3F, but these commands are designed to control and access the host. The Bluetooth^® specification does not define any commands for the host, so all ACI commands are naturally vendor-specific.

The commands designed to control the controller are called HCI commands. This name is defined by the Bluetooth^® specification and is used here for conformity.

The commands designed to control the host are called ACI commands. A different name is used here to indicate that this command is assigned to the host, that is the entire Bluetooth^® LE system, and not only the controller at the lower level. However, because both ACI and HCI commands are received from the external device through the ACI interface, and they share the same data format, sometimes it is unnecessary to differentiate between the two.

The value of the OpCode is much more important. Each command, regardless of whether it is an HCI or ACI command, matches only one OpCode value. The user application must ensure that the OpCode value is used correctly.

NOTE:

The Bluetooth^® specification uses a bit-wise little-endian format for the OpCode. So in the HCI command packet figure, the OGF field is placed to the right. In this document, writing an OpCode in the 0xXXXX format implies the most significant bit is on the left.

For example, if the OpCode is 0xFE81, its top 6-bit OGF is "111111" (0x3F), so it is a vendor-specific command. And its OCF is the 10-bit 0x281. Or if the OpCode is 0x0406, the 6-bit OGF is 0x01, and its OCF is 0x06. So, this is a standard HCI command (HCI_Disconnect).

3.3. HCI event packet

The Bluetooth^® LE stack uses event packets to acknowledge a command or notify the user application that its status has been updated.

HCI event packet

3.4. HCI ACL data packet

ACL data packets are used to exchange data.

HCI ACL data packet

3.5. Vendor-specific commands

The vendor-specific (VS) commands can be either ACI commands to access the host of the Bluetooth^® LE stack, or HCI commands to access the LE controller. Both types use the 0x3F OGF value.

The OCF field of the OpCode of the VS commands is further divided into the following fields: command group ID and command ID.

OpCode format for VS commands

The OpCode format for VS commands figure above shows the 16-bit OpCode format (refer to HCI command packet format for more details). The OGF field value is always 0x3F for VS commands.

The 10-bit OCF field is split into two parts:

• 3-bit command group ID (CGID)
• 7-bit command ID (CID)

The CGID is used by the Bluetooth^® LE stack ACI interface to route the commands to different logical layers, such as L2CAP, GAP, or GATT. It also clears the VS command structure.

The CID determines the ID of each command. Each CGID group can have up to 128 VS commands.

CGID group
Command group Description CGID HCI HCI extension commands 0x0 GAP Generic access profile commands 0x1 GATT Generic attribute profile commands 0x2 L2CAP L2CAP commands 0x3 Reserved 0x4-0x7

The VS event also has a slightly different format than the standard HCI event (refer to HCI event packet for more details):

• The 8-bit event code of the VS event always has a 0xFF value.
• The 16-bit event parameter 0 has a different format.

Event parameter 0 format for VS events

The event parameter 0 is the first return parameter in the HCI event packets, following the parameter length field. These two bytes together are defined as the Bluetooth^® LE stack event code (ECODE). ECODE is further divided into two fields:

• Event group ID (EGIO)
• Event ID (EID)

The Bluetooth^® LE stack combines the events into logical groups using the EGID. The EID is used to specify an event in the group. The EGID occupies 6 bits in the ECODE field, while the EID occupies the remaining 10 bits.

EGID group
Event Group Description EGID HCI HCI extension events 0x0 GAP Generic access profile events 0x1 L2CAP L2CAP events 0x2 GATT Generic attribute profile events 0x3