Quick Start BlueNRG SDK Firmware Development Process

Infineon / Mitsubishi / Fuji / Semikron / Eupec / IXYS

Quick Start BlueNRG SDK Firmware Development Process

Posted Date: 2024-01-14



This document guides users to quickly have an intuitive and clear understanding of the BlueNRG SDK and understand its software architecture, so that they can successfully learn to use the SDK to develop their own user firmware.

The SDK described in this document is the SDK of the BlueNRG-LP/LPS chip. Before reading this document, users should first understand some basic features of the BlueNRG-LP/LPS chip and the programming method of its supporting development board.


SDK directory

Download the SDK installation package from the ST official website. After successful installation, you will get an SDK directory. see picture 1:

Figure 1.SDK directory

The function description of each directory is shown in Table 1:

Table 1. SDK directory description

The BlueNRG SDK installation directory provides a convenient entrance for user engineers to develop the BlueNRG platform. For example, there are the following scenarios:

1. Before hardware engineers design PCB, they can find hardware design guidance documents through the Docs directory. After completing the PCBA production, you can use the Navigator tool to burn the application firmware under Firmware through the serial port to verify the board function.

2. When engineers want to use the board for power consumption and radio frequency testing, they can also find the appropriate compiled firmware in the Firmware directory (Beacon can be used to measure SOC Bluetooth power consumption, and DTM can be used to measure radio frequency parameters)

3. Firmware engineers can find a wealth of routines in the Projects directory, and can use any IDE such as KEIL, IAR, and WiSE to open, compile, and download the project.


SDK routines

The SDK Projects directory contains the following three types of routines:

1. Periph_Examples: Contains chip peripheral driver routines.

2. External_Micro: Contains routines for external microcontrollers, which are used in scenarios where the BlueNRG chip serves as a co-processor in the system.

3. BLE_Examples: Contains all Bluetooth-related routines. The engineering features of these routines are shown below:

Table 2. BLE routine description


Quickly implement user firmware functions

This chapter guides users how to quickly find the corresponding API interface and location in the SDK so as to master how to add their own configuration and user logic code to the SDK routines.

After having an understanding of the functions of the routines provided by the SDK, assume that a development task faced by the user is:

1. BLE slave function, including the following configuration:

a. A service, a characteristic, the characteristic has Write and Notify attributes

b. The device broadcast name is "Hello"

2. Use the mobile BLE tool to communicate with the device and print the data generated during the communication process.

3. Customize the protocol to achieve the following functions:

a. Control the LED to turn on and off

b. Upload the heartbeat packet regularly for 1 second, the content is the seconds count value after the connection

c. Upload key event notification for each key press

Based on the above tasks, we can choose the BLE_SerialPort project as the basic project and use it to develop firmware.

4.1. Verify original project

Before adding user code, we'd better verify the function of the original project (BLE_SerialPort) to ensure that the development environment is normal. Create a new user project directory, for example, test_sdk1.3.0, and then copy the following files from the SDK directory to our user project directory, see Figure 2:

Figure 2. User project directory

Open the Keil project of Projects > BLE_SerialPort, check the "Browse Information" option to enable the jump of functions within the project, and select the Server project configuration, see Figure 3 and Figure 4:

Figure 3.Browse Information

Figure 4. Select Server project configuration

Compile and download the project to the development board. After the project is run, you should see the following printed information:

Figure 5.BLE_SerialPort project LOG information

Use the STBLE Toolbox tool to scan the device, and you should see the device name "Sport_LP", see Figure 6:

Figure 6. STBLE Toolbox scanning page

At this point, the original project has been running normally. This project implements the functions of customized services and features, and can send and receive data through the serial port and mobile phone. To complete this development task, we only need to modify some code in specific locations.

4.2. Configure BLE slave function

The original project has two characteristics, one is responsible for sending (TX_CHR_UUID) and the other is responsible for receiving (RX_CHR_UUID). According to the requirements, we need to merge them into a feature that can be received and sent. Figure 6 demonstrates how to define a new characteristic UUID and comment out the old two characteristic UUIDs:

Figure 7. Characteristic UUID

The protocol stack provides the ble_gatt_chr_def_t type structure. Users can define a structure variable and assign a value to declare a feature. Figure 7 shows the relevant assignment process of the feature configuration we need. In the figure, we can see the UUID declaration of the feature, the feature notify and write attribute declarations, the feature descriptor declaration and other information. Additionally, the old two features should be commented out.

Figure 8. Defining features

Assign the new feature configuration to the service declaration, and change the number of features to 1:

Figure 9. Characteristic declaration assigned to service declaration

The data structures related to the above services and characteristics have been configured, and we still need to pass these configurations to the protocol stack through the API.

First of all, you need to define a new handle. The so-called handle. Simply put, when the user sends and receives data, he needs to choose which feature to send and receive data on. At this time, a handle is needed to specify the feature (the handle is essentially an attribute). handle field). The original two handles should also be commented out, see Figure 10

Figure 10. Handle

Then, the services and characteristics defined above are transmitted to the protocol stack at one time through the aci_gatt_srv_add_service function. The protocol stack parses these configurations, builds a complete ATT attribute table, and saves it in the memory. After that, the user can use the aci_gatt_srv_get_char_decl_handle interface to obtain the allocated handle (see Figure 11). This handle will be frequently used in subsequent data interaction processes.

Figure 11. Get handle

At this point, GATT related configuration has been completed. However, since the upper layer heavily references the old two handles for data transmission and reception, there will be many errors in the compilation at this time. These errors will not be processed here, and other BLE configurations will be completed first.

Next, modify the Bluetooth address and broadcast name, see Figure 12:

Figure 12. Bluetooth address and broadcast name

After the length of the broadcast name is changed, attention should be paid to specifying its length:

Figure 13. Broadcast name length

LOCAL_NAME sets the device name in the broadcast packet. When the device is successfully connected, the host will obtain another device name from the device name feature of the GAP Profile. The two names should be kept consistent here:

Figure 14. Device name

Figure 15. Set device name

At this point, the application configuration of Bluetooth is complete. Next, configuration and implementation related to data communication can be carried out.

4.3. Communicate with mobile phone

After configuring the slave function in the previous section, compilation will generate a large number of errors because the BLE communication process will refer to the old handle more often. Following the operations to solve these compilation errors, we can understand the BLE communication process. The specific operations are as follows:

Globally searching for the old send handle (TXCharHanlde), we found the protocol stack API for data sending, and corrected it:

Figure 16. Send Notify

After the mobile phone enables subscription, it will notify the upper layer through the callback function in Figure 17. At this time, it should be modified to a new feature handle, and at the same time, some printing instructions should be added to indicate the enabled and disabled status of notify:

Figure 17. Enable subscription callback

Add new feature handle global variable declaration, comment out the old one:

Figure 18. Handle declaration

All issues regarding the old send handle (TXCharHanlde) have been resolved. Continuing to search for the old receiving handle (RXCharHanlde), we should be able to find the function interface for the device to receive mobile phone data, and replace the handle with the new characteristic handle, see Figure 19:

Figure 19. Data receiving callback function

At this point, we should be able to pass the entire compilation process and have found the location where data is sent and received. At this time, you can add printing functions for data sending and receiving at these locations. The user interface for receiving data is shown in Figure 20:

Figure 20. User receives BLE data

Regarding sending data, the original project implemented the following processing flow:

1. Receive data from serial port

2. Parse data into commands and cache these commands

3. Continuously send commands in the command buffer through polling.

This processing flow is not suitable for our task requirements. We need to cancel this part of the function first, see Figure 21

Figure 21. Cancel the original data processing process

Then design your own sending function, see Figure 22:

Figure 22. Customized BLE data sending function

At this point, all Bluetooth communication functions have been implemented. Users can:

• Data_Received() interface receives data

• user_send_data_over_ble() interface sends data

4.4. Add other functions

According to the task requirements, we also need to implement the following three functions:

1. Control LED on and off

2. Upload the heartbeat packet regularly for 1 second, the content is the seconds count value after the connection

3. Each time a key is pressed, the key event notification is uploaded and implemented one by one as follows:

4.4.1. Control LED on and off

First, implement the LED on and off processing function,

Figure 23. LED command processing function

Add it to the BLE data receiving function, see Figure 24. The LED control function is implemented.

Figure 24. LED command processing after receiving data

4.4.2. Upload heartbeat packets every second

First, implement the heartbeat upload processing function to upload a 4-byte count value every second when the device is connected, and use 0xaa as the command word. See Figure 25:

Figure 25. Heartbeat upload processing

Add the heartbeat processing function to the system task processing function App_Tick. App_Tick will be called continuously in the main loop. Heartbeat packets can only be sent after the Bluetooth connection is successful and subscription is enabled. In addition, use the timeout_flag variable to control it to be called only once per second. The implementation method is as follows:

Figure 26. Heartbeat processing

The above timeout_flag variable needs to be set periodically using a software timer that cycles every second. The application of software timer is very simple.

First, instantiate a timer and define a timeout callback function:

Figure 27. Software timer instantiation

Then, register the timeout callback function and start the timer at the end of the Serial_port_DeviceInit function.

Figure 28. Starting the timer

4.4.3. Upload key events

First, implement the key callback function, which is called when the key is pressed. Before sending the key event, you should check whether Bluetooth is processing the connection and subscribed status at this time. See Figure 29:

Figure 29. Button callback

Called in the key interrupt service function:

Figure 30. Key interrupt service function

At this point, all the requirements of the development task have been completed. Next, perform functional verification.

4.5. Verification function

After the user project is running, scan it with STBLE Toolbox and you can see that the broadcast name has been modified.

Figure 31. User project broadcast name

Connect the device and click the Notify switch to enable subscription. You can observe that the device's heartbeat packet data (5-byte data starting with AA) has begun to be received at the bottom. The data changes once every second, see Figure 32:

Figure 32. Enable subscription

You can also observe the sending of heartbeat packets through LOG. If you press the button at this time, you can also observe that the button event has been sent:

Figure 33. User project LOG



After completing the above user task development process, I believe that users should have an understanding of the software architecture of BlueNRG SDK. The software layer architecture of BlueNRG SDK is the typical three-layer architecture of STM32, which are driver layer, middle layer and user layer:

Figure 34. Software hierarchy architecture

The entire process of adding user functions mentioned above actually only changes the functions of the user layer. The user layer contains the following files:

Figure 35. User layer files

The meaning of these files is:

• serial_port.c, implementation of user application logic

• BLE_SerialPort_main.c, program entry, program main flow

• gatt_db.c, implementation of BLE GATT layer functions

• rf_device_it.c, stores all interrupt service functions

Most of the above user firmware functions are implemented in serial_port.c. The BLE_SerialPort_main.c function implements the main process of the system. Simply put, the bare-metal system of BlueNRG SDK is a front-end and back-end system. Bluetooth events, key interrupts, etc. belong to the foreground processing, which is responsible for setting relevant flags and status. The while1 of the main function belongs to the background processing, running background tasks such as Bluetooth protocol stack and user task processing, see Figure 36:

Figure 36. System flow

The vast majority of routines in the BlueNRG SDK use the software architecture described in this document, that is, the front-end and back-end systems. The software architecture is relatively simple. The advantage is that users can quickly master its process and quickly build their own user functions based on the examples in this document. The disadvantage is that the function is relatively simple, and users need to add a scheduler on this basis to cope with complex function requirements.

Review Editor: Liu Qing

#Quick #Start #BlueNRG #SDK #Firmware #Development #Process