Bluetooth Knowledge Base

Publish

EFR32BG Peripheral Usage by Bluetooth Stack

MitchC | 06/181/2017 | 06:58 PM

Question
What EFR32BG MCU Peripherals are used by the Bluetooth Stack?

Answer
The following image, taken from the C developers application guide (UG136), shows what resources are used by the Bluetooth stack:

KBA_BT_1303: Enabling LNA on MGM12P for Bluetooth usage

tmonte | 06/181/2017 | 04:19 PM

Introduction

The MGM12P is a multi-protocol module with an on-board LNA for improved RX sensitivity. This article details how the LNA can be enabled for Bluetooth projects starting from SDK 2.4.

Enabling the LNA

The demos and examples listed for MGM12P on Bluetooth SDK 2.4.x will not work out-of-the-box because the LNA is not configured. That requires only a few lines of code so it's very easy to get those examples and custom projects up and running on MGM12P.

The LNA is controlled via pins PD10 and PD11 which are routed only inside the module and not exposed on the pads. To configure those pins the following code needs to be added to InitDevice.c.

/* Add these macros at the top of InitDevice.c */
#define PRS_CH_CTRL_SIGSEL_RACLNAEN 0x00000003UL
#define PRS_CH_CTRL_SIGSEL_RACPAEN 0x00000004UL
#define PRS_CH_CTRL_SOURCESEL_RAC (0x00000051UL << 8)


/* Add this to PORTIO_enter_DefaultMode_from_RESET() */
// $[Port D Configuration]
GPIO_PinModeSet(gpioPortD, 10, gpioModePushPullAlternate, 0);
GPIO_PinModeSet(gpioPortD, 11, gpioModePushPullAlternate, 0);

PRS->CH[5].CTRL = PRS_CH_CTRL_SIGSEL_RACLNAEN  |
                                    PRS_CH_CTRL_SOURCESEL_RAC |
                                    PRS_CH_CTRL_EDSEL_OFF;

PRS->CH[6].CTRL = PRS_CH_CTRL_ORPREV |
                                    PRS_CH_CTRL_SIGSEL_RACPAEN  |
                                    PRS_CH_CTRL_SOURCESEL_RAC |
                                    PRS_CH_CTRL_EDSEL_OFF;

PRS->ROUTELOC1 |= PRS_ROUTELOC1_CH5LOC_LOC0;  // loc0 -> PD10
PRS->ROUTELOC1 |= PRS_ROUTELOC1_CH6LOC_LOC13; // loc12 -> PD11
PRS->ROUTEPEN |= (PRS_ROUTEPEN_CH5PEN | PRS_ROUTEPEN_CH6PEN);
// [Port D Configuration]$

KBA_BT_0804: Secure OTA DFU

platyrhynchos | 06/173/2017 | 12:06 PM
1. Introduction

The following article shows how to securely upgrade Bluetooth application OTA (over-the-air) using signed+encrypted upgrade files. The process is tested with Bluetooth SDK v2.8.1.

Gecko Bootloader

The Gecko Bootloader is a common bootloader for all Silicon Labs protocol stacks. It can load applications from different sources (internal flash, external flash, UART, SPI, over-the-air) using different protocols (XMODEM, BGAPI, EZSP SPI, Bluetooth etc.). It can be configured in a number of ways and its capabilities depend on the current configuration. In this training we demonstrate, how you can use it for loading a new application into the device sent over a Bluetooth connection.

Security features

The Gecko Bootloader has three security features:
- Authenticated (signed) upgrade file
- Encrypted upgrade file
- Secure Boot
Upgrade files are in a custom GBL (Gecko Bootloader) format. An authenticated upgrade file means that an electronic signature is attached to the GBL file. The signature is produced with a public-private key pair. The public key is stored in the device, while the private key is kept secret by the manufacturer. The signature ensures that the upgrade file is from a trusted source.

An encrypted upgrade file means that the content of the GBL file is encrypted to protect against eavesdroppers.

Secure Boot means that a signature is attached to the firmware image (.s37) BEFORE it is packed into upgrade file formal (.gbl). Note that this differs from authenticated upgrade file, as authenticated upgrade file means, that a signature is attached to the upgrade file AFTER the image was packed into GBL format. A signed image file (secure boot) ensures that the image was not modified since last boot, and that it is from a trusted source. This is checked at every boot. Upgrade file authentication is only checked while upgrading.

In this training we demonstrate how to use these security features.

OTA DFU

Over-The-Air Device Firmware Upgrade (OTA DFU) means that the device firmware can be updated via a Bluetooth connection.

To enable Bluetooth OTA update, the target device must be programmed with an appropriate Gecko Bootloader configuration and additionally with any Bluetooth application that supports OTA.

A Bluetooth application developed with Silicon Labs Bluetooth SDK comprises two parts.

Before Bluetooth SDK v2.7 the two parts are
- The Bluetooth stack + Supervisor (provided as precompiled binary code), referred to as Stack from now on
- The user application, referred to as App from now on
Since Bluetooth SDK v2.7 the two parts are
- The Apploader (provided as precompiled binary code), referred to as Apploader from now on
- The Bluetooth stack (provided as precompiled library) + user application, referred to as Application from now on
The OTA functionality is built into the Supervisor and into the Apploader code. If the device is restarted in DFU mode, the Supervisor / Apploader is started instead of the user application. This makes it possible to perform OTA update without any involvement from the user application.

The only requirement for the user application is for a way to trigger a reboot into DFU mode. Reboot into DFU mode can be triggered in a variety of ways. It is up to the application developer to decide which is most applicable. Most of the example applications provided in the Bluetooth SDK already have OTA support built into the code. In these examples, the DFU mode is triggered through the Silicon Labs OTA service that is included as part of the application’s GATT database.

There are two kind of OTA DFU processes:
- Partial OTA: In this case only the user application is upgraded. (Before v2.7 this really means only the user application. Since v2.7 the user application is linked together with the Bluetooth stack code, hence the stack is upgraded as well). In this case
1. The device is restarted in OTA mode, and the Stack / Apploader is started
2. The Stack / Apploader overwrites the old App / Application code with the new one. (Note: Slot0 is used to store the GBL headers during this upload process.)
- Full OTA: In this case the Stack / Apploader code is upgraded as well. Since the running code cannot overwrite itself, this process is done in 3 steps:
  
  The device is restarted in OTA mode, and the Stack / Apploader is started
  
  The new Stack/ Apploader code is uploaded into Slot0. This process is handled by the Stack / Apploader. Note: on 256kB devices Slot0 is in the user application area, which means that the App / Application is overwritten!
  
  Upon reset the bootloader copies the new Stack / Apploader code over the old one (extracting the binary from the stored GBL files).
  
  The new Stack / Apploader overwrites the old App / Application code with the new one. (Note: Slot0 is used to store the GBL headers during this upload process.)
For more details regarding OTA DFU using the Apploader please refer to AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications.

For more details about the legacy OTA DFU process, please refer to AN1045: Bluetooth ® Over-the-Air Device Firmware Update for EFR32xG1 and BGM11x Series Products.

2. Create and Build Bootloader

Create Bootloader Project

Since Gecko SDK Suite 1.0 / Bluetooth SDK 2.3.0 the Gecko Bootloader is included in the Bluetooth SDK. There are a number of predefined configurations available to help customers easily create new Bootloader projects for different purposes. Different bootloader configurations are recommended for different devices:
- In case of 256kB devices use Bluetooth in-place OTA DFU Bootloader configuration
- In case of 512kB devices use Bluetooth in-place OTA DFU Bootloader or Internal Storage Bootloader (single image on 512kB device)
- In case of 1024kB devices use Bluetooth in-place OTA DFU Bootloader or Internal Storage Bootloader (single image on 1MB device)
- You can also use an SPI Flash Storage Bootloader (single image) if you have an SPI flash connected to the device. But in this case it is better to implement an application uploader: https://www.silabs.com/community/wireless/bluetooth/knowledge-base.entry.html/2017/09/20/uploading_imagesto-DXxD
To create a new bootloader project:
1. Open Simplicity Studio, and select your device in the Devices or Debug Adapters tab
2. Check the Preferred SDK at the top of the main window
3. Click New Project button
4. Select Gecko Bootloader application type, click Next
5. Select the latest installed SDK, click Next
6. Select the appropriate bootloader configuration (e.g. Internal Storage Bootloader), click Next
7. Name your project, click Next
8. Check your device and choose toolchain. Click Finish
Add security features

After the bootloader project is created, the Application Builder automatically opens up. To add security features
1. Open the Plugins tab
2. Click on Bootloader Core
3. On the right side tick the checkboxes
  
  Require singed firmware upgrade files
  
  Require encrypted firmware upgrade files
  
  Enable secure boot
4. Click Generate in the upper right corner
Build Bootloader

After the bootloader code was generated by the AppBuilder, build your project:
1. Click on the build icon
Generate security keys

In order to use the security features of the Gecko Bootloader, encryption and signing keys need to be generated. These keys must be then written to the EFR32 device. The encryption key is used with the GBL file for secure firmware update. The signing keys are used both with the GBL file for secure firmware update and to sign the application image for Secure Boot.

You can create security keys with Simplicity Commander:
1. For ease of use add the Commander path (C:\SiliconLabs\SimplicityStudio\v4\developer\adapter_packs\commander) to the Path environment variable in your OS
2. Generate signing keys with the following command in command line
  
  commander gbl keygen --type ecc-p256 --outfile app-sign-key.pem
  
  This creates three files: app-sign-key.pem, app-sign-key.pem.pub, and app-sign-key.pem-token.txt. The first contains the private key (keep it secret), the other two contain the public key which has to be flashed to the device.
3. Generate encryption key with the following command in command line
  
  commander gbl keygen --type aes-ccm --outfile app-encrypt-key.txt
  
  This creates one file named app-encrypt-key.txt
Flash security keys

Write the two token files containing the encryption key and public key as manufacturing tokens to the device
1. Issue the following command:
  commander flash --tokengroup znet --tokenfile app-encrypt-key.txt --tokenfile app-sign-key.pem-tokens.txt
3. Create and Build Basic Application

Since OTA DFU is not fully implemented in the Bootloader, a minimal Bluetooth application has to be created and flashed to the device along with the Bootloader to support the upgrade.

Create Basic Application Project

To create a basic application that supports OTA DFU:
1. Open Simplicity Studio, and select your device in the Devices or Debug Adapters tab
2. Check the Preferred SDK at the top of the main window
3. Click New Project button
4. Select Bluetooth SDK, click Next
5. Select the latest installed SDK, click Next
6. Select SOC - Empty sample application, click Next
7. Name your project, click Next
8. Check your device and choose toolchain. Click Finish
Build Application

The application code is automatically generated after the project was created. The SoC – Empty sample application contains everything needed for OTA support (OTA service and characteristics + code to support to restart the device in DFU mode). To build the application:
1. Click on the build icon
Sign the Application Image

Since Secure Boot was enabled in the bootloader, only signed application images can be booted. If you want to use OTA DFU, you have to sign the Stack / Apploader and the App / Application parts of the image separately, because they will be updated separately! In order to add a signature to the Stack / Apploader and to the App / Application image:
1. Copy app-sign-key.pem (from the folder in which you ran the commander gbl keygen command) into your project
2. Run the create_bl_files.bat batch file found in your project, which will create the signed GBL files into the output_gbl folder
4. Upload Bootloader and Basic Application

After both Bootloader image and Application image are ready, upload them to the device:
1. Copy the *-combined.s37 file from the output folder (named after the compiler) of the bootloader project to the output_gbl folder of the Bluetooth application project. Note: The *-combined.s37 file contains the full bootloader – while other output files in this directory contain only the second stage of the bootloader!
2. Merge the bootloader image with the application
  
  Using Bluetooth SDK v2.6.x or earlier, merge the Bootloader, the Stack and the App images
  commander convert bootloader-storage-internal-single-combined.s37 stack-signed.gbl app-signed.gbl --outfile bootloader+stack+app.s37
  
  Using Bluetooth SDK v2.7.x or later, merge the Bootloader, the Apploader and the Application images
  commander convert bootloader-storage-internal-single-combined.s37 apploader-signed.gbl application-signed.gbl --outfile bootloader+stack+app.s37
3. Open Simplicity Commander GUI by starting commander.exe
4. Connect to the Adapter
5. Connect to the Target Device
6. Select Flash tab
7. Flash bootloader+stack+app.s37 to the device
5. Create and Build Upgrade Application

Create Application Project

Create the application you want to upgrade the device to. In this example we will use the Thermometer sample application for this purpose. Similar to the creation of the Basic Application:
1. Open Simplicity Studio, and select your device in the Devices or Debug Adapters tab
2. Check the Preferred SDK at the top of the main window
3. Click New Project button
4. Select Bluetooth SDK, click Next
5. Select the latest installed SDK, click Next
6. Select SOC - Thermometer sample application, click Next
7. Name your project, click Next
8. Check your device and choose toolchain. Click Finish
Build Application

The application code is automatically generated after the project was created. To build the application:
1. Click on the build icon
Create Signed and Encrypted Upgrade Files from the Image

The bootloader accepts upgrade images in .gbl format. To create .gbl files from the image and sign/encrypt it
1. Copy app-sign-key.pem and app-encrypt-key.txt into your project
2. Run create_bl_files.bat
3. Check upgrade files in output_gbl folder within your project
6. Upgrade your Device

Now your device can be upgraded OTA from the basic application to the upgrade application. For this you need another device which will send the new firmware to the target device via Bluetooth. In this example a smartphone will be used for this purpose.
1. Download and install Blue Gecko app ( http://silabs.com/bluegeckoapp ) to your smartphone
2. Create a new folder under /SiliconLabs_BGApp/OTAFiles/ on your smartphone. E.g. call it my_app
3. Open the output_gbl folder in your project
4. Copy the upgrade files from your computer to your smartphone. If you use Android, copy the upgrade files into /SiliconLabs_BGApp/OTAFiles/my_app folder. If you use iOS, upload the upgrade files to iCloud.
  
  If you use Bluetooth SDK v2.6.X or earlier, then copy stack-signed-encrypted.gbl and app-signed-encrypted.gbl
  
  If you use Bluetooth SDK v2.7.X or later, copy apploader-signed-encrypted.gbl and application-signed-encrypted.gbl
5. Open Blue Gecko app
6. Select Bluetooth Browser
7. Find your device. The basic app advertises itself as Empty Example. Since there might be other devices advertising around you with the same name, place your smartphone close to your device and find the one with the highest RSSI
8. Click on your device to connect to it
9. Open the context menu in the upper right corner and select OTA
10. Choose Full OTA
11. Select my_app folder, then select stack-signed-encrypted.gbl OR apploader-signed-encrypted.gbl as “stack” and app-signed-encrypted.gbl OR application-signed-encrypted.gbl as “app”
12. Click OTA
13. After upload finished, you should see your device advertising itself as Thermometer Example in the Bluetooth Browser
Getting the Most Out of Bluetooth 5 - Webinar Q&As

Siliconlabs | 06/172/2017 | 02:03 PM

The Q&As are based on the webinar, Getting the Most Out of Bluetooth 5, which was held on 17th May 2017. If you were not able to attend the webinar, you can watch a recording of the webinar:

http://www.silabs.com/webinars/getting-the-most-out-of-bluetooth-5

Q: Approximately when will 5.0 be incorporated in iOS and Android phones? I.e. when will the 4x range of 5.0 be achievable with my product that links to smartphones?

Galaxy S8 is the first phone to support Bluetooth 5. Currently, it only supports 2M PHY. iPhone 7 also accepts 2M PHY connections, but officially it claims to be a 4.2 phone. We are not sure when LE Long Range and/or advertisement changes will be adopted but will be monitoring it.

Q: Do you provide consumption simulator?

Yes, we do. Simplicity Studio has a tool called energy profiler, which measures current consumption in real time

Q: Which curves does the ECC module support?

You can see all the supported modes from this document: https://www.silabs.com/documents/public/reference-manuals/efr32xg12-rm.pdf

Q: In current API we can use automatic ADV data generation or prepare UserAdv data. Is there plan to add API for simplified build ADV data? For example, I want to prepare Manufacturer specific data (code FF) myself, but that stack take care about other data, like TX power, flags and so on.

Currently, you need to pretty much build the ADV data yourself, but our support team could help you can make an example that makes it easier to use.

The Bluetooth Developer Studio allows you to graphically build the advertisement data and you could develop a simple plug-in for the Bluetooth Developer Studio, which generates the C code to build the advertisement data.

Q: Is Keil uVision supported in the future for the development with blue gecko devices?

At the moment we support GCC and IAR and unfortunately, there are no plans to add Keil support in the near term future.

Q: Does Silicon Labs Bluetooth stack support RTOS?

Today we work on supporting Micrium Kernel with the Bluetooth stack and the target release in the Q3’17 SDK.

Q: Does Silicon Labs plan to provide a certified stack for Apple HomeKit?

Yes. Silicon Labs provides Apple HomeKit over Bluetooth. Our current HomeKit SDK v1.2.0 implementation is Apple HomeKit R9 compliant already and we are already working for the upcoming R10 changes.

Q: Do BGMxxx modules support for Bluetooth 5?

BGMxxx modules have already support for Bluetooth 5 advertisement sets and scan event reporting. In Q4’17 there will be modules with full Bluetooth 5 support including LE long range and 2M PHY.

Q: Does Mighty Gecko family also support Bluetooth 5?

Yes, the EFR32MG12 supports Bluetooth 5 (2M PHY) and EFR32MG13 supports both Bluetooth 5 2M PHY and Bluetooth 5 LE Long Range.

Q: Can EFR32BG12 / 13 support be a Bluetooth LE slave and master at the same time?

Yes. We can support any combination of master and slave connections up to 8 simultaneous connections at least.

Q: What qualifies a Bluetooth end product for licensing?

All end devices using Bluetooth trademarks and IP must be end product listed. There are a few different schemes how to qualify the end product depending on your situation, but in most cases, any testing can be omitted by using our qualified SW and RF-PHY.

Q: What are the requirements for certification when using a certified module with our own firmware using the SDK?

The firmware doesn't affect the certification requirements. Our modules are modular approved where available, which allows you to integrate the HW to your design and just reference to our grants (for example FCC). Then in some regions, you can use some parts of our certification test results in your self-declaration, but need to do some tests to your end product (CE). The best approach is to take a test house to navigate through the different regional requirements. You can find our materials what we offer from our website.

Q: Are there licensing costs when distributing a product using Bluetooth? If there is, is it an annual or one-time fee?

If you make an end product using Bluetooth, you need to do a Bluetooth End Product listing, which will cost from $2500-8000 depending on your company size and revenue. We make pre-certified modules, which help you to minimize the costs of implementing Bluetooth and radio in end products. Licensing fee is one-time fee per product or product line.

Q: Are modules planned to certificate with SRRC?

This is not in the plan today, we are investigating this but have not reached a conclusion. If you see a strong demand for this don't hesitate to let us know.

Q: Can the 1438 kbps throughput at 2Mbps be divided between multiple nodes in the network? Or does bandwidth not divide evenly?

It will be divided if you have multiple nodes and the TX/RX is time division multiplexed. How it's divided among the nodes, depends typically on the implementation.

Q: How many simultaneous connections do a Blueooth 5 device support?

This is implementation specific and typically comes down to the amount of RAM you have. We officially support 8 connections today and have tested that we can get it up to 12 slave connections at least.

Q: How is the power usage of Bluetooth 5 compared to Bluetooth 4?

It depends on the features used. The TX/RX peak figures are typically the same as with Bluetooth 4. With 2M PHY the TX/RX times are half of what they are with 1M PHY, so your average power consumption can be 50% lower. If you use LE Long Range the TX and RX times will be quite a bit longer which also increases power consumption.

Q: Is Bluetooth 5 backwards compatible with Bluetooth 4?

Yes, it is. Bluetooth 5 devices are fully backward compatible, but of course, the new features like 2M PHY and LE Long Range will not be available.

Q: Is it possible to handle connections with 2M PHY and old BT4 PHY at the same time?

It is possible. In BT5 Different connections and/or even individual packets can use different PHYs.

Q: Does Bluetooth 5 add any features to Bluetooth Classic?

Not really, as it is mostly focused on new features of the BLE

Q: Will we be able to remotely change Tx power?

Yes, you can implement a GATT service and characteristic, which you can write remotely and change the TX power.

Q: Can we switch ADV speed from 1M tо 125kbps?

Yes you can. You can advertise with 1M and LE long range on the primary channels and the secondary channels can use any PHY.

Q: Will there be Bluetooth 5 modules with multiple antennas?

Possibly, especially when the indoor positioning specifications are released with Bluetooth 5.1.

Q: Can we use Bluetooth 5 solution from SiLabs with PA/LNA?

You can, but we have variants with built-in PAs that go up to 19dBm. You can still use an external PA/LNA if you like and our software can automatically control the PA/LNA with a GPIO pin.

Q: What is the acquisition time for two new devices connecting (e.g. a Bluetooth device say a tag being taken passed say a mobile phone with its BT open to connect)?

This related to the scanning and advertising intervals heavily, so the longer the periods the longer it takes to connect. In the best-case scenario, we are talking about some hundreds of milliseconds but it can be some seconds in the worst case.

Q: Can Bluetooth 4 and Bluetooth 5 be used in access control system (PACS) without paring process?

You could encrypt the application data, and achieve application level security without going through the pairing process and encrypting the link. in this case the link would be plain text.

Q: How we can get your roadmaps about Bluetooth stack development?

You will get this via your local sales person under NDA.

Q: Are you planning also to offer a Bluetooth USB Dongle variant for Bluetooth 5, like the Silicon Labs Bluegiga BLED112 Bluetooth 4 Dongle?

We are thinking about this, but the plan is not fully confirmed. If you are interested in such a product, please contact our sales or field marketing and we'd be happy to discuss the details with you.
BT121 - Recognizing a custom firmware from host and by the CRC checksums in a firmware image file

enr_tad | 06/172/2017 | 11:57 AM

In some cases there is the need to be able to recognize a custom firmware either from the host MCU or by analyzing a firmware image .bin file. This article gives a couple of ideas on how to do that, while the chance is taken to provide some information about an image's CRC checksums.

At boot, the module will always send out an event (dumo_evt_system_boot) carrying the firmware version and build number. This is the principal way to recognize the firmware release and the SDK that was used to generate the firmware running in the module, but it does not tell anything about possible different custom firmwares that were generated with the same SDK.
One possible additional way for your host MCU to retrieve the custom version of a custom firmware of yours currently installed in your module, is to store such version number in the Firmware Revision String characteristic that you would add under the Device Information service.
This is a characteristic defined by the spec (see https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.service.device_information.xml) and the value stored in such characteristic via the gatt.xml can be read at any time by the host MCU with the BGAPI command dumo_cmd_gatt_server_read_attribute_value(handle,0)
You might enter the new characteristic into your gatt.xml under the <service uuid="180A"> tag as below:

<characteristic uuid="2A26" id="fw_rev">
<properties read="true" const="true" />
<value>my_utf-8_string</value>
</characteristic>

In the BGAPI command above you will then use the characteristic's handle number (not the UUID / handle number is revealed in the file called "constants" being generated by the bgbuild.exe according to the id="..." inside the <characteristic> tag) to retrieve the firmware custom version number which was in fact hardcoded into the firmware via the gatt.xml and its Firmware Revision String characteristic at the time the firmware was built.

As for recognizing that a particular .bin image file corresponds to a custom firmware of yours, you can consider the last bytes of the image: they contain the CRC checksums for the image and are unique for every different firmware, so you could have a table matching one (or more) of the CRC checksums and a firmware revision, and then use the checksum(s) to recognize which custom firmware of yours a certain image file corresponds to.
More in detail, an image file contain three CRC checksums that are verified at boot, one for the firmware, one for hardware configuration, and a third for imported files like SDP records and BGScripts. These are found in the last bytes of an image, starting at address 0x1efd8, and easily recognized in a HEX editor as they start at the border of the 0xFF bytes.
Here is an example of what you will find at the end of the .bin file starting from the address of 0x1efd8:

00 00 00 00 --> Address of fw segment
88 AF 01 00 --> Size of segment
7A BD 78 E8 --> CRC32 of segment
88 AF 01 00 --> Address of hw segment
8A 00 00 00 --> Size of segment
F4 53 64 85 --> CRC32 of segment
14 B0 01 00 --> Address of files segment
C7 01 00 00 --> Size of segment
B1 2A 91 CD --> CRC32 of segment
03 00 00 00 --> 3 segments defined

So, all in all, taking one of the CRC checksums or all the information above should provide you with a good unique identifier revealing which of your custom firmwares an image file corresponds to.
A few additional pieces of information follows. The segment addresses above are relative to the chipset flash memory boundary address of 0x8001000 (0x1000 in the firmware image, where bootloader uses 0x0 to 0xfff) - About the CRC checking of the three checksums, this is performed by the bootloader at boot, and in case of failure the module will automatically enter the BGAPI-based DFU mode.
KBA_BT_0301: LE Coded PHY on EFR32xG13

tmonte | 06/166/2017 | 01:09 PM
Introduction

Bluetooth 5.0 introduces a new long range PHY (LE Coded PHY) with 125kbps and 500kbps coding which gives range gains of 1.5-2x with improved sensitivity of 4 to 6dB.

The LE Coded PHY uses 1Mbit PHY but payload is coded at 125kbps or 500kbps. It also adds Forward Error Correction and Pattern Mapper.

Note: LE Coded PHY is only supported on EFR32xG13 devices.

Using the LE Coded PHY

Changing to LE Coded PHY can be requested from either slave or master device using the command gecko_cmd_le_connection_set_phy(connection, phy), where the phy value maps as follows:

0x01: 1Mbit PHY

0x02: 2Mbit PHY

0x04: 125kbit Coded PHY (S=8)

0x08: 500kbit Coded PHY (S=2)

For compatibility reasons the default PHY is always 1Mbit. This must the PHY used for advertising as well as establishing the connection. Once the connection is formed either side (master or slave) can request a new PHY to be taken into use. The PHY requests can be issued at any point during the connection and the stack takes care of negotiating the new PHY usage and notifying the application of whether the new PHY has been taken into use or not.

When a new PHY is requested it will take a minimum of 6 connection intervals for the device to switch to the new PHY. Once the PHY switch occurs the event le_connection_phy_status is raised by the stack to notify the application of the new PHY setting.

Note: From SDK 2.8.1 onward it's possible to scan and advertise on LE Code PHY and therefore the connections can also be established using over that PHY. Please refer to this KBA for further information and a code example: Advertising and Scanning with LE Coded PHY

In the case of using 2 EFR32xG1x devices the event le_connection_phy_status will be raised on both devices in the following situations (if the new PHY request is accepted by the receiving device):

Switching to/from LE Coded PHY from/to another PHY (1Mbit/2Mbit)

Switching from 1Mbit to 2Mbit PHY and vice-versa

The event le_connection_phy_status will only be raised on the requesting device when:

The new PHY request is not accepted (e.g. the receiving device doesn’t support it)

Switching LE Coded PHY coding (from S=2 to S=8 and vice-versa) when LE Coded PHY is already in use

The reason is that changing the coding is not negotiated over-the-air, it’s done only locally on the requesting device and the receiving device continues using the same coding. At the RX stage the radio detects the coding based on the packet preamble and it can use a different coding for the TX stage.

An additional note is that the default coding for LE Coded PHY is S=8 (125kbit). This means that when an EFR32BG13 accepts a PHY change request to LE Coded PHY it will default to S=8. It is up for the application to change the coding if desired and the new coding will then be used if the PHY is again changed to 1Mbit/2Mbit and then back to LE Coded PHY.

Examples

Here are a few examples of changing between the PHYs using 2 EFR32xG13 devices in NCP mode and controlled with BGTool.

Changing to LE Coded PHY (S=8, 125kbit)

In this example the devices are connected using a 512ms connection interval. After the PHY change command is issued it takes ~5s to get the event which is raised on both devices.

Changing the Coding While in LE Coded PHY

As explained earlier in this article changing the coding is not negotiated over-the-air between the devices and for that reason the event le_connection_phy_status is only raised on the requesting side and very shortly after the command is sent. The receiving device will continue using the same coding.

Attempted Change to LE Coded PHY

In the example below a new PHY request is attempted but the other device is an EFR32BG1 which only supports 1Mbit PHY so the event le_connection_phy_status is immediately raised on the requesting device to notify that the PHY has not been changed and no event is raised on the receiving device.

Impact on Energy Consumption

Using LE Coded PHY will lead to higher current consumption due to the longer RX/TX periods. The next images show the current profile of a notification packet with 20 bytes of data payload on all the PHYs. The red blocks are highlighting the duration of the entire wake-up period and the average current consumption for said period.

These measurements were made from the slave device (RX precedes TX) with TX Power of 0dBm and the images are sorted from shortest to longest RX/TX periods: 2Mbit, 1Mbit, LE Coded S=2 (500kpbs) and LE Coded S=8 (125kpbs)

Note: When using LE Coded PHY the packet header is always coded with S=8 but the payload can be S=2 or S=8 coded and that is indicated by a bit in the header. This means that empty packets will not have a significant difference between S=8 and S=2 coding in terms of TX duration.

2Mbit PHY

1Mbit PHY

LE Coded PHY (S=2, 500kbps)

LE Coded PHY (S=8, 125kbps)

Indoor Range Tests

The image below shows the result of range test in one of our offices. On the top right corner we placed an EFR32BG13 and then we walked around with a second EFR32BG13 kit to check the connection boundary.

Comparing between 1Mbit PHY and LE Coded PHY (125kbps) the range is roughly double due to the sensitivity improvements.
KBA_BT_0308: Polymorphic GATT

tmonte | 06/165/2017 | 01:47 PM
Introduction

The Bluetooth SDK 2.4 introduced a new feature called Polymorphic GATT which can be used to dynamically show or hide GATT services and characteristics.

This new feature allows customers to create a ‘superset’ GATT database with pre-defined hidden/visible services and characteristics and then alter their visibility on the fly.

How it Works

The visibility of services and characteristics is controlled through the use of GATT capabilities. The usage of capabilities and their syntax in the GATT xml file is fully described in 'UG118: Blue Gecko Bluetooth Profile Toolkit Developer's Guide', specifically in sections 2.3, 2.4.1 and 2.5.1 with a usage example in section 2.6. It's important that you read through these sections to get a good grasp of the visibility and inheritance rules.

In summary each service/characteristic can declare a number of capabilities and the state of the capabilities (enable/disable) determines the visibility of those services/characteristics as a bit-wise OR operation e.g. the service/characteristic is visible when at least one of its capabilities is enabled and it’s not visible when all of its the capabilities are disabled.

Note: If certain services/characteristics are meant to be always visible then one good approach is to have one capability that is declared by those services/characteristics which is enabled by default and untouched by the application code.

Using VGE

The Simplicity Studio VGE (Visual GATT Editor) already supports the polymorphic GATT database and it allows to declare capabilities for the whole GATT database as well as subsets for each of the services and characteristics.

You must always start by declaring the GATT-level capabilities and define their default value. That is done by selecting "Custom BLE GATT" and adding the capabilities in "Capability declaration". To add a capability just press the '+' on the right-hand side and then change the capability name and default value.

Once those capabilities are added they become available on each of the services and characteristics. They can be added through the '+' control but this time you'll be shown the list of capabilities declared at the GATT-level where to pick from.

Example

The attached example shows how the capabilities can be used to change the visibility of services and characteristics to a GATT client. The usage of the example is shown in the below video.

Note: Changing the capabilities state should not be done during a connection as that can cause misbehavior. The safest way is to change the capabilities when no devices are connected.

Declaring the Capabilities in the GATT

In this example there are 5 capabilities which are all enabled by default. The GATT was created using VGE which generates the gatt.xml and gatt_db.c/.h files used to build the project.

Looking into the gatt.xml file we can see all the capabilities declaration as they are explained in UG118.

<gatt generic_attribute_service="true" header="gatt_db.h" name="Custom BLE GATT" out="gatt_db.c" prefix="gattdb_"> <capabilities_declare> <capability enable="true">ota</capability> <capability enable="true">temp_measure</capability> <capability enable="true">temp_type</capability> <capability enable="true">interm_temp</capability> <capability enable="true">meas_interv</capability> </capabilities_declare>

The first 2 services in the GATT database, Generic Access and Device Information, don’t declare any capabilities so they will inherit all the capabilities from the GATT as per the inheritance rules described in UG118 section 2.3.1. This means that if all the capabilities are disabled then these services and all their characteristics will be hidden from a GATT client.

Then the OTA service declared the ota capability which means that the state of this capability alone will determine the visibility of the OTA service.

<service advertise="false" name="Silicon Labs OTA" requirement="mandatory" sourceId="com.silabs.service.ota" type="primary" uuid="1D14D6EE-FD63-4FA1-BFA4-8F47B42119F0"> <informativeText>Abstract: The Silicon Labs OTA Service enables over-the-air firmware update of the device. </informativeText> <capabilities> <capability>ota</capability> </capabilities>

The Health Thermometer service declares the remaining 4 capabilities. Then each of the 4 characteristics under this service declares only one of those capabilities, allowing their visibility to be individually controlled.

<service advertise="false" id="health_thermometer" name="Health Thermometer" requirement="mandatory" sourceId="org.bluetooth.service.health_thermometer" type="primary" uuid="1809"> <informativeText>Abstract: The Health Thermometer service exposes temperature and other data from a thermometer intended for healthcare and fitness applications. Summary: The Health Thermometer service is instantiated as a Primary Service. There are one or more instantiations of the Health Thermometer service per device claiming conformance with this specification. </informativeText> <capabilities> <capability>temp_measure</capability> <capability>temp_type</capability> <capability>interm_temp</capability> <capability>meas_interv</capability> </capabilities>

Enabling/Disabling Capabilities

The capabilities are enabled/disabled with the API command cmd_gatt_server_set_capabilities(caps, reserved) where caps is the bit flags of each capability which should be set to 1 if the capability is to be enabled or 0 if it's to be disabled.

The auto-generated gatt_db.h contains the bit flag value for each of the capabilities.

typedef enum { ota = 0x0001, temp_measure = 0x0002, temp_type = 0x0004, interm_temp = 0x0008, meas_interv = 0x0010, bg_gattdb_data_all_caps = 0x001f } bg_gattdb_data_cap_t;

If for example we would want to enable ota and temp_type and disable all other capabilities the command call would look like this: cmd_gatt_server_set_capabilities(ota | temp_type, 0);

In this example we declare a variable to hold the state of all the capabilities at any given time (uint8_t capabilities). The enumerated bit flags are not being used but instead an index (uint8_t capability_selected) keeps track of which capability is selected in the display and changes the correct bit in capabilities according to the button presses (each button press will toggle the capability between enable and disable, which in practice is setting and clearing the corresponding pin in capabilities variable).

void handle_button_change(uint8_t pin) { if(pin == 6) { // If PB0 was pressed change the selected capability capability_selected++; if(capability_selected == 5) capability_selected = 0; // wrap around } else { // If PB1 was pressed swap the capability status: enabled->disabled and vice-versa if(capabilities & (1<<capability_selected)) { capabilities &= ~(1<<capability_selected); } else { capabilities |= (1<<capability_selected); } // API commands cannot be called from within interrupt context, send external signal to be handled by the stack gecko_external_signal(CAPABILITIES_CHANGED); } }

Because API commands cannot be called from within interrupt context when a capability status is changed we send an external signal to the stack so that it can be handled in the main loop.

case gecko_evt_system_external_signal_id: // The capability status was changed if(evt->data.evt_system_external_signal.extsignals == CAPABILITIES_CHANGED) { gecko_cmd_gatt_server_set_capabilities(capabilities,0); } break;

The stack monitors the local database change status and manages the service changed indications for a GATT client that has enabled the indication configuration of the Service Changed characteristic. The Service Changed characteristic is part of the Generic Attribute service and it can be added to the GATT by adding generic_attribute_service="true" to the <gatt> element (as shown in the first gatt.xml snippet in this article).
GATT_capabilities_example.zip
KBA_BT_1404: Migrating Simplicity Studio projects from Bluetooth SDK 2.3.x to 2.4.x

baadamff | 06/163/2017 | 01:37 PM
To migrate a project from Bluetooth SDK 2.3.x to SDK 2.4.x follow the steps described below.

Install SDK 2.4.x via Simplicity Studio Package Manager

Go to Window->Preferences then select Simplicity Studio-> SDKs

Disable older BLE SDK versions

OPTIONAL - You may use different workspace for the new SDK projects. In this case you need to import the project made with previous SDK to the new workspace.
For importing use the Eclipse built in importer. Go to File->Import.. then choose General->Existing projects into Workspace.
Enable the Copy projects into workspace option.

Open the .isc file on your project folder with text editor.

Add the sourceSampleAppId: soc-empty line to the file.

Save and close the file.

Double click on the .isc file and press generate on the GUI. Wait until generation finished.

OPTIONAL – You may delete the excluded files from the project. These are grayed out by studio.

Open the main.c and remove the pre-processor directives start from #ifndef GENERATION_DONE

Now your project should build with the new 2.4.x SDK .
KBA_BT_1005: Reporting Battery Voltage over BLE

bluetoothsteve | 06/153/2017 | 02:35 PM
Introduction

The Bluetooth SIG defines a battery service. The definition can be found in Bluetooth SIG GATT Service List. This article discusses how to create an application to monitor the battery voltage and report it as a percentage of full charge, as defined by the specification above.

Implementation

Start by creating an SoC - Empty sample app for your chosen hardware.
1. In the project menu select new | Silicon Labs appBuilder project.
2. Select Bluetooth SDK and click next
3. Select the latest Bluetooth SDK and click next
4. Select SOC – Empty and click next
5. Enter a name for the project and click next
6. Replace existing app.c with the app.c attached to this article
7. Copy em_adc.c and em_adc.h from the SDK to the project folder if they aren't already in the platform->emlib->inc/src folders.
Next, add support for the battery service to your application by setting up your GATT database to include the service as shown below

Once you’ve dragged the battery service as shown, change the type of the ‘battery level’ characteristic to ‘user’. Now select the ‘Device Name’ characteristic and change the value to ‘BattMon’ then click Save and then Generate. For this example, only the read property is enabled, the notification property is optional and so it is disabled.

Next, it will be necessary to add the capability to measure the voltage. This can be done using the EFR32’s ADC without the need for any external GPIO.

In the attached app.c file, you will find functions which contain all of the code necessary to set up the ADC. The initial setup is performed by init_adc_for_supply_measurement(). This function mostly uses the defaults for the ADC with a few important adjustments. The inputs to the ADC are chosen to be AVDD and VSS. The reference voltage is chosen to be the internal 5V reference. It is also necessary to choose the attenuation factors for the input voltage and the reference voltage. The following formulas are taken from the ADC section of the EFR32 reference manual. The attenuation factor for the reference voltage is defined as

ATTVREF = (VREFATT + 6) / 24 for VREFATT < 13, and (VREFATT - 3) / 12 for VREFATT ≥ 13

And the attenuation for the input voltage is defined as

ATTVIN = VINATT / 12 for VINATT ≥ 3 (settings 0, 1, and 2 are not allowable values for VINATT)

The ADC is set up for 12 bit conversions, which results in a total of 4096 steps per conversion. The attenuation factor for the input voltage is chosen to 1 and the attenuation factor for the reference voltage is set to be 0.5. The full scale voltage for conversions is determined as follows

VFS = 2 × VREF × ATTVREF / ATTVIN

In our example,

VFS = 2×(5.0)×(0.5)/(1) = 5.0 V

And the number of volts per division, VFS/4096 = 1221 μV/division

Using this information we can determine the battery supply voltage.

In app.c you will find a function called read_supply_voltage() which can be used to read the ADC converted value and return it as the battery voltage in mV.

The boot handler for the application starts a soft_timer to schedule an ADC conversion once per second. The handler for the timer starts a conversion and then reads the converted value. The specification for the service requires the value to be reported as a percentage so the measured voltage is converted to a percentage of 3300 mV. This value is then used in the read request handler.

Running the Example

To run the example, build the project and flash it to your hardware. Open the BlueGecko app on your mobile, then open the Bluetooth Browser tab and connect to the device, the name will display as “BattMon”. Expand the Battery Service and then expand the Battery Level characteristic to view the Battery charge level.

Additional Reading
app.zip

app.h

Battery_Monitor_SDK_v2_12_2.zip

app.c