Note: This KBA has been deprecated, SDK 1.x is no longer supported.

Introduction

This knowledge base article is intended to help to migrate applications to BLE SDK 2.x.x which were originally developed with BLE SDK 1.0.4. Here we explain the differences between the SDK versions and highlight the most important steps during the migration process.

The BLE SDK 2.x.x developed with different principles than the SDK 1.x.x. As a result, the new SDK contains much simpler and easy to understand examples. However, some application related features are dropped or changed.

The new SDK contains new Bluetooth stack whose feature set and stability are enhanced, but these changes are not scope of this document. See the release note for these details.

The migration process can be quite complicated due the new SDK does not contain the Application Builder and its plugins. The process complexity relies on which plugins and callback were used.

Here we list the most important differences between the BLE SDK 1.0.4 and the BLE SDK 2.x.x

Steps for migration

0. The migration tool in studio v4 is not working for the BLE SDK projects

The migration tools is only for MCU projects. The 1.0.4 BLE SDK uses Application builder that is why it will not work.

1. Create an empty project in SDK 2.x.x

This new project will be the base of the existing BLE SDK 1.0.4 project. It is recommend to use the empty – SOC project because it contains the minimal set of working functions. (advertisement, boot, connect, disconnect, OTA)

In case of NCP mode is used the use empty – NCP example as starting project.

2. Overwrite the new .hwconfig file with the old one

Once the old hwconfig copied to the new workspace, close the hwconfig tab and reopen the hwconfig file. Now the gui should updated with old hardware setting. Save the configuration to build the InitDevice.c and h. files.

3. Merge the old .bgproj file with new workspace .bgproj file

In the BLE SDK 2.x.x the default bgproj files contains an OTA service. If you want OTA you need to add this service to your bgproj additionally to your old bgproj. Once the .bgproj files merged, compile the project and check if the newly generated gatt_db.h and gatt_db.h contains the same attributes as the old project.

4. Copy linked plugin .c files to the new workspace

The plugin files are sorted in subfolders on the BLE SDK 1.0.4 workspace. You need to copy the content of these subfolders to the new workspace.

Do not copy the content of the following folders:

• app
• IAR ARM - debug
• inc
• platform
• platform_hw
• src

The easiest way to copy is drag and drop the folders then choose the Copy files and folders option.

5. Copy plugin .h files to the new workspace

This files can be found in the BLE SDK 1.0.4 Installation folders. By default, they are in:

*.h from c:\SiliconLabs\BluetoothSmartSDK\1.0.4.0-GA\sdk\plugins\

*.h from c:\SiliconLabs\BluetoothSmartSDK\1.0.4.0-GA\sdk\plugins\features\

infrastructure.h from c:\SiliconLabs\BluetoothSmartSDK\1.0.4.0-GA\sdk\plugins\platform\

6. Add the newly copied/created folders to the project include path

Go to the project properties then go to C/C++ Build -> Setting-> IAR C/C++ Compiler for ARM-> Preprocessor. Now you need to add all the folders one by one. It is wise to use Symbols to make the paths relative as shows on the screenshot.

7. Configuration header

Copy the ble-soc-configuration.h configuration header to the new workspace. Then replace the CONFIGURATION_HEADER with the “ble-soc-configuration.h” in all plugin header files.

8. Callbacks

Copy the ble-soc-callbacks.c and .h configuration header to the new workspace. Then replace the CALLBACKS_HEADER with the “ble-soc-callbacks.h” in all plugin header files.

9. Add the workspace root to the include path

You can use symbols like to make the paths relative as it shown below:

"${workspace_loc:/${ProjName}}"

10. Event control

The event_control.c and and event_control.h is not used in the BLE SDK V2.x.x projects if you want to use them copy these file to the new workspace they are located here:

C:\SiliconLabs\BluetoothSmartSDK\1.0.4.0-GA\sdk\plugins\platform

As an alternative you can use the soft timers provided by the stack. See the gecko_cmd_hardware_set_soft_timer in the API reference.

11. VCOM and UART retarget

To add VCOM and UART check this KB article:

http://community.silabs.com/t5/Bluetooth-Wi-Fi-Knowledge-Base/Retarget-stdio-to-UART-in-BLE-SDK-2-0-0-examples/ta-p/178710

12. Graphics libs

Add the following include paths to the project:

"${StudioSdkPath}/platform/middleware/glib"

"${StudioSdkPath}/platform/middleware/glib/glib"

"${StudioSdkPath}/platform/middleware/glib/dmd"

Copy displayconfigapp.h from the new workspace it can be found in:

c:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\app\bluetooth_2.0\appbuilder\sample-apps\soc-smartPhone\

Then add the graphics source files to the project, these are the followings:

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\hardware\kit\common\drivers\display.c

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\hardware\kit\common\drivers\displayls013b7dh03.c

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\hardware\kit\common\drivers\displaypalemlib.c

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\platform\middleware\glib\glib\*.c

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\platform\middleware\glib\dmd\display\dmd_display.c

13. Board Support files

Add the board support files to your project. These can be found here:

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\hardware\kit\YOUR_BOARD

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\ble\v2.0.1.0\hardware\kit\common

14. Remove the #include "app_cfg.h"

This header is no more needed due the app_cfg.c is not used anymore. This file connected the application builder callback and the stack events.

15. Application builder callbacks

For each callback, you need to call the callback function manually because the BLE SDK 2.x.x examples does not use them. The most important callbacks are the followings:

mainEfr32StackInitCallback

The content of this callback should copied/merged to the main.c of the new project. It is not recommended to call the callback directly because the stack and hardware init functions already done by the empty – SOC/empty - NCP example.

mainAppTickCallback

This callback should not be used at all. This callback contains periodic application functions which should be merged to the main loop.

For the possible scheduling of application functions check this knowledge base article.

http://community.silabs.com/t5/Bluetooth-Wi-Fi-Knowledge-Base/Scheduling-application-tasks-while-running-BLE-stack/ta-p/179676

resetEventCallback

This callback can be called in the gecko_evt_system_boot_id in the main loop.

Callbacks from app_cfg.c

For each callback which is registered for a stack event in app_cfg.c has to be called in the switch case of the main loop.

For example, all callbacks which can be found in the AppCfgGattServerUserReadRequest_t structure has to be called in the case of gecko_evt_gatt_server_characteristic_status_id stack event.

Some callbacks are not registered to stack events but for other events like a button press. In this case you need to create your own button handling functions and call the callback from there.

16. Bootloader

Version 2.0.0 is not backwards compatible with 1.0.x versions, meaning that one cannot perform DFU, either over UART nor OTA, between the versions 1.0.x and 2.x.x.

The empty – SOC and the empty - NCP examples contains the support of OTA.

Here you can find more about this:

http://community.silabs.com/t5/Bluetooth-Wi-Fi-Knowledge-Base/BGScript-OTA-changes-in-BLE-SDK-2-0/ta-p/179692

Note: This KBA has been marked as deprecated. A more updated KBA can be found here:

Secure SPP (Serial Port Profile) over BLE

Introduction

In this article we demonstrate how to build up a secure Bluetooth connection between two BGM modules, and how to implement serial communication (cable replacement service) between them. The example relies on two earlier knowledge base articles, one demonstrating the cable replacement service:

SPP-over-BLE example

and the other demonstrating how to build up secure connections with BGM modules:

Using Bluetooth security features in Silicon Labs Bluetooth SDK

Please refer to these articles first.

How it works

In the provided example we combine the client and server roles into one code, so you have to upload the same code to both devices you want to connect. The roles are configured by holding down either pushbutton at boot time. Holding down the button makes that device a master (client) scanning for other devices that are capable of cable replacement service. The other device will advertise and becomes the slave (server).

When the connection is built up, the devices have to go through the following states before starting data transfer:

1. Find cable replacement service – the client is discovering the services of the server looking for a cable replacement service with a specific uuid.
2. Find cable replacement characteristic – the client is discovering the characteristics of the server within the cable replacement service looking for a cable replacement characteristic.
3. Enabling notifications – the client is requesting notifications for the cable replacement characteristic.
4. Authenticating – the devices have to confirm that they have successfully built up a secure connection. This is done by showing a passkeys on both devices. If the passkeys match, and both devices confirm this, they get bonded (paired). If they were already bonded when they connected, the authentication is not needed again, and the secure connection is automatically built up. Bonding information persists over resets so to test the authentication repeatedly, you may want to implement a call to sm_delete_bondings with some trigger of your choice. Another option is to use Simplicity Commander tool to erase the devices' flash.

Running the example

To use the attached example code, please follow these steps:

1. Create a new SoC-Empty project (e.g. for BGM13P module).

2. Copy the attached files into it.

3. Import gatt.xml into the GATT Configurator.

4. Press Save and then Generate in the GATT Configurator.

5. Enable debug printing by setting DEBUG_LEVEL to 1 in app.h.

6. Build and flash the project to 2 devices.

7. Open up a terminal program (e.g. TeraTerm) and connect to both devices to see the logs.

8. Press PB0 or PB1 on one of the devices while resetting it to put it into client mode.

9. Simply reset the other device to put it into server mode.

Silicon Labs Bluetooth stack allows connection to multiple slaves, with a maximum number of 8 slaves. This article provides guidance on how to connect to multiple slaves and how to write to them parallel. Sample projects for the slave and the master devices are attached. Parallel reading can be implemented in a similar way.

In this example we connect with one central device (master) to multiple slaves that have a specific service with a specific characteristic. Here we use a custom service/characteristic with a custom UUID, but standard services can be used as well.

Establishing multiple connections

First, let us discuss how to connect to multiple devices.

As a first step, scanning is started by the master device, and the advertisement packets are received. We have to choose from all the incoming advertisement packets the one we want to connect to. The decision can be made based on different parameters, e.g. device name, Tx power, or advertised services. Here we parse the advertisement packets looking for a specific service UUID, and we connect to the device that has this specific UUID in the advertisement. (To find this UUID, it is important to advertise the UUID on the slave side! This can be done by ticking the "Advertise service" checkbox in the Visual GATT Editor of the slave.)

Before requesting a connection to the chosen device we stop scanning. In general, this is not required - the stack can handle parallel scanning and connecting - but it ensures more stable working.

When the connection is established, first the custom service has to be discovered to find the service handle with which it can be referred to. Similarly, after finding the custom service, the custom characteristic within this service has to be discovered to find its characteristic handle. This handle is needed when we are reading /writing the characteristic, hence we save it in a handle table for later use.

Note: it is always the responsibility of the application to store connection/service/characteristic handles, as they cannot be queried from the stack later.

If the handles are found and saved, the scanning is restarted to find other slaves, and we iterate the same process as before. When a new connection is established, the earlier ones are still kept alive until the connection limit (8 connections maximum) is reached.

When all the connections are established (all the slaves are found) it is suggested to stop scanning completely to speed up operation.

Timing of parallel connections

Bluetooth connections use small connection windows to exchange data in every connection interval. At least an empty packet is sent in every connection interval, first by the master, then by the slave, and if there is data to send, then the packets are extended. This ensures that no continuous receiving is needed, and in most of the time the device can go into sleep mode. The same behavior makes it possible to keep alive multiple connections easily at the same time. The connection windows of different connections are simply interleaved.

Connection windows are placed randomly in time domain, so some of the connections might be placed on top of each other. However, if this happens, the scheduler makes sure that each connection gets enough time so that its supervision timeout does not expire. Of course in this case one might see increased latency on some connections, but in general it can be said, that all connections can be accessed at least once within the connection timeout (supervision timeout) interval.

In the example we use 12.5ms connections intervals and 100ms timeout. In this case writing to each of the 8 slaves and getting the ACK responses from them takes 24–100ms, depending on the result of the connection window allocating algorithm.

Writing parallel to multiple slaves means simply issuing multiple write commands right after each other. This puts the write commands in the task queue of the stack, and they will be processed in the next available connection window for each connections. Since connection windows are interleaved, ideally all write commands can be sent before the first ACK is received. Considering the transmission times, it is suggested to use a minimum connection interval of 12.5ms when 8 slaves are in use to ensure enough time for sending all write request before receiving write responses (ACKs).

Example code

The provided example includes the slave (server) code and the master (client) code.

The slave is simple. It has a custom service with a custom characteristic. The service is advertised in the advertisement packets, and the characteristic is used to turn on/off LED1 of the WSTK. LED0 means the connection state:
LED0 on: advertising
LED0 off: connected

The master implements the already discussed flowchart: it connects to any slave that advertises the service with our custom UUID. To see the state of the master, connect to it with a terminal program from your PC using the virtual COM port over USB. After connected to the PC, it is suggested making a reset first on the master, then on the slaves. When you see, that all slaves are connected, push PB0 on the WSTK of the master to stop scanning and reset connection parameters for all connections. After all connection parameters are set, push PB1 to send data to all of the slaves. The time measured from sending the first command to receiving the last ACK is displayed. You can repeat this any time, and you will find, that the measured time is quasi constant. If you push PB0 again, the connection windows are reallocated which can result in a different time from first command to last response.

To create the slave project do as follows:

1. Create a new SOC-Empty project for your device

2. Import the attached gatt.xml into the Visual GATT Editor by clicking on the import button on the right side

3. Press Generate

4. Copy the attached app.c and app.h files from the /slave folder into your project

5. In main.c add #include "app.h" and replace the main() function with the following code:

   void main(void)
   {
     // Initialize device
     initMcu();
     // Initialize board
     initBoard();
     // Initialize application
     initApp();
     // Start application
     appMain(&config);
   }
   

6. Build and flash your project to your slave devices

To create the master project do as follows:

1. Create a new SOC-Empty project for your device

2. Make sure that HAL_VCOM_ENABLE is set to (1) in hal-config.h

3. Copy retargetio.c, retargetserial.c and retargetserial.h from C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\<version>\hardware\kit\common\drivers into your project

4. Copy gpiointerrupt.c from C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\<version>\platform\emdrv\gpiointerrupt\src into your project

5. Copy the attached app.c and app.h files from the /master folder into your project

6. In main.c add #include "app.h" and replace the main() function with the following code:

   void main(void)
   {
     // Initialize device
     initMcu();
     // Initialize board
     initBoard();
     // Initialize application
     initApp();
     // Start application
     appMain(&config);
   }
   

7. Build and flash your project to your master device