Migrating Bluetooth Projects between SDK Releases#

Introduction#

The Gecko SDK and hence Bluetooth SDK gets a regular update, usually on a monthly basis, in the form of major, minor and patch releases. These updates contain important bug fixes, new features, and sometimes they add support for freshly released hardware (new parts or new boards). This article discusses how to update an existing project, once a new release was downloaded to your computer.

Releases#

When you download an SDK with a new major or minor version number (e.g., you update from v2.6.2 to v2.7.0), a new SDK folder will be created on your computer. From that point on, you can choose which SDK to use when creating a new project. Already existing projects are not affected.

Conversely, when you download a patch release to your computer, it will automatically overwrite your existing SDK content. For example, Gecko SDK v2.7.3 will overwrite Gecko SDK v2.7.2 when downloaded. If you create a new project, it will be created using the new patch release. However, your already existing projects will still contain the files originating in the previous patch release because, when you create a project, the SDK files will be copied to your project during project creation and an SDK update won't affect already created projects. This feature prevents automatically updating projects that were already tested with the earlier patch release.

Updating Existing Projects#

You have two options to update an already existing project:

  1. Creating a new SoC-Empty project with the new SDK and merging all your changes that were done on top of the SoC-Empty project generated with the previous SDK

  2. Replacing all SDK files in your already existing project

In general, it may be better to choose the first option because the project generator handles copying files and creating configurations needed for the latest SDK version.

Updating with Newly Created SoC-Empty Project#

Users should write a Bluetooth application to ensure that the application files are completely separated from the SDK files. That's why the SoC-Empty example project contains app.c / app.h files that implement the application and are independent from the underlying SDK version. Note that more files can be added implementing application code. In this case, the best way to migrate to a new SDK version is as follows:

  1. Create a new SoC-Empty project with the new SDK version.

  2. Overwrite app.c/app.h with your application.

  3. Add other application files (e.g., modules that handle peripherals and provide data for Bluetooth).

  4. Copy the needed SDK dependencies into your project from the updated SDK folder (e.g., if you use LE timer in your project, copy em_letimer.c / em_letimer.h into your project).

  5. Import your GATT database with the GATT configurator. Find the import button on the right hand side and import the gatt.xml file from your old project. Press Generate to generate the GATT database code in your project.

  6. You may have applied changes on init_mcu.c, init_board.c, init_app.c in your already existing project. Instead of overwriting these files with the ones from your old project, merge in the changes you made. This is important because these files are not SDK independent and may contain important changes between two SDK versions. Important: do not press Generate in the GATT configurator after this point because it may regenerate these files and cause your changes to disappear.

  7. Add your additional include directories (e.g., if you created a new folder for custom header files or you copied SDK files into a new folder) and libraries in the project settings. Important: do not press Generate in the GATT configurator after this point because it may regenerate project settings and cause your changes to disappear.

  8. You are ready to build your project.

Updating SDK Files in an already Existing Project#

You may also update an existing project, which means updating all SDK files in your project one-by-one. In this case do the following:

  1. Update the /hardware, /platform and /protocol folders in your project. Because these folders in your project contain only a subset of the files existing in the /hardware, /platform, /protocol folders of the SDK (C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\vX.Y), copy the files one-by-one instead of copying the whole folders into your project.

  2. Check at least main.c, init_mcu.c, init_board.c, init_app.c if they contain any important update since the last SDK version. Create a new SoC-Empty project for your part and compare the new files with your existing project. If you see any changes not done by you, merge those changes in your project.