Question: What is a STEP file?

Answer:

A STEP [STandard Exchange of Product model data] file is a CAD file format defined by ISO 10303-21 to represent 3D models of components and assemblies. Since STEP files conform to the ISO standard, they are not vendor or software specific and have been adopted by the majority of ECAD and MCAD [Electronic and Mechanical Computer Aided Design] tools and systems.

STEP files are helpful to understand the physical dimensions of a particular product in a 3D domain. STEP files are also helpful to understand the area required by the part on the PCB during component placement in the mechanical assembly.

The following figure shows a sample for the preliminary STEP files for BGM13P22GA (Built-In Antenna) and BGM13P22GE (External Antenna) variants:

Question: How to obtain it?

Answer: 

As of Q3 2020, STEP files can now be directly downloaded from the Technical Resource Library available on our website or through the following link: https://www.silabs.com/support/resources.ct-schematic-and-layout-files?query=step

If there is any STEP file for a typical wireless module that is not available on the website, then respective Preliminary STEP files can be obtained from Silicon Labs by contacting the Technical Support team. 

There are different STEP files for different part variations.  For example, the BGM13PGA (built-in antenna) STEP file is different from the BGM13PGE (external antenna) STEP file. The example highlights the difference between a Bluetooth module with a U.FL connector versus a module with a chip antenna.  When requesting STEP files, please include the correct part number so that the correct file can be provided.  Once received, please refer to your CAD's website or help for instructions on how to import STEP files.

To obtain a STEP file for a standard package such as QFN32, QFN48, etc, please contact our Technical Support team where you will receive a .bxl [Binary eXchange Language] file, which is a proprietary file format for vendor-neutral CAD data created by UltraLibrarian tool available on our website. Once you receive the .bxl file, please follow the instructions on the CAD/CAE webpage to generate appropriate files for your project.

Introduction

Silicon Labs offers a quality selection of documentation and training material on its Bluetooth products. These should typically suffice for most customers to get up and running with our products and develop their Bluetooth applications.

Some customers might want to dig deeper into the Bluetooth stack behavior and understand some of the underlying concepts. A good place to look is the Bluetooth Core Specification but given the size of this document it's easy to get overwhelmed with the amount of information.

The Bluetooth SIG provides other extremely useful resources which can be leveraged by Silicon Labs customers help bring their products to market faster.

Training videos

On the Bluetooth SIG there is a selection of training videos on topics ranging from the lower layers of the stack to Bluetooth development on iOS/Android mobile platforms.

Educational kits

There are also educational kits available which touch not only embedded Bluetooth stack but also Bluetooth application development on mobile.

They are based on 3rd part and freely available hardware (Arduino, Raspberry Pi) and target both Bluetooth Low Energy as well as Bluetooth Mesh.

For Bluetooth Low Energy the Bluetooth Developer Starter Kit is a good starting point and it contains template projects to develop mobile applications for Android (using Java) and iOS (using Swift). The

For Bluetooth Mesh there is the Mesh Developer Study Guide which includes simple coding exercises to learn some of the most important Bluetooth Mesh concepts.

Bluetooth Qualification

All products deploying Bluetooth technology must go through the Bluetooth SIG's Qualification Process. There are online resources to learn more about the Bluetooth Qualification Process as well as Start Guide on the Launch Studio which is the online tool used to complete the Bluetooth Qualification Process.

The Bluetooth QDIDs for Silicon Labs components can be found in QSG139: Getting Started with Bluetooth® Software Development, on section 2.2.

Note: This KBA has been marked as deprecated. A more updated KBA can be found here: Waking from Deep Sleep Using RF Sense

Introduction

The EFR series of energy friendly radios have the ability to wake themselves upon detecting an RF signal. This article discusses how to use this feature with the Silicon Labs Bluetooth stack. Discussion The rfsense feature can be used to wake the device in any energy mode. This feature is accessed through a RAIL command so the first step is to initialize an additional RAIL configuration. The Bluetooth stack is also built on RAIL so the multiprotocol library is required to be used here. A simple RAIL_CONFIG_t struct can be used with most parameters left NULL. static RAIL_Config_t railCfg = { .eventsCallback = NULL, .protocol = NULL, .scheduler = &railSchedState, };

A call to RAIL_Init with a pointer to this struct is made to initialize the RAIL configuration. railHandleRfsense = RAIL_Init(&railCfg, NULL); Once the RAIL configuration is done, rfsense can be enabled. The rfsense feature in EFR32 can accessed through the RAIL command RAIL_StartRfSense(). This command takes 4 parameters : RAIL handle, the band, sensetime and callback. More specific information on this command can be found in the RAIL API reference guide which is accessible from the launcher view in SimplicityStudio. Once the call to RAIL_StartRfSense() is made, it is safe to go to EM4. Building the Application This section describes how to build the example based on the soc-empty-rail-dmp sample. This sample is used because it has all of the necessary settings to support multiprotocol.

1. Start by generating a copy of the soc-empty-rail-dmp sample app.
2. Add app.c to the project by copying it to the project folder
3. Add a call to appMain() just before the while loop in bluetoothAppTask()
4. Remove the �static� keyword from the definition of boot_to_dfu as follows to make it accessible from app.c //static uint8_t boot_to_dfu = 0;
5. Comment out the following call to OSTaskCreate that starts the proprietaryAppTask /* OSTaskCreate(&proprietaryAppTaskTCB, "Proprietary App Task", proprietaryAppTask, 0u, PROPRIETARY_APP_TASK_PRIO, &proprietaryAppTaskStk[0u], (PROPRIETARY_APP_TASK_STACK_SIZE / 10u), PROPRIETARY_APP_TASK_STACK_SIZE, 0u, 0u, 0u, (OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR), &err); APP_RTOS_ASSERT_DBG((RTOS_ERR_CODE_GET(err) == RTOS_ERR_NONE), 1); */

1. Build the project.

Example Walkthrough

In the provided example application, we start advertising for a fixed period of time. If no connection is made during this time, the device stops advertising, starts rf sense and goes into EM4 sleep mode. The system_boot event performs several tasks. The first is that begins advertising to allow connections. The second task is to initialize the RAIL configuration. At this point it is also necessary to disable RFsense to avoid problems receiving packets. Lastly, a 30 second timer is started. RAIL_StartRfSense(railHandleRfsense,RAIL_RFSENSE_OFF ,RFSENSE_TIME_MIN,rfsense_callback); gecko_cmd_hardware_set_soft_timer(INACTIVITY_TIME,1,1);

The timer will be used to stop advertising, start rf sense and go into EM4 mode. This is handled in the gecko_evt_hardware_soft_timer event.

case gecko_evt_hardware_soft_timer_id: gecko_cmd_le_gap_stop_advertising(0); RAIL_StartRfSense(railHandleRfsense,RAIL_RFSENSE_2_4GHZ,RFSENSE_TIME_MIN,rfsense_callback); EMU_EnterEM4(); break;

If a connection is formed, the gecko_evt_le_connection_opened event stops the timer to prevent going into EM4. case gecko_evt_le_connection_opened_id: // if a connection is formed, stop the timer. gecko_cmd_hardware_set_soft_timer(0,1,0); break; The easiest way to track the sleep mode is with the Energy Profiler. In EM4 the current consumption will be around 1.5 uA. To try this out, build and flash the application to your desired device, open the Energy Profiler and start the energy capture. After reset the average current will be approximately 3.8 mA. After the time expires, the device goes to EM4 and the current drops to around 2 uA. To wake the device up an RF signal > -20 dBm is required. This signal can be provided by placing a mobile phone in active discovery mode and placing it in close proximity to the EFR32. Once the signal is detected, the device wakes up and the device once again begins advertising for the time specified. The length of time the RF signal must be detected for can be adjusted with the symbol RFSENSE_TIME_MIN. In the example it is set to 500 us.

Note: This KBA has been marked as deprecated. A more updated KBA can be found here: Using Bluetooth Security Features in Silicon Labs Bluetooth SDK

Using Bluetooth security features in Silicon Labs Bluetooth SDK

This article introduces the Bluetooth security features and terms then summarizes the practical usage of GATT permissions and pairing processes using the Silicon Labs Bluetooth SDK.

Bluetooth Security Basics

The most common threats in wireless communications are:

• Passive eavesdropping
• Active eavesdropping = Man in the Middle (MITM)
• Privacy (tracking)

Bluetooth defines 5 distinct security features against these threats:

• Pairing — creating trusted relationships between devices (Key Generation, Key Exchange, Identity Information Exchange)
• Bonding — Storing the keys created during pairing for later connections
• Device authentication — verification that devices have the same keys (Protected from MITM)
• Encryption — data confidentiality (FIPS or NIST approved AES128-CCM algorithm used)
• Data signing (Message integrity) — protection against data alteration

These features implemented in different layers of the Bluetooth stack. Let's have a quick look on these.

Pairing

• Is the process of creating trusted relationships between devices
• Used to generate and exchange security keys
• Used to exchange identity information

Bluetooth uses Secure Simple Pairing (SSP) pairing model. The actual pairing process depends on the device I/O capabilities and the security requirements defined by the application.

• Just works — For devices without UI. No user interaction required. No MITM protection. In case of Just works pairing there is no possibility to confirm the identity of the connecting devices. Devices will pair with encryption but without authentication.
• Passkey entry — User needs to enter a passkey the remote party displays. Provides MITM protection
• Numeric comparison — User needs to confirm passkeys both devices display. Provides MITM protection
• Out-of-band — Encryption keys exchanged for example with NFC

More details can be found here in the Pairing Processes KBA.

Bonding

• Storing security keys for future use
• ex. authentication of connections or verifying devices identity

Authentication

• Authentication is defined as a way to prove that the device with which you are connecting is actually the device it claims to be and not a third-party attacker
• Authentication in the GATT Profile is applied to each characteristic independently. The GATT Profile procedures are used to access information that may require the client to be authenticated

A characteristic may be allowed to be read by any device, but only written by an authenticated device. Similarly, if a characteristic can be written, it does not mean the characteristic can also be read. Each individual characteristic could have different security properties.

Encryption

• Encryption protects the data confidentiality and integrity
• Paired or bonded devices can encrypt/decrypt data sent within a connection
• Bluetooth uses AES-128 as the encryption algorithm

Notice: No encryption of broadcast data

Attribute permissions

• Attributes have a set of permissions that controls whether they can be read or written, or whether the attribute value shall be sent over an encrypted link
• Attribute permissions are used by the server to determine whether read or write access is permitted for a given attribute
• Attribute permissions are established by the GATT Profile so different permissions can be granted for the characteristics and descriptors

Security Levels

Security level is a property of a connection. Using different security features can lead to different security levels per connection. The different levels summarized below.

Privacy

• Bluetooth provides privacy protection
• Devices can either use public or private (random) addresses

Public address is fixed and unique to a device Random address can change over time and hides the public address from unwanted devices Bonded devices can resolve the public address

Bluetooth 4.2 Security Features

• New LE Secure connections feature using Elliptic Curve Diffie-Hellman (ECDH) public-private key pairs for numeric comparison paring method

• New numeric comparison paring method. In this pairing method both devices will display a 6-digit passkey. The user must confirm, that the two devices display the same passkey by pressing a button.

• Passkey entry and OOB has updated LE Secure Connection variant. But there is no change from application perspective.

• LE privacy 1.2 — Identity resolving moved from host to controller for faster and lower power operation

Using security features in Silicon Labs Bluetooth SDK

To use the security features you need to do the following steps:

1. Set up attribute permissions in GATT
2. Set up security manager
3. Set up bonding (enabled/disable/delete)
4. Increase security level (optional)
5. Handle security manager stack events by the application

Set up attribute permissions in GATT

The characteristics access and security properties are defined in the gatt.xml file by the XML attribute properties and its parameters, which must be used inside the characteristic XML attribute tags. Alternatively, Visual GATT Editor can be also used for defining the GATT elements and their permissions. The table below describes the parameters that can be used for defining attribute permissions.

GATT Examples

Here we have 3 example for setting up attribute permissions for a characteristic.

Example 1 — No restrictions

In this case properties ensure that reading and writing the characteristic is without any restriction. It does not require authentication or encrypted link. Any GATT client can read or write it.

Example 2 — Encrypted write

Now let's set up the characteristic differently

In this case reading the characteristic is without any restriction. But writing the characteristic requires encrypted link. Characteristics which requires encryption cannot be accessed without pairing. So writing this characteristic in the first time will trigger the pairing process. The pairing can be just works so it is allowed to not have MITM protection.

Example 3 — Authenticated write

Now let's modify the characteristic properties again.

In this case reading the reading the characteristic is without any restriction. But writing requires authentication. It means the remote device must be bonded with man in the middle (MITM) protection enabled. So the characteristic cannot be accessed in case of just works pairing used. Writing this characteristic in the first time will trigger the pairing process.

Setting up the security manager

The application shall use the gecko_cmd_sm_configure(flags, io_capabilities) API to set up the security configuration. The io_capabilities and flagsparameters affect the security level with which the devices will use in connection and leads to different pairing mechanisms.

The io_capabilities parameter informs the stack about the possible user input and output method that is available on the device. See the available options here below:

The flags parameter controls different application specific security requirements. This parameter gives flexibility to the application to decide how strictly use or not use at all the Bluetooth security features. The table below shows the different options:

If the flags parameter is 0, so no application specific requirement set, the pairing method depends only on the IO capabilities of the initiator and the responder device (shown as I and R on the table below).

If a device has application specific security requirements (flags parameter is not 0) then the used pairing method and security level of the connection will be different.

MITM - bit 0

Setting the bit 0 forces the MITM protection. In practice it means that our devices will not bond with devices which don't have the io capabilities at least for legacy pairing.

Encryption - bit 1

Setting the bit 1 forces link encryption. In practice it means that our devices will always use encrypted link with bonded devices. Note if the bonding table is full therefore the device can't save the new bond.

LE Secure connections support - bit 2

If both devices support LE Secure Connections, then the value of then bit 2 doesn’t matter. If either one of the devices doesn’t support secure connections i.e. it supports legacy pairing only, then bit 2 comes into play.

If bit 2 set to 1, secure connection is enforced, and the pairing attempt will fail with error code 0x303 (pairing_fail_authentication_requirements error). This is essentially saying that we don’t want to pair with legacy devices. If bit 2 set to 0, the pairing will fall back to legacy pairing methods.

Application level confirmation of bonding request - bit 3

If bit 3 is set then bonding requests need to be confirmed by the application too. This feature gives additional control over incoming bond requests. So the application can reject devices which otherwise could bond. The application notified about the received bonding request by the sm_confirm_bondingstack event.

The application shall accept or reject the bonding request with the cmd_sm_bonding_confirm command.

Set up bonding (enabled/disable/delete)

To enable secure connection (Security Level 2 and above) the application need to allow bonding. The stack provides the gecko_cmd_sm_set_bondable_mode API function to enable or disable the bonding.

Please note if gecko_cmd_sm_configure(flags, io_capabilities) called with flags parameter where bit 1 is set then the bonding enabled automatically.

During application development sometimes it is useful to delete all the bondings to trigger and test the pairing processes. It can be done by the cmd_sm_delete_bondings API.

There are use cases when the application has to manage the bonding table directly. This is out of scope of this article. You can read more about this in a separate KBA.

Increase security level

If the GATT attribute permissions are set correctly the application don't have to increase the security level manually. The security level of the connection will be increased once there is access demand for GATT elements which requires higher security level. If the 2 devices not bonded yet the pairing process also triggered.

However there can be use cases where the application handles the security level of the connections. In those cases it makes sense to call the cmd_sm_increase_security API function in the evt_le_connection_opened event handler.

Handle security manager stack events by the application

During the pairing process there are few stack events that the application has to handle otherwise the pairing and bonding will fail. These events are the following.

evt_sm_passkey_display
The evt_sm_passkey_display event indicates a request by stack to display the passkey to the user during the pairing process. The application shall write the passkey to a display given by the event as passkey parameter. This event only can happen if the device has a display. It is defined in its io capabilities. See [the Setting up the security manager](### Setting up the security manager) chapter above.

evt_sm_passkey_request
The evt_sm_passkey_request event indicates a request for the user to enter the passkey displayed on the remote device. The application has to read the passkey then push it to stack by the sm_enter_passkey command.

If the passkey was valid and the bonding completed the stack raise a evt_sm_bonded event. If the passkey was invalid or the bonding failed because of any other reason the stack will raise a evt_sm_bonding_failed event.

evt_sm_confirm_passkey
This event can happen when the stack is using numeric comparison pairing method. Its indicates a request to display the passkey to the user then asks to confirm that displayed passkey is the same what is displayed on the remote device. The cmd_sm_passkey_confirm has to be called by the application to accept or reject the displayed passkey depending on the users answer.

evt_sm_bonded
This event is triggered after the pairing or bonding procedure has been successfully completed.

evt_sm_confirm_bonding
This event indicates that new bonding request has been received. The application has to call sm_bonding_confirm to accept or reject the incoming bonding request. This feature can be activated by calling the gecko_cmd_sm_configure(flags, io_capabilities) where the bit 2 of the flag parameter is set to 1.

evt_sm_bonding_failed
This event is triggered when the pairing or bonding procedure failed. The possible reasons and errorcodes are documented here.

References

API Documentation

Bluetooth Core Specification

Pairing Processes

Application Layer Security

Bond Replacing Algorithm

OOB Introduction

Secure Connection Example

Authenticating Devices with No User Interface

Introduction

Bluetooth OTA updates are covered in detail in application note AN1086. https://www.silabs.com/documents/login/application-notes/an1086-gecko-bootloader-bluetooth.pdf

Most of the AN1086 is focusing on the default in-place OTA update process using AppLoader. As Described in Chapter 4, it is also possible to implement OTA updates in the user application. AN1086 also includes a simplified code sample to illustrate the process. This article explains in more detail how OTA can be handled by user application. An example implementation is provided as a code package that can be installed on top of the soc-empty template.

Prerequisites

The reader is expected to be familiar with the content of application note AN1086 (especially Chapter 4).

This example is not applicable in any parts with 256kB flash (BGM111, BGM113, BGM121, BGM11S, BGMEFR32xG1 SoC) (unless external SPI flash is used as download area)

List of parts compatible with this example: BGM13P/S, MGM12P, EFR32xG12, EFR32xG13.

To use this example, your device needs to be programmed with a suitable Gecko bootloader. When creating the bootloader project, select the version named Internal Storage Bootloader (single image on 512kB/1MB device), depending on the size of internal flash in your device.

For more details on Gecko bootloader, see the user guide UG266 - https://www.silabs.com/documents/public/user-guides/ug266-gecko-bootloader-user-guide.pdf .

Difference compared to AppLoader based OTA updates

From external viewpoint, the OTA process is almost the same whether the target application uses AppLoader or handles the update in user application code. The main steps (simplified) are:

1. Connect to the target device

2. Reboot the target device into DFU mode if needed

3. Upload the new firmware, packaged into a GBL file

4. when the upload is finished, Gecko bootloader installs new firmware on top of the old version

The main difference here compared to AppLoader based OTA is that there is no separate DFU mode and step 2 in the above list is not needed at all. The GBL file is uploaded to the target device under the control of the user application. In this example, the file upload is done using the Silicon Labs proprietary OTA service (as specified in AN1086), but it is possible to use also any other customer specific service and protocol to handle the file upload.

Some of the benefits of this approach are:

• the user application remains fully functional while the OTA image is being uploaded

• possibility to implement customer specific OTA service/protocol (with application level security if needed)

• EM2 deep sleep is supported during OTA upload (*

• normal BLE security features (link encryption, bonding...) can be used (*

*) Sleep and BLE encryption/bonding are not supported by AppLoader to reduce the flash footprint.

An obvious disadvantage of this solution is of course the requirement to have dedicated flash space available to be used as the download area.

Interaction between Gecko bootloader and user application

Gecko bootloader has a key part in the OTA update. After GBL file is uploaded, it is Gecko bootloader that takes care of parsing the GBL file and installing the new firmware. The bootloader is also needed during the OTA file upload.

Gecko bootloader has an application interface exposed through a function table in the bootloader. This means that the user application can call functions implemented in the bootloader, even though the application is running in normal mode. In other words, the bootloader API functions are called from the user application context, but the implementation is in the Gecko bootloader project. As a practical example, the user application can call function bootloader_writeStorage to write data into the download area, without even knowing where the download area is physically located.

A list of the key bootloader API calls needed to implement OTA update is found in AN1086, Chapter 4.

Simplified vs full example code

The code sample provided in AN1086 is a simplified version to fit it in one page. The full example provided here includes some additional debug prints and features like printing the estimated data transfer rate.

The main functional difference is related to the erasing of the download area. In the simplified code of AN1086, the download area is erased when the remote OTA client starts the OTA process (writing value 0 to ota_control). In this example, the download area is erased at startup. The code also reads the content of the download area and does an erase only if needed (i.e. if the download area is not already blank). The reason for this change is to avoid dropping connection due to supervision timeout. Erasing the whole download area (256k or more) will take several seconds (it is a blocking function call) and this can lead to supervision timeout unless the connection parameters are specifically adjusted to prevent it.

Testing the example

The attached zip file includes copy of the necessary source codes and also detailed instructions (see readme.txt) on how to install this code on top of the soc-empty template.

Remember that to use this example, you also need to program the target device with suitable Gecko bootloader variant. The application detects the download area information dynamically at runtime. If you have a suitable bootloader installed, you should see something like this printed to the debug output (tested on EFR32BG12)

Gecko bootloader version: 1.0 Slot 0 starts @ 0x00084000, size 499712 bytes

As the OTA update client, you can use the Blue Gecko mobile application. Another possibility is to use the BLED112 dongle and the update client attached to this KB article.

NOTE: you need to use the GBL file named full.gbl to run the update. The files are generated using the same script that is used for normal AppLoader based OTA (create_bl_files.bat/sh)

Related links

If your device has enough flash capacity, then you can use more than one download area. The following KB article demonstrates how to use multiple download areas and select the slot to be used dynamically via the GATT database:

https://www.silabs.com/community/wireless/bluetooth/knowledge-base.entry.html/2017/09/20/uploading_imagesto-DXxD