UM2726
User manual
The BlueNRG-LP 2.4 GHz radio proprietary driver
This document describes the BlueNRG-LP 2.4 GHz radio proprietary low-level driver, which provides access to the BlueNRG-LP device in order to send and receive packets without using the Bluetooth link layer. An application using a central data structure and APIs can control different features of packets such as: interval, channel frequency, data length and so on.
UM2726 - Rev 2 - March 2021 |
www.st.com |
For further information contact your local STMicroelectronics sales office. |
|
|
|
UM2726
1BlueNRG-LP radio operation
The BlueNRG-LP 2.4 GHz radio low level driver interface controls 2.4 GHz radio. Furthermore, it interacts with the wake-up timer, which runs on the slow 32 kHz clock, the RAM memory and the processor.
RAM is used to store radio settings, the current radio status, the data received and data to be transmitted. The radio low level driver can manage up to 8 different radio configurations also called state machines.
Several features are autonomously managed by the radio, without intervention of the processor:
•Packet encryption
•Communication timing
•Sleep management
A number of additional features are present and they are specifically related to the Bluetooth low energy standard like the Bluetooth channel usage.
UM2726 - Rev 2 |
page 2/29 |
|
|
UM2726
2Data packet format
There is only one packet format used in the BlueNRG-LP, it is shown below.
Figure 1. Packet format
|
Preamble |
NetworkID |
Header |
Length |
Data |
CRC |
BlueNRG -LP |
1 byte |
4 bytes |
1 byte |
1 byte |
0 - 255 bytes |
3 bytes |
A packet consists of six fields which, only four are user-accessible:
•By default, the preamble is 1-byte long. But, the user can define how many times to repeat the preamble through RADIO_SetPreambleRep().
•NetworkID is the address of the device, expressed in 4 bytes. The receiver device accepts only those packets whose NetworkID field is the same as the one in its own address. The NetworkID should satisfy the following rules:
–It has no more than 6 consecutive zeros or ones
–It has not all 4 octets equal
–It has no more than 24 transitions
–It has a minimum of 2 transitions in the most significant 6 bits
The NetworkID field is user-accessible through API RADIO_SetTxAttributes() or API
HAL_RADIO_SetNetworkID().
•Header can accept any values and its length is 1 byte. It can be used as a byte of data, but no encryption is applied to this field.
•Length represents the length of the data field. The user sets this value for a packet to transmit or reads this value from a received packet.
The maximum number of bytes of the payload (with or without encryption) that the BlueNRG-LP link layer can accept in reception is 255. The user can set the value of this threshold (from 0 to 255) at hardware level through API RADIO_SetMaxRecievedLength().
Then, the maximum value of the length field is 255 for the BlueNRG-LP, with some exceptions. If the encryption is enabled, at the maximum length of the data field, it must subtract 4 bytes. These 4 bytes are reserved for the MIC field added to the packet as shown in Figure 2. Packet format with encryption enabled. Packet format with encryption enabled. The table below contains a summary about the length field.
Table 1. Values in bytes for the length field
|
Data channels |
Data channels with |
Advertising channels |
Advertising channels |
|
encryption |
with encryption |
||
|
|
|
||
|
|
|
|
|
BlueNRG-LP |
255 |
251 |
255 |
251 |
|
|
|
|
|
To avoid memory corruption due to bad length field received (in packet where the CRC check fails), the user must reserve the maximum memory for packet received that includes 2 bytes of header field as well as the data field
UM2726 - Rev 2 |
page 3/29 |
|
|
UM2726
Data packet format
•Data can accept any value and its length is decided by the length field. The user defines a memory buffer in order to set the header field, the length field and data field as follows:
PacketBuffer[0] = 0x01; // Header field
PacketBuffer[1] = 5; // Length field
PacketBuffer[2] = 0x02; // Data byte 1
PacketBuffer[3] = 0x03; // Data byte 2
PacketBuffer[4] = 0x04; // Data byte 3
PacketBuffer[5] = 0x05; // Data byte 4
PacketBuffer[6] = 0x06; // Data byte 5
If the encryption is enabled, only the data field is encrypted. The other fields including the header field and the length field are not encrypted.
•The CRC is used to identify corrupted packets. Its length is 3 bytes and the radio generates and checks it during transmission and reception respectively. The user can configure the initial value for the CRC
calculation, except in the advertising channels where the initial value is set to 0x555555. The CRC hardware feature can be disabled. It means that the hardware neither appends the CRC in transmission nor checks it during reception.
Figure 2. Packet format with encryption enabled
|
Preamble |
NetworkID |
Header |
Length |
Data |
MIC |
CRC |
BlueNRG-LP |
1 byte |
4 bytes |
1 byte |
1 byte |
0 - 251 bytes |
4 bytes |
3 bytes |
UM2726 - Rev 2 |
page 4/29 |
|
|
UM2726
3Radio low level driver framework
The radio low level driver consists of four files:
•bluenrg_lp_ll_radio.h
•bluenrg_lp_ll_radio.c
•bluenrg_lp_hal_radio.h
•bluenrg_lp_hal_radio.c
The radio low level driver interface provides a set of APIs (file bluenrg_lp_ll_radio.c) which allows the following functions to be addressed :
•Radio initialization
•Encryption
•Set receiver and transmitter Phy (1 Mbps, 2 Mbps, S = 2, S = 8)
•Communication channel management
•Set the network ID, CRC initial value, power level
•Set the maximum received packet length and the receive timeout
•Test commands (tone)
List of APIs managing these settings are:
•RADIO_Init()
•RADIO_SetEncryptionCount()
•RADIO_SetEncryptionAttributes()
•RADIO_SetEncryptFlags()
•RADIO_EncryptPlainData()
•RADIO_Set_ChannelMap()
•RADIO_SetChannel()
•RADIO_SetTxAttributes()
•RADIO_SetBackToBackTime()
•RADIO_SetTxPower()
•RADIO_SetReservedArea()
•RADIO_MakeActionPacketPending()
•RADIO_SetPhy()
•RADIO_SetMaxRecievedLength()
•RADIO_SetPreambleRep()
•RADIO_SetDefaultPreambleLen()
•RADIO_DisableCRC()
•RADIO_StopActivity()
•RADIO_StartTone()
•RADIO_StopTone()
Most of the APIs modify the parameters of the state machine passed as parameter. On the other hand, some parameters are global, that is they are valid for all the state machines. One of which is the receive timeout that is set calling RADIO_SetGlobalReceiveTimeout(). This value sets the duration of the receive window in microseconds.
The radio low level driver uses a central data structure that consists of a linked list of ActionPackets. An ActionPacket is a structure (C language) that, in conjunction with the APIs above, defines a complete operation of transmission or reception. It also includes a number of callbacks, which allow the user to define a chain of actions.
UM2726 - Rev 2 |
page 5/29 |
|
|
UM2726
API architecture
The ActionPacket is composed of input fields used to configure the action and output fields holding information on the action once it has been executed. The table below contains the information on these fields.
Table 2. ActionPacket structure
Parameter name |
Input/output |
Summary |
|
|
|
|
|
StateMachineNo |
IN |
This parameter indicates the state machine number for |
|
this action. From 0 to 7 |
|||
|
|
||
|
|
|
|
ActionTag |
IN |
The configuration of the current action. |
|
Details of the flags in the ActionTag table |
|||
|
|
||
|
|
|
|
MaxReceiveLength |
IN |
Set the maximum number of bytes that the link controller |
|
accepts in reception. It is between 0 and 255 byte |
|||
|
|
||
|
|
|
|
|
|
Contains the wake-up time in microseconds if it is |
|
WakeupTime |
IN |
relative. If it is absolute, the time is expressed in system |
|
time units (STU). More about STU can be found in the |
|||
|
|
||
|
|
BlueNRG-LP timer module application note |
|
|
|
|
|
*next_true |
IN |
Pointer to next ActionPacket if condRoutine() returns |
|
TRUE |
|||
|
|
||
|
|
|
|
*next_false |
IN |
Pointer to next ActionPacket if condRoutine() returns |
|
FALSE |
|||
|
|
||
|
|
|
|
(*condRoutine) |
IN |
User callback necessary to decide the next action in a |
|
(ActionPacket*) |
linked list of ActionPackets. The routine is time critical |
||
|
and it must end within 45 us. |
||
|
|
|
|
(*dataRoutine) |
IN |
User callback to manage data |
|
(ActionPacket*, ActionPacket*) |
|||
|
|
||
|
|
|
|
|
|
Pointer to the array with the data to send (header, length |
|
|
|
and data field), for TX. |
|
*data |
IN/OUT |
Pointer to the array where the data received are copied, |
|
|
|
for RX. In case of RX, the array must have the max. size |
|
|
|
as explained in Section 2 Data packet format |
|
|
|
|
|
|
|
This field contains the timestamp when a packet is |
|
|
|
received. It is intended to be used in the dataRoutine() |
|
timestamp_receive |
OUT |
callback routine. RX only. |
|
|
|
It is expressed in STU. One STU is 625/256 |
|
|
|
microseconds. |
|
|
|
|
|
status |
OUT |
The status register with the information on the action. |
|
|
|
|
|
rssi |
OUT |
The RSSI of the packet was received with. RX only. |
|
|
|
|
The ActionTag is a bitmask used to enable different features of the radio, used by the ActionPacket. The table below explains these parameters.
UM2726 - Rev 2 |
page 6/29 |
|
|
UM2726
API architecture
Table 3. ActionTag field description
Bit |
Name |
Description |
|
|
|
|
|
|
|
This bit sets where the position of the timestamp is taken, at |
|
|
|
the beginning of the packet or at the end of it. |
|
|
|
0: end of the packet, when the demodulator receives the last |
|
7 |
TIMESTAMP_POSITION |
bit of the packet received or when the last transmitted bit has |
|
|
|
been shifted out from the transmit block. |
|
|
|
1: beginning of the packet, when the demodulator detects the |
|
|
|
preamble + access address. Rx only |
|
|
|
|
|
|
|
This bit activates automatic channel increment. The API |
|
6 |
INC_CHAN |
RADIO_SetChannel()(1) sets the value of the increment. |
|
0: no increment |
|||
|
|
||
|
|
1: automatic increment |
|
|
|
|
|
|
|
It determines if the WakeupTime field of the ActionPacket is |
|
5 |
RELATIVE |
considered as absolute time or relative time to the current. |
|
0: absolute |
|||
|
|
||
|
|
1: relative |
|
|
|
|
|
|
|
This bit determines whether whitening is disabled or not |
|
4 |
WHITENING_DISABLE |
0: whitening enabled |
|
|
|
1: whitening disabled |
|
|
|
|
|
3 |
RESERVED |
RESERVED |
|
|
|
|
|
|
|
In the Radio handler, this bit determines if the action (RX or |
|
|
|
TX) is going to be executed based on the back-to-back time |
|
|
|
or based on the WakeupTime. |
|
2 |
TIMER_WAKEUP |
If it is the first action, this bit is ignored since it is going to be |
|
|
|
executed always based on the WakeupTime. |
|
|
|
0: based on the back-to-back time (default 150 µs). |
|
|
|
1: based on the WakeupTime |
|
|
|
|
|
|
|
This bit determines if the action is an RX action or a TX |
|
1 |
TXRX |
action. |
|
1: TX action |
|||
|
|
||
|
|
0: RX action |
|
|
|
|
|
|
|
This bit activates the radio frequency PLL calibration. |
|
0 |
PLL_TRIG |
0: radio frequency calibration disabled. |
|
1: radio frequency calibration enabled. |
|||
|
|
||
|
|
User should set this in the first action |
|
|
|
|
1. In the advertising channels, the frequency hopping is limited to 1 hop.
The bits of the status field of the ActionPacket represent the map of the interrupts triggered by the last radio action. A description of the status field of the ActionPacket is reported below. Refer to "the BlueNRG-LP radio controller" reference manual (RM0480) for the full details.
UM2726 - Rev 2 |
page 7/29 |
|
|
UM2726
API architecture
|
|
Table 4. Status_table |
|
|
|
|
|
Bit name |
Bit position |
Description |
|
|
|
|
|
RCVOK |
31 |
Receive data without errors. |
|
|
|
|
|
RCVCRCERR |
30 |
Receive data fail (CRC error). |
|
This error is raised only if at least preamble and access address have been detected. |
|||
|
|
||
|
|
|
|
TIMECAPTURETRIG |
29 |
Time captured in Time Capture register. |
|
|
|
|
|
RCVCMD |
28 |
Received command. |
|
|
|
|
|
RCVNOMD |
27 |
Received MD bit embedded in the PDU data packet header was zero. |
|
|
|
|
|
RCVTIMEOUT |
26 |
Receive timeout (no preamble found). |
|
|
|
|
|
DONE |
25 |
Receive/Transmit done. |
|
|
|
|
|
TXOK |
24 |
Previous transmitted packet received OK by the peer device. |
|
|
|
|
|
RCVLENGTHERROR |
18 |
The received payload length exceed the maximum. |
|
|
|
|
|
PREVTRANSMIT |
6 |
Previous event was a Transmission (1) or Reception (0). |
|
|
|
|
UM2726 - Rev 2 |
page 8/29 |
|
|
UM2726
4How to write an application
There are two ways to write an application: the former is based on the HAL layer composed mainly of four APIs, and the latter based on the use of the ActionPacket data structure.
The simplest way is to use a set of APIs provided in HAL radio driver (file bluenrg_lp_hal_radio.c), that allows the radio to be configured to fulfill the actions below:
•Send a packet
•Send a packet and then wait for the reception of a packet (ACK)
•Wait for a packet
•Wait for a packet and if the packet is received, a packet is sent back (ACK)
In this contest, the user does not need to use the ActionPacket to configure the operations of the radio, but a pointer to a user callback is requested, which handles different information according to the executed action:
•TX action: IRQ status
•RX action: IRQ status, RSSI, timestamp and data received
The user callback is called in interrupt mode, in particular in the BLE_TX_RX_IRQHandler(), that has the maximum priority.
The second parameter of each API is a relative time in microseconds that represents when the next radio activity starts from the moment in which the API is called. This delay must be big enough as otherwise it is not possible to program the radio timer and an error code is returned.
The user can choose the desired time without taking into account the time that the radio uses for its setup. Then, the delay that is passed to the API, represents when the first bit is transmitted or the receive window starts.
Figure 3. Relative time
|
|
TX or RX |
|
HAL_RADIO_API |
|||
|
start |
||
|
|
|
Relative Time
UM2726 - Rev 2 |
page 9/29 |
|
|