Skip to content

IOTPA_MESH-4876 #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
silabs-orion wants to merge 5 commits into
base: doccurator/2.7.0
Choose a base branch
from
Open

IOTPA_MESH-4876 #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b12715d
Updating OTA docs for Series 3 new GBL format & Studio 6 process changes
silabs-orion Nov 21, 2025
6ac6447
Update OTA bootloader page for studio 6 using MG24
silabs-orion Nov 24, 2025
c2bddba
Updates to OTA documentation for Studio 6 and Series 3
silabs-orion Nov 24, 2025
dbcd39e
Apply suggestions from code review
silabs-orion Nov 25, 2025
cf93e24
Apply suggestions from code review
silabs-orion Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 59 additions & 25 deletions sld407-matter-ota/01-ota-bootloader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,47 +2,58 @@

The Matter OTA Software Update functionality on EFR32 devices requires the use of a Gecko Bootloader built with correct configuration parameters. The key parameters are the storage slot size and (in case of internal storage) storage slot address. The current document lists the steps required to build the Gecko Bootloader for Matter OTA Update and discusses the configuration parameter selection. For a detailed discussion of Gecko Bootloader refer to *UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher*.

The Gecko Bootloader is built with Silicon Labs Simplicity Studio. These instructions assume that you have installed Simplicity Studio 5, the Simplicity Commander tool (installed by default with Simplicity Studio), the GSDK and associated utilities, and that you are familiar with generating, compiling, and flashing an example application in the relevant version.
The Gecko Bootloader is built with Silicon Labs Simplicity Studio. These instructions assume that you have installed Simplicity Studio, the Simplicity Commander tool (installed by default with Simplicity Studio), Simplicity SDK (SiSDK) and associated utilities, and that you are familiar with generating, compiling, and flashing an example application in the relevant version.

## Bootloader Project In Studio

### Creating the Project

In Simplicity Studio, click **Project > New > Silicon Labs Project Wizard** to create a new project. Select the correct Target Board, SDK and the Toolchain.
Each Matter Sample Application Solution in Simplicity Studio contains a bootloader project pre-configured for Matter OTA Software Updates, generally configured for external storage. The stand-alone bootloader project for internal or external storage can be found in the **Example Projects & Demos** view in Simplicity Studio.

In the next screen, select the example project the bootloader will be based on. For a bootloader using external storage, select **Bootloader SoC SPI Flash Storage
(single image with slot size of 1024K). For a bootloader using internal storage, select **Bootloader - SoC Internal Storage (single image on 512kB device)**.
1. In Simplicity Studio, click **Home**. Next to **Start a New Project**, click **all projects & demos** to create a new project.
2. In the upper right, click **Select Device** to choose the correct Target Board, and in the dropdown, select the appropriate Simplicity SDK.

The list of projects can be easily filtered; in this case, for an SoC Bootloader.

![Bootloader projects](./images/studio-6-bootloader-projects.png)

3. Select the example project that the bootloader will be based on. For a bootloader using external storage, select **Bootloader SoC SPI Flash Storage (single image with slot size of 1024K)**. For a bootloader using internal storage, select **Bootloader - SoC Internal Storage (single image on 1536kB device)**.

From there the list of projects can be easily filtered, in this case, for an SoC Bootloader

![Bootloader projects](./images/studio-6-bootloader-projects.png)

In the next screen, select the example project the bootloader will be based on. For a bootloader using external storage, select **Bootloader SoC SPI Flash Storage(single image with slot size of 1024K)**. For a bootloader using internal storage, select **Bootloader - SoC Internal Storage (single image on 1536kB device)**.

### Configuring Storage Components and Parameters

In the newly created project, select the project's .slcp file, click the **Software Components** tab, and select **Platform > Bootloader > Storage**. In the **Bootloader Storage Slot** component (it should be already installed), configure Slot 0's **Start Address** and **Slot size**.
In the newly created project, select the project's .slcp file, click the **Software Components** tab, and select **Platform > Bootloader > Storage**. In the **Bootloader Storage Slot** component (it should be already installed), configure Slot 0's **Start Address** and **Slot Size**.

- For external storage bootloaders, the **Start Address** should be 0 and **Slot size** should be 1048576. Both values are set by default.
- For external storage bootloaders, the **Start Address** should be 0 and **Slot Size** should be 1048576 (0x100000). Both values are set by default.
- For internal storage bootloaders, see the **Internal Bootloader: Image Size, Selecting Storage Slot Address and Size** section. In the **Common Storage** component, leave **Start address of bootload info** at 0.

### Configuring Other Components

Silicon Labs recommends installing the **GBL Compression (LZMA)** component under **Platform > Bootloader > Core**. This allows the bootloader to handle compressed GBL
files. This component is required for internal storage bootloaders.
Silicon Labs recommends installing the **GBL Compression (LZMA)** component under **Platform > Bootloader > Core**. This allows the bootloader to handle compressed GBL files. This component is required for internal storage bootloaders.

At this point, the project contains all the components necessary to support the Matter OTA Software Update functionality. Other components can now be added to support additional features such as Secure Boot. Refer to *UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher* for the description of various bootloader features and the steps to enable them.

### Building and Flashing the Bootloader

Build the project by clicking on the hammer icon in the Studio toolbar. Flash the bootloader to the board using the **Upload Application** option from the **Debug Adapters** view.
Build the project by clicking the **Hammer** icon in the Project Solution in the Simplicity Studio VS Code extension. Flash the bootloader to the board by clicking the **Chip** icon in the Project Solution in the Simplicity Studio VS Code extension.

## Internal Bootloader: Image Size, Selecting Storage Slot Address and Size

The internal storage bootloader for Matter OTA Software Update is supported on MG24/MG26 boards. In this use case, both the running image and the downloadable update image must fit on the internal flash at the same time. This in turn requires that both images are built with a reduced feature set such as disabled logging and Matter shell (see [here](./02-ota-software-update.md#Internal-Storage-Bootloader) for the list of features). See [Code Savings Guide](/matter/{build-docspace-version}/matter-overview-guides/code-size-savings) for a general guide on reducing the application image size. Using LZMA compression when building the GBL file further reduces the downloaded image size.
The internal storage bootloader for Matter OTA Software Update is supported on MG24/MG26/SixG301 boards. In this use case, both the running image and the downloadable update image must fit on the internal flash at the same time. This in turn requires that both images are built with a reduced feature set such as disabled logging and display. See [Internal Storage Bootloader](./02-ota-software-update.md#Internal-Storage-Bootloader) for the list of features. See [Code Savings Guide](/matter/{build-docspace-version}/matter-overview-guides/code-size-savings) for a general guide on reducing the application image size. Using LZMA compression when building the GBL file further reduces the downloaded image size.

When building an internal storage bootloader, the two key configuration parameters are the **Slot Start Address** and **Slot Size** in the **Bootloader Storage Slot** component. The storage slot must not overlap with the running image and the NVM section of the flash. In other words, the slot start address must be greater than the end of the running image address and the sum of the start address and the slot size must be less than the address of the NVM section.
When building an internal storage bootloader, the two key configuration parameters are the **Start Address** and **Slot Size** in the **Bootloader Storage Slot** component. The storage slot must not overlap with the running image and the NVM section of the flash. In other words, the slot start address must be greater than the end of the running image address and the sum of the start address and the slot size must be less than the address of the NVM section.

![Internal Flash Layout](./images/internal-flash-layout.png)

The simplest way to get the relevant addresses for the running image and NVM is by using the Simplicity Commander tool:

- Build the running image for the Matter application.
- Erase the chip and flash the running image to it (For example: use Simplicity Studio's **Debug Adapters** view context menu to flash the application image and some bootloader valid for the device board. Make sure to select the **Erase chip before uploading image** option).
- Erase the chip and flash the running image to it (For example: use Simplicity Commander's **Flash** view context menu to flash the application image and some bootloader valid for the device board. Make sure to **Erase the chip before uploading the new image**).
- In Simplicity Commander, select **Device Info > Flash Map**. The blank area in the middle of the flash (between the running image in the beginning and NVM at the end) is available for the bootloader storage slot. Each block represents a flash page (8K on MG24 boards). Hovering over a block shows the block's start and end address.
- Set the **Slot Start Address** to be the address of the first available block. Calculate the **Slot Size** to be the difference between the end address of the last free block and the **Slot Start Address**. The **Slot Size** must be greater that the size of the GBL file for the update image.
- (Optional) Set the **Slot Start Address** to the beginning of the second or third available block to account for potential growth of the application image. This way, the bootloader won't have to be reconfigured for every increase in the image size. The storage slot must still be able to accommodate the GBL image for the update.
Expand All @@ -52,35 +63,58 @@ Another way to calculate the Storage Slot parameters is by examining the applica
- Build the running image for the Matter application.
- In the application .map file, find the highest address preceding the .data section, round it up to align on the 8K page boundary (e.g. 0x00000000080f1704 would round up to 0x00000000080f2000), and then add 0x2000 to get the next page block address. The result would be the Slot Start Address. The address of the .nvm section in the .map file is the end of the space available for the Storage Slot. The Slot Size is the difference of the .nvm address and the Slot Start Address.

## Example
## Internal Bootloader Example

This example is for an internal storage bootloader for the Matter lighting app on BRD4187C. As this board is a Series 2 device (MG24), it uses the GBL3 (previously known simply as GBL) bootloader as do all series 2 and older devices. Series 3 and newer devices use the GBL4 format.

This example is for an internal storage bootloader for the Matter lighting app on BRD4186C.
- Add the `matter_platform_low_power` component, choose the replace options when presented. This will remove the Matter Shell, Matter CLI, QR Code, and LCD which will reduce the resulting image size. Build the application.

- Build the application in Simplicity Studio after disabling all optional features such as the Matter QR Code, Matter Display, Matter Shell, and OpenThread CLI components.
- Add the `Enable Link time optimization` component and build the project.

- Build the GBL file for the update image and note its size.
- Create the GBL file for the update image and note its size. For more info on GBL3, refer to [GBL3 Commands](https://docs.silabs.com/simplicity-commander/latest/simplicity-commander-commands/gbl-commands).

```shell
$ commander gbl create --compress lzma ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl --app ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.s37
~/SimplicityStudio/v6_test_workspace/MatterLightOverThreadSolution $ commander gbl3 create artifact/matter-light-update.gbl --app MatterLightOverThread/artifact/MatterLightOverThread.s37 --compress lzma

Parsing file MatterLightOverThread/artifact/MatterLightOverThread.s37...
Initializing GBL3 file...
Adding application to GBL...
Compressing using lzma...
Writing GBL file matter-light-update.gbl...
DONE

~/SimplicityStudio/v6_test_workspace/MatterLightOverThreadSolution $ ls -lh artifact/matter-light-update.gbl
518K artifact/matter-light-update.gbl
```

- For Series 3 devices using GBL4, the process is similar, but you use the `commander gbl4 create` command instead. For more info on GBL4, refer to [GBL4 Commands](https://docs.silabs.com/simplicity-commander/latest/simplicity-commander-commands/gbl4-commands#gbl4-commands) and [Silicon Labs Gecko Bootloader User’s Guide for Series 3 and Higher](https://docs.silabs.com/shared-content/latest/bootloader-user-guide-series3-and-higher/).

```shell
$ ls -la out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl
451176 Jul 19 16:39 out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl
~/SimplicityStudio/v6_test_workspace/MatterLightOverThreadSolution_301 $ commander gbl4 create artifact/series3-matter-light.gbl --data MatterLightOverThread_301/artifact/MatterLightOverThread_301.s37 --device SiMG301 --compress lzma
Initializing GBLV4 file...
Parsing file MatterLightOverThread_301/artifact/MatterLightOverThread_301.s37...
Writing GBL file artifact/series3-matter-light.gbl...
DONE

~/SimplicityStudio/v6_test_workspace/MatterLightOverThreadSolution_301 $ ls -lh artifact/series3-matter-light.gbl
616K artifact/series3-matter-light.gbl
```

- Flash the application image and bootloader. Erase the flash.
- Erase the flash and flash the application and bootloader image. In this example, there is only one board connected so the `serialno` option is not needed.

![Erase Flash](./images/application-upload-erase-flash.png)
```shell
commander flash ../bootloader-storage-internal-single-1536k/artifact/bootloader-storage-internal-single-1536k.s37; commander flash artifact/matter-light-update.gbl;
```

- In Simplicity Commander, display the flash map.

![Flash Map](./images/commander-flash-map.png)
![Flash Map](./images/simplicity-commander-flash-map.png)

- The address of the first available page is 0x080b8000. The end address of the last available block is 0x08172000. This means you can set the Slot Start Address to 0x080b8000 and the Slot Size to 761856 (761856 = 0x08172000 - 0x080b8000). The slot size is sufficient for our GBL file (451176 bytes).
- Create a project base on the **Bootloader - SoC Internal Storage (single image on 512kB device)** example. Configure the Bootloader Storage Slot component and set Slot Address and Slot Size.
- The address of the next page block address is 0x080d0000. The end address of the last available block before the NVM3 region (blue) is 0x08174000. This means you can set the **Start Address** to 0x080d0000 and the **Slot Size** to 0xa4000 or 671744 (671744 = 0x08174000 - 0x080d0000). The slot size is sufficient for this GBL file (671kB > 518KB).
- As discussed [above](#creating-the-project), you need to create an Internal Storage Bootloader project. In this case, targeting BRD4187C which has a 1.5MB of flash, **Bootloader - SoC Internal Storage (single image on 1536kB device)** is an appropriate choice. Configure the Bootloader Storage Slot component and set **Slot Address** and **Slot Size** according to what was determined in the previous step.

![StudioProject](./images/studio-project.png)
![StudioProject](./images/studio-6-matter-bootloader-storage-slot.png)

- Enable the "GBL Compression (LZMA)" component.
- Build the project.
- Once flashed onto the board, this bootloader is ready to execute OTA updates on upgrade images it receives. This is covered in the [next section](./02-ota-software-update.md).
Loading