STM32WB0 Bluetooth® LE network and radio coprocessor framework

This wiki page presents the STM32WB0 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 STM32WB0 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 STM32WB0 Bluetooth^® LE network coprocessor and receive events from it.

Bluetooth LE network coprocessor (host and controller)

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

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

1.1. External microcontroller interface (UART or SPI)

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

• SPI slave 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 STM32WB0 device.

1.1.1. UART interface

The UART interface has the following characteristics:

• Baud rate: 921600
• 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: 1 MHz
• Data bits: 8
• Polarity: 1 (clock to 1 when idle)
• Phase: second edge
• Full duplex
• Slave 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 STM32WB0 series devices.

USART1 lines
STM32WB05 STM32WB07 STM32WB09 USART1 RX PB0 PA8 PB0 USART1 TX PA1 PA9 PA1

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

SPI lines
STM32WB05 STM32WB07 STM32WB09 SPI MOSI PA11 PA15 PA11 SPI MISO PA8 PA14 PA8 SPI Clock PB3 PA13 PB3 SPI CS PA9 PA11 PA9 SPI IRQ PA10 PA10 PA10

Information

STM32WB09 and STM32WB05 devices use the SPI3 bus, whereas STM32WB07 devices use the SPI1 bus.

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

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

It provides a reference software framework for the STM32U5 external microcontroller connected to an X-NUCLEO-WB05KN1 board, which includes an STM32WB05KN device. STM32Cube makes the framework easily portable across different MCU families.

The UART and SPI protocol implementation provided with the X-CUBE-WB05N software package is designed to work with any STM32WB0 series device configured as a network or radio coprocessor.

Refer to the X-CUBE-WB05N software package wiki page for more information on how to build a Bluetooth^® LE application within the provided STM32U5 Bluetooth^® LE network/radio coprocessor framework provided with this package.

1.2.1. BLE_TransparentMode application configuration

On STM32WB0 series devices, users can configure the device as a network coprocessor (NCP) by using the BLE_TransparentMode application, available in the STM32CubeWB0 MCU Package. They can customize it using the Bluetooth^® LE stack v4.x modular configuration options to select the required set of Bluetooth^® LE features.

The BLE_TransparentMode application for network coprocessor configuration is built on top of the STMicroelectronics Bluetooth^® LE stack binary image (stm32wb0x_ble_stack.a), provided with the STM32CubeWB0 MCU Package.

Due to differing flash and RAM memory layouts on the different STM32WB0 series devices, the BLE_TransparentMode application provided with the STM32CubeWB0 MCU Package comes with different sets of Bluetooth^® LE features, such as data length extension and extended advertising, and stack initialization parameters, such as the number of radio tasks, for each device (STM32WB05, STM32WB07, and STM32WB09).

The Bluetooth^® LE features are enabled or disabled through the STMicroelectronics Bluetooth^® LE stack v4.x modular configuration options and can also be customized by the user.

Two variants of the BLE_TransparentMode application are available:

• The BLE_TransparentMode application supports the UART interface.
• The BLE_TransparentMode_SPI application supports the SPI interface.

STMicroelectronics Bluetooth® LE stack v4.x modular configuration options

Notes:

• The Bluetooth^® LE stack v4.x modular configuration options and initialization parameters are defined in the app_conf.h file, available in the BLE_TransparentMode application folder of the STM32CubeWB0 MCU Package.
  The number of supported simultaneous radio tasks (CFG_NUM_RADIO_TASKS) is defined in the stm32wb0x_hal_conf.h file, available in the BLE_TransparentMode application folder of the STM32CubeWB0 MCU Package.
• The BLE_TransparentMode application for radio coprocessor (RCP) configuration is built on top of the STMicroelectronics Bluetooth^® LE controller-only binary image file (stm32wb0x_ble_stack_controller_only.a), provided with the STM32CubeWB0 MCU Package.

The referenced BLE_TransparentMode projects to be used for network and radio coprocessor configuration are available in the STM32CubeWB0 MCU Package, in the Projects\{NUCLEO-WB05KZ|NUCLEO-WB07CC|NUCLEO-WB09KE}\Applications\BLE folder:

• BLE_TransparentMode_UART_for_Updater: UART mode (location, essential configuration); this application requires the BLE_TransparentMode_UART_Updater to be loaded first.
• BLE_TransparentMode_UART_for_Updater_C_O: UART mode (controller-only configuration); this application requires the BLE_TransparentMode_UART_Updater to be loaded first.
• BLE_TransparentMode_SPI_for_Updater: SPI mode (location, essential configuration); this application requires the BLE_TransparentMode_SPI_Updater to be loaded first.
• BLE_TransparentMode_SPI_for_Updater_C_O: SPI mode (controller-only configuration); this application requires the BLE_TransparentMode_SPI_Updater to be loaded first.

Refer to the Bluetooth^® LE stack v4.x programming guidelines (PM0274) for more information about the STMicroelectronics Bluetooth^® LE stack v4.x modular configuration options and initialization parameters.

2. SPI protocol

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

• Power efficiency
• Code efficiency
• Fast data transfer

2.1. Hardware details

The SPI protocol requires five pins:

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

The adopted timing diagram is CPOL 1 and CPHA 1, meaning that data are captured on the rising edge of the SPI clock and output on a rising edge.

The SPI CS pin also acts as a wake-up pin for the STM32WB0 series device. If the SPI CS pin is low (external MCU selects the STM32WB0 series device for communication), the STM32WB0 series device wakes up if it was asleep.

The STM32WB0 series device notifies pending events to the external microcontroller through the SPI IRQ pin. If the SPI IRQ pin is high, the STM32WB0 series device has at least one event for the external microcontroller.

STM32WB05xZ SPI lines

STM32WB06xC/STM32WB07xC SPI lines

STM32WB09xE SPI lines

2.2. SPI communication protocol

This section describes how to format the data on the SPI to enable communication with STM32WB0 series devices. An SPI transaction is defined from a rising edge of the SPI CS signal to the next rising edge of the SPI CS signal. Each SPI transaction must include only one data frame. Each data frame must contain a header of at least five bytes and 0 to N bytes of data.

Generic SPI transaction

The figure above shows a generic SPI transaction, which consists of the following steps:

• The external microcontroller lowers the SPI CS signal to initiate communication.
• The STM32WB0 series device raises the SPI IRQ signal to indicate readiness for communication. The time t1 varies depending on the state of the STM32WB0 series device. t1 may include the wake-up of the STM32WB0 series device and preparation of the header part of the frame.
• The external microcontroller must wait for the SPI IRQ signal to go high and then transfer the five header bytes, including the control field with the intended operation. Additionally, the external microcontroller reads five bytes from the STM32WB0 series device, which includes information about the actual size of the read and write buffers.
• The external microcontroller performs the data transaction after checking the five header bytes.
• The STM32WB0 device lowers the SPI IRQ signal when the header bytes have been transferred.
• The external microcontroller waits until the SPI IRQ signal is low before raising the SPI CS signal to mark the end of the communication.

Notes:

• Setting the SPI CS signal low wakes up the STM32WB0 device if it was asleep.
• If the SPI IRQ signal is low before setting the SPI CS signal low, the STM32WB0 device has no data events for the external microcontroller, so the read buffer size is zero (RBUF=0).
• The time t1 is the time between wake-up (point a in the Generic SPI transaction figure) and when the STM32WB0 device is ready to execute the SPI transaction (point b in the Generic SPI transaction figure). The time t1 ranges from minimal value (the STM32WB0 series device already awake when the SPI CS is asserted), to a maximum value that involves a wake-up sequence and software boot.
• Even if there are events pending after the completion of the transaction, the SPI IRQ signal goes low to allow the STM32WB0 device to update the five header bytes and rearm the SPI for the next transaction (after this delay the SPI IRQ signal goes high again if events are pending).
• The SPI CS signal marks the start and end of the transaction
• The SPI CS high marks the end of the transaction and must be set to high only when the SPI IRQ signal is low.
• The gap between the header and the data is not mandatory, but it is normally required by the external microcontroller to process the header and check if there is enough space in the buffers to perform the transaction.
• When the SPI IRQ signal is high, the five header bytes are locked and cannot be modified by the STM32WB0 device firmware.

2.2.1. SPI header

SPI header format

The header of the external microcontroller (the SPI master) is on the MOSI line. It consists of one control byte (CTRL) and four 0x00 bytes. The CTRL field can have only the following values: 0x0A (SPI write) or 0x0B (SPI read).

The STM32WB0 device returns the header on the MISO line simultaneously. When the STM32WB0 device asserts the SPI IRQ signal, it is ready. Otherwise, the STM32WB0 device remains uninitialized. The external microcontroller must wait for the IRQ signal to go high and perform a five-byte transaction. The five bytes on the MISO line consist of one byte for the starting frame, two bytes indicating the size of the write buffer (WBUF), and two bytes indicating the size of the read buffer (RBUF). The endianness for WBUF and RBUF is LSB first. The value in WBUF indicates how many bytes the master can write to the STM32WB0 device. The value in RBUF indicates how many bytes in the STM32WB0 series device are waiting to be read by the external microcontroller.

2.2.2. SPI read transaction

A read transaction occurs when the STM32WB0 device raises the SPI IRQ signal before the SPI CS signal is lowered by the external microcontroller.

SPI read transaction

The SPI IRQ signal is high, indicating that the STM32WB0 device is awake and ready to perform the SPI transaction, after a hardware-dependent setup time, t2, with a typical value of 1.5 µs. The transaction is performed as follows:

1. An event is generated by the STM32WB0 series device (point a in the SPI read transaction figure).
2. The external microcontroller lowers the SPI CS signal to initiate a transaction (point b in the SPI read transaction figure).
3. While the SPI IRQ signal is high, the external microcontroller initiates a data transfer after t2. The external microcontroller transfers five bytes as follows: [0x0B, XX, XX, XX, XX]. The WBUF and RBUF sizes are read from the SPI MISO signal.
4. The external microcontroller performs the read data transaction for RBUF bytes. (Note: If RBUF is 0, it is an unexpected condition as the STM32WB0 device indicates that data is available. The transaction must be completed by reading no bytes).
5. The STM32WB0 device lowers the SPI IRQ signal after the five header bytes are transferred.
6. The external microcontroller raises the SPI CS signal to mark the end of the transaction.

2.2.3. SPI write transaction

The external microcontroller performs a write transaction to send a command to the STM32WB0 device. The STM32WB0 device can be awake or asleep when the SPI CS signal is lowered by the external microcontroller. The assertion of the SPI CS signal wakes up the device, if it was asleep.

SPI write transaction

The transaction is performed as follows:

1. The external microcontroller lowers the SPI CS signal to initiate a transaction.
2. The STM32WB0 device raises the SPI IRQ signal to indicate that it is ready, with t1 >= 0.
3. The external microcontroller waits for the SPI IRQ signal to go high and starts a transfer of five bytes, sending the code of the intended operation and reading the read buffer and write buffer size. The external microcontroller transfers five bytes as follows: [0x0A, XX, XX, XX, XX]. The WBUF and RBUF values are sampled in the SPI MISO signal.
4. The STM32WB0 device lowers the SPI IRQ signal after the five header bytes are transferred.
5. The external microcontroller checks whether the WBUF can send the command. If so, it performs the data transaction; otherwise the external microcontroller must wait.
6. The external microcontroller waits for the SPI IRQ signal to be low before closing the communication.
7. The external microcontroller raises the SPI CS to mark the end of the transaction.

2.2.4. SPI error transaction

The STM32WB0 device firmware presents the following behavior when error transactions occur:

• Incomplete header transaction (0 to 4): the device ignores the transaction.
• The external microcontroller does not wait for the SPI IRQ signal to go low before raising the SPI CS signal: the device lowers the SPI IRQ signal when the SPI CS signal is high.
• The external microcontroller does not wait for the SPI IRQ signal to go high before starting the SPI clock: on both sides, master and slave, the data are corrupted.
• Incomplete read transaction: the master loses the event.
• Incomplete write transaction: the device stores the bytes written by the external microcontroller. During the next write operation, it receives the new bytes and attempts to complete the frame, following Bluetooth^® protocol.
• Two commands in a row without a reading event command: the device parses the two commands and generates the corresponding events.

2.2.5. SPI state machine

The figure and table below describe the STM32WB0 series device SPI state machine and related states.

SPI state machine

SPI state machine states

2.2.6. External microcontroller behavior

The external microcontroller must act as follows according to the information from the STM32WB0 device:

• SPI IRQ signal
• Information from WBUF and RBUF header frames

SPI input from STM32WB0

The figure below describes the expected SPI protocol state machine on the external microcontroller:

Expected SPI protocol state machine on external microcontroller

3. STM32WB0 series Bluetooth^® LE stack v4.x ACI

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

3.1. ACI commands data format

The Bluetooth^® LE stack v4.x ACI commands use and extend 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)
• HCI extended command (packet type: 0x81)
• HCI extended event (packet type: 0x82)

The STM32WB0 Bluetooth^® LE stack v4.x does not support the HCI synchronous data packet.

3.2. HCI command packet format

When an external device sends a command to the Bluetooth^® LE stack v4x, 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
Groupe 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 v4.x 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. HCI extended command packet format

The Bluetooth^® LE stack v4.x HCI extended command packet format is similar to the HCI extended command packet. It includes a total length field parameter size of two bytes.

3.6. HCI extended event packet

The Bluetooth^® LE stack v4.x HCI extended event packet format is similar to the HCI extended event packet. It includes a total length field parameter size of two bytes.

3.7. Vendor-specific commands

The vendor-specific (VS) commands can be either ACI commands to access the host of the Bluetooth^® LE stack v4.x, 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 croup 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 v4.x 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 Genericaccess 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 v4.x event code (ECODE). ECODE is further divided into two fields:

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

The Bluetooth^® LE stack v4.x 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 commands 0x1 L2CAP L2CAP events 0x2 GATT Generic attribute profile events 0x3

4. Hardware configuration parameters

When defining a specific application or printed circuit board (PCB) for targeting a STM32WB0 device network or radio coprocessor framework to achieve the maximum performance, users can select specific hardware configurations, such as LSE, LSI, or SMPS (on or off). Certain procedures must be completed before finalizing and defining the required hardware parameter values, as these can affect device performance:

• Select LSE (external 32-kHz crystal) or internal RO during the system clock configuration initialization (RCC IP initialization procedure).
• Define the correct value of the HSE capacitor to center the HSE frequency (CFG_HW_RCC_HSE_CAPACITOR_TUNE value in the stm32wb0x_hal_conf.h file).
• Define the optimal HSE start-up time to optimize current consumption (RADIO_TIMER_InitStruct.XTAL_StartupTime parameter value of the MX_RADIO_TIMER_Init() function in the main.c file).
• Select SMPS configurations using specific preprocessor options in the system_stm32wb0x.c file:
  • Hardware configuration (on, off, or bypass) through the CFG_HW_SMPS preprocessor option (possible values: SMPS_ON, SMPS_OFF, and SMPS_BYPASS).
  • Supported BOM/inductor value through the CFG_HW_SMPS_BOM preprocessor option (possible values: SMPS_BOM1, SMPS_BOM2, and SMPS_BOM3).
  • Low-power configuration through the CFG_HW_SMPS_LOW_POWER preprocessor option (possible values: SMPS_LOW_POWER_OPEN and SMPS_LOW_POWER_NO_OPEN).

Note: The default SMPS preprocessor options values for CFG_HW_SMPS, CFG_HW_SMPS_BOM, and CFG_HW_SMPS_LOW_POWER are, respectively, SMPS_ON, SMPS_BOM3, and SMPS_LOW_POWER_OPEN.

Refer to the STM32WB05xN Bluetooth^® LE network and radio coprocessor framework and hardware configurations wiki page for detailed information about:

• Hardware requirements to perform the measurements mentioned above.
• Settings to consider and how to estimate them.
• Generating a BLE_TransparentMode network or radio processor binary image with updated setting values.