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


BLE SDK 1.0.4

BLE SDK 2.x.x

Application Builder Plugins




Closed source

Open source

Soft Timer Functions



BLE Event Handling

configured in app_cfg.c

switch - case in main.c

UART Retarget

built in the examples

have to be added separately

Boards Support Package

built in the examples

have to be added separately

LCD Graphics Library

built in the examples

have to be added separately

Simplicity Studio






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


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\\sdk\plugins\

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

infrastructure.h from c:\SiliconLabs\BluetoothSmartSDK\\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:



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:




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:


12. Graphics libs

Add the following include paths to the project:





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



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







13. Board Support files

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




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:



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.



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.



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:



  • Knowledge Base Articles
  • Bluetooth Low Energy
  • Bluetooth Classic