Note: This KBA has been marked as deprecated. BGScript is no longer supported. Please refer to QSG108 to get started and learn about our tools.

Which Development Tool Should I use?

Introduction

Silicon Labs provides three methods or workflows for developing Bluetooth Applications; BGSCript, IAR Embedded Workbench and Silicon Labs SimplicityStudio. This article will describe these workflows and discuss the advantages of each one.

BGScript

The first so-called workflow is called BGscript. This is our own event based scripting language which is similar in syntax to BASIC. This language allows developers to create Bluetooth applications at a higher level of abstraction, avoiding the need to write drivers for common peripherals such as UARTs. Many features in the Bluetooth stack, such as sleep, wakeup, packet trace and UART behavior, can be controlled from an xml file.

Another advantage of BGScript is that the development tools are provided free of charge. The Bluetooth stack provides information as a series of events. To create an application with BGScript, the developer only needs to write handlers for the events to be processed. As such, BGScript is a great way to get up and running quickly with a simple Bluetooth application. A simple GUI tool for building and downloading BGScript applications called BGtool is provided. 

The limitations of BGScript are mainly the lack of support for debugging and the fact that only integral data types are supported.

Support for BGScript is delivered in the form of an SDK available from www.silabs.com.

C-SDK through IAR Embedded Workbench

Another supported workflow is using the C language through the IAR tools. The C language is possibly the most commonly understood programming language, particularly among embedded developers. Developing in C results in greater runtime efficiency than BGScript but requires a little more effort on the part of the developer. Drivers are usually written by the developer unless they can be obtained from the SimplicityStudio method described below. The C language has more flexibility in data representation and processing than BGScript which can ease the development and debugging process.

Another advantage of developing in C comes in the availability of debugging. The IAR tools include a powerful debugger with all of the features that many developers have come to expect such as breakpoints, register and variable watch, and simulated terminal I/O window. Some examples are available to demonstrate how to get started. Please see the examples folder of your SDK installation. This method gives the developer the most flexibility as there are no constraints as there were would be when using a code generation framework such as the SimplicityStudio AppBuilder or language like BGScript.

C-SDK through SimplicityStudio and Appbuilder

Another possibility for developing Bluetooth applications is SimplicityStudio. This is Silicon Labs’ own integrated development environment and is capable of running the IAR command line compiler, assembler and linker. One of the main advantages of this approach is the appbuilder, a GUI interface for code generation. This tools allows the developer to generate drivers for peripherals and configure Bluetooth features such as advertisement, beaconing and transmit power from a simple graphical interface.

SimplicityStudio also provides several example applications to help you get a running start. Please see QSG120.pdf for a complete guide to getting started with this approach. Note that this method is available when developing for Bluegecko SOCs and BGM1xx modules. SimplicityStudio also offers advanced tools for analyzing the behavior of an application such as the energy profiler and network analyzer. Please note that this method requires a separate SDK installation from the BGscript SDK.

Conclusion

Each of these methods has its own advantage. Developing in C, whether through IAR or SimplicityStudio, generally results in more efficient code but may require more implementation on the part of the developer while BGScript offers a quick way to get up and running on a simple project.

/* Gecko configuration parameters (see gecko_configuration.h) */
static const gecko_configuration_t config = {
  .config_flags = 0,
  .sleep.flags = 0, // <- DISABLE THE SLEEP HERE
..
}

Step 4 – On Silicon Labs kits you can use the UART over the J-Link CDC. For that you need to route the UART signals from the MCU to the board controller of the kit.

This can be done by setting VCOM enable pin high. Most of the kits it can be done by setting a GPIO by software. But on some kits a 0 Ohm resistor must soldered additionally.

Here is how you can enable VCOM by software.

GPIO_PinOutSet(BSP_BCC_ENABLE_PORT, BSP_BCC_ENABLE_PIN);

Example

The attached  uart_echo.c and uart_echo.h implements terminal echo. It can be used in any Bluetooth SDK project once the steps described above are completed.

Calling the UART_EchoInit(uint8_t vcom) sets the VCOM enable pin, configures the uartdrv then start to receive.

Once a byte received the UART_rx_callback called by the uartdrv. The callback immediately transmits the received byte back and start to receive the next byte.

Note: This KBA has been deprecated. Please refer to the following KBA: Using Bluetooth security features in Silicon Labs Bluetooth SDK

Introduction

This article shows how the Bluetooth Smart security features can be used in Simplicity Studio C SDK for Blue Gecko products.

First we give some basic info about Bluetooth Smart security features then we highlight and explain the most important code snippets from the attached sample application. The sample application implements a characteristic which can be read if the connection secured by pairing and bonding.

Bluetooth Smart security features

The most common threats in wireless communications are:

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

Bluetooth Smart 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 the different layers of the Bluetooth Smart stack. The figure below highlights the layers involved.

Pairing & Bonding

Pairing

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

Bluetooth Smart uses Secure Simple Pairing (SSP) pairing model

• Just works - For devices without UI. No user interaction required. No MITM protection.

• 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. Note - Numeric comparison not yet supported in the current Blue Gecko stack.

• Out-of-band  - Encryption keys exchanged f.ex. using NFC

Bonding

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

Privacy

• Bluetooth Smart 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

Note – Random address feature not yet supported in the current Blue Gecko stack.

Encryption

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

Bluetooth 4.2  Security Features

• LE Secure connections – Key exchange mechanism updated to ECDH for more secure pairing
• LE privacy 1.2 – Identity resolving moved from host to controller for faster and lower power operation

Note - Bluetooth 4.2  Security Features not yet supported in the current Blue Gecko stack.

Example code

The application is built with the Simplicity Studio Bluetooth Smart C SDK ver. 1.0.4

The application is built to the Blue Gecko SoC Starter Kit (SLWSTK6020A) but it should work with BGM111 and BGM113 targets with minimal changes.

The sample application implements a characteristic which can be read only if the connection secured by pairing and bonding. To achieve this we need to do following steps:

1. Set up the attribute permissions in GATT

The example has a my_secret characteristic. It can be read only through an encrypted connection because the authenticated_read property set to true.

2. Enable bonding

To enable secure connection first we need to allow bonding. The bonding process stores the keys which are used during secure communication. We can enable the bonding on the GUI.

This setting will call gecko_cmd_sm_set_bondable_mode(1) API function after the boot.

3. Set up the security manager

We have to use the gecko_cmd_sm_configure(flags, io_capabilities) API to set up the security configuration.

The flags parameter bit 0:

• 0: Allow bonding without MITM protection
• 1: Bonding requires MITM protection

The flags parameter bit 1:

• 0: Allow encryption without bonding
• 1: Encryption requires bonding

The flags bit 2 to 7 are reserved and they should be 0

The capabilities parameter tells what kind of user input and output methods are available on our device. The different io capabilities leads to different pairing method.

The gecko_cmd_sm_configure API called after the boot.

When sm_io_capability_displayonly or sm_io_capability_displayyesno io capabilities used, the pin will be printed on the UART console and you have to enter this pin on the phone/tablet.

When sm_io_capability_keyboardonly or sm_io_capability_keyboarddisplay io capabilities used, the pin will be printed on phone/tablet and you have to enter this pin on UART console.

Do not use sm_io_capability_noinputnooutput because MITM can’t work with this setting and the pairing and bonding will fail.

4. Increase the security level when connection opened

In the connection opened event handler we have to call the gecko_cmd_sm_increase_security API function. This will trigger the pairing process. In some iOS version this step should be skipped because the iOS device initiate the pairing.

The gecko_cmd_sm_increase_security API function called automatically if the pairing enabled on the GUI.

5. Implement the callback function for the gecko_evt_sm_passkey_display_id event

The gecko_evt_sm_passkey_display_id event indicates a request to display the passkey to the user. In the example this event triggers the MyService_PasskeyDisplayCbk. This callback prints the passkey to the console with the standard printf.

6. Implement the callback function for the gecko_evt_sm_passkey_request_id event

The gecko_evt_sm_passkey_request_id event indicates a request for the user to enter the passkey displayed on the remote device. In the example this event triggers the MyService_PasskeyDisplayCbk. This callback initiates the passkey reading from the console. The actual passkey reading implemented in the MyService_PasskeyRead function. When the reading done the function calls the sm_enter_passkey API command to push the received passkey to the stack.

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

Testing the example

For testing the project we used the Blue Gecko app which can be downloaded from here:

 Follow this step for testing:

1. Flash the project to the WSTK.
2. Delete the bonding to your kit on tablet/phone
3. Open a terminal and select the J-Link CDC UART port
4. Open the Blue Gecko app and select the BLE&Stack & Profile test
5. Connect to the kit
6. Follow the instruction printed on the terminal and on tablet/phone

 7. If everything went well you should read the GATT with the app and you will get the Bonding completed message on the terminal.