UM2726
User manual
The BlueNRG-LP 2.4 GHz radio proprietary driver
Introduction
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 dif
ferent features of packets such as: interval, channel frequency, data length and so on.
UM2726 - Rev 2 - March 2021
For further information contact your local STMicroelectronics sales office.
www
.st.com
1 BlueNRG-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 dif
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.
ferent radio configurations also called state machines.
UM2726
BlueNRG-LP radio operation
UM2726 - Rev 2
page 2/29
2 Data packet format
Preamble
NetworkID
Header
Data CRC
BlueNRG-LP
1 byte 4 bytes 1 byte
0 - 255 bytes
3 bytes
Length
1 byte
There is only one packet format used in the BlueNRG-LP, it is shown below.
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.
UM2726
Data packet format
Figure 1. Packet format
UM2726 - Rev 2
Data channels
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
Table 1. Values in bytes for the length field
Data channels with
encryption
Advertising channels
Advertising channels
with encryption
page 3/29
Preamble
NetworkID
Header
Data CRC
BlueNRG-LP 1 byte 4 bytes 1 byte
0 - 251 bytes
3 bytes
Length
1 byte
MIC
4 bytes
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
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
. The user can configure the initial value for the CRC
UM2726 - Rev 2
page 4/29
3 Radio low level driver framework
3.1 Description
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
3.2 API architecture
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
Radio low level driver framework
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.
Parameter name Input/output Summary
StateMachineNo IN
ActionTag IN
MaxReceiveLength IN
W
akeupTime IN
*next_true IN
*next_false IN
(*condRoutine)
(ActionPacket*)
(*dataRoutine)
(ActionPacket*, ActionPacket*)
*data IN/OUT
timestamp_receive OUT
status OUT The status register with the information on the action.
rssi OUT The RSSI of the packet was received with. RX only
ActionPacket structure
This parameter indicates the state machine number for
this action. From 0 to 7
The configuration of the current action.
Details of the flags in the ActionTag table
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
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
Pointer to next ActionPacket if condRoutine() returns
TRUE
Pointer to next ActionPacket if condRoutine() returns
F
ALSE
IN
IN User callback to manage data
User callback necessary to decide the next action in a
linked list of ActionPackets. The routine is time critical
and it must end within 45 us.
Pointer to the array with the data to send (header
and data field), for TX.
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()
callback routine. RX only
It is expressed in STU. One STU is 625/256
microseconds.
, length
.
.
UM2726 - Rev 2
The ActionTag is a bitmask used to enable different features of the radio, used by the ActionPacket. The table
below explains these parameters.
page 6/29
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.
7 TIMESTAMP_POSITION
6 INC_CHAN
5 RELATIVE
4 WHITENING_DISABLE
3 RESERVED RESERVED
2 TIMER_WAKEUP
1 TXRX
0 PLL_TRIG
1. In the advertising channels, the frequency hopping is limited to 1 hop.
0: end of the packet, when the demodulator receives the last
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
RADIO_SetChannel()
0: no increment
1: automatic increment
It determines if the WakeupTime field of the ActionPacket is
considered as absolute time or relative time to the current.
0: absolute
1: relative
This bit determines whether whitening is disabled or not
0: whitening enabled
1: whitening disabled
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 W
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
action.
1: TX action
0: RX action
This bit activates the radio frequency PLL calibration.
0: radio frequency calibration disabled.
1: radio frequency calibration enabled.
User should set this in the first action
(1)
sets the value of the increment.
ime.
akeupT
UM2726
API architecture
UM2726 - Rev 2
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.
page 7/29
Table 4. Status_table
Bit name Bit position Description
RCVOK 31 Receive data without errors.
RCVCRCERR 30
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).
This error is raised only if at least preamble and access address have been detected.
Receive data fail (CRC error).
UM2726
API architecture
UM2726 - Rev 2
page 8/29
4 How to write an application
HAL_RADIO_API
Relative Time
TX or RX
start
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.
4.1 HAL layer approach
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.
UM2726
How to write an application
Figure 3. Relative time
UM2726 - Rev 2
page 9/29
4.2 TX example with HAL layer
Below is an example where the radio is programmed to send a packet periodically, with a time between two
consecutive packets of 10 ms. Each packet contains 3 bytes of data.
Note: The radio initialization is followed by the timer module initialization.
The ActionPacket structure is not used directly in this example, but it is used through the APIs of the HAL layer.
uint8_t send_packet_flag = 1;
uint8_t packet[5];
int main(void)
{
HAL_VTIMER_InitType VTIMER_InitStruct = {HS_STARTUP_TIME, INITIAL_CALIBRATION,
CALIBRATION_INTERVAL};
/* System initialization function */
if (SystemInit(SYSCLK_64M, BLE_SYSCLK_32M) != SUCCESS) {
/* Error during system clock configuration take appropriate action */
while(1);
}
/* Radio configuration*/
RADIO_Init();
/* Timer Init */
HAL_VTIMER_Init(&VTIMER_InitStruct);
/* Set the Network ID */
HAL_RADIO_SetNetworkID(0x88DF88DF);
/* Set the RF output power at max level */
RADIO_SetTxPower(MAX_OUTPUT_RF_POWER);
packet[0] = 1; /* Header field */
packet[1] = 3; /* Length field */
packet[2] = 2; /* Data */
packet[3] = 3;
packet[4] = 4;
while(1) {
HAL_VTIMER_Tick();
/* If ready, a new action is scheduled */
if(send_packet_flag == 1) {
send_packet_flag = 0;
/* Schedule the action with the parameter - channel, wakeupTime, data,
dataCallback */
HAL_RADIO_SendPacket(22, 10000, packet, TxCallback );
}
}
return 0;
}
void BLE_TX_RX_IRQHandler(void)
{
RADIO_IRQHandler();
}
UM2726
TX example with HAL layer
UM2726 - Rev 2
The user callback, TxCallback(), is defined in order to re-schedule another send packet action as follows:
uint8_t TxCallback(ActionPacket* p, ActionPacket* next)
{
/* Check if the TX action is ended */
if( p ->status & BLUE_STATUSREG_PREVTRANSMIT) != 0) {
/* Triggers the next transmission */
send_packet_flag = 1;
}
return TRUE;
}
page 10/29
4.3 RX example with HAL layer
Below is an example where the radio is programmed to go to RX state periodically. The delay between each RX
operation is 9 ms. This ensures that after the first good reception, the RX device wakes up always 1 ms before
the TX device (configured in Section 4.2 TX example with HAL layer) starts to send the packet (guard time).
Note: The maximum length of the payload is set to 255 bytes.
The RX timeout is 20 ms. This value is big enough to ensure that at least one packet should be received.
The ActionPacket structure is not used directly in this example, but it is used through the APIs of the HAL layer.
uint8_t rx_flag = 1;
uint8_t packet[MAX_PACKET_LENGTH];
int main(void)
{
HAL_VTIMER_InitType VTIMER_InitStruct = {HS_STARTUP_TIME, INITIAL_CALIBRATION,
CALIBRATION_INTERVAL};
/* System initialization function */
if (SystemInit(SYSCLK_64M, BLE_SYSCLK_32M) != SUCCESS) {
/* Error during system clock configuration take appropriate action */
while(1);
}
/* Radio configuration*/
RADIO_Init();
/* Timer Init */
HAL_VTIMER_Init(&VTIMER_InitStruct);
/* Set the Network ID */
HAL_RADIO_SetNetworkID(0x88DF88DF);
UM2726
RX example with HAL layer
while(1) {
HAL_VTIMER_Tick();
/* If ready, a new action is scheduled */
if(rx_flag == 1) {
rx_flag = 0;
/* Schedule the action with the parameter – channel, wakeupTime,
receive buffer, receive timeout, max received length, dataCallback */
HAL_RADIO_ReceivePacket ( 22, 9000, packet, 20000, 255, RxCallback );
}
}
return 0;
}
void BLE_TX_RX_IRQHandler(void)
{
RADIO_IRQHandler();
}
The user callback, RxCallback(), is defined in order to re-schedule another reception and retrieve the information
if a packet has been received as follows:
UM2726 - Rev 2
page 11/29
ActionPacket approach
uint8_t RxCallback(ActionPacket* p, ActionPacket* next)
{
/* Check if the RX action is ended */
if( (p->status & BLUE_STATUSREG_PREVTRANSMIT) == 0) {
/* Check if a packet with a valid CRC is received */
if((p->status & BLUE_INTERRUPT1REG_RCVOK) != 0) {
/* Retrieve the information from the packet */
// p->data contains the data received: header field | length field | data field
// p->rssi
// p->timestamp_receive
}
/* Check if a RX timeout occurred */
else if( (p->status & BLUE_INTERRUPT1REG_RCVTIMEOUT) != 0) {
}
/* Check if a CRC error occurred */
else if ((p->status & BLUE_INTERRUPT1REG_RCVCRCERR) != 0) {
}
}
/* Triggers the next reception */
rx_flag = 1;
return TRUE;
}
UM2726
4.4 ActionPacket approach
The most flexible way is to declare a number of ActionPackets, according to the actions that must be taken
by the radio. Then the user fills these structures with the description of the operations to execute. For each
ActionPacket, the API RADIO_SetReservedArea() must be called in order to initialize the information of the
ActionPacket itself.
To start the execution of an ActionPacket, the API RADIO_MakeActionPacketPending() has to be called. After
this, the application could:
Make sure that another ActionPacket is called, by linking the ActionPackets together and then decide which
•
ActionPacket executes within the condition routine.
• Reactivate the radio execution by calling again the API RADIO_MakeActionPacketPending().
All further actions are handled in interrupt mode as for the HAL layer approach, but in this case, the user handles
two callback functions:
• Condition routine: condRoutine()
It provides the result of the current ActionPacket, and it returns TRUE or FALSE. Depending on this, the next
ActionPacket linked to the current one is selected from two possibilities:
– next_true ActionPacket1
– next_false ActionPacket2
The purpose of this mechanism is to differentiate the next action of the scheduler. For example the condition
routine in an RX action can decide:
– To schedule the next_true ActionPacket, if the packet received is good (ActionPacket1)
– To schedule the next_false ActionPacket, if the packet received is not good (ActionPacket2)
• Data routine: dataRoutine()
It provides information as data received or transmitted, RSSI, timestamps and others. Besides, it is intended
to modify the transmit data for the next packet based upon the last received data. This could be used to
modify the packet data to be sent.
The goal of the multiple callbacks is to enable the user to access to the total performance of the radio, by avoiding
time criticality bottlenecks. The goal is to bundle time critical aspects in the condition routine, and have the rest of
the framework to be non-time-critical.
One benefit is that the framework forces the user to split code over smaller routines, which leads to more
structured programming.
The most time critical operations are performed in the condRoutine(). Here the next activity is chosen according
to some criteria and then patched on the fly. It is obvious that this must occur before the radio controller starts its
operation, otherwise the patch is ignored.
UM2726 - Rev 2
page 12/29
Back-to-back time
(150 µs)
~80 µs ~70 µs
1
2
Current Action Packet
Next Action Packet
UM2726
TX example with ActionPacket
The maximum execution time of the condition routine is about the back-to-back time less the time that the radio
spends for the RF setup. For the moment, it can be considered that the radio in a back-to-back scenario needs 70
µs to set up. Then if the back-to-back time is 150 µs, the condRoutine() has about 80 µs to set the pointer to the
next activity.
Therefore, the dataRoutine() has about the remaining time to modify, for example, the data to send.
The figure below summarizes the timing of the dif
1: before this time, the condition routine must end.
2: before this time, the updating of the next packet must be completed.
ferent callbacks.
Figure 4. Callback timing
4.5 TX example with ActionPacket
Below is an example where the radio is programmed to send a packet periodically, with a time between two
consecutive packets of 10 ms. Each packet contains 3 bytes of data. The ActionPacket structure is used to define
this operation.
UM2726 - Rev 2
page 13/29
TX example with ActionPacket
int8_t packet[5];
ActionPacket txAction;
int main(void)
{
HAL_VTIMER_InitType VTIMER_InitStruct =
{HS_STARTUP_TIME, INITIAL_CALIBRATION,
CALIBRATION_INTERVAL};
/* System initialization function */
if (SystemInit(SYSCLK_64M, BLE_SYSCLK_32M)!=SUCCESS) {
/* Error during system clock configuration take appropriate action */
while(1);
}
/* Radio configuration*/
RADIO_Init();
/* Timer Init */
HAL_VTIMER_Init(&VTIMER_InitStruct);
/* Set the channel (22) and the channel increment (0) */
RADIO_SetChannel(STATE_MACHINE_0, 22, 0);
/* Sets of the Network ID and the CRC initial value */
RADIO_SetTxAttributes(STATE_MACHINE_0,0x88DF88DF, 0x555555);
/* Set the RF output power at max level */
RADIO_SetTxPower(MAX_OUTPUT_RF_POWER);
packet[0] = 1; /* Header field */
packet[1] = 3; /* Length field */
packet[2] = 2; /* Data */
packet[3] = 3;
packet[4] = 4;
/* Builds ActionPacket (txAction) for sending a
single packet and schedules
the next ActionPacket as itself (txAction) */
txAction.StateMachineNo = STATE_MACHINE_0;
/* Make a TX action with time relative to Wakeup
Timer and enable the PLL calibration */
txAction.ActionTag = RELATIVE | TIMER_WAKEUP | TXRX |
PLL_TRIG;
/* 10 ms before operation */
txAction.WakeupTime = 10000;
/* Pointer to the data to send */
txAction.data = packet;
/* Pointer to next ActionPacket: txAction */
txAction.next_true = &txAction;
/* Do nothing */
txAction.next_false = NULL_0;
/* Condition routine for selecting next ActionPacket*/
txAction.condRoutine = conditionRoutine;
/* Data routine called after conditionRoutine */
txAction.dataRoutine = dataRoutine;
/* Records the ActionPacket information */
RADIO_SetReservedArea(&txAction);
/* Execute the ActionPacket */
RADIO_MakeActionPacketPending(&txAction);
while(1) {
HAL_VTIMER_Tick();
}
return 0;
}
UM2726
UM2726 - Rev 2
void BLE_TX_RX_IRQHandler(void)
{
RADIO_IRQHandler();
}
The condition callback triggers the execution of next scheduled ActionPacket (txAction), while the data callback is
not used in this case, but must be defined anyway
.
page 14/29
uint8_t conditionRoutine(ActionPacket* p)
{
/* Check if the TX action is ended */
if( p ->status & BLUE_STATUSREG_PREVTRANSMIT) != 0) {
}
/* The TRUE schedules the next_true action: txAction */
return TRUE;
}
uint8_t dataRoutine(ActionPacket* p, ActionPacket* next)
{
return TRUE;
}
4.6 RX example with ActionPacket
Below is an example where the radio is programmed to go to RX state periodically. The delay between each RX
operation is 9 ms. This ensures that after the first good reception, the RX device wakes up always 1 ms before
the TX device (configured in Section 4.5 TX example with ActionPacket) starts to send the packet (guard time).
The RX timeout is 20 ms. This value is big enough to ensure that at least one packet should be received.
The ActionPacket structure is used to define this operation.
UM2726
RX example with ActionPacket
UM2726 - Rev 2
page 15/29
UM2726
RX example with ActionPacket
ActionPacket rxAction;
int main(void)
{
HAL_VTIMER_InitType VTIMER_InitStruct =
{HS_STARTUP_TIME, INITIAL_CALIBRATION,
CALIBRATION_INTERVAL};
if (SystemInit(SYSCLK_64M,BLE_SYSCLK_32M)!= SUCCESS) {
/* Error during system clock configuration
take appropriate action */
while(1);
}
/* Radio configuration*/
RADIO_Init();
/* Timer Init */
HAL_VTIMER_Init(&VTIMER_InitStruct);
/* Set the channel (22) and the channel increment (0) */
RADIO_SetChannel(STATE_MACHINE_0, 22, 0);
/* Sets of the Network ID and the CRC initial value */
/* RX timeout 20 ms*/
RADIO_SetGlobalReceiveTimeout(20000);
rxAction. MaxReceiveLength = 255;
RADIO_SetTxAttributes(STATE_MACHINE_0, 0x88DF88DF, 0x555555);
/* Builds ActionPacket (rxAction) to make a reception and schedules
the next ActionPacket at itself (rxAction) */
rxAction.StateMachineNo = STATE_MACHINE_0;
/* Make a RX action with time relative to Wakeup Timer and enable the PLL calibration */
rxAction.ActionTag = RELATIVE | TIMER_WAKEUP | PLL_TRIG;
/* 9 ms before operation */
rxAction.WakeupTime = 9000;
/* Pointer to the array where the data are received */
rxAction.data = packet;
/* Pointer to next ActionPacket: rxAction */
rxAction.next_true = &rxAction;
/* Do nothing */
rxAction.next_false = NULL_0;
/* Condition routine for selecting next ActionPacket*/
rxAction.condRoutine = conditionRoutine;
/* Data routine called after conditionRoutine : RSSI, RX timestamps,
data received or data modification before next transmission*/
rxAction.dataRoutine = dataRoutine;
/* Records the ActionPacket information */
RADIO_SetReservedArea(&rxAction);
/* Execute the ActionPacket */
RADIO_MakeActionPacketPending(&rxAction);
while(1) {
HAL_VTIMER_Tick();
}
return 0;
}
void BLE_TX_RX_IRQHandler(void)
{
RADIO_IRQHandler();
}
UM2726 - Rev 2
The condition callback triggers the execution of next scheduled ActionPacket (rxAction), while the data callback is
not used in this case, but must be defined anyway
.
page 16/29
RX example with ActionPacket
uint8_t conditionRoutine(ActionPacket* p)
{
/* Check if the RX action is ended */
if( (p->status & BLUE_STATUSREG_PREVTRANSMIT) == 0) {
/* Check if a packet with a valid CRC is received */
if((p->status & BLUE_STATUSREG_RCVOK) != 0) {
}
/* Check if a RX timeout occurred */
else if( (p->status & BLUE_INTERRUPT1REG_RCVTIMEOUT) != 0) {
}
/* Check if a CRC error occurred */
else if ((p->status & BLUE_INTERRUPT1REG_RCVCRCERR) != 0) {
}
}
/* Triggers the next reception */
return TRUE;
}
uint8_t dataRoutine(ActionPacket* p, ActionPacket* next)
{
/* Check if the RX action is ended */
if( (p->status & BLUE_STATUSREG_PREVTRANSMIT) == 0) {
/* Check if a packet with a valid CRC is received */
if((p->status & BLUE_STATUSREG_RCVOK) != 0) {
/* Retrieve the information from the packet */
// p->data contains the data received: header field | length field | data field
// p->rssi
// p->timestamp_receive
}
/* Check if a RX timeout occurred */
else if( (p->status & BLUE_INTERRUPT1REG_RCVTIMEOUT) != 0) {
}
/* Check if a CRC error occurred */
else if ((p->status & BLUE_INTERRUPT1REG_RCVCRCERR) != 0) {
}
}
return TRUE;
}
UM2726
UM2726 - Rev 2
page 17/29
OTA
CONNECTION
YMODEM
SIZE
YMODEM
LOAD
OTA
SIZE
OTA
START
OTA
DATAREQ
OTA
SENDATA
YMODEM
CLOSE
OTA
COMPLETE
(3)
(3)
(6)
(1)
(1)
(2)
YMODEM
WAIT
(9)
(6)
(3)
(4)
(2)
(4)
(4)
(7)
(8)
(7)
(5)
(1) Wait for a valid YMODEM communication
(2) Get valid YMODEM data
(3) Wait for a valid ACK response
(4) Valid ACK received
(5) Valid ACK received on last data packet
(6) Wait for valid data
(7) Valid data received
(8) Still data needed from YMODEM
(9) The entire binary file has been received
The BlueNRG-LP proprietary over-the-air (OTA) firmware
5 The BlueNRG-LP proprietary over-the-air (OTA) firmware
This section describes the BlueNRG-LP proprietary over-the-air (OTA) firmware upgrade based on the radio
low-level driver, which provides access to the BlueNRG-LP devices in order to send and receive packets without
using the Bluetooth link layer
This section describes two roles: server and client.
The former node is in charge of sending over-the-air a binary image to the client node.
The latter node acts as a reset manager program choosing, which application to run: the OTA client application
that communicates with the server node in order to get the binary image and update its Flash memory with it; or
the application loaded previously (with OTA or in another way).
5.1 OTA server application
The OTA server application is in charge of sending over-the-air a binary image to the client node. The image is
acquired through the UAR
The server state machine is implemented by using two state machine routines:
A state machine dedicated to the YMODEM protocol
•
• A state machine dedicated to the OTA protocol
A token is used to decide which state machine runs.
.
T port by using the YMODEM communication protocol.
UM2726
5.1.1 OTA server state machine
The following diagram shows the state machine implemented for the OTA server node including both OTA
protocol and YMODEM protocol.
Figure 5. OT
A server state diagram
UM2726 - Rev 2
There are 4 YMODEM states:
• SIZE: it is the first YMODEM communication where the user provides the size of the binary file.
• LOAD: it is the main state where up to 1 kB of data (binary image) is received and stored in RAM memory
.
page 18/29
Preamble NetworkID Header Data CRC
1 byte 4 bytes 1 byte variable 3 bytes
Length
1 byte
Preamble NetworkID Header CRC
1 byte 4 bytes 0xA0 3 bytes
Length
0x00
UM2726
OTA server application
• WAIT: it is a transient state where it is checked if the entire binary image has been received or not.
• CLOSE
been received.
Any communication issue through the UART YMODEM is handled with a general abort of the application. The
application starts over.
There are 6 OTA states:
• CONNECTION: once the size of the binary image file has been received (YMODEM SIZE state), a new
firmware update sequence is started, so the server starts to send packets periodically, “connection packet”,
in order to show its availability to make a connection. If an ACK response to the “connection packet” is
received, then the connection with the client is considered established.
• SIZE: during this state, the server sends a “size packet” to the client, showing the size of the binary image
that it can send.
• START: it is the state where the client says to the server to start the over-the-air firmware update. The client
can send a “start packet” or a “not start packet” according to the size of the binary image received during
the SIZE state. If the server receives a “start packet”, then the OTA firmware update starts. Otherwise, the
server goes to CONNECTION state looking for a next connection.
• DATAREQ: the server receives the number of the packets to send (sequence number) from the client.
• SENDATA: the server sends the requested (through the sequence number) packet to the client. All the data
packets have the same length, but the last one that can have a reduced length. If the data request are still
not acquired, the server goes to YMODEM LOAD state and gets the next part of the binary image.
• COMPLETE: when the client has acknowledged the last data packet, then the entire binary image has been
transferred and the OTA operation is completed.
The RF communication during the OTA operations is managed through re-transmission and a certain number of
retries is preprogrammed. If the number of retries during a single state goes through the maximum number of
retries configured, then the OTA operation is aborted and the application starts over.
: it is the state in charge of closing the YMODEM communication once the entire binary image has
5.1.2 OTA server packet frame
The packet frame used is based on the packet format of the radio low-level driver framework
The header of the packet is used to provide the information about the state where actually the server operates,
while the data of the packet provides the information such as the size of the binary image or the data block of the
binary image. The NetworkID can be configured by the user, and must be the same both for the server and for the
client.
The packet list sent by the server is the following:
• Connection packet
: it does not contain the data field. The header is set to 0xA0.
Figure 6. Packet frame format
Figure 7. Connection packet
• Size packet: it contains 4 bytes of data with the information about the size of the binary image in MSB first.
UM2726 - Rev 2
page 19/29
Preamble NetworkID Header Data CRC
1 byte 4 bytes
0xB0
Image size [4 byt es]
3 bytes
Length
0x04
Preamble NetworkID Header CRC
1 byte 4 bytes 0xC0 3 bytes
Length
0x00
Preamble NetworkID Header CRC
1 byte 4 bytes 0xD0 3 bytes
Length
0x00
Preamble NetworkID Header Data CRC
1 byte 4 bytes 0xE0
Seq. num. [ 2 bytes]
3 bytes
Length
variabl e
Image [variable]
UM2726
OTA client application
Figure 8. Size packet
• Start ACK packet: it is the response packet used to acknowledge the start packet of the client.
Figure 9. Start ACK packet
• Data request ACK packet: it is the response packet used to acknowledge the data request packet of the
client.
Figure 10. Data request ACK packet
• Send data packet: it is the packet with a block of data from the binary image. The sequence number is used
to synchronize both the client and the server, and it is used for mechanism of re-transmission.
5.2 OTA client application
The OTA client application is a reset manager application that at the start-up takes the decision to “jump” to the
user application or activate the client OT
The client OT
protocol and loads in the user Flash the binary image acquired.
The OTA client application memory size is below the 8 kB of Flash memory.
5.2.1 OTA client state machine
The following diagram shows the state machine for the OTA protocol implemented for the OTA client node.
A firmware update application is implemented through a state machine that manages the OTA
Figure 1
A firmware update application.
1. Send data packet
UM2726 - Rev 2
page 20/29
Figure 12. OTA client state diagram
OTA
CONNECTION
OTA
NOTSTART
OTA
SIZE
OTA
START
OTA
DATAREQ
OTA
GETDATA
OTA
COMPLETE
(1) Wait for a valid packet
(2) Received a valid packet
(3) Wait for a valid ACK response
(4) Received a valid ACK response
(5) Received a valid packet, but the image size
does not fit the Flash memory free space
(6) Received a valid data packet
(7) Still data needed
(8) The entire binary file has been uploaded
(1)
(1)
(3)
(3)
(1)
(2)
(2)
(4)
(4)
(5)
OTA
FLASHDATA
(6)
(7)
(8)
UM2726
OTA client application
There are 8 OTA states:
• CONNECTION: it is the starting state for the client. It looks for a valid “connection packet” coming from the
server. If the “connection packet” is received, then an ACK response is sent back. This action establishes
the connection with the server
• SIZE: during this state, the client gets the “size packet” from the server.
• START: it is the state where the client sends the “start packet” to the server. This causes the OTA firmware
update to start. The “start packet” is sent only if the size of the binary image fits the user Flash memory.
• NOTSTART: the size of the binary image does not fit the user Flash memory of the client (it is too big).
Therefore, the OTA firmware update cannot start.
• DATAREQ: the client sends to the server the number of the data packets it needs. This is calculated
considering the size of the binary image and the maximum number of bytes that the server can send
(defined initially both for the client and server)
• SENDATA: the clients gets the data packet requested
• FLASHDATA: in this state the data from the data packet are stored inside a buffer and once the size of the
buffer is greater or equal to the page size, all the buffer is actually written in the user Flash memory. This
operation is done also once the last block of the binary image has been received.
• COMPLETE: once the entire binary image has been uploaded in the user Flash memory, the OTA operation
is completed.
The RF communication during the OTA operation is managed through re-transmission in order to have a certain
number of retries. If the number of retries during a single state goes through the maximum number of retries
configured, then the OTA operation is aborted and the application starts over.
5.2.2 OTA client packet frame
The packet frame used is based on the packet format of the radio low-level driver framework.
.
UM2726 - Rev 2
page 21/29
Preamble NetworkID Header Data CRC
1 byte 4 bytes 1 byte variable 3 bytes
Length
1 byte
Preamble NetworkID Header CRC
1 byte 4 bytes 0xA0 3 bytes
Length
0x00
Preamble NetworkID Header CRC
1 byte 4 bytes 0xB0 3 bytes
Length
0x00
Preamble NetworkID Header CRC
1 byte 4 bytes 0xC0 3 bytes
Length
0x00
Preamble NetworkID Header CRC
1 byte 4 bytes 0xF0 3 bytes
Length
0x00
Preamble NetworkID Header Data CRC
1 byte 4 bytes 0xD0
Seq. num. [2 bytes]
3 bytes
Length
0x02
UM2726
OTA client application
Figure 13. Packet frame format (client)
The header of the packet is used to provide the information about the state where the client actually operates,
while the data of the packet is used to request a specific block only of the binary image. The NetworkID can be
configured by the user, and must be the same both for the server and for the client.
The packet list sent by the client is the following:
• Connection ACK packet
: it is the response to the connection packet of the server.
Figure 14. Connection ACK packet
• Size ACK packet: it is the response to the size packet of the server.
Figure 15. Size ACK packet
• Start packet: it is used to start OTA operation.
Figure 16. Start packet
• NotStart packet: it is used to not start OTA operation.
Figure 17. Not start packet
• Data request packet: it is used to request a specific data packet to the server
Figure 18. Data request packet
UM2726 - Rev 2
.
page 22/29
• Send data ACK packet: it is used to ACK the data coming from the server.
Preamble NetworkID Header CRC
1 byte 4 bytes 0xE0 3 bytes
Length
0x00
Figure 19. Send data ACK packet
5.3 OTA firmware upgrade scenario
Hereafter, a scenario for an OTA firmware upgrade operation.
The scenario is made up of two devices.
•
The server running the application RADIO_OT
• The client running the application RADIO_OTA_ResetManager, configuration OTA_Client.
The firmware application is located in the DK folder
\Projects\Peripheral_Examples\Examples_MIX\RADIO\RADIO_OTA_ResetManager.
The steps to follow to have the OTA firmware upgrade are listed below:
1. Power up both the BlueNRG-LP boards and their respective applications OTA_Server_Ymodem and
OTA_Client.
The OTA_Server_Ymodem board must be plugged with the USB cable to a PC.
2. Open the COM port of the board with the OTA_Server_Ymodem configuration with a serial terminal program
such as TeraTerm or similar.
3. Select the transfer mode of a file with YMODEM standard.
In TeraTerm, this can be done by opening the menu File, then select transfer, then YMODEM and press
send.
4. Select the binary image to be uploaded (.bin file). Note that the binary image must be generated as
explained in Section 5.4 How to add the OTA client function.
5. Once the YMODEM transfer has been completed, the OTA firmware upgrade of the client board is also
completed.
Inside the released DK, an example application also containing two configurations reserved to the OTA
client functionality, can be found. The example application is the TxRx, which demonstrates a point-to-point
communication by using the radio low-level driver. The configurations are:
• TX_Use_OTA_ResetManager.
• RX_Use_OTA_ResetManager.
For these two configurations, the steps explained in Section 5.4 How to add the OTA client function have been
applied. The push button PUSH2 of the STEVAL-IDB0011V1 is used to run the OTA Client functionality, in order to
update the respective image.
The example is located in \Projects\Peripheral_Examples\Examples_MIX\RADIO\RADIO_TxRx.
UM2726
OTA firmware upgrade scenario
A_ResetManager, configuration OTA_Server_Ymodem.
5.4 How to add the OTA client function
In order to integrate the OTA client functionality into an existing application, the user must follow the steps below:
1.
Reserve the first five pages (10 kB) of the Flash memory for the client application. The linker symbol
“MEMOR
MEMORY_FLASH_APP_OFFSET =0x2800
The example application TxRx, configurations TX_Use_OTA_ResetManager or
RX_Use_OTA_ResetManager can be used as reference.
2. Include the files “radio_ota.c” and “radio_ota.h” in the application project. These files are located in \Library
\BLE_Application\OTA. The files contain the API OTA_Jump_To_Reset_Manager() used for setting the RAM
variable named ota_sw_activation and then reset the system.
3. Define a trigger to be used to jump from the user application to the OTA client application. This trigger is
used to call the function OTA_Jump_To_Reset_Manager().
UM2726 - Rev 2
Y_FLASH_APP_OFFSET” can be used for this scope as follows:
page 23/29
Figure 20. OTA client Flash memory layout
User APP
OTA Client
PAGES
Flash memory
5
UM2726
How to add the OTA client function
UM2726 - Rev 2
page 24/29
Revision history
Table 5. Document revision history
Date Version Changes
20-Jul-2020 1 Initial release.
Added Table 4. Status_table.
29-Mar-2021 2
Updated T
HAL layer and Section 4.3 RX example with HAL layer.
able 3. ActionTag field description, Section 4.2 TX example with
UM2726
UM2726 - Rev 2
page 25/29
UM2726
Contents
Contents
1 BlueNRG-LP radio operation .......................................................2
2 Data packet format ................................................................3
3 Radio low level driver framework ..................................................5
3.1 Description ....................................................................5
3.2 API architecture................................................................5
4 How to write an application ........................................................9
4.1 HAL layer approach ............................................................9
4.2 TX example with HAL layer .....................................................10
4.3 RX example with HAL layer .....................................................11
4.4 ActionPacket approach.........................................................12
4.5 TX example with ActionPacket ..................................................13
4.6 RX example with ActionPacket ..................................................15
5 The BlueNRG-LP proprietary over-the-air (OT
A) firmware..........................18
5.1 OTA server application .........................................................18
5.1.1 OTA server state machine.................................................18
5.1.2 OTA server packet frame .................................................19
5.2 OTA client application ..........................................................20
5.2.1 OTA client state machine .................................................20
5.2.2 OTA client packet frame ..................................................21
5.3 OTA firmware upgrade scenario .................................................23
5.4 How to add the OTA client function...............................................23
Revision history .......................................................................25
UM2726 - Rev 2
page 26/29
List of tables
UM2726
List of tables
Table 1. V
Table 2. ActionPacket structure ................................................................6
Table 3. ActionTag field description..............................................................7
Table 4. Status_table .......................................................................8
Table 5. Document revision history ............................................................. 25
alues in bytes for the length field ........................................................3
UM2726 - Rev 2
page 27/29
UM2726
List of figures
List of figures
Figure 1. Packet format .....................................................................3
Figure 2. Packet format with encryption enabled....................................................4
Figure 3. Relative time ..................................................................... 9
Figure 4. Callback timing ................................................................... 13
Figure 5. OT
Figure 6. Packet frame format ............................................................... 19
Figure 7. Connection packet ................................................................ 19
Figure 8. Size packet ..................................................................... 20
Figure 9. Start ACK packet ................................................................. 20
Figure 10. Data request ACK packet............................................................ 20
Figure 1
Figure 12. OTA client state diagram ............................................................21
Figure 13. Packet frame format (client) .......................................................... 22
Figure 14. Connection ACK packet ............................................................ 22
Figure 15. Size ACK packet.................................................................. 22
Figure 16. Start packet ..................................................................... 22
Figure 17. Not start packet .................................................................. 22
Figure 18. Data request packet ............................................................... 22
Figure 19. Send data ACK packet ............................................................. 23
Figure 20. OTA client Flash memory layout ....................................................... 24
1. Send data packet ................................................................. 20
A server state diagram ........................................................... 18
UM2726 - Rev 2
page 28/29
UM2726
IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST
products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST
products are sold pursuant to ST’
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of
Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions dif
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www
names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
s terms and conditions of sale in place at the time of order acknowledgement.
ferent from the information set forth herein shall void any warranty granted by ST for such product.
.st.com/trademarks
© 2021 STMicroelectronics – All rights reserved
. All other product or service
UM2726 - Rev 2
page 29/29
Loading...